agent-accelerator 0.5.9 → 0.6.5

package/src/agent/workers.ts

@@ -15,9 +15,15 @@ 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";
+import { mergeUsage, modelName, readUsage, type UsageNode } from "../session/usage.ts";
 
 /** What `spawn` needs to start a worker. */
 export interface WorkerSpec {
@@ -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()
     }
@@ -133,6 +157,17 @@ function readSavedWorker(dir: string | undefined): { model: string; totals: Retu
   return { model: session?.session.model || "unknown", totals: readUsage(session?.session.usage), workers };
 }
 
+/** What a saved session folder and every worker saved below it spent in total (read from disk): the starting point of a chat-wide usage cap after a restart; in: Agent.beginChat, out: usage totals. */
+export function savedSpend(dir: string): ReturnType<typeof readUsage> {
+  const total = readUsage(undefined);
+  const add = (node: { totals: ReturnType<typeof readUsage>; workers: UsageNode[] }): void => {
+    mergeUsage(total, node.totals);
+    for (const w of node.workers) add(w);
+  };
+  add(readSavedWorker(dir));
+  return total;
+}
+
 /** The workers of one parent `Agent` (`agent.workers`). */
 export class WorkerRegistry {
   private readonly entries = new Map<string, Entry>();
@@ -167,10 +202,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 +259,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 +290,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 +305,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 +317,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 +332,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 +344,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";
@@ -331,6 +395,7 @@ export class WorkerRegistry {
       })
     );
     (agent as unknown as { parentSessionId?: string }).parentSessionId = this.parent.sessionId;
+    agent.chat = this.parent.chat; // the worker's turns count into the chat-wide cap and are checked against it
     // A cut-off run was already loaded by the constructor; otherwise bring back what the worker said so far.
     const saved = entry.dir && agent.context.messages.length === 0 ? loadSessionDir(entry.dir)?.session : undefined;
     if (saved) agent.importSession(saved);
@@ -338,8 +403,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 +427,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 +470,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,26 @@
 
 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.                                                                                                              |
