dsh-opencode-go-provider

OpenCode Go LLM provider bundle for DeepSeek Harness (DSH rc.6): a single opencode-go model route over the OpenCode Go gateway, with a Web Connect settings card, a stale-while-revalidate model catalog and safe diagnostic commands.

Status: community software, not published to npm. This package is installed as a commit-pinned Git dependency into a DSH profile; the npm registry is not an installation path. It is not affiliated with, endorsed by, or sponsored by DeepSeek, OpenCode, or any model provider vendor. See LICENSE and THIRD_PARTY_NOTICES.md.

Requirements

• DeepSeek Harness DSH rc.6 (the bundle targets the 0.1.0-rc.6 peer graph).
• Node.js ^22.19.0 || >=24.0.0.
• corepack-managed pnpm 11.7.0 (corepack enable first if pnpm --version does not resolve through Corepack).
• An OpenCode Go API key. The key is stored and resolved only through the DSH credentials service at operation time under the ref OPENCODE_GO_API_KEY; it is never written into settings, the catalog, logs, errors or the package.

Installation (Git, commit-pinned)

The package is not published to npm; the supported installation is a commit-pinned Git dependency for the DSH web profile:

dsh plugin --profile web add github:edynasty/dsh-opencode-go-provider#d2a447610a5dff4006ac966525effd9669342a78

lib/ is committed to the repository, so the Git install loads the bundle without a build step. Uninstall removes the package and its bundle row:

dsh plugin --profile web remove dsh-opencode-go-provider

Coexistence with the web base bundle

The web profile's base bundle (@deepseek-ai/dsh-llm-pi-ai) already declares opencode-go in the provider directory (its catalog ships the route). This bundle adopts that entry instead of re-registering it, and takes over the route with its own adapter (richer SWR catalog), Connect card and doctor routes. No profile changes — and in particular no need to disable llm-pi-ai — are required to install alongside the base bundle.

What the bundle registers

• One provider route: opencode-go, mounted by the llm-opencode-go bundle row (cordis.patch.yml).
• One settings namespace: llm-opencode-go (refresh interval, freshness window, network timeout, deprecated grace, credential ref).
• A Web Connect settings card (injected through dsh.client.inject) that can connect, test the connection, run diagnostics and disconnect.
• A standalone bin (dsh plugin --profile web exec dsh-opencode-go-provider) for status, doctor, migration-dry-run and migration-apply.

Model catalog and protocols

The embedded catalog (catalog/models.json) is derived from OpenCode's models.dev metadata (https://models.opencode.ai/api.json); only the opencode-go provider record is retained. Each model carries its own protocol from that metadata, and the adapter dispatches per model with no model-name-prefix guessing:

Model availability is checked against the live endpoint https://opencode.ai/zen/go/v1/models, which contributes only available ids; models.dev remains the sole authority for protocol, context, modalities, cost and reasoning metadata.

Catalog lifecycle (stale-while-revalidate)

• Embedded catalog is available immediately at boot — offline and without a credential.
• Background refresh keeps a 5-minute freshness window; within it reads never touch the network.
• A 60-minute periodic refresh revalidates; a stale read schedules one single-flight background refresh.
• Every network attempt is bounded by a 10-second timeout.
• Successful refresh writes the cache atomically (same-directory temp, 0600, fsync, rename) at $DSH_HOME/cache/dsh-opencode-go-provider/catalog.json and only then swaps the in-memory snapshot; in-flight requests keep the snapshot they started with.
• Offline fallback: a missing or corrupt cache serves the embedded catalog (origin: embedded/corrupt); the corrupt file is never deleted, and failures never overwrite the last good state.
• Quarantine: a live id with no models.dev metadata is recorded with a sanitized machine-readable reason and is never exposed as a callable model.
• 14-day deprecated grace: a models.dev-known model missing from live availability stays selectable with a deprecatedAt timestamp; after 14 days it is evicted (and resurrects if it returns to live).

Connect / status / doctor / disconnect

• Connect (Web card or Host route) stores the key only in the DSH credentials service under OPENCODE_GO_API_KEY; keys are never rendered back, echoed or written anywhere else.
• Status reports sanitized facts only: configured yes/no, source (embedded/cache/refreshed), model count, last refresh, last attempt, refresh ok/failed counts.
• Test connection / doctor performs exactly one authenticated GET https://opencode.ai/zen/go/v1/models and reports sanitized counts and fixed error codes; it never calls generation endpoints.
• Disconnect removes only the OPENCODE_GO_API_KEY credential. The opencode-go route and Connect card remain registered and selectable — disconnect never removes the provider, writes it to a disabled list, or touches other providers.

connect/disconnect are Host-only: the standalone bin refuses them with a fixed message because the DSH credential store is owned by the running Host.

Migrating the manual route

If an older setup configured llm-pi-ai.providers.opencode-go by hand, the bundle can migrate it away:

dsh plugin --profile web exec dsh-opencode-go-provider migration-dry-run <settings.yaml>
dsh plugin --profile web exec dsh-opencode-go-provider migration-apply --revision <64-hex> <settings.yaml>

• migration-dry-run is read-only and prints the target, the SHA-256 revision and removed key/line counts (never the key names or values).
• migration-apply verifies the expected revision, acquires a same-directory lock, re-reads and re-hashes immediately before writing, creates a timestamped recoverable backup (never touching credentials files), and publishes atomically. A concurrent edit yields conflict with zero residue; a second apply is an idempotent no-change.
• Only conservative YAML shapes are supported: block mappings without flow maps, anchors or aliases are migrated; unsupported shapes abort (unsupported-shape) before any lock, backup or write.
• The migration preserves the default model, all other providers, comments, quoting and key order — only the llm-pi-ai.providers.opencode-go block is removed, and the credential ref is left untouched.

Security

See SECURITY.md for the supported scope, the private reporting route, credential handling and the safe-diagnostics contract.

Development

See CONTRIBUTING.md for setup, the TDD workflow, the strict-type/no-private-import rules, the 250-LOC production ceiling and the full local gate:

corepack enable
pnpm install --frozen-lockfile
pnpm run check

CI (.github/workflows/ci.yml) runs the same gates on Node 22.19.0, 24 and 26 with pnpm 11.7.0 and a frozen lockfile. Live smoke requires both a local RUN_OPENCODE_GO_LIVE=1 opt-in and a local OPENCODE_GO_API_KEY; CI injects neither, so the step always skips.

License

MIT — see LICENSE. Upstream notices and attribution are retained in THIRD_PARTY_NOTICES.md.