@dan-ai-studio/dshopencodego 0.1.5

package/lib/types/index.js

@@ -0,0 +1,195 @@
+/**
+ * The `dshopencodego` plugin: one `opencode-go` route with a live catalog and
+ * the gateway's mandatory session header.
+ *
+ * The plugin exists because a generic pi-ai route cannot express two things the
+ * OpenCode Go gateway needs: a model list that rotates faster than any shipped
+ * catalog, and a per-conversation `x-opencode-session` routing header on every
+ * inference request.
+ *
+ * Route registration is gated on both configuration and credential: a route
+ * whose key is missing would otherwise sit in every model picker and read as a
+ * usable provider to first-run onboarding. The gate re-evaluates on every
+ * credential write and every loader update, and a route another adapter already
+ * owns is reported rather than crashing the mount.
+ *
+ * ```yaml
+ * - id: dshopencodego
+ *   name: '@dan-ai-studio/dshopencodego'
+ *   config:
+ *     enabled: true                             # false withdraws the route only
+ *     apiKeyEnv: OPENCODE_GO_API_KEY             # default
+ *     baseURL: https://opencode.ai/zen/go/v1     # default
+ *     refreshMinutes: 60                         # live catalog TTL
+ *     modelProtocols:                            # last-resort protocol override
+ *       some-model: openai-responses
+ * ```
+ *
+ * @module @dan-ai-studio/dshopencodego
+ */
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import { launchEnvironmentOf } from '@deepseek-ai/dsh-launch-environment';
+import * as llm from '@deepseek-ai/dsh-llm';
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { OpencodeGoAdapter } from "./adapter.js";
+import { DISPLAY_NAME, PROVIDER_ID, discoverCatalogModels } from "./catalog/index.js";
+import { assertBaseURL, PlainConfig, readConfig } from "./config.js";
+import { registerRemotes } from "./remotes.js";
+import { OpencodeGoCatalogService } from "./catalog/service.js";
+import { OpencodeGoUsageService, UsageMeter } from "./usage/index.js";
+export { OpencodeGoAdapter } from "./adapter.js";
+export { DEFAULT_BASE_URL, DISPLAY_NAME, PROVIDER_ID, OpencodeGoCatalog, discoverCatalogModels } from "./catalog/index.js";
+export { Config, PlainConfig, assertBaseURL, DEFAULT_API_KEY_ENV } from "./config.js";
+export { SESSION_HEADER, opencodeSessionValue, providerHeaders } from "./session-header.js";
+export { isModelEnabled, sortModels } from "./models.js";
+export const name = 'dshopencodego';
+export const inject = ['llm'];
+/** True when a loader handed this plugin its live field references. */
+function isLiveConfig(raw) {
+    return typeof raw === 'object' && raw !== null && typeof raw.enabled === 'object'
+        && typeof (raw.enabled?.get) === 'function';
+}
+/**
+ * Register the route, its discovery, and their teardown for one mount.
+ *
+ * Configuration is read through a live source so a profile edit reaches the
+ * next request without a restart; the adapter re-reads it at every operation.
+ * @param ctx - the plugin's Cordis context.
+ * @param raw - the loader's live config, or a plain object in tests.
+ */
+export function apply(ctx, raw) {
+    const live = isLiveConfig(raw) ? raw : undefined;
+    const constant = live === undefined ? PlainConfig((raw ?? {})) : undefined;
+    const current = () => (live === undefined ? constant : readConfig(live));
+    assertBaseURL(current().baseURL);
+    /** Resolve the route credential; a named reference that misses fails loud. */
+    const resolveApiKey = async () => {
+        const ref = current().apiKeyEnv;
+        const credentials = ctx.get('credentials');
+        const hit = credentials !== undefined
+            ? (await credentials.resolve(credentialRef(ref)))?.value
+            // Without the credentials seam the process environment is the whole
+            // credential plane.
+            : launchEnvironmentOf(ctx).get(ref)?.value;
+        if (hit !== undefined && hit.length > 0)
+            return llm.assertUsableApiKey(hit, name, ref);
+        throw new LlmError(`dshopencodego: no credential; the profile resolves ${ref}, which is not set — store ${ref} through the`
+            + ' credentials service (the Web Models page writes it) or export it', 'MISSING_CREDENTIAL');
+    };
+    const meter = new UsageMeter();
+    const adapter = new OpencodeGoAdapter({
+        config: current,
+        resolveApiKey,
+        imageAccess: {
+            resolveAttachments: () => ctx.get('attachments'),
+            resolveImageAccess: (attachments, ref) => llm.resolveImageAttachmentAccess(attachments, hostPath => ctx.get('fs')?.processPathFromHostPath(hostPath), ref),
+        },
+        onFallback: ({ url, error }) => {
+            ctx.logger.warn(`dshopencodego: could not refresh ${url}; using the last known model data (${String(error)})`);
+        },
+        onUnconfigured: (entries) => {
+            ctx.logger.warn(`dshopencodego: gateway models this build cannot configure: ${entries.map(entry => `${entry.id} (${entry.reason})`).join(', ')}`);
+        },
+        onReplayDegrade: (reason) => {
+            ctx.logger.warn(`dshopencodego: unusable replay state on assistant history; sending provider-neutral content (${reason})`);
+        },
+        onUsage: ({ model, usage }) => { meter.record(model, usage); },
+    });
+    // The usage Remote is mounted before the route so a picker can read it even
+    // while the route is withdrawn for a missing credential.
+    registerRemotes(ctx);
+    ctx.plugin(OpencodeGoUsageService, {
+        baseURL: () => current().baseURL,
+        resolveApiKey,
+        meter,
+    });
+    ctx.plugin(OpencodeGoCatalogService, {
+        catalog: () => adapter.catalogOf(current()),
+        visibility: () => current().modelVisibility,
+    });
+    let registration;
+    let visibilityFacts = JSON.stringify(current().modelVisibility);
+    /**
+     * Register the route while it is enabled and its credential resolves, and
+     * drop it when either says no.
+     *
+     * Nothing else is torn down with the route: model discovery and the
+     * configuration surface stay mounted, so the switch that withdrew the route
+     * stays reachable to bring it back.
+     */
+    const applyRoute = (credentialConfigured) => {
+        const enabled = current().enabled;
+        if (enabled && credentialConfigured && registration === undefined) {
+            try {
+                registration = ctx.llm.registerAdapter([PROVIDER_ID], adapter);
+            }
+            catch (error) {
+                // Most likely DUPLICATE_ADAPTER: another adapter family already owns
+                // `opencode-go` (an `llm-pi-ai` profile, or the previous plugin).
+                // Everything else this mount does keeps working.
+                ctx.logger.error(`dshopencodego: not registering the "${PROVIDER_ID}" route — another adapter already owns it;`
+                    + ` uninstall or disable the other provider first (${String(error)})`);
+            }
+        }
+        else if ((!enabled || !credentialConfigured) && registration !== undefined) {
+            registration();
+            registration = undefined;
+            if (!enabled) {
+                ctx.logger.info('dshopencodego: disabled by configuration; the route and its models are withdrawn');
+            }
+        }
+    };
+    /** Re-evaluate the route gate against the credential that is in force now. */
+    const syncRoute = () => {
+        const visibility = JSON.stringify(current().modelVisibility);
+        if (visibility !== visibilityFacts) {
+            visibilityFacts = visibility;
+            // Replacing the owned route notifies every open picker without a restart.
+            registration?.replace([PROVIDER_ID]);
+        }
+        const credentials = ctx.get('credentials');
+        const ref = current().apiKeyEnv;
+        if (credentials === undefined) {
+            applyRoute(launchEnvironmentOf(ctx).get(ref)?.value !== undefined);
+            return;
+        }
+        void credentials.describe(credentialRef(ref))
+            .then((info) => {
+            // An answer applies only while it still answers for the reference in force.
+            if (ref === current().apiKeyEnv)
+                applyRoute(info.configured);
+        })
+            .catch((error) => {
+            ctx.logger.error(`dshopencodego: credential describe failed; keeping the previous route state (${String(error)})`);
+        });
+    };
+    syncRoute();
+    const undiscover = ctx.llm.registerModelDiscovery(name, async (request) => {
+        if (request.provider !== PROVIDER_ID && !(request.baseURL ?? '').includes('opencode.ai')) {
+            throw new LlmError('dshopencodego discovers only OpenCode zen/go endpoints; enter this provider\'s models by hand', 'DISCOVERY_UNSUPPORTED');
+        }
+        return discoverCatalogModels(adapter.catalogOf(current()));
+    });
+    ctx.effect(() => () => {
+        registration?.();
+        undiscover();
+    });
+    // Validate a profile edit before it is persisted, then re-evaluate the gate.
+    ctx.on('internal/config', function (_raw, next) {
+        const value = next();
+        if (this === ctx.fiber)
+            assertBaseURL(PlainConfig(value).baseURL);
+        return value;
+    });
+    ctx.on('loader/volatile-update', syncRoute);
+    ctx.inject(['credentials'], (credentialsCtx) => {
+        credentialsCtx.on('credentials/reference-updated', (ref) => {
+            if (ref === current().apiKeyEnv)
+                syncRoute();
+        });
+        // The seam can become visible after this plugin applied, so the boot-time
+        // call may have fallen back to the environment: sync again here.
+        syncRoute();
+    });
+    ctx.logger.info(`dshopencodego: route "${PROVIDER_ID}" registered as ${DISPLAY_NAME}`);
+}

