@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/terminal/tui/sessionPicker.js

@@ -0,0 +1,141 @@
+import { stat } from 'node:fs/promises';
+import { stripTerminalSequences } from '@earendil-works/pi-tui';
+import { displayProjectName, singleLine } from "./status.js";
+import { FilterList } from "./list.js";
+const RELATIVE_TIME = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
+const TIME_UNITS = [
+    [365 * 24 * 60 * 60 * 1000, 'year'],
+    [30 * 24 * 60 * 60 * 1000, 'month'],
+    [7 * 24 * 60 * 60 * 1000, 'week'],
+    [24 * 60 * 60 * 1000, 'day'],
+    [60 * 60 * 1000, 'hour'],
+    [60 * 1000, 'minute'],
+    [1000, 'second']
+];
+export function formatSessionRelativeTime(value, now = Date.now()) {
+    const delta = value.getTime() - now;
+    if (!Number.isFinite(delta))
+        return 'unknown time';
+    const absolute = Math.abs(delta);
+    const unit = TIME_UNITS.find(([size]) => absolute >= size);
+    return unit ? RELATIVE_TIME.format(Math.round(delta / unit[0]), unit[1]) : RELATIVE_TIME.format(0, 'second');
+}
+export function formatSessionSize(bytes) {
+    if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0)
+        return '—';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let size = bytes;
+    let unit = 0;
+    while (size >= 1024 && unit < units.length - 1) {
+        size /= 1024;
+        unit += 1;
+    }
+    return `${unit === 0 ? Math.round(size) : size.toFixed(1)}${units[unit]}`;
+}
+function safe(value) {
+    return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ' ');
+}
+export class ResumeSessionsPage {
+    options;
+    presentation = 'fullscreen';
+    list;
+    loading = false;
+    loaded = false;
+    disposed = false;
+    error;
+    abort;
+    constructor(options) {
+        this.options = options;
+        this.list = new FilterList({
+            theme: options.theme,
+            search: 'always',
+            rowGap: 1,
+            noun: ['session', 'sessions'],
+            empty: 'No saved sessions in this project',
+            onCancel: options.cancel,
+            onActivate: row => { if (row.data)
+                options.select(row.data); }
+        });
+    }
+    get focused() { return this.list.focused; }
+    set focused(value) { this.list.focused = value; }
+    tabs() { return [{ id: 'sessions', title: 'Resume session' }]; }
+    activeTab() { return 'sessions'; }
+    hint() { return '↑/↓ select · type to search · Enter resume'; }
+    activate() {
+        if (this.loaded || this.loading || this.disposed)
+            return;
+        this.abort = new AbortController();
+        void this.load(this.abort.signal);
+    }
+    dispose() {
+        this.disposed = true;
+        this.abort?.abort();
+    }
+    async load(signal) {
+        this.loading = true;
+        this.options.changed();
+        try {
+            const sessions = await this.options.listSessions(signal);
+            const branch = singleLine(this.options.branch() ?? '') || '—';
+            const rows = await Promise.all(sessions.map(async (session) => {
+                let bytes;
+                try {
+                    bytes = (await stat(session.path)).size;
+                }
+                catch { /* A removed or unreadable file remains selectable and shows an unknown size. */ }
+                const title = session.name?.trim() || session.firstMessage.trim() || session.id;
+                const project = displayProjectName(session.cwd || this.options.cwd());
+                const modified = formatSessionRelativeTime(session.modified);
+                const subtitle = `${modified} · ${project}:${branch} · ${formatSessionSize(bytes)}`;
+                return {
+                    id: session.path,
+                    label: singleLine(title),
+                    subtitle,
+                    searchText: `${title} ${session.firstMessage} ${session.id} ${subtitle}`,
+                    data: session.path
+                };
+            }));
+            if (this.disposed || signal.aborted)
+                return;
+            this.list.setRows(rows);
+            this.error = undefined;
+        }
+        catch (error) {
+            if (!this.disposed && !signal.aborted)
+                this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.loaded = true;
+            this.loading = false;
+            if (!this.disposed)
+                this.options.changed();
+        }
+    }
+    handleInput(data) {
+        if (!this.list.handleInput(data))
+            return false;
+        this.options.changed();
+        return true;
+    }
+    handleMouse(event) {
+        if (event.type === 'move')
+            return { handled: true, render: false };
+        if (event.type === 'wheel')
+            return undefined;
+        const result = this.list.handleMouse(event);
+        if (result?.render)
+            this.options.changed();
+        return result;
+    }
+    render(width, rows) {
+        if (width < 1 || rows < 1)
+            return [];
+        const theme = this.options.theme();
+        if (this.error)
+            return [theme.fg('error', `Could not read saved sessions: ${safe(this.error)}`)];
+        if (this.loading || !this.loaded)
+            return [theme.fg('dim', 'Loading saved sessions…')];
+        return this.list.render(width, rows);
+    }
+}

