agent-accelerator 0.5.8 → 0.6.0

package/src/index.ts

@@ -37,7 +37,14 @@ export { zodToJsonSchema, cleanJsonSchema } from "./tools/schema.ts";
  */
 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 {
@@ -126,12 +133,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 +254,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
@@ -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`), 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,20 +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, ValidationError } from "../types/errors.ts";
 
 // ---------------------------------------------------------------------------
 // Provider aliases — maps our internal ids to models.dev keys
@@ -48,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"],
   };
 }
 
@@ -106,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.
@@ -135,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
+    ),
   };
 }
 
@@ -267,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) {
@@ -291,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;
@@ -410,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,
@@ -421,8 +426,8 @@ export function getModelThinkingInfo(provider: string, modelId: string): ModelTh
   };
 }
 
-/** Thrown when a requested ThinkingLevel is unsupported by the selected model. */
-export class ThinkingLevelError extends Error {
+/** Thrown when a requested ThinkingLevel is unsupported by the selected model: a `ConfigError` (one line, never retried) with `allowedLevels`. */
+export class ThinkingLevelError extends ConfigError {
   readonly provider: string;
   readonly modelId: string;
   readonly requestedLevel: string;
@@ -443,31 +448,19 @@ export class ThinkingLevelError extends Error {
     reason: string;
     remedy?: string;
   }) {
-    const remedyLines = opts.remedy
-      ? `\n\n  How to fix:\n    ${opts.remedy}`
-      : "";
-    const allowedLine = opts.allowedLevels.length > 0
-      ? `\n  Allowed Levels:  [${opts.allowedLevels.map((l) => `"${l}"`).join(", ")}]`
-      : "";
-
-    const formattedMessage =
-      `[Agent Accelerator] ThinkingLevel Mismatch for "${opts.provider}/${opts.modelId}":\n` +
-      `  Requested Level: "${opts.requestedLevel}"\n` +
-      `  Issue:           ${opts.reason}` +
-      allowedLine +
-      remedyLines;
-
-    super(formattedMessage);
+    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}`,
+      { provider: opts.provider, model: opts.modelId }
+    );
     this.name = "ThinkingLevelError";
     this.provider = opts.provider;
     this.modelId = opts.modelId;
     this.requestedLevel = opts.requestedLevel;
     this.allowedLevels = opts.allowedLevels;
     this.supportsThinking = opts.supportsThinking;
-
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, ThinkingLevelError);
-    }
   }
 }
 
@@ -476,7 +469,11 @@ export class ThinkingLevelError extends Error {
  *
  * @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/providers/architecture.md

@@ -2,19 +2,21 @@
 
 All HTTP and wire parsing. Canonical mappers (thinking, cache, tool choice, structured output) live in `../providers.ts`, never here.
 
-| File | Wire | Notes |
-| :-- | :-- | :-- |
-| `google.ts` | Google Interactions | Stateful chaining (TTL gate, self-heal on `not_found`), exact replay of raw `steps`, media consts at the top, Gemini 4 long decode as background interactions. |
-| `openai.ts` | OpenAI Responses | Stateless (`store:false`), full history every turn. |
-| `openrouter.ts` | OpenRouter Chat Completions | Every request streams (so it can be cancelled); `generate()` collects its own stream. |
-| `openai-compat.ts` | OpenAI-compatible Chat Completions | Serves every custom prefix; strict subset of fields; no default base URL. |
-| `registry.ts` | - | Routes `provider/model` to an adapter; the registry is immutable; `ModelProvider` helpers. |
-| `shared.ts` | - | Helpers every adapter uses: signals and timers, error payloads, ids, retry-after, SSE scaffold (`linkStreamAbort`, `withAbortTimer`, `readSseData`, `incompleteStreamCheck`, `failStream`). |
+| File               | Wire                               | Notes                                                                                                                                                                                       |
+| :----------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `google.ts`        | Google Interactions                | Stateful chaining (TTL gate, self-heal on `not_found`), exact replay of raw `steps`, media consts at the top, Gemini 4 long decode as background interactions.                              |
+| `openai.ts`        | OpenAI Responses                   | Stateless (`store:false`), full history every turn.                                                                                                                                         |
+| `openrouter.ts`    | OpenRouter Chat Completions        | Every request streams (so it can be cancelled); `generate()` collects its own stream.                                                                                                       |
+| `openai-compat.ts` | OpenAI-compatible Chat Completions | Serves every custom prefix; strict subset of fields; no default base URL.                                                                                                                   |
+| `registry.ts`      | -                                  | Routes `provider/model` to an adapter; the registry is immutable; `ModelProvider` helpers.                                                                                                  |
+| `shared.ts`        | -                                  | Helpers every adapter uses: signals and timers, error payloads, ids, retry-after, SSE scaffold (`linkStreamAbort`, `withAbortTimer`, `readSseData`, `incompleteStreamCheck`, `failStream`). |
 
 ## Contract (`Provider`, in `../types/model.ts`)
+
 `generate(model, context, options)` returns a `ProviderGenerateResult`; `stream(...)` returns an `AssistantMessageEventStream` that ends with an `AgentResponse`; optional `isLongRunning()` tells the loop to skip its whole-call timeouts.
 
 ## Invariants
+
 - Fix shared streaming behaviour in `shared.ts`, never per adapter. Event parsing and request building stay in each adapter.
 - OpenRouter and compat chat chunk handlers are deliberately not merged.
 - A custom prefix never gets another provider's key or base URL.