package/lib/types/models.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The settings-facing model summary and its visibility rules.
+ *
+ * The adapter's `listModels` and the settings page both need the same facts and
+ * the same answer to "is this model offered right now", so the rule lives here
+ * once: a model nobody can configure is never offered, an explicit switch
+ * always wins, and a deprecated model defaults to off.
+ *
+ * @module @dan-ai-studio/dshopencodego/models
+ */
+import type { ProtocolSource } from './catalog/protocol.ts';
+import type { GoQuota } from './go-limits.ts';
+/** One model as the settings page and the picker describe it. */
+export interface ModelSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly contextWindow?: number;
+    /** Maximum input tokens, when the sources state one. */
+    readonly maxInputTokens?: number;
+    readonly maxTokens?: number;
+    /** models.dev marks the model as retained for compatibility only. */
+    readonly deprecated?: boolean;
+    /** Release date when models.dev states one. */
+    readonly releaseDate?: string;
+    /** Go's published allowance, transcribed from the provider's docs. */
+    readonly goQuota?: GoQuota;
+    /**
+     * Per-million-token rates from models.dev. Absent when the sources state no
+     * positive rate, so a fallback-zero cost never renders as "free".
+     */
+    readonly cost?: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
+    };
+    /** Which ladder level decided this model's protocol. */
+    readonly protocolSource?: ProtocolSource;
+    /** True when a capacity came from the route default rather than a source. */
+    readonly assumedLimits?: boolean;
+    /** Advertised by the gateway but not configurable, with the reason. */
+    readonly configurationMissing?: string;
+    /**
+     * Whether the default configuration keeps this model enabled when nobody set
+     * an explicit switch — the top few by published monthly request estimate.
+     */
+    readonly recommended?: boolean;
+}
+/** How many models the default configuration keeps enabled. */
+export declare const DEFAULT_ENABLED_COUNT = 5;
+/**
+ * Whether the model trades training rights for its price — Meta's
+ * "Contributor" tiers, whose prompts and completions may train future models.
+ * Such a model is never part of the default-enabled few.
+ * @param model - the model under test.
+ * @returns true when the model belongs to a training-contributor tier.
+ */
+export declare function isTrainingTier(model: Pick<ModelSummary, 'id' | 'name'>): boolean;
+/**
+ * The default-enabled ids when nobody configured switches: the models with the
+ * largest published monthly request estimate first, which is Go's own "most
+ * usable" order. Deprecated, unconfigurable, and training-contributor models
+ * never qualify, and a model with no published estimate does not displace one
+ * that has it.
+ *
+ * The estimate is looked up here, by id, rather than read from a `goQuota`
+ * field: the Host's picker and the settings page build their model lists from
+ * different projections, and a caller that forgot to carry the field would
+ * silently fall back to an alphabetical default — which is exactly the
+ * two-surfaces-disagree defect this signature exists to prevent.
+ * @param models - the advertised models, in any order.
+ * @returns the ids the default configuration keeps enabled.
+ */
+export declare function recommendedIds(models: readonly Pick<ModelSummary, 'id' | 'name' | 'deprecated' | 'configurationMissing'>[]): ReadonlySet<string>;
+/**
+ * Whether the picker offers one model.
+ * @param model - the summary under test.
+ * @param visibility - per-model switches; an absent entry keeps the default.
+ * @returns true when the model should be selectable.
+ */
+export declare function isModelEnabled(model: Pick<ModelSummary, 'id' | 'deprecated' | 'configurationMissing' | 'recommended'>, visibility?: Readonly<Record<string, boolean>>): boolean;
+/** A calendar date as models.dev states it, without a timezone. */
+export declare function validReleaseDate(value: unknown): value is string;
+/** Whether a model shipped within the last week. */
+export declare function isNewModel(model: ModelSummary, now?: number): boolean;
+/**
+ * Order models for display: newly shipped first, then the rest, then deprecated.
+ * Newest releases come first within the first group.
+ */
+export declare function sortModels(models: readonly ModelSummary[], now?: number): ModelSummary[];

