outsrc 0.2.0 → 0.2.1

package/dist/mailbox.js

@@ -8,13 +8,15 @@ import { buildInvocation } from "./adapters.js";
 import { addWorktree, hideAgentConfig } from "./git.js";
 import { commandExists, JOB_MARKER, jobEnv, pidAlive, processIdentity, sameProcess, startWrapper, stopOwnedProcess } from "./job.js";
 import { MAX_LOG_READ_BYTES, resolveLimits } from "./limits.js";
+import { resolveModels } from "./model-cache.js";
 import { branchName, filesystemPath, resolveInside, threadDir, threadsDir, worktreePath } from "./paths.js";
 import { isVerified, pluginVersion } from "./plugin-contract.js";
 import { cancelInvocation, engineDir, isPluginAdapter, teardownInvocation } from "./plugins.js";
 import { wrapMessage } from "./prompt.js";
-import { ProcessSchema, readJson, readResult, RunSchema, ThreadSchema, writeJson } from "./state.js";
+import { ProcessSchema, readJson, readResult, readRunUsage, RunSchema, ThreadSchema, writeJson } from "./state.js";
 import { collectWorkspaceDiff, getBaseCommit } from "./workspace.js";
-import { DEFAULT_CALLER, parseAlias, parseRunId, parseTargetName, parseThreadId } from "./types.js";
+import { DEFAULT_CALLER, MINTED_THREAD_ID, parseAlias, parseRunId, parseTargetName, parseThreadId } from "./types.js";
+import { aggregateUsage, emptyUsage } from "./usage.js";
 function id() { return randomBytes(8).toString("hex"); }
 function adapter(target, name) {
     const kind = target.adapter ?? (name === "claude" || name === "codex" || name === "grok" ? name : "custom");
@@ -43,7 +45,7 @@ function pluginStatus(target) {
 }
 function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
 function failedResult(message, sessionId = null) {
-    return { kind: "failed", message, sessionId, findings: [], exitCode: null, finishedAt: new Date().toISOString(), diffstat: "", commit: null };
+    return { kind: "failed", message, sessionId, findings: [], exitCode: null, finishedAt: new Date().toISOString(), diffstat: "", commit: null, usage: emptyUsage() };
 }
 const RequestSchema = z.object({
     fingerprint: z.string(), threadId: z.string().transform(parseThreadId), runId: z.string().transform(parseRunId),
@@ -98,14 +100,14 @@ export function createMailbox(ctx) {
         if (result)
             return result;
         if (existsSync(join(dir, "cancelled"))) {
-            const cancelled = { ...failedResult("Task cancelled", run.sessionId), kind: "cancelled" };
+            const cancelled = { ...failedResult("Task cancelled", run.sessionId), kind: "cancelled", usage: readRunUsage(dir) };
             writeJson(join(dir, "result.json"), cancelled);
             return cancelled;
         }
         if (alive)
             return null;
         if (started) {
-            const failed = failedResult("Agent wrapper stopped without publishing a result", run.sessionId);
+            const failed = { ...failedResult("Agent wrapper stopped without publishing a result", run.sessionId), usage: readRunUsage(dir) };
             writeJson(join(dir, "result.json"), failed);
             return failed;
         }
@@ -130,18 +132,19 @@ export function createMailbox(ctx) {
             const thread = loadThread(threadId);
             const { dir, run } = current(thread);
             const result = resultFor(thread);
+            const fields = usageFields(thread, result);
             if (!result) {
                 const age = Math.max(0, Date.now() - Date.parse(run.createdAt));
                 const retry = ctx.retryAfterSeconds ?? Math.min(300, 30 * 2 ** Math.floor(age / 120_000));
-                return { ok: true, status: "working", retry_after_seconds: retry, run_id: run.id, progress: tail(dir).trim().split("\n").slice(-4).join("\n") };
+                return { ...fields, ok: true, status: "working", retry_after_seconds: retry, run_id: run.id, progress: tail(dir).trim().split("\n").slice(-4).join("\n") };
             }
             if (result.kind === "needs_input")
                 return {
-                    ok: true, status: "needs_input", retry_after_seconds: 0, run_id: run.id,
+                    ...fields, ok: true, status: "needs_input", retry_after_seconds: 0, run_id: run.id,
                     message: result.message, question_id: run.id, session_id: result.sessionId,
                 };
             return {
-                ok: true, status: result.kind === "completed" ? "succeeded" : result.kind,
+                ...fields, ok: true, status: result.kind === "completed" ? "succeeded" : result.kind,
                 run_id: run.id, message: result.message, branch: thread.branch, worktree: thread.worktree,
                 diffstat: { raw: result.diffstat }, exit_code: result.exitCode,
                 session_id: result.sessionId, findings: result.findings, commit: result.commit,
@@ -151,6 +154,24 @@ export function createMailbox(ctx) {
             return { ok: false, error: errorMessage(error) };
         }
     }
+    function usageFields(thread, result) {
+        const { model, effort, ...usage } = result?.usage ?? emptyUsage();
+        return { target: thread.target, effort, model, usage };
+    }
+    function savedRuns(thread) {
+        const root = join(threadDir(ctx.home, thread.id), "runs");
+        return readdirSync(root).flatMap((runId) => {
+            let directory;
+            try {
+                directory = storedRunDir(thread.id, runId);
+            }
+            catch {
+                return [];
+            }
+            const run = RunSchema.parse(readJson(join(directory, "run.json")));
+            return [{ run, result: run.id === thread.latestRunId ? resultFor(thread) : readResult(directory) }];
+        }).sort((a, b) => a.run.createdAt.localeCompare(b.run.createdAt));
+    }
     function replayRequest(file, requestFingerprint) {
         const previous = RequestSchema.parse(readJson(file));
         if (previous.fingerprint !== requestFingerprint)
@@ -236,8 +257,8 @@ export function createMailbox(ctx) {
                 const targetConfig = ctx.config.targets[target];
                 if (!targetConfig)
                     throw new Error(`unknown target: ${target}`);
-                if (input.model && targetConfig.models && !targetConfig.models.allowed.includes(input.model))
-                    throw new Error(`model not allowed: ${input.model}`);
+                if (input.model)
+                    checkModel(target, targetConfig, input.model);
                 if (input.effort && targetConfig.effort && !targetConfig.effort.allowed.includes(input.effort))
                     throw new Error(`effort not allowed: ${input.effort}`);
                 const repoPath = ctx.config.repos.find((item) => item.alias === repo)?.path ?? "";
@@ -370,6 +391,23 @@ export function createMailbox(ctx) {
                 }
             }).sort((a, b) => b.created_at.localeCompare(a.created_at)) };
     }
+    function cachedModels(targets, refresh = false) {
+        const unconfigured = Object.fromEntries(Object.entries(targets).flatMap(([name, target]) => target.models ? [] : [[name, adapter(target, name)]]));
+        return resolveModels({ home: ctx.home, targets: unconfigured, refresh, ...(ctx.discoverModels ? { discover: ctx.discoverModels } : {}) });
+    }
+    // A model outside the configured or cached list is refused rather than passed to the vendor CLI. When discovery
+    // could not list the target's models there is nothing to check against, and the vendor CLI decides.
+    function checkModel(name, target, model) {
+        if (target.models) {
+            if (!target.models.allowed.includes(model))
+                throw new Error(`model not allowed: ${model}. Allowed for ${name}: ${target.models.allowed.join(", ")} (from config)`);
+            return;
+        }
+        const entry = cachedModels({ [name]: target })[name];
+        if (entry?.models && !entry.models.allowed.includes(model)) {
+            throw new Error(`model not allowed: ${model}. Allowed for ${name}: ${entry.models.allowed.join(", ")} (cached ${entry.refreshedAt}; run outsrc models refresh if the list is out of date)`);
+        }
+    }
     function discard(threadId) {
         try {
             const thread = loadThread(threadId);
@@ -396,33 +434,60 @@ export function createMailbox(ctx) {
     }
     return {
         listRepos: () => ({ repos: ctx.config.repos.map(({ alias, path }) => ({ alias, path })) }),
-        listTargets: () => ({ targets: Object.entries(ctx.config.targets).map(([name, target]) => ({
-                name, adapter: adapter(target, name).adapter, available: commandExists(target.command),
-                models: target.models ?? null, effort: target.effort ?? null,
-                description: target.description ?? "", cost_note: target.costNote ?? "Not configured",
-                resume: adapter(target, name).adapter !== "custom" || target.args.some((arg) => arg.includes("{session_id}")),
-                ...pluginStatus(adapter(target, name)),
-            })) }),
+        listTargets: (options = {}) => {
+            const cached = cachedModels(ctx.config.targets, options.refresh);
+            return { targets: Object.entries(ctx.config.targets).map(([name, target]) => ({
+                    name, adapter: adapter(target, name).adapter, available: commandExists(target.command),
+                    models: target.models ?? cached[name]?.models ?? null, models_refreshed_at: cached[name]?.refreshedAt ?? null,
+                    effort: target.effort ?? null,
+                    description: target.description ?? "", cost_note: target.costNote ?? "Not configured",
+                    resume: adapter(target, name).adapter !== "custom" || target.args.some((arg) => arg.includes("{session_id}")),
+                    ...pluginStatus(adapter(target, name)),
+                })) };
+        },
+        refreshModels: (name) => {
+            if (name === undefined)
+                return { refreshed: cachedModels(ctx.config.targets, true) };
+            const target = ctx.config.targets[name];
+            if (!target)
+                throw new Error(`unknown target: ${name}`);
+            return { refreshed: cachedModels({ [name]: target }, true) };
+        },
         send, inbox, threads, discard,
+        usage() {
+            try {
+                const samples = [];
+                for (const name of existsSync(threadsDir(ctx.home)) ? readdirSync(threadsDir(ctx.home)) : []) {
+                    if (!MINTED_THREAD_ID.test(name))
+                        continue;
+                    let thread;
+                    try {
+                        thread = loadThread(name);
+                    }
+                    catch (error) {
+                        if (errorMessage(error) === `unknown thread_id: ${name}`)
+                            continue;
+                        throw error;
+                    }
+                    for (const { run, result } of savedRuns(thread)) {
+                        samples.push({ target: thread.target, created_at: run.createdAt, usage: result?.usage ?? emptyUsage() });
+                    }
+                }
+                return aggregateUsage(samples);
+            }
+            catch (error) {
+                return { ok: false, error: errorMessage(error) };
+            }
+        },
         history(threadId) {
             try {
                 const thread = loadThread(threadId);
-                const root = join(threadDir(ctx.home, thread.id), "runs");
-                return { ok: true, thread_id: thread.id, runs: readdirSync(root).flatMap((runId) => {
-                        let directory;
-                        try {
-                            directory = storedRunDir(thread.id, runId);
-                        }
-                        catch {
-                            return [];
-                        }
-                        const run = RunSchema.parse(readJson(join(directory, "run.json")));
-                        const result = readResult(directory);
-                        return [{ run_id: run.id, request_id: run.requestId, created_at: run.createdAt, message: run.message,
-                                status: result ? (result.kind === "completed" ? "succeeded" : result.kind) : "working",
-                                session_id: result?.sessionId ?? run.sessionId, final_message: result?.message ?? null,
-                                findings: result?.findings ?? [], exit_code: result?.exitCode ?? null }];
-                    }).sort((a, b) => a.created_at.localeCompare(b.created_at)) };
+                return { ok: true, thread_id: thread.id, runs: savedRuns(thread).map(({ run, result }) => {
+                        return { ...usageFields(thread, result), run_id: run.id, request_id: run.requestId, created_at: run.createdAt, message: run.message,
+                            status: result ? (result.kind === "completed" ? "succeeded" : result.kind) : "working",
+                            session_id: result?.sessionId ?? run.sessionId, final_message: result?.message ?? null,
+                            findings: result?.findings ?? [], exit_code: result?.exitCode ?? null };
+                    }) };
             }
             catch (error) {
                 return { ok: false, error: errorMessage(error) };

package/dist/model-cache.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { Adapter, AdapterTarget } from "./adapters.js";
+import { type ModelOptions } from "./models.js";
+export type Discover = (adapter: Adapter, command: string) => ModelOptions | null;
+declare const EntrySchema: z.ZodObject<{
+    adapter: z.ZodString;
+    command: z.ZodString;
+    refreshedAt: z.ZodString;
+    models: z.ZodNullable<z.ZodObject<{
+        default: z.ZodString;
+        allowed: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ModelCacheEntry = z.infer<typeof EntrySchema>;
+export declare function modelCachePath(home: string): string;
+/** A missing or unreadable cache reads as empty, so the next lookup rediscovers. */
+export declare function readModelCache(home: string): Record<string, ModelCacheEntry>;
+/**
+ * Cached models per target. A target is discovered when it has no entry, when its adapter or command changed
+ * since the entry was written, or when `refresh` names it. Everything else is served from the file without
+ * spawning a vendor CLI. Discovery only runs each vendor's model-list command; it never runs a model.
+ */
+export declare function resolveModels(options: {
+    home: string;
+    targets: Record<string, AdapterTarget>;
+    refresh?: boolean;
+    discover?: Discover;
+}): Record<string, ModelCacheEntry>;
+export {};

package/dist/model-cache.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { ensureOutsrcHome, writeHomeFile } from "./fs-home.js";
+import { discoverModels } from "./models.js";
+const EntrySchema = z.object({
+    adapter: z.string(),
+    command: z.string(),
+    refreshedAt: z.string(),
+    models: z.object({ default: z.string(), allowed: z.array(z.string()) }).nullable(),
+});
+const CacheSchema = z.object({ version: z.literal(1), targets: z.record(z.string(), EntrySchema) });
+export function modelCachePath(home) {
+    return join(home, "models.json");
+}
+/** A missing or unreadable cache reads as empty, so the next lookup rediscovers. */
+export function readModelCache(home) {
+    const file = modelCachePath(home);
+    if (!existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+    const parsed = CacheSchema.safeParse(raw);
+    return parsed.success ? parsed.data.targets : {};
+}
+function writeModelCache(home, targets) {
+    ensureOutsrcHome(home);
+    const file = modelCachePath(home);
+    const temp = `${file}.${process.pid}.tmp`;
+    writeHomeFile(temp, `${JSON.stringify({ version: 1, targets }, null, 2)}\n`);
+    renameSync(temp, file);
+}
+/**
+ * Cached models per target. A target is discovered when it has no entry, when its adapter or command changed
+ * since the entry was written, or when `refresh` names it. Everything else is served from the file without
+ * spawning a vendor CLI. Discovery only runs each vendor's model-list command; it never runs a model.
+ */
+export function resolveModels(options) {
+    const discover = options.discover ?? discoverModels;
+    const cache = readModelCache(options.home);
+    const result = {};
+    let changed = false;
+    for (const [name, target] of Object.entries(options.targets)) {
+        const cached = cache[name];
+        if (!options.refresh && cached && cached.adapter === target.adapter && cached.command === target.command) {
+            result[name] = cached;
+            continue;
+        }
+        const entry = { adapter: target.adapter, command: target.command, refreshedAt: new Date().toISOString(), models: discover(target.adapter, target.command) };
+        cache[name] = entry;
+        result[name] = entry;
+        changed = true;
+    }
+    if (changed)
+        writeModelCache(options.home, cache);
+    return result;
+}

package/dist/models.d.ts

@@ -0,0 +1,10 @@
+import type { Adapter } from "./adapters.js";
+export type ModelOptions = {
+    default: string;
+    allowed: string[];
+};
+export declare function parseClaudeModels(stdout: string): ModelOptions | null;
+export declare function parseCodexModels(stdout: string): ModelOptions | null;
+export declare function parseGrokModels(stdout: string): ModelOptions | null;
+/** Asks the target's CLI which models it can use. Null when the adapter cannot list or the CLI fails. */
+export declare function discoverModels(adapter: Adapter, command: string): ModelOptions | null;

package/dist/models.js

@@ -0,0 +1,108 @@
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { z } from "zod";
+const ClaudeInit = z.object({
+    type: z.literal("control_response"),
+    response: z.object({
+        subtype: z.literal("success"),
+        response: z.object({ models: z.array(z.object({ value: z.string().min(1), resolvedModel: z.string().min(1).optional() })) }),
+    }),
+});
+// The Agent SDK's supportedModels(): the initialize control response lists every --model value the account can use.
+// The "default" entry names the account default; a model set in the user's own settings still wins at run time.
+export function parseClaudeModels(stdout) {
+    for (const line of stdout.split("\n")) {
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const init = ClaudeInit.safeParse(value);
+        if (!init.success)
+            continue;
+        const models = init.data.response.response.models;
+        const fallback = models.find((model) => model.value === "default")?.resolvedModel;
+        const allowed = [...new Set(models.map((model) => model.value).filter((name) => name !== "default"))];
+        if (!fallback || allowed.length === 0)
+            return null;
+        return { default: fallback, allowed: allowed.includes(fallback) ? allowed : [fallback, ...allowed] };
+    }
+    return null;
+}
+const CodexCatalog = z.object({
+    models: z.array(z.object({ slug: z.string().min(1), visibility: z.string(), priority: z.number() })),
+});
+// Codex's own picker shows the "list" models and defaults to the highest priority one, as app-server model/list reports.
+export function parseCodexModels(stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const catalog = CodexCatalog.safeParse(value);
+    if (!catalog.success)
+        return null;
+    const listed = catalog.data.models.filter((model) => model.visibility === "list").sort((a, b) => a.priority - b.priority);
+    const first = listed[0];
+    return first ? { default: first.slug, allowed: listed.map((model) => model.slug) } : null;
+}
+// `grok models` has no JSON mode. It prints "Available models:" then one "* id (default)" or "- id" line per model.
+export function parseGrokModels(stdout) {
+    const lines = stdout.split("\n");
+    const start = lines.findIndex((line) => /^available models:/i.test(line.trim()));
+    if (start < 0)
+        return null;
+    const allowed = [];
+    let fallback;
+    for (const line of lines.slice(start + 1)) {
+        const match = /^\s*[*-]\s+(\S+)(\s+\(default\))?\s*$/.exec(line);
+        if (!match?.[1])
+            continue;
+        allowed.push(match[1]);
+        if (match[2])
+            fallback = match[1];
+    }
+    fallback ??= /^default model:\s*(\S+)/im.exec(stdout)?.[1];
+    return fallback && allowed.includes(fallback) ? { default: fallback, allowed } : null;
+}
+const CLAUDE_INIT = `${JSON.stringify({ type: "control_request", request_id: "outsrc-models", request: { subtype: "initialize" } })}\n`;
+// Plugin engines run the vendor CLI themselves: the Codex companion spawns `codex` from PATH, the Grok bridge
+// `$GROK_BINARY` or `grok`. Neither engine has a model-list subcommand, so outsrc asks the CLI they run.
+function lister(adapter, command) {
+    switch (adapter) {
+        case "claude":
+            return {
+                command,
+                args: ["-p", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--no-session-persistence",
+                    "--setting-sources", "user", "--strict-mcp-config", "--settings", JSON.stringify({ disableAllHooks: true })],
+                input: CLAUDE_INIT,
+                parse: parseClaudeModels,
+            };
+        case "codex": return { command, args: ["debug", "models"], parse: parseCodexModels };
+        case "codex-plugin": return { command: "codex", args: ["debug", "models"], parse: parseCodexModels };
+        case "grok": return { command, args: ["models"], parse: parseGrokModels };
+        case "grok-plugin": return { command: process.env.GROK_BINARY ?? "grok", args: ["models"], parse: parseGrokModels };
+        // A custom target's command has no known listing contract.
+        case "custom": return null;
+        default: {
+            const exhaustive = adapter;
+            throw new Error(`unknown adapter: ${exhaustive}`);
+        }
+    }
+}
+/** Asks the target's CLI which models it can use. Null when the adapter cannot list or the CLI fails. */
+export function discoverModels(adapter, command) {
+    const plan = lister(adapter, command);
+    if (!plan || !plan.command)
+        return null;
+    const result = spawnSync(plan.command, plan.args, {
+        cwd: tmpdir(), encoding: "utf8", timeout: 30_000, stdio: ["pipe", "pipe", "ignore"], input: plan.input ?? "",
+    });
+    if (result.error || result.status !== 0)
+        return null;
+    return plan.parse(result.stdout);
+}

package/dist/server.js

@@ -23,8 +23,9 @@ export async function handleTool(box, name, args) {
     try {
         switch (name) {
             case "list_repos": return response(box.listRepos());
-            case "list_targets": return response(box.listTargets());
+            case "list_targets": return response(box.listTargets({ refresh: args.refresh === true }));
             case "threads": return response(box.threads());
+            case "usage": return response(box.usage());
             case "history": return response(box.history(text(args.thread_id)));
             case "send": {
                 const input = {
@@ -74,9 +75,13 @@ export function makeServer(mailbox, configPath) {
             return response({ ok: false, error: error instanceof Error ? error.message : String(error) });
         }
     });
-    server.registerTool("list_targets", { description: "List available targets, configured models/effort, continuation support and owner-provided routing/cost notes.", inputSchema: {} }, async () => handleTool(mailbox(), "list_targets", {}));
+    server.registerTool("list_targets", {
+        description: "List available targets, their models and effort, continuation support and owner-provided routing/cost notes. Models not set in config come from a local cache refreshed by outsrc models refresh; models_refreshed_at says when. Pass refresh: true to ask each vendor CLI again, which is slow.",
+        inputSchema: { refresh: z.boolean().optional().describe("Rediscover models from each vendor CLI instead of reading the cache") },
+    }, async (args) => handleTool(mailbox(), "list_targets", args));
     server.registerTool("threads", { description: "List this caller's saved conversations, current status and recent progress. Recover a lost thread ID here. Other callers' threads are not visible.", inputSchema: {} }, async () => handleTool(mailbox(), "threads", {}));
     server.registerTool("history", { description: "List all runs, submitted messages and saved results in a thread.", inputSchema: { thread_id: z.string() } }, async (args) => handleTool(mailbox(), "history", args));
+    server.registerTool("usage", { description: "Read this caller's local usage for today and the last 7 days, including totals by target. Each metric has total and missing_runs. An incomplete total is null. No provider dashboards or network requests are used.", inputSchema: {} }, async () => handleTool(mailbox(), "usage", {}));
     server.registerTool("send", {
         description: "Start a task with repo + target + message, or continue a finished/waiting session with thread_id + message. Supply a stable request_id for retryable delivery. Returns a thread_id and run_id immediately. Poll inbox using its retry_after_seconds. Review kinds request findings without edits. With a plugin target (codex-plugin, grok-plugin), a review with base runs the vendor plugin's own diff review against that base; review ignores message text there, while adversarial_review uses it as focus. Without base, reviews run read-only in the vendor sandbox.",
         inputSchema: {

package/dist/state.d.ts

@@ -28,6 +28,14 @@ export declare const RunSchema: z.ZodObject<{
     sessionId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const ResultSchema: z.ZodObject<{
+    usage: z.ZodDefault<z.ZodObject<{
+        tokens_in: z.ZodNullable<z.ZodNumber>;
+        tokens_out: z.ZodNullable<z.ZodNumber>;
+        estimated_cost_usd: z.ZodNullable<z.ZodNumber>;
+        wall_minutes: z.ZodNullable<z.ZodNumber>;
+        model: z.ZodNullable<z.ZodString>;
+        effort: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
     kind: z.ZodEnum<{
         cancelled: "cancelled";
         completed: "completed";
@@ -62,6 +70,14 @@ export declare function writeJson(file: string, value: unknown): void;
 export declare function readJson(file: string): unknown;
 export declare function runDirectory(threadDirectory: string, runId: string): string;
 export declare function readResult(directory: string): {
+    usage: {
+        tokens_in: number | null;
+        tokens_out: number | null;
+        estimated_cost_usd: number | null;
+        wall_minutes: number | null;
+        model: string | null;
+        effort: string | null;
+    };
     kind: "cancelled" | "completed" | "failed" | "needs_input";
     message: string;
     sessionId: string | null;
@@ -77,3 +93,11 @@ export declare function readResult(directory: string): {
     diffstat: string;
     commit: string | null;
 } | null;
+export declare function readRunUsage(directory: string): {
+    tokens_in: number | null;
+    tokens_out: number | null;
+    estimated_cost_usd: number | null;
+    wall_minutes: number | null;
+    model: string | null;
+    effort: string | null;
+};

package/dist/state.js

@@ -4,6 +4,7 @@ import { writeHomeFile } from "./fs-home.js";
 import { join } from "node:path";
 import { z } from "zod";
 import { FindingSchema } from "./adapters.js";
+import { emptyUsage, RunUsageSchema } from "./usage.js";
 import { parseAlias, parseRunId, parseTargetName, parseThreadId, STORAGE_ID } from "./types.js";
 export const ThreadSchema = z.object({
     version: z.literal(2),
@@ -30,6 +31,7 @@ export const RunSchema = z.object({
     sessionId: z.string().nullable(),
 });
 export const ResultSchema = z.object({
+    usage: RunUsageSchema.default(emptyUsage),
     kind: z.enum(["completed", "needs_input", "failed", "cancelled"]),
     message: z.string(),
     sessionId: z.string().nullable(),
@@ -59,3 +61,11 @@ export function readResult(directory) {
     const file = join(directory, "result.json");
     return existsSync(file) ? ResultSchema.parse(readJson(file)) : null;
 }
+export function readRunUsage(directory) {
+    try {
+        return RunUsageSchema.parse(readJson(join(directory, "usage.json")));
+    }
+    catch {
+        return emptyUsage();
+    }
+}

package/dist/streams.d.ts

@@ -0,0 +1,49 @@
+import { type ThreadId } from "./types.js";
+export type StreamStatus = "working" | "needs_input" | "succeeded" | "failed" | "cancelled" | "stopped";
+export type StreamPane = {
+    thread_id: ThreadId;
+    repo: string;
+    target: string;
+    branch: string;
+    status: StreamStatus;
+    live: boolean;
+    created_at: string;
+    run_id: string;
+    run_started_at: string;
+    finished_at: string | null;
+    log_size: number;
+};
+export type Scanner = (now?: number) => StreamPane[];
+export declare const INITIAL_TAIL_BYTES: number;
+/**
+ * Returns a scanner over `<home>/threads`. Working threads are always listed; finished ones only if they finished
+ * within `recentMs`, or if they are the pinned `thread`. A finished thread whose thread.json has not changed is not
+ * reread, so each tick costs one stat per old thread.
+ */
+export declare function createScanner(input: {
+    home: string;
+    thread?: ThreadId;
+    recentMs: number;
+}): Scanner;
+/** Reads a run log from `offset`. `reset` is true when the file shrank or the caller asks for the first read. */
+export declare function readLogFrom(home: string, pane: Pick<StreamPane, "thread_id" | "run_id">, offset: number | null): {
+    text: string;
+    next: number;
+    reset: boolean;
+};
+export type StreamServer = {
+    url: string;
+    port: number;
+    token: string;
+    close(): Promise<void>;
+    clients(): number;
+};
+export declare function startStreamServer(input: {
+    home: string;
+    thread?: ThreadId;
+    host?: string;
+    port?: number;
+    pollMs?: number;
+    recentMs?: number;
+    token?: string;
+}): Promise<StreamServer>;