agent-accelerator 0.5.8 → 0.5.9

package/README.md

@@ -126,7 +126,7 @@ An `Agent` holds:
 | `cache`           | `CacheOption`                                        | `"implicit" \| "5m" \| "30m" \| "1h" \| "12h"`. Prompt-cache lifetime; unsupported values warn and fall back (see [Cache](#cache)).                                                                             |
 | `serviceTier`     | `"flex" \| "priority"`                               | Cost / priority routing where supported. Omit for standard routing.                                                                                        |
 | `maxTurns`        | `number`                                             | Maximum model → tool → model loops per `run`. Infinite by default (`0` or omitted = no limit). Hitting a finite limit with pending tool calls warns and sets `finishReason: "max_turns"`. |
-| `limits`          | `AgentRunLimits`                                     | `{ maxTurns?, deadlineMs?, maxToolCallsPerRun?, maxTotalTokens?, requestTimeoutMs?, firstByteTimeoutMs?, streamIdleTimeoutMs? }`. The first four are unlimited by default. The three network timeouts default to 300 s / 120 s / 300 s so a silent connection fails instead of hanging; set one to `0` or `Infinity` to turn it off. A timeout raises a retryable `TimeoutError`. See [Safety and operations](docs/guides/safety-and-ops.md#network-timeouts). |
+| `limits`          | `AgentRunLimits`                                     | `{ maxTurns?, deadlineMs?, maxToolCallsPerRun?, maxTotalTokens?, requestTimeoutMs?, firstByteTimeoutMs?, streamIdleTimeoutMs? }`. The first four are unlimited by default; hitting `maxTurns` ends the run with `finishReason: "max_turns"`, the other three throw a `BudgetExceededError`. The three network timeouts default to 300 s / 120 s / 300 s so a silent connection fails instead of hanging; set one to `0` or `Infinity` to turn it off. A timeout raises a retryable `TimeoutError`. See [Safety and operations](docs/guides/safety-and-ops.md#network-timeouts). |
 | `budget`          | `Budget`                                             | `{ maxCostUsd?, maxTotalTokens?, maxDurationMs?, maxTotalSubagents? }`, per run, workers included. Unlimited by default; exceeding it throws `BudgetExceededError` with partial usage. |
 | `sessionId`       | `string`                                             | Stable identifier used for cache affinity. Auto-generated when omitted.                                                                                    |
 | `headers`         | `Record<string,string>`                              | Additional headers merged into every request.                                                                                                              |
@@ -1089,16 +1089,35 @@ Credential headers are always redacted (`Authorization`, `x-goog-api-key`, anyth
 ---
 ## Errors
 
-Provider failures throw `AgentAccelProviderError` — one actionable line,
+Provider failures throw a `ProviderError` — one actionable line,
 never a wire dump:
 
 ```text
 [openrouter/nvidia/nemotron-3.5-lightning:free] request failed (404): No endpoints found that support input video
 ```
 
-Raw details (`statusCode`, `url`, truncated body) stay attached as
+Branch on the class and `err.retryable` (true for HTTP 408/425/429/5xx,
+network errors and a cut stream), never on the message:
+
+```ts
+import { ProviderError, TimeoutError } from "agent-accelerator";
+
+try {
+  await agent.run("...");
+} catch (err) {
+  if (err instanceof ProviderError && err.retryable) retryLater(); // e.g. a 429 or 503
+  else if (err instanceof TimeoutError) retryLater(); // a request / first-byte / idle timeout
+  else throw err;
+}
+```
+
+`err.code` is the SDK kind (`"provider"`, `"incomplete_stream"` for a cut
+stream; `"timeout"`, `"config"`, ... on the other classes); the provider's own
+error code (e.g. `"not_found"`, `"rate_limit_exceeded"`) is `err.providerCode`.
+Raw details (`statusCode`, `url`, truncated body, `providerCode`) stay attached as
 non-enumerable properties: available programmatically, invisible in runtime
-dumps. URL query strings are stripped (keys sometimes live there); headers
+dumps. Input a model cannot take (a modality the catalog says it lacks, video on
+the OpenAI Responses wire) fails before the network with a `ValidationError`. URL query strings are stripped (keys sometimes live there); headers
 and cookies are never attached. Helpers:
 
 * `toConciseProviderError(err, providerId, modelId)` — collapse any provider error.

package/package.json

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

package/src/agent/agent.ts

@@ -63,7 +63,7 @@ export function resolveEffectiveThinking(
   return { enabled: true, level: overrideLevel as ThinkingConfig["level"] };
 }
 
-import { ConfigError, SessionLoadError, isAbortError } from "../types/errors.ts";
+import { ConfigError, SessionLoadError, ValidationError, isAbortError } from "../types/errors.ts";
 
 /**
  * Disposers for the manual user-signal forward listeners (fallback when
@@ -697,13 +697,15 @@ export class Agent {
     return out || undefined;
   }
 
-  /** Clears conversation messages and provider thought signatures while keeping configuration. */
+  /** Starts a fresh conversation: clears messages, signatures, run marks and the run's saved tool results, keeps config and spending totals. */
   reset(): void {
     const sid = this.sessionId;
     this.context.messages = [];
     this.context.thoughtSignatures = [];
     this.context.systemPrompt = this.getFullInstructions();
     this.runMarks.length = 0;
+    this.toolRecords.length = 0; // a cleared conversation has no run to resume, so its finished tool results go too
+    this.activeMark = undefined;
     // Reset also drops session-scoped provider chaining/routing.
     try { clearInteractionChains(sid); } catch {}
     try { clearSessionRouting(sid); } catch {}
@@ -837,7 +839,7 @@ export class Agent {
   // Throws synchronously on an empty content-part array so run() and stream() fail at the same moment; in: any prompt entry point, out: nothing.
   private assertPromptValid(prompt: string | ContentPart[]): void {
     if (Array.isArray(prompt) && prompt.length === 0) {
-      throw new Error(
+      throw new ValidationError(
         "[Agent Accelerator] Prompt cannot be empty: pass a non-empty string or at least one content part."
       );
     }
@@ -1693,7 +1695,7 @@ export class Agent {
     // Prompt validation throws synchronously in both run() and
     // stream() (same timing; documented here).
     if (Array.isArray(prompt) && prompt.length === 0) {
-      throw new Error(
+      throw new ValidationError(
         "[Agent Accelerator] Prompt cannot be empty: pass a non-empty string or at least one content part."
       );
     }
@@ -2254,7 +2256,7 @@ export class Agent {
 /** What a failed run attempt got done before it failed (the `partial` the loop attaches to its error). */
 type FailedAttempt = Partial<AgentResponse> & { usage: TokenUsage };
 
-// Adds what failed attempts already did (tool calls, results, turns, token usage) to the response of the attempt that finally worked, so a retry never hides side effects or cost; in: the final response + each failed attempt's `err.partial`, out: the run's AgentResponse.
+// Adds what failed attempts already did (tool calls, results, workers, turns, token usage) to the response of the attempt that finally worked, so a retry never hides side effects or cost; in: the final response + each failed attempt's `err.partial`, out: the run's AgentResponse.
 function withFailedAttempts(res: AgentResponse, failed: FailedAttempt[]): AgentResponse {
   const usage: TokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
   for (const f of failed) accumulateUsage(usage, f.usage);
@@ -2266,7 +2268,7 @@ function withFailedAttempts(res: AgentResponse, failed: FailedAttempt[]): AgentR
     thoughtSignature: res.thoughtSignature,
     toolCalls: [...failed.flatMap((f) => f.toolCalls ?? []), ...res.toolCalls],
     toolResults: [...failed.flatMap((f) => f.toolResults ?? []), ...res.toolResults],
-    subagents: res.subagents,
+    subagents: [...failed.flatMap((f) => f.subagents ?? []), ...res.subagents],
     usage,
     responseId: res.responseId,
     model: res.model,

package/src/agent/architecture.md

@@ -23,3 +23,4 @@ The agent and everything that runs under it.
 - Exactly-once worker calls rest on the call key (parent run mark id + tool call id) and `meta.last`.
 - Only results branded by `makeSubagentResult` have their usage metadata trusted.
 - Each Agent records only its own model turns; never sum `AgentResponse.usage` for totals.
+- `reset()` clears the conversation (messages, run marks, the run's saved tool results) but never the spending totals.

package/src/agent/loop.ts

@@ -23,7 +23,7 @@ import {
 import { getModelFromCatalog, ensureModelCatalogFresh, validateModelThinking } from "../models/catalog.ts";
 import { enforceFileAccess } from "../utils/safe-io.ts";
 import { isSubagentResult, normalizeSubagentMetadata } from "../tools/subagent-result.ts";
-import { BudgetExceededError } from "../types/errors.ts";
+import { BudgetExceededError, TimeoutError } from "../types/errors.ts";
 import { applyCaptureRaw, type CaptureRawMode } from "../utils/raw-capture.ts";
 import { previewPrompt } from "../utils/session.ts";
 import { noteProviderTurn, normalizeStructuredOutput, parseStructuredOutput } from "../providers.ts";
@@ -389,7 +389,7 @@ function checkTokenLimit(usage: TokenUsage, maxTotalTokens: number): void {
 // Throws when the run has been going longer than limits.deadlineMs; in: both loops each turn, out: nothing or a thrown error.
 function checkDeadline(startTime: number, deadlineMs: number): void {
   if (Number.isFinite(deadlineMs) && deadlineMs !== Infinity && Date.now() - startTime > deadlineMs) {
-    throw new Error(`[Agent Accelerator] Run deadline exceeded after ${deadlineMs}ms.`);
+    throw new BudgetExceededError(`[Agent Accelerator] Run deadline exceeded after ${deadlineMs}ms.`);
   }
 }
 
@@ -400,9 +400,7 @@ async function generateWithTimeout<T>(task: () => Promise<T>, timeoutMs: number)
   try {
     const timeoutP = new Promise<never>((_, reject) => {
       timer = setTimeout(() => {
-        const e = new Error(`[Agent Accelerator] Request timed out after ${timeoutMs}ms.`);
-        e.name = "TimeoutError";
-        reject(e);
+        reject(new TimeoutError(`[Agent Accelerator] Request timed out after ${timeoutMs}ms.`));
       }, timeoutMs);
       try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
     });
@@ -859,7 +857,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
     allToolCalls.push(...genResult.toolCalls);
     // Per-run tool-call budget.
     if (allToolCalls.length > limits.maxToolCallsPerRun) {
-      throw new Error(
+      throw new BudgetExceededError(
         `[Agent Accelerator] maxToolCallsPerRun exceeded (${allToolCalls.length} > ${limits.maxToolCallsPerRun}).`
       );
     }
@@ -998,6 +996,7 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
         turns,
         toolCalls: allToolCalls,
         toolResults: allToolResults,
+        subagents: allSubagents,
         text: finalResult?.text,
       };
     } catch {
@@ -1191,11 +1190,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
               Number.isFinite(waitMs) && waitMs !== Infinity && waitMs > 0
                 ? new Promise<never>((_, reject) => {
                     timer = setTimeout(() => {
-                      const e = new Error(
-                        `[Agent Accelerator] Stream ${first ? "first-byte" : "idle"} timed out after ${waitMs}ms.`
-                      );
-                      e.name = "TimeoutError";
-                      reject(e);
+                      reject(new TimeoutError(`[Agent Accelerator] Stream ${first ? "first-byte" : "idle"} timed out after ${waitMs}ms.`));
                     }, waitMs);
                     try { (timer as unknown as { unref?: () => void }).unref?.(); } catch {}
                   })
@@ -1311,7 +1306,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         emitProgress(config); // the calls are on record BEFORE they run, so a crash can finish them instead of forgetting them
         allToolCalls.push(...turnResponse.toolCalls);
         if (allToolCalls.length > streamLimits.maxToolCallsPerRun) {
-          throw new Error(
+          throw new BudgetExceededError(
             `[Agent Accelerator] maxToolCallsPerRun exceeded (${allToolCalls.length} > ${streamLimits.maxToolCallsPerRun}).`
           );
         }
@@ -1444,6 +1439,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
             turns,
             toolCalls: allToolCalls,
             toolResults: allToolResults,
+            subagents: allSubagents,
             text: lastResponse?.text,
           }; } catch {}
           outerStream.fail(raw);
@@ -1504,6 +1500,7 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
         turns,
         toolCalls: allToolCalls,
         toolResults: allToolResults,
+        subagents: allSubagents,
         text: lastResponse?.text,
       };
       // Aborts always surface as AbortError with partial attached.

package/src/agent/worker.ts

@@ -5,6 +5,7 @@ import type { Agent } from "./agent.ts";
 import { normalizeToolName } from "../tools/executor.ts";
 import { getModel, getSubModel } from "../utils/env.ts";
 import { resolveModel } from "../providers/registry.ts";
+import { ConfigError } from "../types/errors.ts";
 
 /** Minimal live-trace shape shared by fixed + dynamic workers (structural subset of `SubAgentTrace`). */
 export interface LiveWorkerTrace {
@@ -134,7 +135,7 @@ export function resolveDynamicModelInput(
 export function resolveSubAgentModel(config: { name?: string; model?: AgentConfig["model"] }): NonNullable<AgentConfig["model"]> {
   const resolvedModel = config.model ?? getSubModel() ?? getModel();
   if (!resolvedModel) {
-    throw new Error(
+    throw new ConfigError(
       `[Agent Accelerator] SubAgent '${config.name || "subagent"}' requires a model. ` +
         `Specify 'model' in SubAgent config, or set SUB_AGENT_MODEL or MODEL in environment variables.`
     );

package/src/models/architecture.md

@@ -5,7 +5,7 @@ The model catalog: context limits, prices, modalities and reasoning options come
 | 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`.

package/src/models/catalog.ts

@@ -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
@@ -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);
-    }
   }
 }
 

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.`
     );
@@ -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."
           );
         }

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.
@@ -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.)`
       );
     }

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,
@@ -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."
           );
         }

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."
           );
         }

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

@@ -78,7 +78,7 @@ export function readErrorPayload(
   }
 }
 
-/** Retryable incomplete-stream error for truncated SSE. */
+/** 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,12 +110,8 @@ 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. */

package/src/scheduler/architecture.md

@@ -4,18 +4,18 @@ 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`). |
+| `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 `<id>/delivery.json`, then `<id>/task.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 (the file store is safe for it; the home lock is lifted in a later change of this release). 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`).
+- 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()`.

package/src/utils/architecture.md

@@ -12,8 +12,8 @@ Small shared helpers. Each file has one job.
 | `safe-io.ts` | `fileAccess.roots` containment and the guarded remote fetch (private hosts refused, redirects re-checked, size cap). |
 | `raw-capture.ts` | The `captureRaw` policy for `AgentResponse.raw`. |
 | `cache.ts` | Cache-key clamp (64 chars) and the central secret redaction. |
-| `errors.ts` | `toConciseProviderError` and pre-network modality guards. |
-| `retry.ts` | `withRetries`, `isTransientError`, `isRetryableRun`, `sleep`. Structured data only (status, code, flags), never message text. |
+| `errors.ts` | `toConciseProviderError` (any raw provider failure becomes one-line `ProviderError`: `code` `"provider"`, `retryable` from status/code, the provider's code as `providerCode`; SDK errors pass through), `isTransientError`, and the pre-network modality guards (`ValidationError`). |
+| `retry.ts` | `withRetries`, `isTransientError` (re-exported from `errors.ts`), `isRetryableRun`, `sleep`. Structured data only (status, code, flags), never message text. |
 | `session.ts` | Id helpers (`createSessionId`, `hashSessionPart`, `createTrackingId`, run/turn ids), `parseModelRef`, `previewPrompt`. |
 | `serialization.ts` | `toJsonSafe`, `safeStringify`, `escapeXml`. |
 | `base64.ts`, `thought-signature.ts` | Runtime-agnostic base64; Gemini thought-signature helpers. |

package/src/utils/errors.ts

@@ -1,5 +1,32 @@
 import type { ProviderContext } from "../types/message.ts";
 import { getModelFromCatalog } from "../models/catalog.ts";
+import { AgentAccelError, ProviderError, ValidationError, isAbortError } from "../types/errors.ts";
+
+/**
+ * Checks whether a provider error is transient and safe to retry.
+ * Structured-data only: status / code / transient flag. Never message text,
+ * so a 400 mentioning "512 tokens" is not retried.
+ */
+export function isTransientError(error: unknown): boolean {
+  if (!error) return false;
+  if (isAbortError(error)) return false;
+  const err = error as Record<string, unknown>;
+  if (err["transient"] === true) return true;
+  if ((err as { retryable?: unknown }).retryable === true) return true;
+  const status = Number(
+    (err["status"] as number | undefined) ??
+      (err["statusCode"] as number | undefined) ??
+      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      ((err["lastError"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      NaN
+  );
+  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
+  const code = String((err["providerCode"] as string | undefined) ?? (err["code"] as string | undefined) ?? "").toUpperCase();
+  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "EPIPE", "ETIMEDOUT"].includes(code)) {
+    return true;
+  }
+  return false;
+}
 
 const CONCISE = "__agentAccelConcise";
 
@@ -49,12 +76,12 @@ function displayModel(providerId: string, modelId: string): string {
 }
 
 /**
- * Collapses a raw provider error (which carries the full request/response
- * dump as enumerable props) into a one-line actionable error. Raw details stay
- * available but non-enumerable, so runtime dumps stay small.
+ * Collapses a raw provider error (which carries the full request/response dump as enumerable props) into a one-line
+ * `ProviderError` with `retryable` set from its status/code; the provider's own error code is `providerCode`. Raw
+ * details stay available but non-enumerable, so runtime dumps stay small. An SDK error (already typed) passes through.
  */
 export function toConciseProviderError(error: unknown, providerId: string, modelId: string): Error {
-  if (error instanceof Error && (error as any)[CONCISE]) return error;
+  if (error instanceof AgentAccelError || (error instanceof Error && (error as any)[CONCISE])) return error;
   const err = error as any;
   const status = readStatus(err);
   const url = readUrl(err);
@@ -70,10 +97,10 @@ export function toConciseProviderError(error: unknown, providerId: string, model
   if (rawMeta && !detail.includes(rawMeta.slice(0, 80))) {
     detail = `${detail}\n${rawMeta.slice(0, 500)}`.slice(0, 800);
   }
-  const concise = new Error(
-    `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`
+  const concise = new ProviderError(
+    `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`,
+    { status, provider: providerId, model: modelId, retryable: isTransientError(err) }
   );
-  concise.name = "AgentAccelProviderError";
   Object.defineProperties(concise, {
     [CONCISE]: { value: true, enumerable: false },
     statusCode: { value: status, enumerable: false },
@@ -90,11 +117,10 @@ export function toConciseProviderError(error: unknown, providerId: string, model
     ...(typeof err?.errorType === "string"
       ? { errorType: { value: err.errorType, enumerable: false } }
       : {}),
-    // Forwarded when present (e.g. Google's `not_found` chain-eviction code,
-    // which carries no HTTP status on SSE error frames). Survives re-wraps
-    // so chain-expiry detectors never lose it.
+    // The provider's own error code (e.g. Google's `not_found` chain-eviction code, which carries no HTTP status on
+    // SSE error frames); `code` itself is the SDK kind (`"provider"`). Survives re-wraps so chain detectors never lose it.
     ...((typeof err?.code === "string" || typeof err?.code === "number") && err.code !== ""
-      ? { code: { value: err.code, enumerable: false } }
+      ? { providerCode: { value: err.code, enumerable: false } }
       : {}),
     // Server rate-limit hint in ms (from Retry-After); survives re-wraps so
     // `withRetries` can honor it instead of hammering a 429.
@@ -120,7 +146,7 @@ const PART_TO_MODALITY: Record<string, "image" | "audio" | "video" | "pdf"> = {
  * lacks a requested input modality (image/audio/video/document; files are
  * not checked on OpenRouter, which parses them for any model). Unknown
  * models (custom providers, dynamic routers) are skipped: the provider
- * verdict stands and surfaces via toConciseProviderError instead.
+ * verdict stands and surfaces via toConciseProviderError instead. Throws a `ValidationError`.
  */
 export function assertModalitiesSupported(
   context: ProviderContext,
@@ -147,16 +173,10 @@ export function assertModalitiesSupported(
   if (!supported) return;
   const missing = [...needed].filter((k) => !supported.includes(k));
   if (missing.length === 0) return;
-  const err = new Error(
-    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.`
+  throw new ValidationError(
+    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.`,
+    { provider: providerId, model: modelId }
   );
-  err.name = "AgentAccelProviderError";
-  Object.defineProperties(err, {
-    [CONCISE]: { value: true, enumerable: false },
-    provider: { value: providerId, enumerable: false },
-    model: { value: modelId, enumerable: false },
-  });
-  throw err;
 }
 
 /**
@@ -169,7 +189,7 @@ export function assertModalitiesSupported(
  * `openrouter/stealth/space-bunny-alpha` under the old Responses skin despite
  * its catalog `video` flag, which is chat-transport oriented). Fail fast with
  * a clear one-liner instead; video stays Gemini-only, and OpenRouter Chat
- * Completions carries `video_url` natively (no guard there).
+ * Completions carries `video_url` natively (no guard there). Throws a `ValidationError`.
  */
 export function assertNoVideoPartsOnResponses(
   context: ProviderContext,
@@ -197,14 +217,8 @@ export function assertNoVideoPartsOnResponses(
     // contradict the rejection).
     if (known && known.length > 0) supported = known.filter((m) => m !== "video").join(", ") || "text";
   } catch {}
-  const err = new Error(
-    `[${displayModel(providerId, modelId)}] unsupported video input (the Responses API accepts text/image/file only; supports: ${supported}). Use a video-capable model (e.g. google/gemini-*) or drop the video part.`
+  throw new ValidationError(
+    `[${displayModel(providerId, modelId)}] unsupported video input (the Responses API accepts text/image/file only; supports: ${supported}). Use a video-capable model (e.g. google/gemini-*) or drop the video part.`,
+    { provider: providerId, model: modelId }
   );
-  err.name = "AgentAccelProviderError";
-  Object.defineProperties(err, {
-    [CONCISE]: { value: true, enumerable: false },
-    provider: { value: providerId, enumerable: false },
-    model: { value: modelId, enumerable: false },
-  });
-  throw err;
 }

package/src/utils/headers.ts

@@ -24,7 +24,7 @@ export function getPackageVersion(): string {
     const v = (globalThis as any).process?.env?.npm_package_version;
     if (typeof v === "string" && v) return v;
   } catch {}
-  return "0.5.8";
+  return "0.5.9";
 }
 
 // User-Agent string with version and platform; in: AGENT_ACCEL_USER_AGENT, out: a string.

package/src/utils/retry.ts

@@ -1,33 +1,7 @@
-import { toConciseProviderError } from "./errors.ts";
+import { toConciseProviderError, isTransientError } from "./errors.ts";
 import { isAbortError } from "../types/errors.ts";
 
-export { isAbortError };
-
-/**
- * Checks whether a provider error is transient and safe to retry.
- * Structured-data only: status / code / transient flag. Never message text,
- * so a 400 mentioning "512 tokens" is not retried.
- */
-export function isTransientError(error: unknown): boolean {
-  if (!error) return false;
-  if (isAbortError(error)) return false;
-  const err = error as Record<string, unknown>;
-  if (err["transient"] === true) return true;
-  if ((err as { retryable?: unknown }).retryable === true) return true;
-  const status = Number(
-    (err["status"] as number | undefined) ??
-      (err["statusCode"] as number | undefined) ??
-      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
-      ((err["lastError"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
-      NaN
-  );
-  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
-  const code = String((err["code"] as string | undefined) ?? "").toUpperCase();
-  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "EPIPE", "ETIMEDOUT"].includes(code)) {
-    return true;
-  }
-  return false;
-}
+export { isAbortError, isTransientError };
 
 /**
  * Whether a FAILED RUN (the provider layer already retried the call) is worth trying again: the failure is transient