@dan-ai-studio/dshopencodego 0.1.5

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

@@ -0,0 +1,53 @@
+/**
+ * The since-boot usage meter.
+ *
+ * The gateway's `/usage` endpoint reports account percentages, not tokens, so
+ * the only honest source of per-model token counts is the usage the provider
+ * itself returns on each completed call. This meter accumulates exactly that,
+ * per model and in total, for the lifetime of the process — and says so: the
+ * number is labelled "since this Harness started", never "today".
+ *
+ * A conversation's own totals are durable and are folded from the session log
+ * by the client, which is why nothing here persists.
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/meter
+ */
+import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+/** Token counts and call count for one model, or for every model. */
+export interface MeterTotals {
+    readonly calls: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+    /** Sum of the four token fields, which is what a provider bills. */
+    readonly totalTokens: number;
+}
+/** One model's share of the since-boot meter. */
+export interface MeterModelEntry extends MeterTotals {
+    readonly model: string;
+}
+/** The whole since-boot reading. */
+export interface GoMeter {
+    /** When this process started counting, in epoch milliseconds. */
+    readonly sinceMs: number;
+    /** When this reading was taken, in epoch milliseconds. */
+    readonly atMs: number;
+    readonly totals: MeterTotals;
+    /** Per-model entries, busiest first. */
+    readonly models: readonly MeterModelEntry[];
+}
+/** Accumulates provider-reported usage for the lifetime of one Host process. */
+export declare class UsageMeter {
+    private readonly sinceMs;
+    private totals;
+    private readonly byModel;
+    /**
+     * Record one completed call.
+     * @param model - the model id the call was made with.
+     * @param usage - the provider's own usage for that call.
+     */
+    record(model: string, usage: TokenUsage): void;
+    /** The current reading, busiest model first. */
+    snapshot(now?: number): GoMeter;
+}

package/lib/types/usage/meter.js

