@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/commands/list.js

@@ -0,0 +1,75 @@
+// `commands.list`: every slash command a front end offers for one scope, from one source. The
+// terminal palette and a host's menu both read it, so they never keep their own lists.
+import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
+import { pluginCommandPrefix } from "../plugins/commandPrefix.js";
+import { CORE_COMMANDS } from "./registry.js";
+import { commandRoutes, promptCommandAvailable } from "./routes.js";
+export function listCommands(plugins) {
+    const out = new Map();
+    const taken = new Set();
+    for (const command of CORE_COMMANDS) {
+        const aliases = 'aliases' in command ? [...command.aliases] : [];
+        out.set(command.name, {
+            name: command.name,
+            ...(aliases.length ? { aliases } : {}),
+            ...('args' in command ? { args: command.args } : {}),
+            description: command.description,
+            group: command.group,
+            source: 'core',
+            kind: command.kind
+        });
+        taken.add(command.name);
+        aliases.forEach((alias) => taken.add(alias));
+    }
+    for (const command of BUILTIN_PLUGIN_REGISTRY.commands()) {
+        const name = `${command.prefix}:${command.name}`;
+        out.set(name, { name, description: command.description, group: 'Plugins', source: 'plugin', owner: command.pluginId });
+    }
+    for (const module of BUILTIN_PLUGIN_REGISTRY.modules) {
+        const prefix = module.commandPrefix ?? module.descriptor.id;
+        const fallback = BUILTIN_PLUGIN_REGISTRY.defaultCommand(prefix);
+        if (fallback)
+            out.set(`${prefix}:`, { name: `${prefix}:`, description: fallback.description, group: 'Plugins', source: 'plugin', owner: module.descriptor.id });
+    }
+    const extensions = [];
+    const extensionCommandNames = new Set();
+    for (const plugin of plugins) {
+        for (const contribution of plugin.contributions) {
+            if (contribution.kind !== 'code' || contribution.state !== 'on' || !contribution.path || !contribution.registered)
+                continue;
+            contribution.registered.commands.forEach(name => extensionCommandNames.add(name));
+        }
+    }
+    for (const plugin of plugins) {
+        for (const contribution of plugin.contributions) {
+            if (contribution.state !== 'on')
+                continue;
+            if (contribution.kind === 'code' && contribution.registered && contribution.path) {
+                const packageRoot = (plugin.source === 'package' || plugin.id.startsWith('package:')) ? plugin.path : null;
+                const prefix = pluginCommandPrefix(packageRoot
+                    ? { path: contribution.path, origin: 'package', baseDir: packageRoot }
+                    : { path: contribution.path });
+                for (const command of contribution.registered.commands) {
+                    const name = `${prefix}:${command}`;
+                    extensions.push({ prefix, name: command, owner: packageRoot ? `package:${packageRoot}` : `extension:${contribution.path}`, path: contribution.path,
+                        listed: { name, group: 'Plugins', source: 'extension', owner: plugin.id } });
+                }
+            }
+            // Catalogue entries without a path are observed extension commands, not templates.
+            if (contribution.kind === 'command' && contribution.path && promptCommandAvailable(contribution.name, taken, extensionCommandNames) && !out.has(contribution.name)) {
+                out.set(contribution.name, { name: contribution.name, description: contribution.description, group: 'Prompts', source: 'prompt', owner: plugin.id });
+            }
+            if (contribution.kind === 'skill') {
+                const name = `skill:${contribution.name}`;
+                if (!out.has(name))
+                    out.set(name, { name, description: contribution.description, group: 'Skills', source: 'skill', owner: plugin.id });
+            }
+        }
+    }
+    const indexed = commandRoutes(extensions);
+    for (const [name, routes] of indexed.routes) {
+        if (routes.length === 1 && !indexed.conflictingPrefixes.has(routes[0].prefix) && !out.has(name))
+            out.set(name, routes[0].listed);
+    }
+    return [...out.values()];
+}

