@xingular/harness 1.0.0 → 1.2.0

package/dist/sdk/tools/getCapabilities.d.ts

@@ -0,0 +1,31 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { ToolSpec } from "./types.js";
+export declare const GET_CAPABILITIES = "get_capabilities";
+export declare const CAPABILITY_DISCOVERY: {
+    readonly name: "get_capabilities";
+    readonly label: "Inspect current capabilities";
+    readonly description: "List the tools callable in this run, or inspect one tool and its input schema. Availability is not permission: calls still follow the gate. Disabled, unavailable and unregistered tools are not advertised as callable.";
+    readonly parameters: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly tool: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 200;
+                readonly description: "An exact tool name to inspect. Omit to list callable tools.";
+            };
+        };
+    };
+};
+export interface RegisteredCapabilityTool {
+    name: string;
+    description?: string;
+    parameters?: unknown;
+}
+export declare function describeCapabilities(input: {
+    capabilities: CapabilitySet;
+    active: readonly string[];
+    registered: readonly RegisteredCapabilityTool[];
+}, name?: string): Record<string, unknown>;
+export declare function getCapabilitiesTool(snapshot: () => Parameters<typeof describeCapabilities>[0]): ToolSpec;

package/dist/sdk/tools/getCapabilities.js

@@ -0,0 +1,34 @@
+export const GET_CAPABILITIES = 'get_capabilities';
+export const CAPABILITY_DISCOVERY = {
+    name: GET_CAPABILITIES,
+    label: 'Inspect current capabilities',
+    description: 'List the tools callable in this run, or inspect one tool and its input schema. Availability is not permission: calls still follow the gate. Disabled, unavailable and unregistered tools are not advertised as callable.',
+    parameters: {
+        type: 'object', additionalProperties: false,
+        properties: { tool: { type: 'string', minLength: 1, maxLength: 200, description: 'An exact tool name to inspect. Omit to list callable tools.' } }
+    }
+};
+export function describeCapabilities(input, name) {
+    const allowed = new Set(input.capabilities.tools);
+    const active = new Set(input.active);
+    const tools = input.registered.filter(tool => allowed.has(tool.name) && active.has(tool.name));
+    if (name) {
+        const tool = tools.find(tool => tool.name === name);
+        return tool
+            ? { tool: { name: tool.name, description: tool.description ?? '', ...(tool.parameters !== undefined ? { inputSchema: tool.parameters } : {}), state: 'callable', permission: 'checked per call' } }
+            : { tool: { name, state: 'unavailable', reason: 'This tool is not callable in the current run.' } };
+    }
+    return {
+        tools: tools.map(tool => ({ name: tool.name, description: tool.description ?? '', state: 'callable' })),
+        connectors: [...input.capabilities.connectors],
+        permission: 'Availability does not grant permission. Every call still passes the gate.'
+    };
+}
+export function getCapabilitiesTool(snapshot) {
+    return {
+        ...CAPABILITY_DISCOVERY,
+        readOnly: true,
+        parameters: Type => Type.Unsafe(CAPABILITY_DISCOVERY.parameters),
+        execute: async (input) => JSON.stringify(describeCapabilities(snapshot(), typeof input.tool === 'string' ? input.tool : undefined))
+    };
+}

package/dist/sdk/tools/harnessTools.d.ts

@@ -1,6 +1,8 @@
 import type { CallerContext } from "../core/caller.js";
+import type { HarnessToolDefinition } from "./definitions.js";
 import { type DispatchEnv } from "./dispatch.js";
 import type { ToolSpec } from "./types.js";
 export declare function harnessTools(env: DispatchEnv, context: CallerContext, options?: {
     variantDir?: string | null;
+    definitions?: readonly HarnessToolDefinition[];
 }): ToolSpec[];

package/dist/sdk/tools/harnessTools.js