package/lib/types/models.js

@@ -0,0 +1,86 @@
+/**
+ * The settings-facing model summary and its visibility rules.
+ *
+ * The adapter's `listModels` and the settings page both need the same facts and
+ * the same answer to "is this model offered right now", so the rule lives here
+ * once: a model nobody can configure is never offered, an explicit switch
+ * always wins, and a deprecated model defaults to off.
+ *
+ * @module @dan-ai-studio/dshopencodego/models
+ */
+import { goQuotaFor, monthlyRequestsRank } from "./go-limits.js";
+/** How many models the default configuration keeps enabled. */
+export const DEFAULT_ENABLED_COUNT = 5;
+/**
+ * Whether the model trades training rights for its price — Meta's
+ * "Contributor" tiers, whose prompts and completions may train future models.
+ * Such a model is never part of the default-enabled few.
+ * @param model - the model under test.
+ * @returns true when the model belongs to a training-contributor tier.
+ */
+export function isTrainingTier(model) {
+    return /contributor/i.test(model.id) || /contributor/i.test(model.name);
+}
+/**
+ * The default-enabled ids when nobody configured switches: the models with the
+ * largest published monthly request estimate first, which is Go's own "most
+ * usable" order. Deprecated, unconfigurable, and training-contributor models
+ * never qualify, and a model with no published estimate does not displace one
+ * that has it.
+ *
+ * The estimate is looked up here, by id, rather than read from a `goQuota`
+ * field: the Host's picker and the settings page build their model lists from
+ * different projections, and a caller that forgot to carry the field would
+ * silently fall back to an alphabetical default — which is exactly the
+ * two-surfaces-disagree defect this signature exists to prevent.
+ * @param models - the advertised models, in any order.
+ * @returns the ids the default configuration keeps enabled.
+ */
+export function recommendedIds(models) {
+    const ranked = models
+        .filter(model => model.configurationMissing === undefined
+        && model.deprecated !== true
+        && !isTrainingTier(model))
+        .toSorted((left, right) => monthlyRequestsRank(goQuotaFor(right.id)) - monthlyRequestsRank(goQuotaFor(left.id))
+        || left.id.localeCompare(right.id));
+    return new Set(ranked.slice(0, DEFAULT_ENABLED_COUNT).map(model => model.id));
+}
+/**
+ * Whether the picker offers one model.
+ * @param model - the summary under test.
+ * @param visibility - per-model switches; an absent entry keeps the default.
+ * @returns true when the model should be selectable.
+ */
+export function isModelEnabled(model, visibility) {
+    if (model.configurationMissing !== undefined)
+        return false;
+    const explicit = visibility !== undefined && Object.hasOwn(visibility, model.id)
+        ? visibility[model.id]
+        : undefined;
+    if (typeof explicit === 'boolean')
+        return explicit;
+    // A marked catalog decides the default; an unmarked one keeps every
+    // non-deprecated model, so callers that pass partial facts never lose models.
+    return typeof model.recommended === 'boolean' ? model.recommended : model.deprecated !== true;
+}
+/** A calendar date as models.dev states it, without a timezone. */
+export function validReleaseDate(value) {
+    return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)
+        && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+}
+/** Whether a model shipped within the last week. */
+export function isNewModel(model, now = Date.now()) {
+    if (model.deprecated === true || !validReleaseDate(model.releaseDate))
+        return false;
+    const days = Math.floor(now / 86_400_000) - Date.parse(model.releaseDate) / 86_400_000;
+    return days >= 0 && days < 7;
+}
+/**
+ * Order models for display: newly shipped first, then the rest, then deprecated.
+ * Newest releases come first within the first group.
+ */
+export function sortModels(models, now = Date.now()) {
+    const rank = (model) => model.deprecated === true ? 2 : isNewModel(model, now) ? 0 : 1;
+    return [...models].sort((left, right) => rank(left) - rank(right)
+        || (isNewModel(left, now) && isNewModel(right, now) ? right.releaseDate.localeCompare(left.releaseDate) : 0));
+}