package/dist/sdk/tools/checklist.js

@@ -25,6 +25,7 @@ export function checklistTool(run) {
         description: 'Keep a checklist of the steps of the current work. The user watches this list to follow your progress, so write it early and keep it current. Send the whole list every time; it replaces the previous one. ' +
             'Use it whenever the work has several distinct steps or will take several tool calls, when the user gives several things to do, and when a subagent brief asks for more than one thing. 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. ' +
+            'Before your final response, write one final checklist update: mark every fully completed step completed, and leave unfinished or blocked steps in their accurate pending or in_progress status. Never mark unfinished work completed. ' +
             '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({

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

@@ -0,0 +1,27 @@
+import { type Checkpoint } from "../sessions/contracts.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { RunEvent } from "../sessions/contracts.js";
+import type { ToolSpec } from "./types.js";
+export declare const CHECKPOINT_WRITE = "checkpoint_write";
+/** What the model may send: the record without the numbers the harness fills in. */
+export type CheckpointInput = Omit<Checkpoint, 'slice' | 'reason'> & {
+    reason?: Checkpoint['reason'];
+};
+export type CheckpointParse = {
+    ok: true;
+    value: CheckpointInput;
+} | {
+    ok: false;
+    error: string;
+};
+/** The checkpoint as the model sent it, or one line saying what to fix. */
+export declare function parseCheckpoint(value: unknown): CheckpointParse;
+/** The model's own checkpoint, filled in with this slice and why it was written. */
+export declare function checkpointRecord(input: CheckpointInput, slice: number, fallbackReason: Checkpoint['reason']): Checkpoint;
+/** The latest checkpoint a run recorded, if any. */
+export declare function checkpointOf(events: readonly RunEvent[]): Checkpoint | null;
+/** The checkpoint as the next slice reads it. Bounded by its parts; the caller clips the whole. */
+export declare function describeCheckpoint(checkpoint: Checkpoint): string;
+/** The checkpoint as the model reads it back after writing it. */
+export declare function ackCheckpoint(checkpoint: Checkpoint): string;
+export declare function checkpointTool(run: Pick<ActiveRun, 'emit'>, slice: number | (() => number)): ToolSpec;

package/dist/sdk/tools/checkpoint.js

@@ -0,0 +1,154 @@
+// The reply's handoff when it reaches a work-slice budget (PROP-0041). The model writes it once,
+// the run records it as a `checkpoint` event, and the next slice is told where this one stopped.
+// It only changes run state, so it stays callable in plan mode.
+import { checkpointCheckSchema, checkpointDecisionSchema, checkpointFileSchema, checkpointItemSchema, checkpointReasonSchema, MAX_CHECKPOINT_CHECKS, MAX_CHECKPOINT_DECISIONS, MAX_CHECKPOINT_DONE, MAX_CHECKPOINT_FILES, MAX_CHECKPOINT_SUMMARY, runEventPayloadSchemas } from "../sessions/contracts.js";
+export const CHECKPOINT_WRITE = 'checkpoint_write';
+const text = (value) => (typeof value === 'string' ? value.trim() : '');
+/** Trims and bounds one entry; an unusable entry is dropped rather than failing the whole record. */
+function collect(value, parse, limit) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value.slice(0, limit)) {
+        const parsed = parse(entry);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/** The checkpoint as the model sent it, or one line saying what to fix. */
+export function parseCheckpoint(value) {
+    if (!value || typeof value !== 'object')
+        return { ok: false, error: 'Send checkpoint_write an object with summary and next.' };
+    const input = value;
+    const summary = text(input.summary);
+    if (summary.length > MAX_CHECKPOINT_SUMMARY)
+        return { ok: false, error: `Keep summary to ${MAX_CHECKPOINT_SUMMARY} characters.` };
+    if (text(input.next).length > 500)
+        return { ok: false, error: 'Keep next to 500 characters.' };
+    if (text(input.blocked).length > 500)
+        return { ok: false, error: 'Keep blocked to 500 characters.' };
+    const done = collect(input.done, (entry) => {
+        const parsed = checkpointItemSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_DONE);
+    const files = collect(input.files, (entry) => {
+        const parsed = checkpointFileSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_FILES);
+    const checks = collect(input.checks, (entry) => {
+        const parsed = checkpointCheckSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_CHECKS);
+    const decisions = collect(input.decisions, (entry) => {
+        const parsed = checkpointDecisionSchema.safeParse(entry);
+        return parsed.success ? parsed.data : null;
+    }, MAX_CHECKPOINT_DECISIONS);
+    if (!summary && !done.length && !text(input.next) && !files.length) {
+        return { ok: false, error: 'A checkpoint needs a summary, a next step, or what is done; write the handoff the next slice will read.' };
+    }
+    const reason = input.reason === undefined ? undefined : checkpointReasonSchema.safeParse(input.reason);
+    if (reason && !reason.success)
+        return { ok: false, error: 'reason is budget, stuck, compaction-thrash or requested.' };
+    return {
+        ok: true,
+        value: {
+            summary,
+            done,
+            next: text(input.next),
+            ...(text(input.blocked) ? { blocked: text(input.blocked) } : {}),
+            files,
+            checks,
+            decisions,
+            ...(reason && reason.success ? { reason: reason.data } : {})
+        }
+    };
+}
+/** The model's own checkpoint, filled in with this slice and why it was written. */
+export function checkpointRecord(input, slice, fallbackReason) {
+    return { ...input, slice, reason: input.reason ?? fallbackReason };
+}
+/** The latest checkpoint a run recorded, if any. */
+export function checkpointOf(events) {
+    const last = events.filter((event) => event.type === 'checkpoint').at(-1);
+    if (!last)
+        return null;
+    const parsed = runEventPayloadSchemas.checkpoint.safeParse(last.payload);
+    return parsed.success ? parsed.data : null;
+}
+const line = (value) => value.replace(/\s+/gu, ' ').trim();
+/** The checkpoint as the next slice reads it. Bounded by its parts; the caller clips the whole. */
+export function describeCheckpoint(checkpoint) {
+    const parts = [];
+    if (checkpoint.summary)
+        parts.push(`Where the last slice stopped: ${line(checkpoint.summary)}`);
+    if (checkpoint.done.length)
+        parts.push(`Done:\n${checkpoint.done.map((entry) => `- ${line(entry.item)}${entry.evidence.length ? ` (${entry.evidence.map(line).join('; ')})` : ''}`).join('\n')}`);
+    if (checkpoint.files.length)
+        parts.push(`Files touched:\n${checkpoint.files.map((entry) => `- ${line(entry.path)}${entry.why ? `: ${line(entry.why)}` : ''}`).join('\n')}`);
+    if (checkpoint.checks.length) {
+        const failing = checkpoint.checks.filter((entry) => !entry.ok);
+        const passing = checkpoint.checks.filter((entry) => entry.ok);
+        if (passing.length)
+            parts.push(`Checks that passed: ${passing.map((entry) => line(entry.command)).join('; ')}`);
+        if (failing.length)
+            parts.push(`Checks that failed:\n${failing.map((entry) => `- ${line(entry.command)}${entry.detail ? `: ${line(entry.detail)}` : ''}`).join('\n')}`);
+    }
+    if (checkpoint.decisions.length)
+        parts.push(`Decisions:\n${checkpoint.decisions.map((entry) => `- ${line(entry.what)}${entry.why ? `: ${line(entry.why)}` : ''}`).join('\n')}`);
+    if (checkpoint.blocked)
+        parts.push(`Blocked: ${line(checkpoint.blocked)}`);
+    if (checkpoint.next)
+        parts.push(`Next step: ${line(checkpoint.next)}`);
+    return parts.join('\n\n');
+}
+/** The checkpoint as the model reads it back after writing it. */
+export function ackCheckpoint(checkpoint) {
+    const counts = [
+        checkpoint.done.length ? `${checkpoint.done.length} done` : '',
+        checkpoint.files.length ? `${checkpoint.files.length} files` : '',
+        checkpoint.checks.length ? `${checkpoint.checks.length} checks` : ''
+    ].filter(Boolean).join(', ');
+    return `Checkpoint recorded for slice ${checkpoint.slice}${counts ? ` (${counts})` : ''}.${checkpoint.next ? ` Next: ${line(checkpoint.next)}` : ''}`;
+}
+export function checkpointTool(run, slice) {
+    return {
+        name: CHECKPOINT_WRITE,
+        label: 'Write the handoff checkpoint',
+        description: 'Record where this reply stopped and what the next slice must know. Call it when the harness asks for a handoff at the end of a work slice, or before you stop on purpose. ' +
+            'Include what is done (with the file or check that proves it), the single next step, anything blocking, the files you touched, the checks you ran with their outcome, and decisions the next slice must not revisit. ' +
+            'It records run state for the next slice; it does not change files and does not replace your reply to the user.',
+        parameters: (Type) => Type.Object({
+            summary: Type.Optional(Type.String({ description: 'Where this slice stopped, in 1 to 3 sentences (max 1200 characters)' })),
+            done: Type.Optional(Type.Array(Type.Object({
+                item: Type.String({ description: 'One finished step' }),
+                evidence: Type.Optional(Type.Array(Type.String({ description: 'A path, a check command, or a decision that proves it' }), { maxItems: 5 }))
+            }), { maxItems: MAX_CHECKPOINT_DONE })),
+            next: Type.Optional(Type.String({ description: 'The single next step (max 500 characters)' })),
+            blocked: Type.Optional(Type.String({ description: 'What stops progress, if anything (max 500 characters)' })),
+            files: Type.Optional(Type.Array(Type.Object({
+                path: Type.String(),
+                why: Type.Optional(Type.String({ description: 'Why this file matters to the next slice' }))
+            }), { maxItems: MAX_CHECKPOINT_FILES })),
+            checks: Type.Optional(Type.Array(Type.Object({
+                command: Type.String(),
+                ok: Type.Boolean(),
+                detail: Type.Optional(Type.String({ description: 'The failing line, when it failed' }))
+            }), { maxItems: MAX_CHECKPOINT_CHECKS })),
+            decisions: Type.Optional(Type.Array(Type.Object({
+                what: Type.String(),
+                why: Type.Optional(Type.String())
+            }), { maxItems: MAX_CHECKPOINT_DECISIONS }))
+        }),
+        readOnly: true,
+        planModeSafe: () => true,
+        execute: async (input) => {
+            const parsed = parseCheckpoint(input);
+            if (!parsed.ok)
+                return parsed.error;
+            const checkpoint = checkpointRecord(parsed.value, typeof slice === 'function' ? slice() : slice, 'requested');
+            run.emit('checkpoint', checkpoint);
+            return ackCheckpoint(checkpoint);
+        }
+    };
+}

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/spawnSubagent.js

@@ -27,11 +27,12 @@ export function subagentTools(service, parentRunId) {
     return [{
             name: SPAWN_SUBAGENT,
             label: 'Start a subagent',
-            description: 'Start a fresh child run for independent work: a copy of yourself, or an agent profile from your Subagents list when you name it in agent (for example worker to make changes, explorer to find and explain). Give a short title, which the user sees in the roster, and 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.',
+            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(),
-                agent: Type.Optional(Type.String({ description: 'The name of an agent profile from your Subagents list; omit for a copy of yourself' })),
+                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' }))
             }),

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