agent-accelerator 0.5.3 → 0.5.4

package/README.md

@@ -121,7 +121,7 @@ An `Agent` holds:
 | `tools`           | `Record<string, ToolDefinition> \| ToolDefinition[]` | Deterministic functions the model can call. See [Tools](#tools).                                                                                          |
 | `subagents`       | `SubAgent[] \| Agent[]`                              | Pre-defined workers. Each worker becomes a callable tool. Useful for fixed roles such as researcher or critic.                                             |
 | `subagentModel`   | `string \| ModelSpec \| ModelProviderInstance`       | Developer-only model for dynamically spawned workers. Never choosable by the Main Agent. Deprecated alias of `dynamicSubagents.model` (which wins). Falls back to `SUB_AGENT_MODEL`. |
-| `dynamicSubagents` | `DynamicSubagentsConfig`                            | Enables and constrains LLM-spawned stateless workers: `{ enabled, model?, maxSpawn?, thinkingLevel?, tools?, timeout?, allowScheduledActions? }`. See [Pre-defined vs Dynamic Delegation](#pre-defined-vs-dynamic-delegation) and [Scheduled actions](#scheduled-actions). |
+| `dynamicSubagents` | `DynamicSubagentsConfig`                            | Enables and constrains LLM-spawned workers: `{ enabled, model?, maxSpawn?, maxDepth?, workerBudget?, thinkingLevel?, tools?, timeout?, allowScheduledActions? }` (`timeout` is for scheduled actions only). See [Pre-defined vs Dynamic Delegation](#pre-defined-vs-dynamic-delegation) and [Scheduled actions](#scheduled-actions). |
 | `thinking`        | `ThinkingOption`                                     | Canonical reasoning option: `none \| dynamic \| minimal \| low \| medium \| high \| xhigh \| max`, or `{ level, budgetTokens }`. Legacy `thinkingLevel` still works (canonical wins). Validated against the model catalog before a request.                                      |
 | `cache`           | `CacheOption`                                        | `"implicit" \| "5m" \| "30m" \| "1h" \| "12h"`. Prompt-cache lifetime; unsupported values warn and fall back (see [Cache](#cache)).                                                                             |
 | `serviceTier`     | `"flex" \| "priority"`                               | Cost / priority routing where supported. Omit for standard routing.                                                                                        |
@@ -269,47 +269,60 @@ const agent = new Agent({
   instructions: "You are the Main Agent",
   dynamicSubagents: {
     enabled: true,
-    maxSpawn: 4,
+    maxSpawn: 4, // open workers at once
     thinkingLevel: "low",
-    tools: { get_weather, recent_news },
-    timeout: 60000,
+    tools: { get_weather, recent_news }, // pool: the model grants a subset per worker
   },
 });
 ```
 
-A `spawn_subagents` tool is injected with the following task shape:
+One `subagents` tool is injected. It takes `{ command, id?, name?, role?, instructions?, task?, tools?, history? }` and its manual is the tool description (`src/agent/subagents.md`, with the worker pool and the open-worker limit filled in; the system prompt stays untouched):
+
+- `spawn` starts a worker (`name`, `task`; optional `instructions`, `role`, `tools`, `history`) and waits for its first reply. `message` sends `task` to an open worker `id`, which remembers the whole conversation. `close` frees the slot. `list` shows the open workers and the numbered finished turns that `history: N` can copy into a new worker.
+- Results are plain text with one header line: `[worker researcher-1a2b3c4d] replied:` + the worker's text, or `[worker researcher-1a2b3c4d] failed: <reason>`. Several `spawn` calls in one model turn run in parallel. A bad request comes back as an `Error: ...` line the model can fix.
+- `maxSpawn` is the limit on **open** workers (the model must close one to open another). `budget.maxTotalSubagents` still counts spawns per run.
+- `tools` is the developer-owned pool. Workers get zero tools unless the Main Agent grants a subset by name; unknown names are rejected with the pool listed.
+- The Main Agent cannot choose worker models, reasoning levels or timeouts. The `subagents` tool has no timeouts (`workerTimeoutMs`/`timeout` apply only to scheduled actions).
+- `maxDepth` (default 3, whole number >= 1) is how many levels of workers may exist below the agent: `1` keeps workers flat, `3` lets a worker start workers that start workers. A worker with levels left gets its own `subagents` tool, and its children can only be granted the tools **it** was granted. The levels are saved inside each other (`<session>/workers/<id>/workers/<id>/…`).
+- `workerBudget: { maxCostUsd?, maxTotalTokens? }` is each worker's own spending cap, applied as that worker's per-run `budget` (a spawn, a message or a scheduled run is one run; the usage of the worker's own workers counts toward it) and passed down to its workers. Going over fails that call with a budget error (`[worker <id>] failed: Token budget exceeded…`), leaves the worker open and does not affect the parent. Default: unlimited; models with unknown pricing count $0 toward `maxCostUsd`. Values must be numbers above 0.
+- Workers are real agents with their own session: see [Persistent workers](#persistent-workers-agentworkers) below (the same functions in code, saved on disk with `persist`, resumed after a restart). Each reply's usage is metered into the parent's usage and budget.
+- Each run of a worker gets a system-generated 32-char TrackingID, displayed as `NAME-{TrackingID}`. Thinking/text deltas update the worker trace live (`agent.track(id)`, `subscribeToSubAgent`) and surface on the parent stream as `subagent_delta` events.
 
 ```ts
-{
-  tasks: {
-    name,
-    role?,
-    instructions,
-    task,
-    tools?: string[],
-    timeoutMs?: number
-  }[]
-}
+const res = await agent.run("Audit auth pipeline and write a threat model");
+
+console.log(res.subagents.map((s) => s.name));
 ```
 
-- `maxSpawn` — max workers per call. Extras are trimmed safely, and the limit is stated in the tool description plus the Main Agent's system prompt so the model knows it.
-- `tools` — developer-owned pool. Workers get zero tools unless the Main Agent grants a per-task `tools` subset by name (unknown names are ignored), keeping worker context small.
-- `timeout` (ms) — `0` = no limit, `-1` = the Main Agent sets a per-task `timeoutMs`, `>0` = fixed limit for every worker. Timed-out workers report an error entry; the rest of the batch still completes.
-- Workers are stateless: one task in, one result out, then shut down. No history, no recursion. The Main Agent cannot choose worker models or reasoning levels.
-- Worker names use UPPER-KEBAB (`HBM-PRICING-ANALYST`). Each worker gets a system-generated 32-char TrackingID, displayed as `NAME-{TrackingID}` (e.g. `HBM-PRICING-ANALYST-9f2c…`).
-- Workers stream internally: thinking/text deltas update the worker trace live (`agent.track(id)`, `subscribeToSubAgent`) and surface on the parent stream as `subagent_delta` events.
+### Persistent workers (`agent.workers`)
+
+Besides one-shot delegation, an agent can run **workers that keep their conversation**: start one, message it again and again, close it. A worker is a plain `Agent` with its own instructions and tools, on the developer's worker model (`dynamicSubagents.model` or `SUB_AGENT_MODEL`). With `persist: { dir }` on the parent it is saved under `<parent session folder>/workers/<id>/` (own journal, tool logs and `worker.json`), so it is rebuilt with its history after a restart.
 
 ```ts
-const res = await agent.run("Audit auth pipeline and write a threat model");
+const reply = await lead.workers.spawn({
+  name: "Researcher",
+  instructions: "You research databases and cite sources.", // the worker's OWN prompt; the parent's is never copied
+  task: "Compare SQLite and Postgres for a small SaaS.",
+  tools: ["recent_news"], // subset of dynamicSubagents.tools; unknown names throw
+  history: 1, // optional: start from a copy of the parent's first 1 finished turns (see lead.workers.turns()); default "none"
+});
+console.log(reply.id, reply.text); // e.g. "researcher-1a2b3c4d"
 
-console.log(res.subagents.map((s) => s.name));
+const next = await lead.workers.message(reply.id, "Now focus on write-heavy loads."); // same worker, same conversation
+lead.workers.list(); // open workers: { id, name, role?, tools, busy }
+lead.workers.close(reply.id); // can no longer be messaged; its session stays on disk
 ```
 
+- A turn is one **finished** run (`done` or ended by `ctx.stop`); the running turn and failed or aborted runs are never copied, so a worker never gets a prompt without its answer.
+- `spawn` and `message` wait for the reply and never throw for a failing worker: the `WorkerReply` then carries `error` and a text that says so. They throw `ValidationError` for a bad request (unknown tool or id, closed or busy worker, too many open workers: `dynamicSubagents.maxSpawn` is the open-worker limit, `budget.maxTotalSubagents` still counts spawns per run).
+- A worker handles one call at a time. Pass `{ signal }` to abort its run; the worker stays open.
+- Exactly once across a crash: pass `{ callId }` (the calling tool call's id). A replayed `spawn` finds the worker it already started, a cut-off run is continued with `resume()` instead of sending the text twice, and a call that had already been answered returns that saved answer.
+- Without `persist` the workers live in memory only. A damaged `worker.json` is skipped with a `worker.invalid` event.
+- The reply's `metadata` (usage, steps, lineage) has the same shape as `AgentResponse.subagents`; `agent.track(metadata.trackingId)` shows the run live.
+
 ### Delegation Helpers
 
 * `buildAgentTools(list)` — wraps multiple agents and deduplicates names. Used internally by `subagents`.
-* `createSubagentSpawnTool(parentAgent)` — builds the dynamic subagent spawner. Rarely needed directly.
-* `DynamicSubagentTask` — `{ name, role?, instructions, task, tools?, timeoutMs? }`, the shape produced for dynamic delegation. No `model` — workers run on the developer-configured model.
 
 ---
 ## Scheduled actions
@@ -426,11 +439,11 @@ const pay = tool({
 
 `ctx.stop` throws, so the code after it never runs (even if you forget `return`). The reason is saved as that call's result, calls that were running in parallel in the same batch still run to completion (none is skipped or aborted), and then the run ends with `finishReason: "stopped"` and **no further model turn**. The agent waits for the next user message; the model then sees the reason as the tool's result. A steer typed while the batch ran becomes the next run. The stop is saved with the call, so a crash cannot turn a "no" into a "yes": after a restart the run is closed as stopped without calling the model. A tool's `timeoutMs` counts the time spent waiting for your check, so leave it off for tools that ask a person.
 
-To guard a built-in tool such as `spawn_subagents` or `scheduled_actions`, wrap it on the agent after construction:
+To guard a built-in tool such as `subagents` or `scheduled_actions`, wrap it on the agent after construction:
 
 ```ts
-const inner = agent.tools["spawn_subagents"]!;
-agent.tools["spawn_subagents"] = {
+const inner = agent.tools["subagents"]!;
+agent.tools["subagents"] = {
   ...inner,
   execute: async (input, ctx) => ((await getPermission("Spawn workers?")) ? inner.execute(input, ctx) : ctx.stop("spawning was not approved")),
 };
@@ -1011,9 +1024,32 @@ TokenUsage {
 }
 ```
 
-Cost calculation prefers provider-reported totals. When unavailable, costs are computed using catalog pricing.
+Cost calculation prefers provider-reported totals. When unavailable, costs are computed using catalog pricing, per model turn: fresh input at the input price, cache reads at the cache-read price, cache writes at the cache-write price (both are part of `inputTokens`, so they are not billed twice), output at the output price (thinking tokens are part of output), scaled by `serviceTier` (`flex` x0.5, `priority` x2, estimates). A catalog entry without a cache price bills those tokens at the input rate (cache is never free); unknown pricing stays unknown.
 
 Subagent usage is rolled into the parent totals.
+
+### Usage report (`agent.usageReport()`)
+
+`res.usage` is the cost of one run, workers included. `agent.usageReport()` is the other view: what the agent and **each** worker spent over their lives, itemized, with nothing counted twice.
+
+```ts
+const report = agent.usageReport();
+report.agent;   // this agent's OWN model calls: id, name, model, turns, tokens, cacheHitRate, cost
+report.workers; // every worker below it (open, closed, nested in `workers`, and `status: "fixed"` for `subagents: [...]`)
+report.total;   // agent + all workers
+// each line, e.g. report.workers[0]:
+// { id: "researcher-1a2b3c4d", status: "open", model: "google/gemini-3.5-flash-lite", turns: 2,
+//   tokens: { input: 2000, freshInput: 600, cacheRead: 1200, cacheWrite: 200, output: 400, thinking: 100, total: 2400 },
+//   cacheHitRate: 0.6,
+//   cost: { source: "catalog", unpricedTurns: 0, totalUsd: 0.00891,
+//           parts: { inputUsd: 0.0018, outputUsd: 0.006, cacheReadUsd: 0.00036, cacheWriteUsd: 0.00075 } } }
+```
+
+- **Own turns only.** Every agent records the model calls it made itself, priced **per turn** in integer micro-USD, and saves them in its session (`usage`), so the numbers survive a restart (load the session and the totals carry on; workers are rebuilt from their folders). A parent's `res.usage` already contains its workers' usage, which is why the report never adds responses together: `report.total.tokens.total` equals what the responses show.
+- **Cache-aware.** `input` includes the cache reads and writes (`freshInput = input - cacheRead - cacheWrite`); `output` includes `thinking`. Fresh input, cache reads and cache writes are each priced at their own catalog price, and `serviceTier` is applied. `cacheHitRate` is `cacheRead / input` (0 to 1, `null` when nothing was sent).
+- **Honest costs.** `cost.source` is `provider` (the provider reported the cost, which is exact), `catalog` (estimated from the model catalog), `mixed`, or `unknown`. Unknown pricing is `totalUsd: null`, never 0; `unpricedTurns` above 0 means the total is a lower bound. For turns whose cost the provider reported only the total is exact, so `parts` can add up to less than `totalUsd`.
+- **Not in the report:** the one-shot workers of scheduled actions (their cost is in each run file), and workers started inside a fixed `subagents` worker's per-call copy (their cost is in the response usage). `reset()` does not clear the totals: they are spending, not conversation.
+
 ### ProviderRawData
 
 ```ts
@@ -1288,7 +1324,7 @@ bun run examples/04-sub-agents.ts
 # fixed researcher + critic pipeline
 
 bun run examples/03-multi_agent.ts
-# dynamic spawn_subagents demo
+# dynamic subagents tool demo
 
 bun run examples/01-metadata.ts
 # usage + raw inspection

package/examples/prompts/SYSTEM_PROMPT_AGENT.md

@@ -1,34 +1,28 @@
-You are an Agent — you evaluate user objectives and decide whether to solve them directly or delegate to specialized parallel sub-agents.
+You are an Agent — you evaluate user objectives and decide whether to solve them directly or delegate to specialized parallel workers with the `subagents` tool.
 
 ### Workflow & Decision Matrix
 1. **Triage**:
    - Single-focus, factual, code-generation, or conversational prompts → Answer directly, concisely, and completely.
-   - Do NOT spawn sub-agents for trivial, single-step tasks.
+   - Do NOT start workers for trivial, single-step tasks.
 2. **Delegate**:
-    - Complex research, multi-angle analysis, deep technical trade-offs, or parallel explorations → Invoke `spawn_subagents` with 2 to 4 focused sub-agents in a single batched call.
-   - For each sub-agent define:
-     - `name`: `UPPER_SNAKE_CASE` identifier describing domain focus (e.g., `MARKET_ANALYST`, `SYSTEMS_ARCHITECT`).
+   - Complex research, multi-angle analysis, deep technical trade-offs, or parallel explorations → call `subagents` with `command: "spawn"` once per worker, 2 to 4 focused workers, all in the same turn so they run in parallel.
+   - For each worker define:
+     - `name`: short label describing its domain focus (e.g. `market-analyst`, `systems-architect`).
      - `role`: Distinct specialized persona.
      - `instructions`: Self-contained, expert prompt detailing scope, methodologies, and constraints.
      - `task`: Focused, non-overlapping research query or execution directive.
 3. **Aggregate**:
-   - Sub-agent findings arrive concurrently wrapped in XML:
-   ```xml
-   <SUB-AGENTS-RESPONSE>
-       <DYNAMIC_ROLE_1>
-           Findings from sub-agent 1
-       </DYNAMIC_ROLE_1>
-       <DYNAMIC_ROLE_2>
-           Findings from sub-agent 2
-       </DYNAMIC_ROLE_2>
-   </SUB-AGENTS-RESPONSE>
+   - Each worker answers with a header line and its findings:
    ```
-   - Node tags match each sub-agent's `name` in `UPPER_SNAKE_CASE`.
+   [worker market-analyst-1a2b3c4d] replied:
+   Findings from the worker
+   ```
+   - Use `command: "message"` with the worker's `id` to ask a follow-up; the worker remembers the conversation. `command: "close"` when you no longer need it.
 4. **Synthesize**:
-   - Deliver an editorial-grade, cohesive report that integrates all sub-agent insights.
+   - Deliver an editorial-grade, cohesive report that integrates all worker insights.
    - Reconcile contradictions, de-duplicate redundant information, and highlight critical trade-offs.
-   - Structure with executive summaries, comparative Markdown tables, and concrete strategic conclusions. Never present an uncurated list of sub-agent summaries.
+   - Structure with executive summaries, comparative Markdown tables, and concrete strategic conclusions. Never present an uncurated list of worker summaries.
 
 ### Execution Rules
-- **Tool Protocol**: Invoke `spawn_subagents` directly without conversational preambles. Ensure all sub-agents are passed in a single tool call array.
-- **Context Isolation**: Sub-agents run in isolated contexts; provide complete background in their `instructions` and `task`.
+- **Tool Protocol**: Call `subagents` directly without conversational preambles. Start parallel workers with several `spawn` calls in one turn.
+- **Context Isolation**: Workers start blank; provide complete background in their `instructions` and `task`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "High-performance SDK for AI agents with a unified API across AI providers. Optimized for high cache hit rates, observability, and seamless agent orchestration. Built to power production-grade agentic systems and harnesses for teams at any scale.",
   "license": "MIT",
   "author": "Sashvat Bharat",

package/src/agent/agent.ts

@@ -10,8 +10,11 @@ import { AgentResponse, type StreamEvent } from "../types/response.ts";
 import { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 import { AgentContext } from "./context.ts";
 import { resolveModel } from "../providers/registry.ts";
-import { buildAgentTools, createSubagentSpawnTool } from "./delegation.ts";
+import { buildAgentTools } from "./delegation.ts";
+import { createSubagentsTool } from "./subagents-tool.ts";
+import { WorkerRegistry } from "./workers.ts";
 import {
+  DEFAULT_MAX_DEPTH,
   normalizeToolMap,
   resolveDynamicModelInput,
   resolveMainModel,
@@ -34,7 +37,8 @@ import {
   listSubAgentTraceIdsForSessions,
   type SubAgentTrace,
 } from "./delegation.ts";
-import { saveSessionFile, sessionDirFor, loadSessionDir, findInvalidMessage, telemetryBus, type SessionRunMark, type SessionRunEnd, type SessionPending, type SessionToolRecord } from "../session/store.ts";
+import { addTurn, buildUsageReport, emptyUsage, mergeUsage, modelName, readUsage, type UsageNode, type UsageReport, type UsageTotals } from "../session/usage.ts";
+import { saveSessionFile, sessionDirFor, loadSessionDir, findInvalidMessage, priceUsage, telemetryBus, type SessionRunMark, type SessionRunEnd, type SessionPending, type SessionToolRecord } from "../session/store.ts";
 import { SessionJournal } from "../session/journal.ts";
 import { ToolLogs, type ToolLogWriter } from "../session/tool-log.ts";
 import { isLocalPathInput } from "../utils/safe-io.ts";
@@ -167,6 +171,10 @@ export class Agent {
     timeout: number;
     /** Scheduled actions (`scheduled_actions` + `get_datetime` tools) are on. */
     allowScheduledActions: boolean;
+    /** Levels of workers allowed below this agent. */
+    maxDepth: number;
+    /** Per-run spending cap of each worker (unset = unlimited). */
+    workerBudget?: { maxCostUsd?: number; maxTotalTokens?: number };
   };
   /** Home folder for everything written to disk (`sessions/`, `scheduled_actions/`, `telemetry/`). */
   readonly home: string;
@@ -263,6 +271,8 @@ export class Agent {
   readonly runMarks: SessionRunMark[] = [];
   /** Tool calls finished in the current run; saved the moment each finishes so a crash never repeats them. @internal */
   readonly toolRecords: SessionToolRecord[] = [];
+  /** What this agent spent on its OWN model calls (workers keep their own); saved with the session. @internal */
+  readonly usageTotals: UsageTotals = emptyUsage();
   /** The run in flight (its mark has no ending yet, but it is not "interrupted"). */
   private activeMark?: SessionRunMark;
   /** What to do with a cut-off run at construction (see `AgentConfig.resume`). */
@@ -271,6 +281,7 @@ export class Agent {
   private readonly runRetries: number;
   /** The resume in flight, so a second `resume()` returns the same promise. */
   private resuming?: Promise<AgentResponse | undefined>;
+  private workerRegistry?: WorkerRegistry;
 
   /**
    * Creates an agent and registers its model, tools, cache, and delegation settings.
@@ -307,6 +318,17 @@ export class Agent {
     const dynEnabled = dynRaw ? (dynRaw.enabled ?? true) : false;
     if (dynRaw) {
       const dynTools = normalizeToolMap((dynRaw as { tools?: Record<string, ToolDefinition> | ToolDefinition[] }).tools);
+      const rawDepth = (dynRaw as { maxDepth?: unknown }).maxDepth;
+      if (rawDepth !== undefined && !(Number.isInteger(rawDepth) && (rawDepth as number) >= 1)) {
+        throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.maxDepth ${JSON.stringify(rawDepth)}: expected a whole number >= 1 (default ${DEFAULT_MAX_DEPTH}); set dynamicSubagents.enabled: false to turn workers off.`);
+      }
+      const rawBudget = (dynRaw as { workerBudget?: { maxCostUsd?: unknown; maxTotalTokens?: unknown } }).workerBudget;
+      for (const key of ["maxCostUsd", "maxTotalTokens"] as const) {
+        const v = rawBudget?.[key];
+        if (v !== undefined && !(typeof v === "number" && Number.isFinite(v) && v > 0)) {
+          throw new ConfigError(`[Agent Accelerator] Invalid dynamicSubagents.workerBudget.${key} ${JSON.stringify(v)}: expected a number greater than 0, or omit it for no limit.`);
+        }
+      }
       const rawMax = (dynRaw as any)?.maxSpawn;
       const maxSpawn = Number.isFinite(rawMax) ? Math.max(1, Math.floor(rawMax as number)) : 4;
       // `workerTimeoutMs ?? timeout`, or -1 when `modelMaySetTimeout` (see normalizeWorkerTimeout).
@@ -319,6 +341,8 @@ export class Agent {
         tools: dynTools,
         timeout,
         allowScheduledActions: dynRaw.allowScheduledActions === true,
+        maxDepth: (rawDepth as number | undefined) ?? DEFAULT_MAX_DEPTH,
+        ...(rawBudget ? { workerBudget: { ...(rawBudget as { maxCostUsd?: number; maxTotalTokens?: number }) } } : {}),
       };
     }
     this.apiKey = (rawModel as any)?.apiKey || config.apiKey;
@@ -438,8 +462,8 @@ export class Agent {
       );
     }
     if (dyn?.enabled === true) {
-      const spawnTool = createSubagentSpawnTool(this);
-      this.tools[spawnTool.name || "spawn_subagents"] = spawnTool;
+      const subagentsTool = createSubagentsTool(this);
+      this.tools[subagentsTool.name || "subagents"] = subagentsTool;
     }
     if (dyn?.allowScheduledActions) {
       // Fixed by config, so the tool set (and the prompt cache) stays stable.
@@ -459,6 +483,11 @@ export class Agent {
     }
   }
 
+  /** The persistent sub-agent workers of this agent: `spawn`, `message`, `close`, `list`, `turns` (see `WorkerRegistry`). */
+  get workers(): WorkerRegistry {
+    return (this.workerRegistry ??= new WorkerRegistry(this));
+  }
+
   // Loads a persisted session that a crash cut off (a run without an ending) or that still had waiting prompts, so it can be resumed; true when there is something to resume; in: the session folder of `persist.dir`, out: context, runMarks, toolRecords, pendingQueue.
   private recoverSession(): boolean {
     const root = this.persistConfig?.dir;
@@ -475,6 +504,7 @@ export class Agent {
     if (!(session.runs ?? []).some((r) => !r.end) && waiting.length === 0) return false;
     this.context.messages = session.messages;
     this.runMarks.splice(0, this.runMarks.length, ...(session.runs ?? []));
+    this.restoreUsage(session.usage);
     const open = new Set(unfinishedToolCalls(this.context.messages).map((c) => c.id));
     this.toolRecords.splice(0, this.toolRecords.length, ...(session.tools ?? []).filter((t) => open.has(t.id)));
     for (const w of waiting) {
@@ -489,6 +519,42 @@ export class Agent {
     return true;
   }
 
+  // Puts saved spending totals back after a restart or import (zeros when the file has none); in: a loaded session's `usage`, out: this.usageTotals.
+  private restoreUsage(saved: unknown): void {
+    Object.assign(this.usageTotals, readUsage(saved));
+  }
+
+  // Records one model call of THIS agent (priced per turn, with the service tier); in: the loop's onTurnUsage, out: this.usageTotals (saved by the next persist).
+  private recordTurnUsage(usage: TokenUsage, spec: Parameters<typeof priceUsage>[1]): void {
+    addTurn(this.usageTotals, usage, priceUsage(usage, spec, this.serviceTier ? { serviceTier: this.serviceTier } : undefined));
+  }
+
+  /** Adds another agent's spending to this one (a fixed worker's per-call copy into its template). @internal */
+  absorbUsage(other: UsageTotals): void {
+    mergeUsage(this.usageTotals, other);
+  }
+
+  /**
+   * What this agent and every worker below it spent: per agent and per worker (tokens, cache hits, thinking, exact
+   * cost per turn) plus a whole-session total, with nothing counted twice. `agent` is this agent's own model calls;
+   * workers (open, closed, nested, and rebuilt from disk after a restart) and fixed `subagents` workers are listed
+   * below it. Spending of one-shot scheduled-action workers is in their run files, not here.
+   */
+  usageReport(): UsageReport {
+    return buildUsageReport({ id: this.sessionId, name: this.name, model: modelName(this.modelStringOrSpec), totals: this.usageTotals }, [...this.workers.usageNodes(), ...this.fixedWorkerNodes()]);
+  }
+
+  // The `subagents: [...]` workers as usage nodes (their per-call copies' spending is merged into them); in: the constructor config, out: usageReport.
+  private fixedWorkerNodes(): UsageNode[] {
+    const nodes: UsageNode[] = [];
+    for (const entry of this.forkConfig.subagents ?? []) {
+      const worker = "agent" in entry ? entry.agent : entry;
+      const name = "agent" in entry ? entry.name : worker.name;
+      nodes.push({ id: name, name, model: modelName(worker.modelStringOrSpec), status: "fixed", totals: worker.usageTotals, workers: [] });
+    }
+    return nodes;
+  }
+
   // Says on the telemetry bus that resuming (or a prompt that was waiting) failed; in: a rejected resume, out: telemetryBus.
   private reportResumeFailure(err: unknown): void {
     telemetryBus.emitWarning("agent.resume_failed", `[Agent Accelerator] Resuming session ${this.sessionId} failed: ${err instanceof Error ? err.message : String(err)}`, { sessionId: this.sessionId });
@@ -579,26 +645,6 @@ export class Agent {
         "3. Once your reasoning is complete, output your final response or function calls directly in the standard response output.";
       out = out ? `${out}\n\n${guidance}` : guidance;
     }
-    if (this.dynamicSubagents?.enabled === true && !out.includes("[Dynamic Sub-Agents]")) {
-      const dyn = this.dynamicSubagents;
-      const toolNames = Object.keys(dyn.tools);
-      const timeoutNote =
-        dyn.timeout === -1
-          ? "Timeout policy: set a per-sub-agent timeoutMs (ms) for each task; omit it for no limit."
-          : dyn.timeout === 0
-            ? "Timeout policy: workers run with no time limit."
-            : `Timeout policy: every worker is limited to ${dyn.timeout}ms; per-task timeouts are ignored.`;
-      const policy =
-        "[Dynamic Sub-Agents]\n" +
-        `1. You may spawn at most ${dyn.maxSpawn} sub-agent(s) per spawn_subagents call. Extra tasks beyond ${dyn.maxSpawn} are ignored.\n` +
-        "2. Workers are stateless: each receives one task, returns its result, then shuts down. No conversation history is kept.\n" +
-        "3. You cannot choose worker models or reasoning levels — they are fixed by the developer.\n" +
-        (toolNames.length > 0
-          ? `4. Worker-available tools: ${toolNames.join(", ")}. Grant each worker ONLY the tools its task needs via the per-task tools list; omit it for no tools.\n`
-          : "4. No worker tools are available; omit the per-task tools list.\n") +
-        `5. ${timeoutNote}`;
-      out = out ? `${out}\n\n${policy}` : policy;
-    }
     return out || undefined;
   }
 
@@ -1161,6 +1207,7 @@ export class Agent {
         ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
         ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
         onProgress: () => this.persistNow(),
+        onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
         onToolResult: (r: ToolResultRecord) => this.recordTool(r),
         openToolLog: (call: { name: string }, sid: string | undefined) => this.openToolLog(call, sid),
         ...(resumeMark ? { resume: { stored: this.storedToolResults() } } : {}),
@@ -1251,6 +1298,7 @@ export class Agent {
       ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
       ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
       onProgress: () => this.persistNow(),
+      onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
       onToolResult: (r: ToolResultRecord) => this.recordTool(r),
       openToolLog: (call: { name: string }, sid: string | undefined) => this.openToolLog(call, sid),
       steerInbox,
@@ -1501,6 +1549,7 @@ export class Agent {
     }
     this.context.thoughtSignatures = [];
     this.runMarks.splice(0, this.runMarks.length, ...(data.runs ?? []).filter((r) => r.i < this.context.messages.length));
+    this.restoreUsage(data.usage);
     if (data.systemPrompt) {
       this.context.systemPrompt = data.systemPrompt;
     } else {

package/src/agent/context.ts

@@ -11,7 +11,7 @@ function fail(message: string): never {
 }
 
 /** Deep clone that preserves Uint8Array/ArrayBuffer media (structuredClone may be absent). */
-function deepCloneValue<T>(value: T): T {
+export function deepCloneValue<T>(value: T): T {
   if (value instanceof Uint8Array) return new Uint8Array(value) as T;
   if (value instanceof ArrayBuffer) return value.slice(0) as T;
   if (Array.isArray(value)) return value.map((v) => deepCloneValue(v)) as T;