agent-accelerator 0.5.2 → 0.5.4

package/src/agent/loop.ts

@@ -18,6 +18,7 @@ import {
   shouldBlockRepeat,
   toolCallFingerprint,
   traceToolEvent,
+  type ExecuteToolsOptions,
 } from "../tools/executor.ts";
 import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } from "../models/catalog.ts";
 import { enforceFileAccess } from "../utils/safe-io.ts";
@@ -70,6 +71,17 @@ export interface AgentLoopConfig {
   enforceBudget?: (usage?: TokenUsage) => void;
   /** Called after every turn for durable persistence checkpoints (never fails a turn). */
   onProgress?: () => void;
+  /** Called once per model call this agent made itself (never for its workers), with the provider's usage and the catalog spec: the source of `usageReport()`. */
+  onTurnUsage?: (usage: TokenUsage, spec: ModelSpec | undefined) => void;
+  /** Called the moment each tool call finishes, before the rest of its batch (the crash-proof record of finished work). */
+  onToolResult?: (result: ToolResultRecord) => void;
+  /** Opens the log file of one tool call (see `ToolLogs`); unset when the Agent does not persist to a folder. */
+  openToolLog?: ExecuteToolsOptions["openToolLog"];
+  /**
+   * Continue a run that a crash cut off instead of starting from a new prompt: tool calls the last assistant turn made
+   * without a stored result are finished first (a result in `stored` is reused, anything else runs now), then the loop goes on.
+   */
+  resume?: { stored: Map<string, ToolResultRecord> };
   /**
    * Shared steer inbox for mid-session redirection. Entries are drained
    * between turns (after the current provider/tool work finishes) and
@@ -401,16 +413,14 @@ async function generateWithTimeout<T>(task: () => Promise<T>, timeoutMs: number)
   }
 }
 
-/** Compat wrapper around the one cost model (`priceUsage` in session/store.ts, Q-36).
- * Prefers provider-reported totals, else catalog pricing with integer
- * micro-USD accumulation. Returns undefined when unknown (never a 0 object). */
-export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): TokenUsage["cost"] {
+/** Prices one usage snapshot with the one cost model (`priceUsage`): provider-reported total first, else catalog pricing scaled by `serviceTier`; undefined when unknown. In: loop turns and `accumulateUsage`, out: `usage.cost`. */
+export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec, serviceTier?: string): TokenUsage["cost"] {
   try {
     if (usage.cost && usage.cost.totalCost !== undefined && usage.cost.totalCost > 0) {
       return usage.cost;
     }
     if (!spec) return usage.cost;
-    const priced = priceUsage(usage, spec);
+    const priced = priceUsage(usage, spec, serviceTier ? { serviceTier } : undefined);
     return priced
       ? {
           inputCost: priced.inputCost,
@@ -438,7 +448,7 @@ export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): Tok
 // This function never mutates `source` (Q-35): the priced cost is cloned
 // into a local before folding into the target.
 // ---------------------------------------------------------------------------
-function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec): void {
+export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec, serviceTier?: string): void {
   target.inputTokens += source.inputTokens || 0;
   target.outputTokens += source.outputTokens || 0;
   target.totalTokens += source.totalTokens || 0;
@@ -465,7 +475,7 @@ function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpe
     });
   }
 
-  const priced = computeCostFromPricing(source, spec);
+  const priced = computeCostFromPricing(source, spec, serviceTier);
   // Q-35: pure — read `source` only; never assign back to `source.cost`.
   // Clone the priced cost so later target folds cannot alias source state.
   const sourceCost = priced ? { ...priced } : undefined;