package/dist/sdk/commands/registry.d.ts

@@ -0,0 +1,250 @@
+/** Where a command's work happens. */
+export type CoreCommandKind = 
+/** Changes or reads the current session through a Harness method. */
+'session'
+/** Opens a capability page (doctor, worktrees, tools, ...). */
+ | 'page'
+/** Presentation only: help, key bindings, copying, showing thinking, leaving. */
+ | 'local';
+export type CoreCommandGroup = 'Core' | 'Run' | 'Model' | 'Session' | 'Inspect' | 'Harness';
+export interface CoreCommand {
+    name: string;
+    aliases?: readonly string[];
+    /** What follows the name, for the palette: `<brief>`, `[path]`. */
+    args?: string;
+    description: string;
+    group: CoreCommandGroup;
+    kind: CoreCommandKind;
+    /** The Harness server methods the command uses, when it uses any. */
+    methods?: readonly string[];
+}
+export declare const CORE_COMMANDS: readonly [{
+    readonly name: "help";
+    readonly description: "List the commands";
+    readonly group: "Core";
+    readonly kind: "local";
+}, {
+    readonly name: "plan";
+    readonly args: "[brief]";
+    readonly description: "Plan one request, read-only: /plan <brief>";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.run"];
+}, {
+    readonly name: "btw";
+    readonly aliases: readonly ["side"];
+    readonly args: "[question]";
+    readonly description: "Ask a side question without interrupting: /btw <question>";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["sideQuestions.start", "sideQuestions.cancel"];
+}, {
+    readonly name: "new";
+    readonly description: "Start a new session";
+    readonly group: "Session";
+    readonly kind: "session";
+}, {
+    readonly name: "stop";
+    readonly description: "Stop the current reply";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["runs.interrupt"];
+}, {
+    readonly name: "session";
+    readonly aliases: readonly ["resume"];
+    readonly args: "[path]";
+    readonly description: "Choose a saved session in this account and folder";
+    readonly group: "Session";
+    readonly kind: "session";
+}, {
+    readonly name: "history";
+    readonly aliases: readonly ["tree"];
+    readonly description: "Navigate branches in the current session";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.tree", "sessions.navigate"];
+}, {
+    readonly name: "fork";
+    readonly description: "Fork from an earlier message";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.tree", "sessions.fork"];
+}, {
+    readonly name: "clone";
+    readonly description: "Clone this branch into a new session";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.clone"];
+}, {
+    readonly name: "model";
+    readonly args: "[search]";
+    readonly description: "Choose the model";
+    readonly group: "Model";
+    readonly kind: "session";
+    readonly methods: readonly ["accounts.models"];
+}, {
+    readonly name: "effort";
+    readonly args: "[level]";
+    readonly description: "Choose the thinking effort";
+    readonly group: "Model";
+    readonly kind: "session";
+}, {
+    readonly name: "thinking";
+    readonly args: "[show|hide]";
+    readonly description: "Toggle transcript thinking visibility: /thinking [show|hide]";
+    readonly group: "Model";
+    readonly kind: "local";
+}, {
+    readonly name: "name";
+    readonly args: "[name]";
+    readonly description: "Name this session";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.rename"];
+}, {
+    readonly name: "compact";
+    readonly args: "[instructions]";
+    readonly description: "Compact the context";
+    readonly group: "Session";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.run"];
+}, {
+    readonly name: "copy";
+    readonly description: "Copy the last reply";
+    readonly group: "Inspect";
+    readonly kind: "local";
+    readonly methods: readonly ["sessions.lastReply"];
+}, {
+    readonly name: "export";
+    readonly args: "[path.html|path.jsonl]";
+    readonly description: "Export this branch to HTML or JSONL";
+    readonly group: "Inspect";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.export", "sessions.run"];
+}, {
+    readonly name: "trajectory";
+    readonly args: "[run-id]";
+    readonly description: "Inspect recorded runs for this session";
+    readonly group: "Inspect";
+    readonly kind: "page";
+    readonly methods: readonly ["runs.list", "runs.events"];
+}, {
+    readonly name: "reload";
+    readonly description: "Reload trusted resources and keybindings";
+    readonly group: "Harness";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.reload"];
+}, {
+    readonly name: "accounts";
+    readonly description: "Sign in, switch, check and remove Pi accounts";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["accounts.list"];
+}, {
+    readonly name: "permissions";
+    readonly description: "Full Permission and per-tool approvals";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["approvals.get"];
+}, {
+    readonly name: "harness";
+    readonly description: "Browse foundation, variant and all resources";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "skills";
+    readonly description: "View, inspect and use skills; discover more";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "connections";
+    readonly description: "Manage local and remote MCP connections";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "mcp";
+    readonly description: "Open Connections in the Harness browser";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "tools";
+    readonly description: "Inspect available tools, owners and approvals";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "plugins";
+    readonly description: "Switch plugins on or off and trust their code";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["plugins.inventory"];
+}, {
+    readonly name: "hub";
+    readonly description: "Browse and install reviewed skills, plugins and documents";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "components";
+    readonly description: "Browse skills, prompts and rules for this Harness scope";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "settings";
+    readonly description: "Session, terminal and browser settings";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "doctor";
+    readonly description: "Check account, model, tools and runtime readiness";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["doctor.start", "doctor.read"];
+}, {
+    readonly name: "worktree";
+    readonly description: "Manage repository worktrees";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["worktrees.list"];
+}, {
+    readonly name: "subagents";
+    readonly description: "Watch current subagent tasks and activity";
+    readonly group: "Harness";
+    readonly kind: "page";
+}, {
+    readonly name: "agents";
+    readonly description: "Browse and edit agent profiles";
+    readonly group: "Harness";
+    readonly kind: "page";
+    readonly methods: readonly ["agents.list"];
+}, {
+    readonly name: "log";
+    readonly description: "Harness diagnostics and this conversation's run events";
+    readonly group: "Inspect";
+    readonly kind: "page";
+}, {
+    readonly name: "hotkeys";
+    readonly description: "Keyboard controls";
+    readonly group: "Core";
+    readonly kind: "local";
+}, {
+    readonly name: "quit";
+    readonly description: "Restore the terminal and exit";
+    readonly group: "Core";
+    readonly kind: "local";
+}];
+export type CoreCommandName = typeof CORE_COMMANDS[number]['name'];
+/** The core command a typed name or alias stands for. */
+export declare function coreCommand(name: string): CoreCommand | undefined;
+/** Every listed command, as `commands.list` returns it. */
+export interface ListedCommand {
+    /** What the person types after `/`: `fork`, `annotate:notes`, `skill:review`. */
+    name: string;
+    aliases?: string[];
+    args?: string;
+    description?: string;
+    group: string;
+    source: 'core' | 'plugin' | 'extension' | 'prompt' | 'skill';
+    /** Core commands only. */
+    kind?: CoreCommandKind;
+    /** The owning plugin of a plugin or extension command. */
+    owner?: string;
+}

