agent-accelerator 0.5.3 → 0.5.4

package/src/agent/workers.ts

@@ -0,0 +1,405 @@
+/**
+ * Persistent sub-agent workers. A worker is a plain `Agent` with its own instructions, tools and session: it keeps its
+ * conversation, can be messaged again until it is closed, and is saved under `<parent session>/workers/<id>/` (its own
+ * journal, tool logs and resume, plus `worker.json` with what the registry needs to rebuild it after a restart).
+ * `agent.workers` is the programmatic API; the `subagents` tool is a thin wrapper over the same functions.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Agent } from "./agent.ts";
+import type { AgentResponse, SubAgentExecutionMetadata } from "../types/response.ts";
+import type { Message } from "../types/message.ts";
+import { ConfigError, ValidationError } from "../types/errors.ts";
+import { writeFileDurable } from "../utils/durable.ts";
+import { sessionDirFor, loadSessionDir } from "../session/store.ts";
+import { telemetryBus } from "../telemetry.ts";
+import { hashSessionPart, newRunId, newTurnId, nowMs } from "../utils/session.ts";
+import { buildDynamicWorkerConfig, grantWorkerTools, sanitizeToolName } from "./worker.ts";
+import { createFixedChildSessionId, openWorkerTrace, reserveSpawn, workerMetadata, type WorkerRunResult } from "./delegation.ts";
+import { finishedTurns, historyUpTo, type Turn } from "./turns.ts";
+import { modelName, readUsage, type UsageNode } from "../session/usage.ts";
+
+/** What `spawn` needs to start a worker. */
+export interface WorkerSpec {
+  /** Short label; the worker's id is this name plus a short suffix. */
+  name: string;
+  role?: string;
+  /** The worker's own system prompt (the parent's is never copied). */
+  instructions?: string;
+  /** The first assignment. */
+  task: string;
+  /** Names from the developer's `dynamicSubagents.tools` pool to grant this worker. Unknown names throw. */
+  tools?: string[];
+  /** `"none"` (default) or a number N: start from a copy of the parent's first N finished turns (see `workers.turns()`). */
+  history?: "none" | number;
+}
+
+/** One worker as `list()` shows it. */
+export interface WorkerInfo {
+  id: string;
+  name: string;
+  role?: string;
+  tools: string[];
+  /** A call is running on it right now. */
+  busy: boolean;
+}
+
+/** The answer to one `spawn` or `message`. A failed call carries `error` and a text that says so; it never throws. */
+export interface WorkerReply {
+  id: string;
+  text: string;
+  error?: string;
+  metadata: SubAgentExecutionMetadata;
+}
+
+/** Options of one `spawn`/`message` call. */
+export interface WorkerCallOptions {
+  /** Aborts the worker's run. */
+  signal?: AbortSignal;
+  /** The calling tool call's id: makes the call exactly-once across a crash and replay (the `subagents` tool passes it). */
+  callId?: string;
+  /** Receives the worker's live text and thinking deltas. */
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+}
+
+// Saved in `worker.json`: everything needed to rebuild a worker after a restart.
+interface WorkerMeta {
+  id: string;
+  name: string;
+  role?: string;
+  instructions: string;
+  tools: string[];
+  sessionId: string;
+  status: "open" | "closed";
+  createdAt: number;
+  closedAt?: number;
+  /** The last call delivered: its key, a hash of its text, and how many runs the worker had then. Detects a replayed call. */
+  last?: { key: string; text: string; marks: number };
+}
+
+interface Entry {
+  meta: WorkerMeta;
+  /** The worker's session folder (unset when the parent does not persist). */
+  dir?: string;
+  agent?: Agent;
+  /** Its spending, kept when it is closed (so a worker that was never saved to disk still shows in the report). */
+  kept?: { model: string; totals: ReturnType<typeof readUsage>; workers: UsageNode[] };
+  busy: boolean;
+}
+
+const META_FILE = "worker.json";
+
+// Fails with a one-line message when a required text field is missing; in: spawn/message input, out: the caller's ValidationError.
+function requireText(field: string, value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) throw new ValidationError(`${field}: required, a non-empty string.`);
+  return value.trim();
+}
+
+// Joins the text parts of the last assistant message (the reply a worker already gave); in: a worker's history, out: a replayed call's saved answer.
+function lastAssistantText(messages: Message[]): string | undefined {
+  const last = messages[messages.length - 1];
+  if (!last || last.role !== "assistant") return undefined;
+  if (typeof last.content === "string") return last.content;
+  return last.content.map((p) => (p.type === "text" ? p.text : "")).join("");
+}
+
+// Reads a worker that is not in memory from its folder: its saved spending, model, and the workers saved inside it; in: a worker's session folder, out: usageNodes.
+function readSavedWorker(dir: string | undefined): { model: string; totals: ReturnType<typeof readUsage>; workers: UsageNode[] } {
+  if (!dir) return { model: "unknown", totals: readUsage(undefined), workers: [] };
+  let session: ReturnType<typeof loadSessionDir>;
+  try {
+    session = loadSessionDir(dir);
+  } catch {
+    session = null; // a session over the load limits: its spending is unknown here
+  }
+  const workers: UsageNode[] = [];
+  const root = path.join(dir, "workers");
+  let names: fs.Dirent[] = [];
+  try {
+    names = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    // no workers saved inside this one
+  }
+  for (const d of names) {
+    if (!d.isDirectory()) continue;
+    try {
+      const meta = JSON.parse(fs.readFileSync(path.join(root, d.name, META_FILE), "utf8")) as WorkerMeta;
+      const inner = readSavedWorker(path.join(root, d.name));
+      workers.push({ id: meta.id, name: meta.name, ...(meta.role ? { role: meta.role } : {}), model: inner.model, status: meta.status, totals: inner.totals, workers: inner.workers });
+    } catch {
+      // a damaged worker.json is skipped, as in load()
+    }
+  }
+  return { model: session?.session.model || "unknown", totals: readUsage(session?.session.usage), workers };
+}
+
+/** The workers of one parent `Agent` (`agent.workers`). */
+export class WorkerRegistry {
+  private readonly entries = new Map<string, Entry>();
+
+  constructor(private readonly parent: Agent) {
+    this.load();
+  }
+
+  // Where this parent's workers live on disk, or undefined when it does not persist to a folder; in: the parent's persist config, out: load, create.
+  private root(): string | undefined {
+    const dir = this.parent.persistConfig?.dir;
+    if (!dir || this.parent.stateless) return undefined;
+    try {
+      return path.join(sessionDirFor(dir, this.parent.sessionId), "workers");
+    } catch {
+      return undefined; // not a usable session id for a folder name
+    }
+  }
+
+  // Reads every saved `worker.json` under the parent's session folder; a damaged one is reported on the bus and skipped; in: the constructor, out: this.entries.
+  private load(): void {
+    const root = this.root();
+    if (!root) return;
+    let names: fs.Dirent[];
+    try {
+      names = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      return; // nothing saved yet
+    }
+    for (const d of names) {
+      if (!d.isDirectory()) continue;
+      const dir = path.join(root, d.name);
+      try {
+        const meta = JSON.parse(fs.readFileSync(path.join(dir, META_FILE), "utf8")) as WorkerMeta;
+        if (typeof meta.id !== "string" || typeof meta.sessionId !== "string" || !Array.isArray(meta.tools)) throw new Error("missing fields");
+        this.entries.set(meta.id, { meta, dir, busy: false });
+      } catch (err) {
+        telemetryBus.emitWarning("worker.invalid", `[Agent Accelerator] ${path.join(dir, META_FILE)} is not a valid worker and is skipped: ${err instanceof Error ? err.message : String(err)}`, { dir });
+      }
+    }
+  }
+
+  // Saves a worker's `worker.json` durably (a no-op when the parent does not persist); in: spawn, deliver, close, out: the worker folder.
+  private save(entry: Entry): void {
+    if (entry.dir) writeFileDurable(path.join(entry.dir, META_FILE), JSON.stringify(entry.meta, null, 2) + "\n");
+  }
+
+  // True when this call is the one that last reached the worker (same call key and text): a replay after a crash; in: spawn and deliver, out: exactly-once handling.
+  private isReplay(entry: Entry, key: string | undefined, text: string): boolean {
+    return !!key && entry.meta.last?.key === key && entry.meta.last.text === hashSessionPart(text);
+  }
+
+  // The key that identifies one tool call across a restart: the parent run plus the call id; in: WorkerCallOptions.callId, out: replay detection.
+  private callKey(callId: string | undefined): string | undefined {
+    return callId ? `${this.parent.runMarks[this.parent.runMarks.length - 1]?.id ?? ""}:${callId}` : undefined;
+  }
+
+  /**
+   * Starts a worker on `spec.task` and waits for its first reply. With `opts.callId` a replay of the same call (after a
+   * crash) finds the worker it already started instead of creating a second one.
+   */
+  async spawn(spec: WorkerSpec, opts: WorkerCallOptions = {}): Promise<WorkerReply> {
+    const name = requireText("name", spec?.name);
+    const task = requireText("task", spec?.task);
+    const key = this.callKey(opts.callId);
+    const slug = sanitizeToolName(name).slice(0, 24).replace(/-+$/, "") || "worker";
+    let id = "";
+    let entry: Entry | undefined;
+    for (let n = 0; ; n++) {
+      id = `${slug}-${hashSessionPart(n === 0 ? (key ?? globalThis.crypto.randomUUID()) : `${key ?? globalThis.crypto.randomUUID()}#${n}`)}`;
+      entry = this.entries.get(id);
+      if (!entry || this.isReplay(entry, key, task)) break;
+    }
+    entry ??= await this.create(id, name, task, key, spec);
+    return this.deliver(entry, task, key, opts);
+  }
+
+  /** Sends `text` to an open worker and waits for its reply; the worker remembers the conversation. */
+  async message(id: string, text: string, opts: WorkerCallOptions = {}): Promise<WorkerReply> {
+    const entry = this.open(id);
+    return this.deliver(entry, requireText("text", text), this.callKey(opts.callId), opts);
+  }
+
+  /** Closes a worker: it can no longer be messaged, its session stays on disk (and in `usageReport`). */
+  close(id: string): WorkerInfo {
+    const entry = this.open(id);
+    if (entry.busy) throw new ValidationError(`Worker "${id}" is busy with a call; wait for it to finish before closing it.`);
+    entry.meta.status = "closed";
+    entry.meta.closedAt = Date.now();
+    this.save(entry);
+    if (entry.agent) entry.kept = { model: modelName(entry.agent.modelStringOrSpec), totals: readUsage(entry.agent.usageTotals), workers: entry.agent.workers.usageNodes() };
+    entry.agent?.disposeSession(entry.meta.sessionId); // frees its provider chain; never reset(): that could rewrite the saved history
+    entry.agent = undefined;
+    return this.info(entry);
+  }
+
+  /** The open workers. */
+  list(): WorkerInfo[] {
+    return [...this.entries.values()].filter((e) => e.meta.status === "open").map((e) => this.info(e));
+  }
+
+  /** The parent's finished turns, the numbers `spawn` accepts for `history`. */
+  turns(): Turn[] {
+    return finishedTurns(this.parent.context.messages, this.parent.runMarks);
+  }
+
+  /** Every worker (open and closed) as a usage tree: live ones from memory, the rest from their saved sessions, nested workers included. */
+  usageNodes(): UsageNode[] {
+    return [...this.entries.values()].map((entry) => {
+      const { id, name, role, status } = entry.meta;
+      const base = { id, name, ...(role ? { role } : {}), status };
+      if (entry.agent) return { ...base, model: modelName(entry.agent.modelStringOrSpec), totals: entry.agent.usageTotals, workers: entry.agent.workers.usageNodes() };
+      return { ...base, ...(entry.kept ?? readSavedWorker(entry.dir)) };
+    });
+  }
+
+  // The open worker with this id, or a ValidationError that says what to do; in: message and close, out: the entry.
+  private open(id: string): Entry {
+    const entry = this.entries.get(id);
+    if (!entry) throw new ValidationError(`No worker with id "${id}". Use list to see the open workers.`);
+    if (entry.meta.status === "closed") throw new ValidationError(`Worker "${id}" is closed. Spawn a new worker instead.`);
+    return entry;
+  }
+
+  // The public view of one worker; in: an entry, out: list and close.
+  private info(entry: Entry): WorkerInfo {
+    const { id, name, role, tools } = entry.meta;
+    return { id, name, ...(role ? { role } : {}), tools: [...tools], busy: entry.busy };
+  }
+
+  // Checks a new worker's request, builds its Agent (seeded with the copied history) and saves `worker.json`; in: spawn, out: a new open entry.
+  private async create(id: string, name: string, task: string, key: string | undefined, spec: WorkerSpec): Promise<Entry> {
+    const parent = this.parent;
+    if (!parent.subagentModel) {
+      throw new ConfigError(
+        "[Agent Accelerator] Cannot spawn workers: no sub-agent model is configured. Set dynamicSubagents.model in Agent config or set the SUB_AGENT_MODEL environment variable."
+      );
+    }
+    const maxOpen = parent.dynamicSubagents?.maxSpawn ?? 4;
+    if (this.list().length >= maxOpen) {
+      throw new ValidationError(`Too many open workers (${maxOpen} is the limit). Close one first; open workers: ${this.list().map((w) => w.id).join(", ")}.`);
+    }
+    const pool = parent.dynamicSubagents?.tools ?? {};
+    const requested = spec.tools ?? [];
+    const unknown = requested.filter((n) => Object.keys(grantWorkerTools(pool, [n])).length === 0);
+    if (unknown.length > 0) {
+      const names = Object.keys(pool);
+      throw new ValidationError(
+        `tools: unknown worker tool(s) ${unknown.map((n) => `"${n}"`).join(", ")}; ` + (names.length > 0 ? `the pool is [${names.join(", ")}].` : "no worker tools are available, omit tools.")
+      );
+    }
+    const history = spec.history ?? "none";
+    const messages = history === "none" ? [] : historyUpTo(parent.context.messages, parent.runMarks, history);
+    reserveSpawn(parent, 1);
+
+    const sessionId = createFixedChildSessionId(parent.sessionId, id);
+    const root = this.root();
+    const meta: WorkerMeta = {
+      id,
+      name,
+      ...(spec.role?.trim() ? { role: spec.role.trim() } : {}),
+      instructions: spec.instructions?.trim() ?? "",
+      tools: Object.keys(grantWorkerTools(pool, requested)),
+      sessionId,
+      status: "open",
+      createdAt: Date.now(),
+      ...(key ? { last: { key, text: hashSessionPart(task), marks: 0 } } : {}),
+    };
+    const entry: Entry = { meta, ...(root ? { dir: path.join(root, sessionId) } : {}), busy: false };
+    // Registered before the first await: parallel spawns of one model turn must see each other for the open-worker limit.
+    this.entries.set(id, entry);
+    try {
+      entry.agent = await this.build(entry);
+      if (messages.length > 0) entry.agent.context.messages = messages;
+      this.save(entry);
+    } catch (err) {
+      this.entries.delete(id);
+      throw err;
+    }
+    return entry;
+  }
+
+  // Builds a worker's Agent from its saved meta; a worker reloaded after a restart gets its saved history back; in: create and deliver, out: the worker Agent.
+  private async build(entry: Entry): Promise<Agent> {
+    const { Agent: AgentClass } = await import("./agent.ts");
+    const { meta } = entry;
+    const root = this.root();
+    const agent = new AgentClass(
+      buildDynamicWorkerConfig(this.parent, {
+        name: meta.name,
+        role: meta.role,
+        instructions: meta.instructions,
+        sessionId: meta.sessionId,
+        tools: grantWorkerTools(this.parent.dynamicSubagents?.tools ?? {}, meta.tools),
+        persistent: { dir: root },
+      })
+    );
+    (agent as unknown as { parentSessionId?: string }).parentSessionId = this.parent.sessionId;
+    // A cut-off run was already loaded by the constructor; otherwise bring back what the worker said so far.
+    const saved = entry.dir && agent.context.messages.length === 0 ? loadSessionDir(entry.dir)?.session : undefined;
+    if (saved) agent.importSession(saved);
+    return agent;
+  }
+
+  // Sends one text to a worker and turns what happens into a reply: runs it, or after a crash continues the cut-off run or returns the answer it had already given; in: spawn and message, out: a WorkerReply.
+  private async deliver(entry: Entry, text: string, key: string | undefined, opts: WorkerCallOptions): Promise<WorkerReply> {
+    if (entry.busy) throw new ValidationError(`Worker "${entry.meta.id}" is busy with another call; wait for it, or message another worker.`);
+    entry.busy = true;
+    const { meta } = entry;
+    const startTime = nowMs();
+    try {
+      const agent = (entry.agent ??= await this.build(entry));
+      const live = openWorkerTrace({
+        name: meta.name,
+        sessionId: meta.sessionId,
+        parentSessionId: this.parent.sessionId,
+        task: text,
+        role: meta.role,
+        parent: this.parent,
+        emit: opts.onSubagentEvent,
+      });
+      const lineage = { name: meta.name, displayId: live.displayId, sessionId: meta.sessionId, parentSessionId: this.parent.sessionId, role: meta.role, task: text, runId: newRunId(), turnId: newTurnId() };
+      const replayed = this.isReplay(entry, key, text) && agent.runMarks.length > meta.last!.marks;
+      if (!replayed) {
+        if (key) meta.last = { key, text: hashSessionPart(text), marks: agent.runMarks.length };
+        else delete meta.last;
+        this.save(entry);
+      }
+      const onAbort = (): void => agent.interrupt(opts.signal?.reason);
+      try {
+        if (opts.signal?.aborted) throw new Error("aborted before the worker started");
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        let result: WorkerRunResult | undefined;
+        if (replayed && agent.interrupted().length === 0) {
+          // The crash came after the worker answered: that answer is the reply, nothing runs again.
+          const saved = lastAssistantText(agent.context.messages);
+          if (saved !== undefined) result = { text: saved };
+        }
+        if (!result) {
+          let response: AgentResponse | undefined;
+          if (replayed) {
+            response = await agent.resume();
+          } else {
+            const stream = agent.stream(text, { onTurn: live.onWorkerTurn });
+            const detach = live.attachToStream(stream as unknown as Parameters<typeof live.attachToStream>[0]);
+            try {
+              response = await stream.result();
+            } finally {
+              detach();
+            }
+          }
+          if (!response) throw new Error("the worker had nothing to resume");
+          result = response;
+        }
+        const reply = result.text.trim() ? result.text : `(the worker produced no text${result.finishReason ? `; finish reason: ${result.finishReason}` : ""})`;
+        live.finish(result);
+        return { id: meta.id, text: reply, metadata: workerMetadata({ ...lineage, durationMs: Math.max(0, nowMs() - startTime), result, steps: live.steps() }) };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        live.fail(message);
+        const errorText = `Error in worker ${meta.id}: ${message}`;
+        return { id: meta.id, text: errorText, error: message, metadata: workerMetadata({ ...lineage, durationMs: Math.max(0, nowMs() - startTime), error: message, errorText, steps: live.steps() }) };
+      } finally {
+        opts.signal?.removeEventListener("abort", onAbort);
+      }
+    } finally {
+      entry.busy = false;
+    }
+  }
+}

