agent-accelerator 0.5.9 → 0.6.0

package/src/agent/architecture.md

@@ -2,20 +2,21 @@
 
 The agent and everything that runs under it.
 
-| File | What it is | Used by |
-| :-- | :-- | :-- |
-| `agent.ts` | `Agent`: `run`/`stream`/`ask`, `steer`/`queue`/`interrupt`, persistence hooks, `resume()`/`interrupted()`, `usageReport()`, `fork()`, `toConfig()`/`fromConfig()`, the `workers` getter. | callers, workers, scheduler |
-| `loop.ts` | `runAgentLoop` / `streamAgentLoop`: per turn budget, pairing repair, file access, provider call, tool execution, repeat guard. Also `ensureToolPairing`, `accumulateUsage`. | `Agent` |
-| `context.ts` | `AgentContext`: the validated message list with checkpoint/rollback. | `Agent`, loops |
-| `delegation.ts` | Fixed workers (`agentToTool`, `buildAgentTools`), the live worker trace store, session-id helpers, budget helpers, `openWorkerTrace`/`workerMetadata`. | `Agent`, `workers.ts` |
-| `worker.ts` | Worker core: model/tool normalization, `buildDynamicWorkerConfig` (shared preset), `createLiveWorker`. | `Agent`, registry, scheduler |
-| `workers.ts` | `WorkerRegistry` (`agent.workers`): persistent multi-turn workers. | `Agent`, `subagents` tool |
-| `subagents-tool.ts` + `subagents.md` | The one model-facing `subagents` tool; the `.md` is its description. | `Agent` constructor |
-| `subagent.ts` | `SubAgent` class and `agentFromEnv` (thin, kept for compatibility). | callers |
-| `turns.ts` | Pure grouping of messages into finished turns (history cut for workers). | `workers.ts` |
-| `config-blocks.ts` | RSI blocks: only `model`, `instructions`, `tools` are editable; `allowedModels` check. | `Agent` |
+| File                                 | What it is                                                                                                                                                                               | Used by                      |
+| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- |
+| `agent.ts`                           | `Agent`: `run`/`stream`/`ask`, `steer`/`queue`/`interrupt`, persistence hooks, `resume()`/`interrupted()`, `usageReport()`, `fork()`, `toConfig()`/`fromConfig()`, the `workers` getter. | callers, workers, scheduler  |
+| `loop.ts`                            | `runAgentLoop` / `streamAgentLoop`: per turn budget, pairing repair, file access, provider call, tool execution, repeat guard. Also `ensureToolPairing`, `accumulateUsage`.              | `Agent`                      |
+| `context.ts`                         | `AgentContext`: the validated message list with checkpoint/rollback.                                                                                                                     | `Agent`, loops               |
+| `delegation.ts`                      | Fixed workers (`agentToTool`, `buildAgentTools`), the live worker trace store, session-id helpers, budget helpers, `openWorkerTrace`/`workerMetadata`.                                   | `Agent`, `workers.ts`        |
+| `worker.ts`                          | Worker core: model/tool normalization, `buildDynamicWorkerConfig` (shared preset), `createLiveWorker`.                                                                                   | `Agent`, registry, scheduler |
+| `workers.ts`                         | `WorkerRegistry` (`agent.workers`): persistent multi-turn workers.                                                                                                                       | `Agent`, `subagents` tool    |
+| `subagents-tool.ts` + `subagents.md` | The one model-facing `subagents` tool; the `.md` is its description.                                                                                                                     | `Agent` constructor          |
+| `subagent.ts`                        | `SubAgent` class and `agentFromEnv` (thin, kept for compatibility).                                                                                                                      | callers                      |
+| `turns.ts`                           | Pure grouping of messages into finished turns (history cut for workers).                                                                                                                 | `workers.ts`                 |
+| `config-blocks.ts`                   | RSI blocks: only `model`, `instructions`, `tools` are editable; `allowedModels` check.                                                                                                   | `Agent`                      |
 
 ## Invariants
+
 - `runAgentLoop` and `streamAgentLoop` duplicate their turn logic: every loop change goes into both.
 - An `Agent` runs one thing at a time; delegation forks a copy per call so parallel calls never queue.
 - A worker is a plain `Agent` with a parent link and presets. Never duplicate logic between Agent and worker.

package/src/agent/config-blocks.ts

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

package/src/agent/context.ts

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

package/src/agent/delegation.ts

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