zidane 3.4.1 → 4.0.1

package/README.md

@@ -342,11 +342,16 @@ agent.hooks.hook('turn:after', (ctx) => {
 
 agent.hooks.hook('usage', (ctx) => {
   // ctx.turn, ctx.turnId, ctx.usage (per-turn)
-  // ctx.totalIn, ctx.totalOut (running totals)
+  // ctx.totalIn, ctx.totalOut (running parent-loop totals — children fold in
+  // post-loop and are visible on `agent:done`)
 })
 
 agent.hooks.hook('agent:done', (ctx) => {
-  // ctx.totalIn, ctx.totalOut, ctx.turns, ctx.elapsed, ctx.children?
+  // ctx.totalIn / ctx.totalOut / ctx.cost — cumulative across parent loop +
+  //   every recursively-spawned sub-agent
+  // ctx.turns, ctx.elapsed — parent-loop view (use `flattenTurns(ctx).length`
+  //   for tree-wide turn counts, `statsByModel(ctx)` for per-model breakdown)
+  // ctx.children? — per-child stats in completion order
   // ctx.output — structured output (when behavior.schema is set)
   // Fires on all exit paths: completion, maxTurns, and abort
 })
@@ -1030,11 +1035,24 @@ const schema = zodToJsonSchema(z.toJsonSchema(z.object({ name: z.string() })))
 
 ## Usage Tracking
 
+`stats.totalIn` / `stats.totalOut` / `stats.cost` are **cumulative** — parent
+loop plus every recursively-spawned sub-agent. `stats.turns` and
+`stats.turnUsage` cover the parent loop only; reach for the helpers below for
+tree-wide breakdowns.
+
 ```ts
+import { flattenTurns, statsByModel } from 'zidane'
+
 const stats = await agent.run({ prompt: 'hello' })
-stats.turnUsage                 // TurnUsage[] — per-turn { input, output, cacheCreation?, cacheRead?, thinking?, cost?, finishReason?, modelId? }
-stats.cost                      // total USD cost (if reported by provider)
+stats.totalIn                   // cumulative input tokens (parent + recursive children)
+stats.totalOut                  // cumulative output tokens
+stats.cost                      // cumulative USD cost (when reported by provider)
+stats.turnUsage                 // TurnUsage[] — parent loop only
+stats.children                  // ChildRunStats[] — recursive subtree, completion order
 stats.timeTillFirstTokenMs      // ms from run() start to the first stream/tool event
+
+flattenTurns(stats)             // every TurnUsage in the tree, parent first then DFS children
+statsByModel(stats)             // Map<modelId, { input, output, cost, cacheRead, cacheCreation, turns }>
 ```
 
 ## Types

package/dist/{agent-CMjWCUPr.d.ts → agent-BAHrGtqu.d.ts}

@@ -1,5 +1,5 @@
 import { Hookable } from 'hookable';
-import { b as ExecutionContext, c as ExecutionHandle } from './types-vA1a_ZX7.js';
+import { a as ExecutionContext, c as ExecutionHandle } from './types-Bai5rKpa.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 
 /**
@@ -764,15 +764,59 @@ interface TurnUsage {
     modelId?: string;
 }
 interface AgentStats {
+    /**
+     * Cumulative input tokens across the parent agent loop **and** every
+     * recursively-spawned sub-agent. Use this for billing / token-ledger
+     * consumption.
+     */
     totalIn: number;
+    /** Cumulative output tokens. Same semantics as {@link AgentStats.totalIn}. */
     totalOut: number;
+    /**
+     * Cumulative cache-read tokens across the parent agent loop and every
+     * recursively-spawned sub-agent. Surfaced at the top level (rather than
+     * only per-`TurnUsage`) because Anthropic prices cache reads at a separate
+     * line-item rate from regular input — billing-correct cost computation
+     * needs this number directly. Always `0` for providers that don't report
+     * cache usage.
+     */
+    totalCacheRead: number;
+    /**
+     * Cumulative cache-creation tokens across the parent agent loop and every
+     * recursively-spawned sub-agent. Same rationale as
+     * {@link AgentStats.totalCacheRead} — separate Anthropic billing rate.
+     * Always `0` for providers that don't report cache usage.
+     */
+    totalCacheCreation: number;
+    /**
+     * Number of parent agent-loop turns. Children's turn counts live under
+     * `children[].stats.turns` and are NOT folded in here — a single "turns"
+     * number for the whole tree would conflate two different measures
+     * (parent-loop iterations vs. tree-wide tool-call rounds).
+     *
+     * Tree-wide turn count: `flattenTurns(stats).length`.
+     */
     turns: number;
+    /**
+     * Wall-clock duration of the top-level `agent.run()` call, in milliseconds.
+     * Children run during parent tool calls so this naturally subsumes child
+     * wall time — sequential children inflate it, parallel children compress
+     * into the parent's window.
+     */
     elapsed: number;
-    /** Per-turn usage breakdown */
+    /**
+     * Per-turn usage breakdown for the **parent loop only**. Children's per-turn
+     * usages live under `children[].stats.turnUsage`. Use {@link flattenTurns}
+     * to walk the full tree.
+     */
     turnUsage?: TurnUsage[];
-    /** Total cost in USD (sum of per-turn costs reported by provider) */
+    /**
+     * Cumulative cost in USD — parent loop plus every recursively-spawned
+     * sub-agent. Sums per-turn `TurnUsage.cost` reported by the provider.
+     * Absent when neither parent nor any descendant reported a non-zero cost.
+     */
     cost?: number;
-    /** Stats from child agents spawned during this run */
+    /** Stats from child agents spawned during this run, in completion order. Recursive. */
     children?: ChildRunStats[];
     /** Structured output from schema enforcement (only present when behavior.schema is set) */
     output?: Record<string, unknown>;
@@ -787,6 +831,12 @@ interface AgentStats {
 interface ChildRunStats {
     id: string;
     task: string;
+    /**
+     * The child agent's full {@link AgentStats}. Cumulative for that child's
+     * own subtree (child loop + its grandchildren). Do **not** sum
+     * `ctx.stats.totalIn` across `spawn:complete` events to derive top-level
+     * totals — `agent.run()`'s return value is the canonical cumulative root.
+     */
     stats: AgentStats;
     /**
      * Subagent depth when this child ran. 1 = direct child of the top-level
@@ -2236,6 +2286,15 @@ interface AgentHooks {
         mode: 'steer' | 'block';
     }) => void;
     'agent:abort': (ctx: object) => void;
+    /**
+     * Run finished — fires on all exit paths (completion, maxTurns, abort).
+     *
+     * Since 4.0 the `AgentStats` carried here is **cumulative** across the
+     * parent agent loop and every recursively-spawned sub-agent
+     * (`totalIn` / `totalOut` / `cost` / `totalCacheRead` / `totalCacheCreation`).
+     * For parent-loop-only counts use `ctx.turnUsage` (parent-only array);
+     * for tree-wide turn counts use `flattenTurns(ctx).length`.
+     */
     'agent:done': (ctx: AgentStats) => void;
     'session:start': (ctx: SessionHookContext & {
         runId: string;
@@ -2363,4 +2422,4 @@ interface Agent {
 }
 declare function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, mcpConnector, eager }: AgentOptions): Agent;
 
-export { type ToolMap as $, type Agent as A, type SessionData as B, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as C, type SessionEndStatus as D, type SessionHookContext as E, type SessionMessage as F, type SessionRun as G, type SessionStore as H, type SessionTurn as I, type SkillConfig as J, type SkillResource as K, type SkillsConfig as L, type McpConnection as M, type SpawnHookContext as N, type OAuthRefreshHookContext as O, type PromptDocumentPart as P, type StreamCallbacks as Q, type RemoteStoreOptions as R, type Session as S, type StreamHookContext as T, type StreamOptions as U, type ThinkingLevel as V, type ToolCall as W, type ToolContext as X, type ToolDef as Y, type ToolExecutionMode as Z, type ToolHookContext as _, AgentAbortedError as a, type ToolResult as a0, type ToolResultContent as a1, type ToolResultImageContent as a2, type ToolResultTextContent as a3, type ToolSpec as a4, type TurnFinishReason as a5, type TurnResult as a6, type TurnUsage as a7, matchesContextExceeded as a8, toolOutputByteLength as a9, loadSession as aA, mapOAIFinishReason as aB, normalizeMcpBlocks as aC, normalizeMcpServers as aD, openai as aE, openaiCompat as aF, openrouter as aG, resultToString as aH, toAnthropic as aI, toOpenAI as aJ, toTypedError as aK, toolResultToText as aa, type ActivationVia as ab, type ActiveSkill as ac, type DeactivationReason as ad, type FileMapAdapter as ae, type FileMapStoreOptions as af, type OpenAICompatAuthHeader as ag, OpenAICompatHttpError as ah, type OpenAICompatParams as ai, type SkillActivationState as aj, type SkillActivationStateOptions as ak, type SkillDiagnostic as al, type SkillSource as am, anthropic as an, autoDetectAndConvert as ao, cerebras as ap, classifyOpenAICompatError as aq, connectMcpServers as ar, createAgent as as, createFileMapStore as at, createMemoryStore as au, createRemoteStore as av, createSession as aw, createSkillActivationState as ax, fromAnthropic as ay, fromOpenAI as az, type AgentBehavior as b, AgentContextExceededError as c, type AgentHooks as d, type AgentOptions as e, AgentProviderError as f, type AgentRunOptions as g, type AgentStats as h, AgentToolNotAllowedError as i, type AnthropicParams as j, type CerebrasParams as k, type ChildRunStats as l, type ClassifiedError as m, type ClassifiedErrorKind as n, type CreateSessionOptions as o, type McpServerConfig as p, type McpToolHookContext as q, type OpenAIParams as r, type OpenRouterParams as s, type PromptImagePart as t, type PromptPart as u, type PromptTextPart as v, type Provider as w, type ProviderCapabilities as x, type RunHookMap as y, type SessionContentBlock as z };
+export { type SkillsConfig as $, type AgentHooks as A, type PromptTextPart as B, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as C, type DeactivationReason as D, type Provider as E, type FileMapAdapter as F, type ProviderCapabilities as G, type RunHookMap as H, type Session as I, type SessionContentBlock as J, type SessionData as K, type SessionEndStatus as L, type McpConnection as M, type SessionHookContext as N, type OAuthRefreshHookContext as O, type PromptDocumentPart as P, type SessionMessage as Q, type RemoteStoreOptions as R, type SessionStore as S, type SessionRun as T, type SessionTurn as U, type SkillActivationState as V, type SkillActivationStateOptions as W, type SkillConfig as X, type SkillDiagnostic as Y, type SkillResource as Z, type SkillSource as _, type ActivationVia as a, type SpawnHookContext as a0, type StreamCallbacks as a1, type StreamHookContext as a2, type StreamOptions as a3, type ThinkingLevel as a4, type ToolCall as a5, type ToolContext as a6, type ToolDef as a7, type ToolExecutionMode as a8, type ToolHookContext as a9, normalizeMcpServers as aA, openai as aB, openaiCompat as aC, openrouter as aD, resultToString as aE, toAnthropic as aF, toOpenAI as aG, toTypedError as aH, toolOutputByteLength as aI, toolResultToText as aJ, type ChildRunStats as aK, type ToolMap as aa, type ToolResult as ab, type ToolResultContent as ac, type ToolResultImageContent as ad, type ToolResultTextContent as ae, type ToolSpec as af, type TurnFinishReason as ag, type TurnResult as ah, type TurnUsage as ai, anthropic as aj, autoDetectAndConvert as ak, cerebras as al, classifyOpenAICompatError as am, connectMcpServers as an, createAgent as ao, createFileMapStore as ap, createMemoryStore as aq, createRemoteStore as ar, createSession as as, createSkillActivationState as at, fromAnthropic as au, fromOpenAI as av, loadSession as aw, mapOAIFinishReason as ax, matchesContextExceeded as ay, normalizeMcpBlocks as az, type ActiveSkill as b, type Agent as c, AgentAbortedError as d, type AgentBehavior as e, AgentContextExceededError as f, type AgentOptions as g, AgentProviderError as h, type AgentRunOptions as i, type AgentStats as j, AgentToolNotAllowedError as k, type AnthropicParams as l, type CerebrasParams as m, type ClassifiedError as n, type ClassifiedErrorKind as o, type CreateSessionOptions as p, type FileMapStoreOptions as q, type McpServerConfig as r, type McpToolHookContext as s, type OpenAICompatAuthHeader as t, OpenAICompatHttpError as u, type OpenAICompatParams as v, type OpenAIParams as w, type OpenRouterParams as x, type PromptImagePart as y, type PromptPart as z };

package/dist/{chunk-VTLEPYND.js → chunk-4LPBN547.js}

@@ -7,6 +7,9 @@ import {
   resolveSkills,
   validateResourcePath
 } from "./chunk-6STZTA4N.js";
+import {
+  flattenTurns
+} from "./chunk-IC7FT4OD.js";
 import {
   createProcessContext
 } from "./chunk-UD25QF3H.js";
@@ -1704,6 +1707,8 @@ function sanitizeStoredToolResults(provider, messages) {
 async function runLoop(ctx) {
   let totalIn = 0;
   let totalOut = 0;
+  let totalCacheRead = 0;
+  let totalCacheCreation = 0;
   const turnUsages = [];
   const startTime = Date.now();
   const maxTurns = ctx.maxTurns ?? Number.POSITIVE_INFINITY;
@@ -1726,6 +1731,8 @@ async function runLoop(ctx) {
       turnsCompleted = turn + 1;
       totalIn += result.usage.input;
       totalOut += result.usage.output;
+      totalCacheRead += result.usage.cacheRead ?? 0;
+      totalCacheCreation += result.usage.cacheCreation ?? 0;
       turnUsages.push(result.usage);
       await ctx.hooks.callHook("usage", { turn, turnId: result.turnId, usage: result.usage, totalIn, totalOut });
       if (ctx.signal.aborted) {
@@ -1762,6 +1769,8 @@ async function runLoop(ctx) {
         return {
           totalIn,
           totalOut,
+          totalCacheRead,
+          totalCacheCreation,
           turns: turn + 1,
           elapsed: Date.now() - startTime,
           turnUsage: turnUsages,
@@ -1773,6 +1782,8 @@ async function runLoop(ctx) {
     return {
       totalIn,
       totalOut,
+      totalCacheRead,
+      totalCacheCreation,
       turns: turnsCompleted,
       elapsed: Date.now() - startTime,
       turnUsage: turnUsages,
@@ -2985,8 +2996,27 @@ ${buildSearchableCatalog(disclosure.lazyEntries, { discoveryToolName })}`;
         runStartMs,
         runToolCounts: {}
       });
+      const parentTurnCost = stats.turnUsage?.reduce((sum, t) => sum + (t.cost ?? 0), 0) ?? 0;
+      let childrenIn = 0;
+      let childrenOut = 0;
+      let childrenCost = 0;
+      let childrenCacheRead = 0;
+      let childrenCacheCreation = 0;
+      for (const c of childrenStats) {
+        childrenIn += c.stats.totalIn;
+        childrenOut += c.stats.totalOut;
+        childrenCost += c.stats.cost ?? 0;
+        childrenCacheRead += c.stats.totalCacheRead;
+        childrenCacheCreation += c.stats.totalCacheCreation;
+      }
+      const cumulativeCost = parentTurnCost + childrenCost;
       const finalStats = {
         ...stats,
+        totalIn: stats.totalIn + childrenIn,
+        totalOut: stats.totalOut + childrenOut,
+        totalCacheRead: stats.totalCacheRead + childrenCacheRead,
+        totalCacheCreation: stats.totalCacheCreation + childrenCacheCreation,
+        ...cumulativeCost > 0 ? { cost: cumulativeCost } : {},
         children: childrenStats.length > 0 ? childrenStats : void 0
       };
       await flushTurns();
@@ -2996,15 +3026,12 @@ ${buildSearchableCatalog(disclosure.lazyEntries, { discoveryToolName })}`;
         await hooks.callHook("agent:done", finalStats);
         return finalStats;
       }
-      const totalCost = finalStats.turnUsage?.reduce((sum, t) => sum + (t.cost ?? 0), 0);
-      if (totalCost)
-        finalStats.cost = totalCost;
       session?.completeRun(runId, {
-        turns: finalStats.turns,
-        tokensIn: finalStats.totalIn,
-        tokensOut: finalStats.totalOut,
-        turnUsage: finalStats.turnUsage,
-        cost: totalCost
+        turns: stats.turns,
+        tokensIn: stats.totalIn,
+        tokensOut: stats.totalOut,
+        turnUsage: stats.turnUsage,
+        cost: parentTurnCost > 0 ? parentTurnCost : void 0
       });
       await finalizeSession("completed");
       await hooks.callHook("agent:done", finalStats);
@@ -3014,7 +3041,14 @@ ${buildSearchableCatalog(disclosure.lazyEntries, { discoveryToolName })}`;
       if (abortController.signal.aborted) {
         session?.abortRun(runId);
         await finalizeSession("aborted");
-        const stats = { totalIn: 0, totalOut: 0, turns: 0, elapsed: 0 };
+        const stats = {
+          totalIn: 0,
+          totalOut: 0,
+          totalCacheRead: 0,
+          totalCacheCreation: 0,
+          turns: 0,
+          elapsed: 0
+        };
         await hooks.callHook("agent:done", stats);
         return stats;
       }
@@ -3277,6 +3311,8 @@ function createSpawnTool(options = {}) {
   const localStats = {
     totalIn: 0,
     totalOut: 0,
+    totalCacheRead: 0,
+    totalCacheCreation: 0,
     turns: 0,
     elapsed: 0
   };
@@ -3363,16 +3399,17 @@ function createSpawnTool(options = {}) {
         });
         try {
           finalStats = await raceWithTimeout(runPromise, options.timeoutMs);
+          const treeTurns = flattenTurns(finalStats).length;
           if (ctx.signal.aborted) {
             childRunStatus = "aborted";
             result = [
-              `[sub-agent ${id}] Aborted after ${finalStats.turns} turns (${finalStats.elapsed}ms)`,
+              `[sub-agent ${id}] Aborted after ${treeTurns} turns (${finalStats.elapsed}ms)`,
               `Tokens: ${finalStats.totalIn} in / ${finalStats.totalOut} out`
             ].join("\n");
           } else {
             const response = extractText(agent.turns.at(-1));
             result = [
-              `[sub-agent ${id}] Completed in ${finalStats.turns} turns (${finalStats.elapsed}ms)`,
+              `[sub-agent ${id}] Completed in ${treeTurns} turns (${finalStats.elapsed}ms)`,
               `Tokens: ${finalStats.totalIn} in / ${finalStats.totalOut} out`,
               "",
               response || "(no text response)"
@@ -3385,13 +3422,27 @@ function createSpawnTool(options = {}) {
             try {
               finalStats = await runPromise;
             } catch {
-              finalStats = { totalIn: 0, totalOut: 0, turns: 0, elapsed: err.timeoutMs };
+              finalStats = {
+                totalIn: 0,
+                totalOut: 0,
+                totalCacheRead: 0,
+                totalCacheCreation: 0,
+                turns: 0,
+                elapsed: err.timeoutMs
+              };
             }
             result = `[sub-agent ${id}] Timed out after ${err.timeoutMs}ms`;
           } else {
             const error = err instanceof Error ? err : new Error(String(err));
             childRunStatus = "error";
-            finalStats = { totalIn: 0, totalOut: 0, turns: 0, elapsed: 0 };
+            finalStats = {
+              totalIn: 0,
+              totalOut: 0,
+              totalCacheRead: 0,
+              totalCacheCreation: 0,
+              turns: 0,
+              elapsed: 0
+            };
             result = `[sub-agent ${id}] Error: ${error.message}`;
             await ctx.hooks.callHook("spawn:error", { id, task, depth: childDepth, error });
           }
@@ -3405,6 +3456,8 @@ function createSpawnTool(options = {}) {
         if (finalStats) {
           localStats.totalIn += finalStats.totalIn;
           localStats.totalOut += finalStats.totalOut;
+          localStats.totalCacheRead += finalStats.totalCacheRead;
+          localStats.totalCacheCreation += finalStats.totalCacheCreation;
           localStats.turns += finalStats.turns;
           localStats.elapsed += finalStats.elapsed;
         }

package/dist/{chunk-WE4C6AQE.js → chunk-64LLNY7F.js}

@@ -6,7 +6,7 @@ import {
   readFile,
   shell,
   writeFile
-} from "./chunk-VTLEPYND.js";
+} from "./chunk-4LPBN547.js";
 
 // src/presets/basic.ts
 var basicTools = { shell, readFile, writeFile, listFiles, edit, multiEdit };

package/dist/chunk-IC7FT4OD.js

@@ -0,0 +1,37 @@
+// src/stats.ts
+function flattenTurns(stats) {
+  const out = [];
+  collectTurns(stats, out);
+  return out;
+}
+function collectTurns(stats, out) {
+  if (stats.turnUsage)
+    out.push(...stats.turnUsage);
+  if (stats.children) {
+    for (const child of stats.children)
+      collectTurns(child.stats, out);
+  }
+}
+function statsByModel(stats) {
+  const out = /* @__PURE__ */ new Map();
+  for (const turn of flattenTurns(stats)) {
+    const key = turn.modelId ?? "(unknown)";
+    let entry = out.get(key);
+    if (!entry) {
+      entry = { input: 0, output: 0, cost: 0, cacheRead: 0, cacheCreation: 0, turns: 0 };
+      out.set(key, entry);
+    }
+    entry.input += turn.input;
+    entry.output += turn.output;
+    entry.cost += turn.cost ?? 0;
+    entry.cacheRead += turn.cacheRead ?? 0;
+    entry.cacheCreation += turn.cacheCreation ?? 0;
+    entry.turns += 1;
+  }
+  return out;
+}
+
+export {
+  flattenTurns,
+  statsByModel
+};

package/dist/contexts.d.ts

@@ -1,6 +1,6 @@
-import { S as SpawnConfig, b as ExecutionContext } from './types-vA1a_ZX7.js';
-export { C as ContextCapabilities, a as ContextType, E as ExecResult, c as ExecutionHandle } from './types-vA1a_ZX7.js';
-export { S as SandboxProvider, c as createSandboxContext } from './sandbox-CLghrTLi.js';
+import { S as SpawnConfig, a as ExecutionContext } from './types-Bai5rKpa.js';
+export { C as ContextCapabilities, b as ContextType, E as ExecResult, c as ExecutionHandle } from './types-Bai5rKpa.js';
+export { S as SandboxProvider, c as createSandboxContext } from './sandbox-D7v6Wy62.js';
 
 /**
  * Docker execution context.

package/dist/index.d.ts

@@ -1,12 +1,13 @@
-import { d as AgentHooks } from './agent-CMjWCUPr.js';
-export { ab as ActivationVia, ac as ActiveSkill, A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, ad as DeactivationReason, ae as FileMapAdapter, af as FileMapStoreOptions, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, ag as OpenAICompatAuthHeader, ah as OpenAICompatHttpError, ai as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, aj as SkillActivationState, ak as SkillActivationStateOptions, J as SkillConfig, al as SkillDiagnostic, K as SkillResource, am as SkillSource, L as SkillsConfig, N as SpawnHookContext, Q as StreamCallbacks, T as StreamHookContext, U as StreamOptions, V as ThinkingLevel, W as ToolCall, X as ToolContext, Y as ToolDef, Z as ToolExecutionMode, _ as ToolHookContext, $ as ToolMap, a0 as ToolResult, a1 as ToolResultContent, a2 as ToolResultImageContent, a3 as ToolResultTextContent, a4 as ToolSpec, a5 as TurnFinishReason, a6 as TurnResult, a7 as TurnUsage, an as anthropic, ao as autoDetectAndConvert, ap as cerebras, aq as classifyOpenAICompatError, ar as connectMcpServers, as as createAgent, at as createFileMapStore, au as createMemoryStore, av as createRemoteStore, aw as createSession, ax as createSkillActivationState, ay as fromAnthropic, az as fromOpenAI, aA as loadSession, aB as mapOAIFinishReason, a8 as matchesContextExceeded, aC as normalizeMcpBlocks, aD as normalizeMcpServers, aE as openai, aF as openaiCompat, aG as openrouter, aH as resultToString, aI as toAnthropic, aJ as toOpenAI, aK as toTypedError, a9 as toolOutputByteLength, aa as toolResultToText } from './agent-CMjWCUPr.js';
+import { A as AgentHooks } from './agent-BAHrGtqu.js';
+export { a as ActivationVia, b as ActiveSkill, c as Agent, d as AgentAbortedError, e as AgentBehavior, f as AgentContextExceededError, g as AgentOptions, h as AgentProviderError, i as AgentRunOptions, j as AgentStats, k as AgentToolNotAllowedError, l as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, m as CerebrasParams, n as ClassifiedError, o as ClassifiedErrorKind, p as CreateSessionOptions, D as DeactivationReason, F as FileMapAdapter, q as FileMapStoreOptions, M as McpConnection, r as McpServerConfig, s as McpToolHookContext, O as OAuthRefreshHookContext, t as OpenAICompatAuthHeader, u as OpenAICompatHttpError, v as OpenAICompatParams, w as OpenAIParams, x as OpenRouterParams, P as PromptDocumentPart, y as PromptImagePart, z as PromptPart, B as PromptTextPart, E as Provider, G as ProviderCapabilities, R as RemoteStoreOptions, H as RunHookMap, I as Session, J as SessionContentBlock, K as SessionData, L as SessionEndStatus, N as SessionHookContext, Q as SessionMessage, T as SessionRun, S as SessionStore, U as SessionTurn, V as SkillActivationState, W as SkillActivationStateOptions, X as SkillConfig, Y as SkillDiagnostic, Z as SkillResource, _ as SkillSource, $ as SkillsConfig, a0 as SpawnHookContext, a1 as StreamCallbacks, a2 as StreamHookContext, a3 as StreamOptions, a4 as ThinkingLevel, a5 as ToolCall, a6 as ToolContext, a7 as ToolDef, a8 as ToolExecutionMode, a9 as ToolHookContext, aa as ToolMap, ab as ToolResult, ac as ToolResultContent, ad as ToolResultImageContent, ae as ToolResultTextContent, af as ToolSpec, ag as TurnFinishReason, ah as TurnResult, ai as TurnUsage, aj as anthropic, ak as autoDetectAndConvert, al as cerebras, am as classifyOpenAICompatError, an as connectMcpServers, ao as createAgent, ap as createFileMapStore, aq as createMemoryStore, ar as createRemoteStore, as as createSession, at as createSkillActivationState, au as fromAnthropic, av as fromOpenAI, aw as loadSession, ax as mapOAIFinishReason, ay as matchesContextExceeded, az as normalizeMcpBlocks, aA as normalizeMcpServers, aB as openai, aC as openaiCompat, aD as openrouter, aE as resultToString, aF as toAnthropic, aG as toOpenAI, aH as toTypedError, aI as toolOutputByteLength, aJ as toolResultToText } from './agent-BAHrGtqu.js';
 export { createDockerContext, createProcessContext } from './contexts.js';
-export { S as SandboxProvider, c as createSandboxContext } from './sandbox-CLghrTLi.js';
-export { C as ContextCapabilities, a as ContextType, E as ExecResult, b as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-vA1a_ZX7.js';
+export { S as SandboxProvider, c as createSandboxContext } from './sandbox-D7v6Wy62.js';
+export { C as ContextCapabilities, b as ContextType, E as ExecResult, a as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-Bai5rKpa.js';
 export { Preset, basic, basicTools, definePreset } from './presets.js';
 export { IMPLICITLY_ALLOWED_SKILL_TOOLS, SkillValidationIssue, SkillValidationResult, SourcedScanPath, buildCatalog, defineSkill, discoverSkills, installAllowedToolsGate, interpolateShellCommands, isToolAllowedByUnion, matchesAllowedTool, parseAllowedToolPattern, parseSkillFile, resolveSkills, validateResourcePath, validateSkillForWrite, validateSkillName, writeSkillToDisk, writeSkillsToDisk } from './skills.js';
-export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-6oJKUjk_.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-BWV_pCdO.js';
+export { ModelUsage, flattenTurns, statsByModel } from './types.js';
+export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-DwZrNmcw.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-Pm--dQEU.js';
 import { Hookable } from 'hookable';
 import '@modelcontextprotocol/sdk/client/index.js';
 

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   basicTools,
   basic_default,
   definePreset
-} from "./chunk-WE4C6AQE.js";
+} from "./chunk-64LLNY7F.js";
 import {
   createAgent,
   createInteractionTool,
@@ -24,7 +24,7 @@ import {
   grep,
   multiEdit,
   validateToolArgs
-} from "./chunk-VTLEPYND.js";
+} from "./chunk-4LPBN547.js";
 import {
   IMPLICITLY_ALLOWED_SKILL_TOOLS,
   buildCatalog,
@@ -43,6 +43,10 @@ import {
   writeSkillToDisk,
   writeSkillsToDisk
 } from "./chunk-6STZTA4N.js";
+import {
+  flattenTurns,
+  statsByModel
+} from "./chunk-IC7FT4OD.js";
 import {
   createDockerContext,
   createProcessContext,
@@ -233,6 +237,7 @@ export {
   defineSkill,
   discoverSkills,
   edit,
+  flattenTurns,
   fromAnthropic,
   fromOpenAI,
   glob,
@@ -254,6 +259,7 @@ export {
   parseSkillFile,
   resolveSkills,
   resultToString,
+  statsByModel,
   toAnthropic,
   toOpenAI,
   toTypedError,

package/dist/mcp.d.ts

@@ -1,4 +1,4 @@
 import '@modelcontextprotocol/sdk/client/index.js';
 import 'hookable';
-export { M as McpConnection, p as McpServerConfig, ar as connectMcpServers, aC as normalizeMcpBlocks, aD as normalizeMcpServers, aH as resultToString } from './agent-CMjWCUPr.js';
-import './types-vA1a_ZX7.js';
+export { M as McpConnection, r as McpServerConfig, an as connectMcpServers, az as normalizeMcpBlocks, aA as normalizeMcpServers, aE as resultToString } from './agent-BAHrGtqu.js';
+import './types-Bai5rKpa.js';

package/dist/presets.d.ts

@@ -1,6 +1,6 @@
-import { Y as ToolDef, e as AgentOptions } from './agent-CMjWCUPr.js';
+import { a7 as ToolDef, g as AgentOptions } from './agent-BAHrGtqu.js';
 import 'hookable';
-import './types-vA1a_ZX7.js';
+import './types-Bai5rKpa.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 
 /**

package/dist/presets.js

@@ -2,9 +2,10 @@ import {
   basicTools,
   basic_default,
   definePreset
-} from "./chunk-WE4C6AQE.js";
-import "./chunk-VTLEPYND.js";
+} from "./chunk-64LLNY7F.js";
+import "./chunk-4LPBN547.js";
 import "./chunk-6STZTA4N.js";
+import "./chunk-IC7FT4OD.js";
 import "./chunk-UD25QF3H.js";
 import "./chunk-7GQ7P6DM.js";
 import "./chunk-JH6IAAFA.js";

package/dist/providers.d.ts

@@ -1,4 +1,4 @@
-export { j as AnthropicParams, k as CerebrasParams, ag as OpenAICompatAuthHeader, ah as OpenAICompatHttpError, ai as OpenAICompatParams, r as OpenAIParams, s as OpenRouterParams, w as Provider, x as ProviderCapabilities, Q as StreamCallbacks, U as StreamOptions, W as ToolCall, a0 as ToolResult, a4 as ToolSpec, a6 as TurnResult, an as anthropic, ap as cerebras, aq as classifyOpenAICompatError, aB as mapOAIFinishReason, aE as openai, aF as openaiCompat, aG as openrouter } from './agent-CMjWCUPr.js';
+export { l as AnthropicParams, m as CerebrasParams, t as OpenAICompatAuthHeader, u as OpenAICompatHttpError, v as OpenAICompatParams, w as OpenAIParams, x as OpenRouterParams, E as Provider, G as ProviderCapabilities, a1 as StreamCallbacks, a3 as StreamOptions, a5 as ToolCall, ab as ToolResult, af as ToolSpec, ah as TurnResult, aj as anthropic, al as cerebras, am as classifyOpenAICompatError, ax as mapOAIFinishReason, aB as openai, aC as openaiCompat, aD as openrouter } from './agent-BAHrGtqu.js';
 import 'hookable';
-import './types-vA1a_ZX7.js';
+import './types-Bai5rKpa.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/{sandbox-CLghrTLi.d.ts → sandbox-D7v6Wy62.d.ts}

@@ -1,4 +1,4 @@
-import { S as SpawnConfig, E as ExecResult, b as ExecutionContext } from './types-vA1a_ZX7.js';
+import { S as SpawnConfig, E as ExecResult, a as ExecutionContext } from './types-Bai5rKpa.js';
 
 /**
  * Remote sandbox execution context.

package/dist/session/sqlite.d.ts

@@ -1,6 +1,6 @@
-import { H as SessionStore } from '../agent-CMjWCUPr.js';
+import { S as SessionStore } from '../agent-BAHrGtqu.js';
 import 'hookable';
-import '../types-vA1a_ZX7.js';
+import '../types-Bai5rKpa.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 
 /**

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-export { o as CreateSessionOptions, ae as FileMapAdapter, af as FileMapStoreOptions, R as RemoteStoreOptions, S as Session, z as SessionContentBlock, B as SessionData, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, ao as autoDetectAndConvert, at as createFileMapStore, au as createMemoryStore, av as createRemoteStore, aw as createSession, ay as fromAnthropic, az as fromOpenAI, aA as loadSession, aI as toAnthropic, aJ as toOpenAI } from './agent-CMjWCUPr.js';
+export { p as CreateSessionOptions, F as FileMapAdapter, q as FileMapStoreOptions, R as RemoteStoreOptions, I as Session, J as SessionContentBlock, K as SessionData, Q as SessionMessage, T as SessionRun, S as SessionStore, U as SessionTurn, ak as autoDetectAndConvert, ap as createFileMapStore, aq as createMemoryStore, ar as createRemoteStore, as as createSession, au as fromAnthropic, av as fromOpenAI, aw as loadSession, aF as toAnthropic, aG as toOpenAI } from './agent-BAHrGtqu.js';
 import 'hookable';
-import './types-vA1a_ZX7.js';
+import './types-Bai5rKpa.js';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/{skills-use-6oJKUjk_.d.ts → skills-use-DwZrNmcw.d.ts}

@@ -1,4 +1,4 @@
-import { Y as ToolDef, J as SkillConfig, aj as SkillActivationState, d as AgentHooks } from './agent-CMjWCUPr.js';
+import { a7 as ToolDef, X as SkillConfig, V as SkillActivationState, A as AgentHooks } from './agent-BAHrGtqu.js';
 import { Hookable } from 'hookable';
 
 /**

package/dist/skills.d.ts

@@ -1,7 +1,7 @@
-import { d as AgentHooks, aj as SkillActivationState, J as SkillConfig, am as SkillSource, al as SkillDiagnostic, L as SkillsConfig } from './agent-CMjWCUPr.js';
-export { ab as ActivationVia, ac as ActiveSkill, ad as DeactivationReason, ak as SkillActivationStateOptions, K as SkillResource, ax as createSkillActivationState } from './agent-CMjWCUPr.js';
+import { A as AgentHooks, V as SkillActivationState, X as SkillConfig, _ as SkillSource, Y as SkillDiagnostic, $ as SkillsConfig } from './agent-BAHrGtqu.js';
+export { a as ActivationVia, b as ActiveSkill, D as DeactivationReason, W as SkillActivationStateOptions, Z as SkillResource, at as createSkillActivationState } from './agent-BAHrGtqu.js';
 import { Hookable } from 'hookable';
-import { b as ExecutionContext, c as ExecutionHandle } from './types-vA1a_ZX7.js';
+import { a as ExecutionContext, c as ExecutionHandle } from './types-Bai5rKpa.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 
 /**

package/dist/tools.d.ts

@@ -1,10 +1,10 @@
-export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-6oJKUjk_.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-BWV_pCdO.js';
-import { Y as ToolDef } from './agent-CMjWCUPr.js';
-export { X as ToolContext, $ as ToolMap } from './agent-CMjWCUPr.js';
+export { S as SkillsReadToolOptions, a as SkillsRunScriptToolOptions, b as SkillsUseToolOptions, c as createSkillsReadTool, d as createSkillsRunScriptTool, e as createSkillsUseTool, f as edit, g as glob, h as grep, m as multiEdit } from './skills-use-DwZrNmcw.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult, c as createInteractionTool, b as createSpawnTool, v as validateToolArgs } from './validation-Pm--dQEU.js';
+import { a7 as ToolDef } from './agent-BAHrGtqu.js';
+export { a6 as ToolContext, aa as ToolMap } from './agent-BAHrGtqu.js';
 import 'hookable';
 import './presets.js';
-import './types-vA1a_ZX7.js';
+import './types-Bai5rKpa.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 
 declare const listFiles: ToolDef;

package/dist/tools.js

@@ -14,8 +14,9 @@ import {
   shell,
   validateToolArgs,
   writeFile
-} from "./chunk-VTLEPYND.js";
+} from "./chunk-4LPBN547.js";
 import "./chunk-6STZTA4N.js";
+import "./chunk-IC7FT4OD.js";
 import "./chunk-UD25QF3H.js";
 import "./chunk-7GQ7P6DM.js";
 import "./chunk-JH6IAAFA.js";

package/dist/{types-vA1a_ZX7.d.ts → types-Bai5rKpa.d.ts}

@@ -86,4 +86,4 @@ interface ExecutionContext {
     destroy: (handle: ExecutionHandle) => Promise<void>;
 }
 
-export type { ContextCapabilities as C, ExecResult as E, SpawnConfig as S, ContextType as a, ExecutionContext as b, ExecutionHandle as c };
+export type { ContextCapabilities as C, ExecResult as E, SpawnConfig as S, ExecutionContext as a, ContextType as b, ExecutionHandle as c };

package/dist/types.d.ts

@@ -1,7 +1,55 @@
-export { A as Agent, a as AgentAbortedError, b as AgentBehavior, c as AgentContextExceededError, d as AgentHooks, e as AgentOptions, f as AgentProviderError, g as AgentRunOptions, h as AgentStats, i as AgentToolNotAllowedError, j as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, k as CerebrasParams, l as ChildRunStats, m as ClassifiedError, n as ClassifiedErrorKind, o as CreateSessionOptions, M as McpConnection, p as McpServerConfig, q as McpToolHookContext, O as OAuthRefreshHookContext, r as OpenAIParams, s as OpenRouterParams, P as PromptDocumentPart, t as PromptImagePart, u as PromptPart, v as PromptTextPart, w as Provider, x as ProviderCapabilities, R as RemoteStoreOptions, y as RunHookMap, S as Session, z as SessionContentBlock, B as SessionData, D as SessionEndStatus, E as SessionHookContext, F as SessionMessage, G as SessionRun, H as SessionStore, I as SessionTurn, J as SkillConfig, K as SkillResource, L as SkillsConfig, N as SpawnHookContext, Q as StreamCallbacks, T as StreamHookContext, U as StreamOptions, V as ThinkingLevel, W as ToolCall, X as ToolContext, Y as ToolDef, Z as ToolExecutionMode, _ as ToolHookContext, $ as ToolMap, a0 as ToolResult, a1 as ToolResultContent, a2 as ToolResultImageContent, a3 as ToolResultTextContent, a4 as ToolSpec, a5 as TurnFinishReason, a6 as TurnResult, a7 as TurnUsage, a8 as matchesContextExceeded, a9 as toolOutputByteLength, aa as toolResultToText } from './agent-CMjWCUPr.js';
-export { C as ContextCapabilities, a as ContextType, E as ExecResult, b as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-vA1a_ZX7.js';
-export { S as SandboxProvider } from './sandbox-CLghrTLi.js';
+import { j as AgentStats, ai as TurnUsage } from './agent-BAHrGtqu.js';
+export { c as Agent, d as AgentAbortedError, e as AgentBehavior, f as AgentContextExceededError, A as AgentHooks, g as AgentOptions, h as AgentProviderError, i as AgentRunOptions, k as AgentToolNotAllowedError, l as AnthropicParams, C as CONTEXT_EXCEEDED_MESSAGE_PATTERNS, m as CerebrasParams, aK as ChildRunStats, n as ClassifiedError, o as ClassifiedErrorKind, p as CreateSessionOptions, M as McpConnection, r as McpServerConfig, s as McpToolHookContext, O as OAuthRefreshHookContext, w as OpenAIParams, x as OpenRouterParams, P as PromptDocumentPart, y as PromptImagePart, z as PromptPart, B as PromptTextPart, E as Provider, G as ProviderCapabilities, R as RemoteStoreOptions, H as RunHookMap, I as Session, J as SessionContentBlock, K as SessionData, L as SessionEndStatus, N as SessionHookContext, Q as SessionMessage, T as SessionRun, S as SessionStore, U as SessionTurn, X as SkillConfig, Z as SkillResource, $ as SkillsConfig, a0 as SpawnHookContext, a1 as StreamCallbacks, a2 as StreamHookContext, a3 as StreamOptions, a4 as ThinkingLevel, a5 as ToolCall, a6 as ToolContext, a7 as ToolDef, a8 as ToolExecutionMode, a9 as ToolHookContext, aa as ToolMap, ab as ToolResult, ac as ToolResultContent, ad as ToolResultImageContent, ae as ToolResultTextContent, af as ToolSpec, ag as TurnFinishReason, ah as TurnResult, ay as matchesContextExceeded, aI as toolOutputByteLength, aJ as toolResultToText } from './agent-BAHrGtqu.js';
+export { C as ContextCapabilities, b as ContextType, E as ExecResult, a as ExecutionContext, c as ExecutionHandle, S as SpawnConfig } from './types-Bai5rKpa.js';
+export { S as SandboxProvider } from './sandbox-D7v6Wy62.js';
 export { Preset } from './presets.js';
-export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult } from './validation-BWV_pCdO.js';
+export { C as ChildAgent, I as InteractionToolOptions, S as SpawnToolOptions, a as SpawnToolState, V as ValidationResult } from './validation-Pm--dQEU.js';
 import 'hookable';
 import '@modelcontextprotocol/sdk/client/index.js';
+
+/**
+ * Pure derivations over `AgentStats`.
+ *
+ * Both helpers are tree-shakeable — import only what you need. They never
+ * touch agent state, never do I/O, and always operate on the recursive
+ * `AgentStats` tree returned by `agent.run()`.
+ */
+
+/**
+ * Per-model usage rollup produced by {@link statsByModel}.
+ *
+ * `turns` counts the number of `TurnUsage` entries attributed to the model
+ * across the whole tree (parent loop + every recursively-spawned child).
+ * Cache and cost numbers are summed from the same set of turns.
+ */
+interface ModelUsage {
+    input: number;
+    output: number;
+    cost: number;
+    cacheRead: number;
+    cacheCreation: number;
+    turns: number;
+}
+/**
+ * Depth-first walk over the stats tree, returning every `TurnUsage` entry
+ * — parent loop first, then each child subtree in completion order.
+ *
+ * Closes the cache-token aggregation gap: `TurnUsage.cacheRead` /
+ * `cacheCreation` live only on per-turn entries, and the top-level
+ * `AgentStats` deliberately doesn't carry cumulative forms (one source of
+ * truth, no risk of drift). Anything that needs a tree-wide sum walks
+ * through this.
+ */
+declare function flattenTurns(stats: AgentStats): TurnUsage[];
+/**
+ * Group cumulative usage by `TurnUsage.modelId`. Each entry sums the input,
+ * output, cache, cost, and turn-count across every turn the tree attributed
+ * to that model — naturally handling cross-model runs (vision-fallback,
+ * model-shifted subagents, mixed-provider workflows).
+ *
+ * Turns missing `modelId` (mock providers, providers that don't echo a model
+ * id) are bucketed under the literal string `'(unknown)'`.
+ */
+declare function statsByModel(stats: AgentStats): Map<string, ModelUsage>;
+
+export { AgentStats, type ModelUsage, TurnUsage, flattenTurns, statsByModel };

package/dist/types.js

@@ -1,3 +1,7 @@
+import {
+  flattenTurns,
+  statsByModel
+} from "./chunk-IC7FT4OD.js";
 import {
   toolOutputByteLength,
   toolResultToText
@@ -16,7 +20,9 @@ export {
   AgentProviderError,
   AgentToolNotAllowedError,
   CONTEXT_EXCEEDED_MESSAGE_PATTERNS,
+  flattenTurns,
   matchesContextExceeded,
+  statsByModel,
   toolOutputByteLength,
   toolResultToText
 };

package/dist/{validation-BWV_pCdO.d.ts → validation-Pm--dQEU.d.ts}

@@ -1,4 +1,4 @@
-import { X as ToolContext, Y as ToolDef, h as AgentStats, l as ChildRunStats } from './agent-CMjWCUPr.js';
+import { a6 as ToolContext, a7 as ToolDef, j as AgentStats, aK as ChildRunStats } from './agent-BAHrGtqu.js';
 import { Preset } from './presets.js';
 
 /**
@@ -84,7 +84,17 @@ interface ChildAgent {
 interface SpawnToolState {
     /** Currently running children. */
     readonly children: ReadonlyMap<string, ChildAgent>;
-    /** Aggregated stats from all completed children (returns a copy). */
+    /**
+     * Cumulative stats across every completed direct child of this spawn-tool
+     * instance (returns a copy). Each child's contribution is the cumulative
+     * `AgentStats` returned by its `agent.run()` — so
+     * `totalIn`/`totalOut`/`totalCacheRead`/`totalCacheCreation` cover the
+     * entire subtree (children + grandchildren + …), while `turns` and
+     * `elapsed` stay parent-loop-only per child and are summed across direct
+     * children. `elapsed` over-counts when children ran in parallel.
+     *
+     * Lives across multiple parent runs that share this instance.
+     */
     readonly totalChildStats: Readonly<AgentStats>;
 }
 interface SpawnToolOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "3.4.1",
+  "version": "4.0.1",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,