@bivy/bivy 0.21.2-staging.1 → 0.21.2-staging.3

package/bin/cli-commands.mjs

@@ -129,7 +129,7 @@ export const COMMANDS = [
 
   // Help and discovery
   { name: "guide", group: "help", scope: "node", json: true, usage: "guide [topic] [--json]", summary: "Short playbooks for agents: show the user, talk to them, long work, more hands, automate",
-    tools: [{ name: "bivy_guide", description: "Short playbooks for working in Bivy. Without a topic, lists them.", input: { topic: { type: "string", description: "show-the-user, talk-to-the-user, long-work, more-hands or automate." } }, argv: ["guide", { arg: "topic" }] }] },
+    tools: [{ name: "bivy_guide", description: "Short playbooks for working in Bivy. Without a topic, lists them.", input: { topic: { type: "string", description: "show-the-user, talk-to-the-user, long-work, more-hands, automate or add-an-agent." } }, argv: ["guide", { arg: "topic" }] }] },
   { name: "help", aliases: ["-h", "--help"], group: "help", scope: "node", json: true, usage: "help [command] [--json]", summary: "Show this help, one command's row, or every command as JSON" },
   { name: "version", aliases: ["--version", "-v"], group: "help", scope: "node", usage: "version", summary: "Print the installed Bivy version" },
 

package/bin/guides/add-an-agent.md

@@ -0,0 +1,39 @@
+# Add an agent: any ACP agent or CLI
+
+Summary: Make another coding agent available in Bivy, writing a small adapter when its CLI needs one.
+
+An agent with an ACP mode needs only its command:
+
+    bivy agent add gemini-acp --command gemini --args '["--experimental-acp"]'
+
+Any other CLI that takes a prompt on stdin (or as its last argument with
+`--prompt-mode argv`):
+
+    bivy agent add review-bot --transport process --command review-bot --args '["run"]'
+
+It is in the picker at once. Check it with one real turn, which prints the answer:
+
+    bivy exec -a gemini-acp "Say hello"
+
+When the CLI's output needs translating, write an adapter: a program Bivy runs
+once per turn with the prompt on stdin. It prints one JSON event per line:
+
+    {"type":"session.started","sessionId":"abc"}     # passed back as {id} to resume
+    {"type":"message.reasoning","text":"…"}
+    {"type":"tool.call","toolCallId":"t1","name":"bash","input":{"command":"ls"}}
+    {"type":"tool.result","toolCallId":"t1","result":"…"}
+    {"type":"message.delta","text":"The answer…"}
+    {"type":"usage","tokens":{"input_tokens":10,"output_tokens":20}}
+    {"type":"session.done"}                          # or {"type":"session.error","error":"…"}
+
+Start from examples/agents/jsonl-adapter/adapter.mjs in the Bivy repo, then:
+
+    bivy agent add my-agent --transport process --parser bivy-protocol \
+      --command "$PWD/adapter.mjs" --resume-args '["--resume","{id}"]'
+    bivy exec -a my-agent "List the files here"
+
+These events report what the agent did; they cannot ask before a tool runs. For
+approvals, the adapter must speak ACP (`--transport acp`).
+
+The entry lives under `agents:` in the node's config.yaml (`bivy agent list`,
+`bivy agent remove <id>`). The full format is in docs/add-an-agent.md.

package/dist/agent-cli.js

@@ -1,21 +1,18 @@
 #!/usr/bin/env node
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright (c) 2026 Petter André Sjulstad
-/** First-class BYO-agent convenience CLI backed by the ordinary plugin manifest. */
+/** First-class bring-your-own-agent CLI: writes `agents:` in the node config.yaml. */
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { stringify as stringifyYaml } from "yaml";
-import { currentBivyVersion } from "./app-version.js";
 import { defaultDataDir } from "./data-dir.js";
