agent-accelerator 0.5.7 → 0.5.9

package/src/models/catalog.ts

@@ -1,8 +1,8 @@
 /**
- * Model catalog — battle-tested single source of truth (models.dev)
- * Dynamically loaded and synchronized via ~/.cache with ~12h TTL.
- * All context length, pricing, limits, reasoning, modalities come from here.
- * Providers' hardcoded GOOGLE_MODELS etc. are DEPRECATED fallbacks only.
+ * Model catalog: the single source of truth (models.dev) for context limits, prices, modalities and reasoning options.
+ * The data is cached in `<home>/catalog/models.dev.json` (or `AGENT_CACHE_DIR`) with a 12 hour TTL and refreshed in the
+ * background (see `catalog-cache.ts`). `GOOGLE_MODELS`, `OPENAI_MODELS` and `OPENROUTER_MODELS` are views of it,
+ * rebuilt in place whenever it changes.
  */
 
 import {
@@ -19,6 +19,7 @@ import {
 } 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";
 
 // ---------------------------------------------------------------------------
 // Provider aliases — maps our internal ids to models.dev keys
@@ -77,12 +78,12 @@ function normalizeModelIdForLookup(modelId: string): string {
 
 // ---------------------------------------------------------------------------
 // Internal cache — battle-tested: avoid repeated global scans (7487 models)
-// Bound lookupCache to 1000 entries LRU (Q-33): evict oldest on overflow.
+// Bound lookupCache to 1000 entries LRU: evict oldest on overflow.
 // ---------------------------------------------------------------------------
 const lookupCache = new Map<string, ModelSpec | undefined>();
 const providerModelsCache = new Map<string, ModelSpec[]>();
 
-/** Bounded LRU set for lookupCache (Q-33): keeps at most 1000 entries. */
+/** Bounded LRU set for lookupCache: keeps at most 1000 entries. */
 function setLookupCache(key: string, value: ModelSpec | undefined): void {
   if (lookupCache.has(key)) lookupCache.delete(key);
   else if (lookupCache.size >= 1000) {
@@ -92,7 +93,7 @@ function setLookupCache(key: string, value: ModelSpec | undefined): void {
   lookupCache.set(key, value);
 }
 
-// Custom-registered models (Q-33): checked first in getModelFromCatalog.
+// Custom-registered models: checked first in getModelFromCatalog.
 const customModelRegistry = new Map<string, ModelSpec>();
 
 // Case-insensitive key of a registered custom model; in: registerModel and lookups, out: a string.
@@ -101,7 +102,7 @@ function customRegistryKey(provider: string, modelId: string): string {
 }
 
 /**
- * Registers a custom model spec that takes precedence over the catalog (Q-33).
+ * Registers a custom model spec that takes precedence over the catalog.
  * Stored in a separate map, checked first in `getModelFromCatalog`.
  */
 export function registerModel(spec: ModelSpec): void {
@@ -124,7 +125,7 @@ export function clearCustomModels(): void {
 }
 
 /**
- * Returns where a model resolves from without touching frozen types (Q-33):
+ * Returns where a model resolves from without touching frozen types:
  * `"override"` for custom-registered or MODALITY_OVERRIDES-covered models,
  * `"catalog"` for plain catalog hits, `"unknown"` when unresolvable.
  */
@@ -256,7 +257,7 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
   const modelId = modelIdInput.trim();
   let result: ModelSpec | undefined;
 
-  // Q-33: custom-registered models win over the catalog.
+  // Custom-registered models win over the catalog.
   const customHit =
     customModelRegistry.get(customRegistryKey(provider, modelId)) ??
     customModelRegistry.get(customRegistryKey(provider, normalizeModelIdForLookup(modelId)));
@@ -287,7 +288,7 @@ export function getModelFromCatalog(providerInput: string, modelIdInput: string)
         return result;
       }
     }
-    // Q-33: tightened fuzzy match — exact, `endsWith("/"+modelId)` boundary,
+    // Tightened fuzzy match — exact, `endsWith("/"+modelId)` boundary,
     // 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>)) {
@@ -421,8 +422,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 +444,18 @@ 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);
-    }
   }
 }
 
