You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
On Windows, the OpenCode Provider is reported as Unavailable even though the
OpenCode CLI is installed and opencode --version prints v2.0.18. Spawning an
OpenCode session fails, and the provider never contributes models to the Provider
capability catalog. The same account on macOS (OpenCode 1.18.31) sees the provider
working, so the provider appears on one machine and not another.
The integration still assumes the OpenCode v1 server contract: it waits for the
v1 startup banner, calls v1 HTTP routes, and assumes no server authentication.
OpenCode 2 changed the banner, enabled authentication by default, and moved the HTTP
and event API. Awen therefore times out waiting for a server that is already running
and, even past that, would fail its version probe and inventory load.
Solution
The OpenCode Provider speaks the native OpenCode v2 server contract, for both
daemon-managed local servers and configured external server URLs. When no server URL
is configured, the daemon still starts and owns a local OpenCode server, now
supplying a generated password so it can authenticate. Inventory (upstream
providers, models, agents, skills) loads through the v2 client with the selected
Workspace directory. The minimum supported OpenCode version becomes 2.0.12.
OpenCode v1 is no longer supported and is reported as requiring an upgrade.
User Stories
As an Awen user on Windows with OpenCode 2.x installed, I want the OpenCode
provider to be recognized and healthy, so that I can start an agent session
without switching machines.
As an Awen user, I want the provider to start a daemon-managed OpenCode server on
demand, so that I do not have to run opencode serve myself.
As an Awen user, I want a generated server password for the managed server, so
that v2 authentication is satisfied without me configuring a secret.
As an Awen user, I want to supply my own server password, so that it overrides any
generated one.
As an Awen user pointing at an external OpenCode server URL, I want Awen to use it
with my configured password, so that I can target a remote or shared server.
As an Awen user pointing at an external OpenCode server URL, I want Awen to
validate the server version, so that an incompatible server is rejected clearly.
As an Awen user, I want the provider status to say the server is unreachable when
it is, so that I can fix the URL or start the server.
As an Awen user, I want the provider status to say the server rejected
authentication when it does, so that I can correct the password.
As an Awen user running OpenCode 1.x, I want a clear "upgrade to 2.0.12 or newer"
message, so that I understand why the provider is unavailable.
As an Awen user, I want the connected upstream providers reported in the
provider status, so that I can tell whether my OpenCode credentials are active.
As an Awen user, I want OpenCode's models listed in the model picker for the
selected Workspace directory, so that project-scoped models are available.
As an Awen user, I want OpenCode's primary agents and reasoning variants available
in the composer, so that I can choose how a turn runs.
As an Awen user, I want OpenCode skills discovered for my Workspace, so that
project skills appear in the provider catalog.
As an Awen user, I want a session's turns to stream, complete, and recover through
the v2 event API, so that conversations behave as before.
As an Awen user, I want approvals and stops to keep working against v2, so that I
can intervene during a turn.
As an Awen user, I want text generation (commit message, branch name, PR content,
thread title) to work against the v2 server, so that the composer conveniences
keep working.
As an Awen user, I want the provider to stop owning the local server when idle, so
that background processes do not accumulate.
As an Awen user, I want OPENCODE_CONFIG_CONTENT to keep being inherited from my
environment, so that my OpenCode configuration is not clobbered.
As a maintainer, I want Awen to depend on the official OpenCode v2 client, so that
protocol changes are absorbed by the vendor package.
As a maintainer, I want the v1 JavaScript SDK and CLI-parser inventory paths
removed, so that there is only one protocol surface to maintain.
As a maintainer, I want the minimum OpenCode version raised in one place, so that
the support matrix is easy to audit.
As a maintainer, I want the v1 adapter tests replaced with native v2 execution and
inbox-event fixtures, so that tests describe real behavior rather than a
reconstruction of v1 message parts.
As a maintainer, I want a real-binary integration test, so that banner, auth, and
inventory regressions are caught against the actual CLI.
As a maintainer, I want the provider to still work through the Windows .cmd
shim path, so that the fix does not regress on the reported platform.
As a maintainer, I want third-party license metadata updated for the new client
dependency, so that notices stay accurate.
Implementation Decisions
Protocol target. The OpenCode Provider targets the native OpenCode v2 server
contract only. There is no v1/v2 compatibility boundary; OpenCode v1 is removed.
Dependency. Replace the OpenCode v1 JavaScript SDK dependency with the official
OpenCode v2 client package, pinned to the supported floor (2.0.12), consistent
with the upstream implementation this adapts.
Minimum version. The minimum supported OpenCode version rises from 1.14.19 to 2.0.12 in the runtime module, and the provider/driver messages name that version.
Managed server startup. The runtime accepts the v2 ready line
(server listening on <url>, case-insensitive, matched anywhere on the line) while
retaining the existing URL extraction. It generates a per-server password when
neither settings nor environment provide one, injects it into the child environment
under the v2 password variable, and uses it for client authentication. Diagnostics
redact the password.
Authentication. Client requests to a v2 server use HTTP Basic authentication
with the reserved opencode user and the resolved password. Settings-provided
passwords take precedence over generated ones.
Health and version. The version probe uses the v2 client's server-info call
instead of the v1 global health route. A missing or malformed response maps to an
explicit "invalid health response / upgrade" provider status; a version below the
floor maps to a "too old / upgrade" status.
Inventory. Providers, models, agents, and skills load through the v2 client for
the selected Workspace directory. The v1 CLI-parser inventory fallback and its
parser tests are deleted.
Provider identity and presentation. Awen-specific provider presentation is
preserved: approval request kinds and the hidden interaction-mode toggle are
unchanged. Provider identity, instance configuration, and the settings schema
(binaryPath, serverUrl, serverPassword, customModels) are unchanged; serverPassword becomes optional for local servers because Awen generates one.
Configuration inheritance. The OPENCODE_CONFIG_CONTENT resolution behavior
(caller environment, then inherited environment, then empty config) is preserved.
Text generation and sessions. The adapter, driver, and text generation modules
move to the v2 client and v2 event/inbox model.
Licensing. Third-party license configuration and notices are updated for the
new client package and no longer reference the v1 SDK.
Adaptation, not cherry-pick. The upstream changes do not apply cleanly to this
fork (package scope names and Awen-specific provider presentation differ), so the
change is a manual adaptation guided by the upstream implementation.
Relationship to upstream
Reference implementation: pingdotgg/t3code#13008 (canonical migration) as merged
and integration-tested in gidorah/t3code#3.
The only upstream merged change for this defect (pingdotgg/t3code#13651,
a ready-line regex) is insufficient on its own; this spec supersedes it.
Deferred: the data-driven provider compatibility advisory and the subagent/lifecycle
hardening tracked separately (Step 2).
Testing Decisions
What makes a good test. Tests assert externally observable behavior at a service
seam: what a real OpenCode server (or a faithful local stand-in) receives and
returns, and what the provider reports. Avoid asserting on internal parsing helpers
and private functions.
Seam 1 — runtime against a local HTTP server. The existing pattern of running
the OpenCode runtime against a loopback HTTP server is extended to cover the v2
ready line, authenticated requests, the version gate, and inventory loading. This is
the highest existing seam and the primary regression net.
Seam 2 — provider layer and adapter against the runtime test double. Provider
status construction and adapter turn lifecycle (streaming, completion, approvals,
stop, recovery) are exercised with a runtime test double, mirroring the existing
provider/adapter tests. v1 fixtures are replaced with native v2 execution and inbox
events.
Seam 3 — real-binary integration (new). An isolated test runs a real opencode
binary over loopback with a fake model fixture and covers authenticated managed
startup, one adapter turn, and an external server URL. This is the only seam that
can catch banner/auth drift in the CLI itself, and it is marked/isolated so it does
not require the CLI elsewhere.
Windows. The managed spawn path is exercised through the shared shell command
resolution so the .cmd shim case stays covered.
Removed tests. v1 CLI-parser tests are deleted with the parser.
Out of Scope
OpenCode v1 support and any v1/v2 compatibility layer.
The data-driven provider compatibility advisory mechanism.
OpenCode subagent display and task-lifecycle hardening (Step 2).
OpenCode usage/quota reporting.
Other providers (Codex, Claude Agent, Cursor, Grok, Antigravity).
The unrelated Windows shell: true.cmd spawn warning tracking.
Further Notes
Upstream issue pingdotgg/t3code#11790 describes the same v2 symptom; it is not a
source of a fix.
Because OpenCode v1 support is dropped, the macOS machine in the report
(OpenCode 1.18.31) must upgrade to 2.0.12 or newer after this lands. This is
recorded in ADR-0021.
CONTEXT.md needs no glossary change: Provider and Provider capability catalog
already describe the affected domain. The support-matrix reversal is recorded in
ADR-0021.
Step 1 implemented on branch fix/issue-125 (commit 9db5bf5c).
What landed
Switched to the official @opencode/client v2 client (pinned 2.0.12); v1 SDK and the CLI-parser inventory fallback removed.
MINIMUM_OPENCODE_VERSION is now 2.0.12; v1 servers are rejected with an upgrade message.
Managed servers get a generated password injected as OPENCODE_PASSWORD, requests authenticate with Basic auth, and the password is redacted from startup diagnostics.
Ready-line parsing accepts server listening on <url> case-insensitively anywhere on the line, and no longer assumes a terminating newline.
Inventory (providers, models, agents, skills) loads per Workspace directory; external serverUrl still supported.
Added docs/adr/0021-opencode-v2-only-support.md and an opt-in real-binary integration test.
Verification
pnpm typecheck green (all workspaces); lint and fmt:check clean.
159 OpenCode tests pass, including the real-binary integration test against the installed opencode 2.0.18 on Windows (managed startup, auth rejection without a password, chat/approval/fork/compaction, and a real adapter turn via external serverUrl).
16 third-party-license tests pass.
The full server suite has 24 failures in 11 files that are pre-existing Windows-environment issues (service install, npm/pnpm global prefix detection, git pathspec, Android tool PATH, Codex collab integration); none touch OpenCode and they fail without this change.
One deviation from the spec to flag: the port keeps the upstream migration's OpenCode native command discovery (/command), which adds a fifth inventory beyond the providers/models/agents/skills list in the spec. Awen's client only reads compact from slashCommands, so it is inert UI-wise. Say the word if you want it stripped in a follow-up instead of carried.
Step 2 (#126) stays blocked on this until it merges.
Decision on the one spec deviation: keep OpenCode native command discovery.
loadOpenCodeCommands / the commands inventory / openCodeCommandsToServerProviderSlashCommands stay. Rationale: it is native OpenCode v2 capability, matches the upstream migration (less drift on future syncs), and adds a capability rather than changing existing behavior. The Step 1 inventory is therefore providers, models, agents, skills, and commands.
Activity
AllenReder commentedon Sep 26, 2026
Spec: OpenCode v2 provider support (Step 1)
Problem Statement
On Windows, the OpenCode Provider is reported as Unavailable even though the
OpenCode CLI is installed and
opencode --versionprintsv2.0.18. Spawning anOpenCode session fails, and the provider never contributes models to the Provider
capability catalog. The same account on macOS (OpenCode
1.18.31) sees the providerworking, so the provider appears on one machine and not another.
The integration still assumes the OpenCode v1 server contract: it waits for the
v1 startup banner, calls v1 HTTP routes, and assumes no server authentication.
OpenCode 2 changed the banner, enabled authentication by default, and moved the HTTP
and event API. Awen therefore times out waiting for a server that is already running
and, even past that, would fail its version probe and inventory load.
Solution
The OpenCode Provider speaks the native OpenCode v2 server contract, for both
daemon-managed local servers and configured external server URLs. When no server URL
is configured, the daemon still starts and owns a local OpenCode server, now
supplying a generated password so it can authenticate. Inventory (upstream
providers, models, agents, skills) loads through the v2 client with the selected
Workspace directory. The minimum supported OpenCode version becomes
2.0.12.OpenCode v1 is no longer supported and is reported as requiring an upgrade.
User Stories
provider to be recognized and healthy, so that I can start an agent session
without switching machines.
demand, so that I do not have to run
opencode servemyself.that v2 authentication is satisfied without me configuring a secret.
generated one.
with my configured password, so that I can target a remote or shared server.
validate the server version, so that an incompatible server is rejected clearly.
it is, so that I can fix the URL or start the server.
authentication when it does, so that I can correct the password.
message, so that I understand why the provider is unavailable.
provider status, so that I can tell whether my OpenCode credentials are active.
selected Workspace directory, so that project-scoped models are available.
in the composer, so that I can choose how a turn runs.
project skills appear in the provider catalog.
the v2 event API, so that conversations behave as before.
can intervene during a turn.
thread title) to work against the v2 server, so that the composer conveniences
keep working.
that background processes do not accumulate.
OPENCODE_CONFIG_CONTENTto keep being inherited from myenvironment, so that my OpenCode configuration is not clobbered.
protocol changes are absorbed by the vendor package.
removed, so that there is only one protocol surface to maintain.
the support matrix is easy to audit.
inbox-event fixtures, so that tests describe real behavior rather than a
reconstruction of v1 message parts.
inventory regressions are caught against the actual CLI.
.cmdshim path, so that the fix does not regress on the reported platform.
dependency, so that notices stay accurate.
Implementation Decisions
contract only. There is no v1/v2 compatibility boundary; OpenCode v1 is removed.
OpenCode v2 client package, pinned to the supported floor (
2.0.12), consistentwith the upstream implementation this adapts.
1.14.19to2.0.12in the runtime module, and the provider/driver messages name that version.(
server listening on <url>, case-insensitive, matched anywhere on the line) whileretaining the existing URL extraction. It generates a per-server password when
neither settings nor environment provide one, injects it into the child environment
under the v2 password variable, and uses it for client authentication. Diagnostics
redact the password.
with the reserved
opencodeuser and the resolved password. Settings-providedpasswords take precedence over generated ones.
instead of the v1 global health route. A missing or malformed response maps to an
explicit "invalid health response / upgrade" provider status; a version below the
floor maps to a "too old / upgrade" status.
the selected Workspace directory. The v1 CLI-parser inventory fallback and its
parser tests are deleted.
preserved: approval request kinds and the hidden interaction-mode toggle are
unchanged. Provider identity, instance configuration, and the settings schema
(
binaryPath,serverUrl,serverPassword,customModels) are unchanged;serverPasswordbecomes optional for local servers because Awen generates one.OPENCODE_CONFIG_CONTENTresolution behavior(caller environment, then inherited environment, then empty config) is preserved.
move to the v2 client and v2 event/inbox model.
new client package and no longer reference the v1 SDK.
fork (package scope names and Awen-specific provider presentation differ), so the
change is a manual adaptation guided by the upstream implementation.
Relationship to upstream
pingdotgg/t3code#13008(canonical migration) as mergedand integration-tested in
gidorah/t3code#3.pingdotgg/t3code#13651,a ready-line regex) is insufficient on its own; this spec supersedes it.
hardening tracked separately (Step 2).
Testing Decisions
seam: what a real OpenCode server (or a faithful local stand-in) receives and
returns, and what the provider reports. Avoid asserting on internal parsing helpers
and private functions.
the OpenCode runtime against a loopback HTTP server is extended to cover the v2
ready line, authenticated requests, the version gate, and inventory loading. This is
the highest existing seam and the primary regression net.
status construction and adapter turn lifecycle (streaming, completion, approvals,
stop, recovery) are exercised with a runtime test double, mirroring the existing
provider/adapter tests. v1 fixtures are replaced with native v2 execution and inbox
events.
opencodebinary over loopback with a fake model fixture and covers authenticated managed
startup, one adapter turn, and an external server URL. This is the only seam that
can catch banner/auth drift in the CLI itself, and it is marked/isolated so it does
not require the CLI elsewhere.
resolution so the
.cmdshim case stays covered.Out of Scope
shell: true.cmdspawn warning tracking.Further Notes
pingdotgg/t3code#11790describes the same v2 symptom; it is not asource of a fix.
(OpenCode
1.18.31) must upgrade to2.0.12or newer after this lands. This isrecorded in ADR-0021.
CONTEXT.mdneeds no glossary change:ProviderandProvider capability catalogalready describe the affected domain. The support-matrix reversal is recorded in
ADR-0021.
AllenReder commentedon Sep 26, 2026
Step 1 implemented on branch
fix/issue-125(commit9db5bf5c).What landed
@opencode/clientv2 client (pinned2.0.12); v1 SDK and the CLI-parser inventory fallback removed.MINIMUM_OPENCODE_VERSIONis now2.0.12; v1 servers are rejected with an upgrade message.OPENCODE_PASSWORD, requests authenticate with Basic auth, and the password is redacted from startup diagnostics.server listening on <url>case-insensitively anywhere on the line, and no longer assumes a terminating newline.serverUrlstill supported.docs/adr/0021-opencode-v2-only-support.mdand an opt-in real-binary integration test.Verification
pnpm typecheckgreen (all workspaces); lint andfmt:checkclean.opencode 2.0.18on Windows (managed startup, auth rejection without a password, chat/approval/fork/compaction, and a real adapter turn via externalserverUrl).One deviation from the spec to flag: the port keeps the upstream migration's OpenCode native command discovery (
/command), which adds a fifth inventory beyond the providers/models/agents/skills list in the spec. Awen's client only readscompactfromslashCommands, so it is inert UI-wise. Say the word if you want it stripped in a follow-up instead of carried.Step 2 (#126) stays blocked on this until it merges.
AllenReder commentedon Sep 26, 2026
Decision on the one spec deviation: keep OpenCode native command discovery.
loadOpenCodeCommands/ thecommandsinventory /openCodeCommandsToServerProviderSlashCommandsstay. Rationale: it is native OpenCode v2 capability, matches the upstream migration (less drift on future syncs), and adds a capability rather than changing existing behavior. The Step 1 inventory is therefore providers, models, agents, skills, and commands.feat(opencode): support native OpenCode v2 provider (#131)