agent-accelerator 0.5.6 → 0.5.7

package/README.md

@@ -386,6 +386,8 @@ telemetryBus.onEvent((e) => {
 | `skipScheduledAction(id, { home? })` | Ignore a missed run and wait for the next scheduled time. |
 | `deleteScheduledAction(id, { force?, purge?, home? })` | Delete for good. While it is cooking nothing changes unless `force: true`; `purge: true` also deletes past run files. |
 
+Every function except `createScheduledAction` finds the home folder through `setHome()`, `AGENT_ACCEL_HOME`, or `.agent-accel/` in the working directory. If you built the Agent with its own `home`, pass the same `{ home }` to these calls (the model's `scheduled_actions` tool already does).
+
 **How it behaves**
 
 * **One local clock.** A single timer per home folder (guarded by a one-process lock, `<home>/.lock`) ticks once a second against the machine's own time and only asks what is overdue, so drift or sleep cannot skip a run. There is no timezone or daylight-saving logic. The timer is `unref`'d and runs only while something is pending, so actions run only while your process is alive.
@@ -657,7 +659,7 @@ Implement the `Provider` interface when adding a fully custom transport.
 
 ### Google
 
-`GoogleInteractionsProvider` (aliased as `GoogleAIStudioProvider`) and `GOOGLE_MODELS` provide Google support over the Interactions API (`POST {baseUrl}/interactions`, streaming via `?alt=sse`).
+`GoogleInteractionsProvider` and `GOOGLE_MODELS` provide Google support over the Interactions API (`POST {baseUrl}/interactions`, streaming via `?alt=sse`).
 
 Turns chain statefully through `previous_interaction_id` per session, falling back to stateless full-history sends when the session switches providers or models.
 
@@ -683,7 +685,7 @@ Helpers:
 
 ### OpenAI
 
-`OpenAIResponsesProvider` (aliased as `OpenAIProvider`) and `OPENAI_MODELS` provide OpenAI support over the Responses API (`POST {baseUrl}/responses`).
+`OpenAIResponsesProvider` and `OPENAI_MODELS` provide OpenAI support over the Responses API (`POST {baseUrl}/responses`).
 
 Every turn is stateless: the full history is sent explicitly with `store: false`, so no `previous_response_id`, `background`, or conversation chaining is ever used.
 
@@ -702,7 +704,7 @@ It also:
 
 ### OpenRouter
 
-`OpenRouterChatCompletionsProvider` (aliased as `OpenRouterProvider` / `OpenRouter`) and `OPENROUTER_MODELS` provide OpenRouter support over Chat Completions (`POST {baseUrl}/chat/completions`).
+`OpenRouterChatCompletionsProvider` and `OPENROUTER_MODELS` provide OpenRouter support over Chat Completions (`POST {baseUrl}/chat/completions`).
 
 Every turn is stateless: the full `messages[]` array is sent explicitly — no chaining primitives exist on this endpoint.
 
@@ -731,7 +733,7 @@ setAttribution({ referer: "https://my.app", title: "My App" });
 
 ### Custom
 
-`OpenAICompatibleProvider` is also exposed through the `CustomProvider`, `createCustomProvider`, and `createOpenAICompatibleProvider(prefix, opts?)` aliases.
+`OpenAICompatibleChatProvider` is also exposed through the `CustomProvider`, `createCustomProvider`, and `createOpenAICompatibleProvider(prefix, opts?)` aliases.
 
 `CustomProviderOptions`:
 
@@ -931,15 +933,6 @@ Use:
 Breaking out of `for await` cancels the stream. Your `AbortSignal` and stream cancellation share one linked controller, so `controller.abort()` and `stream.cancel()` both stop the HTTP request. Abort rejects with `AbortError` (never retried) and never resolves partial results. `agent.run(prompt, { stream: true, signal })` exposes the same
 `cancel` handle.
 
-`SSEParser` provides:
-
-```ts
-feed(chunk)
-flush()
-```
-
-It parses provider SSE streams and is only needed when implementing custom transports.
-
 ---
 ## Response, Usage, and Raw Data
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "High-performance SDK for AI agents with a unified API across AI providers. Optimized for high cache hit rates, observability, and seamless agent orchestration. Built to power production-grade agentic systems and harnesses for teams at any scale.",
   "license": "MIT",
   "author": "Sashvat Bharat",

package/src/agent/agent.ts

@@ -29,7 +29,7 @@ import { applyEditable, assertModelAllowed, modelKey, toEditableConfig } from ".
 import { assertNoToolCollisions } from "../tools/executor.ts";
 import { runAgentLoop, streamAgentLoop, unfinishedToolCalls, endsWithStop, accumulateUsage, type SteerEntry } from "./loop.ts";
 import { isRetryableRun, readRetryAfterMs, sleep } from "../utils/retry.ts";
-import { createSessionId, nowMs, newRunId } from "../utils/session.ts";
+import { createSessionId, nowMs, newRunId, previewPrompt } from "../utils/session.ts";
 import {
   chargeBudgetUsage,
   checkBudget,
@@ -590,7 +590,7 @@ export class Agent {
       .map((m) => ({
         runId: m.id,
         startedAt: m.at,
-        prompt: this.previewPrompt((this.context.messages[m.i]?.content ?? "") as string | ContentPart[]),
+        prompt: previewPrompt((this.context.messages[m.i]?.content ?? "") as string | ContentPart[]),
         pendingToolCalls: calls,
       }));
   }
@@ -652,6 +652,7 @@ export class Agent {
     this.doPersist();
   }
 
+  // Builds the system prompt: the developer's instructions plus, when thinking is on, the fixed Reasoning Directive; in: this.instructions + thinkingConfig, out: every AgentContext.systemPrompt.
   private getFullInstructions(): string | undefined {
     const base = this.instructions || "";
     let out = base;
@@ -799,12 +800,14 @@ export class Agent {
     return this.midSessionConfig.mode;
   }
 
+  // Picks steer or queue for a call that arrives while busy: the developer's enforced midSession mode wins over the per-call request; in: run()/stream() `enqueue`, out: their busy branch.
   private resolveEnqueueMode(requested?: "steer" | "queue"): "steer" | "queue" {
     const enforced = this.midSessionConfig.mode;
     if (enforced === "steer" || enforced === "queue") return enforced;
     return requested === "steer" ? "steer" : "queue";
   }
 
+  // Throws synchronously on an empty content-part array so run() and stream() fail at the same moment; in: any prompt entry point, out: nothing.
   private assertPromptValid(prompt: string | ContentPart[]): void {
     if (Array.isArray(prompt) && prompt.length === 0) {
       throw new Error(
@@ -813,19 +816,6 @@ export class Agent {
     }
   }
 
-  private previewPrompt(prompt: string | ContentPart[]): string {
-    if (typeof prompt === "string") return prompt.slice(0, 500);
-    try {
-      const texts = prompt
-        .filter((p) => (p as { type?: unknown }).type === "text")
-        .map((p) => (p as { text?: string }).text ?? "")
-        .join("\n");
-      return (texts || "[multipart]").slice(0, 500);
-    } catch {
-      return "[multipart]";
-    }
-  }
-
   /**
    * Stops the active run now (STOP.) and, given a message, starts it next (STOP. Do this instead). The provider
    * request is aborted (connection closed, so the provider stops generating where it can), the stream is cancelled, and
@@ -961,13 +951,14 @@ export class Agent {
       try {
         this.currentRun?.outerStream?.push({
           type: "queued",
-          queuedPrompt: this.previewPrompt(prompt),
+          queuedPrompt: previewPrompt(prompt),
           queueLength: this.pendingQueue.length,
         } as any);
       } catch {}
     });
   }
 
+  // Starts the next waiting prompt (urgent ones first, aborted ones rejected) as a streaming or non-streaming run once the agent is idle; in: finishCurrentRun and queue changes, out: a new run whose result settles the queued caller.
   private pumpQueue(): void {
     if (this.currentRun !== null) return;
     const next = this.pendingQueue.shift();
@@ -1023,6 +1014,7 @@ export class Agent {
     this.startNonStreamingRun(next.prompt, next.options).then(next.resolve, next.reject);
   }
 
+  // Ends the active run slot: leftover steers become follow-ups at the FRONT of the queue (behind urgent ones), then the queue is pumped; in: a settled run, out: pendingQueue + persistNow.
   private finishCurrentRun(): void {
     // Q-20: leftover steer entries become queued follow-ups instead of dropping.
     let leftover: SteerEntry[] = [];
@@ -1065,6 +1057,7 @@ export class Agent {
     queueMicrotask(() => this.pumpQueue());
   }
 
+  // Removes the abort listener a run's merged signal fallback installed; in: a settled run's controller, out: nothing.
   private cleanupMerge(runController: AbortController): void {
     try {
       const dispose = mergeDisposers.get(runController);
@@ -1075,6 +1068,7 @@ export class Agent {
     } catch {}
   }
 
+  // Joins the caller's AbortSignal with the run's own controller (AbortSignal.any, else a manual forward) so both stop the run; in: AgentRunOptions.signal + the run controller, out: the signal handed to the loop.
   private mergeUserSignal(userSignal?: AbortSignal, runController?: AbortController): AbortSignal | undefined {
     if (!runController) return userSignal;
     if (!userSignal) return runController.signal;
@@ -1227,6 +1221,7 @@ export class Agent {
     };
   }
 
+  // Runs one non-streaming run as a task: catalog refresh, model resolve, prompt/mark (or a resumed mark), loop with `runRetries` backoff, trace merge, run ending recorded; in: run()/queue/resume(), out: the AgentResponse promise.
   private startNonStreamingRun(
     prompt: string | ContentPart[],
     options?: AgentRunOptions,
@@ -1328,6 +1323,7 @@ export class Agent {
     return task;
   }
 
+  // Starts one streaming run: validates the model and thinking level synchronously, adds the prompt, builds the loop config and returns the loop's event stream, recording the run ending when it settles; in: stream()/pumpQueue, out: an AssistantMessageEventStream.
   private startStreamingRun(
     prompt: string | ContentPart[],
     options?: AgentRunOptions
@@ -1655,6 +1651,7 @@ export class Agent {
     } catch {}
   }
 
+  // Adds the user prompt to the target context (fresh context when stateless, stable system prompt, additionalContext as a user prefix) and marks the run start for the default session; in: a run start, out: the new SessionRunMark.
   private prepareTurn(prompt: string | ContentPart[], options?: AgentRunOptions, target?: AgentContext): SessionRunMark | undefined {
     // Q-20: prompt validation throws synchronously in both run() and
     // stream() (same timing; documented here).
@@ -1791,7 +1788,7 @@ export class Agent {
           try {
             this.currentRun?.outerStream?.push({
               type: "queued",
-              queuedPrompt: this.previewPrompt(prompt),
+              queuedPrompt: previewPrompt(prompt),
               queueLength: this.pendingQueue.length,
             } as any);
           } catch {}
@@ -1933,7 +1930,7 @@ export class Agent {
         try {
           this.currentRun.outerStream?.push({
             type: "queued",
-            queuedPrompt: this.previewPrompt(prompt),
+            queuedPrompt: previewPrompt(prompt),
             queueLength: this.pendingQueue.length + 1,
           } as any);
         } catch {}
@@ -2008,6 +2005,7 @@ export class Agent {
     return s;
   }
 
+  // Attaches onEvent/onDelta/onThinkingDelta to a stream and, with wrapThinking, adds display-only <think> tags and whitespace hygiene on the outer events; in: stream()/pumpQueue, out: listeners on the stream.
   private wireStreamCallbacks(
     s: AssistantMessageEventStream,
     options?: AgentRunOptions

package/src/agent/architecture.md

@@ -0,0 +1,25 @@
+# src/agent/
+
+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` |
+
+## Invariants
+- `runAgentLoop` and `streamAgentLoop` duplicate their turn logic: every loop change goes into both.
+- An `Agent` runs one thing at a time; delegation forks a copy per call so parallel calls never queue.
+- A worker is a plain `Agent` with a parent link and presets. Never duplicate logic between Agent and worker.
+- A worker is never less constrained than its parent (`inheritableConfig()`); its children draw only from the tools it was granted.
+- Exactly-once worker calls rest on the call key (parent run mark id + tool call id) and `meta.last`.
+- Only results branded by `makeSubagentResult` have their usage metadata trusted.
+- Each Agent records only its own model turns; never sum `AgentResponse.usage` for totals.

package/src/agent/context.ts

@@ -6,6 +6,7 @@ import { clearInteractionChains } from "../providers/google.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}`);
 }
@@ -32,6 +33,7 @@ export class AgentContext {
     this.systemPrompt = systemPrompt;
   }
 
+  // Validates a user prompt (string or media/text parts) and appends it; in: Agent.prepareTurn and drained steers, out: messages.
   addUserMessage(content: string | ContentPart[]): void {
     if (Array.isArray(content)) {
       if (content.length === 0) return;
@@ -120,6 +122,7 @@ export class AgentContext {
     }
   }
 
+  // Appends one tool message per result, keeping logFile and stopped marks; in: the loops after a tool batch, out: messages.
   addToolResults(results: ToolResultRecord[]): void {
     if (!results || results.length === 0) return;
     for (let i = 0; i < results.length; i++) {
@@ -145,6 +148,7 @@ export class AgentContext {
     }
   }
 
+  // Copies the context with media bytes preserved (structuredClone, else a deep copy); in: callers needing an isolated history, out: a new AgentContext.
   clone(): AgentContext {
     const next = new AgentContext(this.systemPrompt);
     // Preserve Uint8Array/ArrayBuffer media via structuredClone when available (M8 fix)

package/src/agent/delegation.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { tool } from "../tools/tool.ts";
-import { escapeXml } from "../utils/serialization.ts";
 import type { ToolDefinition } from "../types/tool.ts";
 import type { AgentResponse, SubAgentExecutionMetadata, SubAgentStep } from "../types/response.ts";
 import type { TokenUsage } from "../types/core.ts";
@@ -17,8 +16,7 @@ import { newRunId } from "../utils/session.ts";
 import { newTurnId } from "../utils/session.ts";
 import { sanitizeToolName, createLiveWorker } from "./worker.ts";
 
-export { escapeXml };
-
+/** 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 {
   let rand: string;
   try {
@@ -104,17 +102,18 @@ const subagentTraces = new Map<string, SubAgentTrace>();
 const subagentListeners = new Map<string, Set<(trace: SubAgentTrace) => void>>();
 
 /** Max trace keys held (LRU, evicts oldest whole trace on insert) (Q-30). */
-export const MAX_SUBAGENT_TRACES = 500;
+const MAX_SUBAGENT_TRACES = 500;
 /** Trace TTL: 1h wall-clock, lazily expired on read (Q-30). */
-export const SUBAGENT_TRACE_TTL_MS = 60 * 60 * 1000;
+const SUBAGENT_TRACE_TTL_MS = 60 * 60 * 1000;
 /** Max steps retained per trace; oldest steps are dropped beyond this (Q-30). */
-export const MAX_SUBAGENT_STEPS_PER_TRACE = 100;
+const MAX_SUBAGENT_STEPS_PER_TRACE = 100;
 /** Live subscriptions auto-expire after 5min (Q-30). */
-export const SUBAGENT_SUBSCRIBE_TTL_MS = 5 * 60 * 1000;
+const SUBAGENT_SUBSCRIBE_TTL_MS = 5 * 60 * 1000;
 
 /** Last-write wall-clock per canonical trackingId (drives TTL; reads do not extend it). */
 const traceTouchedAt = new Map<string, number>();
 
+// Removes a trace under all its keys plus its listeners and TTL stamp; in: pruneTraces/lookupTrace, out: the trace store.
 function deleteTraceByCanonical(canonical: string): void {
   for (const [key, t] of [...subagentTraces]) {
     if (t.trackingId === canonical) subagentTraces.delete(key);
@@ -123,12 +122,14 @@ function deleteTraceByCanonical(canonical: string): void {
   subagentListeners.delete(canonical);
 }
 
+// True once a trace was not written for SUBAGENT_TRACE_TTL_MS; in: lookup and prune, out: their expiry decision.
 function isTraceExpired(canonical: string, now = Date.now()): boolean {
   const touched = traceTouchedAt.get(canonical);
   if (touched === undefined) return false;
   return now - touched > SUBAGENT_TRACE_TTL_MS;
 }
 
+// Stamps a trace as just written, which restarts its TTL; in: insert and the live worker hooks, out: traceTouchedAt.
 function touchTrace(canonical: string, now = Date.now()): void {
   traceTouchedAt.set(canonical, now);
 }
@@ -138,7 +139,7 @@ function touchTrace(canonical: string, now = Date.now()): void {
  * Called on every insert. Whole-trace eviction removes both the canonical
  * key and its display-id alias.
  */
-export function pruneTraces(now = Date.now()): void {
+function pruneTraces(now = Date.now()): void {
   for (const canonical of [...new Set([...subagentTraces.values()].map((t) => t.trackingId))]) {
     if (isTraceExpired(canonical, now)) deleteTraceByCanonical(canonical);
   }
@@ -155,12 +156,13 @@ export function pruneTraces(now = Date.now()): void {
 }
 
 /** Drops oldest steps beyond {@link MAX_SUBAGENT_STEPS_PER_TRACE} (Q-30). */
-export function trimTraceSteps(trace: SubAgentTrace): void {
+function trimTraceSteps(trace: SubAgentTrace): void {
   if (trace.steps.length > MAX_SUBAGENT_STEPS_PER_TRACE) {
     trace.steps.splice(0, trace.steps.length - MAX_SUBAGENT_STEPS_PER_TRACE);
   }
 }
 
+// Stores a trace under its tracking id and display id in LRU order, pruning expired and excess traces; in: openWorkerTrace, out: the trace store.
 function insertTrace(trace: SubAgentTrace, displayId: string, now = Date.now()): void {
   pruneTraces(now);
   trimTraceSteps(trace);
@@ -181,6 +183,7 @@ function insertTrace(trace: SubAgentTrace, displayId: string, now = Date.now()):
   pruneTraces(now);
 }
 
+// Finds a trace by tracking id, display id or case-insensitive id, dropping expired ones and refreshing LRU order; in: the scoped getters and subscribe, out: the live trace or undefined.
 function lookupTrace(id: string): SubAgentTrace | undefined {
   if (!id) return undefined;
   const direct = subagentTraces.get(id);
@@ -209,10 +212,12 @@ function lookupTrace(id: string): SubAgentTrace | undefined {
   return undefined;
 }
 
+// Deep-enough copy of a trace (steps and usage) so callers never see live mutation; in: the getters and notifyTrace, out: a detached SubAgentTrace.
 function snapshotTrace(t: SubAgentTrace): SubAgentTrace {
   return { ...t, steps: t.steps.map((s) => ({ ...s })), usage: t.usage ? { ...t.usage } : undefined };
 }
 
+// Sends a snapshot of a trace to its live subscribers, ignoring listener errors; in: the live worker hooks, out: subscriber callbacks.
 function notifyTrace(trackingId: string): void {
   const t = subagentTraces.get(trackingId);
   if (!t) return;
@@ -224,45 +229,6 @@ function notifyTrace(trackingId: string): void {
   }
 }
 
-/**
- * Returns a snapshot of one worker's trace by tracking id
- * (`SUBAGENT-NAME-{32hex}` or the raw 32-hex suffix). Used by
- * `agent.track(id)` for realtime inspection.
- *
- * Prefer {@link getSubAgentTraceScoped} when the parent session is known:
- * this compat lookup matches any parent and can confuse sibling workers
- * whose display names collide across sessions.
- */
-export function getSubAgentTrace(id: string): SubAgentTrace | undefined {
-  const t = lookupTrace(id);
-  return t ? snapshotTrace(t) : undefined;
-}
-
-/**
- * Scoped trace lookup (Q-30, preferred): like {@link getSubAgentTrace} but
- * only matches when `trace.parentSessionId === parentSessionId`. Use this
- * from `Agent.track` (or any parent-bound caller) so truncated/aliased ids
- * cannot leak across sessions.
- */
-export function getSubAgentTraceScoped(id: string, parentSessionId: string): SubAgentTrace | undefined {
-  if (!id || !parentSessionId) return undefined;
-  const t = lookupTrace(id);
-  if (!t) return undefined;
-  if (t.parentSessionId !== parentSessionId) return undefined;
-  return snapshotTrace(t);
-}
-
-/**
- * Lists tracking ids of EVERY worker trace in the process (all agents, all
- * sessions). Diagnostics only: `Agent` never uses it, because in a
- * multi-tenant host it would expose other tenants' workers. Use
- * {@link listSubAgentTraceIdsForSessions} for agent-bound callers.
- */
-export function listSubAgentTraceIds(): string[] {
-  pruneTraces();
-  return [...subagentTraces.keys()];
-}
-
 /** Scoped lookup across a set of parent session ids (an agent's default + named sessions). */
 export function getSubAgentTraceForSessions(
   id: string,
@@ -326,21 +292,6 @@ export function subscribeToSubAgent(id: string, fn: (trace: SubAgentTrace) => vo
   };
 }
 
-/** Appends a step to a worker trace and notifies live subscribers. */
-export function appendSubAgentStep(trackingId: string, step: SubAgentStep): void {
-  const t = subagentTraces.get(trackingId) ?? lookupTrace(trackingId);
-  if (!t) return;
-  if (isTraceExpired(t.trackingId)) {
-    deleteTraceByCanonical(t.trackingId);
-    return;
-  }
-  t.steps.push(step);
-  trimTraceSteps(t);
-  t.turns = Math.max(t.turns, step.turn);
-  touchTrace(t.trackingId);
-  notifyTrace(trackingId);
-}
-
 // ---------------------------------------------------------------------------
 // One worker run: live trace + execution metadata (shared by fixed workers and the worker registry)
 // ---------------------------------------------------------------------------
@@ -523,10 +474,12 @@ export function workerMetadata(a: {
 // clock; TTL timestamps above use wall-clock `Date.now()`.
 // ---------------------------------------------------------------------------
 
+// Reads the agent's configured budget; in: budget helpers, out: Budget or undefined.
 function readBudget(parentAgent: Agent): Budget | undefined {
   return (parentAgent as unknown as { budget?: Budget }).budget;
 }
 
+// Returns the agent's per-run budget counters, creating them on first use; in: charge and reserve helpers, out: BudgetState.
 function ensureBudgetState(parentAgent: Agent): BudgetState {
   const host = parentAgent as unknown as { budgetState?: BudgetState };
   if (!host.budgetState) {
@@ -535,6 +488,7 @@ function ensureBudgetState(parentAgent: Agent): BudgetState {
   return host.budgetState;
 }
 
+// Total tokens of a usage value, defensively (total, else input + output); in: budget helpers, out: a non-negative integer.
 function usageTokens(usage: unknown): number {
   const u = usage as { totalTokens?: unknown; inputTokens?: unknown; outputTokens?: unknown } | undefined;
   if (!u || typeof u !== "object") return 0;
@@ -544,6 +498,7 @@ function usageTokens(usage: unknown): number {
   return Math.max(0, Math.floor(inp + out));
 }
 
+// Reported total cost of a usage value in USD, 0 when absent; in: budget helpers, out: a non-negative number.
 function usageCostUsd(usage: unknown): number {
   const cost = (usage as { cost?: { totalCost?: unknown } } | undefined)?.cost;
   const v = cost?.totalCost;
@@ -634,27 +589,6 @@ export function reserveSpawn(parentAgent: Agent, count = 1): BudgetState {
   return state;
 }
 
-// ---------------------------------------------------------------------------
-// Single core loop note + streaming-loop guard (Q-44, partial).
-// The canonical run/stream loops live in `loop.ts` + `agent.ts` (other
-// owners) and are intentionally NOT duplicated here. This guard exists so
-// future consolidation can branch on streaming handles without importing
-// the loop.
-// ---------------------------------------------------------------------------
-
-/** Minimal shape of a streaming run handle (has subscribe + terminal promise). */
-export interface StreamingLoopHandle {
-  on: (...args: unknown[]) => unknown;
-  result: (...args: unknown[]) => Promise<unknown>;
-}
-
-/** Type guard for streaming-loop handles (Q-44). */
-export function isStreamingLoop(value: unknown): value is StreamingLoopHandle {
-  if (!value || typeof value !== "object") return false;
-  const r = value as Record<string, unknown>;
-  return typeof r["on"] === "function" && typeof r["result"] === "function";
-}
-
 /** Optional name/description wrapper for converting an Agent into a tool. */
 export interface AgentAsToolTarget {
   name?: string;

package/src/agent/loop.ts

@@ -25,6 +25,7 @@ import { enforceFileAccess } from "../utils/safe-io.ts";
 import { isSubagentResult, normalizeSubagentMetadata } from "../tools/subagent-result.ts";
 import { BudgetExceededError } from "../types/errors.ts";
 import { applyCaptureRaw, type CaptureRawMode } from "../utils/raw-capture.ts";
+import { previewPrompt } from "../utils/session.ts";
 import { noteProviderTurn, normalizeStructuredOutput, parseStructuredOutput } from "../providers.ts";
 
 /** One mid-session steer request buffered while a run is active. */
@@ -99,20 +100,6 @@ export interface AgentLoopConfig {
   output?: unknown;
 }
 
-/** Short preview for `steer_injected` / `queued` event payloads (bounded, display-only). */
-function steerPreview(prompt: string | ContentPart[]): string {
-  if (typeof prompt === "string") return prompt.slice(0, 500);
-  try {
-    const texts = prompt
-      .filter((p) => (p as { type?: unknown }).type === "text")
-      .map((p) => (p as { text?: string }).text ?? "")
-      .join("\n");
-    return (texts || "[multipart]").slice(0, 500);
-  } catch {
-    return "[multipart]";
-  }
-}
-
 /**
  * Drains pending steer entries into the conversation as new user messages.
  * Returns display previews for events/telemetry. Never throws: invalid
@@ -133,7 +120,7 @@ function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[]): string[]
         else prompt = [{ type: "text", text: prefix } as ContentPart, ...prompt];
       }
       context.addUserMessage(prompt);
-      injected.push(steerPreview(entry.prompt));
+      injected.push(previewPrompt(entry.prompt));
     } catch {
       continue;
     }
@@ -141,6 +128,7 @@ function drainSteerInbox(context: AgentContext, inbox?: SteerEntry[]): string[]
   return injected;
 }
 
+// Reports one finished turn to the caller's onTurn hook (ids only), never throwing; in: both loops, out: AgentRunOptions.onTurn.
 function emitTurn(
   runOptions: AgentRunOptions | undefined,
   turn: { turns: number; text?: string; thinking?: string; toolCalls?: ToolCallRecord[]; toolResults?: ToolResultRecord[] }
@@ -183,6 +171,7 @@ function shouldRollbackOnFailure(
   return !toolsExecuted;
 }
 
+// Calls the persistence checkpoint hook, never throwing; in: both loops after each step, out: Agent.persistNow.
 function emitProgress(config: { onProgress?: () => void }): void {
   try { config.onProgress?.(); } catch {}
 }
@@ -191,6 +180,7 @@ function emitProgress(config: { onProgress?: () => void }): void {
 // Structured outputs (canonical output wiring for the loop).
 // ---------------------------------------------------------------------------
 
+// Normalizes the structured-output option once per run (raw value + provider spec); in: AgentLoopConfig.output, out: the final-answer validation.
 function resolveLoopOutput(config: AgentLoopConfig): { raw: unknown; spec: import("../types/model.ts").StructuredOutputSpec | undefined } {
   const raw = (config as { output?: unknown }).output;
   const fromOptions = (config.options as { output?: import("../types/model.ts").StructuredOutputSpec } | undefined)?.output;
@@ -204,6 +194,7 @@ function resolveLoopOutput(config: AgentLoopConfig): { raw: unknown; spec: impor
   return { raw: undefined, spec: undefined };
 }
 
+// Validates the final text against the structured-output option, throwing ValidationError on mismatch; in: the last model text, out: AgentResponse.parsed.
 function parseFinalStructuredOutput(text: string, raw: unknown, spec: import("../types/model.ts").StructuredOutputSpec | undefined): unknown | undefined {
   if (raw === undefined && spec === undefined) return undefined;
   // Strict-fail when opted in: invalid JSON/schema throws ValidationError.
@@ -350,6 +341,7 @@ function resolveLoopLimits(config: AgentLoopConfig, fallbackMaxTurns: number): L
   return { maxTurns, deadlineMs, maxToolCallsPerRun, maxTotalTokens, requestTimeoutMs, firstByteTimeoutMs, streamIdleTimeoutMs };
 }
 
+// The session id a run's provider calls use (run override, else agent default); in: AgentLoopConfig, out: rollback and routing.
 function loopSessionId(config: AgentLoopConfig): string | undefined {
   try {
     return (
@@ -359,6 +351,7 @@ function loopSessionId(config: AgentLoopConfig): string | undefined {
   } catch { return undefined; }
 }
 
+// Builds an AbortError that carries the run's partial progress; in: an abort reason + partial usage, out: the error the run rejects with.
 function makeAbortError(
   partial: { usage: TokenUsage; turns: number; text?: string },
   reason?: unknown
@@ -373,6 +366,7 @@ function makeAbortError(
   return base;
 }
 
+// Throws the run's AbortError as soon as its signal is aborted; in: loop checkpoints, out: nothing or a thrown abort.
 function throwIfAborted(
   signal: AbortSignal | undefined,
   partial: { usage: TokenUsage; turns: number; text?: string }
@@ -382,6 +376,7 @@ function throwIfAborted(
   }
 }
 
+// Throws BudgetExceededError when the run's tokens pass limits.maxTotalTokens; in: both loops after usage changes, out: nothing or a thrown error.
 function checkTokenLimit(usage: TokenUsage, maxTotalTokens: number): void {
   if (Number.isFinite(maxTotalTokens) && usage.totalTokens > maxTotalTokens) {
     throw new BudgetExceededError(
@@ -391,12 +386,14 @@ function checkTokenLimit(usage: TokenUsage, maxTotalTokens: number): void {
   }
 }
 
+// Throws when the run has been going longer than limits.deadlineMs; in: both loops each turn, out: nothing or a thrown error.
 function checkDeadline(startTime: number, deadlineMs: number): void {
   if (Number.isFinite(deadlineMs) && deadlineMs !== Infinity && Date.now() - startTime > deadlineMs) {
     throw new Error(`[Agent Accelerator] Run deadline exceeded after ${deadlineMs}ms.`);
   }
 }
 
+// Races one provider call against the request timeout (a TimeoutError), clearing its timer either way; in: runAgentLoop, out: the call's result.
 async function generateWithTimeout<T>(task: () => Promise<T>, timeoutMs: number): Promise<T> {
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs === Infinity) return task();
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -493,6 +490,7 @@ export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: M
   }
 }
 
+// Turns a tool result into what the model sees: a branded delegation envelope becomes its text and yields validated worker metadata, anything else passes through; in: executed results, out: history + usage roll-up.
 function sanitizeToolResult(r: ToolResultRecord): { sanitized: ToolResultRecord; metas: SubAgentExecutionMetadata[] } {
   // Only SDK-branded delegation envelopes are trusted. A plain object that
   // merely carries a `_subagentMetadata` key (e.g. scraped JSON) is ordinary

package/src/agent/worker.ts

@@ -3,12 +3,9 @@ import type { SubAgentStep } from "../types/response.ts";
 import type { AgentConfig } from "../types/agent.ts";
 import type { Agent } from "./agent.ts";
 import { normalizeToolName } from "../tools/executor.ts";
-import { escapeXml } from "../utils/serialization.ts";
 import { getModel, getSubModel } from "../utils/env.ts";
 import { resolveModel } from "../providers/registry.ts";
 
-export { escapeXml };
-
 /** Minimal live-trace shape shared by fixed + dynamic workers (structural subset of `SubAgentTrace`). */
 export interface LiveWorkerTrace {
   trackingId: string;
@@ -200,6 +197,7 @@ export function grantWorkerTools(
   return grantedTools;
 }
 
+// The provider id a model string resolves to, or undefined when it cannot be resolved; in: resolveWorkerCredentials, out: the provider match check.
 function providerOf(modelStr: string | unknown | undefined): string | undefined {
   if (!modelStr) return undefined;
   try {