@@ -563,7 +551,7 @@ export function getModelsForProvider(provider: string): ModelSpec[] {
       out.push(mapModelSpec(alias as ProviderId, key, raw));
     }
   }
-  // Q-33: include custom-registered models for this provider/alias set.
+  // Include custom-registered models for this provider/alias set.
   for (const spec of customModelRegistry.values()) {
     if (aliases.includes(String(spec.provider)) || String(spec.provider) === provider) {
       if (!seen.has(spec.id)) {
@@ -573,7 +561,7 @@ export function getModelsForProvider(provider: string): ModelSpec[] {
     }
   }
   // Also include our internal provider id mapping
-  // Q-33: return copies — cache the canonical array, hand out a fresh copy.
+  // Return copies — cache the canonical array, hand out a fresh copy.
   providerModelsCache.set(provider, out);
   return [...out];
 }

package/src/providers/google.ts

@@ -383,7 +383,7 @@ function cleanModelId(model: string | ModelSpec): string {
 function assertSupportedGeneration(clean: string): void {
   const match = clean.match(/^gemini-(\d+)(?:[.\-]|$)/i);
   if (match && Number(match[1]) < 3) {
-    throw new Error(
+    throw new ConfigError(
       `[Agent Accelerator] [google/${clean}] Unsupported generation: Gemini ${match[1]}.x and older are strictly rejected by this SDK. ` +
         `Use a Gemini 3 or later model for full support and feature coverage.`
     );
@@ -609,7 +609,7 @@ async function fullHistorySteps(context: ProviderContext): Promise<InteractionIn
       const turnStart = steps.length;
       for (const part of m.content) {
         if (part.type === "thinking" && part.thinking) {
-          // Q-18: preserve namespaced signatures only — foreign-provider
+          // Preserve namespaced signatures only — foreign-provider
           // signatures never echo here; untagged legacy echoes (compat).
           // Absent signatures are omitted (never sent as empty strings).
           const partProvider = (part as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
@@ -642,7 +642,7 @@ async function fullHistorySteps(context: ProviderContext): Promise<InteractionIn
       } else if (m.thoughtSignature && !steps.slice(turnStart).some((s) => s.type === "thought")) {
         // Preserve a signature-only thought so stateless chaining keeps
         // reasoning continuity even when no summary text was retained.
-        // Q-18: only for google/untagged signatures.
+        // Only for google/untagged signatures.
         const msgProvider = (m as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
         if (shouldEchoSignature(msgProvider, "google")) {
           steps.push({ type: "thought", signature: m.thoughtSignature });
@@ -910,7 +910,7 @@ export class GoogleInteractionsProvider implements Provider {
     signal?: AbortSignal
   ): RequestInit {
     const headers: Record<string, string> = { "Content-Type": "application/json", ...options?.headers };
-    // Q-17: key travels as the `x-goog-api-key` header (never `?key=` in the
+    // Key travels as the `x-goog-api-key` header (never `?key=` in the
     // URL, which would leak into logs). Case-insensitive merge so a custom
     // `X-Goog-Api-Key` never duplicates the canonical header. Proxy flows
     // (`apiKey === "unused"`) preserve custom auth instead of overwriting.
@@ -1022,7 +1022,7 @@ export class GoogleInteractionsProvider implements Provider {
     assertSupportedGeneration(clean);
     const apiKey = resolveApiKey(options);
     if (!apiKey) {
-      throw new Error(
+      throw new ConfigError(
         "[Agent Accelerator] Missing Google API key. Set GEMINI_API_KEY (or GOOGLE_API_KEY) or pass apiKey."
       );
     }
@@ -1133,7 +1133,7 @@ export class GoogleInteractionsProvider implements Provider {
         assertSupportedGeneration(clean);
         const apiKey = resolveApiKey(options);
         if (!apiKey) {
-          throw new Error(
+          throw new ConfigError(
             "[Agent Accelerator] Missing Google API key. Set GEMINI_API_KEY (or GOOGLE_API_KEY) or pass apiKey."
           );
         }
@@ -1392,7 +1392,7 @@ export class GoogleInteractionsProvider implements Provider {
         noteProviderTurn(sessionId, "google");
         checkTurnTokens(sessionId, usage);
 
-        // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
+        // Terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
         const hasTerminal = completedBody !== undefined || sawFinishReason || sawUsage;

package/src/providers/openai-compat.ts

@@ -59,7 +59,7 @@ import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported } from "../utils/errors.ts";
 import { withRetries } from "../utils/retry.ts";
-import { ConfigError } from "../types/errors.ts";
+import { ConfigError, ValidationError } from "../types/errors.ts";
 import {
   parseArguments,
   normalizeThinkingParts,
@@ -350,13 +350,7 @@ function assertNoVideoOrFileParts(
     kind === "video"
       ? `[${prefix}/${modelId}] unsupported video input (generic OpenAI-compatible endpoints carry text/image/audio only). Use a video-capable model (e.g. google/gemini-*) or drop the video part.`
       : `[${prefix}/${modelId}] unsupported file input (generic OpenAI-compatible endpoints carry text/image/audio only). Use a file-capable model (e.g. google/gemini-*) or convert the document to text before sending it.`;
-  const err = new Error(message);
-  err.name = "AgentAccelProviderError";
-  Object.defineProperties(err, {
-    provider: { value: prefix, enumerable: false },
-    model: { value: modelId, enumerable: false },
-  });
-  throw err;
+  throw new ValidationError(message, { provider: prefix, model: modelId });
 }
 
 // Text, image (link or data URL) and audio parts as Chat content blocks; in: a user message's parts, out: fullHistoryMessages.
@@ -406,7 +400,7 @@ function resultToOutput(result: unknown): string {
  * resent — except echoed Gemini thought signatures, which strict
  * OpenAI-compatible endpoints require on tool calls they generated.
  *
- * Q-18: signatures are namespaced — only echo when the stored provider is
+ * Signatures are namespaced — only echo when the stored provider is
  * `google` (or untagged legacy). Signatures minted by other providers never
  * leak onto this transport.
  */
@@ -468,7 +462,7 @@ async function fullHistoryMessages(context: ProviderContext): Promise<ChatMessag
           // Echo provider-issued thought signatures verbatim so endpoints
           // that minted them (Gemini behind a compat proxy) keep working.
           // Only present when a previous turn captured one — other endpoints
-          // never see this field. Q-18: echo only google/untagged signatures.
+          // never see this field. Echo only google/untagged signatures.
           const storedProvider = (part as { thoughtSignatureProvider?: unknown }).thoughtSignatureProvider;
           if (part.thoughtSignature && shouldEchoSignature(storedProvider, "google")) {
             call.extra_content = { google: { thought_signature: part.thoughtSignature } };
@@ -540,7 +534,7 @@ function extractSignature(rawTc: {
   return typeof sig === "string" && sig ? sig : undefined;
 }
 
-/** Tags a captured compat signature with its issuing provider (`google`, Q-18). */
+/** Tags a captured compat signature with its issuing provider (`google`). */
 function withCompatSignature(sig: string | undefined): { thoughtSignature?: string; thoughtSignatureProvider?: string } {
   if (!sig) return {};
   return { thoughtSignature: sig, thoughtSignatureProvider: "google" };
@@ -575,7 +569,7 @@ function parseResponse(
 
   const choice = response.choices?.[0];
   const message = choice?.message;
-  // Q-23: refusal content surfaces as text with a `refusal` finish reason.
+  // Refusal content surfaces as text with a `refusal` finish reason.
   const refusal = typeof message?.refusal === "string" && message.refusal ? message.refusal : "";
   const text = typeof message?.content === "string" && message.content ? message.content : refusal;
   // Thinking tolerance: plain `reasoning` plus per-block texts (deepseek-style
@@ -701,7 +695,7 @@ export class OpenAICompatibleChatProvider implements Provider {
   private requireApiKey(baseUrl: string, options?: ProviderRequestOptions): string | undefined {
     const key = this.apiKey(options);
     if (!key && !isLocalEndpoint(baseUrl)) {
-      throw new Error(
+      throw new ConfigError(
         `[Agent Accelerator] Missing API key for "${this.prefix}". Set ${envPrefixOf(this.prefix)}_API_KEY or pass apiKey. (Local endpoints may omit the key.)`
       );
     }
@@ -789,7 +783,7 @@ export class OpenAICompatibleChatProvider implements Provider {
         // why: invalid output shapes fail fast at Agent construction/loop validation.
       }
     }
-    // Q-38: request usage on streams where supported so terminal accounting
+    // Request usage on streams where supported so terminal accounting
     // arrives on the final chunk. Strict servers that reject unknown fields
     // opt out via `COMPAT_NO_STREAM_OPTIONS=1`; an explicit per-call
     // `(options as any).streamOptions === false` also skips it.
@@ -1068,7 +1062,7 @@ export class OpenAICompatibleChatProvider implements Provider {
           const choice = (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
           const delta = (choice["delta"] as Record<string, unknown>) ?? {};
           // Text delta (content-free accounting frames carry "" — ignored).
-          // Q-23: refusal deltas surface as text with a `refusal` finish.
+          // Refusal deltas surface as text with a `refusal` finish.
           const deltaRefusal = delta["refusal"];
           if (typeof deltaRefusal === "string" && deltaRefusal) {
             text += deltaRefusal;
@@ -1187,7 +1181,7 @@ export class OpenAICompatibleChatProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
+        // Terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
         const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();

package/src/providers/openai.ts

@@ -51,6 +51,7 @@ import { clampCacheKey } from "../utils/cache.ts";
 import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported, assertNoVideoPartsOnResponses } from "../utils/errors.ts";
+import { ConfigError } from "../types/errors.ts";
 import { withRetries } from "../utils/retry.ts";
 import {
   parseArguments,
@@ -472,7 +473,7 @@ function parseResponse(
     }
   }
 
-  // Q-23: `incomplete` -> length (content-filter truncations surface as
+  // `incomplete` -> length (content-filter truncations surface as
   // refusal when refusal text is present).
   const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
   const finishReason =
@@ -716,7 +717,7 @@ export class OpenAIResponsesProvider implements Provider {
     const clean = cleanModelId(model);
     const apiKey = resolveApiKey(options);
     if (!apiKey) {
-      throw new Error(
+      throw new ConfigError(
         "[Agent Accelerator] Missing OpenAI API key. Set OPENAI_API_KEY (or OPENAI_BASE_API_KEY) or pass apiKey."
       );
     }
@@ -804,7 +805,7 @@ export class OpenAIResponsesProvider implements Provider {
       try {
         const apiKey = resolveApiKey(options);
         if (!apiKey) {
-          throw new Error(
+          throw new ConfigError(
             "[Agent Accelerator] Missing OpenAI API key. Set OPENAI_API_KEY (or OPENAI_BASE_API_KEY) or pass apiKey."
           );
         }
@@ -828,7 +829,7 @@ export class OpenAIResponsesProvider implements Provider {
           body,
         };
 
-        // Q-17: optional per-call timeout races the linked abort signal.
+        // Optional per-call timeout races the linked abort signal.
         const streamTimeoutMs = timeoutFor(options as { timeoutMs?: number } | undefined);
         // Transient failures (429/5xx/network) are retried here, before the
         // first byte; once the stream is live it is never retried.
@@ -895,7 +896,7 @@ export class OpenAIResponsesProvider implements Provider {
             type === "response.refusal.delta" ||
             type === "response.output_refusal.delta"
           ) {
-            // Q-23: refusal deltas carry the filter text; surface as text and
+            // Refusal deltas carry the filter text; surface as text and
             // remember for a `refusal` finish reason.
             if (typeof msg["delta"] === "string" && msg["delta"]) {
               text += msg["delta"] as string;
@@ -955,7 +956,7 @@ export class OpenAIResponsesProvider implements Provider {
             }
             // Non-streaming maps `incomplete` → `length` (max tokens). Streaming
             // must do the same — otherwise truncated turns misreport `stop`.
-            // Q-23: content-filter incompletes surface as `refusal`.
+            // Content-filter incompletes surface as `refusal`.
             const incompleteReason = (response as { incomplete_details?: { reason?: string } }).incomplete_details?.reason;
             if (response.status === "incomplete") {
               finishReason = incompleteReason === "content_filter" ? "refusal" : "length";
@@ -1039,7 +1040,7 @@ export class OpenAIResponsesProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // Q-23: terminal-state guard. Loops ending with no completed body, no
+        // Terminal-state guard. Loops ending with no completed body, no
         // finish_reason, and no usage while carrying no content must fail as
         // `incomplete_stream` (retryable) instead of resolving empty success.
         // Skipped for non-SSE payloads (e.g. JSON mocks in delegation tests)

package/src/providers/openrouter.ts

@@ -46,7 +46,7 @@ import { buildSessionHeaders, setHeaderCaseInsensitive } from "../utils/headers.
 import { normalizeMediaInput } from "../utils/media.ts";
 import { safeStringify } from "../utils/serialization.ts";
 import { toConciseProviderError, assertModalitiesSupported } from "../utils/errors.ts";
-import { isAbortError } from "../types/errors.ts";
+import { ConfigError, isAbortError } from "../types/errors.ts";
 import {
   newToolCallId,
   redactedHeaders,
@@ -648,7 +648,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
       try {
         const apiKey = resolveApiKey(options);
         if (!apiKey) {
-          throw new Error(
+          throw new ConfigError(
             "[Agent Accelerator] Missing OpenRouter API key. Set OPENROUTER_API_KEY or pass apiKey."
           );
         }
@@ -741,7 +741,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           const choice = (Array.isArray(msg["choices"]) ? (msg["choices"] as Record<string, unknown>[])[0] : undefined) ?? {};
           const delta = (choice["delta"] as Record<string, unknown>) ?? {};
           // Text delta (content-free accounting frames carry "" — ignored).
-          // Q-23: refusal deltas surface as text with a `refusal` finish.
+          // Refusal deltas surface as text with a `refusal` finish.
           const deltaRefusal = delta["refusal"];
           if (typeof deltaRefusal === "string" && deltaRefusal) {
             text += deltaRefusal;
@@ -854,7 +854,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
           sawFinishReason = true;
         }
 
-        // Q-23: terminal-state guard — fail `incomplete_stream` (retryable)
+        // Terminal-state guard — fail `incomplete_stream` (retryable)
         // instead of resolving empty success. Skipped for non-SSE payloads
         // (JSON mocks) where no SSE frames were ever seen.
         const cleanThinking = thinking.replace(/\n{3,}/g, "\n\n").trim();

package/src/providers/registry.ts

@@ -1,3 +1,4 @@
+import { ConfigError } from "../types/errors.ts";
 import type { Provider, ProviderId, ModelSpec } from "../types/model.ts";
 import type { ThinkingLevel } from "../types/core.ts";
 import { OpenAICompatibleChatProvider } from "./openai-compat.ts";
@@ -54,7 +55,7 @@ function removedProviderMessage(id: string): string {
 /** Throws for removed provider prefixes. */
 function assertProviderNotRemoved(id: string): void {
   if (REMOVED_PROVIDERS.has(id.trim().toLowerCase())) {
-    throw new Error(removedProviderMessage(id.trim()));
+    throw new ConfigError(removedProviderMessage(id.trim()));
   }
 }
 
@@ -83,7 +84,7 @@ export function ensureCustomProvider(
   const id = normalizeProviderPrefix(prefix) as ProviderId;
   if (FIRST_CLASS.has(id.toLowerCase())) {
     if (opts?.baseUrl !== undefined || opts?.apiKey !== undefined) {
-      throw new Error(
+      throw new ConfigError(
         `[Agent Accelerator] Provider "${id}" is first-class and cannot be replaced with custom baseUrl/apiKey. Pass baseUrl/apiKey per-Agent instead.`
       );
     }
@@ -93,7 +94,7 @@ export function ensureCustomProvider(
   if (existing) {
     const prevBase = (existing as { configuredBaseUrl?: string }).configuredBaseUrl;
     if (opts?.baseUrl !== undefined && prevBase !== undefined && prevBase !== opts.baseUrl) {
-      throw new Error(
+      throw new ConfigError(
         `[Agent Accelerator] Conflicting re-registration for provider "${id}". Registry is immutable after creation.`
       );
     }
@@ -120,7 +121,7 @@ export function getProvider(id: ProviderId | string): Provider {
   const provider = providerRegistry.get(key);
   if (provider) return provider;
   if (!key) {
-    throw new Error(
+    throw new ConfigError(
       `Provider '' is not supported or not registered. Available first-support providers: google, openrouter, openai — or any custom prefix via {PREFIX}_API_KEY + {PREFIX}_BASE_URL.`
     );
   }
@@ -146,7 +147,7 @@ export interface ResolvedModel {
  */
 export function resolveModel(model: string | ModelSpec): ResolvedModel {
   if (!model || (typeof model === "string" && !model.trim())) {
-    throw new Error(
+    throw new ConfigError(
       "[Agent Accelerator] No model specified. Please specify 'model' in Agent configuration or set the MODEL environment variable."
     );
   }

package/src/providers/shared.ts

@@ -1,5 +1,5 @@
 /**
- * Shared provider helpers (Q-45-partial).
+ * Shared provider helpers.
  *
  * Single home for the `redactedHeaders` / `readErrorPayload` /
  * `parseArguments` / `normalizeThinkingParts` helpers previously duplicated
@@ -78,7 +78,7 @@ export function readErrorPayload(
   }
 }
 
-/** Retryable incomplete-stream error for truncated SSE (Q-23). */
+/** Retryable incomplete-stream error for truncated SSE: a `ProviderError` whose `code` is `incomplete_stream`. */
 export function incompleteStreamError(provider: string, modelId: string): Error {
   const err = toConciseProviderError(
     Object.assign(new Error("Stream ended without terminal event"), {
@@ -110,15 +110,11 @@ export function isNotFoundChainError(error: unknown): boolean {
       NaN
   );
   if (status === 404) return true;
-  const code = String(
-    (err["code"] as string | undefined) ??
-      (err["errorType"] as string | undefined) ??
-      ""
-  ).toLowerCase();
-  return code === "not_found";
+  // `providerCode` on a wrapped ProviderError (its `code` is the SDK kind), `code` on a raw error.
+  return [err["providerCode"], err["code"], err["errorType"]].some((c) => String(c ?? "").toLowerCase() === "not_found");
 }
 
-/** Per-request timeout ms from provider options (Q-22). */
+/** Per-request timeout ms from provider options. */
 export function timeoutFor(options: { timeoutMs?: number } | undefined): number | undefined {
   const t = (options as { timeoutMs?: unknown } | undefined)?.timeoutMs;
   return typeof t === "number" && Number.isFinite(t) && t > 0 ? Math.floor(t) : undefined;
@@ -149,7 +145,7 @@ export function combinedSignal(signal?: AbortSignal, timeoutMs?: number): { sign
   return { signal: ctrl.signal, cleanup };
 }
 
-/** Q-34: crypto-backed tool-call id, no Math.random primary. */
+/** Crypto-backed tool-call id, no Math.random primary. */
 export function newToolCallId(prefix = "call"): string {
   try {
     const c = (globalThis as any)?.crypto;

package/src/scheduler/architecture.md

@@ -4,16 +4,19 @@ Scheduled actions: a worker that runs later (once or repeating) and saves its an
 
 | File | What it is |
 | :-- | :-- |
-| `scheduler.ts` | One `Scheduler` per home folder: a 1 s unref'd clock that runs only while something is pending, startup sweep, cook/deliver state machine, and the public functions (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`). |
-| `store.ts` | Disk layer under `<home>/scheduled_actions/`: `tasks.json`, `deliveries.json`, run files; validation of records. |
+| `scheduler.ts` | One `Scheduler` per home folder: a 1 s unref'd clock that runs only while something is pending, startup sweep, dead-owner recovery, heartbeats, cook/deliver state machine, and the public functions (`createScheduledAction`, `list/update/run/skip/deleteScheduledAction`). |
+| `store.ts` | Disk layer under `<home>/scheduled/`: `<id>/task.json`, `<id>/delivery.json`, run files, one short mutex per action; validation of records. |
 | `time.ts` | Pure `DD:HH:MM` and local-clock maths. No timezone, DST or `Intl`; `now` is always passed in. |
 | `tool.ts` + `scheduled-actions.md` | The model-facing `scheduled_actions` tool and `get_datetime`; the `.md` is the tool description. |
 
 ## Invariants
 - The files are the truth: every write re-reads first and goes through the durable writer. The file format is a stable public contract: see `docs/scheduled-action-files.md` and add a changelog row for any change.
-- Write order when a run ends: run file, then `deliveries.json`, then `tasks.json`. The startup sweep repairs a crash in between.
+- Write order when a run ends: run file, then `<id>/delivery.json`, then `<id>/task.json`. A crash in between is repaired by the dead-owner recovery (`recoverCooking`, at start and every 15 s): the delivery is rebuilt from the run file, or the run is marked `missed` when no run file exists.
 - `startCook` advances the next times BEFORE the run starts; a run still cooking when the next is due is skipped, never stacked.
 - Runs are fresh stateless workers built by `buildDynamicWorkerConfig`; their spending guardrail is `workerBudget` only.
 - The Agent registry holds `WeakRef`s by name: keep every Agent that owns actions referenced, or its runs become `missed`.
+- Several processes may share a home: scheduled actions take no home lock, only the short per-action mutex (`<id>/.mutex`); the one-process lock is on session folders only. Ownership: a process only starts, delivers or recovers actions whose Agent it registered. An action nobody here owns is left alone until its delivery time passed with no run started, then marked `missed` (`no_agent`).
+- Exactly once: a scheduled start re-checks under the action's mutex that it is still `waiting` and due; `markMissed` only changes the state the caller saw; a delivery is emitted only by the process that removed its entry from `delivery.json`.
+- A run in flight keeps `<id>/.heartbeat` (pid, host, token; mtime refreshed every 5 s, stale after 60 s), written before the record shows `cooking`. A cooking action whose owner is dead (pid gone, stale, or none) is recovered by a live process that owns its Agent, at start and every 15 s. `delete` of a run another live process is cooking is refused, even with `force`.
 - Times come from `Date`, local clock only. Tests inject `scheduler.now` / `tickMs` and call `tick()`.
 - Events: `scheduled_action.{created,updated,started,ready,failed,delivered,missed,skipped,deleted,invalid,store_corrupt,error}`.