package/dist/sdk/commands/registry.js

@@ -0,0 +1,47 @@
+// The core slash commands every front end offers. This module is plain data with no imports, so a
+// browser renderer can read it as well as the terminal. A front end must handle every `action`
+// here (INV-PAR-1); `commands.list` adds plugin commands, prompt templates and skills.
+export const CORE_COMMANDS = [
+    { name: 'help', description: 'List the commands', group: 'Core', kind: 'local' },
+    { name: 'plan', args: '[brief]', description: 'Plan one request, read-only: /plan <brief>', group: 'Run', kind: 'session', methods: ['sessions.run'] },
+    { name: 'btw', aliases: ['side'], args: '[question]', description: 'Ask a side question without interrupting: /btw <question>', group: 'Run', kind: 'session', methods: ['sideQuestions.start', 'sideQuestions.cancel'] },
+    { name: 'new', description: 'Start a new session', group: 'Session', kind: 'session' },
+    { name: 'stop', description: 'Stop the current reply', group: 'Run', kind: 'session', methods: ['runs.interrupt'] },
+    { name: 'session', aliases: ['resume'], args: '[path]', description: 'Choose a saved session in this account and folder', group: 'Session', kind: 'session' },
+    { name: 'history', aliases: ['tree'], description: 'Navigate branches in the current session', group: 'Session', kind: 'session', methods: ['sessions.tree', 'sessions.navigate'] },
+    { name: 'fork', description: 'Fork from an earlier message', group: 'Session', kind: 'session', methods: ['sessions.tree', 'sessions.fork'] },
+    { name: 'clone', description: 'Clone this branch into a new session', group: 'Session', kind: 'session', methods: ['sessions.clone'] },
+    { name: 'model', args: '[search]', description: 'Choose the model', group: 'Model', kind: 'session', methods: ['accounts.models'] },
+    { name: 'effort', args: '[level]', description: 'Choose the thinking effort', group: 'Model', kind: 'session' },
+    { name: 'thinking', args: '[show|hide]', description: 'Toggle transcript thinking visibility: /thinking [show|hide]', group: 'Model', kind: 'local' },
+    { name: 'name', args: '[name]', description: 'Name this session', group: 'Session', kind: 'session', methods: ['sessions.rename'] },
+    { name: 'compact', args: '[instructions]', description: 'Compact the context', group: 'Session', kind: 'session', methods: ['sessions.run'] },
+    { name: 'copy', description: 'Copy the last reply', group: 'Inspect', kind: 'local', methods: ['sessions.lastReply'] },
+    { name: 'export', args: '[path.html|path.jsonl]', description: 'Export this branch to HTML or JSONL', group: 'Inspect', kind: 'session', methods: ['sessions.export', 'sessions.run'] },
+    { name: 'trajectory', args: '[run-id]', description: 'Inspect recorded runs for this session', group: 'Inspect', kind: 'page', methods: ['runs.list', 'runs.events'] },
+    { name: 'reload', description: 'Reload trusted resources and keybindings', group: 'Harness', kind: 'session', methods: ['sessions.reload'] },
+    { name: 'accounts', description: 'Sign in, switch, check and remove Pi accounts', group: 'Harness', kind: 'page', methods: ['accounts.list'] },
+    { name: 'permissions', description: 'Full Permission and per-tool approvals', group: 'Harness', kind: 'page', methods: ['approvals.get'] },
+    { name: 'harness', description: 'Browse foundation, variant and all resources', group: 'Harness', kind: 'page' },
+    { name: 'skills', description: 'View, inspect and use skills; discover more', group: 'Harness', kind: 'page' },
+    { name: 'connections', description: 'Manage local and remote MCP connections', group: 'Harness', kind: 'page' },
+    { name: 'mcp', description: 'Open Connections in the Harness browser', group: 'Harness', kind: 'page' },
+    { name: 'tools', description: 'Inspect available tools, owners and approvals', group: 'Harness', kind: 'page' },
+    { name: 'plugins', description: 'Switch plugins on or off and trust their code', group: 'Harness', kind: 'page', methods: ['plugins.inventory'] },
+    { name: 'hub', description: 'Browse and install reviewed skills, plugins and documents', group: 'Harness', kind: 'page' },
+    { name: 'components', description: 'Browse skills, prompts and rules for this Harness scope', group: 'Harness', kind: 'page' },
+    { name: 'settings', description: 'Session, terminal and browser settings', group: 'Harness', kind: 'page' },
+    { name: 'doctor', description: 'Check account, model, tools and runtime readiness', group: 'Harness', kind: 'page', methods: ['doctor.start', 'doctor.read'] },
+    { name: 'worktree', description: 'Manage repository worktrees', group: 'Harness', kind: 'page', methods: ['worktrees.list'] },
+    { name: 'subagents', description: 'Watch current subagent tasks and activity', group: 'Harness', kind: 'page' },
+    { name: 'agents', description: 'Browse and edit agent profiles', group: 'Harness', kind: 'page', methods: ['agents.list'] },
+    { name: 'log', description: "Harness diagnostics and this conversation's run events", group: 'Inspect', kind: 'page' },
+    { name: 'hotkeys', description: 'Keyboard controls', group: 'Core', kind: 'local' },
+    { name: 'quit', description: 'Restore the terminal and exit', group: 'Core', kind: 'local' }
+];
+const ALIASES = new Map(CORE_COMMANDS.flatMap((command) => ('aliases' in command ? command.aliases : []).map((alias) => [alias, command.name])));
+/** The core command a typed name or alias stands for. */
+export function coreCommand(name) {
+    const canonical = ALIASES.get(name) ?? name;
+    return CORE_COMMANDS.find((command) => command.name === canonical);
+}