package/lib/types/remotes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Remote registration.
+ *
+ * One registry owns one contribution per package, so both usage methods are
+ * mounted together after whichever registry activation order the composition
+ * happens to use.
+ *
+ * @module @dan-ai-studio/dshopencodego/remotes
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Register this package's Remote contribution for the mount's lifetime. */
+export declare function registerRemotes(ctx: Context): void;

package/lib/types/remotes.js

@@ -0,0 +1,28 @@
+/**
+ * Remote registration.
+ *
+ * One registry owns one contribution per package, so both usage methods are
+ * mounted together after whichever registry activation order the composition
+ * happens to use.
+ *
+ * @module @dan-ai-studio/dshopencodego/remotes
+ */
+import { catalogRemote } from "./catalog/contract.js";
+import { usageRemote } from "./usage/contract.js";
+/** Every Remote method this package owns, mounted as one contribution. */
+const contribution = {
+    package: usageRemote.package,
+    descriptors: [...usageRemote.descriptors, ...catalogRemote.descriptors],
+};
+/** Register this package's Remote contribution for the mount's lifetime. */
+export function registerRemotes(ctx) {
+    ctx.inject(['typert'], (scope) => {
+        scope.effect(() => scope.typert.register({
+            package: contribution.package,
+            face: 'host',
+            schemas: [],
+            model: { services: [], events: [], objects: [] },
+            invocations: contribution.descriptors,
+        }));
+    });
+}

