dsh-opencode 0.1.0

package/lib/config.d.ts

@@ -0,0 +1,38 @@
+import { Product } from "./normalize.js";
+import { RetryPolicyConfig } from "@deepseek-ai/dsh-llm";
+import z from "@deepseek-ai/schemastery";
+//#region src/config.d.ts
+/** Configuration for one fixed live route; the `providers` dict key IS the route. */
+interface OpenCodeProviderConfig {
+  /** Which OpenCode product this route serves; must match the route key. */
+  product?: Product;
+  /** Credential reference (environment-variable name) resolved per request. */
+  apiKeyEnv?: string;
+  /** Display name shown by configuration surfaces. */
+  displayName?: string;
+  /** Additional deployment-owned request headers. */
+  headers?: Record<string, string>;
+  /** Provider-owned model-request retry policy. */
+  retryPolicy?: RetryPolicyConfig;
+  /** Maximum provider idle time while one stream read is outstanding. */
+  streamIdleTimeoutMs?: number;
+}
+/** Catalog refresh configuration. */
+interface CatalogConfigInput {
+  refreshIntervalMs?: number;
+  listRevalidateAfterMs?: number;
+  timeoutMs?: number;
+  maxStaleMs?: number;
+  requireFresh?: boolean;
+  /** Cache file location; defaults under the DSH home. */
+  cachePath?: string;
+}
+/** Plugin configuration. */
+interface Config {
+  providers?: Record<string, OpenCodeProviderConfig>;
+  catalog?: CatalogConfigInput;
+}
+/** Runtime schema for {@link Config}. */
+declare const Config: z<Config>;
+//#endregion
+export { CatalogConfigInput, Config, OpenCodeProviderConfig };

package/lib/config.js