package/dist/sdk/commands/routes.d.ts

@@ -0,0 +1,16 @@
+/** One observed registration, identified by its package or loose extension owner. */
+export interface CommandRoute {
+    prefix: string;
+    name: string;
+    owner: string;
+    path: string;
+}
+/** Listing and dispatch reject the whole prefix when different owners claim it. */
+export declare function commandRoutes<T extends CommandRoute>(commands: readonly T[]): {
+    routes: Map<string, T[]>;
+    byName: Map<string, T[]>;
+    ownersByPrefix: Map<string, Map<string, Set<string>>>;
+    conflictingPrefixes: Map<string, string[]>;
+};
+/** Namespace roots and reserved routes cannot be claimed by prompt templates. */
+export declare function promptCommandAvailable(name: string, taken: ReadonlySet<string>, extensionCommands?: ReadonlySet<string>): boolean;

package/dist/sdk/commands/routes.js

@@ -0,0 +1,33 @@
+import { BUILTIN_PLUGIN_REGISTRY } from "../plugins/builtin.js";
+/** Listing and dispatch reject the whole prefix when different owners claim it. */
+export function commandRoutes(commands) {
+    const routes = new Map();
+    const byName = new Map();
+    const ownersByPrefix = new Map();
+    const builtinPrefixes = new Map(BUILTIN_PLUGIN_REGISTRY.commands().map(command => [command.prefix, command.pluginId]));
+    for (const command of commands) {
+        const owners = ownersByPrefix.get(command.prefix) ?? new Map();
+        const paths = owners.get(command.owner) ?? new Set();
+        paths.add(command.path);
+        owners.set(command.owner, paths);
+        ownersByPrefix.set(command.prefix, owners);
+        const route = `${command.prefix}:${command.name}`;
+        routes.set(route, [...(routes.get(route) ?? []), command]);
+        byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
+    }
+    const conflictingPrefixes = new Map();
+    for (const [prefix, owners] of ownersByPrefix) {
+        const builtin = builtinPrefixes.get(prefix);
+        if (owners.size > 1 || builtin || prefix === 'plugin' || prefix === 'skill') {
+            conflictingPrefixes.set(prefix, [
+                ...(builtin ? [`built-in plugin ${builtin}`] : []),
+                ...[...owners.values()].flatMap(paths => [...paths])
+            ]);
+        }
+    }
+    return { routes, byName, ownersByPrefix, conflictingPrefixes };
+}
+/** Namespace roots and reserved routes cannot be claimed by prompt templates. */
+export function promptCommandAvailable(name, taken, extensionCommands = new Set()) {
+    return !name.includes(':') && !taken.has(name) && !extensionCommands.has(name);
+}

