outsrc 0.2.0 → 0.2.1

package/README.md

@@ -51,7 +51,7 @@ Install it globally rather than running it through `npx`: agents launch the inst
 
 For agents and scripts, `outsrc init --json --repo <path> [--repo <path>] [--local claude,codex,grok] [--max-jobs <n|unlimited>] [--max-run-minutes <n|unlimited>]` prints one JSON event per line and exits with code 3 when a person has to act, such as logging in to a CLI. Rerun it after that step. Without `--local`, nothing is registered. A `settings` event lists the limits, repositories and targets so the agent can review them with the owner.
 
-`outsrc doctor` rechecks the configuration. `OUTSRC_HOME` moves the state directory away from `~/.outsrc`, which outsrc keeps readable by you only.
+`outsrc doctor` rechecks the configuration and asks the npm registry for the latest `outsrc`. Its JSON adds `update_available` (true only when the installed version is behind npm) and `version`: `{status, installed, latest}`, where `status` is `current`, `outdated`, `ahead` or `unknown`. Without `--json` it also prints one line to stderr, such as `outsrc 0.2.0 is installed; 0.3.0 is available. Upgrade with: npm install -g outsrc@latest`. Doctor never upgrades. If the registry cannot be reached within 3 seconds, `status` is `unknown` with an `error`, `update_available` is false and the exit code is unaffected. `OUTSRC_HOME` moves the state directory away from `~/.outsrc`, which outsrc keeps readable by you only.
 
 ## Settings
 
@@ -101,6 +101,7 @@ The MCP tools and the CLI commands return the same JSON.
 | `threads` | This caller's threads and their status |
 | `settings` | Every setting with its value, default and meaning (read-only) |
 | `history` | Every run in a thread, with its message and result |
+| `usage` | Local usage for today and the last 7 days, including totals by target |
 | `log` | A slice of a run's log |
 | `diff` | Changes since the thread started, committed or not (256 KiB by default) |
 | `stop` | Cancel a running thread |
@@ -108,6 +109,47 @@ The MCP tools and the CLI commands return the same JSON.
 
 CLI only: `outsrc config set` and `unset` change settings, `outsrc prune` deletes finished worktrees past their retention period, `outsrc migrate` imports threads from earlier versions, and `outsrc plugins` checks the plugin engines.
 