-import { recommendedBivyRange } from "./plugin-sdk/index.js";
-import { installPlugin, listInstalledPlugins, removePlugin } from "./plugins/store.js";
+import { mergeLegacyIntoNodeConfig, nodeConfigPath, readNodeConfig, writeNodeConfig } from "./node-config.js";
+import { listInstalledPlugins, removePlugin } from "./plugins/store.js";
 function option(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
 }
 function positional(args) {
-    const valued = new Set(["--command", "--transport", "--adapter", "--args", "--name", "--prompt-mode", "--data-dir"]);
+    const valued = new Set(["--command", "--transport", "--adapter", "--args", "--name", "--prompt-mode", "--parser", "--resume-args", "--data-dir"]);
     const out = [];
     for (let index = 0; index < args.length; index += 1) {
         if (valued.has(args[index])) {
@@ -42,17 +39,35 @@ function parseArgs(value) {
         parsed = JSON.parse(value);
     }
     catch {
-        throw new Error("--args must be a JSON string array");
+        throw new Error("--args and --resume-args must be JSON string arrays");
     }
     if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) {
-        throw new Error("--args must be a JSON string array");
+        throw new Error("--args and --resume-args must be JSON string arrays");
     }
     return parsed;
 }
-function localManifest(args) {
+function readJson(dataDir, name) {
+    try {
+        const value = JSON.parse(fs.readFileSync(path.join(dataDir, name), "utf8"));
+        return value && typeof value === "object" ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The node's config.yaml, or the one the daemon would create from legacy files
+ *  — never a bare file that would skip that migration. */
+function nodeConfig(dataDir) {
+    return readNodeConfig(dataDir) ?? mergeLegacyIntoNodeConfig(readJson(dataDir, "cli.json"), readJson(dataDir, "settings.json"));
+}
+function agentId(args) {
     const id = positional(args)[1]?.trim().toLowerCase() ?? "";
     if (!/^[a-z][a-z0-9-]{1,47}$/.test(id))
         throw new Error("Agent id must be a lowercase slug of 2-48 characters");
+    return id;
+}
+/** `bivy agent add` flags → the `adapter` block config.yaml and plugins share. */
+function agentConfig(args, id) {
     const command = option(args, "--command")?.trim();
     if (!command)
         throw new Error("--command is required");
@@ -61,29 +76,26 @@ function localManifest(args) {
         throw new Error("--transport must be acp or process");
     const adapterArgs = parseArgs(option(args, "--args"));
     const name = option(args, "--name")?.trim() || id.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
-    const promptModeValue = option(args, "--prompt-mode") ?? "stdin";
-    if (promptModeValue !== "stdin" && promptModeValue !== "argv")
+    if (transport === "acp") {
+        for (const flag of ["--prompt-mode", "--parser", "--resume-args"])
+            if (option(args, flag))
+                throw new Error(`${flag} applies to --transport process only`);
+        return { name, adapter: { kind: "acp", command, ...(adapterArgs.length ? { args: adapterArgs } : {}) } };
+    }
+    const promptMode = option(args, "--prompt-mode") ?? "stdin";
+    if (promptMode !== "stdin" && promptMode !== "argv")
         throw new Error("--prompt-mode must be stdin or argv");
-    const promptMode = promptModeValue;
+    const parser = option(args, "--parser");
+    const resumeArgs = option(args, "--resume-args");
     return {
-        apiVersion: "bivy.sh/v1alpha1",
-        kind: "Plugin",
-        metadata: {
-            id,
-            name,
-            version: "0.1.0",
-            description: `Local integration for the ${name} agent.`,
-        },
-        requires: { bivy: recommendedBivyRange(currentBivyVersion()) },
-        contributes: {
-            agents: [{
-                    id,
-                    name,
-                    authOwner: "agent",
-                    adapter: transport === "acp"
-                        ? { kind: "acp", command, ...(adapterArgs.length ? { args: adapterArgs } : {}) }
-                        : { kind: "process", command, ...(adapterArgs.length ? { args: adapterArgs } : {}), promptMode },
-                }],
+        name,
+        adapter: {
+            kind: "process",
+            command,
+            ...(adapterArgs.length ? { args: adapterArgs } : {}),
+            promptMode,
+            ...(parser ? { structured: { args: adapterArgs, parser } } : {}),
+            ...(resumeArgs ? { resume: { args: parseArgs(resumeArgs) } } : {}),
         },
     };
 }
@@ -94,64 +106,80 @@ async function main() {
     const dataDir = path.resolve(option(args, "--data-dir") ?? defaultDataDir());
     if (!command || command === "help" || args.includes("--help") || args.includes("-h")) {
         console.log(`Usage:
-  bivy agent add <id> --command <command> [--transport acp|process] [--args '["..."]']
+  bivy agent add <id> --command <command> [--args '["..."]'] [--name <name>] [--force]
+      ACP agent (default):  --transport acp
+      Any other CLI:        --transport process [--prompt-mode stdin|argv]
+                            [--parser <id>] [--resume-args '["...","{id}"]']
   bivy agent list [--json]
-  bivy agent remove <integration-id>
+  bivy agent remove <id>
 
-Adds an existing user-owned agent through the same declarative package contract used by every external integration.`);
+Agents are saved under agents: in <data-dir>/config.yaml and appear in the
+picker right away. Edit that file directly for every adapter option.`);
         return;
     }
     try {
         if (command === "add") {
-            const manifest = localManifest(args);
-            const existingPackage = listInstalledPlugins(dataDir).some((plugin) => plugin.id === manifest.metadata.id);
-            if (!existingPackage) {
+            const id = agentId(args);
+            const spec = agentConfig(args, id);
+            const config = nodeConfig(dataDir);
+            const replaced = Boolean(config.agents?.[id]);
+            if (replaced && !args.includes("--force"))
+                throw new Error(`Agent ${id} is already configured; pass --force to replace it`);
+            if (!replaced) {
                 const runtimeModule = await import("./runtime/index.js");
-                const retained = runtimeModule.canonicalAgentId(manifest.contributes.agents[0].id);
+                const retained = runtimeModule.canonicalAgentId(id);
                 if (retained)
-                    throw new Error(`Agent id ${manifest.contributes.agents[0].id} conflicts with retained integration ${retained}; choose a unique id`);
-            }
-            const temp = fs.mkdtempSync(path.join(os.tmpdir(), "bivy-agent-add-"));
-            const file = path.join(temp, "bivy.plugin.yaml");
-            try {
-                fs.writeFileSync(file, stringifyYaml(manifest), { mode: 0o600 });
-                const result = installPlugin(file, { dataDir, force: args.includes("--force"), bivyVersion: currentBivyVersion() });
-                const body = { ok: true, id: manifest.metadata.id, path: result.path, replaced: result.replaced, restartRequired: true };
-                if (json)
-                    console.log(JSON.stringify(body, null, 2));
-                else {
-                    console.log(`${result.replaced ? "Updated" : "Added"} agent integration ${manifest.metadata.name} (${manifest.metadata.id}).`);
-                    console.log("Restart Bivy to activate it: bivy restart");
-                }
-            }
-            finally {
-                fs.rmSync(temp, { recursive: true, force: true });
+                    throw new Error(`Agent id ${id} conflicts with ${retained}; choose a unique id`);
             }
+            writeNodeConfig(dataDir, { ...config, agents: { ...config.agents, [id]: spec } });
+            const body = { ok: true, id, path: nodeConfigPath(dataDir), replaced };
+            if (json)
+                console.log(JSON.stringify(body, null, 2));
+            else
+                console.log(`${replaced ? "Updated" : "Added"} ${"name" in spec ? spec.name : id} (${id}). It is in the agent picker now.`);
             return;
         }
         if (command === "list" || command === "ls") {
-            const rows = listInstalledPlugins(dataDir).flatMap((plugin) => plugin.manifest?.contributes.agents.map((agent) => ({
+            const configured = Object.entries(readNodeConfig(dataDir)?.agents ?? {}).map(([id, spec]) => ({
+                id,
+                name: "adapter" in spec ? spec.name ?? id : spec.label ?? id,
+                source: "config",
+                transport: "adapter" in spec ? spec.adapter.kind : `extends ${spec.extends}`,
+                command: "adapter" in spec ? spec.adapter.command : spec.command ?? spec.extends,
+            }));
+            const packaged = listInstalledPlugins(dataDir).flatMap((plugin) => plugin.manifest?.contributes.agents.map((agent) => ({
                 id: agent.id,
                 name: agent.name,
-                package: plugin.id,
-                version: plugin.manifest.metadata.version,
+                source: `${plugin.id}@${plugin.manifest.metadata.version}`,
                 transport: agent.adapter.kind,
                 command: agent.adapter.command,
-                status: plugin.errors.length ? "invalid" : "installed",
+                ...(plugin.errors.length ? { status: "invalid" } : {}),
             })) ?? []);
+            const rows = [...configured, ...packaged];
             if (json)
                 console.log(JSON.stringify({ ok: true, agents: rows }, null, 2));
             else if (!rows.length)
-                console.log("No installed agent integration packages.");
+                console.log("No agents added on this machine. Add one with: bivy agent add <id> --command <command>");
             else
                 for (const row of rows)
-                    console.log(`${row.id}\t${row.transport}\t${row.command}\t${row.package}@${row.version}`);
+                    console.log(`${row.id}\t${row.transport}\t${row.command}\t${row.source}`);
             return;
         }
         if (command === "remove" || command === "rm") {
             const id = positional(args)[1];
             if (!id)
-                fail("Usage: bivy agent remove <integration-id>", json);
+                fail("Usage: bivy agent remove <id>", json);
+            const config = readNodeConfig(dataDir);
+            if (config?.agents?.[id]) {
+                const { [id]: _removed, ...agents } = config.agents;
+                writeNodeConfig(dataDir, { ...config, agents });
+                if (json)
+                    console.log(JSON.stringify({ ok: true, id, removed: true }));
+                else
+                    console.log(`Removed ${id}.`);
+                return;
+            }
+            // Agents added before config.yaml held them were single-agent plugin packages.
             const installed = listInstalledPlugins(dataDir);
             const direct = installed.find((plugin) => plugin.id === id);
             const matches = direct ? [direct] : installed.filter((plugin) => plugin.manifest?.contributes.agents.some((agent) => agent.id === id));
@@ -162,7 +190,7 @@ Adds an existing user-owned agent through the same declarative package contract
             if (json)
                 console.log(JSON.stringify({ ok: true, id, packageId, removed }));
             else
-                console.log(removed ? `Removed ${id} (${packageId}). Restart Bivy to deactivate it.` : `Agent integration ${id} is not installed.`);
+                console.log(removed ? `Removed ${id} (${packageId}).` : `Agent ${id} is not configured.`);
             return;
         }
         fail(`Unknown agent command: ${command}`, json);

package/dist/agents/claude-code/runtime.js

@@ -691,6 +691,8 @@ class ClaudeSession {
     messages = [];
     streaming = false;
     name;
+    /** Set by the runtime so a disposed session leaves its registry. */
+    onDispose;
     models = [];
     currentModel;
     desiredModel;
@@ -1390,6 +1392,7 @@ class ClaudeSession {
             }
         }
         this.emitter.removeAllListeners();
+        this.onDispose?.();
     }
     async getModels() {
         // Re-query the live agent so the picker reflects the current lineup instead
@@ -1515,6 +1518,16 @@ export class ClaudeCodeRuntime {
     constructor(options = {}) {
         this.options = options;
     }
+    /** Each session holds its whole transcript, so it stays registered only
+     *  while open; a closed one would otherwise be kept for the daemon's lifetime. */
+    track(session) {
+        this.sessions.push(session);
+        session.onDispose = () => {
+            const i = this.sessions.indexOf(session);
+            if (i >= 0)
+                this.sessions.splice(i, 1);
+        };
+    }
     /** Claude Code runs Anthropic models; the authoritative list comes from the
      *  live query per session, so the session-less catalog is the known lineup. */
     listCatalog() {
@@ -1522,12 +1535,12 @@ export class ClaudeCodeRuntime {
     }
     async createSession(options) {
         const session = new ClaudeSession({ ...(await withSessionCredentials(this.options, options.credentialLabels)), instructions: options.instructions?.text }, options.workspace, options.toolInterceptor, options.toolProvider);
-        this.sessions.push(session);
+        this.track(session);
         return { session };
     }
     async openSession(options) {
         const session = new ClaudeSession({ ...(await withSessionCredentials(this.options, options.credentialLabels)), instructions: options.instructions?.text }, options.workspace, options.toolInterceptor, options.toolProvider, options.sessionFile);
-        this.sessions.push(session);
+        this.track(session);
         return {
             session,
             warning: "Resumed Claude Code session history is replayed by the agent on the next turn; prior messages are not preloaded.",
@@ -1732,15 +1745,11 @@ export class ClaudeCodeRuntime {
         // Drop (and tear down) any in-memory handle so the fallback branch of
         // listSessions (used when no sessionsDir is set) can't re-advertise it, and a
         // still-live child doesn't outlive the delete.
-        for (let i = this.sessions.length - 1; i >= 0; i--) {
-            const s = this.sessions[i];
-            if (s.id === sessionId || (sessionFile && s.sessionFile === sessionFile)) {
-                try {
-                    s.dispose();
-                }
-                catch { /* already disposed by the caller's close */ }
-                this.sessions.splice(i, 1);
+        for (const s of this.sessions.filter((s) => s.id === sessionId || (sessionFile && s.sessionFile === sessionFile))) {
+            try {
+                s.dispose();
             }
+            catch { /* already disposed by the caller's close */ }
         }
         // Prefer the exact path the SDK reports (that's the file it would re-read on
         // the next list); fall back to locating the transcript by id across Claude's

package/dist/node-config.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parseAgentAdapter } from "./plugin-sdk/manifest.js";
 export const NODE_CONFIG_FILE = "config.yaml";
 export const NODE_CONFIG_VERSION = 1;
 const ROOT_KEYS = ["version", "node", "defaults", "safety", "sessions", "github", "automation", "agents", "environment"];
@@ -170,6 +171,23 @@ export function validateNodeConfig(value) {
             errors.push(`${at} must be an object`);
             continue;
         }
+        if (spec.adapter !== undefined) {
+            unknownKeys(spec, ["name", "description", "hidden", "authOwner", "adapter"], at, errors);
+            const adapter = parseAgentAdapter(spec.adapter, `${at}.adapter`, errors);
+            const authOwner = spec.authOwner;
+            if (authOwner !== undefined && authOwner !== "agent" && authOwner !== "bivy" && authOwner !== "mixed")
+                errors.push(`${at}.authOwner must be agent, bivy, or mixed`);
+            const name = optionalString(spec.name, `${at}.name`, errors, 120);
+            const description = optionalString(spec.description, `${at}.description`, errors, 500);
+            const hidden = optionalBoolean(spec.hidden, `${at}.hidden`, errors);
+            if (adapter)
+                agents[id] = { name, description, hidden, authOwner, adapter };
+            continue;
+        }
+        if (spec.extends === undefined) {
+            errors.push(`${at} needs an adapter (any ACP or CLI command) or extends (a maintained agent id)`);
+            continue;
+        }
         unknownKeys(spec, ["extends", "label", "command", "args", "jsonArgs", "parserId", "promptMode", "hidden"], at, errors);
         const extend = optionalString(spec.extends, `${at}.extends`, errors, 80);
         const list = (value, key) => {

package/dist/plugin-cli.js

@@ -247,13 +247,13 @@ export async function main(argv = process.argv.slice(2)) {
             if (!input)
                 fail("Usage: bivy plugin install <path> [--force]", json);
             const result = installPlugin(input, { dataDir, force: args.includes("--force") });
-            const body = { ok: true, installed: result.manifest.metadata.id, version: result.manifest.metadata.version, path: result.path, replaced: result.replaced, restartRequired: true };
+            const body = { ok: true, installed: result.manifest.metadata.id, version: result.manifest.metadata.version, path: result.path, replaced: result.replaced };
             if (json)
                 outputJson(body);
             else {
                 console.log(`${result.replaced ? "Updated" : "Installed"} ${result.manifest.metadata.name} (${result.manifest.metadata.id}@${result.manifest.metadata.version}).`);
                 console.log(`Stored at ${result.path}`);
-                console.log("Restart Bivy to activate it: bivy restart");
+                console.log("It is in the agent picker now.");
             }
             return;
         }
@@ -300,12 +300,11 @@ export async function main(argv = process.argv.slice(2)) {
             const removed = removePlugin(id, dataDir);
             if (!removed)
                 fail(`Plugin ${id} is not installed`, json);
-            const body = { ok: true, removed: id, restartRequired: true };
+            const body = { ok: true, removed: id };
             if (json)
                 outputJson(body);
             else {
                 console.log(`Removed plugin ${id}.`);
-                console.log("Restart Bivy to unload it: bivy restart");
             }
             return;
         }

package/dist/plugin-sdk/manifest.js

@@ -179,6 +179,21 @@ function parseAcpAdapter(raw, at, errors) {
     const args = stringList(raw.args, `${at}.args`, errors);
     return command ? { kind: "acp", command, ...(args ? { args } : {}) } : undefined;
 }
+/** Validate one `adapter` block. Plugin manifests and node `config.yaml` agents
+ *  share it, so an agent is described the same way wherever it is declared. */
+export function parseAgentAdapter(value, at, errors) {
+    const raw = object(value);
+    if (!raw) {
+        errors.push(`${at} must be an object`);
+        return undefined;
+    }
+    if (raw.kind === "process")
+        return parseProcessAdapter(raw, at, errors);
+    if (raw.kind === "acp")
+        return parseAcpAdapter(raw, at, errors);
+    errors.push(`${at}.kind must be process or acp`);
+    return undefined;
+}
 function parseAgent(value, index, errors) {
     const at = `contributes.agents[${index}]`;
     const raw = object(value);
@@ -198,16 +213,7 @@ function parseAgent(value, index, errors) {
     if (authOwner !== undefined && authOwner !== "agent" && authOwner !== "bivy" && authOwner !== "mixed") {
         errors.push(`${at}.authOwner must be agent, bivy, or mixed`);
     }
-    const adapterRaw = object(raw.adapter);
-    let adapter;
-    if (!adapterRaw)
-        errors.push(`${at}.adapter must be an object`);
-    else if (adapterRaw.kind === "process")
-        adapter = parseProcessAdapter(adapterRaw, `${at}.adapter`, errors);
-    else if (adapterRaw.kind === "acp")
-        adapter = parseAcpAdapter(adapterRaw, `${at}.adapter`, errors);
-    else
-        errors.push(`${at}.adapter.kind must be process or acp`);
+    const adapter = parseAgentAdapter(raw.adapter, `${at}.adapter`, errors);
     if (!id || !name || !adapter)
         return undefined;
     return {
@@ -351,5 +357,7 @@ export function recommendedBivyRange(currentVersion) {
     const parsed = parseSemver(currentVersion);
     if (!parsed)
         throw new Error(`Cannot generate a compatibility range from invalid Bivy version ${currentVersion}`);
-    return `>=${parsed.major}.${parsed.minor}.${parsed.patch} <${parsed.major}.${parsed.minor + 1}.0`;
+    // The manifest contract is versioned by apiVersion, so a plugin keeps working
+    // across Bivy minor releases; only a major release may break it.
+    return `>=${parsed.major}.${parsed.minor}.${parsed.patch} <${parsed.major + 1}.0.0`;
 }

package/dist/runtime/cli-parsers.js

@@ -241,6 +241,7 @@ export function bivyProtocolParser() {
     // appended verbatim (a shim emits an explicit break when it wants one), so it
     // opts out of inferred segment boundaries.
     const acc = new TurnAccumulator({ provider: "bivy-protocol", protocol: "protocol" }, false);
+    let sessionRef;
     return {
         onLine(line) {
             const events = [];
@@ -255,9 +256,23 @@ export function bivyProtocolParser() {
                 return events; // ignore non-JSON noise (banners etc.)
             }
             const type = String(msg.type ?? "");
-            if (type === "message.delta") {
+            if (type === "session.started") {
+                // The adapter's own conversation id; `resume.args` gets it back as {id}.
+                if (typeof msg.sessionId === "string" && msg.sessionId.trim())
+                    sessionRef = msg.sessionId.trim();
+            }
+            else if (type === "message.delta") {
                 acc.appendText(String(msg.text ?? ""), events);
             }
+            else if (type === "message.reasoning") {
+                acc.appendReasoning(String(msg.text ?? ""), events);
+            }
+            else if (type === "usage") {
+                const tokens = extractTokenUsage(msg.tokens ?? msg);
+                const costUsd = typeof msg.costUsd === "number" ? { costUsd: msg.costUsd } : {};
+                if (tokens || costUsd.costUsd !== undefined)
+                    acc.addUsage({ ...tokens, ...costUsd });
+            }
             else if (type === "session.status") {
                 const status = String(msg.status ?? "");
                 if (status === "working")
@@ -288,6 +303,8 @@ export function bivyProtocolParser() {
             return events;
         },
         messages: () => acc.history(),
+        usage: () => acc.usageSnapshot,
+        sessionRef: () => sessionRef,
     };
 }
 /** Parser for Claude Code CLI `--output-format stream-json`. */