package/lib/types/session-header.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The session header the OpenCode Go gateway requires.
+ *
+ * Every inference request must carry `x-opencode-session`; the gateway answers
+ * `400 MissingSessionID` without it and routes plus caches by its value. Two
+ * rules make that useful rather than merely accepted:
+ *
+ * 1. The value is the conversation's stable Harness session id, verbatim — the
+ *    same string the session log records — so one conversation keeps one
+ *    routing bucket and one prompt cache across turns, resume, compaction,
+ *    retries, and subagents.
+ * 2. A request that carries no session id gets a fresh random value rather than
+ *    a shared constant, because a constant would merge unrelated traffic into a
+ *    single cache bucket and evict itself.
+ *
+ * @module @dan-ai-studio/dshopencodego/session-header
+ */
+/** Header name the gateway requires. */
+export declare const SESSION_HEADER = "x-opencode-session";
+/**
+ * The header value for one request.
+ * @param sessionId - the request's session id, if it names one.
+ * @returns the exact session id, or a fresh UUID when there is none.
+ */
+export declare function opencodeSessionValue(sessionId: string | undefined): string;
+/**
+ * Every header one provider request carries.
+ *
+ * The attribution `user-agent` is Harness-owned and always present; the session
+ * header is added on top of it. A caller-supplied header of the same name can
+ * never win, because the gateway's routing decision must follow the session,
+ * not a deployment string.
+ * @param sessionId - the request's session id, if it names one.
+ * @returns headers for the pi-ai request options.
+ */
+export declare function providerHeaders(sessionId: string | undefined): Record<string, string>;

package/lib/types/session-header.js

