@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/usage/ledger.js

@@ -0,0 +1,142 @@
+import { all, run as execute, transaction, withIndex } from "../core/index.js";
+import { now } from "../core/fs.js";
+import { readAllRuns } from "../sessions/runIndex.js";
+import { findRun, readEvents } from "../sessions/runStore.js";
+import { usagePayloadSchema } from "../sessions/contracts.js";
+const number = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const optionalNumber = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : null);
+const text = (value) => (typeof value === 'string' && value ? value : null);
+/** One row per request: the event's own `request`, or the run's totals when a provider reported only those. */
+export function usageRowsFor(run, events) {
+    const rows = [];
+    let lastTotals = null;
+    let lastTotalsAt = null;
+    for (const event of events) {
+        if (event.type !== 'usage.updated')
+            continue;
+        const parsed = usagePayloadSchema.safeParse(event.payload);
+        if (!parsed.success)
+            continue;
+        const payload = parsed.data;
+        lastTotals = payload;
+        lastTotalsAt = event.timestamp;
+        const request = payload.request;
+        // Without a per-request update the event's fields are cumulative; only the last one may count.
+        if (!request)
+            continue;
+        rows.push({
+            runId: run.id,
+            sequence: event.sequence,
+            requestIndex: request?.index ?? payload.requests ?? rows.length + 1,
+            at: event.timestamp,
+            day: event.timestamp.slice(0, 10),
+            accountId: run.accountId ?? null,
+            projectId: run.projectId ?? null,
+            sessionId: run.sessionId,
+            agentId: run.agentId ?? null,
+            mode: run.mode ?? 'chat',
+            trigger: run.trigger ?? null,
+            provider: request?.provider ?? payload.provider ?? null,
+            model: request?.model ?? payload.model ?? null,
+            inputTokens: number(request?.inputTokens ?? payload.inputTokens),
+            cacheReadTokens: number(request?.cacheReadTokens ?? payload.cacheReadTokens),
+            cacheWriteTokens: number(request?.cacheWriteTokens ?? payload.cacheWriteTokens),
+            outputTokens: number(request?.outputTokens ?? payload.outputTokens),
+            reasoningTokens: number(request?.reasoningTokens ?? payload.reasoningTokens),
+            costUsd: optionalNumber(request?.costUsd ?? payload.costUsd),
+            costSource: text(request?.costSource ?? payload.costSource),
+            contextTokens: optionalNumber(payload.contextTokens),
+            contextWindow: optionalNumber(payload.contextWindow),
+            durationMs: optionalNumber(request?.durationMs),
+            ttftMs: optionalNumber(request?.ttftMs),
+            requests: number(payload.requests)
+        });
+    }
+    // A run whose provider reported totals but no per-request update (an older record) still counts once.
+    if (!rows.length && lastTotals) {
+        rows.push({
+            runId: run.id, sequence: 0, requestIndex: lastTotals.requests ?? 1,
+            at: lastTotalsAt ?? run.endedAt ?? run.startedAt, day: (lastTotalsAt ?? run.endedAt ?? run.startedAt).slice(0, 10),
+            accountId: run.accountId ?? null, projectId: run.projectId ?? null, sessionId: run.sessionId,
+            agentId: run.agentId ?? null, mode: run.mode ?? 'chat', trigger: run.trigger ?? null,
+            provider: lastTotals.provider ?? null, model: lastTotals.model ?? null,
+            inputTokens: number(lastTotals.inputTokens), cacheReadTokens: number(lastTotals.cacheReadTokens),
+            cacheWriteTokens: number(lastTotals.cacheWriteTokens), outputTokens: number(lastTotals.outputTokens),
+            reasoningTokens: number(lastTotals.reasoningTokens), costUsd: optionalNumber(lastTotals.costUsd),
+            costSource: text(lastTotals.costSource), contextTokens: optionalNumber(lastTotals.contextTokens),
+            contextWindow: optionalNumber(lastTotals.contextWindow), durationMs: null, ttftMs: null,
+            requests: number(lastTotals.requests)
+        });
+    }
+    return rows;
+}
+function write(database, run, rows) {
+    execute(database, 'DELETE FROM usage_requests WHERE run_id = ?', run.id);
+    for (const row of rows) {
+        execute(database, `INSERT INTO usage_requests (run_id, sequence, request_index, at, day, account_id, project_id, session_id, agent_id, mode, trigger,
+         provider, model, input_tokens, cache_read_tokens, cache_write_tokens, output_tokens, reasoning_tokens,
+         cost_usd, cost_source, context_tokens, context_window, duration_ms, ttft_ms, requests)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, row.runId, row.sequence, row.requestIndex, row.at, row.day, row.accountId, row.projectId, row.sessionId, row.agentId, row.mode, row.trigger, row.provider, row.model, row.inputTokens, row.cacheReadTokens, row.cacheWriteTokens, row.outputTokens, row.reasoningTokens, row.costUsd, row.costSource, row.contextTokens, row.contextWindow, row.durationMs, row.ttftMs, row.requests);
+    }
+    execute(database, 'INSERT OR REPLACE INTO usage_indexed (run_id, indexed_at, rows) VALUES (?, ?, ?)', run.id, now(), rows.length);
+}
+/** Indexes one run's usage. Idempotent, and safe to call when the index is unavailable. */
+export function indexRunUsage(root, runId) {
+    const run = findRun(root, runId);
+    if (!run)
+        return false;
+    let events;
+    try {
+        events = readEvents(root, runId);
+    }
+    catch {
+        return false;
+    }
+    const rows = usageRowsFor(run, events);
+    try {
+        withIndex(root, (database) => transaction(database, () => write(database, run, rows)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Indexes every run the ledger has not seen yet. Returns how many runs it added. */
+export function syncUsage(root) {
+    const indexed = new Set();
+    try {
+        withIndex(root, (database) => {
+            for (const row of all(database, 'SELECT run_id FROM usage_indexed'))
+                indexed.add(row.run_id);
+        });
+    }
+    catch {
+        return 0;
+    }
+    let added = 0;
+    for (const record of readAllRuns(root)) {
+        if (indexed.has(record.id))
+            continue;
+        if (indexRunUsage(root, record.id))
+            added += 1;
+    }
+    return added;
+}
+/** The ledger's last write, or null when it holds nothing. */
+export function lastIndexedAt(root) {
+    try {
+        return withIndex(root, (database) => all(database, 'SELECT MAX(indexed_at) AS at FROM usage_indexed')[0]?.at ?? null);
+    }
+    catch {
+        return null;
+    }
+}
+/** Run ids the ledger knows, for diagnostics and tests. */
+export function indexedRuns(root) {
+    try {
+        return withIndex(root, (database) => all(database, 'SELECT run_id FROM usage_indexed').map((row) => row.run_id));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/sdk/usage/limits/adapters.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderLimitAdapter } from "./types.js";
+export declare const OPENROUTER_ADAPTER: ProviderLimitAdapter;
+export declare const DEEPSEEK_ADAPTER: ProviderLimitAdapter;
+export declare const ANTHROPIC_ADMIN_ADAPTER: ProviderLimitAdapter;
+/** ChatGPT/Codex plan windows and credits, from the account's own usage endpoint. */
+export declare const CODEX_ADAPTER: ProviderLimitAdapter;
+/** OpenCode Go's 5-hour, weekly and monthly subscription windows. */
+export declare const OPENCODE_GO_ADAPTER: ProviderLimitAdapter;
+/** The documented adapter for a provider, when one exists. Headers remain the other source. */
+export declare function adapterFor(provider: string): ProviderLimitAdapter | null;
+export declare const DOCUMENTED_ADAPTERS: readonly ProviderLimitAdapter[];

package/dist/sdk/usage/limits/adapters.js

@@ -0,0 +1,349 @@
+import { authHeaders, failure, getJson } from "./http.js";
+import { toIso } from "./normalize.js";
+const providerEntry = (provider, observedAt, limit) => ({ ...limit, provider, observedAt, source: 'provider' });
+const percent = (used, limit) => (limit > 0 ? Math.min(100, Math.max(0, (used / limit) * 100)) : null);
+export const OPENROUTER_ADAPTER = {
+    id: 'openrouter-key',
+    providers: ['openrouter'],
+    stability: 'documented',
+    async read({ provider, auth, baseUrl, fetch, signal, now }) {
+        const base = (baseUrl || 'https://openrouter.ai/api/v1').replace(/\/$/, '');
+        const reading = await getJson(fetch, `${base}/key`, authHeaders(auth), signal);
+        if (reading.status < 200 || reading.status >= 300)
+            throw new Error(failure(reading.status, 'OpenRouter'));
+        const data = reading.body?.data;
+        if (!data || typeof data !== 'object')
+            return { limits: [], reason: 'OpenRouter returned no key details.' };
+        const observedAt = now.toISOString();
+        const limits = [];
+        const limit = typeof data.limit === 'number' ? data.limit : null;
+        const remaining = typeof data.limit_remaining === 'number' ? data.limit_remaining : null;
+        if (limit !== null && remaining !== null) {
+            const used = Math.max(0, limit - remaining);
+            limits.push(providerEntry(provider, observedAt, {
+                id: `${provider}:key-credits`,
+                label: 'Key credits',
+                kind: 'credit',
+                unit: 'usd',
+                used,
+                limit,
+                remaining,
+                usedPercent: percent(used, limit),
+                remainingPercent: percent(remaining, limit),
+                status: remaining <= 0 ? 'rejected' : percent(used, limit) >= 80 ? 'warning' : 'allowed'
+            }));
+        }
+        const budgets = Array.isArray(data.budgets) ? data.budgets : [];
+        for (const value of budgets.slice(0, 8)) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const budget = value;
+            const cap = typeof budget.limit_usd === 'number' ? budget.limit_usd : null;
+            const spend = typeof budget.spend_usd === 'number' ? budget.spend_usd : null;
+            if (cap === null || spend === null)
+                continue;
+            const id = typeof budget.budget_id === 'string' ? budget.budget_id : typeof budget.guardrail_id === 'string' ? budget.guardrail_id : `${budget.scope}`;
+            const interval = typeof budget.reset_interval === 'string' ? budget.reset_interval : 'lifetime';
+            limits.push(providerEntry(provider, observedAt, {
+                id: `${provider}:budget-${id}`,
+                label: `Budget (${interval})`,
+                kind: 'credit',
+                unit: 'usd',
+                used: spend,
+                limit: cap,
+                remaining: typeof budget.remaining_usd === 'number' ? budget.remaining_usd : Math.max(0, cap - spend),
+                usedPercent: percent(spend, cap),
+                remainingPercent: percent(typeof budget.remaining_usd === 'number' ? budget.remaining_usd : Math.max(0, cap - spend), cap),
+                resetsAt: toIso(typeof budget.resets_at === 'string' ? budget.resets_at : undefined, now),
+                status: spend >= cap ? 'rejected' : percent(spend, cap) >= 80 ? 'warning' : 'allowed'
+            }));
+        }
+        const free = data.free_model_daily_requests;
+        if (free && typeof free === 'object') {
+            const used = typeof free.used === 'number' ? free.used : null;
+            const cap = typeof free.limit === 'number' ? free.limit : null;
+            if (used !== null && cap !== null) {
+                limits.push(providerEntry(provider, observedAt, {
+                    id: `${provider}:free-daily`,
+                    label: 'Free-model requests today',
+                    kind: 'rate',
+                    unit: 'requests',
+                    used,
+                    limit: cap,
+                    remaining: Math.max(0, cap - used),
+                    usedPercent: percent(used, cap),
+                    remainingPercent: percent(cap - used, cap),
+                    status: used >= cap ? 'rejected' : percent(used, cap) >= 80 ? 'warning' : 'allowed'
+                }));
+            }
+        }
+        return {
+            limits,
+            plan: data.is_free_tier === true ? 'Free tier' : null,
+            reason: limits.length ? null : 'OpenRouter reports no credit limit for this key.'
+        };
+    }
+};
+export const DEEPSEEK_ADAPTER = {
+    id: 'deepseek-balance',
+    providers: ['deepseek'],
+    stability: 'documented',
+    async read({ provider, auth, baseUrl, fetch, signal, now }) {
+        const base = (baseUrl || 'https://api.deepseek.com').replace(/\/$/, '');
+        const reading = await getJson(fetch, `${base}/user/balance`, authHeaders(auth), signal);
+        if (reading.status < 200 || reading.status >= 300)
+            throw new Error(failure(reading.status, 'DeepSeek'));
+        const body = reading.body;
+        const available = body?.is_available === true;
+        const infos = Array.isArray(body?.balance_infos) ? body.balance_infos : [];
+        const observedAt = now.toISOString();
+        const limits = infos.slice(0, 4).flatMap((info) => {
+            if (!info || typeof info !== 'object')
+                return [];
+            const currency = typeof info.currency === 'string' ? info.currency : 'USD';
+            const total = typeof info.total_balance === 'string' ? Number(info.total_balance) : typeof info.total_balance === 'number' ? info.total_balance : null;
+            if (total === null || !Number.isFinite(total))
+                return [];
+            return [providerEntry(provider, observedAt, {
+                    id: `${provider}:balance-${currency}`,
+                    label: `Balance (${currency})`,
+                    kind: 'credit',
+                    unit: 'currency',
+                    remaining: total,
+                    detail: currency,
+                    status: available ? (total > 0 ? 'allowed' : 'rejected') : 'rejected'
+                })];
+        });
+        return { limits, reason: limits.length ? null : 'DeepSeek returned no balance.' };
+    }
+};
+export const ANTHROPIC_ADMIN_ADAPTER = {
+    id: 'anthropic-rate-limits',
+    providers: ['anthropic'],
+    stability: 'documented',
+    async read({ provider, credentialType, auth, baseUrl, fetch, signal, now }) {
+        // A subscription sign-in is not an organization administrator.
+        if (credentialType !== 'api_key')
+            return { limits: [], reason: 'Organization limits need an Anthropic admin API key.' };
+        const base = (baseUrl || 'https://api.anthropic.com').replace(/\/$/, '');
+        const headers = { ...authHeaders(auth), 'anthropic-version': '2023-06-01' };
+        const reading = await getJson(fetch, `${base}/v1/organizations/rate_limits`, headers, signal);
+        if (reading.status < 200 || reading.status >= 300)
+            throw new Error(failure(reading.status, 'Anthropic'));
+        const data = reading.body?.data;
+        if (!Array.isArray(data))
+            return { limits: [], reason: 'Anthropic returned no rate limits for this credential.' };
+        const observedAt = now.toISOString();
+        const limits = [];
+        for (const value of data.slice(0, 24)) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const group = value.group;
+            const groupName = typeof group?.display_name === 'string' ? group.display_name : typeof group?.type === 'string' ? group.type : 'Organization';
+            const groupId = typeof group?.id === 'string' ? group.id : groupName;
+            const entries = Array.isArray(value.limits) ? value.limits : [];
+            for (const item of entries) {
+                const type = typeof item.type === 'string' ? item.type : '';
+                const cap = typeof item.value === 'number' ? item.value : null;
+                if (!type || cap === null)
+                    continue;
+                limits.push(providerEntry(provider, observedAt, {
+                    id: `${provider}:configured-${groupId}-${type}`,
+                    label: `${groupName} · ${type.replaceAll('_', ' ')}`,
+                    kind: 'configured',
+                    unit: type.includes('token') ? 'tokens' : 'requests',
+                    limit: cap,
+                    windowMinutes: 1,
+                    status: 'configured',
+                    detail: 'Configured limit, not current usage'
+                }));
+            }
+        }
+        return { limits, reason: limits.length ? null : 'Anthropic returned no configured rate limits.' };
+    }
+};
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+const pick = (value, keys) => {
+    if (!value)
+        return undefined;
+    for (const key of keys)
+        if (value[key] !== undefined && value[key] !== null)
+            return value[key];
+    return undefined;
+};
+const numeric = (value) => {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value.trim());
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+};
+const clampPercent = (value) => value === null ? null : Math.min(100, Math.max(0, value));
+const windowLabel = (seconds) => {
+    if (seconds === null || seconds <= 0)
+        return 'Usage window';
+    const minutes = Math.round(seconds / 60);
+    if (minutes === 300)
+        return '5-hour window';
+    if (minutes === 10_080)
+        return 'Weekly window';
+    if (minutes >= 1_440)
+        return `${Math.round(minutes / 1_440)}-day window`;
+    if (minutes >= 60)
+        return `${Math.round(minutes / 60)}-hour window`;
+    return `${minutes} min window`;
+};
+const epochIso = (value) => {
+    if (value === null)
+        return null;
+    // The Codex usage endpoint reports seconds; tolerate milliseconds too.
+    const millis = value > 10_000_000_000 ? value : value * 1_000;
+    const date = new Date(millis);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+};
+/** The account id Pi's Codex OAuth credential carries in its access-token claims. */
+function codexAccountId(token) {
+    if (!token)
+        return null;
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        const auth = record(payload['https://api.openai.com/auth']);
+        const id = auth?.chatgpt_account_id;
+        return typeof id === 'string' && id ? id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** ChatGPT/Codex plan windows and credits, from the account's own usage endpoint. */
+export const CODEX_ADAPTER = {
+    id: 'codex-usage',
+    providers: ['openai-codex'],
+    stability: 'documented',
+    async read({ provider, auth, baseUrl, fetch, signal, now }) {
+        const base = (baseUrl || 'https://chatgpt.com/backend-api').replace(/\/$/, '');
+        const headers = { ...authHeaders(auth), accept: 'application/json' };
+        const accountId = codexAccountId(auth.apiKey);
+        if (accountId)
+            headers['chatgpt-account-id'] = accountId;
+        const reading = await getJson(fetch, `${base}/wham/usage`, headers, signal);
+        if (reading.status === 401 || reading.status === 403)
+            throw new Error('The ChatGPT sign-in cannot read Codex usage. Sign in again in Accounts.');
+        if (reading.status < 200 || reading.status >= 300)
+            throw new Error(failure(reading.status, 'Codex'));
+        const root = record(reading.body) ?? {};
+        const rate = record(pick(root, ['ratelimit', 'rateLimit', 'rate_limit']));
+        const observedAt = now.toISOString();
+        const limits = [];
+        for (const [name, keys] of [
+            ['primary', ['primarywindow', 'primaryWindow', 'primary_window']],
+            ['secondary', ['secondarywindow', 'secondaryWindow', 'secondary_window']]
+        ]) {
+            const window = record(pick(rate, keys));
+            const used = numeric(pick(window, ['usedpercent', 'usedPercent', 'used_percent']));
+            const reset = numeric(pick(window, ['resetat', 'resetAt', 'reset_at']));
+            const windowSeconds = numeric(pick(window, ['limitwindowseconds', 'limitWindowSeconds', 'limit_window_seconds']));
+            if (used === null && reset === null && windowSeconds === null)
+                continue;
+            const usedPercent = clampPercent(used);
+            limits.push(providerEntry(provider, observedAt, {
+                id: `${provider}:window-${name}`,
+                label: windowLabel(windowSeconds),
+                kind: 'window',
+                unit: 'percent',
+                usedPercent,
+                remainingPercent: usedPercent === null ? null : 100 - usedPercent,
+                windowMinutes: windowSeconds === null ? null : Math.round(windowSeconds / 60),
+                resetsAt: epochIso(reset),
+                status: usedPercent === null ? 'allowed' : usedPercent >= 100 ? 'rejected' : usedPercent >= 80 ? 'warning' : 'allowed'
+            }));
+        }
+        const credits = record(pick(root, ['credits']));
+        const balance = numeric(pick(credits, ['balance']));
+        const unlimited = pick(credits, ['unlimited']) === true;
+        const hasCredits = pick(credits, ['hascredits', 'hasCredits', 'has_credits']);
+        // Credits are an optional extra on ChatGPT plans: an empty balance is not a used-up plan window.
+        const includeCredits = unlimited || (balance !== null && (hasCredits === true || balance > 0));
+        if (includeCredits) {
+            limits.push(providerEntry(provider, observedAt, {
+                id: `${provider}:credits`,
+                label: 'Credits',
+                kind: 'credit',
+                unit: 'count',
+                remaining: unlimited ? null : balance,
+                status: unlimited ? 'allowed' : balance !== null && balance > 0 ? 'allowed' : 'warning',
+                detail: unlimited ? 'Unlimited credits' : 'ChatGPT credits'
+            }));
+        }
+        const plan = pick(root, ['plantype', 'planType', 'plan_type']);
+        return {
+            limits,
+            plan: typeof plan === 'string' && plan ? `ChatGPT ${plan}` : null,
+            reason: limits.length ? null : 'The ChatGPT account reported no Codex windows.'
+        };
+    }
+};
+/** OpenCode Go's 5-hour, weekly and monthly subscription windows. */
+export const OPENCODE_GO_ADAPTER = {
+    id: 'opencode-go-usage',
+    providers: ['opencode-go'],
+    stability: 'documented',
+    async read({ provider, auth, fetch, signal, now }) {
+        const reading = await getJson(fetch, 'https://opencode.ai/zen/go/v1/usage', { ...authHeaders(auth), accept: 'application/json' }, signal);
+        if (reading.status === 401 || reading.status === 403)
+            throw new Error('The OpenCode API key cannot read Go usage. Check the key in Accounts.');
+        if (reading.status < 200 || reading.status >= 300)
+            throw new Error(failure(reading.status, 'OpenCode Go'));
+        const root = record(reading.body) ?? {};
+        const usage = record(pick(root, ['usage']));
+        if (!usage)
+            return { limits: [], reason: 'OpenCode Go returned no usage windows.' };
+        const renewsAt = typeof pick(usage, ['renewsAt', 'renews_at', 'endsAt', 'ends_at']) === 'string'
+            ? toIso(String(pick(usage, ['renewsAt', 'renews_at', 'endsAt', 'ends_at'])), now)
+            : typeof pick(root, ['renewsAt', 'renews_at']) === 'string'
+                ? toIso(String(pick(root, ['renewsAt', 'renews_at'])), now)
+                : null;
+        const observedAt = now.toISOString();
+        const limits = [];
+        const windows = [
+            { key: 'rolling', label: '5-hour window', minutes: 300 },
+            { key: 'weekly', label: 'Weekly window', minutes: 10_080 },
+            { key: 'monthly', label: 'Monthly window', minutes: 43_200 }
+        ];
+        for (const window of windows) {
+            const value = record(pick(usage, [window.key, `${window.key}Usage`]));
+            const usedPercent = clampPercent(numeric(pick(value, ['percent', 'usagePercent', 'usage_percent'])));
+            if (usedPercent === null)
+                continue;
+            const resetInSec = numeric(pick(value, ['resetInSec', 'reset_in_sec', 'resetInSeconds', 'resetsInSec']));
+            const resetAt = pick(value, ['resetAt', 'reset_at', 'resetsAt', 'resets_at', 'resetTime', 'reset_time']);
+            const resetsAt = resetInSec !== null
+                ? new Date(now.getTime() + Math.max(0, resetInSec) * 1_000).toISOString()
+                : typeof resetAt === 'string' ? toIso(resetAt, now) : window.key === 'monthly' ? renewsAt : null;
+            limits.push(providerEntry(provider, observedAt, {
+                id: `${provider}:window-${window.key}`,
+                label: window.label,
+                kind: 'window',
+                unit: 'percent',
+                usedPercent,
+                remainingPercent: 100 - usedPercent,
+                windowMinutes: window.minutes,
+                resetsAt,
+                status: usedPercent >= 100 ? 'rejected' : usedPercent >= 80 ? 'warning' : 'allowed',
+                detail: window.key === 'monthly' ? 'Monthly allowance' : null
+            }));
+        }
+        return { limits, reason: limits.length ? null : 'OpenCode Go returned no usage windows.' };
+    }
+};
+const ADAPTERS = [OPENROUTER_ADAPTER, DEEPSEEK_ADAPTER, ANTHROPIC_ADMIN_ADAPTER, CODEX_ADAPTER, OPENCODE_GO_ADAPTER];
+/** The documented adapter for a provider, when one exists. Headers remain the other source. */
+export function adapterFor(provider) {
+    return ADAPTERS.find((adapter) => adapter.providers.includes(provider)) ?? null;
+}
+export const DOCUMENTED_ADAPTERS = ADAPTERS;

package/dist/sdk/usage/limits/capture.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderResponseLike } from "./types.js";
+type Observe = (provider: string, response: ProviderResponseLike) => void;
+/**
+ * Wraps every provider once so responses reach `observe`. Repeated calls do nothing, and a runtime
+ * that cannot be wrapped is used unchanged.
+ */
+export declare function observeProviderResponses(models: unknown, observe: Observe): void;
+export {};

package/dist/sdk/usage/limits/capture.js

@@ -0,0 +1,47 @@
+const WRAPPED = Symbol('xingular-usage-observed');
+function wrap(provider, method, observe) {
+    if (typeof method !== 'function')
+        return method;
+    return function observed(model, context, options) {
+        const previous = options?.onResponse;
+        const next = {
+            ...(options ?? {}),
+            onResponse: async (response) => {
+                try {
+                    if (typeof previous === 'function')
+                        await previous(response, model);
+                }
+                finally {
+                    try {
+                        observe(String(model?.provider ?? provider.id), response);
+                    }
+                    catch { /* observation is best effort */ }
+                }
+            }
+        };
+        return method.call(this, model, context, next);
+    };
+}
+/**
+ * Wraps every provider once so responses reach `observe`. Repeated calls do nothing, and a runtime
+ * that cannot be wrapped is used unchanged.
+ */
+export function observeProviderResponses(models, observe) {
+    const target = models;
+    if (!target || typeof target.getProviders !== 'function' || typeof target.setProvider !== 'function')
+        return;
+    for (const provider of target.getProviders()) {
+        if (provider[WRAPPED])
+            continue;
+        try {
+            const clone = Object.create(Object.getPrototypeOf(provider), Object.getOwnPropertyDescriptors(provider));
+            clone.stream = wrap(provider, provider.stream, observe);
+            clone.streamSimple = wrap(provider, provider.streamSimple, observe);
+            clone[WRAPPED] = true;
+            target.setProvider(clone);
+        }
+        catch {
+            // An unusual provider is left as it is; limits simply stay unavailable for it.
+        }
+    }
+}

package/dist/sdk/usage/limits/http.d.ts

@@ -0,0 +1,12 @@
+import type { FetchLike } from "./types.js";
+export interface JsonReading {
+    status: number;
+    body: unknown;
+}
+export declare function getJson(fetchImpl: FetchLike, url: string, headers: Record<string, string>, signal: AbortSignal): Promise<JsonReading>;
+/** The headers a provider endpoint needs, from the credential Pi resolved. */
+export declare function authHeaders(auth: {
+    apiKey?: string;
+    headers?: Record<string, string | null>;
+}): Record<string, string>;
+export declare function failure(status: number, provider: string): string;

package/dist/sdk/usage/limits/http.js

@@ -0,0 +1,51 @@
+// A small, bounded read of a provider's own usage endpoint. It sends only the account's resolved
+// credential, never a body, never follows a redirect elsewhere, and never puts a credential in an
+// error message.
+import { scrub } from "../../accounts/store.js";
+const MAX_BODY = 200_000;
+const TIMEOUT_MS = 5_000;
+function allowed(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' || (parsed.protocol === 'http:' && (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1'));
+    }
+    catch {
+        return false;
+    }
+}
+export async function getJson(fetchImpl, url, headers, signal) {
+    if (!allowed(url))
+        throw new Error('The provider endpoint is not an HTTPS address.');
+    const timeout = AbortSignal.timeout(TIMEOUT_MS);
+    const combined = typeof AbortSignal.any === 'function' ? AbortSignal.any([signal, timeout]) : timeout;
+    const response = await fetchImpl(url, { headers, signal: combined, redirect: 'error' });
+    const text = (await response.text()).slice(0, MAX_BODY);
+    if (!text.trim())
+        return { status: response.status, body: null };
+    try {
+        return { status: response.status, body: JSON.parse(text) };
+    }
+    catch {
+        throw new Error(scrub(`The provider returned an unreadable response (${response.status}).`));
+    }
+}
+/** The headers a provider endpoint needs, from the credential Pi resolved. */
+export function authHeaders(auth) {
+    const headers = {};
+    for (const [key, value] of Object.entries(auth.headers ?? {}))
+        if (typeof value === 'string' && value)
+            headers[key] = value;
+    if (auth.apiKey && !Object.keys(headers).some((key) => key.toLowerCase() === 'authorization' || key.toLowerCase() === 'x-api-key')) {
+        headers.authorization = `Bearer ${auth.apiKey}`;
+    }
+    return headers;
+}
+export function failure(status, provider) {
+    if (status === 401 || status === 403)
+        return `The ${provider} credential cannot read usage limits (a key with more access is required).`;
+    if (status === 404)
+        return `The ${provider} usage endpoint is not available at this address.`;
+    if (status === 429)
+        return `The ${provider} usage endpoint is rate limited. Try again later.`;
+    return `The ${provider} usage endpoint returned ${status}.`;
+}

package/dist/sdk/usage/limits/normalize.d.ts

@@ -0,0 +1,15 @@
+import type { Limit } from "../../accounts/store.js";
+import type { ProviderResponseLike } from "./types.js";
+export declare function toNumber(value: string | undefined): number | null;
+/** A reset time as an ISO instant: epoch seconds or milliseconds, a duration, or a date string. */
+export declare function toIso(value: string | undefined, now: Date): string | null;
+export interface NormalizedHeaders {
+    limits: Limit[];
+}
+/**
+ * Reads every limit family present in one provider response. `provider` is the Pi provider id;
+ * the returned ids are namespaced with it so two providers never overwrite each other.
+ */
+export declare function normalizeHeaders(provider: string, response: ProviderResponseLike, now?: Date): NormalizedHeaders;
+/** Only the limit-bearing headers, bounded, so a child process never relays an entire response. */
+export declare function limitHeaders(input: Record<string, string>): Record<string, string>;