agent-accelerator 0.5.9 → 0.6.0

package/src/agent/subagent.ts

@@ -16,9 +16,7 @@ export interface SubAgentConfig extends AgentConfig {}
  * `Agent.fromEnv()` (attached below without touching `agent.ts`, owned by
  * another audit lane) delegates here.
  */
-export function agentFromEnv(
-  config?: Omit<AgentConfig, "model"> & { model?: AgentConfig["model"] }
-): Agent {
+export function agentFromEnv(config?: Omit<AgentConfig, "model"> & { model?: AgentConfig["model"] }): Agent {
   return new Agent({
     ...config,
     model: config?.model ?? getModel() ?? getSubModel(),

package/src/agent/subagents-tool.ts

@@ -22,7 +22,9 @@ function loadManual(): string {
 
 // 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}`;
+  const text = reply.error
+    ? `[worker ${reply.id}] failed: ${reply.error}`
+    : `[worker ${reply.id}] replied:\n${reply.text}`;
   return makeSubagentResult(text, [reply.metadata]);
 }
 
@@ -33,7 +35,12 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
   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(
+        "{{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)"),
     input: z.object({
       command: z.enum(COMMANDS),
@@ -42,15 +49,28 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
       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)."),
+      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." };
+          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;
@@ -59,7 +79,17 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
         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)
+              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));
@@ -81,7 +111,15 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
 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 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

@@ -1,12 +1,14 @@
 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. 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.
@@ -23,6 +25,7 @@ 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.
 - {{LIMIT}}

package/src/agent/turns.ts

@@ -53,7 +53,9 @@ export function historyUpTo(messages: Message[], marks: SessionRunMark[], n: num
     );
   }
   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 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

@@ -30,14 +30,23 @@ export interface LiveWorkerTrace {
 export function sanitizeXmlTag(raw: string): string {
   let s = raw.toUpperCase().replace(/[^A-Z0-9.-]/g, "-");
   if (!/^[A-Z]/.test(s)) s = `AGENT-${s}`;
-  s = s.replace(/[.]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  s = s
+    .replace(/[.]/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "");
   return s.slice(0, 64) || "SUBAGENT";
 }
 
 /** Sanitizes a worker name into a tool name (`lower-kebab`, 64 chars). */
 export function sanitizeToolName(raw: string): string {
   const tag = sanitizeXmlTag(raw);
-  return tag.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").slice(0, 64) || "sub-agent";
+  return (
+    tag
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, "-")
+      .replace(/-{2,}/g, "-")
+      .slice(0, 64) || "sub-agent"
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -91,13 +100,8 @@ export function resolveMainModel(configModel: AgentConfig["model"]): {
  * `dynamicSubagents.model ?? subagentModel ?? SUB_AGENT_MODEL`.
  * Unwraps `ModelProviderInstance` / `ModelSpec` the same way.
  */
-export function resolveDynamicWorkerModel(
-  dynModelRawInput: unknown
-): string | Record<string, unknown> | undefined {
-  const dynModelRaw = dynModelRawInput as
-    | { model?: unknown; id?: unknown; provider?: unknown }
-    | string
-    | undefined;
+export function resolveDynamicWorkerModel(dynModelRawInput: unknown): string | Record<string, unknown> | undefined {
+  const dynModelRaw = dynModelRawInput as { model?: unknown; id?: unknown; provider?: unknown } | string | undefined;
   let dynModel: string | Record<string, unknown> | undefined;
   if (dynModelRaw && typeof dynModelRaw === "object" && "model" in (dynModelRaw as Record<string, unknown>)) {
     dynModel = (dynModelRaw as { model: string }).model as unknown as string | Record<string, unknown>;
@@ -109,7 +113,7 @@ export function resolveDynamicWorkerModel(
   ) {
     dynModel = dynModelRaw as Record<string, unknown>;
   } else {
-    dynModel = (dynModelRaw as string | undefined) || getSubModel() as string | undefined;
+    dynModel = (dynModelRaw as string | undefined) || (getSubModel() as string | undefined);
   }
   return dynModel;
 }
@@ -132,7 +136,10 @@ export function resolveDynamicModelInput(
  * `config.model ?? SUB_AGENT_MODEL ?? MODEL`, throwing with the same message
  * when nothing resolves. Kept here so `Agent` / `SubAgent` share one chain.
  */
-export function resolveSubAgentModel(config: { name?: string; model?: AgentConfig["model"] }): NonNullable<AgentConfig["model"]> {
+export function resolveSubAgentModel(config: {
+  name?: string;
+  model?: AgentConfig["model"];
+}): NonNullable<AgentConfig["model"]> {
   const resolvedModel = config.model ?? getSubModel() ?? getModel();
   if (!resolvedModel) {
     throw new ConfigError(
@@ -191,8 +198,10 @@ export function grantWorkerTools(
     if (declared) poolByNormalized.set(normalizeToolName(declared), def);
   }
   const grantedTools: Record<string, ToolDefinition> = {};
-  for (const toolName of ((requested as string[] | undefined) ?? [])) {
-    const pooled = (toolPool as Record<string, ToolDefinition>)[toolName] ?? poolByNormalized.get(normalizeToolName(String(toolName)));
+  for (const toolName of (requested as string[] | undefined) ?? []) {
+    const pooled =
+      (toolPool as Record<string, ToolDefinition>)[toolName] ??
+      poolByNormalized.get(normalizeToolName(String(toolName)));
     if (pooled) grantedTools[(pooled as ToolDefinition).name || toolName] = pooled;
   }
   return grantedTools;
@@ -205,9 +214,9 @@ function providerOf(modelStr: string | unknown | undefined): string | undefined
     const m =
       typeof modelStr === "string"
         ? modelStr
-        : (modelStr as { model?: unknown; id?: unknown })?.model ??
+        : ((modelStr as { model?: unknown; id?: unknown })?.model ??
           (modelStr as { id?: unknown })?.id ??
-          String(modelStr);
+          String(modelStr));
     return resolveModel(m as string).provider.id;
   } catch {
     return undefined;
@@ -225,9 +234,9 @@ export function resolveWorkerCredentials(
   const chosenModelStrForProvider =
     typeof chosenModel === "string"
       ? chosenModel
-      : (chosenModel as { model?: unknown; id?: unknown })?.model ??
+      : ((chosenModel as { model?: unknown; id?: unknown })?.model ??
         (chosenModel as { id?: unknown })?.id ??
-        String(chosenModel);
+        String(chosenModel));
   const attemptedProvider = providerOf(chosenModelStrForProvider);
   const parentProvider = providerOf(parentAgent.modelStringOrSpec as string);
   const targetProviderFinal = providerOf(chosenModelStrForProvider);
@@ -380,10 +389,18 @@ export function createLiveWorker(
         trace.steps.push({ turn: turn.turns, type: "tool_result", name: tr.name, isError: tr.isError, timestamp });
       }
       trace.turns = Math.max(trace.turns, turn.turns);
-      try { hooks.trim?.(trace); } catch {}
-      try { hooks.touch?.(trace.trackingId); } catch {}
-      try { hooks.notify?.(trackingId); } catch {}
-      try { hooks.persist?.(); } catch {}
+      try {
+        hooks.trim?.(trace);
+      } catch {}
+      try {
+        hooks.touch?.(trace.trackingId);
+      } catch {}
+      try {
+        hooks.notify?.(trackingId);
+      } catch {}
+      try {
+        hooks.persist?.();
+      } catch {}
     } catch {}
   };
 
@@ -409,8 +426,12 @@ export function createLiveWorker(
         entry.thinking = partialThinking;
         entry.timestamp = Date.now();
       }
-      try { hooks.trim?.(trace); } catch {}
-      try { hooks.notify?.(trackingId); } catch {}
+      try {
+        hooks.trim?.(trace);
+      } catch {}
+      try {
+        hooks.notify?.(trackingId);
+      } catch {}
       try {
         hooks.emit?.({
           trackingId: displayId,
@@ -429,11 +450,19 @@ export function createLiveWorker(
   }): (() => void) => {
     const textListener = (e: { delta?: string }): void => onWorkerDelta(e.delta, undefined);
     const thinkingListener = (e: { thinkingDelta?: string }): void => onWorkerDelta(undefined, e.thinkingDelta);
-    try { workerStream.on("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
-    try { workerStream.on("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
+    try {
+      workerStream.on("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+    } catch {}
+    try {
+      workerStream.on("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+    } catch {}
     return () => {
-      try { workerStream.off("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
-      try { workerStream.off("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
+      try {
+        workerStream.off("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+      } catch {}
+      try {
+        workerStream.off("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+      } catch {}
     };
   };
 

package/src/agent/workers.ts

@@ -15,7 +15,13 @@ import { sessionDirFor, loadSessionDir } from "../session/store.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { hashSessionPart, newRunId, newTurnId, nowMs } from "../utils/session.ts";
 import { buildDynamicWorkerConfig, grantWorkerTools, sanitizeToolName } from "./worker.ts";
-import { createFixedChildSessionId, openWorkerTrace, reserveSpawn, workerMetadata, type WorkerRunResult } from "./delegation.ts";
+import {
+  createFixedChildSessionId,
+  openWorkerTrace,
+  reserveSpawn,
+  workerMetadata,
+  type WorkerRunResult,
+} from "./delegation.ts";
 import { finishedTurns, historyUpTo, type Turn } from "./turns.ts";
 import { modelName, readUsage, type UsageNode } from "../session/usage.ts";
 
@@ -59,7 +65,13 @@ export interface WorkerCallOptions {
   /** The calling tool call's id: makes the call exactly-once across a crash and replay (the `subagents` tool passes it). */
   callId?: string;
   /** Receives the worker's live text and thinking deltas. */
-  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
+  onSubagentEvent?: (event: {
+    trackingId: string;
+    delta?: string;
+    thinkingDelta?: string;
+    partialText?: string;
+    partialThinking?: string;
+  }) => void;
 }
 
 // Saved in `worker.json`: everything needed to rebuild a worker after a restart.
@@ -104,7 +116,11 @@ function lastAssistantText(messages: Message[]): string | undefined {
 }
 
 // Reads a worker that is not in memory from its folder: its saved spending, model, and the workers saved inside it; in: a worker's session folder, out: usageNodes.
-function readSavedWorker(dir: string | undefined): { model: string; totals: ReturnType<typeof readUsage>; workers: UsageNode[] } {
+function readSavedWorker(dir: string | undefined): {
+  model: string;
+  totals: ReturnType<typeof readUsage>;
+  workers: UsageNode[];
+} {
   if (!dir) return { model: "unknown", totals: readUsage(undefined), workers: [] };
   let session: ReturnType<typeof loadSessionDir>;
   try {
@@ -125,7 +141,15 @@ function readSavedWorker(dir: string | undefined): { model: string; totals: Retu
     try {
       const meta = JSON.parse(fs.readFileSync(path.join(root, d.name, META_FILE), "utf8")) as WorkerMeta;
       const inner = readSavedWorker(path.join(root, d.name));
-      workers.push({ id: meta.id, name: meta.name, ...(meta.role ? { role: meta.role } : {}), model: inner.model, status: meta.status, totals: inner.totals, workers: inner.workers });
+      workers.push({
+        id: meta.id,
+        name: meta.name,
+        ...(meta.role ? { role: meta.role } : {}),
+        model: inner.model,
+        status: meta.status,
+        totals: inner.totals,
+        workers: inner.workers,
+      });
     } catch {
       // a damaged worker.json is skipped, as in load()
     }
@@ -167,10 +191,15 @@ export class WorkerRegistry {
       const dir = path.join(root, d.name);
       try {
         const meta = JSON.parse(fs.readFileSync(path.join(dir, META_FILE), "utf8")) as WorkerMeta;
-        if (typeof meta.id !== "string" || typeof meta.sessionId !== "string" || !Array.isArray(meta.tools)) throw new Error("missing fields");
+        if (typeof meta.id !== "string" || typeof meta.sessionId !== "string" || !Array.isArray(meta.tools))
+          throw new Error("missing fields");
         this.entries.set(meta.id, { meta, dir, busy: false });
       } catch (err) {
-        telemetryBus.emitWarning("worker.invalid", `[Agent Accelerator] ${path.join(dir, META_FILE)} is not a valid worker and is skipped: ${err instanceof Error ? err.message : String(err)}`, { dir });
+        telemetryBus.emitWarning(
+          "worker.invalid",
+          `[Agent Accelerator] ${path.join(dir, META_FILE)} is not a valid worker and is skipped: ${err instanceof Error ? err.message : String(err)}`,
+          { dir }
+        );
       }
     }
   }
@@ -219,11 +248,17 @@ export class WorkerRegistry {
   /** Closes a worker: it can no longer be messaged, its session stays on disk (and in `usageReport`). */
   close(id: string): WorkerInfo {
     const entry = this.open(id);
-    if (entry.busy) throw new ValidationError(`Worker "${id}" is busy with a call; wait for it to finish before closing it.`);
+    if (entry.busy)
+      throw new ValidationError(`Worker "${id}" is busy with a call; wait for it to finish before closing it.`);
     entry.meta.status = "closed";
     entry.meta.closedAt = Date.now();
     this.save(entry);
-    if (entry.agent) entry.kept = { model: modelName(entry.agent.modelStringOrSpec), totals: readUsage(entry.agent.usageTotals), workers: entry.agent.workers.usageNodes() };
+    if (entry.agent)
+      entry.kept = {
+        model: modelName(entry.agent.modelStringOrSpec),
+        totals: readUsage(entry.agent.usageTotals),
+        workers: entry.agent.workers.usageNodes(),
+      };
     entry.agent?.disposeSession(entry.meta.sessionId); // frees its provider chain; never reset(): that could rewrite the saved history
     entry.agent = undefined;
     return this.info(entry);
@@ -244,7 +279,13 @@ export class WorkerRegistry {
     return [...this.entries.values()].map((entry) => {
       const { id, name, role, status } = entry.meta;
       const base = { id, name, ...(role ? { role } : {}), status };
-      if (entry.agent) return { ...base, model: modelName(entry.agent.modelStringOrSpec), totals: entry.agent.usageTotals, workers: entry.agent.workers.usageNodes() };
+      if (entry.agent)
+        return {
+          ...base,
+          model: modelName(entry.agent.modelStringOrSpec),
+          totals: entry.agent.usageTotals,
+          workers: entry.agent.workers.usageNodes(),
+        };
       return { ...base, ...(entry.kept ?? readSavedWorker(entry.dir)) };
     });
   }
@@ -253,7 +294,8 @@ export class WorkerRegistry {
   private open(id: string): Entry {
     const entry = this.entries.get(id);
     if (!entry) throw new ValidationError(`No worker with id "${id}". Use list to see the open workers.`);
-    if (entry.meta.status === "closed") throw new ValidationError(`Worker "${id}" is closed. Spawn a new worker instead.`);
+    if (entry.meta.status === "closed")
+      throw new ValidationError(`Worker "${id}" is closed. Spawn a new worker instead.`);
     return entry;
   }
 
@@ -264,7 +306,13 @@ export class WorkerRegistry {
   }
 
   // Checks a new worker's request, builds its Agent (seeded with the copied history) and saves `worker.json`; in: spawn, out: a new open entry.
-  private async create(id: string, name: string, task: string, key: string | undefined, spec: WorkerSpec): Promise<Entry> {
+  private async create(
+    id: string,
+    name: string,
+    task: string,
+    key: string | undefined,
+    spec: WorkerSpec
+  ): Promise<Entry> {
     const parent = this.parent;
     if (!parent.subagentModel) {
       throw new ConfigError(
@@ -273,7 +321,11 @@ export class WorkerRegistry {
     }
     const maxOpen = parent.dynamicSubagents?.maxSpawn ?? Infinity;
     if (this.list().length >= maxOpen) {
-      throw new ValidationError(`Too many open workers (${maxOpen} is the limit). Close one first; open workers: ${this.list().map((w) => w.id).join(", ")}.`);
+      throw new ValidationError(
+        `Too many open workers (${maxOpen} is the limit). Close one first; open workers: ${this.list()
+          .map((w) => w.id)
+          .join(", ")}.`
+      );
     }
     const pool = parent.dynamicSubagents?.tools ?? {};
     const requested = spec.tools ?? [];
@@ -281,7 +333,8 @@ export class WorkerRegistry {
     if (unknown.length > 0) {
       const names = Object.keys(pool);
       throw new ValidationError(
-        `tools: unknown worker tool(s) ${unknown.map((n) => `"${n}"`).join(", ")}; ` + (names.length > 0 ? `the pool is [${names.join(", ")}].` : "no worker tools are available, omit tools.")
+        `tools: unknown worker tool(s) ${unknown.map((n) => `"${n}"`).join(", ")}; ` +
+          (names.length > 0 ? `the pool is [${names.join(", ")}].` : "no worker tools are available, omit tools.")
       );
     }
     const history = spec.history ?? "none";
@@ -338,8 +391,16 @@ export class WorkerRegistry {
   }
 
   // Sends one text to a worker and turns what happens into a reply: runs it, or after a crash continues the cut-off run or returns the answer it had already given; in: spawn and message, out: a WorkerReply.
-  private async deliver(entry: Entry, text: string, key: string | undefined, opts: WorkerCallOptions): Promise<WorkerReply> {
-    if (entry.busy) throw new ValidationError(`Worker "${entry.meta.id}" is busy with another call; wait for it, or message another worker.`);
+  private async deliver(
+    entry: Entry,
+    text: string,
+    key: string | undefined,
+    opts: WorkerCallOptions
+  ): Promise<WorkerReply> {
+    if (entry.busy)
+      throw new ValidationError(
+        `Worker "${entry.meta.id}" is busy with another call; wait for it, or message another worker.`
+      );
     entry.busy = true;
     const { meta } = entry;
     const startTime = nowMs();
@@ -354,14 +415,24 @@ export class WorkerRegistry {
         parent: this.parent,
         emit: opts.onSubagentEvent,
       });
-      const lineage = { name: meta.name, displayId: live.displayId, sessionId: meta.sessionId, parentSessionId: this.parent.sessionId, role: meta.role, task: text, runId: newRunId(), turnId: newTurnId() };
+      const lineage = {
+        name: meta.name,
+        displayId: live.displayId,
+        sessionId: meta.sessionId,
+        parentSessionId: this.parent.sessionId,
+        role: meta.role,
+        task: text,
+        runId: newRunId(),
+        turnId: newTurnId(),
+      };
       const replayed = this.isReplay(entry, key, text) && agent.runMarks.length > meta.last!.marks;
       if (!replayed) {
         if (key) meta.last = { key, text: hashSessionPart(text), marks: agent.runMarks.length };
         else delete meta.last;
         this.save(entry);
       }
-      const onAbort = (): void => agent.interrupt(opts.signal?.reason instanceof Error ? opts.signal.reason : undefined);
+      const onAbort = (): void =>
+        agent.interrupt(opts.signal?.reason instanceof Error ? opts.signal.reason : undefined);
       try {
         if (opts.signal?.aborted) throw new Error("aborted before the worker started");
         opts.signal?.addEventListener("abort", onAbort, { once: true });
@@ -387,14 +458,36 @@ export class WorkerRegistry {
           if (!response) throw new Error("the worker had nothing to resume");
           result = response;
         }
-        const reply = result.text.trim() ? result.text : `(the worker produced no text${result.finishReason ? `; finish reason: ${result.finishReason}` : ""})`;
+        const reply = result.text.trim()
+          ? result.text
+          : `(the worker produced no text${result.finishReason ? `; finish reason: ${result.finishReason}` : ""})`;
         live.finish(result);
-        return { id: meta.id, text: reply, metadata: workerMetadata({ ...lineage, durationMs: Math.max(0, nowMs() - startTime), result, steps: live.steps() }) };
+        return {
+          id: meta.id,
+          text: reply,
+          metadata: workerMetadata({
+            ...lineage,
+            durationMs: Math.max(0, nowMs() - startTime),
+            result,
+            steps: live.steps(),
+          }),
+        };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         live.fail(message);
         const errorText = `Error in worker ${meta.id}: ${message}`;
-        return { id: meta.id, text: errorText, error: message, metadata: workerMetadata({ ...lineage, durationMs: Math.max(0, nowMs() - startTime), error: message, errorText, steps: live.steps() }) };
+        return {
+          id: meta.id,
+          text: errorText,
+          error: message,
+          metadata: workerMetadata({
+            ...lineage,
+            durationMs: Math.max(0, nowMs() - startTime),
+            error: message,
+            errorText,
+            steps: live.steps(),
+          }),
+        };
       } finally {
         opts.signal?.removeEventListener("abort", onAbort);
       }

package/src/architecture.md

@@ -2,24 +2,25 @@
 
 The whole SDK. `index.ts` is the only public entry (`main`/`module`/`types`); everything else is reached through it.
 
-| File / folder | What it is |
-| :-- | :-- |
-| `index.ts` | The public barrel. Adding or removing an export is a public API change. |
-| `telemetry.ts` | The in-process event bus (`telemetryBus`). Imports nothing from the SDK, so any module may use it. |
+| File / folder       | What it is                                                                                                                                                                  |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts`          | The public barrel. Adding or removing an export is a public API change.                                                                                                     |
+| `telemetry.ts`      | The in-process event bus (`telemetryBus`). Imports nothing from the SDK, so any module may use it.                                                                          |
 | `telemetry-file.ts` | Opt-in NDJSON sink for the bus: a persisted session's events go to `<session folder>/telemetry.ndjson`, the rest to `<home>/telemetry/<date>.ndjson`; never outside a home. |
-| `update-models.ts` | CLI behind `bun run update-models` (refreshes the model catalog cache). |
-| `providers.ts` | Provider-agnostic mappers (thinking, cache, tool choice, structured output, generation params). No HTTP. |
-| `agent/` | `Agent`, the model-to-tools loop, workers, delegation. |
-| `providers/` | One adapter per wire (Google, OpenAI, OpenRouter, OpenAI-compatible), the registry, shared helpers. |
-| `models/` | The model catalog (models.dev) and its cache. |
-| `tools/` | `tool()`, schemas, the executor. |
-| `streaming/` | The event stream and the SSE parser. |
-| `session/` | Persistence (snapshot + journal), usage accounting, tool logs. |
-| `scheduler/` | Scheduled actions. |
-| `types/` | Shared contracts (no logic except small helpers). |
-| `utils/` | Small shared helpers (durable writes, home, env, media, retry, safe I/O). |
+| `update-models.ts`  | CLI behind `bun run update-models` (refreshes the model catalog cache).                                                                                                     |
+| `providers.ts`      | Provider-agnostic mappers (thinking, cache, tool choice, structured output, generation params). No HTTP.                                                                    |
+| `agent/`            | `Agent`, the model-to-tools loop, workers, delegation.                                                                                                                      |
+| `providers/`        | One adapter per wire (Google, OpenAI, OpenRouter, OpenAI-compatible), the registry, shared helpers.                                                                         |
+| `models/`           | The model catalog (models.dev) and its cache.                                                                                                                               |
+| `tools/`            | `tool()`, schemas, the executor.                                                                                                                                            |
+| `streaming/`        | The event stream and the SSE parser.                                                                                                                                        |
+| `session/`          | Persistence (snapshot + journal), usage accounting, tool logs.                                                                                                              |
+| `scheduler/`        | Scheduled actions.                                                                                                                                                          |
+| `types/`            | Shared contracts (no logic except small helpers).                                                                                                                           |
+| `utils/`            | Small shared helpers (durable writes, home, env, media, retry, safe I/O).                                                                                                   |
 
 ## Rules for every file here
+
 - Imports use `.ts` extensions; type-only imports use `import type`.
 - No `console.*`: warnings and traces go to `telemetryBus` (exceptions: the `update-models.ts` CLI and one compat `console.warn` in `providers.ts`).
 - All state is written under the one home folder (`utils/home.ts`). Files are replaced through `utils/durable.ts`; the append-only ones are the session journal and tool logs (fsynced per line) and the opt-in telemetry file (not fsynced).