package/src/index.ts

@@ -61,7 +61,6 @@ export { assertPathAllowed, enforceFileAccess, fetchRemoteBytes, isPrivateAddres
 export {
   buildAgentTools,
   agentToTool,
-  createSubagentSpawnTool,
   createChildSessionId,
   createFixedChildSessionId,
   isSessionDescendant,
@@ -85,7 +84,8 @@ export {
   MAX_SUBAGENT_STEPS_PER_TRACE,
   SUBAGENT_SUBSCRIBE_TTL_MS,
 } from "./agent/delegation.ts";
-export type { DynamicSubagentTask, AgentAsToolTarget, SubAgentTrace, StreamingLoopHandle } from "./agent/delegation.ts";
+export type { AgentAsToolTarget, SubAgentTrace, StreamingLoopHandle } from "./agent/delegation.ts";
+export type { WorkerRegistry, WorkerSpec, WorkerInfo, WorkerReply, WorkerCallOptions } from "./agent/workers.ts";
 
 // Scheduled actions: dynamic sub-agents that run later and save their answer to a file
 export {
@@ -317,6 +317,7 @@ export {
   formatSessionBanner,
   emptyTotals,
 } from "./session/store.ts";
+export type { UsageReport, UsageLine, UsageTotals, AgentUsage, WorkerUsage, CostSource } from "./session/usage.ts";
 export type { SessionLimits, SessionPayloadStatus, PersistedAgentSession, SessionTotals, SessionAgentLike, LoadedSessionDir, PersistedSubAgentTrace, SessionRunMark, SessionRunEnd, SessionPending, SessionPendingPrompt, SessionToolRecord } from "./session/store.ts";
 
 // Utilities

package/src/session/journal.ts

@@ -51,6 +51,8 @@ export class SessionJournal {
   private lastRun: unknown;
   /** JSON of the last journaled waiting prompts. */
   private pending = EMPTY_PENDING;
+  /** JSON of the last journaled spending totals. */
+  private usage = "";
   /** Run ids whose ending is on disk. */
   private readonly endsOnDisk = new Set<string>();
   /** How many of the current run's finished tool results are on disk, and the last one. */
@@ -90,6 +92,8 @@ export class SessionJournal {
     if (meta !== this.meta) records.push(`{"t":"meta","m":${meta}}`);
     const pending = this.pendingOf(agent);
     if (pending !== this.pending) records.push(`{"t":"pending","p":${pending}}`);
+    const usage = this.usageOf(agent);
+    if (usage !== this.usage) records.push(`{"t":"usage","u":${usage}}`);
     if (records.length === 0) return;
     const text = records.join("\n") + "\n";
     try {
@@ -110,6 +114,7 @@ export class SessionJournal {
     this.runCount = runs.length;
     this.lastRun = runs[runs.length - 1];
     this.pending = pending;
+    this.usage = usage;
     this.toolCount = tools.length;
     this.lastTool = tools[tools.length - 1];
     for (const mark of runs) if (mark.end) this.endsOnDisk.add(mark.id);
@@ -134,6 +139,7 @@ export class SessionJournal {
     writeFileDurable(path.join(this.dir, JOURNAL_FILE), header, { backup: false });
     this.epoch = epoch;
     this.pending = pending;
+    this.usage = this.usageOf(agent); // the snapshot holds it
     this.runs(agent);
     this.count = messages.length;
     this.last = messages[messages.length - 1];
@@ -167,9 +173,14 @@ export class SessionJournal {
     return JSON.stringify({ steer: slim(waiting.steer), queue: slim(waiting.queue) } satisfies SessionPending);
   }
 
+  // JSON of the agent's spending totals (`null` before its first model call); in: the live agent, out: change detection + the `usage` record.
+  private usageOf(agent: SessionAgentLike): string {
+    return agent.usageTotals && agent.usageTotals.turns > 0 ? JSON.stringify(agent.usageTotals) : "null";
+  }
+
   // JSON of everything in the snapshot that is not a message, identity or totals; in: the live agent, out: change detection + the `meta` record.
   private metaOf(agent: SessionAgentLike): string {
-    const { version: _v, sessionId: _s, messages: _m, totals: _t, runs: _r, ...rest } = buildSessionData(
+    const { version: _v, sessionId: _s, messages: _m, totals: _t, runs: _r, usage: _u, ...rest } = buildSessionData(
       { ...agent, context: { ...agent.context, messages: [] } },
       null
     );

package/src/session/store.ts

@@ -33,6 +33,7 @@ import type { SubAgentStep } from "../types/response.ts";
 import { SessionLoadError } from "../types/errors.ts";
 import { createSessionId } from "../utils/session.ts";
 import { writeFileDurable, readWithBackup } from "../utils/durable.ts";
+import type { UsageTotals } from "./usage.ts";
 
 /** Cumulative per-session token + cost totals (JSON-safe). */
 export interface SessionTotals {
@@ -118,6 +119,8 @@ export interface PersistedAgentSession {
   epoch?: string;
   /** Where each run began, oldest first. */
   runs?: SessionRunMark[];
+  /** What this agent spent on its own model calls (see `usage.ts`); the journal keeps it current with `usage` records. */
+  usage?: UsageTotals;
   /** Read from the journal only (never in `session.json`): prompts that were still waiting. */
   pending?: SessionPending;
   /** Read from the journal only: results of tool calls finished in the current run (used to resume without repeating them). */
@@ -335,6 +338,8 @@ export interface SessionAgentLike {
   pendingPrompts?: () => SessionPending;
   /** Tool calls finished in the current run (cleared when the next run starts). */
   toolRecords?: SessionToolRecord[];
+  /** What this agent spent on its own model calls. */
+  usageTotals?: UsageTotals;
   context: { systemPrompt?: string; messages: Message[] };
 }
 
@@ -482,6 +487,7 @@ export function buildSessionData(agent: SessionAgentLike, telemetry?: SessionTel
     ...(parentSessionId ? { parentSessionId } : {}),
     ...(subagents ? { subagents } : {}),
     ...(agent.runMarks && agent.runMarks.length > 0 ? { runs: agent.runMarks.map((r) => ({ ...r })) } : {}),
+    ...(agent.usageTotals && agent.usageTotals.turns > 0 ? { usage: JSON.parse(JSON.stringify(agent.usageTotals)) as UsageTotals } : {}),
   };
 }
 
@@ -671,6 +677,7 @@ function parseSession(raw: string, limits?: SessionLimits): PersistedAgentSessio
       subagents: obj.subagents,
       ...(typeof obj.epoch === "string" ? { epoch: obj.epoch } : {}),
       ...(Array.isArray(obj.runs) ? { runs: obj.runs as SessionRunMark[] } : {}),
+      ...(obj.usage && typeof obj.usage === "object" ? { usage: obj.usage as UsageTotals } : {}),
     };
   } catch {
     return null;
@@ -985,7 +992,7 @@ export const JOURNAL_FILE = "journal.ndjson";
 // Snapshot fields a `meta` journal record replaces (everything except messages, identity and totals).
 const JOURNAL_META_KEYS = ["model", "subagentModel", "thinkingLevel", "cache", "systemPrompt", "parentSessionId", "subagents"] as const;
 
-// Applies a journal to its snapshot: records of the snapshot's own epoch only, `msg` by index (already-present ones skipped), `run` adds a run boundary, `end` closes one, `tool` keeps a finished tool result, `pending` replaces the waiting prompts, `meta` replaces config fields, unknown record types ignored; a torn last line is dropped, damage earlier stops the replay with a bus warning; in: the parsed snapshot + journal text, out: loadSessionDir.
+// Applies a journal to its snapshot: records of the snapshot's own epoch only, `msg` by index (already-present ones skipped), `run` adds a run boundary, `end` closes one, `usage` replaces the agent's spending totals, `tool` keeps a finished tool result, `pending` replaces the waiting prompts, `meta` replaces config fields, unknown record types ignored; a torn last line is dropped, damage earlier stops the replay with a bus warning; in: the parsed snapshot + journal text, out: loadSessionDir.
 function replayJournal(snapshot: PersistedAgentSession, text: string, file: string): PersistedAgentSession {
   if (!snapshot.epoch) return snapshot;
   const lines = text.split("\n");
@@ -997,7 +1004,7 @@ function replayJournal(snapshot: PersistedAgentSession, text: string, file: stri
   for (let k = 0; k < lines.length; k++) {
     const line = lines[k]!.trim();
     if (!line) continue;
-    let rec: { t?: unknown; e?: unknown; i?: unknown; m?: unknown; p?: unknown; id?: unknown; at?: unknown; status?: unknown; call?: unknown; name?: unknown; result?: unknown; isError?: unknown; stopped?: unknown };
+    let rec: { t?: unknown; e?: unknown; i?: unknown; m?: unknown; p?: unknown; id?: unknown; at?: unknown; u?: unknown; status?: unknown; call?: unknown; name?: unknown; result?: unknown; isError?: unknown; stopped?: unknown };
     try {
       rec = JSON.parse(line);
     } catch {
@@ -1023,6 +1030,8 @@ function replayJournal(snapshot: PersistedAgentSession, text: string, file: stri
       if (mark) session.runs = session.runs!.map((r) => (r === mark ? { ...r, end: rec.status as SessionRunEnd } : r));
     } else if (rec.t === "tool" && typeof rec.call === "string" && typeof rec.name === "string") {
       session.tools = [...(session.tools ?? []).filter((x) => x.id !== rec.call), { id: rec.call, name: rec.name, result: rec.result, ...(rec.isError ? { isError: true } : {}), ...(rec.stopped ? { stopped: true } : {}) }];
+    } else if (rec.t === "usage" && rec.u && typeof rec.u === "object") {
+      session.usage = rec.u as UsageTotals; // latest record wins
     } else if (rec.t === "pending" && rec.p && typeof rec.p === "object") {
       const p = rec.p as SessionPending; // latest record wins
       if (Array.isArray(p.steer) && Array.isArray(p.queue)) {
@@ -1328,15 +1337,16 @@ function toDollars(microUSD: number): number {
  * `cost.context_over_200k`, the over-200k tier prices apply; otherwise base
  * `pricing.*` (falling back to legacy `cost.*`) applies.
  */
+// Cache prices stay undefined when the catalog has none: priceUsage then bills those tokens at the input rate (never free).
 function resolveEffectivePricing(
   spec: ModelSpec | undefined,
   inputTokens: number
-): { input: number; output: number; cacheRead: number; cacheWrite: number; audio: number; tier: string } {
+): { input: number; output: number; cacheRead: number | undefined; cacheWrite: number | undefined; audio: number; tier: string } {
   const base = {
     input: spec?.pricing?.inputPerMillion ?? (spec?.cost?.input as number | undefined) ?? 0,
     output: spec?.pricing?.outputPerMillion ?? (spec?.cost?.output as number | undefined) ?? 0,
-    cacheRead: spec?.pricing?.cacheReadPerMillion ?? (spec?.cost?.cache_read as number | undefined) ?? 0,
-    cacheWrite: spec?.pricing?.cacheWritePerMillion ?? (spec?.cost?.cache_write as number | undefined) ?? 0,
+    cacheRead: spec?.pricing?.cacheReadPerMillion ?? (spec?.cost?.cache_read as number | undefined),
+    cacheWrite: spec?.pricing?.cacheWritePerMillion ?? (spec?.cost?.cache_write as number | undefined),
     audio:
       spec?.pricing?.inputAudioPerMillion ?? (spec?.cost as { input_audio?: number } | undefined)?.input_audio ?? 0,
   };
@@ -1388,8 +1398,9 @@ function resolveEffectivePricing(
  * - Audio tokens (`usage.audioTokens` / `usage.inputAudioTokens` when present)
  *   price at `pricing.inputAudioPerMillion` / `cost.input_audio` and fold into
  *   the total (separately itemized in `breakdown.audioMicroUSD`).
- * - `opts.serviceTier` (`flex` ~0.5x, `priority` ~1.5x, estimates) scales the
+ * - `opts.serviceTier` (`flex` 0.5x, `priority` 2x, estimates) scales the
  *   catalog total; provider-reported costs are never rescaled.
+ * - Cache reads and writes are subsets of the input tokens; a missing cache price bills at the input rate.
  */
 export function priceUsage(
   usage: TokenUsage,
@@ -1438,12 +1449,15 @@ export function priceUsage(
     return undefined;
   }
   const { multiplier, tier: serviceTier } = serviceTierMultiplier(opts?.serviceTier, opts?.modelId ?? spec?.id);
-  const nonCachedInput = Math.max(0, inputTokens - cachedTokens);
+  // Cache reads and writes are both a SUBSET of the input tokens (OpenRouter `prompt_tokens` includes them), so the
+  // plain input rate applies only to what is neither read from nor written to the cache.
+  const freshInput = Math.max(0, inputTokens - cachedTokens - cacheWriteTokens);
   // Integer micro-USD accumulation: microUSD = tokens * pricePerMillion
   // ($P per 1M tokens == $P/1e6 per token == P micro-USD per token).
-  const inputMicroUSD = Math.round(nonCachedInput * pricing.input * multiplier);
-  const cacheReadMicroUSD = Math.round(cachedTokens * pricing.cacheRead * multiplier);
-  const cacheWriteMicroUSD = Math.round(cacheWriteTokens * pricing.cacheWrite * multiplier);
+  // A catalog entry without a cache price bills those tokens at the input rate: cache reads/writes are never free.
+  const inputMicroUSD = Math.round(freshInput * pricing.input * multiplier);
+  const cacheReadMicroUSD = Math.round(cachedTokens * (pricing.cacheRead ?? pricing.input) * multiplier);
+  const cacheWriteMicroUSD = Math.round(cacheWriteTokens * (pricing.cacheWrite ?? pricing.input) * multiplier);
   const outputMicroUSD = Math.round(outputTokens * pricing.output * multiplier);
   const audioMicroUSD = Math.round(audioCount * pricing.audio * multiplier);
   const totalMicroUSD = inputMicroUSD + cacheReadMicroUSD + cacheWriteMicroUSD + outputMicroUSD + audioMicroUSD;