dsh-opencode-go 0.1.0

package/lib/types/config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration schema for the OpenCode Go adapter plugin. The section is
+ * installed under the `llm-opencode-go` settings namespace: a cordis.yml
+ * entry supplies the composition base and the settings document overrides it
+ * field by field, hot-reloaded without a restart. Self-contained constraints
+ * (URL shape, numeric bounds) fail at load for the composition layer and
+ * refuse the write for the settings layer.
+ *
+ * @module dsh-llm-opencode-go/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Environment variable resolving the OpenCode API key. */
+export declare const DEFAULT_API_KEY_ENV = "OPENCODE_API_KEY";
+/** Default interval between live catalog re-resolutions. */
+export declare const DEFAULT_REFRESH_MINUTES = 60;
+/** Default maximum idle interval while a stream read is outstanding. */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Runtime configuration for one plugin mount. */
+export interface OpencodeGoConfig {
+    /**
+     * Whether this adapter serves its route at all. False withdraws the
+     * `opencode-go` route and its models from every picker without unloading the
+     * plugin, so the settings page that owns this switch stays reachable to turn
+     * it back on. Independent of the credential: a key present while this is
+     * false registers nothing.
+     */
+    enabled: boolean;
+    /** Credential reference: the environment variable the key resolves from. */
+    apiKeyEnv: string;
+    /** The gateway endpoint; also the base of the live model listing. */
+    baseURL: string;
+    /** How long one live catalog resolution stays authoritative, in minutes. */
+    refreshMinutes: number;
+    /** Largest idle gap between stream events before the request fails. */
+    streamIdleTimeoutMs: number;
+    /** Request-level bound on base64-encoded image payload, in bytes. */
+    maxRequestImageBytes: number;
+    /** Total-pixel budget for one request image. */
+    requestImagePixelBudget: number;
+    /** Raw encoded-byte target for one request image before base64 expansion. */
+    requestImageMaxBytes: number;
+}
+/** Runtime schema for {@link OpencodeGoConfig}. */
+export declare const Config: z<OpencodeGoConfig>;
+/**
+ * Accept only an http(s) base without a query or fragment. Runs at load for
+ * the composition layer and as the settings section's write validator, so a
+ * bad URL fails where it is written, never at first request.
+ * @param raw - the configured base URL.
+ * @returns the normalized base URL without trailing slashes.
+ */
+export declare function assertBaseURL(raw: string): string;

package/lib/types/conversion/config.d.ts

@@ -0,0 +1,4 @@
+/** Default image budgets, overridable through the adapter configuration. */
+export declare const DEFAULT_MAX_REQUEST_IMAGE_BYTES: number;
+export declare const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET: number;
+export declare const DEFAULT_REQUEST_IMAGE_MAX_BYTES: number;

