@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +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

@@ -0,0 +1,20 @@
+import { describeTool, HARNESS_TOOLS } from "./definitions.js";
+import { dispatch } from "./dispatch.js";
+export function harnessTools(env, context, options = {}) {
+    return (options.definitions ?? HARNESS_TOOLS).map((tool) => ({
+        name: tool.name,
+        label: tool.label,
+        description: describeTool(tool, env.productName),
+        parameters: (Type) => Type.Unsafe(tool.parameters),
+        readOnly: tool.name !== 'wiki_write' && tool.name !== 'plugin_propose',
+        execute: async (input) => {
+            try {
+                return dispatch(env, context, tool.call, input, { variantDir: options.variantDir }) || 'Nothing found.';
+            }
+            catch (error) {
+                // The model sees the reason and can adjust, rather than the run failing.
+                return `That did not work: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+    }));
+}

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

@@ -0,0 +1,16 @@
+import type { ToolSpec } from "./types.js";
+export declare const SESSION_NAME = "session_name";
+/** The trigger the prompt and the tool description share, so naming guidance cannot drift. */
+export declare const SESSION_GUIDANCE: string;
+export interface NamedSession {
+    readonly sessionName?: string;
+    setSessionName(name: string): void;
+}
+/** The one name validation every caller uses: a short, single-line, control-free sentence. */
+export declare function normalizeSessionName(value: unknown): string;
+/**
+ * A provisional name for a substantive first request. It is deliberately mechanical: the model
+ * can still revise it with session_name. Greetings and short conversational replies stay unnamed.
+ */
+export declare function deriveSessionName(text: string): string | null;
+export declare function sessionNameTool(current: () => NamedSession | undefined): ToolSpec;

package/dist/sdk/tools/sessionName.js

@@ -0,0 +1,78 @@
+// Pi owns session names and their history. Both execution paths bind this tool to
+// the current native session; it never receives a target session id from the model.
+import { invalid } from "../core/errors.js";
+export const SESSION_NAME = 'session_name';
+/** The trigger the prompt and the tool description share, so naming guidance cannot drift. */
+export const SESSION_GUIDANCE = 'If the request needs tools or changes state — not a greeting, thanks, or a short conversational reply — call session_name once before your first other tool call, naming the work from the request. ' +
+    'Use one short imperative sentence of at most six words. Revise the name only when the overall objective changes; keep the current name when it does not.';
+/** The one name validation every caller uses: a short, single-line, control-free sentence. */
+export function normalizeSessionName(value) {
+    if (typeof value !== 'string')
+        throw invalid('Send name as a short sentence of at most six words.');
+    if (/[\x00-\x08\x0e-\x1f\x7f-\x9f]/u.test(value)) {
+        throw invalid('Session names cannot contain terminal escapes or control characters.');
+    }
+    const name = value.replace(/\s+/gu, ' ').trim();
+    if (!name || name.split(' ').length > 6)
+        throw invalid('Use a non-empty session name of at most six words.');
+    return name;
+}
+const CONVERSATIONAL = /^(?:hi|hello|hey|yo|thanks|thank you|ok|okay|sure|great|nice|cool|sounds good|got it|good morning|good afternoon|good evening|how are you|what'?s up)[.!?]*$/iu;
+const LEADING = /^(?:please|can you|could you|would you|i want you to|i'd like you to|help me|let'?s|go ahead and)[,\s]+/iu;
+/**
+ * A provisional name for a substantive first request. It is deliberately mechanical: the model
+ * can still revise it with session_name. Greetings and short conversational replies stay unnamed.
+ */
+export function deriveSessionName(text) {
+    if (typeof text !== 'string')
+        return null;
+    const input = text.trim();
+    if (!input || input.startsWith('!') || input.startsWith('```') || /^https?:\/\//iu.test(input))
+        return null;
+    if (CONVERSATIONAL.test(input))
+        return null;
+    if (/^continue\b/iu.test(input))
+        return 'Continue previous work';
+    const sentence = input.split(/[.!?](?:\s|$)/u)[0] ?? input;
+    const cleaned = sentence
+        .replace(/```[\s\S]*?```/gu, ' ')
+        .replace(/[`*_~#>]/gu, ' ')
+        .replace(/[:;,]+/gu, ' ')
+        .replace(LEADING, '')
+        .replace(/\s+/gu, ' ')
+        .trim();
+    if (!/[a-z]/iu.test(cleaned))
+        return null;
+    const words = cleaned.split(' ').filter(Boolean).slice(0, 6);
+    if (!words.length)
+        return null;
+    const name = words.join(' ').replace(/^[\p{P}\p{S}]+/u, '').replace(/[\p{P}\p{S}]+$/u, '').trim();
+    if (!name)
+        return null;
+    const capitalized = name[0].toUpperCase() + name.slice(1);
+    try {
+        return normalizeSessionName(capitalized);
+    }
+    catch {
+        return null;
+    }
+}
+export function sessionNameTool(current) {
+    return {
+        name: SESSION_NAME,
+        label: 'Name the session',
+        description: `Set or revise this session’s name. ${SESSION_GUIDANCE} ` +
+            'For example, "Add web browser integrations". You may revise a manually assigned name. This only names your own session.',
+        parameters: Type => Type.Object({ name: Type.String({ description: 'One short sentence describing the objective, at most six words' }) }),
+        planModeSafe: () => true,
+        execute: async (input) => {
+            const name = normalizeSessionName(input.name);
+            const session = current();
+            if (!session)
+                throw invalid('The native session is unavailable; try naming it again once it is ready.');
+            if (session.sessionName !== name)
+                session.setSessionName(name);
+            return `Session name: ${name}`;
+        }
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { Subagents } from "../sessions/subagentService.js";
+import type { ToolSpec } from "./types.js";
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_CHILDREN, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_CHILDREN, MAX_SUBAGENT_DEPTH, subagentDepth, subagentQuota, subagentReport, type SubagentOptions, type SubagentQuota } from "../sessions/subagents.js";
+export declare function subagentTools(service: Subagents, parentRunId: string): ToolSpec[];

package/dist/sdk/tools/spawnSubagent.js

@@ -0,0 +1,63 @@
+import { HarnessError, invalid } from "../core/errors.js";
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, SUBAGENT_RECEIPT, MAX_SUBAGENT_TITLE_WORDS, subagentTitle } from "../sessions/subagents.js";
+export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_CHILDREN, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_CHILDREN, MAX_SUBAGENT_DEPTH, subagentDepth, subagentQuota, subagentReport } from "../sessions/subagents.js";
+function reported(parentRunId, results, spawned) {
+    const included = [];
+    let length = 0;
+    for (const result of results) {
+        if (length + result.text.length > 24_000 && included.length)
+            break;
+        included.push(result);
+        length += result.text.length + 300;
+    }
+    const receipt = { version: 1, ownerRunId: parentRunId, ...(spawned ? { spawned } : {}), delivered: included.map((result) => result.runId) };
+    return { text: JSON.stringify({ results: included, ...(results.length > included.length ? { remaining: results.slice(included.length).map((result) => result.runId) } : {}) }), details: { [SUBAGENT_RECEIPT]: receipt } };
+}
+export function subagentTools(service, parentRunId) {
+    const quota = service.quota(parentRunId);
+    const budget = `This run allows at most ${quota.children} children: ${Object.entries(quota.profiles).map(([name, value]) => `${value} ${name}`).join(', ')}, ${quota.other} of any other profile and ${quota.unprofiled} unprofiled; a refused spawn means do the work yourself.`;
+    const execute = (fn) => async (input) => {
+        try {
+            return await fn(input);
+        }
+        catch (error) {
+            if (error instanceof HarnessError)
+                return error.message;
+            throw error;
+        }
+    };
+    return [{
+            name: SPAWN_SUBAGENT,
+            label: 'Start a subagent',
+            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. The optional tools field only narrows the profile and parent intersection; in plan mode, omit it unless you need a stricter subset. 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. To resume a child that stopped before finishing (interrupted or failed), pass continue with its run ID and no title, agent or tools: it reopens that child\'s own conversation with the same profile and tools, and brief becomes an optional extra instruction. ' + budget,
+            planModeSafe: input => service.planSpawnRefusal(parentRunId, input) === null,
+            parameters: (Type) => Type.Object({
+                title: Type.Optional(Type.String({ description: `Required for a new child: a short imperative title for the roster, at most ${MAX_SUBAGENT_TITLE_WORDS} words, such as "Map the auth flow"` })),
+                brief: Type.Optional(Type.String({ description: 'Required for a new child: a self-contained task: goal, relevant context or paths, non-goals, expected result, and acceptance or verification. The child cannot see this conversation. With continue, an optional extra instruction.' })),
+                continue: Type.Optional(Type.String({ description: 'The run ID of one of your subagents that stopped before finishing, to continue it from where it stopped instead of starting a fresh child' })),
+                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({ description: 'Only request a stricter subset of the profile and parent tools. In plan mode, omit this field to inherit the safe available research intersection.' }))),
+                wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' }))
+            }),
+            execute: execute(async (input) => {
+                const resume = input.continue === undefined ? undefined : input.continue;
+                const title = resume === undefined ? subagentTitle(input.title) : undefined;
+                if (resume === undefined && !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, ...(resume === undefined ? {} : { continue: resume }) });
+                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] } } };
+            })
+        }, {
+            name: WAIT_SUBAGENTS,
+            label: 'Wait for subagents',
+            description: 'Wait for all selected direct subagents to settle and return their results, including failures. Omit runIds to select your current children. Do useful independent work before waiting; results also arrive automatically before your final reply.',
+            parameters: (Type) => Type.Object({ runIds: Type.Optional(Type.Array(Type.String())) }),
+            execute: execute(async (input) => {
+                if (input.runIds !== undefined && !Array.isArray(input.runIds))
+                    throw invalid('runIds must be an array of child run IDs.');
+                return reported(parentRunId, await service.wait({ parentRunId, runIds: input.runIds }));
+            })
+        }];
+}

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

@@ -0,0 +1,15 @@
+import { type TodoItem, type RunEvent } from "../sessions/contracts.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { ToolSpec } from "./types.js";
+export declare const TODO_WRITE = "todo_write";
+/** The trigger the prompt and the tool description share, so progress guidance cannot drift. */
+export declare const TODO_GUIDANCE: string;
+/** The todo list as the model reads it back. */
+export declare function describeTodo(items: readonly TodoItem[]): string;
+/** The latest todo list a run wrote, or an empty list. Reads the pre-rename event too. */
+export declare function todoOf(events: readonly RunEvent[]): TodoItem[];
+export declare function todoTool(run: Pick<ActiveRun, 'emit'>): ToolSpec;
+/** @deprecated Use `TODO_WRITE`; kept for one release so embedders can migrate. */
+export declare const CHECKLIST_WRITE = "todo_write";
+/** @deprecated Use `todoOf`; kept for one release so embedders can migrate. */
+export declare const checklistOf: typeof todoOf;

package/dist/sdk/tools/todo.js

@@ -0,0 +1,66 @@
+// The run's own todo list: the model writes the whole list each time, and the run records it as
+// a `todo.updated` event. It only changes run state, so it stays callable in plan mode.
+import { todoItemSchema, MAX_TODO_ITEMS } from "../sessions/contracts.js";
+export const TODO_WRITE = 'todo_write';
+/** The trigger the prompt and the tool description share, so progress guidance cannot drift. */
+export const TODO_GUIDANCE = 'If the work has several distinct steps, call todo_write before your first other tool call with the steps you know so far, and keep the list current as steps start and finish. ' +
+    'The list shows the person your progress; it is not the scope of the work. The request, and any document it points to, is the scope: add steps as the work shows them, and list the steps of a handoff or plan instead of folding them into one "remaining work" item. ' +
+    'Keep the list true: mark a step completed only once it is done and checked, and never mark unfinished work completed. Before you end the turn, compare the request, not the list, with what is done and checked; if a step stays open, say why in the reply. ' +
+    'When a login blocks a step, leave it open and give the exact command the person must run in the reply. ' +
+    'The person follows your work from it, and a subagent’s todo list shows as its progress in the person’s list of subagents.';
+/** The event a run writes; `checklist.updated` is the pre-rename name, still read for old runs. */
+const TODO_EVENTS = new Set(['todo.updated', 'checklist.updated']);
+const MARK = { pending: '[ ]', in_progress: '[~]', completed: '[x]' };
+/** The todo list as the model reads it back. */
+export function describeTodo(items) {
+    if (!items.length)
+        return 'The todo list is empty.';
+    return items.map((item) => `${MARK[item.status]} ${item.text}`).join('\n');
+}
+/** The latest todo list a run wrote, or an empty list. Reads the pre-rename event too. */
+export function todoOf(events) {
+    const last = events.filter((event) => TODO_EVENTS.has(event.type)).at(-1);
+    const items = last?.payload?.items;
+    return Array.isArray(items) ? items.flatMap((item) => {
+        const parsed = todoItemSchema.safeParse(item);
+        return parsed.success ? [parsed.data] : [];
+    }) : [];
+}
+export function todoTool(run) {
+    return {
+        name: TODO_WRITE,
+        label: 'Write the todo list',
+        description: `Keep a todo list of the steps of the current work. The user watches this list to follow your progress. ${TODO_GUIDANCE} ` +
+            'Send the whole list every time; it replaces the previous one. Do not use it for a single, simple step or for conversation. ' +
+            'Statuses: pending, in_progress, completed. Keep exactly one step in_progress while you work, mark a step completed as soon as it is done (not in batches), and add steps you discover. ' +
+            'Only mark a step completed when it is fully done; if something blocks it, keep it in_progress and add a step for the blocker.',
+        parameters: (Type) => Type.Object({
+            items: Type.Array(Type.Object({
+                text: Type.String({ description: 'One step, as a short imperative line' }),
+                status: Type.Union([Type.Literal('pending'), Type.Literal('in_progress'), Type.Literal('completed')])
+            }), { maxItems: MAX_TODO_ITEMS })
+        }),
+        readOnly: true,
+        planModeSafe: () => true,
+        execute: async (input) => {
+            if (!Array.isArray(input.items))
+                return 'Send items: the whole todo list as an array.';
+            if (input.items.length > MAX_TODO_ITEMS)
+                return `Keep the todo list to ${MAX_TODO_ITEMS} steps or fewer.`;
+            const items = [];
+            for (const raw of input.items) {
+                const entry = raw;
+                const parsed = todoItemSchema.safeParse({ text: typeof entry?.text === 'string' ? entry.text.trim() : entry?.text, status: entry?.status });
+                if (!parsed.success)
+                    return 'Every step needs text of 1 to 500 characters and a status of pending, in_progress or completed.';
+                items.push(parsed.data);
+            }
+            run.emit('todo.updated', { items });
+            return describeTodo(items);
+        }
+    };
+}
+/** @deprecated Use `TODO_WRITE`; kept for one release so embedders can migrate. */
+export const CHECKLIST_WRITE = TODO_WRITE;
+/** @deprecated Use `todoOf`; kept for one release so embedders can migrate. */
+export const checklistOf = todoOf;

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

@@ -0,0 +1,48 @@
+import type { CallerContext } from "../core/caller.js";
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { ToolAttachmentRef } from "../sessions/contracts.js";
+import type { ProviderDiagnostics } from "../doctor/types.js";
+export interface ToolResult {
+    text: string;
+    /** Native-history metadata; never interpreted as model instructions. */
+    details?: Record<string, unknown>;
+    image?: {
+        data: string;
+        mimeType: string;
+    };
+    /** Further images, after `image`. A screenshot tool returns one; a comparison may return several. */
+    images?: {
+        data: string;
+        mimeType: string;
+    }[];
+    /** References to content stored by the provider; bytes never enter the run-event stream. */
+    attachments?: ToolAttachmentRef[];
+}
+export interface ToolSpec {
+    name: string;
+    label: string;
+    description: string;
+    /** Builds the TypeBox parameter schema. */
+    parameters: (type: typeof import('typebox').Type) => unknown;
+    /** Only reads or asks; such a tool stays callable in plan mode. */
+    readOnly?: boolean;
+    /** Whether this particular call is safe for plan-mode research. Refusals happen before approvals. */
+    planModeSafe?: (input: Record<string, unknown>) => boolean;
+    execute: (input: Record<string, unknown>) => Promise<string | ToolResult>;
+}
+/** What a tool provider is told about the session it is building tools for. */
+export interface ToolSession {
+    run: ActiveRun;
+    caller: CallerContext;
+    /** The tool names switched on for this session. */
+    allow: readonly string[];
+    /** Hops from the user to this session (0 when the user started it). */
+    depth: number;
+    /** The session's working folder. */
+    cwd: string;
+    /** The capability set frozen when this run started. */
+    capabilities: CapabilitySet;
+}
+/** Builds the tools a session may be given. Only those named in `allow` are registered. */
+export type ToolProvider = ((session: ToolSession) => ToolSpec[] | Promise<ToolSpec[]>) & ProviderDiagnostics;

package/dist/sdk/tools/types.js

@@ -0,0 +1 @@
+export {};

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