agent-accelerator 0.5.9 → 0.6.5

package/src/agent/architecture.md

@@ -2,25 +2,29 @@
 
 The agent and everything that runs under it.
 
-| File | What it is | Used by |
-| :-- | :-- | :-- |
-| `agent.ts` | `Agent`: `run`/`stream`/`ask`, `steer`/`queue`/`interrupt`, persistence hooks, `resume()`/`interrupted()`, `usageReport()`, `fork()`, `toConfig()`/`fromConfig()`, the `workers` getter. | callers, workers, scheduler |
-| `loop.ts` | `runAgentLoop` / `streamAgentLoop`: per turn budget, pairing repair, file access, provider call, tool execution, repeat guard. Also `ensureToolPairing`, `accumulateUsage`. | `Agent` |
-| `context.ts` | `AgentContext`: the validated message list with checkpoint/rollback. | `Agent`, loops |
-| `delegation.ts` | Fixed workers (`agentToTool`, `buildAgentTools`), the live worker trace store, session-id helpers, budget helpers, `openWorkerTrace`/`workerMetadata`. | `Agent`, `workers.ts` |
-| `worker.ts` | Worker core: model/tool normalization, `buildDynamicWorkerConfig` (shared preset), `createLiveWorker`. | `Agent`, registry, scheduler |
-| `workers.ts` | `WorkerRegistry` (`agent.workers`): persistent multi-turn workers. | `Agent`, `subagents` tool |
-| `subagents-tool.ts` + `subagents.md` | The one model-facing `subagents` tool; the `.md` is its description. | `Agent` constructor |
-| `subagent.ts` | `SubAgent` class and `agentFromEnv` (thin, kept for compatibility). | callers |
-| `turns.ts` | Pure grouping of messages into finished turns (history cut for workers). | `workers.ts` |
-| `config-blocks.ts` | RSI blocks: only `model`, `instructions`, `tools` are editable; `allowedModels` check. | `Agent` |
+| File                | What it is                                                                                                                                                                                                                              | Used by                                |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |
+| `agent.ts`          | `Agent`: `run`/`stream`/`ask`, `steer`/`queue`/`interrupt`, persistence hooks, `resume()`/`interrupted()`, `usageReport()`, `fork()`, `toConfig()`/`fromConfig()`, the `workers` getter.                                                | callers, workers, scheduler            |
+| `loop.ts`           | `runAgentLoop` / `streamAgentLoop`: per turn budget, pairing repair, file access, provider call, tool execution, repeat guard. Also `ensureToolPairing`, `accumulateUsage`.                                                             | `Agent`                                |
+| `context.ts`        | `AgentContext`: the validated message list with checkpoint/rollback.                                                                                                                                                                    | `Agent`, loops                         |
+| `delegation.ts`     | Fixed workers (`agentToTool`, `buildAgentTools`), the live worker trace store, session-id helpers, budget helpers, `openWorkerTrace`/`workerMetadata`.                                                                                  | `Agent`, `workers.ts`                  |
+| `worker.ts`         | Worker core: model/tool normalization, `buildDynamicWorkerConfig` (shared preset), `createLiveWorker`.                                                                                                                                  | `Agent`, registry, scheduler           |
+| `workers.ts`        | `WorkerRegistry` (`agent.workers`): persistent multi-turn workers.                                                                                                                                                                      | `Agent`, `subagents` tool              |
+| `subagents-tool.ts` | The one model-facing `subagents` tool; its description is the `subagentsTool` prompt (`../prompts/subagents-tool.md`).                                                                                                                  | `Agent` constructor                    |
+| `subagent.ts`       | `SubAgent` class and `agentFromEnv` (thin, kept for compatibility).                                                                                                                                                                     | callers                                |
+| `turns.ts`          | Pure grouping of messages into finished turns (history cut for workers).                                                                                                                                                                | `workers.ts`                           |
+| `defaults.ts`       | `configure()` and the `AGENT_ACCEL_*` env vars: developer defaults for `usageLimit` and `dynamicSubagents.scheduledActionBudget`, per field (Agent config > `configure()` > env). SDK-built workers never take them (`isWorkerConfig`). | `Agent`, barrel                        |
+| `usage-limit.ts`    | `UsageLimit`: the chat-wide cap (`AgentConfig.usageLimit`). The root agent owns it, registry and fixed workers share it (`agent.chat`); every model turn adds to it and is checked against it.                                          | `Agent`, `workers.ts`, `delegation.ts` |
+| `config-blocks.ts`  | RSI blocks: only `model`, `instructions`, `tools` are editable; `allowedModels` check.                                                                                                                                                  | `Agent`                                |
 
 ## Invariants
