agent-accelerator 0.6.0 → 0.6.6

package/src/agent/named-sessions.ts

@@ -0,0 +1,93 @@
+/**
+ * The named in-memory sessions of one Agent (`run(prompt, { sessionId })`, `agent.session(id)`): one `AgentContext` per
+ * id, at most 100 kept (least recently used goes first) and dropped after an hour idle. The Agent's own session is
+ * never kept here: it is its default context.
+ */
+import { AgentContext } from "./context.ts";
+import { clearSessionRouting } from "../providers.ts";
+import { clearInteractionChains } from "../providers/google.ts";
+
+/** Max named sessions kept per Agent (LRU). */
+const SESSION_LRU_MAX = 100;
+/** Idle TTL for named sessions. */
+const SESSION_TTL_MS = 60 * 60 * 1000;
+
+/** The named sessions of one Agent. */
+export class NamedSessions {
+  private readonly entries = new Map<string, { context: AgentContext; lastAccess: number }>();
+
+  constructor(
+    private readonly defaultId: () => string,
+    private readonly defaultContext: () => AgentContext,
+    private readonly create: () => AgentContext
+  ) {}
+
+  // Forgets a session's provider chain and routing state; in: every removal below, out: nothing.
+  private forget(id: string): void {
+    try {
+      clearInteractionChains(id);
+    } catch {}
+    try {
+      clearSessionRouting(id);
+    } catch {}
+  }
+
+  /** The context for `sessionId` (the default session gives the Agent's own context); expired ones are dropped and the oldest is evicted past the limit. */
+  contextFor(sessionId?: string): AgentContext {
+    const sid = sessionId || this.defaultId();
+    if (sid === this.defaultId()) return this.defaultContext();
+    const now = Date.now();
+    try {
+      for (const [key, entry] of [...this.entries]) {
+        if (now - entry.lastAccess > SESSION_TTL_MS) {
+          this.entries.delete(key);
+          this.forget(key);
+        }
+      }
+    } catch {}
+    const existing = this.entries.get(sid);
+    if (existing) {
+      existing.lastAccess = now;
+      return existing.context;
+    }
+    const fresh = this.create();
+    this.entries.set(sid, { context: fresh, lastAccess: now });
+    try {
+      while (this.entries.size > SESSION_LRU_MAX) {
+        let oldest: string | undefined;
+        let oldestTs = Infinity;
+        for (const [key, entry] of this.entries) {
+          if (entry.lastAccess < oldestTs) {
+            oldestTs = entry.lastAccess;
+            oldest = key;
+          }
+        }
+        if (!oldest) break;
+        this.entries.delete(oldest);
+        this.forget(oldest);
+      }
+    } catch {}
+    return fresh;
+  }
+
+  /** Drops one session and its provider state; no-op for an unknown id. */
+  dispose(id: string): void {
+    try {
+      this.entries.delete(id);
+    } catch {}
+    this.forget(id);
+  }
+
+  /** Drops every named session. */
+  clear(): void {
+    try {
+      for (const id of [...this.entries.keys()]) this.forget(id);
+      this.entries.clear();
+    } catch {}
+  }
+
+  /** The ids of the named sessions held now. */
+  ids(): string[] {
+    return [...this.entries.keys()];
+  }
+}

package/src/agent/options.ts

