@dan-ai-studio/dshopencodego 0.1.5

package/lib/types/adapter.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The OpenCode Go adapter: one route, one live catalog, one mandatory header.
+ *
+ * The gateway has two requirements a generic pi-ai route cannot express — a
+ * model list that rotates faster than any shipped catalog, and a per
+ * conversation `x-opencode-session` routing header — so this adapter owns both
+ * instead of delegating them to configuration.
+ *
+ * Each operation reads the current configuration and resolves the catalog
+ * snapshot once, before its first await, so a settings change reaches the next
+ * request and never mixes two catalog generations inside one call.
+ *
+ * @module @dan-ai-studio/dshopencodego/adapter
+ */
+import { attributionHeaders, LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, ImageAttachmentAccess, LlmModelInfo, LlmResolvedModelInfo, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import { OpencodeGoCatalog } from './catalog/index.ts';
+import type { OpencodeGoConfig } from './config.ts';
+/** Image machinery the adapter reads once per request. */
+export interface OpencodeGoImageAccess {
+    /** Resolve the durable attachment service at request time. */
+    readonly resolveAttachments: () => AttachmentStore | undefined;
+    /** Bridge one attachment reference into the current tool execution world. */
+    readonly resolveImageAccess: (attachments: AttachmentStore, ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
+}
+/** Constructor inputs for {@link OpencodeGoAdapter}. */
+export interface OpencodeGoAdapterOptions {
+    /** Current configuration, re-read at every operation. */
+    readonly config: () => OpencodeGoConfig;
+    /** Resolve the route credential; a miss must fail loud, never fall back. */
+    readonly resolveApiKey: () => Promise<string | undefined>;
+    /** Image input machinery; absent refuses image content. */
+    readonly imageAccess?: OpencodeGoImageAccess;
+    /** Observe a catalog source falling back to retained data. */
+    readonly onFallback?: (detail: {
+        url: string;
+        error: unknown;
+        kept: number;
+    }) => void;
+    /** Observe gateway models this build cannot configure. */
+    readonly onUnconfigured?: (detail: {
+        id: string;
+        reason: string;
+    }[]) => void;
+    /** Observe assistant history degrading to provider-neutral conversion. */
+    readonly onReplayDegrade?: (reason: string) => void;
+    /**
+     * Observe the provider's own usage for one completed call. This is the only
+     * honest source of token counts: the gateway's `/usage` endpoint reports
+     * account percentages, not tokens.
+     */
+    readonly onUsage?: (detail: {
+        model: string;
+        usage: TokenUsage;
+    }) => void;
+}
+/**
+ * The single `opencode-go` route's adapter.
+ *
+ * The catalog is cached per endpoint, refresh interval, and protocol-override
+ * set: changing any of those builds a new one, while a settings change that
+ * touches none of them keeps the cached snapshot for its full TTL.
+ */
+export declare class OpencodeGoAdapter extends LlmAdapter {
+    private cache;
+    private readonly options;
+    constructor(options: OpencodeGoAdapterOptions);
+    /** The catalog for one configuration, rebuilt when its owned facts change. */
+    catalogOf(config: OpencodeGoConfig): OpencodeGoCatalog;
+    providerInfo(provider: string): {
+        id: string;
+        name: string;
+    };
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(_provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /** Describe one model: capacities plus the reasoning levels it really offers. */
+    private modelInfo;
+    /** Validate an explicit effort against the model's own levels, without clamping. */
+    private resolveReasoningLevel;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/** Re-exported so a composition can assert the attribution contract in one place. */
+export { attributionHeaders };

package/lib/types/adapter.js

@@ -0,0 +1,311 @@
+/**
+ * The OpenCode Go adapter: one route, one live catalog, one mandatory header.
+ *
+ * The gateway has two requirements a generic pi-ai route cannot express — a
+ * model list that rotates faster than any shipped catalog, and a per
+ * conversation `x-opencode-session` routing header — so this adapter owns both
+ * instead of delegating them to configuration.
+ *
+ * Each operation reads the current configuration and resolves the catalog
+ * snapshot once, before its first await, so a settings change reaches the next
+ * request and never mixes two catalog generations inside one call.
+ *
+ * @module @dan-ai-studio/dshopencodego/adapter
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { getSupportedThinkingLevels, normalizeContext } from '@earendil-works/pi-ai';
+import { attributionHeaders, contentHasImage, LlmAdapter, LlmError, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
+import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout';
+import { DISPLAY_NAME, PROVIDER_ID, OpencodeGoCatalog } from "./catalog/index.js";
+import { toPiModel } from "./catalog/metadata.js";
+import { assertBaseURL } from "./config.js";
+import { toPiContext, toStreamChunks } from "./conversion/index.js";
+import { isModelEnabled, recommendedIds } from "./models.js";
+import { providerHeaders } from "./session-header.js";
+/**
+ * pi-ai thinking formats that answer an unset effort with an explicit disable.
+ * Every other format omits the parameter and lets the provider decide, so only
+ * these need a default effort to avoid silently turning thinking off.
+ */
+const DISABLES_THINKING_WHEN_UNSET = new Set(['deepseek', 'zai', 'qwen', 'qwen-chat-template']);
+/** Apply one request's configured capacities without touching the catalog. */
+function withModelLimit(model, limits) {
+    const limit = limits[model.id];
+    if (limit === null || limit === undefined)
+        return model;
+    return {
+        ...model,
+        contextWindow: limit.contextWindow ?? model.contextWindow,
+        maxTokens: limit.maxTokens ?? model.maxTokens,
+    };
+}
+/**
+ * The single `opencode-go` route's adapter.
+ *
+ * The catalog is cached per endpoint, refresh interval, and protocol-override
+ * set: changing any of those builds a new one, while a settings change that
+ * touches none of them keeps the cached snapshot for its full TTL.
+ */
+export class OpencodeGoAdapter extends LlmAdapter {
+    cache;
+    options;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    /** The catalog for one configuration, rebuilt when its owned facts change. */
+    catalogOf(config) {
+        const key = `${config.baseURL}|${String(config.refreshMinutes)}|${JSON.stringify(config.modelProtocols)}`;
+        if (this.cache?.key !== key) {
+            this.cache = {
+                key,
+                catalog: new OpencodeGoCatalog({
+                    baseURL: assertBaseURL(config.baseURL),
+                    refreshMs: config.refreshMinutes * 60_000,
+                    defaults: {
+                        contextWindow: 262_144,
+                        maxTokens: 32_768,
+                        input: ['text'],
+                    },
+                    overrides: config.modelProtocols,
+                    observers: {
+                        ...this.options.onFallback === undefined ? {} : { onFallback: this.options.onFallback },
+                        ...this.options.onUnconfigured === undefined ? {} : { onUnconfigured: this.options.onUnconfigured },
+                    },
+                }),
+            };
+        }
+        return this.cache.catalog;
+    }
+    providerInfo(provider) {
+        return { id: provider, name: DISPLAY_NAME };
+    }
+    async listModels(_provider) {
+        const config = this.options.config();
+        const snapshot = await this.catalogOf(config).snapshot();
+        // DSH resolves every listed model before showing the provider, so an
+        // unconfigurable id belongs in the settings diagnostics, not this list.
+        const facts = [...snapshot.facts.values()];
+        // The same default the settings page marks: without explicit switches the
+        // top few by published monthly estimate stay enabled.
+        const recommended = recommendedIds(facts);
+        return facts
+            .map(fact => ({ ...fact, recommended: recommended.has(fact.id) }))
+            .filter(fact => isModelEnabled(fact, config.modelVisibility))
+            .map(fact => ({
+            provider: PROVIDER_ID,
+            id: fact.id,
+            name: fact.name,
+            inputModalities: [...fact.input],
+        }));
+    }
+    async resolveModel(_provider, model, _signal) {
+        const config = this.options.config();
+        const snapshot = await this.catalogOf(config).forModel(model);
+        const facts = snapshot.facts.get(model);
+        if (facts === undefined)
+            throw new LlmError(`opencode-go has no model "${model}"`, 'UNKNOWN_MODEL');
+        return this.modelInfo(withModelLimit(toPiModel(facts, config.baseURL), config.modelLimits));
+    }
+    /** Describe one model: capacities plus the reasoning levels it really offers. */
+    modelInfo(model) {
+        const reasoning = {};
+        const levels = model.reasoning ? getSupportedThinkingLevels(model) : [];
+        if (levels.length > 0) {
+            // A format that disables thinking when no effort is named would silently
+            // strip reasoning from a model that offers levels, so it gets a default.
+            const format = model.compat?.thinkingFormat;
+            const fallback = format !== undefined && DISABLES_THINKING_WHEN_UNSET.has(format)
+                ? levels.includes('high') ? 'high' : levels.findLast(level => level !== 'off')
+                : undefined;
+            reasoning.reasoning = {
+                efforts: levels.map(level => ({
+                    id: ReasoningEffortId(level),
+                    name: `${level.charAt(0).toUpperCase()}${level.slice(1)}`,
+                })),
+                ...fallback === undefined ? {} : { defaultEffort: ReasoningEffortId(fallback) },
+            };
+        }
+        return {
+            provider: PROVIDER_ID,
+            id: model.id,
+            name: model.name,
+            inputModalities: [...model.input],
+            context: { contextWindow: model.contextWindow },
+            ...reasoning,
+        };
+    }
+    /** Validate an explicit effort against the model's own levels, without clamping. */
+    resolveReasoningLevel(model, effort) {
+        if (effort === undefined)
+            return undefined;
+        const supported = getSupportedThinkingLevels(model);
+        if (supported.some(level => level === effort))
+            return effort;
+        throw new LlmError(`opencode-go model "${model.id}" does not support reasoning effort "${effort}"`, 'UNSUPPORTED_REASONING_EFFORT');
+    }
+    async *stream(options) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (options.stop !== undefined) {
+                throw new LlmError('dshopencodego does not support GenerateOptions.stop', 'UNSUPPORTED_OPTION');
+            }
+            const config = this.options.config();
+            const snapshot = await this.catalogOf(config).forModel(options.model);
+            const facts = snapshot.facts.get(options.model);
+            if (facts === undefined)
+                throw new LlmError(`opencode-go has no model "${options.model}"`, 'UNKNOWN_MODEL');
+            const model = withModelLimit(toPiModel(facts, config.baseURL), config.modelLimits);
+            const outputLimit = config.modelLimits[model.id]?.maxTokens;
+            const maxTokens = outputLimit === null || outputLimit === undefined
+                ? options.maxTokens
+                : Math.min(options.maxTokens ?? outputLimit, outputLimit);
+            const apiKey = await this.options.resolveApiKey();
+            if (apiKey === undefined || apiKey.length === 0) {
+                throw new LlmError('dshopencodego: no credential resolved for the opencode-go route', 'MISSING_CREDENTIAL');
+            }
+            const reasoning = this.resolveReasoningLevel(model, options.reasoningEffort);
+            const consumer = new AbortController();
+            const upstream = options.signal === undefined ? consumer.signal : AbortSignal.any([options.signal, consumer.signal]);
+            const watchdog = __addDisposableResource(env_1, idleWatchdog(upstream, config.streamIdleTimeoutMs, 'LLM_STREAM_IDLE_TIMEOUT'), false);
+            try {
+                const containsImage = options.messages.some(message => contentHasImage(message.content));
+                if (containsImage && !model.input.includes('image')) {
+                    throw new LlmError(`opencode-go model "${model.id}" does not support image input`, 'UNSUPPORTED_CONTENT');
+                }
+                let imageRequest;
+                if (containsImage) {
+                    const access = this.options.imageAccess;
+                    const store = access?.resolveAttachments();
+                    if (access === undefined || store === undefined) {
+                        throw new LlmError('dshopencodego image input requires the durable attachment service', 'UNSUPPORTED_CONTENT');
+                    }
+                    imageRequest = {
+                        attachments: store,
+                        resolveImageAccess: ref => access.resolveImageAccess(store, ref),
+                        maxRequestImageBytes: config.maxRequestImageBytes,
+                        requestImagePolicy: { maxPixels: config.requestImagePixelBudget, maxBytes: config.requestImageMaxBytes },
+                    };
+                }
+                const context = imageRequest === undefined
+                    ? await toPiContext(options, undefined, this.options.onReplayDegrade)
+                    : await toPiContext({ ...options, signal: watchdog.signal }, imageRequest, this.options.onReplayDegrade);
+                const events = snapshot.provider.streamSimple(model, normalizeContext(context), {
+                    apiKey,
+                    ...reasoning === undefined || reasoning === 'off' ? {} : { reasoning },
+                    ...options.temperature === undefined ? {} : { temperature: options.temperature },
+                    ...maxTokens === undefined ? {} : { maxTokens },
+                    ...options.sessionId === undefined ? {} : { sessionId: String(options.sessionId) },
+                    signal: watchdog.signal,
+                    // The gateway refuses a request without `x-opencode-session`; the
+                    // attribution user-agent rides along on the same object.
+                    headers: providerHeaders(options.sessionId === undefined ? undefined : String(options.sessionId)),
+                    // The agent recovery layer owns visible attempts; one adapter call is
+                    // one SDK attempt.
+                    maxRetries: 0,
+                });
+                const iterator = toStreamChunks(events, model.contextWindow, options.signal, model.id)[Symbol.asyncIterator]();
+                let exhausted = false;
+                try {
+                    while (true) {
+                        const result = await watchdog.next(iterator);
+                        if (timeoutOf(watchdog.signal, 'LLM_STREAM_IDLE_TIMEOUT') !== undefined) {
+                            throw new LlmError('opencode-go stream idle timeout', 'TIMEOUT');
+                        }
+                        if (result.done) {
+                            exhausted = true;
+                            return;
+                        }
+                        if (result.value.type === 'usage') {
+                            this.options.onUsage?.({ model: options.model, usage: result.value.usage });
+                        }
+                        yield result.value;
+                    }
+                }
+                finally {
+                    if (!exhausted) {
+                        consumer.abort('opencode-go stream consumer stopped');
+                        try {
+                            await iterator.return(undefined);
+                        }
+                        catch (_abortedSdkTeardown) {
+                            // The stable signal already owns SDK termination.
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                if (timeoutOf(watchdog.signal, 'LLM_STREAM_IDLE_TIMEOUT') !== undefined) {
+                    throw new LlmError('opencode-go stream idle timeout', 'TIMEOUT', { cause: error });
+                }
+                if (options.signal?.aborted) {
+                    throw new LlmError('opencode-go request aborted by caller', 'ABORTED', { cause: error });
+                }
+                throw error;
+            }
+            finally {
+                consumer.abort('opencode-go stream consumer stopped');
+            }
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+}
+/** Re-exported so a composition can assert the attribution contract in one place. */
+export { attributionHeaders };

package/lib/types/catalog/constants.d.ts

@@ -0,0 +1,16 @@
+/** Shared identities and endpoints for the OpenCode Go route. */
+/** DSH provider route this plugin owns. */
+export declare const PROVIDER_ID = "opencode-go";
+/** Selector label for the route. */
+export declare const DISPLAY_NAME = "OpenCode Go";
+/** Gateway base URL; `/models` and `/usage` hang off it. */
+export declare const DEFAULT_BASE_URL = "https://opencode.ai/zen/go/v1";
+/** Online model metadata: capability, lifecycle, and pricing per model id. */
+export declare const MODEL_METADATA_URL = "https://models.dev/api.json";
+/** The models.dev provider key this plugin reads. */
+export declare const MODEL_METADATA_PROVIDER = "opencode-go";
+/** Timeout for the two metadata GETs. */
+export declare const METADATA_FETCH_TIMEOUT_MS = 10000;
+/** Response caps: the listing is tiny, the metadata document is not. */
+export declare const MODEL_LISTING_MAX_BYTES: number;
+export declare const MODEL_METADATA_MAX_BYTES: number;

package/lib/types/catalog/constants.js

@@ -0,0 +1,16 @@
+/** Shared identities and endpoints for the OpenCode Go route. */
+/** DSH provider route this plugin owns. */
+export const PROVIDER_ID = 'opencode-go';
+/** Selector label for the route. */
+export const DISPLAY_NAME = 'OpenCode Go';
+/** Gateway base URL; `/models` and `/usage` hang off it. */
+export const DEFAULT_BASE_URL = 'https://opencode.ai/zen/go/v1';
+/** Online model metadata: capability, lifecycle, and pricing per model id. */
+export const MODEL_METADATA_URL = 'https://models.dev/api.json';
+/** The models.dev provider key this plugin reads. */
+export const MODEL_METADATA_PROVIDER = 'opencode-go';
+/** Timeout for the two metadata GETs. */
+export const METADATA_FETCH_TIMEOUT_MS = 10_000;
+/** Response caps: the listing is tiny, the metadata document is not. */
+export const MODEL_LISTING_MAX_BYTES = 1024 * 1024;
+export const MODEL_METADATA_MAX_BYTES = 16 * 1024 * 1024;

package/lib/types/catalog/contract.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Wire contract for the catalog Remote.
+ *
+ * `read` serves the cached snapshot; `refresh` revalidates both sources first.
+ * The distinction is the whole point of the settings page's refresh button: the
+ * runtime TTL exists so sessions do not re-fetch on every request, and a human
+ * asking "what does the gateway serve right now" must not be answered from
+ * that cache.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/contract
+ */
+import type { RemoteResult, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+import type { CatalogReading } from './reading.ts';
+export type { CatalogReading } from './reading.ts';
+/** Validate a catalog reading crossing the wire. */
+export declare function parseCatalogReading(value: unknown): CatalogReading;
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface TypertRemoteNamespaceMap {
+        opencodeGoCatalog: {
+            read(): Promise<RemoteResult<CatalogReading>>;
+            refresh(): Promise<RemoteResult<CatalogReading>>;
+        };
+    }
+}
+/** Remote methods the catalog owns. */
+export declare const catalogRemote: TypertRemoteContribution;

package/lib/types/catalog/contract.js

@@ -0,0 +1,131 @@
+/**
+ * Wire contract for the catalog Remote.
+ *
+ * `read` serves the cached snapshot; `refresh` revalidates both sources first.
+ * The distinction is the whole point of the settings page's refresh button: the
+ * runtime TTL exists so sessions do not re-fetch on every request, and a human
+ * asking "what does the gateway serve right now" must not be answered from
+ * that cache.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/contract
+ */
+function parseGoQuota(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid go quota');
+    const row = value;
+    const usd = row['monthlyUsd'];
+    if (usd !== 'unlimited' && (typeof usd !== 'number' || !Number.isFinite(usd))) {
+        throw new Error('invalid go quota monthlyUsd');
+    }
+    const requests = row['monthlyRequests'];
+    if (requests !== undefined && requests !== 'unlimited'
+        && (typeof requests !== 'number' || !Number.isFinite(requests))) {
+        throw new Error('invalid go quota monthlyRequests');
+    }
+    return {
+        monthlyUsd: usd,
+        ...requests === undefined ? {} : { monthlyRequests: requests },
+    };
+}
+function parseCost(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid model cost');
+    const row = value;
+    const rate = (key) => {
+        const entry = row[key];
+        if (typeof entry !== 'number' || !Number.isFinite(entry) || entry < 0)
+            throw new Error(`invalid model cost "${key}"`);
+        return entry;
+    };
+    return {
+        input: rate('input'),
+        output: rate('output'),
+        ...typeof row['cacheRead'] === 'number' ? { cacheRead: rate('cacheRead') } : {},
+        ...typeof row['cacheWrite'] === 'number' ? { cacheWrite: rate('cacheWrite') } : {},
+    };
+}
+function parseModel(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid catalog model');
+    const row = value;
+    if (typeof row['id'] !== 'string' || row['id'].length === 0)
+        throw new Error('invalid catalog model id');
+    return {
+        id: row['id'],
+        name: typeof row['name'] === 'string' ? row['name'] : row['id'],
+        ...typeof row['contextWindow'] === 'number' ? { contextWindow: row['contextWindow'] } : {},
+        ...typeof row['maxInputTokens'] === 'number' ? { maxInputTokens: row['maxInputTokens'] } : {},
+        ...typeof row['maxTokens'] === 'number' ? { maxTokens: row['maxTokens'] } : {},
+        ...typeof row['deprecated'] === 'boolean' ? { deprecated: row['deprecated'] } : {},
+        ...typeof row['releaseDate'] === 'string' ? { releaseDate: row['releaseDate'] } : {},
+        ...row['goQuota'] === undefined ? {} : { goQuota: parseGoQuota(row['goQuota']) },
+        ...row['cost'] === undefined ? {} : { cost: parseCost(row['cost']) },
+        ...row['protocolSource'] === 'builtin' || row['protocolSource'] === 'online'
+            || row['protocolSource'] === 'inferred' || row['protocolSource'] === 'override'
+            ? { protocolSource: row['protocolSource'] } : {},
+        ...typeof row['assumedLimits'] === 'boolean' ? { assumedLimits: row['assumedLimits'] } : {},
+        ...typeof row['configurationMissing'] === 'string' ? { configurationMissing: row['configurationMissing'] } : {},
+    };
+}
+/** Validate a catalog reading crossing the wire. */
+export function parseCatalogReading(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid catalog reading');
+    const row = value;
+    const counts = row['counts'];
+    if (!Array.isArray(row['models']) || typeof row['stale'] !== 'boolean'
+        || typeof row['fetchedAtMs'] !== 'number' || counts === null || typeof counts !== 'object') {
+        throw new Error('invalid catalog reading');
+    }
+    const numbers = counts;
+    const count = (key) => {
+        const entry = numbers[key];
+        if (typeof entry !== 'number' || !Number.isFinite(entry) || entry < 0)
+            throw new Error(`invalid catalog count "${key}"`);
+        return entry;
+    };
+    return {
+        models: row['models'].map(parseModel),
+        stale: row['stale'],
+        ...typeof row['error'] === 'string' ? { error: row['error'] } : {},
+        fetchedAtMs: row['fetchedAtMs'],
+        counts: {
+            total: count('total'),
+            enabled: count('enabled'),
+            deprecated: count('deprecated'),
+            unconfigured: count('unconfigured'),
+            inferred: count('inferred'),
+        },
+    };
+}
+/** Codec shape accepted by both released and source DSH builds. */
+const codec = {
+    mode: 'strict',
+    typeSymbol: '@dan-ai-studio/dshopencodego#CatalogReading',
+    schema: { parse: parseCatalogReading },
+    create: () => ({ parse: parseCatalogReading }),
+};
+/** Remote methods the catalog owns. */
+export const catalogRemote = {
+    package: '@dan-ai-studio/dshopencodego',
+    descriptors: [
+        {
+            id: '@dan-ai-studio/dshopencodego#opencodeGoCatalog/read',
+            service: 'opencodeGoCatalog',
+            namespace: 'opencodeGoCatalog',
+            method: 'read',
+            invocation: { kind: 'direct' },
+            parameters: [],
+            result: codec,
+        },
+        {
+            id: '@dan-ai-studio/dshopencodego#opencodeGoCatalog/refresh',
+            service: 'opencodeGoCatalog',
+            namespace: 'opencodeGoCatalog',
+            method: 'refresh',
+            invocation: { kind: 'direct' },
+            parameters: [],
+            result: codec,
+        },
+    ],
+};

package/lib/types/catalog/gateway.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The gateway model listing: which ids the subscription can call right now.
+ *
+ * The endpoint answers an OpenAI-shaped `{ object: 'list', data: [{ id, … }] }`
+ * with no capability information at all, so it decides *membership* and nothing
+ * else. A malformed reply is a failure (never "the gateway serves nothing").
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/gateway
+ */
+/** Read the ids out of a model-listing body. */
+export declare function readModelIds(body: unknown): readonly string[];
+/**
+ * Fetch the ids the gateway currently advertises.
+ * @param baseURL - normalized gateway base without a trailing slash.
+ * @param signal - caller cancellation, if any.
+ * @returns the advertised ids in endpoint order, deduplicated.
+ * @throws {LlmError} `DISCOVERY_FAILED` when the endpoint is unreachable, not
+ *   OK, or does not answer a model listing.
+ */
+export declare function fetchModelIds(baseURL: string, signal?: AbortSignal): Promise<readonly string[]>;

package/lib/types/catalog/gateway.js

@@ -0,0 +1,59 @@
+/**
+ * The gateway model listing: which ids the subscription can call right now.
+ *
+ * The endpoint answers an OpenAI-shaped `{ object: 'list', data: [{ id, … }] }`
+ * with no capability information at all, so it decides *membership* and nothing
+ * else. A malformed reply is a failure (never "the gateway serves nothing").
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/gateway
+ */
+import { attributionHeaders, LlmError } from '@deepseek-ai/dsh-llm';
+import { MODEL_LISTING_MAX_BYTES, METADATA_FETCH_TIMEOUT_MS } from "./constants.js";
+import { readBoundedJson } from "./json-response.js";
+/** Read the ids out of a model-listing body. */
+export function readModelIds(body) {
+    const data = body?.data;
+    if (!Array.isArray(data))
+        throw new Error('the model listing has no "data" array');
+    const ids = [];
+    for (const entry of data) {
+        const id = entry?.id;
+        if (typeof id === 'string' && id.length > 0)
+            ids.push(id);
+    }
+    return [...new Set(ids)];
+}
+/**
+ * Fetch the ids the gateway currently advertises.
+ * @param baseURL - normalized gateway base without a trailing slash.
+ * @param signal - caller cancellation, if any.
+ * @returns the advertised ids in endpoint order, deduplicated.
+ * @throws {LlmError} `DISCOVERY_FAILED` when the endpoint is unreachable, not
+ *   OK, or does not answer a model listing.
+ */
+export async function fetchModelIds(baseURL, signal) {
+    const url = `${baseURL.replace(/\/+$/, '')}/models`;
+    const timeout = AbortSignal.timeout(METADATA_FETCH_TIMEOUT_MS);
+    const response = await fetch(url, {
+        method: 'GET',
+        redirect: 'error',
+        // An explicit request header rather than `RequestInit.cache`: Node's fetch
+        // does not implement HTTP caching, and the header is what any intermediary
+        // in front of the gateway reads.
+        headers: { ...attributionHeaders(), accept: 'application/json', 'cache-control': 'no-cache' },
+        signal: signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
+    }).catch((error) => {
+        throw new LlmError(`could not reach ${url}`, 'DISCOVERY_FAILED', { cause: error });
+    });
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new LlmError(`${url} answered HTTP ${response.status}`, 'DISCOVERY_FAILED');
+    }
+    const body = await readBoundedJson(response, url, MODEL_LISTING_MAX_BYTES);
+    try {
+        return readModelIds(body);
+    }
+    catch (error) {
+        throw new LlmError(`${url} returned an invalid model listing`, 'DISCOVERY_FAILED', { cause: error });
+    }
+}