@@ -506,6 +516,8 @@ function sanitizeToolResult(r: ToolResultRecord): { sanitized: ToolResultRecord;
 async function executeToolCallsWithRepeatGuard(options: {
   tools: Record<string, ToolDefinition>;
   toolCalls: ToolCallRecord[];
+  onResult?: (result: ToolResultRecord) => void;
+  openToolLog?: ExecuteToolsOptions["openToolLog"];
   previousFingerprints: Set<string>;
   repeatCounts: Map<string, number>;
   agentName?: string;
@@ -546,6 +558,8 @@ async function executeToolCallsWithRepeatGuard(options: {
         signal: options.signal,
         sessionId: options.sessionId,
         onSubagentEvent: options.onSubagentEvent,
+        onResult: options.onResult,
+        openToolLog: options.openToolLog,
       })
     : [];
   const byId = new Map<string, ToolResultRecord[]>();
@@ -572,6 +586,73 @@ async function executeToolCallsWithRepeatGuard(options: {
   };
 }
 
+/** Tool calls of the LAST assistant message that have no result in the conversation yet (a crash or interrupt cut them off). */
+export function unfinishedToolCalls(messages: AgentContext["messages"]): ToolCallRecord[] {
+  let lastAssistant = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]!.role === "assistant") {
+      lastAssistant = i;
+      break;
+    }
+  }
+  const calls = lastAssistant < 0 ? [] : messages[lastAssistant]!.content;
+  if (!Array.isArray(calls)) return [];
+  const answered = new Set<string>();
+  for (const m of messages.slice(lastAssistant + 1)) {
+    if (m.role !== "tool" || !Array.isArray(m.content)) continue;
+    for (const p of m.content) if (p.type === "tool_result") answered.add(p.id);
+  }
+  const open: ToolCallRecord[] = [];
+  for (const p of calls) {
+    if (p.type === "tool_call" && !answered.has(p.id)) {
+      open.push({ id: p.id, name: p.name, arguments: p.arguments, ...(p.rawArguments ? { rawArguments: p.rawArguments } : {}), ...(p.callId ? { callId: p.callId } : {}) });
+    }
+  }
+  return open;
+}
+
+/** True when the conversation ends with tool results of a batch in which a tool called `ctx.stop` (the run was meant to end there). */
+export function endsWithStop(messages: AgentContext["messages"]): boolean {
+  for (let i = messages.length - 1; i >= 0 && messages[i]!.role === "tool"; i--) {
+    const content = messages[i]!.content;
+    if (Array.isArray(content) && content.some((p) => p.type === "tool_result" && p.stopped === true)) return true;
+  }
+  return false;
+}
+
+// Finishes the tool calls a crash left open (stored result reused, anything else executed now) and records the results in the conversation; in: a resumed run's config, out: tool results in context + what the response should report.
+async function finishInterruptedTools(
+  config: AgentLoopConfig
+): Promise<{ calls: ToolCallRecord[]; results: ToolResultRecord[]; subagents: SubAgentExecutionMetadata[] }> {
+  const open = unfinishedToolCalls(config.context.messages);
+  const none = { calls: [], results: [], subagents: [] };
+  if (open.length === 0 || !config.resume) return none;
+  const stored = config.resume.stored;
+  const toRun = open.filter((c) => !stored.has(c.id));
+  const executed = toRun.length
+    ? await executeToolCalls({
+        tools: config.tools,
+        toolCalls: toRun,
+        agentName: config.agentName,
+        parallel: true,
+        signal: config.runOptions?.signal,
+        sessionId: config.runOptions?.sessionId || config.options?.sessionId,
+        onResult: config.onToolResult,
+        openToolLog: config.openToolLog,
+      })
+    : [];
+  const ran = new Map(executed.map((r) => [r.id, r]));
+  const subagents: SubAgentExecutionMetadata[] = [];
+  const results = open.map((call) => {
+    const { sanitized, metas } = sanitizeToolResult(ran.get(call.id) ?? stored.get(call.id)!);
+    subagents.push(...metas);
+    return sanitized;
+  });
+  config.context.addToolResults(results);
+  emitProgress(config);
+  return { calls: open, results, subagents };
+}
+
 /**
  * Runs a single non-streaming agent turn or multi-turn loop
  */