@@ -0,0 +1,166 @@
+/**
+ * Option handling for an Agent: the normalized run limits, the thinking level, the tool choice and the one function
+ * that turns agent config plus per-run options into what every provider call receives.
+ */
+import type { AgentConfig, AgentRunOptions, RetryPolicyConfig, ToolChoiceOption } from "../types/agent.ts";
+import type { ProviderRequestOptions, StructuredOutputSpec } from "../types/model.ts";
+import type { CacheOption, ServiceTier, ThinkingConfig, ThinkingLevel } from "../types/core.ts";
+import type { Prompts } from "../prompts/prompts.ts";
+import { normalizeThinkingV2 } from "../tools/tool.ts";
+import { validateModelThinking } from "../models/catalog.ts";
+import { telemetryBus } from "../telemetry.ts";
+
+/**
+ * Resolves a per-run thinking override without mutating agent config.
+ */
+export function resolveEffectiveThinking(base?: ThinkingConfig, overrideLevel?: string): ThinkingConfig | undefined {
+  if (!overrideLevel) return base;
+  if (overrideLevel === "none") return { enabled: false, level: "none", budgetTokens: 0 };
+  if (overrideLevel === "dynamic") return { enabled: true, level: "dynamic", budgetTokens: -1 };
+  return { enabled: true, level: overrideLevel as ThinkingConfig["level"] };
+}
+
+/** Normalized per-run limits. Sub-agents inherit these unless overridden. */
+export interface AgentRunLimits {
+  maxTurns?: number;
+  deadlineMs?: number;
+  maxToolCallsPerRun?: number;
+  maxTotalTokens?: number;
+  requestTimeoutMs: number;
+  firstByteTimeoutMs: number;
+  streamIdleTimeoutMs: number;
+}
+
+/** Resolves `(config as any).limits` with defaults (timeouts tolerate reasoning). */
+export function resolveAgentLimits(config: { limits?: Record<string, unknown> }): AgentRunLimits {
+  const raw = (config as { limits?: Record<string, unknown> }).limits ?? {};
+  const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+  // A network timeout: `0` or `Infinity` turns it off, any other number is milliseconds, anything else is unset (the default applies).
+  const timeout = (v: unknown): number | undefined => (typeof v === "number" && !Number.isNaN(v) ? v : undefined);
+  return {
+    ...(num(raw.maxTurns) !== undefined ? { maxTurns: Math.max(1, Math.floor(num(raw.maxTurns)!)) } : {}),
+    ...(num(raw.deadlineMs) !== undefined ? { deadlineMs: num(raw.deadlineMs)! } : {}),
+    ...(num(raw.maxToolCallsPerRun) !== undefined
+      ? { maxToolCallsPerRun: Math.max(1, Math.floor(num(raw.maxToolCallsPerRun)!)) }
+      : {}),
+    ...(num(raw.maxTotalTokens) !== undefined
+      ? { maxTotalTokens: Math.max(1, Math.floor(num(raw.maxTotalTokens)!)) }
+      : {}),
+    requestTimeoutMs: timeout(raw.requestTimeoutMs) ?? 300_000,
+    firstByteTimeoutMs: timeout(raw.firstByteTimeoutMs) ?? 120_000,
+    streamIdleTimeoutMs: timeout(raw.streamIdleTimeoutMs) ?? 300_000,
+  };
+}
+
+/** The Agent settings `buildProviderOptions` reads. */
+export interface ProviderOptionSource {
+  apiKey?: string;
+  baseUrl?: string;
+  customHeaders?: Record<string, string>;
+  thinkingConfig?: ThinkingConfig;
+  cache?: CacheOption;
+  serviceTier?: ServiceTier;
+  sessionId: string;
+  outputSpec?: StructuredOutputSpec;
+  prompts: Prompts;
+  googleTier?: "free" | "paid";
+  callDefaults: {
+    toolChoice?: ToolChoiceOption;
+    maxOutputTokens?: number;
+    retry?: RetryPolicyConfig;
+    env?: Record<string, string>;
+    fetch?: typeof fetch;
+  };
+}
+
+/**
+ * Single place that turns agent config + per-run options into the options
+ * every provider call receives. Per-run values override agent defaults
+ * (objects such as `retry` and `env` merge key by key).
+ */
+export function buildProviderOptions(
+  agent: ProviderOptionSource,
+  runOptions: AgentRunOptions | undefined
+): ProviderRequestOptions {
+  const d = agent.callDefaults;
+  const sessionId = runOptions?.sessionId || agent.sessionId;
+  const toolChoice = normalizeToolChoiceOption(runOptions?.toolChoice ?? d.toolChoice);
+  const retry = { ...d.retry, ...runOptions?.retry };
+  const env = { ...d.env, ...runOptions?.env };
+  const maxOutputTokens = runOptions?.maxOutputTokens ?? d.maxOutputTokens;
+  const fetchImpl = runOptions?.fetch ?? d.fetch;
+  return {
+    apiKey: agent.apiKey,
+    baseUrl: agent.baseUrl,
+    headers: { ...(agent.customHeaders ?? {}), ...(runOptions?.headers ?? {}) },
+    thinking: resolveEffectiveThinking(agent.thinkingConfig, runOptions?.thinkingLevel),
+    ...(agent.cache ? { cache: agent.cache } : {}),
+    serviceTier: agent.serviceTier,
+    sessionId,
+    ...(agent.outputSpec ? { output: agent.outputSpec } : {}),
+    prompts: { structuredOutput: agent.prompts.structuredOutput, toolBridge: agent.prompts.toolBridge },
+    ...(agent.googleTier ? { googleTier: agent.googleTier } : {}),
+    ...(toolChoice !== undefined ? { toolChoice } : {}),
+    ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
+    ...(Object.keys(env).length > 0 ? { env } : {}),
+    ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    ...(retry.maxRetries !== undefined ? { maxRetries: retry.maxRetries } : {}),
+    ...(retry.maxDelayMs !== undefined ? { maxRetryDelayMs: retry.maxDelayMs } : {}),
+    ...(retry.baseDelayMs !== undefined ? { retryBaseDelayMs: retry.baseDelayMs } : {}),
+    ...(retry.budgetMs !== undefined ? { retryBudgetMs: retry.budgetMs } : {}),
+  };
+}
+
+/** Normalizes the public `thinkingLevel` flag into provider-neutral thinking settings. */
+export function normalizeThinking(config: AgentConfig, fallbackLevel?: string): ThinkingConfig | undefined {
+  // DX4: only thinkingLevel, values: none, dynamic, minimal, low, medium, high, xhigh, max
+  // `thinking` (canonical) wins over legacy `thinkingLevel`; `{ level }` objects are unwrapped.
+  const rawLevel = normalizeThinkingV2(config.thinking, config.thinkingLevel) ?? fallbackLevel;
+  if (typeof config.thinking === "object" && config.thinking?.budgetTokens !== undefined) {
+    // No provider maps an explicit token budget yet: say so instead of ignoring it silently.
+    telemetryBus.emitWarning(
+      "config.thinking_budget_ignored",
+      "[Agent Accelerator] thinking.budgetTokens is not forwarded by any provider adapter yet; the level alone is used.",
+      { budgetTokens: config.thinking.budgetTokens }
+    );
+  }
+  const level = rawLevel as ThinkingLevel | undefined;
+
+  if (!level) return undefined;
+
+  // Validate model thinking from catalog if model is configured
+  if (config.model) {
+    try {
+      const rawModel: any = (config.model as any)?.model ? (config.model as any).model : config.model;
+      const modelStr = typeof rawModel === "string" ? rawModel : rawModel?.id || "";
+      const provStr =
+        typeof rawModel === "object" && rawModel?.provider
+          ? rawModel.provider
+          : modelStr.includes("/")
+            ? modelStr.split("/")[0]
+            : "";
+      const actualModelId = modelStr.includes("/") ? modelStr.split("/").slice(1).join("/") : modelStr;
+      if (actualModelId) {
+        validateModelThinking(provStr || "openrouter", actualModelId, level);
+      }
+    } catch (e) {
+      throw e;
+    }
+  }
+
+  if (level === "none") {
+    return { enabled: false, level: "none", budgetTokens: 0 };
+  }
+  if (level === "dynamic") {
+    return { enabled: true, level: "dynamic", budgetTokens: -1 };
+  }
+  return { enabled: true, level };
+}
+
+/** Maps the public `toolChoice` option onto the provider wire-neutral form. */
+export function normalizeToolChoiceOption(choice: ToolChoiceOption | undefined): ProviderRequestOptions["toolChoice"] {
+  if (!choice) return undefined;
+  if (typeof choice === "string") return choice;
+  if (choice.tool) return { type: "function", function: { name: choice.tool } };
+  return choice.mode;
+}