@@ -1,7 +1,7 @@
 import { describeTool, HARNESS_TOOLS } from "./definitions.js";
 import { dispatch } from "./dispatch.js";
 export function harnessTools(env, context, options = {}) {
-    return HARNESS_TOOLS.map((tool) => ({
+    return (options.definitions ?? HARNESS_TOOLS).map((tool) => ({
         name: tool.name,
         label: tool.label,
         description: describeTool(tool, env.productName),

package/dist/sdk/tools/spawnSubagent.js

@@ -1,5 +1,5 @@
 import { HarnessError, invalid } from "../core/errors.js";
-import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, SUBAGENT_RECEIPT } from "../sessions/subagents.js";
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, SUBAGENT_RECEIPT, MAX_SUBAGENT_TITLE_WORDS, subagentTitle } from "../sessions/subagents.js";
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, subagentDepth, subagentReport } from "../sessions/subagents.js";
 function reported(parentRunId, results, spawned) {
     const included = [];
@@ -27,10 +27,20 @@ export function subagentTools(service, parentRunId) {
     return [{
             name: SPAWN_SUBAGENT,
             label: 'Start a subagent',
-            description: 'Start a fresh child run for independent work: yourself, or one of your subagents when you name it in agent. Give a complete brief: the child has no conversation history and no more capabilities than you. Returns its run ID immediately by default so you can continue working. Results arrive automatically before you finish. Use wait_subagents to join selected children, or wait: true for an inline result. Stopping you stops your children.',
-            parameters: (Type) => Type.Object({ brief: Type.String(), agent: Type.Optional(Type.String({ description: 'The name of one of your subagents; omit for a copy of yourself' })), tools: Type.Optional(Type.Array(Type.String())), wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' })) }),
+            description: 'Start a fresh child run for independent work. Delegate substantial, bounded tasks that benefit from a separate context, not simple lookups, tiny edits or tightly coupled steps. Prefer a named specialist profile; omit agent only when no profile fits. Plan mode permits only eligible read-only research profiles. Give a short title and a self-contained brief: the child has no conversation history and no more capabilities than you. Returns its run ID immediately by default so you can continue other useful work. Results arrive automatically before you finish. Use wait_subagents when you need results before proceeding, or wait: true for an inline result. Avoid overlapping write assignments. Stopping you stops your children.',
+            planModeSafe: input => service.planSpawnRefusal(parentRunId, input) === null,
+            parameters: (Type) => Type.Object({
+                title: Type.String({ description: `A short imperative title for the roster, at most ${MAX_SUBAGENT_TITLE_WORDS} words, such as "Map the auth flow"` }),
+                brief: Type.String({ description: 'A self-contained task: goal, relevant context or paths, non-goals, expected result, and acceptance or verification. The child cannot see this conversation.' }),
+                agent: Type.Optional(Type.String({ description: 'The name of a specialist profile from your Subagents list; omit only when no listed profile fits (omitting starts an unprofiled copy)' })),
+                tools: Type.Optional(Type.Array(Type.String())),
+                wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' }))
+            }),
             execute: execute(async (input) => {
-                const child = await service.spawn({ parentRunId, brief: input.brief, agent: input.agent, tools: input.tools, wait: input.wait });
+                const title = subagentTitle(input.title);
+                if (!title)
+                    throw invalid(`Give the subagent a title of at most ${MAX_SUBAGENT_TITLE_WORDS} words, with no control characters.`);
+                const child = await service.spawn({ parentRunId, brief: input.brief, title, agent: input.agent, tools: input.tools, wait: input.wait });
                 if (input.wait === true)
                     return reported(parentRunId, service.results({ parentRunId, runIds: [child.runId] }), [child.runId]);
                 return { text: JSON.stringify(child), details: { [SUBAGENT_RECEIPT]: { version: 1, ownerRunId: parentRunId, spawned: [child.runId] } } };

package/dist/sdk/usage/analytics.d.ts

@@ -0,0 +1,20 @@
+import { type PriceRates } from "../sessions/pricing.js";
+import type { UsageFilter, UsagePeriod, UsageSummary } from "./types.js";
+/** A price lookup, injected so tests never load Pi's catalogue. */
+export type RatesLookup = (provider: string, model: string) => Promise<PriceRates | null>;
+/** The local-day boundaries `period` covers, expressed as UTC instants. */
+export declare function periodRange(period: UsagePeriod, offsetMinutes: number, now?: Date): {
+    from: string | null;
+    to: string;
+};
+export interface SummaryInput {
+    root: string;
+    filter: UsageFilter;
+    period: UsagePeriod;
+    timezoneOffsetMinutes: number;
+    /** Model labels are `provider/model`; only accounts need a lookup. */
+    accountLabel?: (accountId: string) => string;
+    rates?: RatesLookup;
+    now?: Date;
+}
+export declare function summarize(input: SummaryInput): Promise<UsageSummary>;

package/dist/sdk/usage/analytics.js

@@ -0,0 +1,151 @@
+import { all, withIndex } from "../core/index.js";
+import { costAt } from "../sessions/pricing.js";
+import { lastIndexedAt } from "./ledger.js";
+const ROW_LIMIT = 10;
+const DAY_LIMIT = 400;
+const UNPRICED_LIMIT = 40;
+const zero = (value) => value ?? 0;
+const round = (value, places = 6) => Math.round(value * 10 ** places) / 10 ** places;
+function totals(row, estimated = 0) {
+    const input = zero(row?.input);
+    const cacheRead = zero(row?.cacheRead);
+    const cacheWrite = zero(row?.cacheWrite);
+    const cost = row?.cost == null && !estimated ? null : round(zero(row?.cost) + estimated);
+    const cached = cacheRead + input + cacheWrite;
+    return {
+        requests: zero(row?.requests),
+        inputTokens: input,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+        outputTokens: zero(row?.output),
+        reasoningTokens: zero(row?.reasoning),
+        costUsd: cost,
+        estimatedCostUsd: estimated ? round(estimated) : 0,
+        unpricedRequests: zero(row?.unpriced),
+        avgTtftMs: row?.ttft == null ? null : Math.round(row.ttft),
+        avgDurationMs: row?.duration == null ? null : Math.round(row.duration),
+        cacheHitPercent: cached ? Math.round((cacheRead / cached) * 1000) / 10 : null
+    };
+}
+/** The local-day boundaries `period` covers, expressed as UTC instants. */
+export function periodRange(period, offsetMinutes, now = new Date()) {
+    const to = now.toISOString();
+    if (period === 'all')
+        return { from: null, to };
+    const shifted = new Date(now.getTime() + offsetMinutes * 60_000);
+    const midnight = Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate());
+    const days = period === 'today' ? 0 : period === '7d' ? 6 : 29;
+    return { from: new Date(midnight - days * 86_400_000 - offsetMinutes * 60_000).toISOString(), to };
+}
+function where(filter, from, to) {
+    const clauses = ['at < ?'];
+    const params = [to];
+    if (from) {
+        clauses.push('at >= ?');
+        params.push(from);
+    }
+    if (filter.session) {
+        clauses.push('session_id = ?');
+        params.push(filter.session);
+    }
+    if (filter.account) {
+        clauses.push('account_id = ?');
+        params.push(filter.account);
+    }
+    if (filter.project) {
+        clauses.push('project_id = ?');
+        params.push(filter.project);
+    }
+    return { sql: clauses.join(' AND '), params };
+}
+const SUM = `COUNT(*) AS requests, SUM(input_tokens) AS input, SUM(cache_read_tokens) AS cacheRead,
+  SUM(cache_write_tokens) AS cacheWrite, SUM(output_tokens) AS output, SUM(reasoning_tokens) AS reasoning,
+  SUM(cost_usd) AS cost, SUM(CASE WHEN cost_usd IS NULL THEN 1 ELSE 0 END) AS unpriced,
+  AVG(ttft_ms) AS ttft, AVG(duration_ms) AS duration`;
+function grouped(database, column, clause, params, limit) {
+    return all(database, `SELECT ${column} AS key, ${SUM} FROM usage_requests WHERE ${clause}
+     GROUP BY ${column} ORDER BY SUM(COALESCE(input_tokens,0)+COALESCE(cache_read_tokens,0)+COALESCE(cache_write_tokens,0)+COALESCE(output_tokens,0)) DESC
+     LIMIT ${limit}`, ...params).map((row) => ({ key: row.key ?? '', values: row }));
+}
+function modelKey(provider, model) {
+    return `${provider ?? 'unknown'}/${model ?? 'unknown'}`;
+}
+/** Estimates the cost of the requests a provider did not price, grouped by model. */
+async function estimate(database, clause, params, rates) {
+    const rows = all(database, `SELECT provider, model, ${SUM} FROM usage_requests
+     WHERE ${clause} AND cost_usd IS NULL GROUP BY provider, model LIMIT ${UNPRICED_LIMIT}`, ...params);
+    const estimates = new Map();
+    for (const row of rows) {
+        if (!row.model)
+            continue;
+        const table = await rates(row.provider ?? '', row.model).catch(() => null);
+        if (!table)
+            continue;
+        const cost = costAt(table, {
+            inputTokens: zero(row.input),
+            outputTokens: zero(row.output),
+            cacheReadTokens: zero(row.cacheRead),
+            cacheWriteTokens: zero(row.cacheWrite)
+        });
+        const key = modelKey(row.provider, row.model);
+        const previous = estimates.get(key) ?? { cost: 0, requests: 0 };
+        estimates.set(key, { cost: previous.cost + cost, requests: previous.requests + zero(row.requests) });
+    }
+    return estimates;
+}
+export async function summarize(input) {
+    const offset = Number.isFinite(input.timezoneOffsetMinutes) ? Math.max(-840, Math.min(840, Math.trunc(input.timezoneOffsetMinutes))) : 0;
+    const { from, to } = periodRange(input.period, offset, input.now ?? new Date());
+    const { sql: clause, params } = where(input.filter, from, to);
+    const shift = `${offset >= 0 ? '+' : ''}${offset} minutes`;
+    const label = input.accountLabel ?? ((id) => id.slice(0, 8));
+    const summary = withIndex(input.root, (database) => {
+        const total = all(database, `SELECT ${SUM} FROM usage_requests WHERE ${clause}`, ...params)[0];
+        const days = all(database, `SELECT date(at, ?) AS day, ${SUM} FROM usage_requests WHERE ${clause}
+       GROUP BY day ORDER BY day DESC LIMIT ${DAY_LIMIT}`, shift, ...params);
+        return {
+            total,
+            days: days.reverse(),
+            byModel: grouped(database, "COALESCE(provider,'unknown') || '/' || COALESCE(model,'unknown')", clause, params, ROW_LIMIT + 1),
+            byProvider: grouped(database, "COALESCE(provider,'unknown')", clause, params, ROW_LIMIT + 1),
+            byAccount: grouped(database, "COALESCE(account_id,'')", clause, params, ROW_LIMIT + 1),
+            bySession: grouped(database, 'session_id', clause, params, ROW_LIMIT + 1)
+        };
+    });
+    const estimates = input.rates && zero(summary.total?.unpriced)
+        ? await withIndex(input.root, (database) => estimate(database, clause, params, input.rates))
+        : new Map();
+    const estimated = [...estimates.values()].reduce((sum, entry) => sum + entry.cost, 0);
+    const row = (key, values, labelText, detail) => {
+        const estimateEntry = estimates.get(key);
+        return { key, label: labelText, detail, ...totals(values, estimateEntry?.cost ?? 0) };
+    };
+    const modelRows = summary.byModel.map((entry) => row(entry.key, entry.values, entry.key, null));
+    const truncate = (entries) => entries.length > ROW_LIMIT;
+    const accountRows = summary.byAccount.slice(0, ROW_LIMIT).map((entry) => row(entry.key, entry.values, entry.key ? label(entry.key) : 'No account', null));
+    const sessionRows = summary.bySession.slice(0, ROW_LIMIT).map((entry) => row(entry.key, entry.values, entry.key.slice(0, 12), null));
+    const days = summary.days.map((entry) => ({
+        day: entry.day,
+        requests: zero(entry.requests),
+        inputTokens: zero(entry.input),
+        cacheReadTokens: zero(entry.cacheRead),
+        outputTokens: zero(entry.output),
+        costUsd: entry.cost == null ? null : round(entry.cost)
+    }));
+    return {
+        scope: input.filter.session ? 'session' : input.filter.project ? 'project' : input.filter.account ? 'account' : 'all',
+        period: input.period,
+        from,
+        to,
+        timezoneOffsetMinutes: offset,
+        generatedAt: new Date().toISOString(),
+        totals: totals(summary.total, estimated),
+        byDay: days,
+        byModel: modelRows.slice(0, ROW_LIMIT),
+        byProvider: summary.byProvider.slice(0, ROW_LIMIT).map((entry) => row(entry.key, entry.values, entry.key, null)),
+        byAccount: accountRows,
+        bySession: sessionRows,
+        truncated: truncate(summary.byModel) || truncate(summary.byProvider) || truncate(summary.byAccount) || truncate(summary.bySession),
+        lastIndexedAt: lastIndexedAt(input.root)
+    };
+}

package/dist/sdk/usage/ledger.d.ts

@@ -0,0 +1,38 @@
+import { type RunEvent, type RunRecord } from "../sessions/contracts.js";
+export interface UsageRow {
+    runId: string;
+    sequence: number;
+    requestIndex: number;
+    at: string;
+    day: string;
+    accountId: string | null;
+    projectId: string | null;
+    sessionId: string;
+    agentId: string | null;
+    mode: string;
+    trigger: string | null;
+    provider: string | null;
+    model: string | null;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    costUsd: number | null;
+    costSource: string | null;
+    contextTokens: number | null;
+    contextWindow: number | null;
+    durationMs: number | null;
+    ttftMs: number | null;
+    requests: number;
+}
+/** One row per request: the event's own `request`, or the run's totals when a provider reported only those. */
+export declare function usageRowsFor(run: RunRecord, events: readonly RunEvent[]): UsageRow[];
+/** Indexes one run's usage. Idempotent, and safe to call when the index is unavailable. */
+export declare function indexRunUsage(root: string, runId: string): boolean;
+/** Indexes every run the ledger has not seen yet. Returns how many runs it added. */
+export declare function syncUsage(root: string): number;
+/** The ledger's last write, or null when it holds nothing. */
+export declare function lastIndexedAt(root: string): string | null;
+/** Run ids the ledger knows, for diagnostics and tests. */
+export declare function indexedRuns(root: string): string[];

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[];