agent-accelerator 0.6.0 → 0.6.5

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 {
@@ -631,7 +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) ||
@@ -679,6 +680,7 @@ export function agentToTool(input: Agent | AgentAsToolTarget): ToolDefinition {
           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,
@@ -729,12 +731,15 @@ export function agentToTool(input: Agent | AgentAsToolTarget): ToolDefinition {
  *
  * @example `const tools = buildAgentTools([researcher, reviewer]);`
  */
-export function buildAgentTools(agents?: (Agent | AgentAsToolTarget)[]): Record<string, ToolDefinition> {
+export function buildAgentTools(
+  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;

package/src/agent/loop.ts

@@ -32,6 +32,7 @@ import { isSubagentResult, normalizeSubagentMetadata } from "../tools/subagent-r
 import { BudgetExceededError, TimeoutError } from "../types/errors.ts";
 import { applyCaptureRaw, type CaptureRawMode } from "../utils/raw-capture.ts";
 import { previewPrompt } from "../utils/session.ts";
+import { DEFAULT_PROMPTS, fillPrompt, type Prompts } from "../prompts/prompts.ts";
 import { noteProviderTurn, normalizeStructuredOutput, parseStructuredOutput } from "../providers.ts";
 
 /** One mid-session steer request buffered while a run is active. */
@@ -98,6 +99,8 @@ export interface AgentLoopConfig {
   steerInbox?: SteerEntry[];
   /** Called after steer entries are injected (streaming loops also push `steer_injected` events). */
   onSteerInjected?: (injectedPrompts: string[]) => void;
+  /** The SDK prompts for this run (`AgentConfig.prompts` resolved); the shipped ones when unset. */
+  prompts?: Prompts;
   /**
    * Canonical structured-output request (raw `AgentConfig.output`).
    * Normalized per turn for the provider wire; validated once at the end
@@ -111,7 +114,7 @@ export interface AgentLoopConfig {
  * Returns display previews for events/telemetry. Never throws: invalid
  * entries are skipped so one bad steer cannot fail the active turn.
  */
-function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[]): string[] {
+function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[], prompts: Prompts = DEFAULT_PROMPTS): string[] {
   if (!inbox || inbox.length === 0) return [];
   const injected: string[] = [];
   while (inbox.length > 0) {
@@ -121,7 +124,7 @@ function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[]): string[]
       const opts = entry.options;
       if (Array.isArray(prompt) && prompt.length === 0) continue;
       if (opts?.additionalContext) {
-        const prefix = `[Additional Context]\n${opts.additionalContext}\n\n`;
+        const prefix = `${fillPrompt(prompts.additionalContext, { context: opts.additionalContext })}\n\n`;
         if (typeof prompt === "string") prompt = prefix + prompt;
         else prompt = [{ type: "text", text: prefix } as ContentPart, ...prompt];
       }
@@ -157,7 +160,7 @@ function emitTurn(
 }
 
 /**
- * Per-turn `toolChoice`. `"none"` holds for the whole run; a forced choice
+ * Per-turn `toolChoice`. `"none"` and `"validated"` (which forces nothing) hold for the whole run; a forced choice
  * (`"required"` or a pinned function) applies to the FIRST model turn only:
  * forcing a tool call on every turn would keep the model calling tools until
  * `maxTurns`, so the run could never produce a final answer.
@@ -167,7 +170,7 @@ function toolChoiceForTurn(
   turn: number
 ): ProviderRequestOptions["toolChoice"] {
   if (choice === undefined || choice === "auto") return undefined;
-  if (choice === "none") return "none";
+  if (choice === "none" || choice === "validated") return choice;
   return turn === 1 ? choice : undefined;
 }
 
@@ -275,7 +278,7 @@ function warnMaxTurnsHit(agentName: string | undefined, maxTurns: number, pendin
  * - drops results whose id the model never issued.
  * Open-weight models that reuse one id for several calls keep one result per call.
  */
-export function ensureToolPairing(context: AgentContext): void {
+export function ensureToolPairing(context: AgentContext, prompts: Prompts = DEFAULT_PROMPTS): void {
   try {
     type ToolResultPart = Extract<ContentPart, { type: "tool_result" }>;
     const messages = context.messages;
@@ -316,7 +319,7 @@ export function ensureToolPairing(context: AgentContext): void {
                 type: "tool_result",
                 id: p.id,
                 name,
-                result: `Error: tool_call '${name}' (${p.id}) has no result because the run was interrupted before it completed (recovered by ensureToolPairing). It may have partially executed: check the tool trace before repeating side-effecting work.`,
+                result: fillPrompt(prompts.toolInterrupted, { tool: name, id: p.id }),
                 isError: true,
               },
             ],
@@ -472,6 +475,14 @@ export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec, serv
   }
 }
 
+// Adds the media token details of `source` into `target` (kept only when something was reported); in: accumulateUsage, out: target.inputDetails / outputDetails.
+function sumDetails(target: TokenUsage, source: TokenUsage, key: "inputDetails" | "outputDetails"): void {
+  const from = source[key] as Record<string, number | undefined> | undefined;
+  if (!from) return;
+  const into = ((target[key] as Record<string, number> | undefined) ??= {});
+  for (const [k, v] of Object.entries(from)) if (typeof v === "number") into[k] = (into[k] ?? 0) + v;
+}
+
 // ---------------------------------------------------------------------------
 // Canonical usage accumulation (pure w.r.t. source).
 // Invariants (see assertUsageInvariants in session/store.ts):
@@ -484,6 +495,7 @@ export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec, serv
 // This function never mutates `source`: the priced cost is cloned
 // into a local before folding into the target.
 // ---------------------------------------------------------------------------
+// Adds one turn's usage (and its priced cost) into a running total without touching the source; in: both loops per model turn and finished worker, out: the run's accumulatedUsage.
 export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec, serviceTier?: string): void {
   target.inputTokens += source.inputTokens || 0;
   target.outputTokens += source.outputTokens || 0;
@@ -492,6 +504,8 @@ export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: M
   target.cacheReadTokens = (target.cacheReadTokens ?? 0) + (source.cacheReadTokens ?? 0);
   target.cacheWriteTokens = (target.cacheWriteTokens ?? 0) + (source.cacheWriteTokens ?? 0);
   target.thinkingTokens = (target.thinkingTokens ?? 0) + (source.thinkingTokens ?? 0);
+  sumDetails(target, source, "inputDetails");
+  sumDetails(target, source, "outputDetails");
 
   // Canonical invariant (provider-agnostic): cache hits are a subset of
   // input. Some providers occasionally report cached > input on long chained
@@ -557,6 +571,7 @@ async function executeToolCallsWithRepeatGuard(options: {
   openToolLog?: ExecuteToolsOptions["openToolLog"];
   previousFingerprints: Set<string>;
   repeatCounts: Map<string, number>;
+  prompts?: Prompts;
   agentName?: string;
   signal?: AbortSignal;
   sessionId?: string;
@@ -590,7 +605,7 @@ async function executeToolCallsWithRepeatGuard(options: {
         { agentName: options.agentName, sessionId: options.sessionId },
         { reason: "repeat_blocked" }
       );
-      blocked.set(call.id, makeRepeatBlockedResult(call));
+      blocked.set(call.id, makeRepeatBlockedResult(call, options.prompts?.toolRepeatBlocked));
     } else {
       executable.push(call);
     }
@@ -610,6 +625,7 @@ async function executeToolCallsWithRepeatGuard(options: {
           onSubagentEvent: options.onSubagentEvent,
           onResult: options.onResult,
           openToolLog: options.openToolLog,
+          prompts: options.prompts,
         })
       : [];
   const byId = new Map<string, ToolResultRecord[]>();
@@ -693,6 +709,7 @@ async function finishInterruptedTools(
         sessionId: config.runOptions?.sessionId || config.options?.sessionId,
         onResult: config.onToolResult,
         openToolLog: config.openToolLog,
+        prompts: config.prompts,
       })
     : [];
   const ran = new Map(executed.map((r) => [r.id, r]));
@@ -776,7 +793,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       checkDeadline(startTime, limits.deadlineMs);
       config.enforceBudget?.();
       // Repair orphan tool pairs before every request.
-      ensureToolPairing(context);
+      ensureToolPairing(context, config.prompts);
       if (config.fileAccess?.roots) await enforceFileAccess(context.messages, config.fileAccess.roots);
       turns++;
 
@@ -880,7 +897,9 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       // inject them now. Tool turns still execute first (see below) so the
       // current action finishes before redirection.
       const noToolSteered =
-        !genResult.toolCalls || genResult.toolCalls.length === 0 ? drainSteerInbox(context, config.steerInbox) : [];
+        !genResult.toolCalls || genResult.toolCalls.length === 0
+          ? drainSteerInbox(context, config.steerInbox, config.prompts)
+          : [];
 
       // If no tool calls, generation is complete — unless steered, in which
       // case the injected message extends the SAME run (no new response).
@@ -918,6 +937,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
         sessionId: runOptions?.sessionId || options?.sessionId,
         onResult: config.onToolResult,
         openToolLog: config.openToolLog,
+        prompts: config.prompts,
       });
       const results = guarded.results;
       previousToolCallFingerprints = guarded.fingerprints;
@@ -964,7 +984,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       // Steer drain AFTER tool results so call/result pairs stay adjacent.
       // The next loop iteration sends the injected user message to the model
       // within the same run (same usage/turn budget).
-      const toolSteered = drainSteerInbox(context, config.steerInbox);
+      const toolSteered = drainSteerInbox(context, config.steerInbox, config.prompts);
       if (toolSteered.length > 0) {
         try {
           config.onSteerInjected?.(toolSteered);
@@ -1180,7 +1200,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         throwIfCancelled({ usage: accumulatedUsage, turns, text: lastResponse?.text });
         checkDeadline(streamStartTime, streamLimits.deadlineMs);
         config.enforceBudget?.();
-        ensureToolPairing(context);
+        ensureToolPairing(context, config.prompts);
         if (config.fileAccess?.roots) await enforceFileAccess(context.messages, config.fileAccess.roots);
         turns++;
 
@@ -1340,7 +1360,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
 
         const noToolSteered =
           !turnResponse.toolCalls || turnResponse.toolCalls.length === 0
-            ? drainSteerInbox(context, config.steerInbox)
+            ? drainSteerInbox(context, config.steerInbox, config.prompts)
             : [];
         if (!turnResponse.toolCalls || turnResponse.toolCalls.length === 0) {
           emitTurn(runOptions, { turns, text: turnResponse.text, thinking: turnResponse.thinking });
@@ -1388,6 +1408,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           sessionId: runOptions?.sessionId || options?.sessionId,
           onResult: config.onToolResult,
           openToolLog: config.openToolLog,
+          prompts: config.prompts,
           onSubagentEvent: (ev) => {
             try {
               outerStream.push({
@@ -1459,7 +1480,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           emitProgress(config);
           break;
         }
-        const toolSteered = drainSteerInbox(context, config.steerInbox);
+        const toolSteered = drainSteerInbox(context, config.steerInbox, config.prompts);
         if (toolSteered.length > 0) {
           for (const preview of toolSteered) {
             try {

package/src/agent/subagents-tool.ts

@@ -1,9 +1,8 @@
 /**
  * The model-facing `subagents` tool: one flat tool with a `command` field (`spawn | message | close | list`), a thin
- * wrapper over `agent.workers`. The tool manual lives in `subagents.md`, not in code. Results are plain text with one
+ * wrapper over `agent.workers`. The tool manual lives in `src/prompts/subagents-tool.md`, not in code. Results are plain text with one
  * header line naming the worker; the branded envelope under them carries usage and lineage to the loop.
  */
-import { readFileSync } from "node:fs";
 import { z } from "zod";
 import type { Agent } from "./agent.ts";
 import { tool } from "../tools/tool.ts";
@@ -11,20 +10,15 @@ import { makeSubagentResult } from "../tools/subagent-result.ts";
 import { ValidationError } from "../types/errors.ts";
 import type { ToolDefinition } from "../types/tool.ts";
 import type { WorkerReply } from "./workers.ts";
+import { fillPrompt, type Prompts } from "../prompts/prompts.ts";
 
 const COMMANDS = ["spawn", "message", "close", "list"] as const;
 
-let manual: string | undefined;
-/** Read on first use (not at import), so a program that never enables workers never touches the file. */
-function loadManual(): string {
-  return (manual ??= readFileSync(new URL("./subagents.md", import.meta.url), "utf8"));
-}
-
 // One worker reply as the model sees it: a header line naming the worker, then its text; in: a WorkerReply, out: the branded result.
-function asResult(reply: WorkerReply): ReturnType<typeof makeSubagentResult> {
+function asResult(reply: WorkerReply, prompts: Prompts): ReturnType<typeof makeSubagentResult> {
   const text = reply.error
-    ? `[worker ${reply.id}] failed: ${reply.error}`
-    : `[worker ${reply.id}] replied:\n${reply.text}`;
+    ? fillPrompt(prompts.workerFailed, { id: reply.id, reason: reply.error })
+    : fillPrompt(prompts.workerReplied, { id: reply.id, text: reply.text });
   return makeSubagentResult(text, [reply.metadata]);
 }
 
@@ -34,14 +28,12 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
   const max = agent.dynamicSubagents?.maxSpawn ?? Infinity;
   return tool({
     name: "subagents",
-    description: loadManual()
-      .replace(
-        "{{LIMIT}}",
-        Number.isFinite(max)
-          ? `You can have at most ${max} open workers. Close the ones you are done with.`
-          : "There is no limit on open workers. Close the ones you are done with: each one keeps its whole conversation."
-      )
-      .replace("{{TOOLS}}", poolNames.length > 0 ? poolNames.join(", ") : "none (omit tools)"),
+    description: fillPrompt(agent.prompts.subagentsTool, {
+      LIMIT: Number.isFinite(max)
+        ? `You can have at most ${max} open workers. Close the ones you are done with.`
+        : "There is no limit on open workers. Close the ones you are done with: each one keeps its whole conversation.",
+      TOOLS: poolNames.length > 0 ? poolNames.join(", ") : "none (omit tools)",
+    }),
     input: z.object({
       command: z.enum(COMMANDS),
       id: z.string().optional().describe("The worker's full id (message, close)."),
@@ -89,10 +81,11 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
                   history: a.history,
                 },
                 opts
-              )
+              ),
+              agent.prompts
             );
           case "message":
-            return asResult(await agent.workers.message(need("id"), need("task"), opts));
+            return asResult(await agent.workers.message(need("id"), need("task"), opts), agent.prompts);
           case "close":
             return `Worker ${agent.workers.close(need("id")).id} closed.`;
           case "list":

package/src/agent/usage-limit.ts

@@ -0,0 +1,92 @@
+/**
+ * The chat-wide spending cap (`AgentConfig.usageLimit`). One `UsageLimit` belongs to the root agent of a chat and is
+ * handed to every agent below it (registry workers at any depth, fixed `subagents` workers), so each model turn of the
+ * whole tree adds to one running total and every turn is checked before it starts. The total survives a restart: the
+ * first run rebuilds the starting point from the saved sessions of the agent and its workers (`usageReport()`), after
+ * which only new turns are added. Scheduled actions are separate and never count.
+ */
+import { BudgetExceededError } from "../types/errors.ts";
+
+/** What the cap is made of; either part may be set, the first one reached stops the chat. */
+export interface UsageLimitConfig {
+  maxCostUsd?: number;
+  maxTotalTokens?: number;
+}
+
+/** A one-line problem with a `usageLimit` value, or undefined when it is valid; in: the Agent constructor, out: its ConfigError. */
+export function checkUsageLimitConfig(raw: unknown): string | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    return "expected an object like { maxCostUsd, maxTotalTokens }";
+  const r = raw as Record<string, unknown>;
+  const keys = Object.keys(r).filter((k) => r[k] !== undefined);
+  if (keys.length === 0) return "set maxCostUsd, maxTotalTokens or both";
+  for (const k of keys) {
+    if (k !== "maxCostUsd" && k !== "maxTotalTokens") return `unknown key "${k}" (use maxCostUsd or maxTotalTokens)`;
+    const v = r[k];
+    if (!(typeof v === "number" && Number.isFinite(v) && v > 0)) return `${k} must be a number greater than 0`;
+  }
+  return undefined;
+}
+
+/** The running total of one chat and its limit. */
+export class UsageLimit {
+  private baseTokens = 0;
+  private baseMicroUSD = 0;
+  private addedTokens = 0;
+  private addedMicroUSD = 0;
+  private started = false;
+
+  constructor(readonly limit: UsageLimitConfig) {}
+
+  /** Takes the starting point (what the chat spent before this process) once; later calls do nothing until `restart()`. */
+  begin(startingPoint: () => { tokens: number; microUSD: number }): void {
+    if (this.started) return;
+    this.started = true;
+    const s = startingPoint();
+    this.baseTokens = s.tokens;
+    this.baseMicroUSD = s.microUSD;
+    this.addedTokens = 0;
+    this.addedMicroUSD = 0;
+  }
+
+  /** Forgets the total (a session was imported over this agent): the next `begin` takes a new starting point. */
+  restart(): void {
+    this.started = false;
+  }
+
+  /** Adds one model turn of any agent in the chat. Unpriced turns add tokens only (unknown pricing is never a made-up $0 of cost). */
+  add(tokens: number, microUSD: number): void {
+    this.addedTokens += tokens;
+    this.addedMicroUSD += microUSD;
+  }
+
+  /** What the chat has spent so far. */
+  spent(): { tokens: number; costUsd: number } {
+    return {
+      tokens: this.baseTokens + this.addedTokens,
+      costUsd: (this.baseMicroUSD + this.addedMicroUSD) / 1_000_000,
+    };
+  }
+
+  /** Throws a `BudgetExceededError` ("Usage limit reached") once the chat has spent its whole limit. */
+  check(): void {
+    const { tokens, costUsd } = this.spent();
+    const { maxCostUsd, maxTotalTokens } = this.limit;
+    const byCost = maxCostUsd !== undefined && costUsd >= maxCostUsd;
+    const byTokens = maxTotalTokens !== undefined && tokens >= maxTotalTokens;
+    if (!byCost && !byTokens) return;
+    const parts = [
+      ...(maxCostUsd !== undefined ? [`$${costUsd.toFixed(6)} of $${maxCostUsd}`] : []),
+      ...(maxTotalTokens !== undefined ? [`${tokens} of ${maxTotalTokens} tokens`] : []),
+    ];
+    throw new BudgetExceededError(
+      `[Agent Accelerator] Usage limit reached: ${parts.join(", ")} spent by this chat (the agent and all its workers).`,
+      {
+        context: {
+          limit: "usageLimit",
+          partial: { usage: { inputTokens: 0, outputTokens: 0, totalTokens: tokens }, turns: 0 },
+        },
+      }
+    );
+  }
+}

package/src/agent/worker.ts

@@ -246,6 +246,14 @@ export function resolveWorkerCredentials(
   return { apiKeyToUse: undefined, baseUrlToUse: undefined, attemptedProvider };
 }
 
+// Configs built by `buildDynamicWorkerConfig`: the Agent constructor checks it so SDK-built workers never take `configure()` or env defaults.
+const workerConfigs = new WeakSet<object>();
+
+/** True for a config made by `buildDynamicWorkerConfig` (a chat worker or a scheduled run), not by the developer. */
+export function isWorkerConfig(config: object): boolean {
+  return workerConfigs.has(config);
+}
+
 /** How many levels of workers may exist below an agent unless `dynamicSubagents.maxDepth` says otherwise: unlimited. */
 export const DEFAULT_MAX_DEPTH = Infinity;
 
@@ -256,7 +264,7 @@ export const DEFAULT_MAX_DEPTH = Infinity;
  * `persistent` makes a multi-turn worker that keeps its history (saved under `persistent.dir` when given, and
  * continued by `resume()` after a crash, never automatically). A persistent worker with levels left below it
  * (`maxDepth` of the parent, minus one for itself) gets its own `subagents` tool; its children can only be granted
- * the tools it was granted. One-shot workers never spawn. `dynamicSubagents.workerBudget` becomes each worker's own
+ * the tools it was granted. One-shot workers never spawn. `dynamicSubagents.workerBudget` becomes each chat worker's own
  * per-run `budget` (and is passed to its children).
  */
 export function buildDynamicWorkerConfig(
@@ -274,7 +282,7 @@ export function buildDynamicWorkerConfig(
   const { apiKeyToUse, baseUrlToUse } = resolveWorkerCredentials(parent, model);
   const dyn = parent.dynamicSubagents;
   const levelsBelow = (dyn?.maxDepth ?? DEFAULT_MAX_DEPTH) - 1;
-  return {
+  const config: AgentConfig = {
     name: worker.name,
     description: worker.role || `Sub-agent ${worker.name}`,
     instructions: worker.instructions,
@@ -284,7 +292,11 @@ export function buildDynamicWorkerConfig(
     thinkingLevel: parent.dynamicSubagents?.thinkingLevel ?? parent.thinkingConfig?.level,
     sessionId: worker.sessionId,
     tools: worker.tools,
-    ...(dyn?.workerBudget ? { budget: { ...dyn.workerBudget } } : {}),
+    // A chat worker (persistent) is capped by `workerBudget`; a one-shot scheduled run only by `scheduledActionBudget`.
+    ...(() => {
+      const cap = worker.persistent ? dyn?.workerBudget : dyn?.scheduledActionBudget;
+      return cap ? { budget: { ...cap } } : {};
+    })(),
     stateless: !worker.persistent,
     ...(worker.persistent?.dir ? { persist: { dir: worker.persistent.dir }, resume: "explicit" as const } : {}),
     ...(worker.persistent && levelsBelow >= 1
@@ -305,6 +317,8 @@ export function buildDynamicWorkerConfig(
     maxTurns: parent.maxTurns,
     ...parent.inheritableConfig(),
   };
+  workerConfigs.add(config);
+  return config;
 }
 
 // ---------------------------------------------------------------------------

package/src/agent/workers.ts

@@ -23,7 +23,7 @@ import {
   type WorkerRunResult,
 } from "./delegation.ts";
 import { finishedTurns, historyUpTo, type Turn } from "./turns.ts";
-import { modelName, readUsage, type UsageNode } from "../session/usage.ts";
+import { mergeUsage, modelName, readUsage, type UsageNode } from "../session/usage.ts";
 
 /** What `spawn` needs to start a worker. */
 export interface WorkerSpec {
@@ -157,6 +157,17 @@ function readSavedWorker(dir: string | undefined): {
   return { model: session?.session.model || "unknown", totals: readUsage(session?.session.usage), workers };
 }
 
+/** What a saved session folder and every worker saved below it spent in total (read from disk): the starting point of a chat-wide usage cap after a restart; in: Agent.beginChat, out: usage totals. */
+export function savedSpend(dir: string): ReturnType<typeof readUsage> {
+  const total = readUsage(undefined);
+  const add = (node: { totals: ReturnType<typeof readUsage>; workers: UsageNode[] }): void => {
+    mergeUsage(total, node.totals);
+    for (const w of node.workers) add(w);
+  };
+  add(readSavedWorker(dir));
+  return total;
+}
+
 /** The workers of one parent `Agent` (`agent.workers`). */
 export class WorkerRegistry {
   private readonly entries = new Map<string, Entry>();
@@ -384,6 +395,7 @@ export class WorkerRegistry {
       })
     );
     (agent as unknown as { parentSessionId?: string }).parentSessionId = this.parent.sessionId;
+    agent.chat = this.parent.chat; // the worker's turns count into the chat-wide cap and are checked against it
     // A cut-off run was already loaded by the constructor; otherwise bring back what the worker said so far.
     const saved = entry.dir && agent.context.messages.length === 0 ? loadSessionDir(entry.dir)?.session : undefined;
     if (saved) agent.importSession(saved);

package/src/architecture.md

@@ -15,6 +15,7 @@ The whole SDK. `index.ts` is the only public entry (`main`/`module`/`types`); ev
 | `tools/`            | `tool()`, schemas, the executor.                                                                                                                                            |
 | `streaming/`        | The event stream and the SSE parser.                                                                                                                                        |
 | `session/`          | Persistence (snapshot + journal), usage accounting, tool logs.                                                                                                              |
+| `prompts/`          | The SDK's own prompts as `.md` files, `DEFAULT_PROMPTS`, `AgentConfig.prompts`.                                                                                             |
 | `scheduler/`        | Scheduled actions.                                                                                                                                                          |
 | `types/`            | Shared contracts (no logic except small helpers).                                                                                                                           |
 | `utils/`            | Small shared helpers (durable writes, home, env, media, retry, safe I/O).                                                                                                   |

package/src/index.ts

@@ -31,6 +31,10 @@ export {
 } from "./tools/tool.ts";
 export type { CreateToolOptions } from "./tools/tool.ts";
 export { zodToJsonSchema, cleanJsonSchema } from "./tools/schema.ts";
+export { toolContent } from "./tools/tool-content.ts";
+export { DEFAULT_PROMPTS } from "./prompts/prompts.ts";
+export type { PromptName, PromptOverrides } from "./prompts/prompts.ts";
+export type { ToolContent, ToolContentPart } from "./tools/tool-content.ts";
 /**
  * @deprecated Internal executor surface. Prefer `Agent` runs; for direct
  * execution import from the future `/internal` entry.
@@ -60,17 +64,12 @@ export {
 export type { AgentAsToolTarget, SubAgentTrace } from "./agent/delegation.ts";
 export type { WorkerRegistry, WorkerSpec, WorkerInfo, WorkerReply, WorkerCallOptions } from "./agent/workers.ts";
 
-// Scheduled actions: dynamic sub-agents that run later and save their answer to a file
-export {
-  createScheduledAction,
-  listScheduledActions,
-  updateScheduledAction,
-  runScheduledAction,
-  skipScheduledAction,
-  deleteScheduledAction,
-} from "./scheduler/scheduler.ts";
+// Scheduled actions: dynamic sub-agents that run later and save their answer to a file (use `agent.scheduled`)
+export type { ScheduledActions } from "./scheduler/scheduler.ts";
 export { getDatetimeTool } from "./scheduler/tool.ts";
 export { setHome, resolveHome } from "./utils/home.ts";
+export { configure } from "./agent/defaults.ts";
+export type { AgentDefaults } from "./agent/defaults.ts";
 export type {
   ScheduledActionInput,
   ScheduledActionPatch,
@@ -323,6 +322,7 @@ export type {
   ProviderContext,
   ProviderSteps,
   MediaResolution,
+  VideoProcessing,
 } from "./types/message.ts";
 
 export type {

package/src/prompts/additional-context.md

@@ -0,0 +1,2 @@
+[Additional Context]
+{{context}}

package/src/prompts/architecture.md

@@ -0,0 +1,19 @@
+# src/prompts/
+
+The prompts the SDK itself puts in front of the model, as plain `.md` files, so they can be read, copied and replaced.
+
+| File                                                                                                                        | What it is                                                                                                                                                                         |
+| :-------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompts.ts`                                                                                                                | `DEFAULT_PROMPTS` (the shipped text, read once at load, final newline removed), `resolvePrompts` (defaults + `AgentConfig.prompts`, validated), `fillPrompt` (`{{name}}` markers). |
+| `reasoning-directive.md`, `structured-output.md`, `additional-context.md`, `tool-bridge.md`                                 | Text added to the system prompt, a user turn or a history gap.                                                                                                                     |
+| `tool-truncated-arguments.md`, `tool-not-found.md`, `tool-schema-error.md`, `tool-repeat-blocked.md`, `tool-interrupted.md` | The refusals the executor and the loop send back as tool results.                                                                                                                  |
+| `worker-replied.md`, `worker-failed.md`                                                                                     | The header of a `subagents` answer.                                                                                                                                                |
+| `subagents-tool.md`, `scheduled-actions-tool.md`                                                                            | The manuals that are the descriptions of the `subagents` and `scheduled_actions` tools.                                                                                            |
+
+## Invariants
+
+- One file per prompt; the name in `FILES` (`prompts.ts`) is the public name. Add a prompt by adding a file, a `FILES` entry, its use, a row in `docs/guides/prompts.md` and a pinned-text assertion in `test/prompts.test.ts`.
+- The default text is pinned exactly by a test: reflowing a file (an editor or formatter) changes what the model sees and the prompt cache, so the test must fail.
+- Every user of a prompt reads it from the Agent's resolved prompts (`agent.prompts`, `loop` config `prompts`, `ProviderRequestOptions.prompts`, executor `prompts`), never from `DEFAULT_PROMPTS` directly, except as the default of an optional parameter.
+- Machine-readable parts stay in code: the `repeat_blocked` `errorCode`, the `[Structured Output]` marker line.
+- The system prompt carries no delegation text (cache-stable): tool manuals are tool descriptions.

package/src/prompts/prompts.ts

@@ -0,0 +1,81 @@
+/**
+ * The prompts the SDK itself puts in front of the model, kept as `.md` files in this folder so they can be read,
+ * copied and replaced. `DEFAULT_PROMPTS` holds the shipped text; `AgentConfig.prompts` overrides single entries per
+ * Agent. Keeping the original is recommended: it is what the SDK was tested with, and a good starting point (and the
+ * reference) for writing your own. `{{name}}` marks a value the SDK fills in at use time.
+ */
+import { readFileSync } from "node:fs";
+import { ConfigError } from "../types/errors.ts";
+
+/** One entry per prompt file: its public name and the file that holds the default text. */
+const FILES = {
+  reasoningDirective: "reasoning-directive.md",
+  structuredOutput: "structured-output.md",
+  additionalContext: "additional-context.md",
+  toolBridge: "tool-bridge.md",
+  toolTruncatedArguments: "tool-truncated-arguments.md",
+  toolNotFound: "tool-not-found.md",
+  toolSchemaError: "tool-schema-error.md",
+  toolRepeatBlocked: "tool-repeat-blocked.md",
+  toolInterrupted: "tool-interrupted.md",
+  workerReplied: "worker-replied.md",
+  workerFailed: "worker-failed.md",
+  subagentsTool: "subagents-tool.md",
+  scheduledActionsTool: "scheduled-actions-tool.md",
+} as const;
+
+/** The name of one SDK prompt (see `DEFAULT_PROMPTS`). */
+export type PromptName = keyof typeof FILES;
+
+/** The text of every prompt, by name. */
+export type Prompts = Record<PromptName, string>;
+
+/** Per-Agent replacements for single prompts (`AgentConfig.prompts`); every other prompt keeps its default. */
+export type PromptOverrides = Partial<Prompts>;
+
+// Reads one prompt file without its final newline; in: DEFAULT_PROMPTS at load, out: the default text.
+function readPrompt(file: string): string {
+  return readFileSync(new URL(`./${file}`, import.meta.url), "utf8").replace(/\n$/, "");
+}
+
+/**
+ * The prompts as shipped. Placeholders (`{{name}}`) are filled in by the SDK: `reasoningDirective` none;
+ * `structuredOutput` `{{schema}}`; `additionalContext` `{{context}}`; `toolTruncatedArguments`, `toolRepeatBlocked`
+ * `{{tool}}`; `toolNotFound` `{{tool}}`, `{{suggestion}}`; `toolSchemaError` `{{tool}}`, `{{detail}}`, `{{keys}}`,
+ * `{{expected}}`; `toolInterrupted` `{{tool}}`, `{{id}}`; `workerReplied` `{{id}}`, `{{text}}`; `workerFailed` `{{id}}`,
+ * `{{reason}}`; `subagentsTool` `{{TOOLS}}`, `{{LIMIT}}`; `scheduledActionsTool` `{{TOOLS}}`.
+ */
+export const DEFAULT_PROMPTS: Readonly<Prompts> = Object.freeze(
+  Object.fromEntries(Object.entries(FILES).map(([name, file]) => [name, readPrompt(file)])) as Prompts
+);
+
+/** Defaults with `overrides` applied. Throws a `ConfigError` for an unknown name or an empty or non-string text. */
+export function resolvePrompts(overrides?: PromptOverrides): Prompts {
+  const out: Prompts = { ...DEFAULT_PROMPTS };
+  if (overrides === undefined) return out;
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
+    throw new ConfigError(
+      '[Agent Accelerator] Invalid prompts: expected an object like { reasoningDirective: "..." } (see DEFAULT_PROMPTS for the names).'
+    );
+  }
+  for (const [name, text] of Object.entries(overrides)) {
+    if (text === undefined) continue;
+    if (!Object.hasOwn(FILES, name)) {
+      throw new ConfigError(
+        `[Agent Accelerator] Unknown prompt "${name}". Valid names: ${Object.keys(FILES).join(", ")}.`
+      );
+    }
+    if (typeof text !== "string" || !text.trim()) {
+      throw new ConfigError(`[Agent Accelerator] Invalid prompt "${name}": expected a non-empty string.`);
+    }
+    out[name as PromptName] = text;
+  }
+  return out;
+}
+
+/** Fills `{{name}}` markers in a prompt from `values`; a marker with no value is left as written. */
+export function fillPrompt(template: string, values: Record<string, string | number>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (whole, key: string) =>
+    Object.hasOwn(values, key) ? String(values[key]) : whole
+  );
+}