package/dist/sdk/core/commandBudget.d.ts

@@ -0,0 +1,23 @@
+/** What a command gets when the caller says nothing. */
+export declare const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;
+/** Past this, a call must say why it needs longer. */
+export declare const COMMAND_TIMEOUT_CEILING_SECONDS = 300;
+/** The longest a single command may run at all. */
+export declare const COMMAND_TIMEOUT_MAX_SECONDS = 900;
+export type CommandTimeout = {
+    ok: true;
+    timeout: number;
+} | {
+    ok: false;
+    message: string;
+};
+/** Resolves a requested timeout against the default, the ceiling and the maximum. */
+export declare function resolveCommandTimeout(requested: unknown, reason: unknown): CommandTimeout;
+/** A command's result when it was stopped by the budget rather than finishing. */
+export declare function commandTimeoutText(seconds: number, output: string): string;
+/**
+ * Runs a command with a wall-clock budget. The abort reaches the live shell, so the promise
+ * settles instead of leaving the reply blocked; a timeout is reported as a rejection the caller
+ * turns into a tool result.
+ */
+export declare function withCommandBudget<T>(run: () => Promise<T>, abort: (() => void) | undefined, seconds: number): Promise<T>;

package/dist/sdk/core/commandBudget.js

@@ -0,0 +1,57 @@
+// One command budget for every path that runs a shell command (PROP-0041). A blocking command is
+// how a reply spends a quarter of an hour: a default keeps ordinary commands honest, a ceiling
+// makes a long one an explicit choice, and a timeout returns what it saw instead of waiting.
+/** What a command gets when the caller says nothing. */
+export const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;
+/** Past this, a call must say why it needs longer. */
+export const COMMAND_TIMEOUT_CEILING_SECONDS = 300;
+/** The longest a single command may run at all. */
+export const COMMAND_TIMEOUT_MAX_SECONDS = 900;
+/** Resolves a requested timeout against the default, the ceiling and the maximum. */
+export function resolveCommandTimeout(requested, reason) {
+    const why = typeof reason === 'string' ? reason.trim() : '';
+    if (typeof requested !== 'number' || !Number.isFinite(requested))
+        return { ok: true, timeout: DEFAULT_COMMAND_TIMEOUT_SECONDS };
+    const timeout = Math.floor(requested);
+    if (timeout < 1)
+        return { ok: false, message: 'timeout must be a positive number of seconds.' };
+    if (timeout > COMMAND_TIMEOUT_MAX_SECONDS)
+        return { ok: false, message: `A command may run for at most ${COMMAND_TIMEOUT_MAX_SECONDS} seconds. Split it into smaller commands.` };
+    if (timeout > COMMAND_TIMEOUT_CEILING_SECONDS && !why) {
+        return { ok: false, message: `A command over ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds needs a reason: pass reason with why it cannot be narrowed or run in smaller steps.` };
+    }
+    return { ok: true, timeout };
+}
+/** A command's result when it was stopped by the budget rather than finishing. */
+export function commandTimeoutText(seconds, output) {
+    return `The command was stopped after ${seconds} seconds by the command budget. Its output so far:\n${output || '(none)'}\n\nNarrow it: one test file, --grep for the failing case, or a line range, then run the full set at a checkpoint.`;
+}
+/**
+ * Runs a command with a wall-clock budget. The abort reaches the live shell, so the promise
+ * settles instead of leaving the reply blocked; a timeout is reported as a rejection the caller
+ * turns into a tool result.
+ */
+export async function withCommandBudget(run, abort, seconds) {
+    let timer;
+    try {
+        return await Promise.race([
+            run(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    try {
+                        abort?.();
+                    }
+                    catch {
+                        // The abort is best effort; the timeout still settles the reply.
+                    }
+                    reject(new Error(commandTimeoutText(seconds, '')));
+                }, seconds * 1000);
+                timer.unref?.();
+            })
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/sdk/core/index.js

@@ -53,7 +53,23 @@ export const MIGRATIONS = [
      CREATE INDEX runs_agent ON runs (agent_id, started_at);
      CREATE INDEX runs_started ON runs (started_at);`,
     // 7: the per-account usage table goes
-    'DROP TABLE IF EXISTS usage;'
+    'DROP TABLE IF EXISTS usage;',
+    // 8: the usage ledger behind `/usage:analysis`, rebuilt from each run's `usage.updated` events
+    `CREATE TABLE usage_requests (run_id TEXT NOT NULL, sequence INTEGER NOT NULL, request_index INTEGER NOT NULL,
+        at TEXT NOT NULL, day TEXT NOT NULL, account_id TEXT, project_id TEXT, session_id TEXT NOT NULL,
+        agent_id TEXT, mode TEXT NOT NULL, trigger TEXT, provider TEXT, model TEXT,
+        input_tokens INTEGER NOT NULL DEFAULT 0, cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+        cache_write_tokens INTEGER NOT NULL DEFAULT 0, output_tokens INTEGER NOT NULL DEFAULT 0,
+        reasoning_tokens INTEGER NOT NULL DEFAULT 0, cost_usd REAL, cost_source TEXT,
+        context_tokens INTEGER, context_window INTEGER, duration_ms INTEGER, ttft_ms INTEGER,
+        requests INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (run_id, sequence, request_index));
+     CREATE INDEX usage_at ON usage_requests (at);
+     CREATE INDEX usage_day ON usage_requests (day);
+     CREATE INDEX usage_account_day ON usage_requests (account_id, day);
+     CREATE INDEX usage_session_day ON usage_requests (session_id, day);
+     CREATE INDEX usage_model_day ON usage_requests (model, day);
+     CREATE TABLE usage_indexed (run_id TEXT PRIMARY KEY, indexed_at TEXT NOT NULL, rows INTEGER NOT NULL);`
 ];
 const connections = new Map();
 export function dbPath(root) {

package/dist/sdk/core/interactiveProfile.d.ts

@@ -0,0 +1,46 @@
+import { type SecretStore } from "../accounts/secrets.js";
+export type SecretBackendDescriptor = {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'host';
+    id: string;
+};
+export interface InteractiveProfile {
+    version: 1;
+    dataRoot: string;
+    stateDir: string;
+    defaultVariantScope: string;
+    secretBackend: SecretBackendDescriptor;
+}
+export type InteractiveProfileOverrides = Partial<Omit<InteractiveProfile, 'version'>>;
+export interface InteractiveProfileLocation {
+    /** Overrides the home used for the default profile path. */
+    home?: string;
+    /** Selects a profile file directly, without searching any application-specific locations. */
+    configPath?: string;
+}
+/** Strict, bounded, credential-free configuration. Unknown fields are errors, not ignored secrets. */
+export declare function validateInteractiveProfile(value: unknown): InteractiveProfile;
+export declare function interactiveProfilePath(home?: string): string;
+/** Read only. Missing is legacy mode; malformed or inaccessible is never silently ignored. */
+export declare function readInteractiveProfile(location?: InteractiveProfileLocation): InteractiveProfile | null;
+/** Explicit roots > selected profile > caller's legacy defaults. Never creates roots or merges data. */
+export declare function resolveInteractiveProfile(options?: InteractiveProfileLocation & {
+    legacyDefaults?: InteractiveProfileOverrides;
+    overrides?: InteractiveProfileOverrides;
+}): InteractiveProfile;
+/**
+ * Explicit adoption only. Creates the profile file, never roots or credentials; it never replaces
+ * an existing profile or merges data. A pre-profile host must supply its selected backend in
+ * `legacyDefaults` so an absent profile cannot silently downgrade it to the file store.
+ */
+export declare function adoptInteractiveProfile(profile: InteractiveProfile, location?: InteractiveProfileLocation): void;
+/**
+ * Every participating process must map this host id to the same credential store. The account
+ * lock serializes access but cannot unify distinct native Keychain identities; no file fallback is
+ * allowed when a selected host adapter is unavailable.
+ */
+export declare function interactiveProfileSecretStore(profile: InteractiveProfile, host?: (descriptor: Extract<SecretBackendDescriptor, {
+    kind: 'host';
+}>) => SecretStore | Promise<SecretStore>): Promise<SecretStore>;