+| `prompts/`          | The SDK's own prompts as `.md` files, `DEFAULT_PROMPTS`, `AgentConfig.prompts`.                                                                                             |
+| `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).

package/src/index.ts

@@ -31,13 +31,24 @@ export {
 } from "./tools/tool.ts";
 export type { CreateToolOptions } from "./tools/tool.ts";
 export { zodToJsonSchema, cleanJsonSchema } from "./tools/schema.ts";
+export { toolContent } from "./tools/tool-content.ts";
+export { DEFAULT_PROMPTS } from "./prompts/prompts.ts";
+export type { PromptName, PromptOverrides } from "./prompts/prompts.ts";
+export type { ToolContent, ToolContentPart } from "./tools/tool-content.ts";
 /**
  * @deprecated Internal executor surface. Prefer `Agent` runs; for direct
  * execution import from the future `/internal` entry.
  */
 export { executeToolCalls } from "./tools/executor.ts";
 
-export { assertPathAllowed, enforceFileAccess, fetchRemoteBytes, isPrivateAddress, RemoteFetchError, MAX_REMOTE_FETCH_BYTES } from "./utils/safe-io.ts";
+export {
+  assertPathAllowed,
+  enforceFileAccess,
+  fetchRemoteBytes,
+  isPrivateAddress,
+  RemoteFetchError,
+  MAX_REMOTE_FETCH_BYTES,
+} from "./utils/safe-io.ts";
 
 // Multi-Agent Delegation & Tools
 export {
@@ -53,17 +64,12 @@ export {
 export type { AgentAsToolTarget, SubAgentTrace } from "./agent/delegation.ts";
 export type { WorkerRegistry, WorkerSpec, WorkerInfo, WorkerReply, WorkerCallOptions } from "./agent/workers.ts";
 
-// Scheduled actions: dynamic sub-agents that run later and save their answer to a file
-export {
-  createScheduledAction,
-  listScheduledActions,
-  updateScheduledAction,
-  runScheduledAction,
-  skipScheduledAction,
-  deleteScheduledAction,
-} from "./scheduler/scheduler.ts";
+// Scheduled actions: dynamic sub-agents that run later and save their answer to a file (use `agent.scheduled`)
+export type { ScheduledActions } from "./scheduler/scheduler.ts";
 export { getDatetimeTool } from "./scheduler/tool.ts";
 export { setHome, resolveHome } from "./utils/home.ts";
+export { configure } from "./agent/defaults.ts";
+export type { AgentDefaults } from "./agent/defaults.ts";
 export type {
   ScheduledActionInput,
   ScheduledActionPatch,
@@ -126,12 +132,8 @@ export {
   GoogleInteractionsProvider,
   clearInteractionChains,
 } from "./providers/google.ts";
-export {
-  OpenRouterChatCompletionsProvider,
-} from "./providers/openrouter.ts";
-export {
-  OpenAIResponsesProvider,
-} from "./providers/openai.ts";
+export { OpenRouterChatCompletionsProvider } from "./providers/openrouter.ts";
+export { OpenAIResponsesProvider } from "./providers/openai.ts";
 /**
  * @deprecated Internal provider mappers/routing helpers. Prefer the
  * provider-agnostic registry (`resolveModel`/`getProvider`); direct mapper
@@ -251,14 +253,36 @@ export {
   emptyTotals,
 } from "./session/store.ts";
 export type { UsageReport, UsageLine, UsageTotals, AgentUsage, WorkerUsage, CostSource } from "./session/usage.ts";
-export type { SessionLimits, SessionPayloadStatus, PersistedAgentSession, SessionTotals, SessionAgentLike, LoadedSessionDir, PersistedSubAgentTrace, SessionRunMark, SessionRunEnd, SessionPending, SessionPendingPrompt, SessionToolRecord } from "./session/store.ts";
+export type {
+  SessionLimits,
+  SessionPayloadStatus,
+  PersistedAgentSession,
+  SessionTotals,
+  SessionAgentLike,
+  LoadedSessionDir,
+  PersistedSubAgentTrace,
+  SessionRunMark,
+  SessionRunEnd,
+  SessionPending,
+  SessionPendingPrompt,
+  SessionToolRecord,
+} from "./session/store.ts";
 
 // Utilities
 /**
  * @deprecated Session-routing internals. Prefer agent-level `sessionId`;
  * direct use moves to the future `/internal` entry.
  */
-export { createSessionId, hashSessionPart, createTrackingId, nowMs, newRunId, newTurnId, previewPrompt, parseModelRef } from "./utils/session.ts";
+export {
+  createSessionId,
+  hashSessionPart,
+  createTrackingId,
+  nowMs,
+  newRunId,
+  newTurnId,
+  previewPrompt,
+  parseModelRef,
+} from "./utils/session.ts";
 export type { ParsedModelRef } from "./utils/session.ts";
 /**
  * @deprecated Raw env access. Prefer explicit `Agent` config (which wins over
@@ -298,6 +322,7 @@ export type {
   ProviderContext,
   ProviderSteps,
   MediaResolution,
+  VideoProcessing,
 } from "./types/message.ts";
 
 export type {
@@ -344,7 +369,6 @@ export type {
   RetryPolicyConfig,
   AgentLogger,
   ToolChoiceOption,
-  StopOption,
   Budget,
   BudgetState,
   SubAgentRunIds,

package/src/models/architecture.md

@@ -2,12 +2,13 @@
 
 The model catalog: context limits, prices, modalities and reasoning options come from models.dev, not from code.
 
-| File | What it is |
-| :-- | :-- |
+| File               | What it is                                                                                                                                                                                                                                                                                                          |
+| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `catalog-cache.ts` | Downloads and caches `models.dev/api.json` in `<home>/catalog/` (or `AGENT_CACHE_DIR`). Stale-while-revalidate: an expired catalog is served at once and refreshed in the background (8 s timeout, 10 min backoff after a failure); only a cold start waits. `AGENT_CATALOG_REFRESH=off` stops automatic refreshes. |
-| `catalog.ts` | Lookups (`getModelFromCatalog`), `registerModel`, thinking validation (`validateModelThinking`, which throws `ThinkingLevelError`, a one-line `ConfigError`), and the exported `GOOGLE_/OPENAI_/OPENROUTER_MODELS` arrays (rebuilt in place when the catalog changes). |
+| `catalog.ts`       | Lookups (`getModelFromCatalog`), `registerModel`, thinking validation (`validateModelThinking`, which throws `ThinkingLevelError`, a one-line `ConfigError`), and the exported `GOOGLE_/OPENAI_/OPENROUTER_MODELS` arrays (rebuilt in place when the catalog changes).                                              |
 
 ## Invariants
+
 - Never hand-edit the cache file; register custom models with `registerModel()`. Verified modality fixes go in `MODALITY_OVERRIDES`.
 - The global bare-id fallback applies to first-class providers and explicit bare-id lookups only. A custom prefix never borrows another provider's price or modalities: unknown stays unknown.
 - A payload that is not a catalog (fewer than 3 providers with models) never overwrites the cache.

package/src/models/catalog-cache.ts

@@ -313,7 +313,7 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
       fallbackToDiskCache();
       return getCatalogStatus();
     }
-  } catch (err: any) {
+  } catch {
     clearTimeout(timer);
     // If download fails, retain disk cache if available
     fallbackToDiskCache();
@@ -356,7 +356,6 @@ export async function refreshModelCatalog(options: RefreshCatalogOptions = {}):
   return getCatalogStatus();
 }
 
-
 /** True when `AGENT_CATALOG_REFRESH` is `off`/`0`/`false`: never touch the network automatically. */
 function automaticRefreshDisabled(): boolean {
   const v = getEnv("AGENT_CATALOG_REFRESH")?.trim().toLowerCase();
@@ -388,9 +387,11 @@ export async function ensureModelCatalogFresh(options: RefreshCatalogOptions = {
   const start = (): Promise<CatalogStatus> => {
     if (!inFlightRefresh) {
       const timeoutMs = options.timeoutMs ?? (current.loaded ? BACKGROUND_REFRESH_TIMEOUT_MS : undefined);
-      inFlightRefresh = refreshModelCatalog({ ...options, ...(timeoutMs !== undefined ? { timeoutMs } : {}) }).finally(() => {
-        inFlightRefresh = null;
-      });
+      inFlightRefresh = refreshModelCatalog({ ...options, ...(timeoutMs !== undefined ? { timeoutMs } : {}) }).finally(
+        () => {
+          inFlightRefresh = null;
+        }
+      );
     }
     return inFlightRefresh;
   };

package/src/models/catalog.ts

@@ -5,21 +5,10 @@
  * rebuilt in place whenever it changes.
  */
 
-import {
-  getActiveCatalog,
-  registerCatalogUpdateListener,
-  refreshModelCatalog,
-  ensureModelCatalogFresh,
-  getCatalogStatus,
-  setCatalogTTL,
-  getCatalogTTL,
-  DEFAULT_CATALOG_TTL_MS,
-  type CatalogStatus,
-  type RefreshCatalogOptions,
-} from "./catalog-cache.ts";
+import { getActiveCatalog, registerCatalogUpdateListener } from "./catalog-cache.ts";
 import type { ModelSpec, ProviderId, ModelLimit, ModelCost, ModelModalities } from "../types/model.ts";
 import type { ThinkingLevel } from "../types/core.ts";
-import { ConfigError } from "../types/errors.ts";
+import { ConfigError, ValidationError } from "../types/errors.ts";
 
 // ---------------------------------------------------------------------------
 // Provider aliases — maps our internal ids to models.dev keys
@@ -49,8 +38,8 @@ function applyModalityOverrides(provider: string, modelId: string, base: ModelMo
     MODALITY_OVERRIDES[`${provider}/${normalizeModelIdForLookup(modelId)}`];
   if (!hit) return base;
   return {
-    input: ((hit.input ?? base.input) as ModelModalities["input"]),
-    output: ((hit.output ?? base.output) as ModelModalities["output"]),
+    input: (hit.input ?? base.input) as ModelModalities["input"],
+    output: (hit.output ?? base.output) as ModelModalities["output"],
   };
 }
 
@@ -107,7 +96,7 @@ function customRegistryKey(provider: string, modelId: string): string {
  */
 export function registerModel(spec: ModelSpec): void {
   if (!spec || typeof spec.id !== "string" || typeof spec.provider !== "string") {
-    throw new Error("[Agent Accelerator] registerModel requires spec.id and spec.provider strings");
+    throw new ValidationError("[Agent Accelerator] registerModel requires spec.id and spec.provider strings");
   }
   customModelRegistry.set(customRegistryKey(String(spec.provider), String(spec.id)), { ...spec });
   // Invalidate derived caches so the custom model is visible immediately.
@@ -136,30 +125,38 @@ export function getModelSource(provider: string, modelId: string): "catalog" | "
   if (customModelRegistry.has(customRegistryKey(p, m)) || customModelRegistry.has(customRegistryKey(p, norm))) {
     return "override";
   }
-  if (
-    MODALITY_OVERRIDES[`${p}/${m}`] !== undefined ||
-    MODALITY_OVERRIDES[`${p}/${norm}`] !== undefined
-  ) {
+  if (MODALITY_OVERRIDES[`${p}/${m}`] !== undefined || MODALITY_OVERRIDES[`${p}/${norm}`] !== undefined) {
     return "override";
   }
   return getModelFromCatalog(provider, modelId) ? "catalog" : "unknown";
 }
 
 // Derives capability flags (thinking, caching, tools, structured output, modalities) from a raw catalog entry; in: mapModelSpec, out: ModelCapabilities.
-function mapCapabilities(raw: any, cost: ModelCost, reasoning: boolean, toolCall: boolean, modalities: ModelModalities) {
+function mapCapabilities(
+  raw: any,
+  cost: ModelCost,
+  reasoning: boolean,
+  toolCall: boolean,
+  modalities: ModelModalities
+) {
   return {
     supportsThinking: reasoning,
     supportsThinkingLevel: !!raw.reasoning_options,
-    supportsThinkingBudget: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "budget_tokens"),
+    supportsThinkingBudget:
+      Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "budget_tokens"),
     supportsImplicitCaching: cost.cache_read !== undefined || cost.cache_write !== undefined,
     supportsLongCacheRetention: cost.cache_read !== undefined,
     supportsExplicitCaching: cost.cache_read !== undefined,
     supportsParallelToolCalls: toolCall,
     supportsStreaming: true,
     supportsStructuredOutput: raw.structured_output === undefined ? true : !!raw.structured_output,
-    supportsReasoningToggle: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "toggle"),
-    supportsReasoningEffort: Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "effort"),
-    modalities: [...(modalities.input || []), ...(modalities.output || [])].filter((v: any, i: any, a: any) => a.indexOf(v) === i),
+    supportsReasoningToggle:
+      Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "toggle"),
+    supportsReasoningEffort:
+      Array.isArray(raw.reasoning_options) && raw.reasoning_options.some((o: any) => o.type === "effort"),
+    modalities: [...(modalities.input || []), ...(modalities.output || [])].filter(
+      (v: any, i: any, a: any) => a.indexOf(v) === i
+    ),
   };
 }
 
@@ -268,7 +265,9 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
   }
 
   const aliasProviders = PROVIDER_ALIASES[provider] || [provider];
-  const tryProviders = [...new Set([...aliasProviders, provider, provider.replace("-zen", ""), provider.replace("-go", "")])];
+  const tryProviders = [
+    ...new Set([...aliasProviders, provider, provider.replace("-zen", ""), provider.replace("-go", "")]),
+  ];
   const catalog = getActiveCatalog();
 
   for (const p of tryProviders) {
@@ -292,7 +291,11 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
     // or normalized equality. The old loose `modelId.endsWith(key)` is removed
     // (e.g. "gpt-4o-mini-extra" must not match "mini").
     for (const [key, raw] of Object.entries(providerData.models as Record<string, any>)) {
-      if (key === modelId || key.endsWith(`/${modelId}`) || normalizeModelIdForLookup(key) === normalizeModelIdForLookup(modelId)) {
+      if (
+        key === modelId ||
+        key.endsWith(`/${modelId}`) ||
+        normalizeModelIdForLookup(key) === normalizeModelIdForLookup(modelId)
+      ) {
         result = mapModelSpec(p as ProviderId, key, raw as any);
         setLookupCache(cacheKey, result);
         return result;
@@ -411,7 +414,8 @@ export function getModelThinkingInfo(provider: string, modelId: string): ModelTh
   allowed.add("dynamic");
 
   const allowedLevels = Array.from(allowed);
-  const supportsDisable = allowed.has("none") || !!toggleOpt || Boolean(budgetOpt && (budgetOpt.min === undefined || budgetOpt.min <= 0));
+  const supportsDisable =
+    allowed.has("none") || !!toggleOpt || Boolean(budgetOpt && (budgetOpt.min === undefined || budgetOpt.min <= 0));
 
   return {
     supportsThinking: true,
@@ -444,7 +448,8 @@ export class ThinkingLevelError extends ConfigError {
     reason: string;
     remedy?: string;
   }) {
-    const allowed = opts.allowedLevels.length > 0 ? ` Allowed levels: ${opts.allowedLevels.map((l) => `"${l}"`).join(", ")}.` : "";
+    const allowed =
+      opts.allowedLevels.length > 0 ? ` Allowed levels: ${opts.allowedLevels.map((l) => `"${l}"`).join(", ")}.` : "";
     const remedy = opts.remedy ? ` How to fix: ${opts.remedy}` : "";
     super(
       `[Agent Accelerator] Thinking level "${opts.requestedLevel}" does not fit "${opts.provider}/${opts.modelId}": ${opts.reason}${allowed}${remedy}`,
@@ -464,7 +469,11 @@ export class ThinkingLevelError extends ConfigError {
  *
  * @example `validateModelThinking("google", "gemini-3.5-flash-lite", "medium");`
  */
-export function validateModelThinking(provider: string, modelId: string, requestedLevel?: ThinkingLevel | string): void {
+export function validateModelThinking(
+  provider: string,
+  modelId: string,
+  requestedLevel?: ThinkingLevel | string
+): void {
   if (!requestedLevel) return;
   const level = String(requestedLevel).toLowerCase().trim();
   const info = getModelThinkingInfo(provider, modelId);

package/src/prompts/additional-context.md

@@ -0,0 +1,2 @@
+[Additional Context]
+{{context}}