+
 - `runAgentLoop` and `streamAgentLoop` duplicate their turn logic: every loop change goes into both.
 - An `Agent` runs one thing at a time; delegation forks a copy per call so parallel calls never queue.
 - A worker is a plain `Agent` with a parent link and presets. Never duplicate logic between Agent and worker.
 - A worker is never less constrained than its parent (`inheritableConfig()`); its children draw only from the tools it was granted.
 - Exactly-once worker calls rest on the call key (parent run mark id + tool call id) and `meta.last`.
 - Only results branded by `makeSubagentResult` have their usage metadata trusted.
+- A chat-wide cap (`usageLimit`) counts every model turn of the root and of all workers through one shared `UsageLimit`; its starting point is read once per process from the saved sessions. Scheduled workers never get it.
 - Each Agent records only its own model turns; never sum `AgentResponse.usage` for totals.
 - `reset()` clears the conversation (messages, run marks, the run's saved tool results) but never the spending totals.

package/src/agent/config-blocks.ts

@@ -22,25 +22,37 @@ export function modelKey(model: unknown): string | undefined {
 export function assertModelAllowed(allowed: unknown, model: string | undefined): void {
   if (allowed === undefined) return;
   if (!Array.isArray(allowed) || allowed.length === 0 || allowed.some((m) => typeof m !== "string" || !m.trim())) {
-    throw new ConfigError(`[Agent Accelerator] Invalid allowedModels ${JSON.stringify(allowed)}: expected a non-empty list of "provider/model" strings, or omit it to allow any model.`);
+    throw new ConfigError(
+      `[Agent Accelerator] Invalid allowedModels ${JSON.stringify(allowed)}: expected a non-empty list of "provider/model" strings, or omit it to allow any model.`
+    );
   }
   if (!model || !allowed.includes(model)) {
-    throw new ConfigError(`[Agent Accelerator] Model ${JSON.stringify(model ?? null)} is not in allowedModels. Allowed: ${allowed.map((m) => JSON.stringify(m)).join(", ")}.`);
+    throw new ConfigError(
+      `[Agent Accelerator] Model ${JSON.stringify(model ?? null)} is not in allowedModels. Allowed: ${allowed.map((m) => JSON.stringify(m)).join(", ")}.`
+    );
   }
 }
 
 // The editable part of an agent as plain JSON; in: the Agent's model, instructions and the developer's tool list (not the built-in delegation/scheduler tools), out: Agent.toConfig.
-export function toEditableConfig(model: unknown, instructions: string, tools: AgentConfig["tools"]): Required<EditableAgentConfig> {
+export function toEditableConfig(
+  model: unknown,
+  instructions: string,
+  tools: AgentConfig["tools"]
+): Required<EditableAgentConfig> {
   return { model: modelKey(model) ?? "", instructions, tools: Object.keys(normalizeToolMap(tools)) };
 }
 
 // Merges what an agent edited into the developer's config: only model/instructions/tools can change; tools are names picked from base.tools; the model is checked against allowedModels when the Agent is built; in: Agent.fromConfig args, out: the AgentConfig for `new Agent`.
 export function applyEditable(editable: EditableAgentConfig, base: AgentConfig): AgentConfig {
   if (!editable || typeof editable !== "object" || Array.isArray(editable)) {
-    throw new ConfigError(`[Agent Accelerator] Invalid editable config ${JSON.stringify(editable)}: expected an object like { model, instructions, tools } (see Agent.toConfig()).`);
+    throw new ConfigError(
+      `[Agent Accelerator] Invalid editable config ${JSON.stringify(editable)}: expected an object like { model, instructions, tools } (see Agent.toConfig()).`
+    );
   }
   const e = editable as Record<string, unknown>;
-  const ignored = Object.keys(e).filter((k) => !(EDITABLE_FIELDS as readonly string[]).includes(k) && e[k] !== undefined);
+  const ignored = Object.keys(e).filter(
+    (k) => !(EDITABLE_FIELDS as readonly string[]).includes(k) && e[k] !== undefined
+  );
   if (ignored.length > 0) {
     telemetryBus.emitWarning(
       "config.not_editable",
@@ -51,26 +63,41 @@ export function applyEditable(editable: EditableAgentConfig, base: AgentConfig):
   const out: AgentConfig = { ...base };
   if (e.model !== undefined) {
     const next = typeof e.model === "string" ? e.model.trim() : "";
-    if (!next) throw new ConfigError(`[Agent Accelerator] Invalid editable model ${JSON.stringify(e.model)}: expected a "provider/model" string.`);
+    if (!next)
+      throw new ConfigError(
+        `[Agent Accelerator] Invalid editable model ${JSON.stringify(e.model)}: expected a "provider/model" string.`
+      );
     // A model helper's key and base URL belong to its own provider: they are never sent to another one.
     const prev = base.model as { model?: unknown; apiKey?: string; baseUrl?: string } | string | undefined;
     const sameProvider = next.includes("/") && next.split("/")[0] === modelKey(prev)?.split("/")[0];
-    out.model = prev && typeof prev === "object" && typeof prev.model === "string"
-      ? { ...prev, model: next, ...(sameProvider ? {} : { apiKey: undefined, baseUrl: undefined }) }
-      : next;
+    out.model =
+      prev && typeof prev === "object" && typeof prev.model === "string"
+        ? { ...prev, model: next, ...(sameProvider ? {} : { apiKey: undefined, baseUrl: undefined }) }
+        : next;
   }
   if (e.instructions !== undefined) {
-    if (typeof e.instructions !== "string") throw new ConfigError(`[Agent Accelerator] Invalid editable instructions: expected a string, got ${typeof e.instructions}.`);
+    if (typeof e.instructions !== "string")
+      throw new ConfigError(
+        `[Agent Accelerator] Invalid editable instructions: expected a string, got ${typeof e.instructions}.`
+      );
     out.instructions = e.instructions;
   }
   if (e.tools !== undefined) {
     if (!Array.isArray(e.tools) || e.tools.some((n) => typeof n !== "string")) {
-      throw new ConfigError(`[Agent Accelerator] Invalid editable tools ${JSON.stringify(e.tools)}: expected a list of tool names from the developer's tool pool.`);
+      throw new ConfigError(
+        `[Agent Accelerator] Invalid editable tools ${JSON.stringify(e.tools)}: expected a list of tool names from the developer's tool pool.`
+      );
     }
     const pool = normalizeToolMap(base.tools);
     const unknown = (e.tools as string[]).filter((n) => !Object.hasOwn(pool, n));
     if (unknown.length > 0) {
-      throw new ConfigError(`[Agent Accelerator] Unknown tool ${unknown.map((n) => JSON.stringify(n)).join(", ")} in the editable config. Available: ${Object.keys(pool).map((n) => JSON.stringify(n)).join(", ") || "none"}.`);
+      throw new ConfigError(
+        `[Agent Accelerator] Unknown tool ${unknown.map((n) => JSON.stringify(n)).join(", ")} in the editable config. Available: ${
+          Object.keys(pool)
+            .map((n) => JSON.stringify(n))
+            .join(", ") || "none"
+        }.`
+      );
     }
     const picked: Record<string, ToolDefinition> = {};
     for (const n of e.tools as string[]) picked[n] = pool[n]!;

package/src/agent/context.ts

@@ -3,12 +3,13 @@ import type { ToolCallRecord, ToolResultRecord } from "../types/tool.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { clearSessionRouting } from "../providers.ts";
 import { clearInteractionChains } from "../providers/google.ts";
+import { ValidationError } from "../types/errors.ts";
 
 const USER_PART_TYPES = new Set(["text", "image", "audio", "video", "file"]);
 
 // Throws the AgentContext validation error with the SDK prefix; in: the add* validators, out: a thrown Error.
 function fail(message: string): never {
-  throw new Error(`[Agent Accelerator] AgentContext: ${message}`);
+  throw new ValidationError(`[Agent Accelerator] AgentContext: ${message}`);
 }
 
 /** Deep clone that preserves Uint8Array/ArrayBuffer media (structuredClone may be absent). */
@@ -142,6 +143,7 @@ export class AgentContext {
             isError: res.isError,
             ...(res.logFile ? { logFile: res.logFile } : {}),
             ...(res.stopped ? { stopped: true } : {}),
+            ...(res.parts && res.parts.length > 0 ? { parts: res.parts } : {}),
           },
         ],
       });
@@ -192,8 +194,12 @@ export class AgentContext {
     if (Array.isArray(cp?.messages)) this.messages = deepCloneValue(cp.messages);
     if (Array.isArray(cp?.signatures)) this.thoughtSignatures = [...cp.signatures];
     if (sessionId) {
-      try { clearInteractionChains(sessionId); } catch {}
-      try { clearSessionRouting(sessionId); } catch {}
+      try {
+        clearInteractionChains(sessionId);
+      } catch {}
+      try {
+        clearSessionRouting(sessionId);
+      } catch {}
     }
   }
 }

package/src/agent/defaults.ts

@@ -0,0 +1,88 @@
+/**
+ * Developer defaults for the spending caps, set in code (`configure()`) or through env vars, so one place can cap every
+ * agent of a program. Precedence, per field (`maxCostUsd`, `maxTotalTokens`): the Agent's own config, then `configure()`,
+ * then the env var, then no cap. Only agents YOU construct take defaults: the workers and scheduled runs the SDK builds
+ * itself never do (a chat worker joins its parent's cap; a scheduled run has its own).
+ */
+import { ConfigError } from "../types/errors.ts";
+import { getEnv } from "../utils/env.ts";
+import { checkUsageLimitConfig, type UsageLimitConfig } from "./usage-limit.ts";
+
+/** What `configure()` can set; every key is optional and has the same meaning as the Agent option of the same name. */
+export interface AgentDefaults {
+  /** Default for `AgentConfig.usageLimit` (the chat-wide cap). Env: `AGENT_ACCEL_USAGE_LIMIT_USD`, `AGENT_ACCEL_USAGE_LIMIT_TOKENS`. */
+  usageLimit?: UsageLimitConfig;
+  /** Default for `dynamicSubagents.scheduledActionBudget`. Env: `AGENT_ACCEL_SCHEDULED_BUDGET_USD`, `AGENT_ACCEL_SCHEDULED_BUDGET_TOKENS`. */
+  scheduledActionBudget?: UsageLimitConfig;
+}
+
+type CapName = keyof AgentDefaults;
+
+const ENV: Record<CapName, { maxCostUsd: string; maxTotalTokens: string }> = {
+  usageLimit: { maxCostUsd: "AGENT_ACCEL_USAGE_LIMIT_USD", maxTotalTokens: "AGENT_ACCEL_USAGE_LIMIT_TOKENS" },
+  scheduledActionBudget: {
+    maxCostUsd: "AGENT_ACCEL_SCHEDULED_BUDGET_USD",
+    maxTotalTokens: "AGENT_ACCEL_SCHEDULED_BUDGET_TOKENS",
+  },
+};
+
+let configured: AgentDefaults = {};
+
+/**
+ * Sets developer defaults for the spending caps; call it once at startup, like `setHome()`. It REPLACES what an earlier
+ * call set (`configure({})` clears it). A key an Agent sets itself wins, field by field; env vars are the fallback.
+ * Throws a `ConfigError` for a value that is not a number above 0.
+ *
+ * @example `configure({ usageLimit: { maxCostUsd: 5 }, scheduledActionBudget: { maxCostUsd: 0.5 } });`
+ */
+export function configure(defaults: AgentDefaults = {}): void {
+  if (!defaults || typeof defaults !== "object" || Array.isArray(defaults)) {
+    throw new ConfigError("[Agent Accelerator] configure() expects an object like { usageLimit: { maxCostUsd: 5 } }.");
+  }
+  for (const key of Object.keys(defaults)) {
+    if (!(key in ENV)) {
+      throw new ConfigError(
+        `[Agent Accelerator] configure(): unknown setting "${key}" (known: ${Object.keys(ENV).join(", ")}).`
+      );
+    }
+    const value = (defaults as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    const problem = checkUsageLimitConfig(value);
+    if (problem) throw new ConfigError(`[Agent Accelerator] configure(): invalid ${key}: ${problem}.`);
+  }
+  configured = Object.fromEntries(
+    Object.entries(defaults)
+      .filter(([, v]) => v !== undefined)
+      .map(([k, v]) => [k, { ...(v as UsageLimitConfig) }])
+  ) as AgentDefaults;
+}
+
+// Reads one cap field from its env var: undefined when unset, a ConfigError naming the variable when it is not a number above 0; in: mergeCap, out: the value.
+function fromEnv(variable: string): number | undefined {
+  const raw = getEnv(variable);
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!(Number.isFinite(n) && n > 0)) {
+    throw new ConfigError(
+      `[Agent Accelerator] Invalid ${variable} ${JSON.stringify(raw)}: expected a number greater than 0.`
+    );
+  }
+  return n;
+}
+
+/** The cap an Agent uses: its own value, field by field over `configure()` over the env vars; undefined when nothing sets one. `withDefaults: false` ignores `configure()` and the env (SDK-built workers). */
+export function mergeCap(
+  name: CapName,
+  own: UsageLimitConfig | undefined,
+  withDefaults: boolean
+): UsageLimitConfig | undefined {
+  const base = withDefaults ? configured[name] : undefined;
+  const maxCostUsd = own?.maxCostUsd ?? base?.maxCostUsd ?? (withDefaults ? fromEnv(ENV[name].maxCostUsd) : undefined);
+  const maxTotalTokens =
+    own?.maxTotalTokens ?? base?.maxTotalTokens ?? (withDefaults ? fromEnv(ENV[name].maxTotalTokens) : undefined);
+  if (maxCostUsd === undefined && maxTotalTokens === undefined) return undefined;
+  return {
+    ...(maxCostUsd !== undefined ? { maxCostUsd } : {}),
+    ...(maxTotalTokens !== undefined ? { maxTotalTokens } : {}),
+  };
+}

package/src/agent/delegation.ts

@@ -15,6 +15,7 @@ import { nowMs } from "../utils/session.ts";
 import { newRunId } from "../utils/session.ts";
 import { newTurnId } from "../utils/session.ts";
 import { sanitizeToolName, createLiveWorker } from "./worker.ts";
+import type { UsageLimit } from "./usage-limit.ts";
 
 /** Builds a random child session id that fits the 64-char provider limit, embedding a hash of the parent when it must be cut; in: a parent id + tag from scheduled runs, out: the worker's session id. */
 export function createChildSessionId(parentId: string, tag: string): string {
@@ -61,7 +62,7 @@ export function createFixedChildSessionId(parentId: string, name: string): strin
     return `${parentId.slice(0, maxParent - 9)}-${parentHash}${suffix}`;
   }
   if (maxParent > 0) return parentId.slice(0, maxParent) + suffix;
-  return (`${parentId}-sub-${name}`).slice(0, 64);
+  return `${parentId}-sub-${name}`.slice(0, 64);
 }
 
 /**
@@ -225,7 +226,9 @@ function notifyTrace(trackingId: string): void {
   if (!listeners || listeners.size === 0) return;
   const snap = snapshotTrace(t);
   for (const fn of [...listeners]) {
-    try { fn(snap); } catch {}
+    try {
+      fn(snap);
+    } catch {}
   }
 }
 
@@ -280,15 +283,23 @@ export function subscribeToSubAgent(id: string, fn: (trace: SubAgentTrace) => vo
   }
   set.add(fn);
   const timer = setTimeout(() => {
-    try { subagentListeners.get(key)?.delete(fn); } catch {}
+    try {
+      subagentListeners.get(key)?.delete(fn);
+    } catch {}
   }, SUBAGENT_SUBSCRIBE_TTL_MS);
-  try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
+  try {
+    (timer as unknown as { unref?: () => void }).unref?.();
+  } catch {}
   let done = false;
   return () => {
     if (done) return;
     done = true;
-    try { clearTimeout(timer); } catch {}
-    try { subagentListeners.get(key)?.delete(fn); } catch {}
+    try {
+      clearTimeout(timer);
+    } catch {}
+    try {
+      subagentListeners.get(key)?.delete(fn);
+    } catch {}
   };
 }
 
@@ -334,7 +345,13 @@ export function openWorkerTrace(a: {
   role?: string;
   /** When given, the trace is also kept in this agent's own registry and saved with its session. */
   parent?: Agent;
-  emit?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+  emit?: (event: {
+    trackingId: string;
+    delta?: string;
+    thinkingDelta?: string;
+    partialText?: string;
+    partialThinking?: string;
+  }) => void;
 }): WorkerTraceHandle {
   const trackingId = createTrackingId();
   const displayId = `${a.name}-${trackingId}`;
@@ -360,9 +377,19 @@ export function openWorkerTrace(a: {
     trim: (t) => trimTraceSteps(t),
     touch: (id) => touchTrace(id),
     notify: (id) => notifyTrace(id),
-    ...(a.parent ? { persist: () => { try { a.parent!.persistNow(); } catch {} } } : {}),
+    ...(a.parent
+      ? {
+          persist: () => {
+            try {
+              a.parent!.persistNow();
+            } catch {}
+          },
+        }
+      : {}),
     emit: (ev) => {
-      try { a.emit?.(ev); } catch {}
+      try {
+        a.emit?.(ev);
+      } catch {}
     },
   });
   const settle = (): void => {
@@ -386,7 +413,11 @@ export function openWorkerTrace(a: {
         t.turns = result.turns ?? t.turns;
         t.text = result.text;
         if (result.usage) {
-          t.usage = { inputTokens: result.usage.inputTokens ?? 0, outputTokens: result.usage.outputTokens ?? 0, totalTokens: result.usage.totalTokens ?? 0 };
+          t.usage = {
+            inputTokens: result.usage.inputTokens ?? 0,
+            outputTokens: result.usage.outputTokens ?? 0,
+            totalTokens: result.usage.totalTokens ?? 0,
+          };
         }
       }
       settle();
@@ -492,7 +523,8 @@ function ensureBudgetState(parentAgent: Agent): BudgetState {
 function usageTokens(usage: unknown): number {
   const u = usage as { totalTokens?: unknown; inputTokens?: unknown; outputTokens?: unknown } | undefined;
   if (!u || typeof u !== "object") return 0;
-  if (typeof u.totalTokens === "number" && Number.isFinite(u.totalTokens)) return Math.max(0, Math.floor(u.totalTokens));
+  if (typeof u.totalTokens === "number" && Number.isFinite(u.totalTokens))
+    return Math.max(0, Math.floor(u.totalTokens));
   const inp = typeof u.inputTokens === "number" && Number.isFinite(u.inputTokens) ? u.inputTokens : 0;
   const out = typeof u.outputTokens === "number" && Number.isFinite(u.outputTokens) ? u.outputTokens : 0;
   return Math.max(0, Math.floor(inp + out));
@@ -532,10 +564,9 @@ export function checkBudget(
     );
   }
   if (budget.maxTotalTokens !== undefined && totalTokens > budget.maxTotalTokens) {
-    throw new BudgetExceededError(
-      `Token budget exceeded: ${totalTokens} > maxTotalTokens ${budget.maxTotalTokens}.`,
-      { context: { partial } }
-    );
+    throw new BudgetExceededError(`Token budget exceeded: ${totalTokens} > maxTotalTokens ${budget.maxTotalTokens}.`, {
+      context: { partial },
+    });
   }
   if (budget.maxCostUsd !== undefined && totalCostUsd > budget.maxCostUsd) {
     throw new BudgetExceededError(
@@ -601,9 +632,7 @@ export interface AgentAsToolTarget {
  *
  * @example `const researchTool = researcher.asTool("research");`
  */
-export function agentToTool(
-  input: Agent | AgentAsToolTarget
-): ToolDefinition {
+export function agentToTool(input: Agent | AgentAsToolTarget, opts?: { chat?: UsageLimit }): ToolDefinition {
   const agentInstance = "agent" in input ? input.agent : input;
   const rawName =
     ("name" in input && (input as any).name) ||
@@ -635,28 +664,56 @@ export function agentToTool(
         task,
         emit: (ev) => ctx?.onSubagentEvent?.(ev),
       });
-      const lineage = { name, displayId: live.displayId, sessionId: subSessionId, parentSessionId, task, runId: callRunId, turnId: callTurnId };
+      const lineage = {
+        name,
+        displayId: live.displayId,
+        sessionId: subSessionId,
+        parentSessionId,
+        task,
+        runId: callRunId,
+        turnId: callTurnId,
+      };
       try {
         // One isolated copy per call: the shared instance is single-flight, so
         // calling it directly would serialize (or steer) parallel tool calls.
         const worker: Agent =
-          typeof (agentInstance as Agent).fork === "function" ? agentInstance.fork(subSessionId, parentSessionId) : agentInstance;
-        const workerStream = worker.stream(task, { signal: ctx?.signal, sessionId: subSessionId, onTurn: live.onWorkerTurn } as any);
-        const detachWorkerListeners = live.attachToStream(workerStream as unknown as Parameters<typeof live.attachToStream>[0]);
+          typeof (agentInstance as Agent).fork === "function"
+            ? agentInstance.fork(subSessionId, parentSessionId)
+            : agentInstance;
+        if (worker !== agentInstance && opts?.chat) worker.chat = opts.chat; // this call counts into the parent chat's cap
+        const workerStream = worker.stream(task, {
+          signal: ctx?.signal,
+          sessionId: subSessionId,
+          onTurn: live.onWorkerTurn,
+        } as any);
+        const detachWorkerListeners = live.attachToStream(
+          workerStream as unknown as Parameters<typeof live.attachToStream>[0]
+        );
         let response: AgentResponse;
         try {
           response = await workerStream.result();
         } finally {
-          try { detachWorkerListeners(); } catch {}
+          try {
+            detachWorkerListeners();
+          } catch {}
           // The per-call session id is never reused: drop its provider chain/routing state.
           if (worker !== agentInstance) {
-            try { agentInstance.absorbUsage(worker.usageTotals); } catch {} // the template keeps what its copies spent
-            try { worker.reset(); } catch {}
+            try {
+              agentInstance.absorbUsage(worker.usageTotals);
+            } catch {} // the template keeps what its copies spent
+            try {
+              worker.reset();
+            } catch {}
           }
         }
         live.finish(response);
         return makeSubagentResult(response.text, [
-          workerMetadata({ ...lineage, durationMs: Math.max(0, nowMs() - startTime), result: response, steps: live.steps() }),
+          workerMetadata({
+            ...lineage,
+            durationMs: Math.max(0, nowMs() - startTime),
+            result: response,
+            steps: live.steps(),
+          }),
         ]);
       } catch (err: any) {
         const msg = err?.message || String(err);
@@ -675,13 +732,14 @@ export function agentToTool(
  * @example `const tools = buildAgentTools([researcher, reviewer]);`
  */
 export function buildAgentTools(
-  agents?: (Agent | AgentAsToolTarget)[]
+  agents?: (Agent | AgentAsToolTarget)[],
+  opts?: { chat?: UsageLimit }
 ): Record<string, ToolDefinition> {
   if (!agents || agents.length === 0) return {};
 
   const tools: Record<string, ToolDefinition> = {};
   for (const item of agents) {
-    const t = agentToTool(item);
+    const t = agentToTool(item, opts);
     if (t.name) {
       let finalName = t.name;
       let n = 1;