agent-accelerator 0.3.0 → 0.4.5

package/src/tools/tool.ts

@@ -4,7 +4,90 @@ import type {
   StandardToolDeclaration,
   ToolExecuteFn,
 } from "../types/tool.ts";
+import type { ThinkingLevel } from "../types/core.ts";
+import type { ThinkingOption } from "../types/agent.ts";
 import { zodToJsonSchema } from "./schema.ts";
+import { ConfigError } from "../types/errors.ts";
+
+/**
+ * Valid tool-name pattern (Q-55): 1–64 chars of letters, digits, `_`, `-`.
+ * Names are validated at registration in {@link tool} (record-key fallback
+ * included); invalid names throw `ConfigError` with a fix.
+ */
+export const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+
+/**
+ * Throws `ConfigError` when `name` is not a valid tool name.
+ *
+ * @example `assertValidToolName("get_status");`
+ */
+export function assertValidToolName(name: string): void {
+  if (!TOOL_NAME_PATTERN.test(name)) {
+    throw new ConfigError(
+      `[Agent Accelerator] Invalid tool name "${name}": expected 1-64 characters of letters, digits, "_" or "-". ` +
+        `Fix: rename the tool (e.g. "get_status").`
+    );
+  }
+}
+
+/**
+ * Normalizes the Q-52 canonical `thinking` option to a bare level.
+ * Accepts a level string or `{ level, budgetTokens }`; `budgetTokens` is
+ * carried separately by providers, so only the level is returned here.
+ * Resolution honors `thinking ?? thinkingLevel`.
+ *
+ * @example `normalizeThinkingV2({ level: "medium" }, "low"); // "medium"`
+ */
+export function normalizeThinkingV2(
+  thinking?: ThinkingOption,
+  thinkingLevel?: ThinkingLevel
+): ThinkingLevel | undefined {
+  if (thinking !== undefined) {
+    if (typeof thinking === "string") return thinking;
+    return thinking.level ?? thinkingLevel;
+  }
+  return thinkingLevel;
+}
+
+/**
+ * Resolves the Q-51 canonical busy policy. `whenBusy` wins over `mode`.
+ *
+ * @example `resolveWhenBusy({ whenBusy: "queue", mode: "steer" }); // "queue"`
+ */
+export function resolveWhenBusy(
+  config?: { mode?: "steer" | "queue" | "auto"; whenBusy?: "steer" | "queue" | "auto" }
+): "steer" | "queue" | "auto" {
+  const v = config?.whenBusy ?? config?.mode ?? "auto";
+  return v === "steer" || v === "queue" ? v : "auto";
+}
+
+/**
+ * Maps the Q-52 canonical worker-timeout knobs to the legacy `timeout` value
+ * (`0` = no limit, `-1` = model sets per-task `timeoutMs`, `>0` = fixed ms).
+ * An explicit `timeout`/`workerTimeoutMs` wins over `modelMaySetTimeout`.
+ *
+ * @example `normalizeWorkerTimeout({ modelMaySetTimeout: true }); // -1`
+ */
+export function normalizeWorkerTimeout(
+  config?: { timeout?: number; workerTimeoutMs?: number; modelMaySetTimeout?: boolean }
+): number {
+  const explicit = config?.workerTimeoutMs ?? config?.timeout;
+  if (Number.isFinite(explicit as number)) return Math.floor(explicit as number);
+  if (config?.modelMaySetTimeout === true) return -1;
+  return 0;
+}
+
+/**
+ * Normalizes the Q-52 `maxAttempts` alias to a `maxTries` value.
+ * `maxTries` wins when both are set.
+ *
+ * @example `normalizeMaxAttempts({ maxAttempts: 3 }); // 3`
+ */
+export function normalizeMaxAttempts(
+  config?: { maxTries?: number | string; maxAttempts?: number | string }
+): number | string | undefined {
+  return config?.maxTries ?? config?.maxAttempts;
+}
 
 /** Complete configuration accepted by {@link tool}. */
 export interface CreateToolOptions<TInput = any, TOutput = any> {
@@ -22,8 +105,54 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
   timeoutMs?: number;
   /** Maximum total attempts for transient failures. `0`/omitted means no configured limit. */
   maxTries?: number | string;
+  /**
+   * Canonical alias for `maxTries` (Q-52). When both are set, `maxTries` wins.
+   * Normalized by `normalizeMaxAttempts`.
+   */
+  maxAttempts?: number | string;
   /** Maximum simultaneous executions of this tool. `0`/omitted uses the global pool. */
   maxConcurrency?: number | string;
+  /**
+   * Whether this tool is safe to retry on transient failures. Retry defaults
+   * to a single attempt unless this is `true` (bounded retries) or `maxTries`
+   * explicitly overrides the attempt count.
+   */
+  idempotent?: boolean;
+  /**
+   * Whether an identical call may repeat across consecutive turns. Defaults to
+   * `true` for idempotent tools, `false` otherwise. Honored by repeat guards.
+   */
+  repeatable?: boolean;
+  /**
+   * Maximum characters of a string tool result kept for model context.
+   * Longer strings are truncated with a `[Truncated: ...]` marker.
+   * `0`/omitted uses the executor default (20000).
+   */
+  maxResultChars?: number | string;
+  /** Optional hook to redact/replace the error message sent back to the model. */
+  redactError?: (err: unknown) => string;
+  /**
+   * Canonical alias for `redactError` (Q-55). When both are set,
+   * `redactError` wins.
+   */
+  redact?: (err: unknown) => string;
+  /**
+   * Explicit retry policy (Q-55). Preferred over bare `maxTries` for new
+   * code; the executor reads via `(toolDef as any).retry`.
+   */
+  retry?: { maxRetries?: number; baseDelayMs?: number; maxDelayMs?: number };
+  /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */
+  tags?: string[];
+  /**
+   * When true, the host must approve this call before execution. Stored only;
+   * enforcement is wired by the host, default open.
+   */
+  needsApproval?: boolean;
+  /**
+   * Optional output schema (Zod or JSON Schema, stored as `unknown` so `zod`
+   * stays optional for type-only consumers).
+   */
+  output?: unknown;
   /** Implementation invoked with validated input and execution metadata. */
   execute: ToolExecuteFn<TInput, TOutput>;
 }