@@ -614,13 +695,28 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   let finalResult: any = null;
   let turns = 0;
   let toolsExecuted = false;
+  let stoppedByTool = false;
   let previousToolCallFingerprints = new Set<string>();
   const repeatCounts = new Map<string, number>();
 
   try {
   const standardTools = toStandardToolDeclarations(tools);
 
-  while (turns < maxTurns) {
+  if (config.resume) {
+    const finished = await finishInterruptedTools(config);
+    stoppedByTool = finished.results.some((r) => r.stopped) || endsWithStop(context.messages);
+    if (finished.calls.length > 0) {
+      toolsExecuted = true;
+      allToolCalls.push(...finished.calls);
+      allToolResults.push(...finished.results);
+      for (const meta of finished.subagents) {
+        allSubagents.push(meta);
+        accumulateUsage(accumulatedUsage, meta.usage, getModelFromCatalog(meta.provider, meta.model));
+      }
+    }
+  }
+
+  while (!stoppedByTool && turns < maxTurns) {
     // Q-21: fail fast on abort (throws AbortError with partial).
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: finalResult?.text });
     checkDeadline(startTime, limits.deadlineMs);
@@ -703,8 +799,9 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       }
     }
 
-    accumulateUsage(accumulatedUsage, genResult.usage, spec);
-    config.enforceBudget?.({ ...genResult.usage, cost: computeCostFromPricing(genResult.usage, spec) });
+    accumulateUsage(accumulatedUsage, genResult.usage, spec, options?.serviceTier);
+    try { config.onTurnUsage?.(genResult.usage, spec); } catch {}
+    config.enforceBudget?.({ ...genResult.usage, cost: computeCostFromPricing(genResult.usage, spec, options?.serviceTier) });
     checkTokenLimit(accumulatedUsage, limits.maxTotalTokens);
 
     // Record assistant turn in context
@@ -758,6 +855,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     // Execute tool calls — always parallel (model-driven, bloatfree DX7)
     // Q-21: check abort before tools (throws AbortError with partial).
     throwIfAborted(runOptions?.signal, { usage: accumulatedUsage, turns, text: genResult.text });
+    emitProgress(config); // the calls are on record BEFORE they run, so a crash can finish them instead of forgetting them
     allToolCalls.push(...genResult.toolCalls);
     // Q-22: per-run tool-call budget.
     if (allToolCalls.length > limits.maxToolCallsPerRun) {
@@ -774,6 +872,8 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       agentName,
       signal: runOptions?.signal,
       sessionId: runOptions?.sessionId || options?.sessionId,
+      onResult: config.onToolResult,
+      openToolLog: config.openToolLog,
     });
     const results = guarded.results;
     previousToolCallFingerprints = guarded.fingerprints;
@@ -811,6 +911,12 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       toolCalls: genResult.toolCalls,
       toolResults: sanitizedResults,
     });
+    // A tool ended the run (`ctx.stop`): the whole batch has finished, so stop here. Waiting steers become follow-ups.
+    if (sanitizedResults.some((r) => r.stopped)) {
+      stoppedByTool = true;
+      emitProgress(config);
+      break;
+    }
     // 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).
@@ -829,7 +935,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   // results above were never sent back, so the run is truncated — surface
   // it via finishReason + warning instead of silently returning.
   const truncatedByMaxTurns =