@@ -0,0 +1,142 @@
+import { PRODUCT_BY_ROUTE, ROUTE_BY_PRODUCT } from "./normalize.js";
+import { RetryPolicySchema, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+//#region src/config.ts
+/**
+* Non-secret configuration schema for the `opencode-live` plugin.
+*
+* The composition base (cordis.patch.yml) and the optional user-settings
+* section share this schema. Configuration carries references, never secret
+* values: the API key is named through `apiKeyEnv` and resolved per request
+* through the DSH credential seam.
+*
+* The plugin owns exactly two fixed routes. A provider entry keyed anything
+* else, or keyed with the wrong product, is refused where it is written.
+*
+* @module opencode-live/config
+*/
+/** Upper bound shared with DSH's timer facilities. */
+const MAX_TIMER_DELAY_MS = 2147483647;
+/** The credential reference both OpenCode products document. */
+const DEFAULT_API_KEY_ENV = "OPENCODE_API_KEY";
+const DEFAULT_REFRESH_INTERVAL_MS = 9e5;
+const DEFAULT_LIST_REVALIDATE_AFTER_MS = 6e4;
+const DEFAULT_TIMEOUT_MS = 15e3;
+const DEFAULT_MAX_STALE_MS = 6048e5;
+const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 3e5;
+const DEFAULT_MAX_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024;
+const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 2048 * 2048;
+const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
+const productSchema = z.union([z.const("zen").required(), z.const("go").required()]);
+const providerSchema = z.object({
+	product: productSchema,
+	apiKeyEnv: z.string().role("credential-ref"),
+	displayName: z.string(),
+	headers: z.dict(z.string()),
+	retryPolicy: RetryPolicySchema,
+	streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS)
+});
+const catalogSchema = z.object({
+	refreshIntervalMs: z.number().step(1).min(1),
+	listRevalidateAfterMs: z.number().step(1).min(1),
+	timeoutMs: z.number().step(1).min(1),
+	maxStaleMs: z.number().step(1).min(1),
+	requireFresh: z.boolean(),
+	cachePath: z.string()
+});
+/** Runtime schema for {@link Config}. */
+const Config = z.object({
+	providers: z.dict(providerSchema),
+	catalog: catalogSchema.default({})
+});
+/** Whether one number is a positive finite integer within timer bounds. */
+function isBoundedPositiveInteger(value, max) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= max;
+}
+/** Validate one bounded catalog interval field. */
+function requireInterval(value, fallback, label, max = MAX_TIMER_DELAY_MS) {
+	const resolved = value ?? fallback;
+	if (!isBoundedPositiveInteger(resolved, max)) throw new Error(`opencode-live: catalog.${label} must be a positive integer no greater than ${max}`);
+	return resolved;
+}
+/**
+* Validate configuration and resolve every default. This is the one explicit
+* resolve step; an invalid route key, a product/route mismatch, or an out-of
+* -bound interval fails loudly here instead of disabling a route silently.
+* @param config - the raw configuration value.
+* @returns detached validated configuration.
+*/
+function resolveConfig(config) {
+	const providers = /* @__PURE__ */ new Map();
+	const entries = Object.entries(config.providers ?? {});
+	if (entries.length === 0) for (const route of [ROUTE_BY_PRODUCT.zen, ROUTE_BY_PRODUCT.go]) providers.set(route, resolveProvider(route, {
+		product: PRODUCT_BY_ROUTE[route],
+		apiKeyEnv: DEFAULT_API_KEY_ENV
+	}));
+	for (const [route, source] of entries) {
+		if (route !== ROUTE_BY_PRODUCT.zen && route !== ROUTE_BY_PRODUCT.go) throw new Error(`opencode-live: provider "${route}" is not a route this plugin owns; the fixed routes are ${ROUTE_BY_PRODUCT.zen} and ${ROUTE_BY_PRODUCT.go}`);
+		const resolved = resolveProvider(route, source);
+		if (providers.get(resolved.route) !== void 0) throw new Error(`opencode-live: provider "${route}" is declared twice`);
+		providers.set(resolved.route, resolved);
+	}
+	return {
+		providers,
+		catalog: {
+			refreshIntervalMs: requireInterval(config.catalog?.refreshIntervalMs, DEFAULT_REFRESH_INTERVAL_MS, "refreshIntervalMs"),
+			listRevalidateAfterMs: requireInterval(config.catalog?.listRevalidateAfterMs, DEFAULT_LIST_REVALIDATE_AFTER_MS, "listRevalidateAfterMs"),
+			timeoutMs: requireInterval(config.catalog?.timeoutMs, DEFAULT_TIMEOUT_MS, "timeoutMs"),
+			maxStaleMs: requireInterval(config.catalog?.maxStaleMs, DEFAULT_MAX_STALE_MS, "maxStaleMs"),
+			requireFresh: config.catalog?.requireFresh ?? false,
+			...config.catalog?.cachePath !== void 0 ? { cachePath: requireCachePath(config.catalog.cachePath) } : {}
+		}
+	};
+}
+/** Validate one provider entry against its fixed route. */
+function resolveProvider(route, source) {
+	const product = source.product ?? PRODUCT_BY_ROUTE[route];
+	if (PRODUCT_BY_ROUTE[route] !== product) throw new Error(`opencode-live: provider "${route}" declares product "${source.product}", but this route serves "${PRODUCT_BY_ROUTE[route]}"`);
+	const apiKeyEnv = credentialRef(source.apiKeyEnv ?? "OPENCODE_API_KEY");
+	const streamIdleTimeoutMs = source.streamIdleTimeoutMs ?? 3e5;
+	if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) throw new Error(`opencode-live: provider "${route}" streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+	if (source.displayName !== void 0 && source.displayName.length === 0) throw new Error(`opencode-live: provider "${route}" has an empty displayName`);
+	assertValidHeaders(route, source.headers);
+	return {
+		route,
+		product,
+		apiKeyEnv,
+		displayName: source.displayName ?? defaultDisplayName(route),
+		...source.headers !== void 0 ? { headers: { ...source.headers } } : {},
+		retryPolicy: resolveRetryPolicy(source.retryPolicy, `opencode-live: provider "${route}" retryPolicy`),
+		streamIdleTimeoutMs
+	};
+}
+/** The default display name for one fixed route. */
+function defaultDisplayName(route) {
+	return route === ROUTE_BY_PRODUCT.zen ? "OpenCode Zen (Live)" : "OpenCode Go (Live)";
+}
+/** Reject a header Fetch cannot carry, naming the route and field. */
+function assertValidHeaders(route, headers) {
+	for (const [name, value] of Object.entries(headers ?? {})) try {
+		new Headers([[name, value]]);
+	} catch {
+		throw new Error(`opencode-live: provider "${route}" header "${name}" is not valid for Fetch; use a valid HTTP field name and a single-line value representable as bytes`);
+	}
+}
+/** Validate the optional cache path override. */
+function requireCachePath(path) {
+	if (path.length === 0) throw new Error("opencode-live: catalog.cachePath must be a non-empty path when set");
+	return path;
+}
+/**
+* Refuse a section this plugin could not serve. Registered as the settings
+* namespace's validator so an invalid route or interval is rejected where it
+* is written instead of silently disabling a route.
+* @param config - the resolved section to check.
+* @throws Error naming the offending configuration entry.
+*/
+function assertServiceable(config) {
+	resolveConfig(config);
+}
+//#endregion
+export { Config, DEFAULT_API_KEY_ENV, DEFAULT_LIST_REVALIDATE_AFTER_MS, DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_MAX_STALE_MS, DEFAULT_REFRESH_INTERVAL_MS, DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, assertServiceable, resolveConfig };

package/lib/credentials.js

@@ -0,0 +1,88 @@
+import { LlmError, assertUsableApiKey } from "@deepseek-ai/dsh-llm";
+import "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+//#region src/credentials.ts
+/**
+* Resolve the API key for one inference call.
+*
+* Mirrors the fail-loud reference semantics of the DSH pi-ai adapter: a named
+* reference that misses throws `MISSING_CREDENTIAL` naming the route and the
+* reference, never a key fragment, and never falls back to an ambient key
+* another provider might have left in the environment.
+* @param ctx - the plugin context carrying the optional credential service.
+* @param route - the live route the credential is resolved for.
+* @param profile - the resolved profile naming the credential reference.
+* @returns the validated key for this call.
+* @throws {LlmError} code `MISSING_CREDENTIAL` when the reference is unset.
+*/
+async function resolveApiKeyFor(ctx, route, profile) {
+	const ref = profile.apiKeyEnv;
+	if (ref === void 0) return void 0;
+	const credentials = ctx.get("credentials");
+	const hit = credentials !== void 0 ? (await credentials.resolve(ref))?.value : launchEnvironmentOf(ctx).get(ref)?.value;
+	if (hit !== void 0 && hit.length > 0) return assertUsableApiKey(hit, "opencode-live", ref);
+	throw new LlmError(`opencode-live: no credential for provider route "${route}"; its profile resolves ${ref}, which is not set — store it through the credentials service (the web Models page writes it) or export it in the launching environment`, "MISSING_CREDENTIAL");
+}
+/**
+* Api-key auth for a route the plugin authenticates itself.
+*
+* `Models` calls this when the request carries no `apiKey` override (for
+* example a status check): it reports the route as unconfigured rather than
+* inventing ambient credentials. The per-request key override remains the
+* only real authentication path.
+* @param name - display name used as the resolution's status label.
+* @returns the api-key auth method.
+*/
+function apiKeyOnlyAuth(name) {
+	return {
+		name,
+		resolve: ({ credential }) => Promise.resolve({
+			auth: credential?.key === void 0 ? {} : { apiKey: credential.key },
+			source: name
+		})
+	};
+}
+/**
+* Whether the configured reference is currently set, for status display.
+* Presence is reported without ever exposing the value.
+* @param ctx - the plugin context.
+* @param ref - the credential reference to describe.
+* @returns presence facts, or `undefined` without a credential service.
+*/
+async function describeCredential(ctx, ref) {
+	const credentials = ctx.get("credentials");
+	if (credentials === void 0) return void 0;
+	return credentials.describe(ref);
+}
+/**
+* The stable auth bridge handed to `PiAiAdapter`.
+*
+* pi-ai requires both members; this plugin's routes authenticate exclusively
+* through the per-request key, so the store is inert (nothing to read, no
+* sign-in to persist) and the context never answers ambient questions. A
+* write attempt is refused loudly rather than silently dropped: a login that
+* believed it persisted would fail every later request.
+* @returns the injection for `createModels()`.
+*/
+function staticAuthBridge() {
+	return {
+		credentials: {
+			async read() {},
+			async list() {
+				return [];
+			},
+			async modify() {
+				throw new LlmError("opencode-live: stored credential sign-ins are not supported; its routes authenticate through the apiKeyEnv reference resolved by the DSH credential service", "NO_CREDENTIAL_STORE");
+			},
+			async delete() {}
+		},
+		authContext: {
+			async env() {},
+			async fileExists() {
+				return false;
+			}
+		}
+	};
+}
+//#endregion
+export { apiKeyOnlyAuth, describeCredential, resolveApiKeyFor, staticAuthBridge };

package/lib/index.d.ts

@@ -0,0 +1,19 @@
+import { Product, ROUTE_BY_PRODUCT, RouteId } from "./normalize.js";
+import { Config } from "./config.js";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/index.d.ts
+/** Cordis plugin name. */
+declare const name = "opencode-live";
+/** Services required before the plugin can activate. */
+declare const inject: string[];
+/** The settings namespace this plugin owns. */
+declare const SETTINGS_NAMESPACE = "opencode-live";
+/**
+ * Register the plugin against one composition context.
+ * @param ctx - the Cordis context.
+ * @param config - the composition base configuration for this plugin.
+ */
+declare function apply(ctx: Context, config?: Config): void;
+//#endregion
+export { Config, type Product, ROUTE_BY_PRODUCT, type RouteId, SETTINGS_NAMESPACE, apply, inject, name };

package/lib/index.js

@@ -0,0 +1,208 @@
+import { ROUTE_BY_PRODUCT } from "./normalize.js";
+import { LiveOpenCodeAdapter } from "./adapter.js";
+import { readySetHash } from "./snapshot.js";
+import { CatalogManager } from "./catalog.js";
+import { Config, DEFAULT_MAX_REQUEST_IMAGE_BYTES, DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, assertServiceable, resolveConfig } from "./config.js";
+import { apiKeyOnlyAuth, describeCredential, resolveApiKeyFor, staticAuthBridge } from "./credentials.js";
+import { registerCommands } from "./commands.js";
+import { buildRouteProvider } from "./transport.js";
+import { resolveImageAttachmentAccess, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+//#region src/index.ts
+/** Cordis plugin name. */
+const name = "opencode-live";
+/** Services required before the plugin can activate. */
+const inject = ["llm"];
+/** The settings namespace this plugin owns. */
+const SETTINGS_NAMESPACE = "opencode-live";
+/**
+* Register the plugin against one composition context.
+* @param ctx - the Cordis context.
+* @param config - the composition base configuration for this plugin.
+*/
+function apply(ctx, config = {}) {
+	const resolved = resolveConfig(config);
+	let currentConfig = resolved;
+	let configRevision = 0;
+	const catalog = new CatalogManager({
+		config: {
+			...resolved.catalog,
+			...resolved.catalog.cachePath === void 0 ? { cachePath: defaultCachePath() } : {}
+		},
+		onChange: (snapshot) => onCatalogChange(snapshot),
+		warn: (message) => ctx.logger.warn(message)
+	});
+	const adapter = new LiveOpenCodeAdapter({
+		profiles,
+		resolveApiKey: (route, profile) => resolveApiKeyFor(ctx, route, profile),
+		auth: staticAuthBridge(),
+		resolveAttachments: () => ctx.get("attachments"),
+		resolveImageAccess: (attachments, ref) => resolveImageAttachmentAccess(attachments, (hostPath) => ctx.get("fs")?.processPathFromHostPath(hostPath), ref),
+		catalog,
+		initialWaitMs: currentConfig.catalog.timeoutMs,
+		requireFresh: currentConfig.catalog.requireFresh,
+		onReplayDegrade: ({ provider, model, reason }) => {
+			ctx.logger.warn(`opencode-live: unusable replay state on assistant history for route "${provider}/${model}"; sending that message as provider-neutral content (${reason})`);
+		}
+	});
+	/** Memoized profiles keyed by configuration revision and catalog content. */
+	let memoKey;
+	let memoProfiles;
+	function profiles() {
+		const key = `${configRevision}:${catalog.current?.contentHash ?? "empty"}`;
+		if (memoKey === key && memoProfiles !== void 0) return memoProfiles;
+		const map = /* @__PURE__ */ new Map();
+		for (const [route, providerConfig] of currentConfig.providers) {
+			const view = catalog.current?.products[providerConfig.product];
+			const ready = view === void 0 ? [] : view.readyIds.map((id) => view.candidates.get(id)).filter((candidate) => candidate !== void 0);
+			map.set(route, {
+				provider: route,
+				displayName: providerConfig.displayName,
+				apiKeyEnv: providerConfig.apiKeyEnv,
+				streamIdleTimeoutMs: providerConfig.streamIdleTimeoutMs,
+				maxRequestImageBytes: DEFAULT_MAX_REQUEST_IMAGE_BYTES,
+				requestImagePixelBudget: DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
+				requestImageMaxBytes: DEFAULT_REQUEST_IMAGE_MAX_BYTES,
+				retryPolicy: providerConfig.retryPolicy ?? resolveRetryPolicy(void 0, `opencode-live: provider "${route}" retryPolicy`),
+				...providerConfig.headers !== void 0 ? { headers: { ...providerConfig.headers } } : {},
+				configuredMaxTokens: /* @__PURE__ */ new Map(),
+				piProvider: buildRouteProvider({
+					route,
+					product: providerConfig.product,
+					displayName: providerConfig.displayName,
+					ready,
+					auth: { apiKey: apiKeyOnlyAuth(providerConfig.displayName) }
+				})
+			});
+		}
+		memoKey = key;
+		memoProfiles = map;
+		return map;
+	}
+	let registration;
+	let registeredFacts;
+	let lastReadyHash;
+	/** The current route list in fixed order. */
+	function routeList() {
+		return [...currentConfig.providers.keys()];
+	}
+	/** Registration facts: routes with their display names and retry policies. */
+	function registrationFacts() {
+		return JSON.stringify(routeList().map((route) => {
+			const provider = currentConfig.providers.get(route);
+			return {
+				route,
+				displayName: provider?.displayName,
+				retryPolicy: provider?.retryPolicy
+			};
+		}));
+	}
+	/** Register or atomically replace this adapter's routes. */
+	function ensureRegistration() {
+		const routes = routeList();
+		const facts = registrationFacts();
+		if (registration === void 0) {
+			if (routes.length === 0) {
+				registeredFacts = facts;
+				return;
+			}
+			registration = ctx.llm.registerAdapter(routes, adapter);
+			registeredFacts = facts;
+			return;
+		}
+		registration.replace(routes);
+		registeredFacts = facts;
+	}
+	/** The directory entries for the two fixed routes. */
+	function directoryEntries() {
+		return routeList().map((route) => ({
+			provider: route,
+			displayName: currentConfig.providers.get(route)?.displayName ?? route,
+			settingsNs: SETTINGS_NAMESPACE,
+			settingsPath: ["providers", route],
+			declared: true
+		}));
+	}
+	let directory;
+	/** Register or atomically replace the configurable-provider directory. */
+	function ensureDirectory() {
+		const entries = directoryEntries();
+		JSON.stringify(entries);
+		if (directory === void 0) {
+			if (entries.length === 0) return;
+			directory = ctx.llm.registerConfigurableProviders(entries);
+			return;
+		}
+		directory.replace(entries);
+	}
+	/** Re-register only when the executable set actually changed. */
+	function onCatalogChange(snapshot) {
+		if (snapshot === void 0) return;
+		const hash = readySetHash(snapshot);
+		if (hash === lastReadyHash) return;
+		lastReadyHash = hash;
+		if (registration !== void 0) ensureRegistration();
+	}
+	ensureRegistration();
+	ensureDirectory();
+	let commandDisposers = [];
+	ctx.inject(["commands"], (commandsCtx) => {
+		commandDisposers = registerCommands(commandsCtx, {
+			catalog,
+			config: () => currentConfig,
+			describeCredential: async (route) => {
+				const provider = currentConfig.providers.get(route);
+				if (provider === void 0) return void 0;
+				return describeCredential(ctx, provider.apiKeyEnv);
+			}
+		});
+	});
+	let source = () => config;
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.installSection(ctx, SETTINGS_NAMESPACE, Config, config, {
+			validate: assertServiceable,
+			setSource: (next) => {
+				source = next;
+			},
+			onChange: () => {
+				try {
+					const next = resolveConfig(source());
+					const catalogChanged = JSON.stringify(next.catalog) !== JSON.stringify(currentConfig.catalog);
+					const routesChanged = registrationFacts() !== registeredFacts;
+					currentConfig = next;
+					configRevision += 1;
+					adapter.updateOptions({
+						initialWaitMs: next.catalog.timeoutMs,
+						requireFresh: next.catalog.requireFresh
+					});
+					if (catalogChanged) catalog.reconfigure({
+						...next.catalog,
+						...next.catalog.cachePath === void 0 ? {} : { cachePath: next.catalog.cachePath }
+					});
+					if (routesChanged) ensureRegistration();
+					ensureDirectory();
+				} catch (error) {
+					ctx.logger.error("opencode-live: keeping the previously registered routes after a refused settings update");
+					ctx.logger.error(error);
+				}
+			}
+		});
+	});
+	ctx.effect(function* () {
+		yield () => {
+			catalog.stop();
+			for (const dispose of commandDisposers) dispose();
+			commandDisposers = [];
+		};
+	}, "opencode-live effects");
+	catalog.start().catch((error) => {
+		ctx.logger.warn("opencode-live: the initial catalog refresh failed; the catalog will retry periodically");
+		ctx.logger.warn(error);
+	});
+}
+/** The default cache location under the resolved DSH home. */
+function defaultCachePath() {
+	return dshHomePath("cache", "opencode-live", "catalog.json");
+}
+//#endregion
+export { Config, ROUTE_BY_PRODUCT, SETTINGS_NAMESPACE, apply, inject, name };

package/lib/normalize.d.ts

@@ -0,0 +1,10 @@
+//#region src/normalize.d.ts
+/** The two OpenCode products this plugin serves. */
+type Product = 'zen' | 'go';
+/** DSH route keys this plugin registers; fixed for the plugin's lifetime. */
+declare const ROUTE_ZEN = "opencode-zen-live";
+declare const ROUTE_GO = "opencode-go-live";
+type RouteId = typeof ROUTE_ZEN | typeof ROUTE_GO;
+declare const ROUTE_BY_PRODUCT: Readonly<Record<Product, RouteId>>;
+//#endregion
+export { Product, ROUTE_BY_PRODUCT, ROUTE_GO, ROUTE_ZEN, RouteId };