@dan-ai-studio/dshopencodego 0.1.5

package/lib/types/catalog/metadata.js

@@ -0,0 +1,259 @@
+/**
+ * Online model metadata: how to call each advertised model.
+ *
+ * models.dev is the only source that knows about a model the day it ships, so
+ * it supplies names, capacities, modalities, pricing, lifecycle, and the
+ * protocol hint. The installed pi-ai catalog still wins where it knows the
+ * exact id, because its entries carry the wire quirks (`thinkingFormat`,
+ * reasoning-content replay, affinity format) that a generic metadata document
+ * cannot express.
+ *
+ * Every field degrades independently: a model missing a capacity falls back to
+ * the installed entry, then to the route default, and is flagged `assumedLimits`
+ * so the settings surface can say so instead of presenting a guess as a fact.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/metadata
+ */
+import { asWireProtocol, decideProtocol, protocolOfNpm } from "./protocol.js";
+import { MODEL_METADATA_PROVIDER } from "./constants.js";
+const LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : {};
+}
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/** A calendar date models.dev states without a timezone. */
+function validReleaseDate(value) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return undefined;
+    return Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value ? value : undefined;
+}
+function rates(value) {
+    const cost = record(value);
+    const rate = (key) => {
+        const entry = cost[key];
+        return typeof entry === 'number' && Number.isFinite(entry) && entry >= 0 ? entry : 0;
+    };
+    return { input: rate('input'), output: rate('output'), cacheRead: rate('cache_read'), cacheWrite: rate('cache_write') };
+}
+/**
+ * Reasoning levels a model actually offers.
+ *
+ * An absent `reasoning_options` list is not "no levels": it means the document
+ * does not describe them, so an installed entry's map is kept when there is
+ * one. Levels the model does not offer stay `null`, which is what stops the
+ * seam from offering a control the provider would ignore.
+ */
+function thinkingLevels(metadata, known) {
+    const options = metadata['reasoning_options'];
+    if (!Array.isArray(options))
+        return known?.thinkingLevelMap;
+    const map = Object.fromEntries(LEVELS.map(level => [level, null]));
+    for (const item of options) {
+        const option = record(item);
+        if (option['type'] === 'toggle' || option['type'] === 'budget_tokens') {
+            map.off = 'off';
+            map.high = 'high';
+        }
+        if (option['type'] !== 'effort' || !Array.isArray(option['values']))
+            continue;
+        for (const value of option['values']) {
+            const level = value === 'none' ? 'off' : value;
+            if (typeof level === 'string' && LEVELS.includes(level)) {
+                map[level] = String(value);
+            }
+        }
+    }
+    // An established transport may support disabling thinking on top of the
+    // advertised effort levels (DeepSeek's separate thinking flag, for example).
+    if (known?.reasoning === true && known.thinkingLevelMap?.off !== null) {
+        map.off ??= known.thinkingLevelMap?.off ?? 'off';
+    }
+    return map;
+}
+/**
+ * The closest installed entry in the same family, for inheriting wire quirks.
+ *
+ * models.dev's own `family` field is preferred when the document lists a
+ * sibling the installed catalog knows. When it does not — the common case for a
+ * model that just shipped — the longest shared id prefix stands in, which is
+ * how `deepseek-v4.1-flash` inherits `deepseek-v4-flash`'s thinking format.
+ * A shared prefix shorter than three characters is treated as no evidence.
+ */
+function familySibling(id, api, documentFamily, entries, builtin) {
+    if (documentFamily !== undefined) {
+        for (const [other, value] of Object.entries(entries)) {
+            if (other === id || record(value)['family'] !== documentFamily)
+                continue;
+            const candidate = builtin.get(other);
+            if (candidate !== undefined && candidate.api === api)
+                return candidate;
+        }
+    }
+    let best;
+    const lower = id.toLowerCase();
+    for (const [other, candidate] of builtin) {
+        if (other === id || candidate.api !== api)
+            continue;
+        const score = commonPrefixLength(lower, other.toLowerCase());
+        if (score < 3)
+            continue;
+        if (best === undefined || score > best.score)
+            best = { model: candidate, score };
+    }
+    return best?.model;
+}
+function commonPrefixLength(left, right) {
+    let index = 0;
+    while (index < left.length && index < right.length && left[index] === right[index])
+        index += 1;
+    return index;
+}
+/**
+ * Wire quirks for one protocol.
+ *
+ * The installed entry's `compat` is authoritative when the protocol matches,
+ * including for a *family sibling*: a brand-new id in a family the catalog
+ * already serves inherits that family's quirks instead of starting from the
+ * generic defaults.
+ */
+function compatFor(api, metadata, exact, sibling) {
+    const inherited = exact !== undefined && exact.api === api
+        ? exact.compat
+        : sibling !== undefined && sibling.api === api ? sibling.compat : undefined;
+    if (api === 'openai-completions') {
+        return {
+            supportsStore: false,
+            supportsDeveloperRole: false,
+            maxTokensField: 'max_tokens',
+            ...(record(metadata['interleaved'])['field'] === 'reasoning_content'
+                ? { requiresReasoningContentOnAssistantMessages: true }
+                : {}),
+            ...inherited,
+        };
+    }
+    if (api === 'openai-responses') {
+        return { sessionAffinityFormat: 'openai-nosession', ...inherited };
+    }
+    return inherited ?? {};
+}
+/** The base URL one protocol's SDK expects for this gateway. */
+export function modelBaseURL(api, baseURL) {
+    const base = baseURL.replace(/\/+$/, '');
+    // The Anthropic SDK appends `/v1/messages`; the OpenAI SDKs append paths
+    // below `/v1`, which the configured base already carries.
+    return api === 'anthropic-messages' ? base.replace(/\/v1$/, '') : base;
+}
+/**
+ * Parse the `opencode-go` record of a models.dev document.
+ * @param body - the whole models.dev document.
+ * @param sources - installed entries, defaults, and configured overrides.
+ * @returns per-id facts and per-id parse failures; a bad entry never discards
+ *   the rest of the document.
+ * @throws {Error} when the document has no usable `opencode-go` models object.
+ */
+export function readOnlineMetadata(body, sources) {
+    const provider = record(record(body)[MODEL_METADATA_PROVIDER]);
+    const rawModels = provider['models'];
+    if (rawModels === null || typeof rawModels !== 'object' || Array.isArray(rawModels)) {
+        throw new Error(`models.dev has no ${MODEL_METADATA_PROVIDER} models object`);
+    }
+    const providerNpm = provider['npm'];
+    const entries = record(rawModels);
+    const models = new Map();
+    const errors = new Map();
+    for (const [id, value] of Object.entries(entries)) {
+        const metadata = record(value);
+        try {
+            const exact = sources.builtin.get(id);
+            const override = asWireProtocol(sources.overrides[id]);
+            if (sources.overrides[id] !== undefined && override === undefined) {
+                throw new Error(`configured protocol "${sources.overrides[id]}" is not one of anthropic-messages, openai-completions, openai-responses`);
+            }
+            const decision = decideProtocol(id, {
+                ...exact?.api === undefined ? {} : { builtin: exact.api },
+                ...protocolOfNpm(metadata['provider'] === undefined ? providerNpm : record(metadata['provider'])['npm'] ?? providerNpm) === undefined
+                    ? {}
+                    : { online: protocolOfNpm(record(metadata['provider'])['npm'] ?? providerNpm) },
+                ...override === undefined ? {} : { override },
+            });
+            if (decision === undefined)
+                throw new Error('no protocol could be decided');
+            const api = decision.api;
+            const limit = record(metadata['limit']);
+            const onlineContext = positiveInteger(limit['context']);
+            const onlineInputLimit = positiveInteger(limit['input']);
+            const onlineOutput = positiveInteger(limit['output']);
+            const builtinContext = exact?.api === api ? positiveInteger(exact.contextWindow) : undefined;
+            const builtinOutput = exact?.api === api ? positiveInteger(exact.maxTokens) : undefined;
+            const contextWindow = onlineContext ?? builtinContext ?? sources.defaults.contextWindow;
+            const maxTokens = onlineOutput ?? builtinOutput ?? sources.defaults.maxTokens;
+            const onlineInput = record(metadata['modalities'])['input'];
+            const input = Array.isArray(onlineInput) && onlineInput.includes('text')
+                ? (onlineInput.includes('image') ? ['text', 'image'] : ['text'])
+                : exact?.api === api ? exact.input : sources.defaults.input;
+            const reasoning = typeof metadata['reasoning'] === 'boolean'
+                ? metadata['reasoning']
+                : exact?.api === api ? exact.reasoning : false;
+            const family = nonEmptyString(metadata['family']);
+            const sibling = familySibling(id, api, family, entries, sources.builtin);
+            const cost = rates(metadata['cost']);
+            const tiers = record(metadata['cost'])['tiers'];
+            if (Array.isArray(tiers)) {
+                const parsed = tiers.flatMap((item) => {
+                    const tier = record(record(item)['tier']);
+                    const size = positiveInteger(tier['size']);
+                    return tier['type'] === 'context' && size !== undefined
+                        ? [{ ...rates(item), inputTokensAbove: size }]
+                        : [];
+                }).sort((a, b) => a.inputTokensAbove - b.inputTokensAbove);
+                if (parsed.length > 0)
+                    cost.tiers = parsed;
+            }
+            models.set(id, {
+                id,
+                name: nonEmptyString(metadata['name']) ?? id,
+                api,
+                protocolSource: decision.source,
+                contextWindow,
+                maxInputTokens: onlineInputLimit,
+                maxTokens,
+                assumedLimits: onlineContext === undefined && builtinContext === undefined
+                    || onlineOutput === undefined && builtinOutput === undefined,
+                input,
+                reasoning,
+                thinkingLevelMap: reasoning ? thinkingLevels(metadata, exact?.api === api ? exact : sibling) : undefined,
+                compat: compatFor(api, metadata, exact, sibling),
+                cost,
+                deprecated: metadata['status'] === 'deprecated',
+                releaseDate: validReleaseDate(metadata['release_date']),
+            });
+        }
+        catch (error) {
+            errors.set(id, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return { models, errors };
+}
+/** Project one parsed model into the shape pi-ai's providers consume. */
+export function toPiModel(facts, baseURL) {
+    return {
+        id: facts.id,
+        name: facts.name,
+        provider: 'opencode-go',
+        api: facts.api,
+        baseUrl: modelBaseURL(facts.api, baseURL),
+        reasoning: facts.reasoning,
+        ...facts.thinkingLevelMap === undefined ? {} : { thinkingLevelMap: facts.thinkingLevelMap },
+        input: [...facts.input],
+        contextWindow: facts.contextWindow,
+        maxTokens: facts.maxTokens,
+        cost: facts.cost,
+        compat: facts.compat,
+    };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Wire-protocol vocabulary and the inference ladder.
+ *
+ * The gateway is a multi-protocol front door: the same base URL answers
+ * `chat/completions`, `responses`, and `messages`, and each model speaks
+ * exactly one of them. Four evidence levels decide which, first hit wins:
+ *
+ * 1. the installed pi-ai catalog entry for that exact id (protocol *and* the
+ *    wire quirks in its `compat`);
+ * 2. models.dev's per-model `provider.npm`, which names the AI SDK package the
+ *    OpenCode Go console itself uses;
+ * 3. a family rule, for ids neither source describes;
+ * 4. an explicit configuration override, which always wins.
+ *
+ * Measured 2026-09-24: of the 12 gateway ids pi-ai 0.87.1 does not know, 10 are
+ * fully described by models.dev and 2 (`deepseek-flash`, `hy3-preview`) are
+ * absent from it — the family rule exists for those two and for any future id
+ * that lands the same way, not to rescue a large set.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/protocol
+ */
+import type { Api } from '@earendil-works/pi-ai';
+/** The three wire protocols the OpenCode Go gateway serves. */
+export type WireProtocol = 'anthropic-messages' | 'openai-completions' | 'openai-responses';
+/** Every protocol this plugin can drive, in catalog order. */
+export declare const WIRE_PROTOCOLS: readonly WireProtocol[];
+/** Which evidence level produced a protocol decision. */
+export type ProtocolSource = 'builtin' | 'online' | 'inferred' | 'override';
+/** One model's protocol decision with the evidence that produced it. */
+export interface ProtocolDecision {
+    readonly api: WireProtocol;
+    readonly source: ProtocolSource;
+}
+/** The protocol a models.dev `npm` field names, when it names one. */
+export declare function protocolOfNpm(npm: unknown): WireProtocol | undefined;
+/**
+ * The family rule for one id: the Responses families by prefix, everything else
+ * over Chat Completions, which is what the gateway's provider-level default
+ * (`@ai-sdk/openai-compatible`) implies for an id no per-model record covers.
+ * @param id - the gateway model id.
+ * @returns the inferred protocol; the caller records it as `inferred`.
+ */
+export declare function inferProtocol(id: string): WireProtocol;
+/** Narrow an arbitrary configured string to a protocol this plugin can drive. */
+export declare function asWireProtocol(value: string | undefined): WireProtocol | undefined;
+/** One model's evidence, as gathered from the three automatic sources. */
+export interface ProtocolEvidence {
+    /** Protocol the installed pi-ai catalog declares for this exact id. */
+    readonly builtin?: WireProtocol;
+    /** Protocol models.dev names for this model, or its provider-level default. */
+    readonly online?: WireProtocol;
+    /** The configured override for this id, if any. */
+    readonly override?: WireProtocol;
+}
+/**
+ * Walk the ladder for one model.
+ * @param id - the gateway model id, used only by the family rule.
+ * @param evidence - what the automatic sources and configuration say.
+ * @returns the decision, or `undefined` when the override names a protocol this
+ *   build cannot drive (the caller reports that as a configuration error rather
+ *   than silently falling back to a guess).
+ */
+export declare function decideProtocol(id: string, evidence: ProtocolEvidence): ProtocolDecision | undefined;
+/** The pi-ai API string for one wire protocol. */
+export declare function piApiOf(api: WireProtocol): Api;

package/lib/types/catalog/protocol.js

@@ -0,0 +1,87 @@
+/**
+ * Wire-protocol vocabulary and the inference ladder.
+ *
+ * The gateway is a multi-protocol front door: the same base URL answers
+ * `chat/completions`, `responses`, and `messages`, and each model speaks
+ * exactly one of them. Four evidence levels decide which, first hit wins:
+ *
+ * 1. the installed pi-ai catalog entry for that exact id (protocol *and* the
+ *    wire quirks in its `compat`);
+ * 2. models.dev's per-model `provider.npm`, which names the AI SDK package the
+ *    OpenCode Go console itself uses;
+ * 3. a family rule, for ids neither source describes;
+ * 4. an explicit configuration override, which always wins.
+ *
+ * Measured 2026-09-24: of the 12 gateway ids pi-ai 0.87.1 does not know, 10 are
+ * fully described by models.dev and 2 (`deepseek-flash`, `hy3-preview`) are
+ * absent from it — the family rule exists for those two and for any future id
+ * that lands the same way, not to rescue a large set.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/protocol
+ */
+/** Every protocol this plugin can drive, in catalog order. */
+export const WIRE_PROTOCOLS = [
+    'anthropic-messages',
+    'openai-completions',
+    'openai-responses',
+];
+/** The AI SDK package names models.dev uses to name a model's protocol. */
+const NPM_PROTOCOLS = {
+    '@ai-sdk/anthropic': 'anthropic-messages',
+    '@ai-sdk/openai': 'openai-responses',
+    '@ai-sdk/openai-compatible': 'openai-completions',
+};
+/**
+ * Families whose models are served over the OpenAI Responses API.
+ *
+ * Only families where every known member agrees are listed. Qwen and MiniMax
+ * are deliberately absent: the installed catalog serves `qwen3.8-flash` and
+ * `minimax-m3` over Anthropic Messages while serving `qwen3.6-plus`,
+ * `qwen3.7-*`, `qwen3.8-max`, and `minimax-m2.7` over Chat Completions, so a
+ * family rule would be wrong about half of them.
+ */
+const RESPONSES_FAMILIES = ['grok', 'gpt', 'muse'];
+/** The protocol a models.dev `npm` field names, when it names one. */
+export function protocolOfNpm(npm) {
+    return typeof npm === 'string' ? NPM_PROTOCOLS[npm] : undefined;
+}
+/**
+ * The family rule for one id: the Responses families by prefix, everything else
+ * over Chat Completions, which is what the gateway's provider-level default
+ * (`@ai-sdk/openai-compatible`) implies for an id no per-model record covers.
+ * @param id - the gateway model id.
+ * @returns the inferred protocol; the caller records it as `inferred`.
+ */
+export function inferProtocol(id) {
+    const lower = id.toLowerCase();
+    return RESPONSES_FAMILIES.some(family => lower.startsWith(family))
+        ? 'openai-responses'
+        : 'openai-completions';
+}
+/** Narrow an arbitrary configured string to a protocol this plugin can drive. */
+export function asWireProtocol(value) {
+    return value !== undefined && WIRE_PROTOCOLS.includes(value)
+        ? value
+        : undefined;
+}
+/**
+ * Walk the ladder for one model.
+ * @param id - the gateway model id, used only by the family rule.
+ * @param evidence - what the automatic sources and configuration say.
+ * @returns the decision, or `undefined` when the override names a protocol this
+ *   build cannot drive (the caller reports that as a configuration error rather
+ *   than silently falling back to a guess).
+ */
+export function decideProtocol(id, evidence) {
+    if (evidence.override !== undefined)
+        return { api: evidence.override, source: 'override' };
+    if (evidence.builtin !== undefined)
+        return { api: evidence.builtin, source: 'builtin' };
+    if (evidence.online !== undefined)
+        return { api: evidence.online, source: 'online' };
+    return { api: inferProtocol(id), source: 'inferred' };
+}
+/** The pi-ai API string for one wire protocol. */
+export function piApiOf(api) {
+    return api;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The settings-facing reading of the catalog.
+ *
+ * The settings page needs more than the picker's model list: it needs to say
+ * which models the gateway advertises, which of them this build cannot
+ * configure, how each protocol was decided, and whether the reading is stale
+ * because a refresh failed. That projection lives here as a pure function so it
+ * can be asserted without a Cordis context.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/reading
+ */
+import type { ModelSummary } from '../models.ts';
+import type { CatalogSnapshot } from './index.ts';
+/** One settings-page reading of the catalog. */
+export interface CatalogReading {
+    /** Every advertised model, new first, deprecated last. */
+    readonly models: readonly ModelSummary[];
+    /** True when the gateway listing failed and this is the last known set. */
+    readonly stale: boolean;
+    /** Why the reading is stale, when it is. */
+    readonly error?: string;
+    /** When the underlying snapshot was built. */
+    readonly fetchedAtMs: number;
+    /** Counts the settings page shows without walking the list again. */
+    readonly counts: {
+        readonly total: number;
+        readonly enabled: number;
+        readonly deprecated: number;
+        readonly unconfigured: number;
+        readonly inferred: number;
+    };
+}
+/**
+ * Project one snapshot for the settings page.
+ * @param snapshot - the catalog snapshot, live or retained.
+ * @param visibility - per-model switches; absent entries keep the default.
+ * @param listingFailure - the failure message when the listing failed.
+ * @returns the reading, with unconfigurable ids kept visible so the page can
+ *   explain them instead of hiding them.
+ */
+export declare function catalogReading(snapshot: CatalogSnapshot, visibility: Readonly<Record<string, boolean>>, listingFailure?: string): CatalogReading;

package/lib/types/catalog/reading.js

@@ -0,0 +1,68 @@
+/**
+ * The settings-facing reading of the catalog.
+ *
+ * The settings page needs more than the picker's model list: it needs to say
+ * which models the gateway advertises, which of them this build cannot
+ * configure, how each protocol was decided, and whether the reading is stale
+ * because a refresh failed. That projection lives here as a pure function so it
+ * can be asserted without a Cordis context.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/reading
+ */
+import { isModelEnabled, recommendedIds, sortModels } from "../models.js";
+import { goQuotaFor } from "../go-limits.js";
+/**
+ * Project one snapshot for the settings page.
+ * @param snapshot - the catalog snapshot, live or retained.
+ * @param visibility - per-model switches; absent entries keep the default.
+ * @param listingFailure - the failure message when the listing failed.
+ * @returns the reading, with unconfigurable ids kept visible so the page can
+ *   explain them instead of hiding them.
+ */
+export function catalogReading(snapshot, visibility, listingFailure) {
+    const rows = [
+        ...[...snapshot.facts.values()].map(fact => {
+            const quota = goQuotaFor(fact.id);
+            const priced = fact.cost.input > 0 || fact.cost.output > 0;
+            return {
+                id: fact.id,
+                name: fact.name,
+                contextWindow: fact.contextWindow,
+                maxTokens: fact.maxTokens,
+                ...fact.maxInputTokens === undefined ? {} : { maxInputTokens: fact.maxInputTokens },
+                deprecated: fact.deprecated,
+                ...fact.releaseDate === undefined ? {} : { releaseDate: fact.releaseDate },
+                ...quota === undefined ? {} : { goQuota: quota },
+                ...!priced ? {} : {
+                    cost: {
+                        input: fact.cost.input,
+                        output: fact.cost.output,
+                        cacheRead: fact.cost.cacheRead,
+                        cacheWrite: fact.cost.cacheWrite,
+                    },
+                },
+                protocolSource: fact.protocolSource,
+                assumedLimits: fact.assumedLimits,
+            };
+        }),
+        ...[...snapshot.unavailable].map(([id, reason]) => ({ id, name: id, configurationMissing: reason })),
+    ];
+    // Nobody configured switches? Then the default configuration keeps the top
+    // few by published monthly estimate, and every row carries that default.
+    const recommended = recommendedIds(rows);
+    const models = rows.map(row => ({ ...row, recommended: recommended.has(row.id) }));
+    const enabled = models.filter(model => isModelEnabled(model, visibility)).length;
+    return {
+        models: sortModels(models),
+        stale: !snapshot.live,
+        ...!snapshot.live && listingFailure !== undefined ? { error: listingFailure } : {},
+        fetchedAtMs: snapshot.fetchedAtMs,
+        counts: {
+            total: models.length,
+            enabled,
+            deprecated: models.filter(model => model.deprecated === true).length,
+            unconfigured: models.filter(model => model.configurationMissing !== undefined).length,
+            inferred: models.filter(model => model.protocolSource === 'inferred').length,
+        },
+    };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Host half of the catalog Remote.
+ *
+ * Both methods return the same projection; they differ only in whether the
+ * cache may answer. `refresh` is what the settings page's button calls, and it
+ * revalidates the gateway listing and the online metadata before projecting.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { OpencodeGoCatalog } from './index.ts';
+import type { CatalogReading } from './reading.ts';
+/** Host inputs for the catalog service. */
+export interface CatalogServiceOptions {
+    /** The route's current catalog resolver. */
+    readonly catalog: () => OpencodeGoCatalog;
+    /** Current per-model visibility switches. */
+    readonly visibility: () => Readonly<Record<string, boolean>>;
+}
+/** Catalog Remote: what the gateway serves, and how each model is called. */
+export declare class OpencodeGoCatalogService extends TypertRemoteService {
+    private readonly options;
+    constructor(ctx: Context, options: CatalogServiceOptions);
+    /** The cached reading. */
+    read(): Promise<CatalogReading>;
+    /** Revalidate both sources, then read. */
+    refresh(): Promise<CatalogReading>;
+    private project;
+}
+/** The domain failure the settings page renders when a refresh cannot run. */
+export declare function catalogFailure(error: unknown): RemoteError;

package/lib/types/catalog/service.js

@@ -0,0 +1,45 @@
+/**
+ * Host half of the catalog Remote.
+ *
+ * Both methods return the same projection; they differ only in whether the
+ * cache may answer. `refresh` is what the settings page's button calls, and it
+ * revalidates the gateway listing and the online metadata before projecting.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/service
+ */
+import { RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { catalogReading } from "./reading.js";
+/** Catalog Remote: what the gateway serves, and how each model is called. */
+export class OpencodeGoCatalogService extends TypertRemoteService {
+    options;
+    constructor(ctx, options) {
+        super(ctx, 'opencodeGoCatalog');
+        this.options = options;
+    }
+    /** The cached reading. */
+    read() {
+        return this.project(false);
+    }
+    /** Revalidate both sources, then read. */
+    refresh() {
+        return this.project(true);
+    }
+    async project(force) {
+        const catalog = this.options.catalog();
+        const snapshot = await catalog.snapshot(force);
+        const failure = snapshot.listingFailure;
+        return catalogReading(snapshot, this.options.visibility(), failure === undefined
+            ? undefined
+            : failure instanceof LlmError || failure instanceof Error ? failure.message : String(failure));
+    }
+}
+/** The domain failure the settings page renders when a refresh cannot run. */
+export function catalogFailure(error) {
+    return new RemoteError('dshopencodego/usage-unavailable', error instanceof Error
+        ? error.message
+        : 'The OpenCode Go catalog is unavailable', {
+        retryable: true,
+        retainPrevious: true,
+    }, { cause: error });
+}