@@ -0,0 +1,45 @@
+/**
+ * The session header the OpenCode Go gateway requires.
+ *
+ * Every inference request must carry `x-opencode-session`; the gateway answers
+ * `400 MissingSessionID` without it and routes plus caches by its value. Two
+ * rules make that useful rather than merely accepted:
+ *
+ * 1. The value is the conversation's stable Harness session id, verbatim — the
+ *    same string the session log records — so one conversation keeps one
+ *    routing bucket and one prompt cache across turns, resume, compaction,
+ *    retries, and subagents.
+ * 2. A request that carries no session id gets a fresh random value rather than
+ *    a shared constant, because a constant would merge unrelated traffic into a
+ *    single cache bucket and evict itself.
+ *
+ * @module @dan-ai-studio/dshopencodego/session-header
+ */
+import { randomUUID } from 'node:crypto';
+import { attributionHeaders } from '@deepseek-ai/dsh-llm';
+/** Header name the gateway requires. */
+export const SESSION_HEADER = 'x-opencode-session';
+/**
+ * The header value for one request.
+ * @param sessionId - the request's session id, if it names one.
+ * @returns the exact session id, or a fresh UUID when there is none.
+ */
+export function opencodeSessionValue(sessionId) {
+    return sessionId !== undefined && sessionId.length > 0 ? sessionId : randomUUID();
+}
+/**
+ * Every header one provider request carries.
+ *
+ * The attribution `user-agent` is Harness-owned and always present; the session
+ * header is added on top of it. A caller-supplied header of the same name can
+ * never win, because the gateway's routing decision must follow the session,
+ * not a deployment string.
+ * @param sessionId - the request's session id, if it names one.
+ * @returns headers for the pi-ai request options.
+ */
+export function providerHeaders(sessionId) {
+    return {
+        [SESSION_HEADER]: opencodeSessionValue(sessionId),
+        ...attributionHeaders(),
+    };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Wire contract for the usage Remote.
+ *
+ * Two readings are exposed, and they answer different questions: `readWindows`
+ * asks the gateway what the account has left, and `readMeter` reports what this
+ * process has actually spent since it started. Neither is a per-model quota —
+ * the endpoint does not publish one — and the client labels them accordingly.
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/contract
+ */
+import type { RemoteResult, TypertRemoteContribution } from '@deepseek-ai/dsh-typert-protocol';
+import type { GoMeter } from './meter.ts';
+import type { GoUsageWindows } from './windows.ts';
+export type { GoMeter, MeterModelEntry, MeterTotals } from './meter.ts';
+export type { GoUsageWindows, UsageWindow } from './windows.ts';
+/** Validate a windows reading crossing the wire. */
+export declare function parseUsageWindows(value: unknown): GoUsageWindows;
+/** Validate a meter reading crossing the wire. */
+export declare function parseGoMeter(value: unknown): GoMeter;
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        'dshopencodego/usage-unavailable': {
+            /** Whether retrying the same read could succeed. */
+            readonly retryable: boolean;
+            /** Whether a previously displayed reading stays valid. */
+            readonly retainPrevious: boolean;
+            /** Identity of the reading the client already holds, when any. */
+            readonly source?: string;
+        };
+    }
+    interface TypertRemoteNamespaceMap {
+        opencodeGoUsage: {
+            readWindows(): Promise<RemoteResult<GoUsageWindows>>;
+            readMeter(): Promise<RemoteResult<GoMeter>>;
+        };
+    }
+}
+/** Remote methods this package owns, mounted together by the plugin. */
+export declare const usageRemote: TypertRemoteContribution;

package/lib/types/usage/contract.js