package/lib/types/conversion/context.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Harness request-history conversion into pi-ai's Context vocabulary.
+ *
+ * @module dsh-opencode-go/conversion/context
+ */
+import type { GenerateOptions, ImageAttachmentAccessResolver } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment';
+import type { Context as PiContext } from '@earendil-works/pi-ai';
+/** Inputs that bind deterministic request images to one current tool execution world. */
+export interface PiImageRequestContext {
+    /** Durable provider that resolves request-image bytes and provider-owned host objects. */
+    attachments: AttachmentStore;
+    /** Resolve current tool access separately from deterministic request-image versions. */
+    resolveImageAccess: ImageAttachmentAccessResolver;
+    /** Request-level bound on the base64-encoded payload of retained images; omission leaves the bound unchecked. */
+    maxRequestImageBytes?: number;
+    /** Route pixel and raw encoded-byte budgets. */
+    requestImagePolicy?: PiImageRequestBudget;
+}
+/** Per-route budgets from which each request image's target is derived. */
+export interface PiImageRequestBudget {
+    /** Total-pixel budget; larger sources are downscaled proportionally. */
+    maxPixels: number;
+    /** Encoded-byte target for one request image. */
+    maxBytes: number;
+}
+/**
+ * Convert text-only harness history to a synchronous pi-ai Context. Tool
+ * result names are recovered from preceding assistant tool calls.
+ * @param options - the harness request; `options.system`, else a leading `system` message, maps to pi-ai's single `systemPrompt` slot.
+ * @param images - absent; selects the synchronous conversion.
+ * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+ * @returns the pi-ai context; `tools` is omitted when the request declares none.
+ * @throws {LlmError} `UNSUPPORTED_CONTENT` for images in any history role, including a leading system message.
+ */
+export declare function toPiContext(options: GenerateOptions, images?: undefined, onReplayDegrade?: (reason: string) => void): PiContext;
+/**
+ * Convert harness history to a pi-ai Context while resolving durable images.
+ * Tool result names are recovered from preceding assistant tool calls. Image
+ * occurrences the surface marks offloaded become text placeholders; when the
+ * retained occurrences' exact base64 payload still exceeds
+ * `maxRequestImageBytes`, the call fails with `IMAGE_OFFLOAD_REQUIRED` naming
+ * how many more oldest occurrences must be offloaded.
+ * @param options - the harness request; `options.system`, else a leading `system` message, maps to pi-ai's single `systemPrompt` slot.
+ * @param images - attachment provider, current path resolver, and request limits.
+ * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+ * @returns the asynchronously resolved pi-ai context.
+ */
+export declare function toPiContext(options: GenerateOptions, images: PiImageRequestContext, onReplayDegrade?: (reason: string) => void): Promise<PiContext>;

package/lib/types/conversion/index.d.ts

@@ -0,0 +1,5 @@
+/** History, image, and stream conversion shared by this plugin's protocol adapters. */
+export { toPiContext } from './context.ts';
+export type { PiImageRequestContext } from './context.ts';
+export { toStreamChunks } from './stream.ts';
+export { DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, } from './config.ts';

package/lib/types/conversion/replay.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Durable pi-ai replay metadata and assistant-history reconstruction.
+ *
+ * Harness content remains the durable source for text and tool calls. This
+ * module stores only the provider-native metadata needed to reconstruct a
+ * pi-ai assistant message on a later request.
+ *
+ * @module dsh-opencode-go/conversion/replay
+ */
+import type { Message, ReplayEnvelope } from '@deepseek-ai/dsh-llm';
+import type { Api, AssistantMessage } from '@earendil-works/pi-ai';
+/** Per-block half of the pi-ai replay envelope, one entry per content block. */
+export type PiAiReplayBlock = {
+    type: 'text';
+    textSignature?: string;
+} | {
+    type: 'reasoning';
+    thinkingSignature?: string;
+    redacted?: boolean;
+} | {
+    type: 'tool-call';
+    thoughtSignature?: string;
+};
+/** Versioned response-level half of the pi-ai replay envelope. */
+export interface PiAiReplayResponse {
+    kind: 'pi-ai';
+    version: 2;
+    api: Api;
+    provider: string;
+    /** Requested model identity, matching the durable assistant source. */
+    model: string;
+    /** Provider-reported model; only Anthropic replays it as the native model (reported in `message.model`, not `message.responseModel`). */
+    responseModel?: string;
+    responseId?: string;
+    /** Provider-native effort for historical replay; absence is preserved. */
+    providerThinkingLevel?: string;
+    stopReason: AssistantMessage['stopReason'];
+}
+/**
+ * Project a successful pi-ai response into the minimal durable replay state.
+ * The per-block half is index-aligned with the streamed blocks (pi-ai content
+ * order), so `BlockAssembler` prunes an entry with its block whenever assembly
+ * removes one.
+ * @param message - completed native pi-ai assistant response.
+ * @param requestedModel - request identity stored in the assistant source; defaults to the native model.
+ * @returns the versioned lossless-JSON replay projection.
+ */
+export declare function toPiReplayState(message: AssistantMessage, requestedModel?: string): ReplayEnvelope;
+/**
+ * Convert one durable Harness assistant message into pi-ai history.
+ *
+ * Durable content is the authoritative record; replay metadata only restores
+ * native fidelity (ids, signatures). A replay state this build cannot use —
+ * another adapter's kind, another version, a malformed value, or metadata that
+ * no longer matches the content — therefore degrades the one message to
+ * provider-neutral history instead of failing the request.
+ * @param message - assistant content with required source and optional adapter-owned replay metadata.
+ * @param onDegrade - called with the diagnostic reason when an unusable replay
+ *   state falls back to provider-neutral conversion.
+ * @returns a native pi-ai assistant message reconstructed from durable content.
+ */
+export declare function toPiAssistant(message: Message, onDegrade?: (reason: string) => void): AssistantMessage;