@@ -0,0 +1,65 @@
+/**
+ * The since-boot usage meter.
+ *
+ * The gateway's `/usage` endpoint reports account percentages, not tokens, so
+ * the only honest source of per-model token counts is the usage the provider
+ * itself returns on each completed call. This meter accumulates exactly that,
+ * per model and in total, for the lifetime of the process — and says so: the
+ * number is labelled "since this Harness started", never "today".
+ *
+ * A conversation's own totals are durable and are folded from the session log
+ * by the client, which is why nothing here persists.
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/meter
+ */
+const EMPTY = {
+    calls: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    totalTokens: 0,
+};
+function add(totals, usage) {
+    const inputTokens = totals.inputTokens + usage.inputTokens;
+    const outputTokens = totals.outputTokens + usage.outputTokens;
+    const cacheReadTokens = totals.cacheReadTokens + (usage.cacheReadTokens ?? 0);
+    const cacheWriteTokens = totals.cacheWriteTokens + (usage.cacheWriteTokens ?? 0);
+    return {
+        calls: totals.calls + 1,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        // The four counts are disjoint (uncached input, cached input, output), so
+        // their sum is the billed total. The provider's own `totalTokens` is not
+        // used: it is optional, and mixing the two would double-count a cache read.
+        totalTokens: inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
+    };
+}
+/** Accumulates provider-reported usage for the lifetime of one Host process. */
+export class UsageMeter {
+    sinceMs = Date.now();
+    totals = EMPTY;
+    byModel = new Map();
+    /**
+     * Record one completed call.
+     * @param model - the model id the call was made with.
+     * @param usage - the provider's own usage for that call.
+     */
+    record(model, usage) {
+        this.totals = add(this.totals, usage);
+        this.byModel.set(model, add(this.byModel.get(model) ?? EMPTY, usage));
+    }
+    /** The current reading, busiest model first. */
+    snapshot(now = Date.now()) {
+        return {
+            sinceMs: this.sinceMs,
+            atMs: now,
+            totals: this.totals,
+            models: [...this.byModel.entries()]
+                .map(([model, totals]) => ({ model, ...totals }))
+                .sort((left, right) => right.totalTokens - left.totalTokens || left.model.localeCompare(right.model)),
+        };
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Host half of the usage Remote.
+ *
+ * The credential never leaves the Host: the browser asks for a reading and gets
+ * percentages, and the Host decides whether a failed read may be shown as the
+ * previous one. A read that fails while the account is unchanged keeps the last
+ * good value and says it is stale; a read for a different endpoint or key
+ * invalidates it, because the old numbers describe a different account.
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/service
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { UsageMeter } from './meter.ts';
+import type { GoMeter } from './meter.ts';
+import type { GoUsageWindows } from './windows.ts';
+/** Host inputs for the usage service. */
+export interface UsageServiceOptions {
+    /** Current gateway base URL. */
+    readonly baseURL: () => string;
+    /** Resolve the route credential per read. */
+    readonly resolveApiKey: () => Promise<string | undefined>;
+    /** The process-lifetime meter fed by the adapter. */
+    readonly meter: UsageMeter;
+}
+/**
+ * Decide what one failed read means for the client.
+ *
+ * A missing credential is a configuration fact, not a transient one: retrying
+ * cannot help and the reading a client holds was produced by a *different*
+ * account, so it must not be shown as this one's. Any other failure describes
+ * the account the client already has a reading for, so that reading stays valid
+ * and is marked stale.
+ * @param error - the failure raised by credential resolution or the read.
+ * @param source - identity of the account the failed read was for.
+ * @returns the domain error to send across the wire.
+ */
+export declare function usageFailure(error: unknown, source: string | undefined): RemoteError;
+/** Usage Remote: account windows from the gateway, spend from this process. */
+export declare class OpencodeGoUsageService extends TypertRemoteService {
+    private identity;
+    private readonly options;
+    constructor(ctx: Context, options: UsageServiceOptions);
+    /** The account's three windows, or a domain failure the client can render. */
+    readWindows(): Promise<GoUsageWindows>;
+    /** What this process has spent through the route since it started. */
+    readMeter(): GoMeter;
+}

package/lib/types/usage/service.js

@@ -0,0 +1,74 @@
+/**
+ * Host half of the usage Remote.
+ *
+ * The credential never leaves the Host: the browser asks for a reading and gets
+ * percentages, and the Host decides whether a failed read may be shown as the
+ * previous one. A read that fails while the account is unchanged keeps the last
+ * good value and says it is stale; a read for a different endpoint or key
+ * invalidates it, because the old numbers describe a different account.
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/service
+ */
+import { randomUUID } from 'node:crypto';
+import { RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { LlmError } from '@deepseek-ai/dsh-llm';
+import { assertBaseURL } from "../config.js";
+import { readUsageWindows } from "./windows.js";
+/**
+ * Decide what one failed read means for the client.
+ *
+ * A missing credential is a configuration fact, not a transient one: retrying
+ * cannot help and the reading a client holds was produced by a *different*
+ * account, so it must not be shown as this one's. Any other failure describes
+ * the account the client already has a reading for, so that reading stays valid
+ * and is marked stale.
+ * @param error - the failure raised by credential resolution or the read.
+ * @param source - identity of the account the failed read was for.
+ * @returns the domain error to send across the wire.
+ */
+export function usageFailure(error, source) {
+    const missing = error instanceof LlmError && error.code === 'MISSING_CREDENTIAL';
+    return new RemoteError('dshopencodego/usage-unavailable', error instanceof Error ? error.message : 'OpenCode Go usage is unavailable', missing
+        ? { retryable: false, retainPrevious: false }
+        : { retryable: true, retainPrevious: true, ...source === undefined ? {} : { source } }, { cause: error });
+}
+/** Usage Remote: account windows from the gateway, spend from this process. */
+export class OpencodeGoUsageService extends TypertRemoteService {
+    identity;
+    options;
+    constructor(ctx, options) {
+        super(ctx, 'opencodeGoUsage');
+        this.options = options;
+    }
+    /** The account's three windows, or a domain failure the client can render. */
+    async readWindows() {
+        const baseURL = assertBaseURL(this.options.baseURL());
+        let key;
+        try {
+            key = await this.options.resolveApiKey();
+        }
+        catch (error) {
+            this.identity = undefined;
+            throw usageFailure(error, undefined);
+        }
+        if (key === undefined || key.length === 0) {
+            this.identity = undefined;
+            throw usageFailure(new LlmError('No OpenCode Go API key is configured', 'MISSING_CREDENTIAL'), undefined);
+        }
+        if (this.identity?.baseURL !== baseURL || this.identity.key !== key) {
+            // A new account or endpoint invalidates any reading the client holds.
+            this.identity = { baseURL, key, source: randomUUID() };
+        }
+        const { source } = this.identity;
+        try {
+            return await readUsageWindows({ baseURL, apiKey: key, source });
+        }
+        catch (error) {
+            throw usageFailure(error, source);
+        }
+    }
+    /** What this process has spent through the route since it started. */
+    readMeter() {
+        return this.options.meter.snapshot();
+    }
+}

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

@@ -0,0 +1,51 @@
+/**
+ * The account's usage windows, read from the gateway.
+ *
+ * `/usage` reports three percentages — a rolling five-hour window, a week, and
+ * a month — each with a reset time and a rate-limited flag. It reports *no*
+ * per-model breakdown and no token counts, so this module never pretends to:
+ * per-model and per-session numbers are derived locally from real provider
+ * usage instead (see `./meter.ts` and the session fold in the client).
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/windows
+ */
+/** One quota window as the gateway reports it. */
+export interface UsageWindow {
+    readonly status: 'ok' | 'rate-limited';
+    readonly percent: number;
+    readonly resetsAt: string;
+}
+/** The account's three windows plus an opaque identity for the reading. */
+export interface GoUsageWindows {
+    /** Opaque Host identity for the endpoint and credential that produced this reading. */
+    readonly source?: string;
+    readonly rolling: UsageWindow;
+    readonly weekly: UsageWindow;
+    readonly monthly: UsageWindow;
+}
+/**
+ * Parse a usage response body.
+ * @param value - the `usage` member of the response.
+ * @returns the three windows.
+ * @throws {Error} when a window is missing or malformed; an unavailable reading
+ *   must never be displayed as a zero percentage.
+ */
+export declare function parseGoUsage(value: unknown): Omit<GoUsageWindows, 'source'>;
+/** Inputs one usage read needs. */
+export interface UsageReadOptions {
+    /** Normalized gateway base URL. */
+    readonly baseURL: string;
+    /** Resolved credential; absence is reported as an unconfigured route. */
+    readonly apiKey: string | undefined;
+    /** Opaque identity of the endpoint and credential pair, when known. */
+    readonly source?: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Read the account's usage windows.
+ * @param options - endpoint, credential, and identity.
+ * @returns the three windows, tagged with the identity that produced them.
+ * @throws {LlmError} `USAGE_UNAVAILABLE` when the credential is missing, the
+ *   endpoint fails, or the body is not a usage document.
+ */
+export declare function readUsageWindows(options: UsageReadOptions): Promise<GoUsageWindows>;

package/lib/types/usage/windows.js

@@ -0,0 +1,84 @@
+/**
+ * The account's usage windows, read from the gateway.
+ *
+ * `/usage` reports three percentages — a rolling five-hour window, a week, and
+ * a month — each with a reset time and a rate-limited flag. It reports *no*
+ * per-model breakdown and no token counts, so this module never pretends to:
+ * per-model and per-session numbers are derived locally from real provider
+ * usage instead (see `./meter.ts` and the session fold in the client).
+ *
+ * @module @dan-ai-studio/dshopencodego/usage/windows
+ */
+import { attributionHeaders, LlmError } from '@deepseek-ai/dsh-llm';
+import { readBoundedJson } from "../catalog/json-response.js";
+/** Response cap: this document is a few hundred bytes. */
+const USAGE_MAX_BYTES = 1024 * 1024;
+/** Timeout for one usage read. */
+const USAGE_TIMEOUT_MS = 10_000;
+/**
+ * Parse a usage response body.
+ * @param value - the `usage` member of the response.
+ * @returns the three windows.
+ * @throws {Error} when a window is missing or malformed; an unavailable reading
+ *   must never be displayed as a zero percentage.
+ */
+export function parseGoUsage(value) {
+    if (value === null || typeof value !== 'object')
+        throw new Error('invalid usage response');
+    const source = value;
+    const result = {};
+    for (const key of ['rolling', 'weekly', 'monthly']) {
+        const row = source[key];
+        if (row === null || row === undefined
+            || (row.status !== 'ok' && row.status !== 'rate-limited')
+            || typeof row.percent !== 'number' || !Number.isFinite(row.percent) || row.percent < 0
+            || typeof row.resetsAt !== 'string' || !Number.isFinite(Date.parse(row.resetsAt))) {
+            throw new Error(`invalid usage response: window "${key}" is missing or malformed`);
+        }
+        result[key] = { status: row.status, percent: row.percent, resetsAt: row.resetsAt };
+    }
+    return result;
+}
+/**
+ * Read the account's usage windows.
+ * @param options - endpoint, credential, and identity.
+ * @returns the three windows, tagged with the identity that produced them.
+ * @throws {LlmError} `USAGE_UNAVAILABLE` when the credential is missing, the
+ *   endpoint fails, or the body is not a usage document.
+ */
+export async function readUsageWindows(options) {
+    if (options.apiKey === undefined || options.apiKey.length === 0) {
+        throw new LlmError('dshopencodego: no credential is configured for the opencode-go route', 'USAGE_UNAVAILABLE');
+    }
+    const url = `${options.baseURL.replace(/\/+$/, '')}/usage`;
+    const timeout = AbortSignal.timeout(USAGE_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, {
+            redirect: 'error',
+            headers: {
+                ...attributionHeaders(),
+                accept: 'application/json',
+                authorization: `Bearer ${options.apiKey}`,
+            },
+            signal: options.signal === undefined ? timeout : AbortSignal.any([options.signal, timeout]),
+        });
+    }
+    catch (error) {
+        throw new LlmError(`could not reach ${url}`, 'USAGE_UNAVAILABLE', { cause: error });
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new LlmError(`${url} answered HTTP ${response.status}`, 'USAGE_UNAVAILABLE');
+    }
+    const body = await readBoundedJson(response, url, USAGE_MAX_BYTES);
+    try {
+        return {
+            ...parseGoUsage(body?.usage),
+            ...options.source === undefined ? {} : { source: options.source },
+        };
+    }
+    catch (error) {
+        throw new LlmError(`${url} returned an invalid usage document`, 'USAGE_UNAVAILABLE', { cause: error });
+    }
+}

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "@dan-ai-studio/dshopencodego",
+  "version": "0.1.5",
+  "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dan-ai-studio/dshopencodego.git"
+  },
+  "homepage": "https://github.com/dan-ai-studio/dshopencodego#readme",
+  "bugs": {
+    "url": "https://github.com/dan-ai-studio/dshopencodego/issues"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.1.7-alpha.1 <0.1.8"
+  },
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-model-selection"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.host.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.3",
+    "@earendil-works/pi-ai": "0.87.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.2 || 4.0.3 || 4.0.4",
+    "@deepseek-ai/dsh-api-remotes": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-attachment": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-brand": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-client-store": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-client-ui-model-selection": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-credentials": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-fs": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-launch-environment": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-llm": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-settings": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-timeout": ">=0.1.7-alpha.1 <0.1.8",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.7-alpha.1 <0.1.8"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-api-remotes": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-store": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-model-selection": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-api-remotes": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-attachment": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-brand": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-store": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-model-selection": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-credentials": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-fs": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-launch-environment": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-settings": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-timeout": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.7-rc.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "esbuild": "^0.28.2",
+    "jsdom": "^29.0.0",
+    "lightningcss": "^1.32.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "opencode",
+    "opencode-go",
+    "llm",
+    "cordis"
+  ]
+}