package/src/agent/run-control.ts

@@ -0,0 +1,248 @@
+/**
+ * Mid-session control of one Agent: the run that is active now, the follow-ups waiting behind it, and what happens when
+ * a new prompt arrives while busy (`steer`, `queue`, `interrupt`). `Agent` keeps the public methods and calls into this
+ * class; the class only needs the few things in {@link RunHost}.
+ */
+import type { AgentRunOptions, MidSessionConfig } from "../types/agent.ts";
+import type { ContentPart } from "../types/message.ts";
+import type { AgentResponse, StreamEvent } from "../types/response.ts";
+import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
+import { ValidationError } from "../types/errors.ts";
+import type { SteerEntry } from "./loop.ts";
+
+/** The run that is active right now. */
+export interface ActiveRun {
+  steerInbox: SteerEntry[];
+  outerStream?: AssistantMessageEventStream;
+  runPromise?: Promise<AgentResponse>;
+  abortController: AbortController;
+}
+
+/** A prompt waiting for the active run to finish. */
+export interface QueuedPrompt {
+  prompt: string | ContentPart[];
+  options?: AgentRunOptions;
+  isStream: boolean;
+  deferredStream?: AssistantMessageEventStream;
+  resolve: (res: AgentResponse) => void;
+  reject: (err: unknown) => void;
+  /** Put here by `interrupt(message)`: runs before every other waiting prompt. */
+  urgent?: boolean;
+}
+
+/** What the run control needs from its Agent. */
+export interface RunHost {
+  persistNow(): void;
+  run(prompt: string | ContentPart[], options?: AgentRunOptions): Promise<AgentResponse>;
+  startNonStreamingRun(prompt: string | ContentPart[], options?: AgentRunOptions): Promise<AgentResponse>;
+  startStreamingRun(prompt: string | ContentPart[], options?: AgentRunOptions): AssistantMessageEventStream;
+  readonly midSessionConfig: Required<Pick<MidSessionConfig, "mode">> & MidSessionConfig;
+  readonly maxSteers: number;
+}
+
+/** The active run and the waiting queue of one Agent. */
+export class RunControl {
+  /** The run in flight, or null when idle. */
+  current: ActiveRun | null = null;
+  /** Prompts waiting behind it (urgent ones first). */
+  readonly queue: QueuedPrompt[] = [];
+
+  constructor(private readonly host: RunHost) {}
+
+  /** Throws when the steer inbox is at its bound. */
+  assertSteerRoom(inbox: SteerEntry[]): void {
+    const max = this.host.maxSteers ?? 20;
+    if (inbox.length >= max) {
+      throw new ValidationError(
+        `[Agent Accelerator] Steer inbox is full (${inbox.length}/${max}). Wait for the active run to drain or increase midSession.maxSteers.`
+      );
+    }
+  }
+
+  // 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.
+  resolveEnqueueMode(requested?: "steer" | "queue"): "steer" | "queue" {
+    const enforced = this.host.midSessionConfig.mode;
+    if (enforced === "steer" || enforced === "queue") return enforced;
+    return requested === "steer" ? "steer" : "queue";
+  }
+
+  // Aborts the active run (provider request, tools, workers, stream) through its own controller; no-op when idle; in: interrupt and queueUrgent, out: the run settles as AbortError.
+  abortActive(reason?: Error): void {
+    const active = this.current;
+    if (!active) return;
+    try {
+      active.abortController.abort(reason ?? new Error("Agent interrupted"));
+    } catch {}
+    try {
+      active.outerStream?.cancel(reason);
+    } catch {}
+  }
+
+  // Puts a prompt ahead of everything waiting (behind earlier interrupts) and aborts the active run, so it starts as soon as that run has settled; ignores midSession mode and maxQueued; in: run()/stream() with enqueue "interrupt", out: pendingQueue + the abort.
+  queueUrgent(entry: QueuedPrompt): void {
+    entry.urgent = true;
+    const firstOrdinary = this.queue.findIndex((e) => !e.urgent);
+    this.queue.splice(firstOrdinary < 0 ? this.queue.length : firstOrdinary, 0, entry);
+    this.host.persistNow();
+    this.abortActive();
+  }
+
+  /**
+   * Buffers a steer prompt into the active run and returns a promise for ITS
+   * reply: the active run's response when the prompt is injected, or (if the
+   * run ends first and the prompt becomes a queued follow-up) the follow-up
+   * run's response, so a late steer's answer is never lost.
+   */
+  steerInto(active: ActiveRun, prompt: string | ContentPart[], options?: AgentRunOptions): Promise<AgentResponse> {
+    this.assertSteerRoom(active.steerInbox);
+    const runDone = active.runPromise ?? active.outerStream?.result();
+    if (!runDone) return this.host.run(prompt, options) as Promise<AgentResponse>;
+    const entry: SteerEntry = { prompt, options };
+    const reply = new Promise<AgentResponse>((resolve, reject) => {
+      entry.settle = { resolve, reject };
+    });
+    reply.catch(() => {}); // a fire-and-forget caller must not trigger an unhandled rejection
+    active.steerInbox.push(entry);
+    this.host.persistNow();
+    runDone.then(
+      (res) => {
+        if (!entry.settle?.deferredToQueue) entry.settle?.resolve(res);
+      },
+      (err) => {
+        if (!entry.settle?.deferredToQueue) entry.settle?.reject(err);
+      }
+    );
+    return reply;
+  }
+
+  // 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.
+  pumpQueue(): void {
+    if (this.current !== null) return;
+    const next = this.queue.shift();
+    if (!next) return;
+    this.host.persistNow();
+    // Reject queued items whose signal aborted before start.
+    try {
+      if ((next.options as { signal?: AbortSignal } | undefined)?.signal?.aborted) {
+        const reason = ((next.options as { signal?: AbortSignal }).signal as unknown as { reason?: unknown })?.reason;
+        const abortErr = Object.assign(
+          reason instanceof Error ? reason : new Error("Queued run aborted before start"),
+          { name: "AbortError" }
+        );
+        try {
+          next.reject(abortErr);
+        } catch {}
+        try {
+          next.deferredStream?.fail(abortErr instanceof Error ? abortErr : new Error(String(abortErr)));
+        } catch {}
+        queueMicrotask(() => this.pumpQueue());
+        return;
+      }
+    } catch {}
+    if (next.isStream && next.deferredStream) {
+      const deferred = next.deferredStream;
+      try {
+        const real = this.host.startStreamingRun(next.prompt, next.options);
+        try {
+          (deferred as any).__piped = true;
+        } catch {}
+        const forward = (e: StreamEvent) => {
+          try {
+            deferred.push(e);
+          } catch {}
+        };
+        real.on("*", forward as any);
+        try {
+          deferred.onCancel(() => {
+            try {
+              real.cancel();
+            } catch {}
+          });
+        } catch {}
+        real.result().then(
+          (res) => {
+            try {
+              next.resolve(res);
+            } catch {}
+            try {
+              deferred.end(res);
+            } catch {}
+          },
+          (err) => {
+            try {
+              next.reject(err);
+            } catch {}
+            // Pipe failures into the deferred stream so for-await sees them.
+            try {
+              deferred.fail(err instanceof Error ? err : new Error(String(err)));
+            } catch {}
+          }
+        );
+      } catch (err) {
+        try {
+          next.reject(err);
+        } catch {}
+        try {
+          deferred.fail(err instanceof Error ? err : new Error(String(err)));
+        } catch {}
+        // Keep draining even if starting failed.
+        queueMicrotask(() => this.pumpQueue());
+      }
+      return;
+    }
+    this.host.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.
+  finishCurrentRun(): void {
+    // Leftover steer entries become queued follow-ups instead of dropping.
+    let leftover: SteerEntry[] = [];
+    try {
+      leftover = this.current?.steerInbox?.splice(0) ?? [];
+    } catch {
+      leftover = [];
+    }
+    this.current = null;
+    if (leftover.length > 0) {
+      try {
+        const max = this.host.midSessionConfig.maxQueued ?? 20;
+        // Late steers were typed BEFORE anything already queued: they go to the front, in the order they arrived.
+        const lateSteers: QueuedPrompt[] = [];
+        for (const entry of leftover) {
+          try {
+            if ((entry.options as { signal?: AbortSignal } | undefined)?.signal?.aborted) {
+              entry.settle?.reject(
+                Object.assign(new Error("Steer aborted before it could run"), { name: "AbortError" })
+              );
+              continue;
+            }
+          } catch {
+            continue;
+          }
+          if (this.queue.length + lateSteers.length >= max) {
+            entry.settle?.reject(
+              new ValidationError("[Agent Accelerator] Steer dropped: the follow-up queue is full.")
+            );
+            continue;
+          }
+          // The steer was never injected: it now runs as a follow-up, and the
+          // caller's promise resolves with that run's response.
+          if (entry.settle) entry.settle.deferredToQueue = true;
+          lateSteers.push({
+            prompt: entry.prompt,
+            options: entry.options,
+            isStream: false,
+            resolve: entry.settle?.resolve ?? (() => {}),
+            reject: entry.settle?.reject ?? (() => {}),
+          });
+        }
+        // ...but behind an interrupt(message), which is the newest and most urgent instruction.
+        const firstOrdinary = this.queue.findIndex((e) => !e.urgent);
+        this.queue.splice(firstOrdinary < 0 ? this.queue.length : firstOrdinary, 0, ...lateSteers);
+      } catch {}
+    }
+    this.host.persistNow();
+    // Defer pump so the completing run's .then handlers settle first.
+    queueMicrotask(() => this.pumpQueue());
+  }
+}

package/src/agent/subagents-tool.ts

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

package/src/agent/usage-limit.ts

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