@@ -46,7 +175,7 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
  *   maxTries: 2,
  *   maxConcurrency: 2,
  *   execute: async ({ username }, ctx) => {
- *     return username === "Akshat Dwivedi" ? "Valid" : "Invalid";
+ *     return username === "alice" ? "Valid" : "Invalid";
  *   },
  * });
  * ```
@@ -57,6 +186,10 @@ export interface CreateToolOptions<TInput = any, TOutput = any> {
 export function tool<TInput = any, TOutput = any>(
   options: CreateToolOptions<TInput, TOutput>
 ): ToolDefinition<TInput, TOutput> {
+  // Q-55: names are validated at registration (record-key fallback included).
+  if (options.name !== undefined) assertValidToolName(options.name);
+  // ToolDefinition (src/types/tool.ts) carries the v2 policies as typed
+  // optionals; the executor additionally reads them via `(toolDef as any).*`.
   return {
     name: options.name,
     description: options.description,
@@ -64,10 +197,21 @@ export function tool<TInput = any, TOutput = any>(
     parameters: options.parameters,
     strict: options.strict,
     timeoutMs: options.timeoutMs,
-    maxTries: options.maxTries,
+    maxTries: normalizeMaxAttempts(options),
     maxConcurrency: options.maxConcurrency,
     execute: options.execute,
-  };
+    ...(options.idempotent !== undefined ? { idempotent: options.idempotent } : {}),
+    ...(options.repeatable !== undefined ? { repeatable: options.repeatable } : {}),
+    ...(options.maxResultChars !== undefined ? { maxResultChars: options.maxResultChars } : {}),
+    ...(options.redactError !== undefined ? { redactError: options.redactError } : {}),
+    ...(options.redactError === undefined && options.redact !== undefined ? { redactError: options.redact } : {}),
+    ...(options.redact !== undefined ? { redact: options.redact } : {}),
+    ...(options.retry !== undefined ? { retry: options.retry } : {}),
+    ...(options.tags !== undefined ? { tags: options.tags } : {}),
+    ...(options.needsApproval !== undefined ? { needsApproval: options.needsApproval } : {}),
+    ...(options.output !== undefined ? { output: options.output } : {}),
+    ...(options.maxAttempts !== undefined ? { maxAttempts: options.maxAttempts } : {}),
+  } as ToolDefinition<TInput, TOutput>;
 }
 
 /**

package/src/types/agent.ts

@@ -1,4 +1,4 @@
-import type { ProviderId, ModelSpec } from "./model.ts";
+import type { ModelSpec } from "./model.ts";
 import type { ToolDefinition } from "./tool.ts";
 import type {
   ThinkingLevel,
@@ -7,6 +7,71 @@ import type {
 } from "./core.ts";
 import type { ModelProviderInstance } from "../providers/registry.ts";
 import type { Agent } from "../agent/agent.ts";
+import type { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Q-52/Q-53/Q-54 canonical option types (all additive; nothing renamed).
+//
+// Canonical homes (one place per setting):
+// - Worker model: `dynamicSubagents.model` only. Top-level `subagentModel`
+//   is a deprecated alias (still honored: dynamicSubagents.model ??
+//   subagentModel ?? SUB_AGENT_MODEL ?? parent model).
+// - Session identity: agent-level `sessionId` only (per-run `sessionId`
+//   selects a named session entry; `cache.sessionId` is a deprecated alias).
+// - Model identity: `ModelRef` = string (`provider/model`) | catalog
+//   `ModelSpec` | `ModelProviderInstance` ({ provider, model, apiKey?,
+//   baseUrl? }). Explicit `Agent` config always wins over env; constructing
+//   an `Agent` with an explicit `model` reads no env for routing.
+// ---------------------------------------------------------------------------
+
+/** Canonical model reference: `provider/model` string, catalog spec, or provider helper result. */
+export type ModelRef = string | ModelSpec | ModelProviderInstance;
+
+/** Canonical reasoning option (Q-52): bare level, or level + explicit token budget. */
+export type ThinkingOption = ThinkingLevel | { level?: ThinkingLevel; budgetTokens?: number };
+
+/** Canonical sampling knobs (Q-54). Read by the loop via `(config as any).sampling`. */
+export interface SamplingConfig {
+  temperature?: number;
+  topP?: number;
+}
+
+/** Canonical retry policy (Q-54). Read by the loop via `(config as any).retry`. */
+export interface RetryPolicyConfig {
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  budgetMs?: number;
+}
+
+/** Minimal logger surface for Agent/loop telemetry (Q-54). */
+export interface AgentLogger {
+  debug?: (...args: unknown[]) => void;
+  info?: (...args: unknown[]) => void;
+  warn?: (...args: unknown[]) => void;
+  error?: (...args: unknown[]) => void;
+}
+
+/** Canonical tool-selection control (Q-54). String form is the portable subset. */
+export type ToolChoiceOption =
+  | "auto"
+  | "none"
+  | "required"
+  | { mode?: "auto" | "none" | "required"; tool?: string };
+
+/** Canonical stop control (Q-54): sequence(s) halting generation. */
+export type StopOption = string | string[];
+
+/** Canonical structured-output input (Q-61). Zod, JSON Schema, or explicit form. */
+export type StructuredOutputOption =
+  | z.ZodType
+  | Record<string, unknown>
+  | {
+      name?: string;
+      description?: string;
+      schema: z.ZodType | Record<string, unknown>;
+      strict?: boolean;
+    };
 
 /** Configuration used to construct an {@link Agent}. */
 export interface AgentConfig {
@@ -30,6 +95,13 @@ export interface AgentConfig {
   tools?: Record<string, ToolDefinition> | ToolDefinition[];
   /** Requested reasoning level, validated against the model catalog. */
   thinkingLevel?: ThinkingLevel;
+  /**
+   * Canonical reasoning option (Q-52, preferred over `thinkingLevel`).
+   * Accepts a bare level or `{ level, budgetTokens }`. When both are set,
+   * `thinking` wins; resolution honors `thinking ?? thinkingLevel`.
+   * See `normalizeThinkingV2` (re-exported from the root entry).
+   */
+  thinking?: ThinkingOption;
   /** Prompt-cache retention and session-affinity settings. */
   cache?: CacheConfig;
   /** Provider service tier, when supported. */
@@ -45,12 +117,23 @@ export interface AgentConfig {
   sessionId?: string;
   /** Headers merged into every provider request. */
   headers?: Record<string, string>;
-  /** Maximum model/tool turns per run. `0` or omitted means infinite. */
+  /**
+   * Maximum model/tool turns per run. `0` or omitted means infinite
+   * (legacy `0` alias, normalized to `Infinity`; prefer omitting).
+   */
   maxTurns?: number;
   /** Fixed worker agents exposed as delegation tools. */
   subagents?: (Agent | { name: string; description: string; agent: Agent })[];
   /** Clears conversation state before and after every run. */
   stateless?: boolean;
+  /**
+   * Mid-session queue policy for new queries arriving while a run is active.
+   * - `{ mode: "steer" }`: only steer (inject into current turn) is allowed.
+   * - `{ mode: "queue" }`: only queue (next-turn follow-up) is allowed.
+   * - `{ mode: "auto" }` (default): caller picks per message via `enqueue` or `steer()`/`queue()`.
+   * `interrupt` (cancel stream now) is always available via `interrupt()`/`cancel()`/`AbortSignal`.
+   */
+  midSession?: MidSessionConfig;
   /**
    * Durable session persistence: when set, the session file is rewritten
    * after every step (user turn, assistant turn, tool batch, sub-agent
@@ -59,6 +142,84 @@ export interface AgentConfig {
    * pretty `.session.json` file. Writes are atomic and never fail a turn.
    */
   persist?: { dir?: string; file?: string };
+  // Q-54 missing knobs (all optional, additive; loop reads via `(config as any).*`).
+  /** Canonical tool-selection control (`"auto"` default). */
+  toolChoice?: ToolChoiceOption;
+  /** Maximum output tokens for one model call. */
+  maxOutputTokens?: number;
+  /** Sampling knobs. */
+  sampling?: SamplingConfig;
+  /** Stop sequence(s). */
+  stop?: StopOption;
+  /** Deterministic seed, when the provider supports it. */
+  seed?: number;
+  /**
+   * Optional output schema (Zod, JSON Schema, or `{ name, schema, strict }`,
+   * see `StructuredOutputOption`, stored as `unknown` so `zod`
+   * stays optional for type-only consumers). Agent-level only; per-run
+   * overrides are intentionally unsupported. When set, the model answer is
+   * constrained to the schema on all providers and `AgentResponse.parsed`
+   * carries the validated value.
+   */
+  output?: unknown;
+  /** Retry policy for provider calls. */
+  retry?: RetryPolicyConfig;
+  /** Fetch implementation override (defaults to global `fetch`). */
+  fetch?: typeof fetch;
+  /** Provider/env overrides forwarded to key resolution. */
+  env?: Record<string, string>;
+  /** Structured logger for loop telemetry (defaults to no-op). */
+  logger?: AgentLogger;
+  /** Control hooks (Q-59). All optional, fail-open by default. */
+  hooks?: unknown;
+  /** Threshold compaction policy (Q-60a). Fully configurable/replaceable. */
+  contextManagement?: unknown;
+  /** Telemetry bus (Q-41). Default no-op; pretty logger lives in /cli. */
+  telemetry?: { onEvent?: (e: any) => void } | unknown;
+  /** Local file access roots (Q-08). Default deny; `path` sources must resolve inside roots. */
+  fileAccess?: { roots?: string[] };
+  /** Raw capture policy (Q-11). Default "redacted": no bodies. */
+  captureRaw?: false | "redacted" | true;
+  /** Opt-in run budgets (Q-39). All fields default unlimited. */
+  budget?: Budget;
+  /** Run + network limits (Q-22). Turn/budget caps unlimited by default; network timeouts finite. */
+  limits?: AgentRunLimits;
+}
+
+/** Per-request + run limits (Q-22). */
+export interface AgentRunLimits {
+  maxTurns?: number;
+  deadlineMs?: number;
+  maxTotalTokens?: number;
+  maxToolCallsPerRun?: number;
+  requestTimeoutMs?: number;
+  firstByteTimeoutMs?: number;
+  streamIdleTimeoutMs?: number;
+}
+
+/** Developer policy for mid-session new-query insertion while a run is active. */
+export type MidSessionMode = "steer" | "queue" | "auto";
+
+/** Q-51 canonical busy-policy alias: prefer `whenBusy`, `mode` kept for compat. */
+export type WhenBusyMode = MidSessionMode;
+
+/** Developer-configured policy for LLM-spawned dynamic sub-agents. */
+export interface MidSessionConfig {
+  /**
+   * Which mid-session method is allowed while a run is active:
+   * - `"steer"`: only steer (inject into current turn) is allowed.
+   * - `"queue"`: only queue (next-turn follow-up) is allowed.
+   * - `"auto"` (default): caller/user picks per message via `enqueue` or `steer()`/`queue()`.
+   */
+  mode?: MidSessionMode;
+  /**
+   * Canonical alias for `mode` (Q-51, preferred). When both are set,
+   * `whenBusy` wins. Accepted anywhere `mode` is read; resolution honors
+   * `whenBusy ?? mode ?? "auto"`.
+   */
+  whenBusy?: MidSessionMode;
+  /** Max queued (follow-up) requests buffered while busy. Extra `queue()` calls throw. Defaults to 20. */
+  maxQueued?: number;
 }
 
 /** Developer-configured policy for LLM-spawned dynamic sub-agents. */
@@ -75,12 +236,29 @@ export interface DynamicSubagentsConfig {
   tools?: Record<string, ToolDefinition> | ToolDefinition[];
   /** Per-worker timeout in ms. `0` (default) = no limit. `-1` = the Main Agent sets a per-task `timeoutMs`. `>0` = fixed timeout for every worker. */
   timeout?: number;
+  /**
+   * Canonical per-worker timeout in ms (Q-52, preferred over `timeout`).
+   * Maps to `timeout`: `workerTimeoutMs ?? timeout ?? 0`. See
+   * `normalizeWorkerTimeout` (re-exported from the root entry).
+   */
+  workerTimeoutMs?: number;
+  /**
+   * When true, the Main Agent sets a per-task `timeoutMs` (maps to
+   * `timeout: -1`). When both are set, an explicit `timeout`/`workerTimeoutMs`
+   * wins over `modelMaySetTimeout`.
+   */
+  modelMaySetTimeout?: boolean;
 }
 
 /** Per-run overrides for {@link Agent.run}, {@link Agent.ask}, and {@link Agent.stream}. */
 export interface AgentRunOptions {
   /** Per-run reasoning-level override, validated against the selected model. */
   thinkingLevel?: ThinkingLevel;
+  /**
+   * Canonical per-run reasoning option (Q-52, preferred over `thinkingLevel`).
+   * Resolution honors `thinking ?? thinkingLevel`.
+   */
+  thinking?: ThinkingOption;
   /** Return a streaming object instead of waiting for a final response. */
   stream?: boolean;
   /** Cancels provider, tool, and sub-agent work. */
@@ -89,6 +267,14 @@ export interface AgentRunOptions {
   sessionId?: string;
   /** Context added only to this user turn, preserving the stable system prompt. */
   additionalContext?: string;
+  /**
+   * Mid-session method to use when this call arrives while another run is active.
+   * Only honored when `midSession.mode` is `"auto"` (default). When the developer
+   * enforces `"steer"` or `"queue"`, that policy wins and this field is ignored.
+   * When idle, this field is ignored and the call runs immediately.
+   * Defaults to `"queue"` (finish current turn, run as next turn).
+   */
+  enqueue?: "steer" | "queue";
   /** Headers merged for this run only. */
   headers?: Record<string, string>;
   /** Called for each text delta as it streams (only when stream:true). */
@@ -101,6 +287,26 @@ export interface AgentRunOptions {
   wrapThinking?: boolean;
   /** Called after every model/tool turn with a turn summary (also drives sub-agent step logs + durable persistence). */
   onTurn?: (turn: AgentTurnEvent) => void;
+  // Q-54 per-run knobs (all optional, additive; `output` intentionally
+  // omitted here — it is agent-level only, see AgentConfig.output).
+  /** Per-run tool-selection override. */
+  toolChoice?: ToolChoiceOption;
+  /** Per-run output-token cap. */
+  maxOutputTokens?: number;
+  /** Per-run sampling override. */
+  sampling?: SamplingConfig;
+  /** Per-run stop sequence(s). */
+  stop?: StopOption;
+  /** Per-run seed. */
+  seed?: number;
+  /** Per-run retry override. */
+  retry?: RetryPolicyConfig;
+  /** Per-run fetch override. */
+  fetch?: typeof fetch;
+  /** Per-run env overrides. */
+  env?: Record<string, string>;
+  /** Per-run logger. */
+  logger?: AgentLogger;
 }
 
 /** Turn summary emitted to `AgentRunOptions.onTurn` after each loop turn. */
@@ -116,3 +322,39 @@ export interface AgentTurnEvent {
   /** Tool results executed this turn, if any. */
   toolResults?: Array<{ id: string; name: string; isError?: boolean }>;
 }
+
+/** Optional run budgets enforced by delegation helpers (Q-39). All fields default to unlimited. */
+export interface Budget {
+  /** Maximum total cost in USD across this agent + spawned workers. */
+  maxCostUsd?: number;
+  /** Maximum total tokens across this agent + spawned workers. */
+  maxTotalTokens?: number;
+  /** Maximum wall/monotonic duration in ms since budget tracking started. */
+  maxDurationMs?: number;
+  /** Maximum total dynamic sub-agents spawned via `spawn_subagents`. */
+  maxTotalSubagents?: number;
+}
+
+/** Mutable counters backing a {@link Budget}. Stored on the agent instance (untyped `budgetState`). */
+export interface BudgetState {
+  /** Workers spawned so far (incremented by `reserveSpawn`). */
+  spawned: number;
+  /** Accumulated total tokens charged via `chargeBudgetUsage`. */
+  totalTokens: number;
+  /** Accumulated total cost in USD charged via `chargeBudgetUsage`. */
+  totalCostUsd: number;
+  /** Monotonic start time (`nowMs()` clock) for `maxDurationMs` checks. */
+  startedAtMs: number;
+}
+
+/** Run/turn lineage attached to sub-agent metadata via `(metadata as any)` (Q-42). */
+export interface SubAgentRunIds {
+  /** Stable id for this worker batch/run (`newRunId`). */
+  runId?: string;
+  /** Stable id for this worker turn (`newTurnId`). */
+  turnId?: string;
+  /** Parent run id when known (opaque, forwarded when the host exposes one). */
+  parentRunId?: string;
+  /** Root run id when known (opaque, forwarded when the host exposes one). */
+  rootRunId?: string;
+}

package/src/types/errors.ts

@@ -0,0 +1,133 @@
+import type { TokenUsage } from "./core.ts";
+import type { ToolCallRecord, ToolResultRecord } from "./tool.ts";
+
+/** Machine-readable error codes. No ANSI in messages. */
+export type AgentAccelErrorCode =
+  | "config"
+  | "provider"
+  | "timeout"
+  | "budget_exceeded"
+  | "tool"
+  | "validation"
+  | "session_load"
+  | "security_policy"
+  | "abort"
+  | "incomplete_stream"
+  | "context_overflow";
+
+export interface AgentAccelErrorContext {
+  provider?: string;
+  model?: string;
+  status?: number;
+  requestId?: string;
+  retryable?: boolean;
+  runId?: string;
+  turnId?: string;
+  docs?: string;
+  fixes?: string[];
+  partial?: {
+    usage?: TokenUsage;
+    turns?: number;
+    text?: string;
+    toolCalls?: ToolCallRecord[];
+    toolResults?: ToolResultRecord[];
+  };
+  [k: string]: unknown;
+}
+
+/** Base for all SDK errors. Message is one line, no ANSI. */
+export class AgentAccelError extends Error {
+  readonly code: AgentAccelErrorCode;
+  readonly retryable: boolean;
+  readonly context: AgentAccelErrorContext;
+  constructor(code: AgentAccelErrorCode, message: string, opts?: { retryable?: boolean; context?: AgentAccelErrorContext; cause?: unknown }) {
+    super(message);
+    this.name = "AgentAccelError";
+    this.code = code;
+    this.retryable = opts?.retryable ?? false;
+    this.context = opts?.context ?? {};
+    if (opts?.cause !== undefined) (this as { cause?: unknown }).cause = opts.cause;
+  }
+}
+
+export class ConfigError extends AgentAccelError {
+  constructor(message: string, context?: AgentAccelErrorContext) {
+    super("config", message, { retryable: false, context });
+    this.name = "ConfigError";
+  }
+}
+
+export class ProviderError extends AgentAccelError {
+  readonly status?: number;
+  constructor(message: string, opts?: { status?: number; provider?: string; model?: string; requestId?: string; retryable?: boolean; context?: AgentAccelErrorContext }) {
+    super("provider", message, {
+      retryable: opts?.retryable ?? false,
+      context: { ...opts?.context, provider: opts?.provider, model: opts?.model, status: opts?.status, requestId: opts?.requestId },
+    });
+    this.name = "ProviderError";
+    this.status = opts?.status;
+  }
+}
+
+export class TimeoutError extends AgentAccelError {
+  constructor(message: string, context?: AgentAccelErrorContext) {
+    super("timeout", message, { retryable: true, context });
+    this.name = "TimeoutError";
+  }
+}
+
+export class BudgetExceededError extends AgentAccelError {
+  constructor(message: string, context?: AgentAccelErrorContext) {
+    super("budget_exceeded", message, { retryable: false, context });
+    this.name = "BudgetExceededError";
+  }
+}
+
+export class ToolError extends AgentAccelError {
+  readonly expose: boolean;
+  constructor(message: string, opts?: { retryable?: boolean; expose?: boolean; context?: AgentAccelErrorContext }) {
+    super("tool", message, { retryable: opts?.retryable ?? false, context: opts?.context });
+    this.name = "ToolError";
+    this.expose = opts?.expose ?? true;
+  }
+}
+
+export class ValidationError extends AgentAccelError {
+  constructor(message: string, context?: AgentAccelErrorContext) {
+    super("validation", message, { retryable: false, context });
+    this.name = "ValidationError";
+  }
+}
+
+export class SessionLoadError extends AgentAccelError {
+  constructor(message: string, context?: AgentAccelErrorContext) {
+    super("session_load", message, { retryable: false, context });
+    this.name = "SessionLoadError";
+  }
+}
+
+export class SecurityPolicyError extends AgentAccelError {
+  constructor(message: string, context?: AgentAccelErrorContext) {
+    super("security_policy", message, { retryable: false, context });
+    this.name = "SecurityPolicyError";
+  }
+}
+
+/** Abort is signal.aborted or name === AbortError only. Never message regex. */
+export function isAbortError(error: unknown): boolean {
+  const err = error as { name?: unknown } | null;
+  if (!err || typeof err !== "object") return false;
+  if ((err as { name?: unknown }).name === "AbortError") return true;
+  return false;
+}
+
+/** Format without ANSI for CLI pretty-printing. */
+export function formatErrorPlain(err: unknown): string {
+  if (err instanceof AgentAccelError) {
+    const ctx = err.context?.provider ? ` [${err.context.provider}${err.context.model ? `/${err.context.model}` : ""}]` : "";
+    const status = err.context?.status ? ` (${err.context.status})` : "";
+    return `[${err.code}]${ctx}${status}: ${err.message}`;
+  }
+  if (err instanceof Error) return `${err.name}: ${err.message}`;
+  return String(err);
+}

package/src/types/model.ts

@@ -1,5 +1,5 @@
 import type { ThinkingConfig, CacheConfig, ServiceTier, TokenUsage } from "./core.ts";
-import type { ProviderContext, Message, ContentPart } from "./message.ts";
+import type { ProviderContext } from "./message.ts";
 import type { StandardToolDeclaration, ToolCallRecord } from "./tool.ts";
 import type { AssistantMessageEventStream } from "../streaming/event-stream.ts";
 
@@ -87,6 +87,7 @@ export interface ModelCapabilities {
   supportsLongCacheRetention?: boolean;
   supportsParallelToolCalls?: boolean;
   supportsStreaming?: boolean;
+  supportsStructuredOutput?: boolean;
   modalities?: ("text" | "image" | "audio" | "video" | "pdf")[];
   // derived
   supportsReasoningToggle?: boolean;
@@ -138,6 +139,24 @@ export interface ModelSpec {
   raw?: RawModelData;
 }
 
+// ---------------------------------------------------------------------------
+// Structured outputs — normalized, provider-agnostic spec.
+// Canonical input is `AgentConfig.output` (Zod, JSON Schema, or explicit
+// `{ name, schema, strict }`); `normalizeStructuredOutput` in
+// `src/providers.ts` produces this shape for adapters.
+// ---------------------------------------------------------------------------
+/** Normalized structured-output request passed from Agent to providers. */
+export interface StructuredOutputSpec {
+  /** Format name (1-64 chars, `[a-zA-Z0-9_-]`). Defaults to `structured_output`. */
+  name: string;
+  /** JSON Schema for the final answer (already converted from Zod when needed). */
+  schema: Record<string, unknown>;
+  /** Strict schema adherence (OpenAI/OpenRouter only; ignored by Google). Defaults to true. */
+  strict?: boolean;
+  /** Optional description of what the format is for. */
+  description?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Provider plumbing — unchanged API
 // ---------------------------------------------------------------------------
@@ -156,6 +175,8 @@ export interface ProviderRequestOptions {
   env?: Record<string, string>;
   maxRetries?: number;
   maxRetryDelayMs?: number;
+  /** Normalized structured-output spec (see `normalizeStructuredOutput`). */
+  output?: StructuredOutputSpec;
 }
 
 /** Auditable request/response wire payload captured in AgentResponse. */