@@ -0,0 +1,106 @@
+/**
+ * Wire contract for the usage Remote.
+ *
+ * Two readings are exposed, and they answer different questions: `readWindows`
+ * asks the gateway what the account has left, and `readMeter` reports what this
+ * process has actually spent since it started. Neither is a per-model quota —
+ * the endpoint does not publish one — and the client labels them accordingly.
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/contract
+ */
+/** Validate one window on the way back from the Host. */
+function parseWindow(value, key) {
+    if (value === null || typeof value !== 'object')
+        throw new Error(`invalid usage window "${key}"`);
+    const row = value;
+    if ((row['status'] !== 'ok' && row['status'] !== 'rate-limited')
+        || typeof row['percent'] !== 'number' || !Number.isFinite(row['percent'])
+        || typeof row['resetsAt'] !== 'string') {
+        throw new Error(`invalid usage window "${key}"`);
+    }
+    return { status: row['status'], percent: row['percent'], resetsAt: row['resetsAt'] };
+}
+/** Validate a windows reading crossing the wire. */
+export function parseUsageWindows(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid usage reading');
+    const row = value;
+    return {
+        ...typeof row['source'] === 'string' ? { source: row['source'] } : {},
+        rolling: parseWindow(row['rolling'], 'rolling'),
+        weekly: parseWindow(row['weekly'], 'weekly'),
+        monthly: parseWindow(row['monthly'], 'monthly'),
+    };
+}
+function parseTotals(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid meter totals');
+    const row = value;
+    const count = (key) => {
+        const entry = row[key];
+        if (typeof entry !== 'number' || !Number.isFinite(entry) || entry < 0)
+            throw new Error(`invalid meter field "${key}"`);
+        return entry;
+    };
+    return {
+        calls: count('calls'),
+        inputTokens: count('inputTokens'),
+        outputTokens: count('outputTokens'),
+        cacheReadTokens: count('cacheReadTokens'),
+        cacheWriteTokens: count('cacheWriteTokens'),
+        totalTokens: count('totalTokens'),
+    };
+}
+/** Validate a meter reading crossing the wire. */
+export function parseGoMeter(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid meter reading');
+    const row = value;
+    if (typeof row['sinceMs'] !== 'number' || typeof row['atMs'] !== 'number' || !Array.isArray(row['models'])) {
+        throw new Error('invalid meter reading');
+    }
+    return {
+        sinceMs: row['sinceMs'],
+        atMs: row['atMs'],
+        totals: parseTotals(row['totals']),
+        models: row['models'].map((entry) => {
+            if (entry === null || typeof entry !== 'object')
+                throw new Error('invalid meter model entry');
+            const model = entry['model'];
+            if (typeof model !== 'string')
+                throw new Error('invalid meter model entry');
+            return { model, ...parseTotals(entry) };
+        }),
+    };
+}
+/** Codec shape accepted by both released and source DSH builds. */
+const codec = (typeSymbol, parse) => ({
+    mode: 'strict',
+    typeSymbol,
+    schema: { parse },
+    create: () => ({ parse }),
+});
+/** Remote methods this package owns, mounted together by the plugin. */
+export const usageRemote = {
+    package: '@dan-ai-studio/dshopencodego',
+    descriptors: [
+        {
+            id: '@dan-ai-studio/dshopencodego#opencodeGoUsage/readWindows',
+            service: 'opencodeGoUsage',
+            namespace: 'opencodeGoUsage',
+            method: 'readWindows',
+            invocation: { kind: 'direct' },
+            parameters: [],
+            result: codec('@dan-ai-studio/dshopencodego#GoUsageWindows', parseUsageWindows),
+        },
+        {
+            id: '@dan-ai-studio/dshopencodego#opencodeGoUsage/readMeter',
+            service: 'opencodeGoUsage',
+            namespace: 'opencodeGoUsage',
+            method: 'readMeter',
+            invocation: { kind: 'direct' },
+            parameters: [],
+            result: codec('@dan-ai-studio/dshopencodego#GoMeter', parseGoMeter),
+        },
+    ],
+};

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

@@ -0,0 +1,11 @@
+/**
+ * Usage readings for the `opencode-go` route.
+ * @module @dan-ai-studio/dshopencodego/usage
+ */
+export { UsageMeter } from './meter.ts';
+export type { GoMeter, MeterModelEntry, MeterTotals } from './meter.ts';
+export { parseGoUsage, readUsageWindows } from './windows.ts';
+export type { GoUsageWindows, UsageWindow } from './windows.ts';
+export { parseGoMeter, parseUsageWindows, usageRemote } from './contract.ts';
+export { OpencodeGoUsageService } from './service.ts';
+export type { UsageServiceOptions } from './service.ts';

package/lib/types/usage/index.js

@@ -0,0 +1,8 @@
+/**
+ * Usage readings for the `opencode-go` route.
+ * @module @dan-ai-studio/dshopencodego/usage
+ */
+export { UsageMeter } from "./meter.js";
+export { parseGoUsage, readUsageWindows } from "./windows.js";
+export { parseGoMeter, parseUsageWindows, usageRemote } from "./contract.js";
+export { OpencodeGoUsageService } from "./service.js";