-    turns >= maxTurns && !!finalResult?.toolCalls && finalResult.toolCalls.length > 0;
+    !stoppedByTool && turns >= maxTurns && !!finalResult?.toolCalls && finalResult.toolCalls.length > 0;
   if (truncatedByMaxTurns) {
     warnMaxTurnsHit(
       agentName,
@@ -841,7 +947,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
   // Structured outputs: validate final text only (tool turns skip this).
   // Strict-fail throws ValidationError with partial attached via catch below.
   let parsedOutput: unknown | undefined;
-  if (loopOutput.raw !== undefined && !truncatedByMaxTurns) {
+  if (loopOutput.raw !== undefined && !truncatedByMaxTurns && !stoppedByTool) {
     parsedOutput = parseFinalStructuredOutput(finalResult?.text || "", loopOutput.raw, loopOutput.spec);
   }
 
@@ -858,7 +964,9 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     model: modelId,
     provider: provider.id,
     // Q-04: canonical finish reason + raw vendor passthrough.
-    ...canonicalFinishReason(finalResult?.finishReason, truncatedByMaxTurns),
+    ...(stoppedByTool
+      ? { finishReason: "stopped" as const, ...(finalResult?.finishReason ? { rawFinishReason: finalResult.finishReason } : {}) }
+      : canonicalFinishReason(finalResult?.finishReason, truncatedByMaxTurns)),
     durationMs: Date.now() - startTime,
     raw: applyCaptureRaw(finalResult?.raw, config.captureRaw) as ProviderRawData,
     turns,
@@ -1016,6 +1124,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
       turns = 0;
       let previousToolCallFingerprints = new Set<string>();
       const repeatCounts = new Map<string, number>();
+      let stoppedByTool = false;
 
       while (turns < maxTurns) {
         throwIfCancelled({ usage: accumulatedUsage, turns, text: lastResponse?.text });
@@ -1144,8 +1253,9 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           }
         }
 
-        accumulateUsage(accumulatedUsage, turnResponse.usage, spec2);
-        config.enforceBudget?.({ ...turnResponse.usage, cost: computeCostFromPricing(turnResponse.usage, spec2) });
+        accumulateUsage(accumulatedUsage, turnResponse.usage, spec2, options?.serviceTier);
+        try { config.onTurnUsage?.(turnResponse.usage, spec2); } catch {}
+        config.enforceBudget?.({ ...turnResponse.usage, cost: computeCostFromPricing(turnResponse.usage, spec2, options?.serviceTier) });
         checkTokenLimit(accumulatedUsage, streamLimits.maxTotalTokens);
 
         context.addAssistantMessage(
@@ -1198,6 +1308,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         }
 
         throwIfCancelled({ usage: accumulatedUsage, turns, text: turnResponse.text });
+        emitProgress(config); // the calls are on record BEFORE they run, so a crash can finish them instead of forgetting them
         allToolCalls.push(...turnResponse.toolCalls);
         if (allToolCalls.length > streamLimits.maxToolCallsPerRun) {
           throw new Error(
@@ -1219,6 +1330,8 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           agentName,
           signal: linked.signal,
           sessionId: runOptions?.sessionId || options?.sessionId,
+          onResult: config.onToolResult,
+          openToolLog: config.openToolLog,
           onSubagentEvent: (ev) => {
             try {
               outerStream.push({
@@ -1284,6 +1397,12 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           toolCalls: turnResponse.toolCalls,
           toolResults: sanitizedResults,
         });
+        // A tool ended the run (`ctx.stop`): the whole batch has finished, so stop here. Waiting steers become follow-ups.
+        if (sanitizedResults.some((r) => r.stopped)) {
+          stoppedByTool = true;
+          emitProgress(config);
+          break;
+        }
         const toolSteered = drainSteerInbox(context, config.steerInbox);
         if (toolSteered.length > 0) {
           for (const preview of toolSteered) {
@@ -1301,7 +1420,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
       }
 
       const truncatedByMaxTurns =
-        turns >= maxTurns && !!lastResponse?.toolCalls && lastResponse.toolCalls.length > 0;
+        !stoppedByTool && turns >= maxTurns && !!lastResponse?.toolCalls && lastResponse.toolCalls.length > 0;
       if (truncatedByMaxTurns) {
         warnMaxTurnsHit(
           agentName,
@@ -1309,10 +1428,12 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           lastResponse!.toolCalls.map((c) => c.name)
         );
       }
-      const truncatedFinish = canonicalFinishReason(lastResponse?.finishReason, truncatedByMaxTurns);
+      const truncatedFinish = stoppedByTool
+        ? { finishReason: "stopped" as const, ...(lastResponse?.finishReason ? { rawFinishReason: lastResponse.finishReason } : {}) }
+        : canonicalFinishReason(lastResponse?.finishReason, truncatedByMaxTurns);
 
       let streamParsed: unknown | undefined;
-      if (streamOutputRaw !== undefined && !truncatedByMaxTurns) {
+      if (streamOutputRaw !== undefined && !truncatedByMaxTurns && !stoppedByTool) {
         try {
           streamParsed = parseFinalStructuredOutput(lastResponse?.text || "", streamOutputRaw, streamOutputSpec);
         } catch (err) {

package/src/agent/subagents-tool.ts

@@ -0,0 +1,87 @@
+/**
+ * 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
+ * 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";
+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";
+
+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> {
+  const text = reply.error ? `[worker ${reply.id}] failed: ${reply.error}` : `[worker ${reply.id}] replied:\n${reply.text}`;
+  return makeSubagentResult(text, [reply.metadata]);
+}
+
+/** Builds the `subagents` tool for `agent`; its description is the manual with the worker pool and the open-worker limit filled in. */
+export function createSubagentsTool(agent: Agent): ToolDefinition {
+  const poolNames = Object.keys(agent.dynamicSubagents?.tools ?? {});
+  const max = agent.dynamicSubagents?.maxSpawn ?? 4;
+  return tool({
+    name: "subagents",
+    description: loadManual()
+      .replace(/\{\{MAX\}\}/g, String(max))
+      .replace("{{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)."),
+      name: z.string().optional().describe('Short label for a new worker, e.g. "researcher" (spawn).'),
+      role: z.string().optional().describe("Short persona for the worker (spawn)."),
+      instructions: z.string().optional().describe("The worker's own system prompt (spawn)."),
+      task: z.string().optional().describe("The assignment (spawn) or the next message to the worker (message)."),
+      tools: z.array(z.string()).optional().describe(`Worker tools to grant, from: ${poolNames.join(", ") || "none"} (spawn).`),
+      history: z.number().int().min(0).optional().describe("How many of the first finished turns of this conversation to copy into the worker; 0 or omitted = none (spawn)."),
+    }),
+    execute: async (a, ctx) => {
+      const opts = { signal: ctx.signal, callId: ctx.toolCallId, onSubagentEvent: ctx.onSubagentEvent };
+      const need = (field: "id" | "name" | "task"): string => {
+        const value = a[field];
+        if (!value?.trim()) {
+          const example = a.command === "spawn" ? { command: "spawn", name: "researcher", task: "Do the work." } : { command: a.command, id: "researcher-1a2b3c4d", task: "Next question." };
+          throw new ValidationError(`${a.command} needs "${field}". Example: ${JSON.stringify(example)}`);
+        }
+        return value;
+      };
+      try {
+        switch (a.command) {
+          case "spawn":
+            return asResult(
+              await agent.workers.spawn({ name: need("name"), role: a.role, instructions: a.instructions, task: need("task"), tools: a.tools, history: a.history }, opts)
+            );
+          case "message":
+            return asResult(await agent.workers.message(need("id"), need("task"), opts));
+          case "close":
+            return `Worker ${agent.workers.close(need("id")).id} closed.`;
+          case "list":
+            return describeWorkers(agent);
+        }
+      } catch (err) {
+        // A bad request is feedback for the model; anything else (budget, configuration) is a real failure.
+        if (err instanceof ValidationError) return `Error: ${err.message}`;
+        throw err;
+      }
+    },
+  });
+}
+
+// The `list` answer: the open workers and the conversation turns `history` can copy; in: the agent's registry, out: plain text for the model.
+function describeWorkers(agent: Agent): string {
+  const workers = agent.workers.list();
+  const turns = agent.workers.turns();
+  const open = workers.length === 0 ? "none" : workers.map((w) => `- ${w.id} (${w.name}${w.role ? `, ${w.role}` : ""}) tools: ${w.tools.join(", ") || "none"}${w.busy ? " [busy]" : ""}`).join("\n");
+  const copyable = turns.length === 0 ? "none yet" : turns.map((t) => `${t.n}. ${t.prompt}`).join("\n");
+  return `Open workers:\n${open}\n\nFinished turns of this conversation (history: N copies turns 1 to N):\n${copyable}`;
+}

package/src/agent/subagents.md

@@ -0,0 +1,31 @@
+Starts helpers ("workers") that work on a task for you and can be asked again later. A worker is a separate agent with its own instructions, its own tools and its own memory: it knows only what you give it (plus the earlier conversation you choose to copy). Use workers for parallel research, a second opinion, or a long side task you do not want in your own context.
+
+COMMANDS (one tool, the `command` field)
+- spawn: start a worker. Needs `name` and `task`. Optional: `instructions` (the worker's own system prompt), `role`, `tools`, `history`. It waits for the worker's first reply and gives you the worker's `id`.
+- message: send `task` to the open worker `id`. The worker remembers everything said to it before. It waits for the reply.
+- close: end the worker `id` when you no longer need it. This frees one of your {{MAX}} open slots. A closed worker cannot be messaged again.
+- list: your open workers, plus the numbered turns of this conversation that `history` can copy.
+
+FIELDS
+- name: a short label such as "researcher". The SDK adds a suffix; use the full `id` it returns ("researcher-1a2b3c4d") in message and close.
+- instructions: the worker's own system prompt: its role, rules and the format you want back.
+- task: for spawn, the first assignment; for message, the next message to that worker.
+- tools: names of worker tools to grant. Available: {{TOOLS}}. Grant only what the task needs.
+- history: a number N (default 0 = none). Starts the worker with a copy of the first N finished turns of this conversation, in order. Call list to see the turns and their numbers. The turn you are in right now is never copied: restate what you need in `task`.
+
+RESULTS
+Every spawn and message answers with one header line and the worker's text: `[worker <id>] replied:` or `[worker <id>] failed: <reason>`. A failed worker stays open: fix the problem and message it again, or close it.
+
+EXAMPLES
+Start a researcher:
+{"command":"spawn","name":"researcher","instructions":"You research databases. Answer in 5 bullets with sources.","task":"Compare SQLite and Postgres for a small SaaS."}
+Ask it a follow-up:
+{"command":"message","id":"researcher-1a2b3c4d","task":"Now focus on write-heavy workloads."}
+
+RULES
+- Several workers at once: make several spawn calls in the same turn. They run in parallel.
+- A worker handles one call at a time. Wait for its reply before messaging it again.
+- You can have at most {{MAX}} open workers. Close the ones you are done with.
+- A worker starts blank: put everything it needs in `instructions` and `task`, or copy earlier turns with `history`.
+- Worker answers are written by another model. Check them before you rely on them.
+- Never put secrets in `instructions` or `task`.

package/src/agent/turns.ts

@@ -0,0 +1,60 @@
+/**
+ * Turn grouping: a "turn" is one finished run (the user prompt plus the whole answer to it: text, thinking, tool calls
+ * and results), found through the run marks the Agent keeps. A worker that starts from a copy of its parent's history
+ * gets whole finished turns only, so a prompt never reaches it without its answer. Pure functions, no Agent import.
+ */
+import type { Message, ContentPart } from "../types/message.ts";
+import type { SessionRunMark } from "../session/store.ts";
+import { ValidationError } from "../types/errors.ts";
+import { previewPrompt } from "../utils/session.ts";
+import { deepCloneValue } from "./context.ts";
+
+/** One finished turn: its 1-based number (counting finished turns only), a prompt preview, and its messages `[from, to)`. */
+export interface Turn {
+  n: number;
+  prompt: string;
+  from: number;
+  to: number;
+}
+
+/** Longest prompt preview shown to a model in a turn list. */
+const PREVIEW_CHARS = 200;
+
+// A run counts as finished when it ended with its answer (`done`) or with a tool's `ctx.stop` (`stopped`); in: a run mark, out: finishedTurns.
+function isFinished(mark: SessionRunMark): boolean {
+  return mark.end === "done" || mark.end === "stopped";
+}
+
+/** The finished turns of a conversation, oldest first. The running turn and failed, aborted or abandoned runs are not turns. */
+export function finishedTurns(messages: Message[], marks: SessionRunMark[]): Turn[] {
+  const sorted = marks.filter((m) => m.i >= 0 && m.i < messages.length).sort((a, b) => a.i - b.i);
+  const turns: Turn[] = [];
+  sorted.forEach((mark, k) => {
+    if (!isFinished(mark)) return;
+    turns.push({
+      n: turns.length + 1,
+      prompt: previewPrompt(messages[mark.i]!.content as string | ContentPart[]).slice(0, PREVIEW_CHARS),
+      from: mark.i,
+      to: sorted[k + 1]?.i ?? messages.length,
+    });
+  });
+  return turns;
+}
+
+/**
+ * A deep copy of the first `n` finished turns (plus anything before the first run mark), in order. `0` gives an empty
+ * history. Throws a `ValidationError` naming how many finished turns exist when `n` is not a whole number in range.
+ */
+export function historyUpTo(messages: Message[], marks: SessionRunMark[], n: number): Message[] {
+  const turns = finishedTurns(messages, marks);
+  if (!Number.isInteger(n) || n < 0 || n > turns.length) {
+    throw new ValidationError(
+      `history: ${JSON.stringify(n)} is not valid; use "none" or a whole number from 1 to ${turns.length} (the number of finished turns).`
+    );
+  }
+  if (n === 0) return [];
+  const first = marks.filter((m) => m.i >= 0 && m.i < messages.length).reduce((lo, m) => Math.min(lo, m.i), messages.length);
+  const kept = [...messages.slice(0, first)];
+  for (const turn of turns.slice(0, n)) kept.push(...messages.slice(turn.from, turn.to));
+  return deepCloneValue(kept);
+}

package/src/agent/worker.ts

@@ -42,11 +42,6 @@ export function sanitizeToolName(raw: string): string {
   return tag.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").slice(0, 64) || "sub-agent";
 }
 
-/** Stable worker ids: `{sanitizedName}-{32hex}` display id + raw tracking id. */
-export function makeWorkerIds(sanitizedName: string, trackingId: string): { trackingId: string; displayId: string } {
-  return { trackingId, displayId: `${sanitizedName}-${trackingId}` };
-}
-
 // ---------------------------------------------------------------------------
 // Shared Agent / SubAgent config normalization (behavior-preserving)
 // ---------------------------------------------------------------------------
@@ -203,11 +198,6 @@ export function grantWorkerTools(
   return grantedTools;
 }
 
-/** Resolves a provider id for credential reuse / error metadata (shared). */
-export function providerOfWorkerModel(modelStr: string | unknown | undefined): string | undefined {
-  return providerOf(modelStr);
-}
-
 function providerOf(modelStr: string | unknown | undefined): string | undefined {
   if (!modelStr) return undefined;
   try {
@@ -246,18 +236,34 @@ export function resolveWorkerCredentials(
   return { apiKeyToUse: undefined, baseUrlToUse: undefined, attemptedProvider };
 }
 
+/** How many levels of workers may exist below an agent unless `dynamicSubagents.maxDepth` says otherwise. */
+export const DEFAULT_MAX_DEPTH = 3;
+
 /**
- * Config of a stateless dynamic worker (`spawn_subagents` and scheduled
- * actions): the developer's fixed worker model, level and limits, never the
- * LLM's choice. Credentials carry over only when the providers match, and
- * `inheritableConfig()` keeps the worker no less constrained than its parent.
+ * Config of a dynamic worker (scheduled actions, the worker registry): the developer's fixed worker
+ * model, level and limits, never the LLM's choice. Credentials carry over only when the providers match, and
+ * `inheritableConfig()` keeps the worker no less constrained than its parent. Stateless one-shot by default;
+ * `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
+ * per-run `budget` (and is passed to its children).
  */
 export function buildDynamicWorkerConfig(
   parent: Agent,
-  worker: { name: string; role?: string; instructions: string; sessionId: string; tools: Record<string, ToolDefinition> }
+  worker: {
+    name: string;
+    role?: string;
+    instructions: string;
+    sessionId: string;
+    tools: Record<string, ToolDefinition>;
+    persistent?: { dir?: string };
+  }
 ): AgentConfig {
   const model = parent.subagentModel;
   const { apiKeyToUse, baseUrlToUse } = resolveWorkerCredentials(parent, model);
+  const dyn = parent.dynamicSubagents;
+  const levelsBelow = (dyn?.maxDepth ?? DEFAULT_MAX_DEPTH) - 1;
   return {
     name: worker.name,
     description: worker.role || `Sub-agent ${worker.name}`,
@@ -268,8 +274,22 @@ export function buildDynamicWorkerConfig(
     thinkingLevel: parent.dynamicSubagents?.thinkingLevel ?? parent.thinkingConfig?.level,
     sessionId: worker.sessionId,
     tools: worker.tools,
-    // Stateless by design: one task in, one result out, then shut down. No history, no recursion.
-    stateless: true,
+    ...(dyn?.workerBudget ? { budget: { ...dyn.workerBudget } } : {}),
+    stateless: !worker.persistent,
+    ...(worker.persistent?.dir ? { persist: { dir: worker.persistent.dir }, resume: "explicit" as const } : {}),
+    ...(worker.persistent && levelsBelow >= 1
+      ? {
+          dynamicSubagents: {
+            enabled: true,
+            model,
+            ...(dyn?.maxSpawn !== undefined ? { maxSpawn: dyn.maxSpawn } : {}),
+            ...(dyn?.thinkingLevel ? { thinkingLevel: dyn.thinkingLevel } : {}),
+            tools: worker.tools,
+            ...(dyn?.workerBudget ? { workerBudget: dyn.workerBudget } : {}),
+            maxDepth: levelsBelow,
+          },
+        }
+      : {}),
     serviceTier: parent.serviceTier,
     headers: parent.customHeaders,
     maxTurns: parent.maxTurns,
@@ -277,18 +297,6 @@ export function buildDynamicWorkerConfig(
   };
 }
 
-/** Builds one `<NAME>...text...</NAME>` block inside `<SUB-AGENTS-RESPONSE>`. */
-export function buildWorkerXmlBlock(name: string, text: string): string {
-  const escaped = escapeXml(text);
-  const indentedText = escaped.split("\n").map((line) => `        ${line}`).join("\n");
-  return `    <${name}>\n${indentedText}\n    </${name}>`;
-}
-
-/** Builds the `<SUB-AGENTS-RESPONSE>` envelope for dynamic workers. */
-export function buildSubagentsXml(results: Array<{ name: string; text: string }>): string {
-  return `<SUB-AGENTS-RESPONSE>\n${results.map((r) => buildWorkerXmlBlock(r.name, r.text)).join("\n")}\n</SUB-AGENTS-RESPONSE>`;
-}
-
 // ---------------------------------------------------------------------------
 // Shared live worker state machine (single home for fixed + dynamic workers)
 // ---------------------------------------------------------------------------
@@ -322,7 +330,7 @@ export interface LiveWorkerHooks {
 
 /**
  * Single live worker state machine shared by fixed (`agentToTool`) and
- * dynamic (`spawn_subagents`) workers. Owns `liveTurn` / `partialText` /
+ * registry workers. Owns `liveTurn` / `partialText` /
  * `partialThinking`, finalizes partial streaming entries on `onTurn`, and
  * forwards deltas to the parent stream. The trace object is mutated in place;
  * trimming / touching / notifying / persisting are delegated to hooks so this