+### Local usage and spend
+
+Run `outsrc usage --caller grok --json` or call the MCP `usage` tool. Omit `--caller` on the CLI to include all callers. The command reads saved runs on this computer. It does not contact providers, scrape dashboards, or send usage to a cloud service.
+
+Every successful `inbox` response and every run in `history` includes these fields, including working, waiting, failed, and cancelled runs:
+
+```json
+{
+  "target": "grok-plugin",
+  "effort": null,
+  "model": "grok-4.7-build",
+  "usage": {
+    "tokens_in": 30655,
+    "tokens_out": 369,
+    "estimated_cost_usd": 0.021794,
+    "wall_minutes": 2
+  }
+}
+```
+
+The token and cost values above come from the sanitized Grok review fixture; wall minutes illustrate the shape. `tokens_in` and `tokens_out` are the vendor's reported input/output counters. Separate cache and reasoning counters are not added. `estimated_cost_usd` is the vendor-reported USD cost estimate; outsrc does not apply a price table or infer a subscription charge. `model` is the vendor-reported model, or the sole model named in its `modelUsage` metadata, falling back to the explicit model passed in the invocation. It is null when neither is known. `effort` is the explicit setting passed in that run's invocation, not a guessed vendor default. Paths that ignore model or effort, including Codex plugin branch reviews, report null for those fields.
+
+Claude and Grok native JSON result envelopes expose counters and cost when provided. Codex native JSONL `turn.completed.usage` events expose counters; cost stays null. Grok plugin review/critique envelopes expose usage through `result` or `grok.stdout`, counted once even when both contain it. The pinned Grok plugin 0.2.0 task path invokes the CLI with plain output, so task tokens and cost are null. Codex plugin 1.0.5 discards usage notifications, so its task and review tokens and cost are null. Their saved job results repeat the emitted payload and contain no additional usage to recover. Custom adapters have no supported usage contract, so their tokens and cost are null. Model-generated answer text is never interpreted as usage metadata. The engine pins remain unchanged.
+
+`wall_minutes` measures elapsed wrapper time, including setup, agent execution, plugin teardown, and result collection. It excludes time before the wrapper starts. Working runs, old records, and interrupted runs without a recorded duration have null wall minutes. Old records require no migration. Missing or invalid vendor metadata produces explicit nulls, never zero or invented numbers. A reported zero remains zero. Each run saves reported usage in `usage.json` as stdout arrives, then includes it in `result.json`. Deadline failures retain stdout usage. Cancellation and wrapper interruption recover the saved usage without reading mixed stdout/stderr logs. A later commit or result collection failure also retains it.
+
+The usage report has `as_of`, `today`, and `last_7_days`. Today starts at midnight in the local process time zone; the 7-day window is the preceding 168 hours. Runs are assigned by their submission time (`created_at`), including continuations, working runs, and retained discarded threads. Each window includes `since`, `runs`, the four numeric metrics, and a sorted `by_target` array with the same counts and metrics. Each metric is `{ "total": number | null, "missing_runs": number }`. A total is null if any included run lacks that metric, so known partial spend cannot appear as a complete total. Empty windows have zero runs and zero totals. Each saved run is counted once.
+
+`npm run verify` reruns the recorded-envelope finished-run checks through source and built CLI/MCP surfaces. `npm run smoke:native` requires non-null input/output counters on each succeeded continuation. `npm run smoke:plugins` requires Grok review counters and explicit nulls on pinned plugin paths that cannot report usage. The live smoke commands use provider accounts.
+
+## Watching jobs live
+
+`outsrc streams` (or `outsrc watch`) opens a grid of live agent logs in your browser, served from `127.0.0.1` on the machine that runs the jobs.
+
+- One pane per working thread. The header shows the short thread id, target, status, branch and run age. The body follows the tail of the latest run's `run.log`. Scroll up to pause; click "paused" to follow again.
+- New threads appear without a restart. With no working threads the page says so and keeps watching.
+- Finished threads stop growing and move to a muted strip for 15 minutes (`--recent-minutes`). Click one to show its log.
+- `--thread <id>` shows one thread only, finished or not. `--port <n>` fixes the port. `--no-open` prints the URL without opening a browser.
+
+The viewer reads `$OUTSRC_HOME/threads` (default `~/.outsrc`) about once a second, and only while a page is open. It never calls a vendor CLI or a model, writes nothing, and does not change what `send` or `inbox` report. The URL carries a random token. Stopping the viewer (Ctrl-C) leaves jobs running. It keeps no state of its own, so it outlives bot and outsrc upgrades and shows nothing once `~/.outsrc` is removed.
+
 ## Repository options
 
 ```toml
@@ -138,6 +180,24 @@ A custom target prints one JSON object with `kind` (`completed`, `needs_input` o
 
 Each finding has `priority` (`P0` to `P3`), `title`, `body`, `path` (or null) and `line` (or null).
 
+### Model cache
+
+A target with `models` in its config uses those. For every other target outsrc asks the vendor CLI for its models (a model-list command, not a model run, so it spends no tokens) and keeps the answer in `~/.outsrc/models.json` (`$OUTSRC_HOME/models.json`). `list_targets` reads that file, so a warm cache starts no vendor CLI. Each target shows `models_refreshed_at`, the time its entry was written, or null when its models come from config.
+
+- Miss: a target with no entry, or whose `adapter` or `command` changed since the entry was written, is discovered once and written back. On a first install the first `list_targets` (or `init`) fills the cache.
+- Stale: entries do not expire. outsrc serves an old entry until something refreshes it, so schedule a refresh.
+- Failed listing: a missing or logged-out CLI is cached as `models: null` until the next refresh.
+
+Refresh with `outsrc models refresh` (all targets) or `outsrc models refresh --target <name>`. `outsrc models` prints the cache. `outsrc list_targets --refresh`, or `list_targets` with `{"refresh": true}` over MCP, rediscovers before answering. To refresh twice a day with cron:
+
+```
+0 7,19 * * * /usr/bin/env outsrc models refresh >/dev/null 2>&1
+```
+
+On macOS a launchd agent with `StartCalendarInterval` at the same hours works the same way. Both need `PATH` to include the vendor CLIs.
+
+`send` refuses a `model` that is not in the target's configured or cached list, and the error lists the allowed models. When the cache has no list for the target (`models: null`) outsrc cannot check, and passes the model to the vendor CLI unchanged.
+
 ## Vendor plugin engines
 
 The `codex-plugin` and `grok-plugin` adapters drive the vendors' own Claude Code plugins, [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) and [xai-org/grok-build-plugin-cc](https://github.com/xai-org/grok-build-plugin-cc), both Apache-2.0. The plugin launches the CLI and supplies the review prompts, output schema and, for Codex, the built-in reviewer. outsrc keeps the mailbox, worktrees, repository list and filtered environment. It runs the engine scripts directly; no Claude Code session is involved.
@@ -167,6 +227,48 @@ The plugin scripts are the vendors' internal CLIs, not a documented API. outsrc
 
 To move a pin, run `outsrc engines pin <codex-plugin|grok-plugin> <commit|branch|tag>`. It updates `engines.lock.json` only if the contract check passes. Then run `npm run smoke:plugins` and keep the change only if that passes too.
 
+## Update checks
+
+`outsrc updates refresh` checks whether Claude Code, Codex, Grok Build and outsrc itself are behind their latest release. It runs `claude --version`, `codex --version`, `grok --version`, `grok update --check --json` and reads the npm registry. It calls no model and costs no tokens. It never installs anything: you upgrade by hand, or ask the bot to after you say yes.
+
+`outsrc updates` prints the last result without checking again, and `outsrc doctor` includes the same summary under `updates`.
+
+State lives in two files under `~/.outsrc` (or `OUTSRC_HOME`), both readable by you only:
+
+- `updates.json`: when the last check ran, each product's installed and latest version (or the error), and `pending`, the products that are behind. Only `refresh` writes it. A pending entry keeps its `first_seen_at` until a newer release appears. A failed check keeps the previous entry.
+- `updates-ack.json`: the notifications already shown to you. Only `outsrc updates ack` writes it.
+
+Each pending update is a notification with the id `<product>@<latest>`, for example `claude@2.1.286`. `refresh` lists the ones it found for the first time under `new`, and `unread` lists every pending notification not yet acknowledged. A rerun that finds nothing newer announces nothing, and an acknowledged version stays quiet until a newer one ships.
+
+Run it a few times a day. cron and launchd start jobs with a short `PATH` that usually lacks `node` and the CLIs, and a CLI that cannot be found counts as not installed. Give the job your shell's `PATH` (the output of `echo $PATH`). With cron:
+
+```
+PATH=<your PATH>
+17 */6 * * * outsrc updates refresh >/dev/null 2>&1
+```
+
+On macOS with launchd, save this as `~/Library/LaunchAgents/ing.outsrc.updates.plist`, fill in `PATH` and the `outsrc` path (the output of `command -v outsrc`), then run `launchctl load` on the file:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>ing.outsrc.updates</string>
+  <key>ProgramArguments</key>
+  <array><string>/usr/local/bin/outsrc</string><string>updates</string><string>refresh</string></array>
+  <key>EnvironmentVariables</key>
+  <dict><key>PATH</key><string>your PATH</string></dict>
+  <key>StartInterval</key><integer>21600</integer>
+  <key>RunAtLoad</key><true/>
+</dict>
+</plist>
+```
+
+### For bot authors
+
+When the bot next talks to its owner, it runs `outsrc updates --json` and, for each `unread` entry, tells the owner the product, installed version and latest version, and asks whether to upgrade. If the bot also reports to another agent, it forwards the same fields (`product`, `installed`, `latest`) there. After the owner has seen them, the bot runs `outsrc updates ack <id>...` (or `--all`) so they are not repeated. The bot upgrades only after the owner says yes.
+
 ## Limits
 
 outsrc checks that thread and run paths stay inside its state directory, and it signals a process only if it is still the job outsrc started. By default at most 4 threads work at once and a run is stopped after 2 hours (both settings). A run log stops growing at 1 MiB, and `log` returns at most 8 KiB.

