mcp-server-opencode 1.1.4 → 1.2.0

package/build/src/modules/shared/permissions.d.ts

@@ -0,0 +1,108 @@
+import type { Config, OpencodeClient } from "@opencode-ai/sdk";
+/**
+ * A pending permission request, as the OpenCode server actually emits it.
+ *
+ * The SDK's generated `Permission` type is stale relative to the running
+ * binary (verified against opencode 1.18.18 / `@opencode-ai/sdk` 1.17.20):
+ * the live event is `permission.asked` rather than `permission.updated`, the
+ * permission kind arrives as `permission` rather than `type`, and the call id
+ * is nested under `tool`. Both spellings are accepted so this keeps working
+ * whichever side moves first.
+ */
+export interface PermissionAsk {
+    id: string;
+    sessionID: string;
+    /** Live server field. */
+    permission?: string;
+    /** Generated-SDK field. */
+    type?: string;
+    patterns?: string[];
+    always?: string[];
+    metadata?: Record<string, unknown>;
+    /** Live server nests the originating call here. */
+    tool?: {
+        messageID?: string;
+        callID?: string;
+    };
+    /** Generated-SDK field. */
+    callID?: string;
+}
+/** The permission kind, reading whichever field this server version emits. */
+export declare function permissionKind(ask: PermissionAsk): string | undefined;
+/** The originating tool call id, reading whichever field this server emits. */
+export declare function permissionCallID(ask: PermissionAsk): string | undefined;
+/**
+ * How the delegated agent may touch paths outside the directory the server was
+ * launched in.
+ *
+ * - `read-only` (default): reads outside the cwd are approved, writes are rejected.
+ * - `allow`: no boundary at all — anything outside the cwd is approved.
+ * - `deny`: nothing outside the cwd is reachable.
+ */
+export type ExternalDirectoryPolicy = "read-only" | "allow" | "deny";
+export declare const DEFAULT_EXTERNAL_DIRECTORY_POLICY: ExternalDirectoryPolicy;
+/** The permission type OpenCode raises for any path outside the server cwd. */
+export declare const EXTERNAL_DIRECTORY = "external_directory";
+/**
+ * Resolve the external-directory policy.
+ *
+ * Precedence: the `OPENCODE_MCP_EXTERNAL_DIR` environment variable wins over an
+ * `OPENCODE_MCP_EXTERNAL_DIR=<policy>` CLI arg, which wins over `read-only`.
+ * Unrecognised values fall back to the default.
+ *
+ * Reads `process.env` / `process.argv` lazily on each call so tests can vary
+ * them between invocations without module re-import tricks.
+ */
+export declare function getExternalDirectoryPolicy(): ExternalDirectoryPolicy;
+/**
+ * Build the config handed to `createOpencodeServer`.
+ *
+ * OpenCode deep-merges this over the user's global config per permission key,
+ * so only `external_directory` is touched — existing `read` / `edit` / `bash`
+ * rules (including deny globs for secrets) survive untouched.
+ *
+ * `read-only` keeps the key on `ask` on purpose: the permission responder is
+ * what applies the read/write split, and it can only do that if OpenCode still
+ * raises the request.
+ */
+export declare function buildServerConfig(policy: ExternalDirectoryPolicy): Config;
+export type PermissionResponse = "once" | "always" | "reject";
+export interface PermissionDecision {
+    response: PermissionResponse;
+    reason: string;
+}
+/**
+ * Decide how to answer a pending permission request.
+ *
+ * Anything that is not `external_directory` targets the directory the server
+ * was launched in, which the caller already owns — approved with `always` so
+ * repeat calls stop round-tripping.
+ *
+ * External reads are approved with `once` rather than `always` on purpose: an
+ * `always` reply persists the approval keyed by directory pattern, not by
+ * operation, which would silently let a later write into that same directory
+ * through and defeat the read-only boundary.
+ */
+export declare function decidePermission(client: OpencodeClient, ask: PermissionAsk, policy: ExternalDirectoryPolicy, sleep?: (ms: number) => Promise<void>): Promise<PermissionDecision>;
+export interface PermissionResponderOptions {
+    policy?: ExternalDirectoryPolicy;
+    /** Called on stream/reply failures so they never bubble into the MCP server. */
+    onError?: (error: unknown) => void;
+    /** Called after each answered request; useful for diagnostics and tests. */
+    onDecision?: (ask: PermissionAsk, decision: PermissionDecision) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface PermissionResponder {
+    stop: () => void;
+    /** Resolves once the responder loop has exited. */
+    done: Promise<void>;
+}
+/**
+ * Answer permission requests for a headless server.
+ *
+ * Without this, any request configured as `ask` blocks the agent forever: there
+ * is no interactive approver behind an MCP-spawned server, so the session stays
+ * genuinely busy and the task never completes or fails.
+ */
+export declare function startPermissionResponder(client: OpencodeClient, options?: PermissionResponderOptions): PermissionResponder;
+//# sourceMappingURL=permissions.d.ts.map

package/build/src/modules/shared/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../../../src/modules/shared/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,mDAAmD;IACnD,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAErE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAErE,eAAO,MAAM,iCAAiC,EAAE,uBAAqC,CAAC;AAEtF,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAyBvD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,IAAI,uBAAuB,CAYpE;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CAGzE;AAED,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAsCD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,uBAAuB,EAC/B,KAAK,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAgB,GAClD,OAAO,CAAC,kBAAkB,CAAC,CAyB7B;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACxE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,mDAAmD;IACnD,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACrB;AAMD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,CAmCrB"}

package/build/src/modules/shared/permissions.js

@@ -0,0 +1,193 @@
+/** Event types that carry a pending permission request. */
+const PERMISSION_EVENTS = new Set(["permission.asked", "permission.updated"]);
+/** The permission kind, reading whichever field this server version emits. */
+export function permissionKind(ask) {
+    return ask.permission ?? ask.type;
+}
+/** The originating tool call id, reading whichever field this server emits. */
+export function permissionCallID(ask) {
+    return ask.tool?.callID ?? ask.callID;
+}
+export const DEFAULT_EXTERNAL_DIRECTORY_POLICY = "read-only";
+/** The permission type OpenCode raises for any path outside the server cwd. */
+export const EXTERNAL_DIRECTORY = "external_directory";
+/**
+ * Tools that only observe. OpenCode raises a single `external_directory`
+ * permission for reads and writes alike, so the operation has to be recovered
+ * from the tool that triggered it. Names verified against the live catalog
+ * (`client.tool.ids()` on opencode 1.18.18) — there is no `list` tool.
+ */
+const READ_ONLY_TOOLS = new Set(["read", "grep", "glob", "webfetch", "websearch"]);
+/** Delay before re-subscribing after the event stream drops. */
+const RECONNECT_DELAY_MS = 1_000;
+/** Attempts to correlate a permission to its tool call before giving up. */
+const CORRELATION_ATTEMPTS = 3;
+/** Delay between correlation attempts, covering the event/message write race. */
+const CORRELATION_DELAY_MS = 100;
+const POLICIES = new Set([
+    "read-only",
+    "allow",
+    "deny",
+]);
+/**
+ * Resolve the external-directory policy.
+ *
+ * Precedence: the `OPENCODE_MCP_EXTERNAL_DIR` environment variable wins over an
+ * `OPENCODE_MCP_EXTERNAL_DIR=<policy>` CLI arg, which wins over `read-only`.
+ * Unrecognised values fall back to the default.
+ *
+ * Reads `process.env` / `process.argv` lazily on each call so tests can vary
+ * them between invocations without module re-import tricks.
+ */
+export function getExternalDirectoryPolicy() {
+    const fromEnv = parsePolicy(process.env.OPENCODE_MCP_EXTERNAL_DIR);
+    if (fromEnv !== undefined)
+        return fromEnv;
+    const argPrefix = "OPENCODE_MCP_EXTERNAL_DIR=";
+    const argEntry = process.argv.find((arg) => arg.startsWith(argPrefix));
+    if (argEntry !== undefined) {
+        const fromArg = parsePolicy(argEntry.slice(argPrefix.length));
+        if (fromArg !== undefined)
+            return fromArg;
+    }
+    return DEFAULT_EXTERNAL_DIRECTORY_POLICY;
+}
+function parsePolicy(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (!POLICIES.has(normalized))
+        return undefined;
+    return normalized;
+}
+/**
+ * Build the config handed to `createOpencodeServer`.
+ *
+ * OpenCode deep-merges this over the user's global config per permission key,
+ * so only `external_directory` is touched — existing `read` / `edit` / `bash`
+ * rules (including deny globs for secrets) survive untouched.
+ *
+ * `read-only` keeps the key on `ask` on purpose: the permission responder is
+ * what applies the read/write split, and it can only do that if OpenCode still
+ * raises the request.
+ */
+export function buildServerConfig(policy) {
+    const external_directory = policy === "read-only" ? "ask" : policy;
+    return { permission: { external_directory } };
+}
+/**
+ * Call ids arrive as `<tool>_<n>` (e.g. `read_0`, `write_0`), so the tool name
+ * is readable straight off the event with no round-trip and no race.
+ */
+const CALL_ID_TOOL = /^(.+)_\d+$/;
+/**
+ * Find the tool that raised a permission.
+ *
+ * The call id encodes the tool name, which is the fast path. If a future
+ * server stops encoding it, fall back to matching the id against the session's
+ * tool parts — retried, because the event can land before the part is readable.
+ */
+async function resolveToolName(client, ask, sleep) {
+    const callID = permissionCallID(ask);
+    if (callID === undefined)
+        return undefined;
+    const encoded = CALL_ID_TOOL.exec(callID);
+    if (encoded)
+        return encoded[1];
+    for (let attempt = 0; attempt < CORRELATION_ATTEMPTS; attempt++) {
+        if (attempt > 0)
+            await sleep(CORRELATION_DELAY_MS);
+        const res = await client.session.messages({ path: { id: ask.sessionID } });
+        for (const message of res.data ?? []) {
+            for (const part of message.parts) {
+                if (part.type === "tool" && part.callID === callID)
+                    return part.tool;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Decide how to answer a pending permission request.
+ *
+ * Anything that is not `external_directory` targets the directory the server
+ * was launched in, which the caller already owns — approved with `always` so
+ * repeat calls stop round-tripping.
+ *
+ * External reads are approved with `once` rather than `always` on purpose: an
+ * `always` reply persists the approval keyed by directory pattern, not by
+ * operation, which would silently let a later write into that same directory
+ * through and defeat the read-only boundary.
+ */
+export async function decidePermission(client, ask, policy, sleep = defaultSleep) {
+    if (permissionKind(ask) !== EXTERNAL_DIRECTORY) {
+        return { response: "always", reason: "inside the server working directory" };
+    }
+    if (policy === "allow") {
+        return { response: "always", reason: "external_directory policy is 'allow'" };
+    }
+    if (policy === "deny") {
+        return { response: "reject", reason: "external_directory policy is 'deny'" };
+    }
+    // Shell commands carry their own metadata shape and can write through any
+    // number of paths, so they never qualify as read-only.
+    if (ask.metadata?.command !== undefined) {
+        return { response: "reject", reason: "shell command outside the working directory" };
+    }
+    const tool = await resolveToolName(client, ask, sleep);
+    if (tool === undefined) {
+        return { response: "reject", reason: "could not identify the tool behind the request" };
+    }
+    if (!READ_ONLY_TOOLS.has(tool)) {
+        return { response: "reject", reason: `'${tool}' writes outside the working directory` };
+    }
+    return { response: "once", reason: `'${tool}' only reads` };
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Answer permission requests for a headless server.
+ *
+ * Without this, any request configured as `ask` blocks the agent forever: there
+ * is no interactive approver behind an MCP-spawned server, so the session stays
+ * genuinely busy and the task never completes or fails.
+ */
+export function startPermissionResponder(client, options = {}) {
+    const policy = options.policy ?? getExternalDirectoryPolicy();
+    const onError = options.onError ?? (() => { });
+    const onDecision = options.onDecision ?? (() => { });
+    const sleep = options.sleep ?? defaultSleep;
+    let stopped = false;
+    const stop = () => {
+        stopped = true;
+    };
+    const done = (async () => {
+        while (!stopped) {
+            try {
+                const { stream } = await client.event.subscribe();
+                for await (const event of stream) {
+                    if (stopped)
+                        return;
+                    if (!PERMISSION_EVENTS.has(event.type))
+                        continue;
+                    const ask = event.properties;
+                    const decision = await decidePermission(client, ask, policy, sleep);
+                    await client.postSessionIdPermissionsPermissionId({
+                        path: { id: ask.sessionID, permissionID: ask.id },
+                        body: { response: decision.response },
+                    });
+                    onDecision(ask, decision);
+                }
+            }
+            catch (error) {
+                onError(error);
+            }
+            if (stopped)
+                return;
+            await sleep(RECONNECT_DELAY_MS);
+        }
+    })();
+    return { stop, done };
+}
+//# sourceMappingURL=permissions.js.map

package/build/src/modules/shared/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../../../src/modules/shared/permissions.ts"],"names":[],"mappings":"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"}

package/build/src/modules/shared/task-registry.d.ts

@@ -4,8 +4,19 @@ export interface TaskRecord {
     sessionId: string;
     /** Epoch ms when the task was started; used to detect tasks that never produced output. */
     createdAt?: number;
+    /**
+     * Epoch ms when the task was cancelled. Without it an aborted session whose
+     * last assistant message carries a completed timestamp reports `completed`,
+     * which is indistinguishable from a task that finished on its own.
+     */
+    cancelledAt?: number;
 }
 export declare function registerTask(task: TaskRecord): void;
 export declare function getTask(taskId: string): TaskRecord | undefined;
+/**
+ * Record that a task was cancelled. No-ops for an unknown id so callers do not
+ * have to re-check the registry after aborting.
+ */
+export declare function markTaskCancelled(taskId: string, at?: number): void;
 export declare function removeTask(taskId: string): void;
 //# sourceMappingURL=task-registry.d.ts.map

package/build/src/modules/shared/task-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-registry.d.ts","sourceRoot":"","sources":["../../../../src/modules/shared/task-registry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,QAE5C;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE9D;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,QAExC"}
+{"version":3,"file":"task-registry.d.ts","sourceRoot":"","sources":["../../../../src/modules/shared/task-registry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,QAE5C;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE9D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,GAAE,MAAmB,QAIxE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,QAExC"}

package/build/src/modules/shared/task-registry.js

@@ -5,6 +5,16 @@ export function registerTask(task) {
 export function getTask(taskId) {
     return tasks.get(taskId);
 }
+/**
+ * Record that a task was cancelled. No-ops for an unknown id so callers do not
+ * have to re-check the registry after aborting.
+ */
+export function markTaskCancelled(taskId, at = Date.now()) {
+    const task = tasks.get(taskId);
+    if (!task)
+        return;
+    task.cancelledAt = at;
+}
 export function removeTask(taskId) {
     tasks.delete(taskId);
 }

package/build/src/modules/shared/task-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"task-registry.js","sourceRoot":"","sources":["../../../../src/modules/shared/task-registry.ts"],"names":[],"mappings":"AAQA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,MAAc;IACpC,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACvB,CAAC"}
+{"version":3,"file":"task-registry.js","sourceRoot":"","sources":["../../../../src/modules/shared/task-registry.ts"],"names":[],"mappings":"AAcA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,MAAc;IACpC,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,EAAE,GAAW,IAAI,CAAC,GAAG,EAAE;IACvE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACvB,CAAC"}

package/build/src/modules/shared/usage-limits.d.ts

@@ -0,0 +1,70 @@
+/** Same page, anchored at the section we read — shown as the citation. */
+export declare const USAGE_LIMITS_SOURCE_URL = "https://opencode.ai/docs/es/go/#l\u00EDmites-de-uso";
+export type ModelQuota = {
+    model: string;
+    /** `null` when the docs list the quota as unmetered or unknown. */
+    perFiveHours: number | null;
+    perWeek: number | null;
+    perMonth: number | null;
+};
+export type SpendBudget = {
+    fiveHours: string | null;
+    weekly: string | null;
+    monthly: string | null;
+};
+export type UsageLimits = {
+    source: string;
+    /** ISO timestamp of the fetch that produced this snapshot. */
+    fetchedAt: string;
+    spendBudget: SpendBudget;
+    models: ModelQuota[];
+};
+/**
+ * Resolve where the daily snapshot is persisted.
+ *
+ * Precedence: `OPENCODE_MCP_CACHE_DIR` > `XDG_CACHE_HOME` > `~/.cache`, always
+ * under an `opencode-mcp/` subdirectory. Read lazily so tests can redirect it.
+ */
+export declare function getCachePath(): string;
+/** Snapshot lifetime in ms; `OPENCODE_MCP_LIMITS_TTL_MS` overrides the 24h default. */
+export declare function getCacheTtlMs(): number;
+/**
+ * Return the OpenCode Go usage limits, fetching the docs at most once a day.
+ *
+ * A fresh cache entry short-circuits the network. On a fetch or parse failure
+ * a stale cache entry is still returned, so an offline start degrades to
+ * yesterday's numbers instead of no numbers at all. Returns `null` only when
+ * there is neither a usable cache nor a usable response.
+ */
+export declare function getUsageLimits(): Promise<UsageLimits | null>;
+/**
+ * Pull the spend budget and the per-model request estimates out of the docs
+ * HTML. Returns `null` when the quota table is missing or unrecognisable, so a
+ * page redesign falls back to the cache instead of injecting garbage.
+ */
+export declare function parseUsageLimits(html: string): Omit<UsageLimits, "source" | "fetchedAt"> | null;
+/** How costly one request is against the shared budget, cheapest tier first. */
+export type QuotaTier = "high-volume" | "balanced" | "scarce" | "unlisted";
+/** Bucket a model by its 5h request estimate. Thresholds live here only. */
+export declare function quotaTier(perFiveHours: number | null): QuotaTier;
+/**
+ * Index the snapshot by slugified display name so a live model id from an
+ * OpenCode server (`mimo-v2.5`) joins onto the docs row (`MiMo-V2.5`).
+ *
+ * Verified against a real server: all 22 `opencode-go` model ids match this
+ * way. Ids with no row (the free/preview models on the `opencode` provider)
+ * are simply absent, which callers report as "no published quota".
+ */
+export declare function quotaByModelId(limits: UsageLimits): Map<string, ModelQuota>;
+/**
+ * Render the live half of the quota guidance: where the numbers came from and
+ * the shared dollar budget every model spends against.
+ *
+ * The per-model numbers deliberately stay OUT of the instructions —
+ * opencode_list_agents reports them per model, keyed by the real model id,
+ * which is the only form the agent can act on.
+ */
+export declare function formatUsageLimits(limits: UsageLimits): string;
+/** Render the static tier legend, one line per `tier` value list_agents emits. */
+export declare function formatTierGuide(): string;
+//# sourceMappingURL=usage-limits.d.ts.map

package/build/src/modules/shared/usage-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-limits.d.ts","sourceRoot":"","sources":["../../../../src/modules/shared/usage-limits.ts"],"names":[],"mappings":"AAMA,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,wDAAmD,CAAC;AAsBxF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAOrC;AAED,uFAAuF;AACvF,wBAAgB,aAAa,IAAI,MAAM,CAMtC;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CASlE;AA+BD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,WAAW,CAAC,GAAG,IAAI,CAS/F;AAkID,gFAAgF;AAChF,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAe3E,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAKhE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAE3E;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAK7D;AAED,kFAAkF;AAClF,wBAAgB,eAAe,IAAI,MAAM,CAExC"}