Skip to content

fix: opencode provider 无法识别 #125

Closed

Description

@AllenReder

macos 上 opencode v1.18.31 可识别
windows 上 opencode v2.0.18 无法识别

Image

Activity

  1. self-assigned this
    on Sep 26, 2026
  2. AllenReder commented on Sep 26, 2026

    @AllenReder
    OwnerAuthor

    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 --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

    1. 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.
    2. 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.
    3. 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.
    4. As an Awen user, I want to supply my own server password, so that it overrides any
      generated one.
    5. 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.
    6. 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.
    7. 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.
    8. 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.
    9. 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.
    10. 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.
    11. 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.
    12. 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.
    13. As an Awen user, I want OpenCode skills discovered for my Workspace, so that
      project skills appear in the provider catalog.
    14. 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.
    15. As an Awen user, I want approvals and stops to keep working against v2, so that I
      can intervene during a turn.
    16. 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.
    17. As an Awen user, I want the provider to stop owning the local server when idle, so
      that background processes do not accumulate.
    18. As an Awen user, I want OPENCODE_CONFIG_CONTENT to keep being inherited from my
      environment, so that my OpenCode configuration is not clobbered.
    19. As a maintainer, I want Awen to depend on the official OpenCode v2 client, so that
      protocol changes are absorbed by the vendor package.
    20. 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.
    21. As a maintainer, I want the minimum OpenCode version raised in one place, so that
      the support matrix is easy to audit.
    22. 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.
    23. As a maintainer, I want a real-binary integration test, so that banner, auth, and
      inventory regressions are caught against the actual CLI.
    24. 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.
    25. 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.
  3. AllenReder commented on Sep 26, 2026

    @AllenReder
    OwnerAuthor

    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.

  4. AllenReder commented on Sep 26, 2026

    @AllenReder
    OwnerAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions