dsh-opencode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 askdkc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# dsh-opencode — OpenCode Zen / Go live catalog plugin
+
+An out-of-tree DSH bundle that serves the OpenCode **Zen** and **Go** products as two independent live LLM routes with a **dynamic model catalog**: models the official lists publish become selectable and executable without a plugin update, rebuild, or DSH restart, as long as they use a known wire protocol and publish the metadata the route needs.
+
+- `opencode-zen-live` — **OpenCode Zen (Live)**
+- `opencode-go-live` — **OpenCode Go (Live)**
+
+The plugin reuses DSH's public `PiAiAdapter` and pi-ai's public `createProvider()` for all message conversion, streaming, tool calls, images, replay state, usage, cancellation, and idle-timeout behavior. It does **not** port OAuth, does not modify the existing `llm-pi-ai` configuration, does not fail over between Zen and Go automatically, and never sends an inference request as part of a catalog refresh.
+
+## Compatibility
+
+- DSH packages: `0.1.2-rc.1` (published release; peer range `^0.1.2-rc.1`)
+- pi-ai: pinned to the installed DSH adapter's range (`>=0.84.2 <0.86`, verified on `0.84.2`)
+- Cordis: `4.0.2`
+- Node: `^22.19.0 || >=24.0.0`
+
+## Installation
+
+```sh
+pnpm dsh plugin --profile web add github:askdkc/dsh-opencode
+pnpm dsh --profile web --dump-config
+```
+
+The dump should contain the `opencode-live` row with both provider routes. A restart applies the bundle once; after that, catalog updates need no restart.
+
+To remove it:
+
+```sh
+pnpm dsh plugin --profile web remove dsh-opencode
+```
+
+## API key
+
+Both routes resolve the credential reference `apiKeyEnv` per request through the DSH credentials service (or the launch environment when no credential service is mounted). The default reference is `OPENCODE_API_KEY` for both products; set a different one per route in settings, e.g. `DSH_OPENCODE_ZEN_API_KEY` / `DSH_OPENCODE_GO_API_KEY`, and store the value through the standard credentials UI (the web Models page) or export it in the launch environment.
+
+- A missing or unusable key fails the request with `MISSING_CREDENTIAL`; the plugin never falls back to an unrelated ambient key (`OPENAI_API_KEY`, `GEMINI_API_KEY`, …).
+- Catalog fetches are unauthenticated and share no client with inference; keys never appear in URLs, logs, diagnostics, command output, or the cache.
+- Go requests carry an honest `x-opencode-client: opencode-live/<version>` header and an opaque, stable `x-opencode-session` value per DSH session; the plugin never impersonates OpenCode itself.
+
+## How the catalog works
+
+Three public sources feed the catalog: the official Zen list, the official Go list, and the Models.dev `api.json` metadata for the `opencode` / `opencode-go` providers. The plugin joins them by exact model id and keeps every candidate visible:
+
+| State | Meaning | Selector | Diagnostics |
+|---|---|---|---|
+| `ready` | officially listed with complete metadata and a known wire API | shown | — |
+| `metadata-pending` | officially listed; missing name/context/output/input/api | hidden | shown with the missing fields |
+| `unsupported-protocol` | metadata names an unknown SDK | hidden | shown with the SDK id |
+| `catalog-only` | in Models.dev but absent from the official list | hidden | shown |
+| `removed` | was officially listed before; no longer present | hidden (history keeps the name) | shown |
+
+Wire APIs are chosen from the model-level `provider.npm` (falling back to the provider default) through a fixed allowlist: `@ai-sdk/openai-compatible` → Chat Completions, `@ai-sdk/openai` → Responses, `@ai-sdk/anthropic` → Anthropic Messages, `@ai-sdk/google` → Google Generative AI. Unknown SDK identifiers are never executed and nothing fetched is ever imported or installed. Reasoning-effort controls are offered only where the source publishes a verified effort list; toggle-only models keep the provider's default behavior.
+
+Refreshes run single-flight per source (Models.dev once for both products) with conditional GET/304 handling, timeout and decoded-body caps, empty-list protection, and per-source failure isolation. An executable-set change re-registers the same routes in place, which publishes `llm/adapters-updated` so an open selection UI re-fetches. Snapshots are immutable and generation-bound; a prepared call cannot switch providers mid-request.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/dsh-opencode` | After the key is stored securely, refreshes both catalogs and enables Zen/Go immediately; never accepts key values |
+| `/opencode-refresh [all\|zen\|go]` | Force a catalog refresh (joins in-flight fetches) |
+| `/opencode-status` | Freshness, per-source errors, ready/pending counts, credential presence |
+| `/opencode-models <zen\|go> [--all]` | Ready models, or every candidate with its state and reason |
+
+None of these commands displays key values or fragments, and none registers a model-visible tool.
+
+## Configuration
+
+Namespace `opencode-live` (composition defaults in `cordis.patch.yml`):
+
+```yaml
+providers:
+  opencode-zen-live:
+    product: zen            # must match the route key
+    apiKeyEnv: OPENCODE_API_KEY
+  opencode-go-live:
+    product: go
+    apiKeyEnv: OPENCODE_API_KEY
+catalog:
+  refreshIntervalMs: 900000   # periodic refresh (with jitter)
+  listRevalidateAfterMs: 60000  # re-check TTL on display/selection
+  timeoutMs: 15000            # per-request HTTP timeout
+  maxStaleMs: 604800000       # 7 days; staleness display bound
+  requireFresh: false         # true refuses requests while the official list is stale
+```
+
+`cachePath` (optional) relocates the validated-source cache; it defaults to `cache/opencode-live/catalog.json` under the DSH home. The cache stores source payloads and freshness facts only — never normalized output, never secrets.
+
+`limit.output` sizes the model's capability; it is never materialized as a per-request token default. `configuredMaxTokens` stays empty by design: only explicit per-model configuration belongs there, and this plugin defines none.
+
+## Development
+
+```sh
+pnpm install
+pnpm typecheck        # tsc --noEmit
+pnpm test             # vitest run (offline only; live tests skip)
+pnpm test:live        # opt-in: hits the public GET endpoints, no key, no inference
+pnpm build            # tsdown -> lib/
+pnpm pack:check       # npm pack --dry-run
+```
+
+Tests mount a real Cordis context with the published DSH packages, stub the three catalog URLs, and cover the candidate states, refresh failure classes, wire-API selection, session headers, credential semantics, registry replacement, unload safety, and packaging.
+
+## Scope notes
+
+- Catalog refreshes never generate inference traffic, and a Go auth/limit error never switches the request to Zen.
+- Model `limit.context` / `limit.output` come only from a validated source; unknown capacities never become fabricated numbers. Source pricing maps into pi-ai's descriptor; absent pricing is the absence of a fact, not a $0 claim.
+- The repository commits the built `lib/` so installation needs no runtime TypeScript compilation.

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# Add the two live OpenCode routes and this plugin's composition entry.
+# This patch never touches llm-pi-ai, openai-codex, or any other existing row:
+# unlike a targeted replace, an insert cannot lose another bundle's config.
+- insert:
+    - id: opencode-live
+      name: './lib/index.js'
+      config:
+        providers:
+          opencode-zen-live:
+            product: zen
+            apiKeyEnv: OPENCODE_API_KEY
+          opencode-go-live:
+            product: go
+            apiKeyEnv: OPENCODE_API_KEY
+        catalog:
+          refreshIntervalMs: 900000
+          listRevalidateAfterMs: 60000
+          timeoutMs: 15000
+          maxStaleMs: 604800000
+          requireFresh: false

package/lib/adapter.js

@@ -0,0 +1,109 @@
+import { PRODUCT_BY_ROUTE, describeNonReadyState } from "./normalize.js";
+import { LlmError } from "@deepseek-ai/dsh-llm";
+import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
+//#region src/adapter.ts
+/**
+* The live OpenCode adapter: catalog awareness on top of the public
+* `PiAiAdapter`.
+*
+* Message conversion, streaming, tool calls, images, replay state, usage,
+* cancellation, and idle timeouts stay entirely delegated. This subclass adds
+* only what a dynamic catalog requires: waiting for the first catalog data,
+* revalidating on display, forcing one refresh for an unknown model, refusing
+* non-ready or stale candidates with their reason, and refusing tool-bearing
+* requests on models known not to support tools.
+*
+* Every refusal names the candidate state; nothing is silently dropped and no
+* model is substituted.
+*
+* @module opencode-live/adapter
+*/
+/**
+* pi-ai-backed adapter over the two live OpenCode routes.
+*
+* Each operation reads the current catalog snapshot, so a published catalog
+* change reaches the next request; a prepared call keeps the snapshot its
+* generation captured, because the stream it returns is bound to that
+* generation's provider.
+*/
+var LiveOpenCodeAdapter = class extends PiAiAdapter {
+	catalog;
+	initialWaitMs;
+	requireFresh;
+	constructor(options) {
+		super(options);
+		this.catalog = options.catalog;
+		this.initialWaitMs = options.initialWaitMs;
+		this.requireFresh = options.requireFresh;
+	}
+	/** Apply updated catalog-related settings without re-registering. */
+	updateOptions(options) {
+		this.initialWaitMs = options.initialWaitMs;
+		this.requireFresh = options.requireFresh;
+	}
+	/** The product behind one owned route, or the not-owned failure. */
+	productOf(provider) {
+		const product = PRODUCT_BY_ROUTE[provider];
+		if (product === void 0) throw new LlmError(`opencode-live: adapter does not own provider "${provider}"`, "NO_ADAPTER");
+		return product;
+	}
+	/** The candidate for one route/model pair in the current snapshot. */
+	candidateOf(provider, model) {
+		const snapshot = this.catalog.current;
+		if (snapshot === void 0) return void 0;
+		return snapshot.products[this.productOf(provider)].candidates.get(model);
+	}
+	/**
+	* Make one route/model pair selectable: wait for initial data, revalidate
+	* the list if its TTL expired, and force exactly one refresh for an unknown
+	* id before refusing with the candidate's state.
+	* @param provider - the route the request names.
+	* @param model - the exact model id the request names.
+	*/
+	async ensureSelectable(provider, model) {
+		const product = this.productOf(provider);
+		await this.catalog.ensureInitial(this.initialWaitMs);
+		this.catalog.revalidateIfNeeded(product);
+		let candidate = this.candidateOf(provider, model);
+		if (candidate === void 0) {
+			await this.catalog.forceRefreshOnce(product);
+			candidate = this.candidateOf(provider, model);
+		}
+		if (candidate === void 0) throw new LlmError(`opencode-live: product "${product}" has no model "${model}" in the current catalog`, "UNKNOWN_MODEL");
+		if (candidate.state !== "ready") throw new LlmError(`opencode-live: model "${model}" on "${product}" is not executable: ${describeNonReadyState(candidate)}`, "UNKNOWN_MODEL");
+		const view = this.catalog.current?.products[product];
+		if (this.requireFresh && view?.stale === true) throw new LlmError(`opencode-live: the official "${product}" list is stale and catalog.requireFresh is set; refresh the catalog or relax the setting`, "STALE_CATALOG");
+	}
+	/** Refuse tool-bearing requests on models known not to support tools. */
+	guardTools(options) {
+		if (options.tools === void 0 || options.tools.length === 0) return;
+		if (this.candidateOf(options.provider, options.model)?.tools === false) throw new LlmError(`opencode-live: model "${options.model}" on "${options.provider}" does not support tool calls; send this request without tools or select a tool-capable model`, "UNSUPPORTED_CAPABILITY");
+	}
+	async listModels(provider) {
+		const product = this.productOf(provider);
+		await this.catalog.ensureInitial(this.initialWaitMs);
+		this.catalog.revalidateIfNeeded(product);
+		return super.listModels(provider);
+	}
+	async resolveModel(provider, model, signal) {
+		await this.ensureSelectable(provider, model);
+		return super.resolveModel(provider, model, signal);
+	}
+	async prepareCall(provider, model, signal) {
+		await this.ensureSelectable(provider, model);
+		const prepared = await super.prepareCall(provider, model, signal);
+		return {
+			model: prepared.model,
+			stream: (options) => {
+				this.guardTools(options);
+				return prepared.stream(options);
+			}
+		};
+	}
+	stream(options) {
+		this.guardTools(options);
+		return super.stream(options);
+	}
+};
+//#endregion
+export { LiveOpenCodeAdapter };

package/lib/cache.js

@@ -0,0 +1,171 @@
+import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
+/** Whether one stored source state carries only the bounded display facts. */
+function isSourceState(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	return [...Object.values(record)].every((member) => typeof member === "string" || typeof member === "number") && Object.keys(record).every((key) => [
+		"lastCheckedAt",
+		"lastSuccessfulAt",
+		"etag",
+		"lastErrorCode",
+		"lastErrorMessage"
+	].includes(key));
+}
+/** Whether one stored official list is structurally valid. */
+function isCachedOfficialList(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	return isSourceState(record.state) && typeof record.fetchedAt === "number" && Number.isFinite(record.fetchedAt) && Array.isArray(record.ids) && record.ids.every((id) => typeof id === "string" && id.length > 0);
+}
+/** Whether one stored Models.dev slice is structurally valid. */
+function isCachedModelsDev(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value;
+	if (!isSourceState(record.state) || typeof record.fetchedAt !== "number" || !Number.isFinite(record.fetchedAt) || typeof record.providers !== "object" || record.providers === null) return false;
+	return Object.values(record.providers).every((provider) => typeof provider === "object" && provider !== null && typeof provider.models === "object");
+}
+/**
+* Load and validate the cache file. Any structural defect — wrong version,
+* wrong normalizer, malformed source entry — refuses the whole file rather
+* than trusting a partial restore.
+* @param path - the cache file path.
+* @returns the cached sources, or `undefined` when absent or invalid.
+*/
+async function loadCache(path) {
+	let raw;
+	try {
+		const { readFile } = await import("node:fs/promises");
+		raw = JSON.parse(await readFile(path, "utf8"));
+	} catch {
+		return;
+	}
+	if (typeof raw !== "object" || raw === null) return void 0;
+	const file = raw;
+	if (file.version !== 1 || file.normalizer !== 1) return void 0;
+	if (typeof file.savedAt !== "number" || !Number.isFinite(file.savedAt)) return void 0;
+	if (typeof file.sources !== "object" || file.sources === null) return void 0;
+	const sources = file.sources;
+	const cached = {};
+	if (isCachedOfficialList(sources["zen-list"])) cached.zenList = sources["zen-list"];
+	if (isCachedOfficialList(sources["go-list"])) cached.goList = sources["go-list"];
+	if (isCachedModelsDev(sources["models-dev"])) cached.modelsDev = sources["models-dev"];
+	if (cached.zenList === void 0 && cached.goList === void 0 && cached.modelsDev === void 0) return;
+	return cached;
+}
+/**
+* Persist the payload under a file lock and an atomic replacement, merging
+* per source so a slower writer can never erase a fresher entry another
+* completion already stored: each source keeps whichever entry — the stored
+* one or the incoming one — validated more recently, and a source the caller
+* does not name leaves the stored entry untouched.
+*
+* A write failure is reported to the caller — the in-memory catalog stays
+* usable — and the caller decides what the loss means for later restarts.
+* @param path - the cache file path.
+* @param payload - the validated source payloads to store.
+* @param savedAt - the wall-clock stamp for the entry.
+*/
+async function saveCache(path, payload, savedAt) {
+	const incoming = buildFile(payload, savedAt);
+	await withFileLock(path, async () => {
+		const existing = await readCacheFile(path);
+		const merged = existing === void 0 ? incoming : mergeFiles(existing, incoming);
+		await writeFileAtomic(path, JSON.stringify(merged), {
+			mode: 384,
+			dirMode: 448
+		});
+	});
+}
+/** Assemble one cache file image from a payload. */
+function buildFile(payload, savedAt) {
+	return {
+		version: 1,
+		normalizer: 1,
+		savedAt,
+		sources: {
+			...payload.zenList === void 0 ? {} : { "zen-list": {
+				state: payload.zenList.state,
+				fetchedAt: savedAt,
+				ids: payload.zenList.ids
+			} },
+			...payload.goList === void 0 ? {} : { "go-list": {
+				state: payload.goList.state,
+				fetchedAt: savedAt,
+				ids: payload.goList.ids
+			} },
+			...payload.modelsDev === void 0 ? {} : { "models-dev": {
+				state: payload.modelsDev.state,
+				fetchedAt: savedAt,
+				providers: payload.modelsDev.providers
+			} }
+		}
+	};
+}
+/** The success stamp ordering one merge decision. */
+function successAt(entry) {
+	return entry.state.lastSuccessfulAt ?? -1;
+}
+/**
+* Merge two cache file images per source: the entry whose source confirmed
+* more recently wins; an equally fresh entry is taken from the incoming file
+* because its state carries the most recent check outcome. Sources absent
+* from the incoming image keep the stored entry, which is what stops a
+* partial or failed refresh from erasing another source's data.
+*/
+function mergeFiles(existing, incoming) {
+	const sources = {};
+	const target = sources;
+	for (const key of [
+		"zen-list",
+		"go-list",
+		"models-dev"
+	]) {
+		const prior = existing.sources[key];
+		const next = incoming.sources[key];
+		if (next === void 0 && prior === void 0) continue;
+		if (next === void 0) {
+			target[key] = prior;
+			continue;
+		}
+		if (prior === void 0 || successAt(next) >= successAt(prior)) {
+			target[key] = next;
+			continue;
+		}
+		target[key] = prior;
+	}
+	return {
+		version: incoming.version,
+		normalizer: incoming.normalizer,
+		savedAt: Math.max(incoming.savedAt, existing.savedAt),
+		sources
+	};
+}
+/** Read and parse the cache file without validation judgment. */
+async function readCacheFile(path) {
+	try {
+		const { readFile } = await import("node:fs/promises");
+		const raw = JSON.parse(await readFile(path, "utf8"));
+		if (typeof raw !== "object" || raw === null) return void 0;
+		const file = raw;
+		if (file.version !== 1 || file.normalizer !== 1) return void 0;
+		if (typeof file.savedAt !== "number" || !Number.isFinite(file.savedAt)) return void 0;
+		if (typeof file.sources !== "object" || file.sources === null) return void 0;
+		return file;
+	} catch {
+		return;
+	}
+}
+/**
+* Rebuild a validated official list from stored ids. The ids were validated
+* when fetched; restoring keeps them exact.
+* @param product - which product's list this is (used only by the caller).
+* @param cached - the stored entry.
+* @returns the official list shape the normalizer consumes.
+*/
+function restoreOfficialList(_product, cached) {
+	const models = /* @__PURE__ */ new Map();
+	for (const id of cached.ids) models.set(id, { id });
+	return { models };
+}
+//#endregion
+export { loadCache, restoreOfficialList, saveCache };