package/dist/cli.js

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process";
 import { defaultConfigPath, defaultHome, loadConfigFile } from "./config.js";
 import { migrateLegacy } from "./migrate.js";
+import { modelCachePath, readModelCache } from "./model-cache.js";
 import { changeSetting, listSettings } from "./settings.js";
 import { defaultInitEnv, parseInitArgs, runInit } from "./init.js";
 import { createMailbox } from "./mailbox.js";
 import { installEngine, managedScript, readLock, resolveCommit, writeLockEntry } from "./engines.js";
 import { checkPluginContract, pluginVersion } from "./plugin-contract.js";
 import { isPluginAdapter, resolvePluginScript } from "./plugins.js";
-import { DEFAULT_CALLER, parseCaller } from "./types.js";
+import { startStreamServer } from "./streams.js";
+import { DEFAULT_CALLER, parseCaller, parseThreadId } from "./types.js";
+import { checkForUpdate, describeUpdate, installedVersion, registryFetchLatest, updateAvailable } from "./update-check.js";
+import { ack, ackFile, defaultProbe, readUpdates, refresh, unread, updatesFile } from "./updates.js";
 function pluginReports(explicit) {
     return ["codex-plugin", "grok-plugin"].flatMap((adapter) => {
         const script = explicit[adapter] ?? managedScript(defaultHome(), adapter) ?? resolvePluginScript(adapter);
@@ -36,6 +41,8 @@ function parseMailboxArgs(argv) {
     rest = callerFlag.rest;
     const json = hasFlag(rest, "--json");
     rest = rest.filter((arg) => arg !== "--json");
+    const refresh = hasFlag(rest, "--refresh");
+    rest = rest.filter((arg) => arg !== "--refresh");
     const names = ["--repo", "--target", "--message", "--thread", "--thread-id", "--request-id", "--model", "--effort", "--kind", "--base", "--ref", "--run-id", "--offset", "--limit"];
     const flags = {};
     for (const name of names) {
@@ -49,6 +56,7 @@ function parseMailboxArgs(argv) {
     return {
         caller: callerFlag.value !== undefined ? parseCaller(callerFlag.value) : undefined,
         json,
+        refresh,
         flags,
         positionals: rest,
     };
@@ -59,30 +67,98 @@ function writeJson(body, pretty = true) {
 const HELP = `outsrc init [--repo <path>]... [--yes] [--json] [--plugins|--no-plugins] [--local claude,codex,grok]
             [--max-jobs <n|unlimited>] [--max-run-minutes <n|unlimited>]
        config [list] | config set <key> <value> | config unset <key>
-       doctor | list_repos | list_targets | targets | threads | prune | migrate
+       doctor [--json] | list_repos | list_targets [--refresh] | targets | threads | prune | migrate
+       models [list] | models refresh [--target <name>]
        plugins [--codex <script>] [--grok <script>]
+       updates | updates refresh | updates ack <product@version>... | updates ack --all
        engines pin <codex-plugin|grok-plugin> <commit|branch|tag>
        send --repo <alias> --target <name> --message <text> [--caller <id>] [--json]
             [--thread-id <id>] [--request-id <id>] [--model <m>] [--effort <e>]
             [--kind task|review|adversarial_review] [--base <ref>] [--ref <ref>]
        inbox <thread_id> [--caller <id>] [--json]
        history <thread_id> [--caller <id>] [--json]
+       usage [--caller <id>] [--json]
        log <thread_id> [--run-id <id>] [--offset <n>] [--limit <n>] [--caller <id>] [--json]
        diff <thread_id> [--limit <n>] [--caller <id>] [--json]
        stop <thread_id> [--caller <id>] [--json]
        discard <thread_id> [--caller <id>] [--json]
+       streams [--thread <id>] [--port <n>] [--recent-minutes <n>] [--no-open]   (alias: watch)
 
 init sets up config and optional local MCP registration for local CLIs.
 Public install is the Outsrc bot from Bot Exchange; this CLI is for bot authors and advanced operators.
 
+streams opens a local browser grid of live run.log tails, one pane per working thread. It only reads
+files under the outsrc home; it never calls a vendor CLI or a model. See outsrc streams --help.
+
 Mailbox commands print JSON (same shapes as the stdio MCP tools). Pass --caller so each
-bot only sees its own threads; omit it on doctor/list_*/threads to act as the owner.
+bot only sees its own threads; omit it on doctor/list_*/threads/usage to act as the owner.
 `;
+const STREAMS_HELP = `outsrc streams [--thread <id>] [--port <n>] [--recent-minutes <n>] [--no-open]
+outsrc watch   (same command)
+
+Serves a grid of live run logs on http://127.0.0.1 and opens it in your browser.
+One pane per working thread: short id, target, status, branch and age, then the tail of the
+latest run's run.log. Panes follow new output; scroll up to pause, click "paused" to follow again.
+New threads appear without a restart. Finished threads stop growing and move to a muted strip
+(click one to show its log). Threads finished more than --recent-minutes ago (default 15) are hidden.
+
+  --thread <id>          Show only this thread, finished or not; waits for it if it does not exist yet
+  --port <n>             Listen on this port (default: a free one)
+  --recent-minutes <n>   How long finished threads stay in the strip (default 15)
+  --no-open              Print the URL without opening a browser
+
+The viewer reads $OUTSRC_HOME/threads (default ~/.outsrc) about once a second, only while a page is
+open. It never calls a vendor CLI or a model and writes nothing. The URL carries a random token and
+the server listens on 127.0.0.1 only. Ctrl-C stops the viewer; jobs keep running.
+`;
+function openBrowser(url) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+    try {
+        spawn(opener, [url], { detached: true, stdio: "ignore" }).on("error", () => { }).unref();
+    }
+    catch { /* the URL is printed anyway */ }
+}
+async function runStreams(argv) {
+    if (hasFlag(argv, "--help") || hasFlag(argv, "-h")) {
+        process.stdout.write(STREAMS_HELP);
+        return;
+    }
+    let rest = argv.filter((arg) => arg !== "--no-open");
+    const thread = takeFlag(rest, "--thread");
+    rest = thread.rest;
+    const port = takeFlag(rest, "--port");
+    rest = port.rest;
+    const recent = takeFlag(rest, "--recent-minutes");
+    rest = recent.rest;
+    if (rest.length)
+        throw new Error(`unknown argument: ${rest[0]}\n\n${STREAMS_HELP}`);
+    const portNumber = port.value === undefined ? 0 : Number(port.value);
+    if (!Number.isInteger(portNumber) || portNumber < 0 || portNumber > 65535)
+        throw new Error("--port must be 0-65535");
+    const recentMinutes = recent.value === undefined ? 15 : Number(recent.value);
+    if (!Number.isFinite(recentMinutes) || recentMinutes < 0)
+        throw new Error("--recent-minutes must be a number of minutes");
+    const server = await startStreamServer({
+        home: defaultHome(), port: portNumber, recentMs: recentMinutes * 60_000,
+        ...(thread.value !== undefined ? { thread: parseThreadId(thread.value) } : {}),
+    });
+    process.stdout.write(`outsrc streams: ${server.url}\nWatching ${defaultHome()}/threads. Ctrl-C stops the viewer; jobs keep running.\n`);
+    if (!hasFlag(argv, "--no-open"))
+        openBrowser(server.url);
+    await new Promise((resolve) => {
+        const stop = () => { void server.close().then(resolve); };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}
 const command = process.argv[2] ?? "help";
 try {
     if (command === "help" || command === "--help" || command === "-h") {
         process.stdout.write(HELP);
     }
+    else if (command === "streams" || command === "watch") {
+        await runStreams(process.argv.slice(3));
+    }
     else if (command === "init") {
         const options = parseInitArgs(process.argv.slice(3));
         const env = defaultInitEnv(defaultConfigPath(defaultHome()), options.json);
@@ -113,6 +189,25 @@ try {
             writeJson({ pinned: true, entry, next: "Run npm run smoke:plugins. Commit engines.lock.json if it passes; revert it if not." });
         }
     }
+    else if (command === "updates") {
+        const [sub, ...rest] = process.argv.slice(3).filter((arg) => arg !== "--json");
+        const home = defaultHome();
+        const files = { state: updatesFile(home), acks: ackFile(home) };
+        if (sub === undefined || sub === "list") {
+            const state = readUpdates(home);
+            writeJson({ ...state, unread: unread(home, state), files });
+        }
+        else if (sub === "refresh" && rest.length === 0) {
+            const { state, fresh } = await refresh(home, defaultProbe);
+            writeJson({ ...state, new: fresh, unread: unread(home, state), files });
+        }
+        else if (sub === "ack" && rest.length > 0) {
+            const all = rest.includes("--all");
+            writeJson({ acked: ack(home, all ? "all" : rest.filter((arg) => arg !== "--all")) });
+        }
+        else
+            throw new Error("usage: outsrc updates [list] | updates refresh | updates ack <product@version>... | updates ack --all");
+    }
     else if (command === "config") {
         const [sub, key, value, ...extra] = process.argv.slice(3).filter((arg) => arg !== "--json");
         const configPath = defaultConfigPath(defaultHome());
@@ -144,22 +239,30 @@ try {
         const parsed = parseMailboxArgs(process.argv.slice(3));
         // Owner CLI (no --caller) sees every thread for doctor/list/threads/prune.
         // Mailbox mutations and per-thread reads default to "local" when --caller is omitted.
-        const ownerCommands = new Set(["doctor", "list_repos", "repos", "list_targets", "targets", "threads", "prune", "migrate"]);
+        const ownerCommands = new Set(["doctor", "list_repos", "repos", "list_targets", "targets", "models", "threads", "usage", "prune", "migrate"]);
         const caller = parsed.caller ?? (ownerCommands.has(command) ? undefined : DEFAULT_CALLER);
         const box = createMailbox({ home, config, ...(caller !== undefined ? { caller } : {}) });
         switch (command) {
             case "doctor": {
                 const targets = box.listTargets().targets;
                 const plugins = Object.values(config.targets).flatMap((target) => target.adapter && isPluginAdapter(target.adapter) && target.command ? [checkPluginContract(target.adapter, target.command)] : []);
+                const version = await checkForUpdate(installedVersion(), registryFetchLatest());
+                // Reads the last `outsrc updates refresh`; the only network call doctor makes is the npm probe above.
+                const updatesState = readUpdates(home);
                 const report = {
+                    update_available: updateAvailable(version),
+                    version,
                     node: process.version,
                     config: defaultConfigPath(home),
                     repositories: box.listRepos().repos,
                     targets,
                     plugins,
-                    note: "Checks configuration, executable discovery and the vendor plugin CLI contract. Does not authenticate providers or establish an execution security boundary.",
+                    updates: { checked_at: updatesState.checked_at, pending: updatesState.pending, unread: unread(home, updatesState) },
+                    note: "Checks configuration, executable discovery, the vendor plugin CLI contract and whether npm has a newer outsrc. Does not upgrade, authenticate providers or establish an execution security boundary.",
                 };
                 writeJson(report);
+                if (!parsed.json)
+                    process.stderr.write(`${describeUpdate(version)}\n`);
                 if (targets.some((target) => !target.available) || plugins.some((plugin) => plugin.status === "broken"))
                     process.exitCode = 1;
                 break;
@@ -170,11 +273,29 @@ try {
                 break;
             case "list_targets":
             case "targets":
-                writeJson(box.listTargets());
+                writeJson(box.listTargets({ refresh: parsed.refresh }));
+                break;
+            case "models": {
+                const [sub, ...extra] = parsed.positionals;
+                if (extra.length || (sub !== undefined && sub !== "list" && sub !== "refresh"))
+                    throw new Error("usage: outsrc models [list] | models refresh [--target <name>]");
+                const target = parsed.flags["--target"];
+                if (sub === "refresh")
+                    writeJson({ path: modelCachePath(home), ...box.refreshModels(target) });
+                else
+                    writeJson({ path: modelCachePath(home), targets: readModelCache(home) });
                 break;
+            }
             case "threads":
                 writeJson(box.threads());
                 break;
+            case "usage": {
+                const result = box.usage();
+                writeJson(result);
+                if (!result.ok)
+                    process.exitCode = 1;
+                break;
+            }
             case "migrate": {
                 const migrated = migrateLegacy({ home, config });
                 writeJson(migrated);
@@ -294,7 +415,7 @@ try {
 catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     process.exitCode = 1;
-    const mailbox = new Set(["send", "inbox", "history", "log", "diff", "stop", "discard"]);
+    const mailbox = new Set(["send", "inbox", "history", "usage", "log", "diff", "stop", "discard"]);
     if (mailbox.has(command))
         process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
     else

package/dist/mailbox.d.ts

@@ -7,7 +7,9 @@ export declare function createMailbox(ctx: MailboxContext): {
             path: string;
         }[];
     };
-    listTargets: () => {
+    listTargets: (options?: {
+        refresh?: boolean;
+    }) => {
         targets: {
             name: string;
             adapter: import("./adapters.js").Adapter;
@@ -16,6 +18,7 @@ export declare function createMailbox(ctx: MailboxContext): {
                 default: string;
                 allowed: string[];
             } | null;
+            models_refreshed_at: string | null;
             effort: {
                 default: string;
                 allowed: string[];
@@ -25,6 +28,17 @@ export declare function createMailbox(ctx: MailboxContext): {
             resume: boolean;
         }[];
     };
+    refreshModels: (name?: string) => {
+        refreshed: Record<string, {
+            adapter: string;
+            command: string;
+            refreshedAt: string;
+            models: {
+                default: string;
+                allowed: string[];
+            } | null;
+        }>;
+    };
     send: (input: SendInput) => Promise<SendResult>;
     inbox: (threadId: string) => InboxResult;
     threads: () => {
@@ -52,11 +66,102 @@ export declare function createMailbox(ctx: MailboxContext): {
         ok: boolean;
         error: string;
     };
+    usage(): {
+        ok: boolean;
+        as_of: string;
+        today: {
+            runs: number;
+            tokens_in: {
+                total: number | null;
+                missing_runs: number;
+            };
+            tokens_out: {
+                total: number | null;
+                missing_runs: number;
+            };
+            estimated_cost_usd: {
+                total: number | null;
+                missing_runs: number;
+            };
+            wall_minutes: {
+                total: number | null;
+                missing_runs: number;
+            };
+            since: string;
+            by_target: {
+                runs: number;
+                tokens_in: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                tokens_out: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                estimated_cost_usd: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                wall_minutes: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                target: string;
+            }[];
+        };
+        last_7_days: {
+            runs: number;
+            tokens_in: {
+                total: number | null;
+                missing_runs: number;
+            };
+            tokens_out: {
+                total: number | null;
+                missing_runs: number;
+            };
+            estimated_cost_usd: {
+                total: number | null;
+                missing_runs: number;
+            };
+            wall_minutes: {
+                total: number | null;
+                missing_runs: number;
+            };
+            since: string;
+            by_target: {
+                runs: number;
+                tokens_in: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                tokens_out: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                estimated_cost_usd: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                wall_minutes: {
+                    total: number | null;
+                    missing_runs: number;
+                };
+                target: string;
+            }[];
+        };
+    } | {
+        ok: boolean;
+        error: string;
+    };
     history(threadId: string): {
         error?: never;
         ok: boolean;
         thread_id: ThreadId;
         runs: {
+            target: string;
+            effort: string | null;
+            model: string | null;
+            usage: Omit<import("./usage.js").RunUsage, "model" | "effort">;
             run_id: import("./types.js").RunId;
             request_id: string | null;
             created_at: string;