package/lib/types/conversion/stream.d.ts

@@ -0,0 +1,42 @@
+/**
+ * pi-ai assistant event translation into the Harness streaming protocol.
+ *
+ * pi-ai tool-call arguments are parsed objects while the Harness keeps their
+ * raw JSON representation. pi-ai also reports failures as terminal stream
+ * events, which this module maps into Harness finish chunks.
+ *
+ * @module dsh-opencode-go/conversion/stream
+ */
+import type { FinishReason, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { AssistantMessage, AssistantMessageEvent, Usage as PiUsage } from '@earendil-works/pi-ai';
+/**
+ * Map pi-ai usage (reasoning folded into output by pi-ai).
+ * @param usage - cumulative usage from the terminal pi-ai event.
+ * @returns harness counts with pi-ai's exact total; cache fields appear only
+ *   when non-zero (pi-ai reports zeros, not absence).
+ */
+export declare function mapUsage(usage: PiUsage): TokenUsage;
+/**
+ * Map a terminal pi-ai event to the harness finish reason.
+ * @param message - the assistant message carried by the `done` or `error` event.
+ * @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+ * @returns the mapped harness reason. Recognized error text, `stop` usage above
+ *   `contextWindow`, and zero-output `length` usage that fills the window map
+ *   to `CONTEXT_WINDOW_EXCEEDED`; a `stop` with no content blocks maps to an
+ *   `EMPTY_RESPONSE` error, while terminal `pending` and `deferred` states map
+ *   to non-retryable `PI_AI_ERROR` failures.
+ */
+export declare function mapStopReason(message: AssistantMessage, contextWindow?: number): FinishReason;
+/**
+ * Translate the pi-ai event stream into StreamChunks. pi-ai never throws
+ * mid-stream — failures arrive as `error` events, which become error/aborted
+ * `finish` chunks (the harness protocol's other error-delivery style).
+ * @param events - one assistant turn's pi-ai event stream.
+ * @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+ * @param callerSignal - caller cancellation state; an aborted caller makes any
+ *   in-band terminal error an aborted finish.
+ * @param requestedModel - request model identity recorded for durable replay.
+ * @returns the harness chunks, ending with `usage` then `finish`; throws
+ *   `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event.
+ */
+export declare function toStreamChunks(events: AsyncIterable<AssistantMessageEvent>, contextWindow?: number, callerSignal?: AbortSignal, requestedModel?: string): AsyncGenerator<StreamChunk>;

package/lib/types/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Dedicated OpenCode Go adapter plugin. Registers one `opencode-go` route
+ * whose catalog is the curated table intersected with the gateway's live model
+ * listing, and installs the `llm-opencode-go` settings section: the Web UI
+ * renders it as its own settings page where the API key and every knob are
+ * edited, and a change reaches the next request without a restart. The plugin
+ * exists because the gateway has wire requirements a generic pi-ai route
+ * cannot express: a mandatory per-conversation `x-opencode-session` routing
+ * header and a model list that rotates faster than any shipped catalog.
+ *
+ * Configuration layers like every settings-backed plugin: a `cordis.yml`
+ * entry supplies the composition base and the settings document overrides it
+ * field by field.
+ *
+ * ```yaml
+ * - id: llm-opencode-go
+ *   name: 'dsh-opencode-go'
+ *   config:
+ *     enabled: true                     # false withdraws the route; the plugin stays mounted
+ *     apiKeyEnv: OPENCODE_API_KEY       # default
+ *     baseURL: https://opencode.ai/zen/go/v1   # default
+ *     refreshMinutes: 60                # live catalog re-resolution interval
+ * ```
+ *
+ * The credential resolves per request through the credentials seam, falling
+ * back to the process environment — the same reference semantics the generic
+ * pi-ai adapter uses. The route registers atomically: if another adapter
+ * family already owns `opencode-go` (a profile in `llm-pi-ai`, for example),
+ * the refusal is logged with the reason and everything else this plugin does
+ * still works.
+ *
+ * @module dsh-opencode-go
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { OpencodeGoConfig } from './config.ts';
+export { OpencodeGoAdapter } from './adapter.ts';
+export type { OpencodeGoAdapterOptions, OpencodeGoImageAccess } from './adapter.ts';
+export { DEFAULT_BASE_URL, DISPLAY_NAME, PROVIDER_ID, OpencodeGoCatalog, discoverCatalogModels, readLiveModelIds, } from './catalog.ts';
+export { Config, assertBaseURL } from './config.ts';
+export type { OpencodeGoConfig } from './config.ts';
+export declare const name = "llm-opencode-go";
+export declare const inject: string[];
+/** Settings namespace this plugin installs and the Web page edits. */
+export declare const NS = "llm-opencode-go";
+/**
+ * Register the route, its discovery, the settings section, and their
+ * teardown for one mount. Configuration starts as the cordis.yml entry and is
+ * replaced by the settings section's resolved value once the settings
+ * provider attaches; the adapter re-reads it at every operation.
+ */
+export declare function apply(ctx: Context, raw?: OpencodeGoConfig): void;

package/package.json

@@ -0,0 +1,174 @@
+{
+  "name": "dsh-opencode-go",
+  "version": "0.1.0",
+  "description": "OpenCode Go model provider and settings UI for DeepSeek Harness",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "THIRD_PARTY_NOTICES.md",
+    "docs",
+    "examples"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.host.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build",
+    "pretest": "npm run build",
+    "verify:installed": "node --expose-internals scripts/installed-smoke.mjs",
+    "verify:headless": "node scripts/headless-smoke.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-attachment": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-credentials": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-fs": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-launch-environment": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-settings": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-timeout": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-api-remotes": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-api-gateway": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-api-settings-controller": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-store": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.6-alpha.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-brand": "0.1.6-alpha.1",
+    "@deepseek-ai/schemastery": "3.18.2",
+    "@earendil-works/pi-ai": "0.85.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/cordis-plugin-include": "1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.3",
+    "@deepseek-ai/dsh-api-gateway": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-api-remotes": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-api-settings-controller": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-attachment": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-brand": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-store": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-credentials": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-credentials-local": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-fs": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-launch-environment": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-settings": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-settings-file": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-timeout": "0.1.6-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.6-alpha.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "esbuild": "^0.25.0",
+    "jsdom": "29.1.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "6.0.3",
+    "vitest": "^4.1.8",
+    "@types/react-dom": "~18.3.0",
+    "clsx": "^2.0.0",
+    "diff": "^9.0.0",
+    "anser": "^2.3.5",
+    "katex": "^0.16.47",
+    "micromark-core-commonmark": "^2.0.3",
+    "micromark-util-character": "^2.1.1",
+    "micromark-util-classify-character": "^2.0.1",
+    "micromark-util-symbol": "^2.0.1",
+    "micromark-util-types": "^2.0.2",
+    "shiki": "^4.3.1",
+    "@shikijs/langs": "^4.3.1",
+    "@types/mdast": "^4.0.4",
+    "micromark-factory-space": "^2.0.1",
+    "micromark-extension-math": "^3.1.0",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-math": "^3.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-util-sanitize-uri": "^2.0.1",
+    "zustand": "~4.4.7",
+    "immer": "^10.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-api-remotes": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-api-gateway": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-api-settings-controller": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-store": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-renderer": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-typert-protocol": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "opencode",
+    "opencode-go",
+    "llm",
+    "cordis"
+  ]
+}