@ggui-ai/ui-gen 0.8.0 → 0.10.0

package/dist/harness/index.d.ts

@@ -1,138 +1,17 @@
 import { Harness } from './types-public.js';
 export { CheckLeg, CheckResult, CreateHarnessInput, DefaultTaskRunner, HarnessConstructionContext, HarnessId, HarnessMeta, HarnessName, HarnessOverrides, HarnessRevision, HowLeg, IterationRecord, LLMEvaluator, PatchFn, Phase, PhaseRunResult, PlannerDecision, PlannerFn, ProcessLeg, PromptBuilder, RetryPolicy, RunCheckInput, RunHarnessInput, RunHarnessReason, RunHarnessResult, RunWorkflowInput, Task, TaskContext, TaskRunner, TierCheck, WhatLeg, Workflow, WorkflowRunResult, createHarness, runCheck, runHarness, runWorkflow } from './types-public.js';
 export { applyLineRanges, defaultApplyPatch } from '../patch.js';
-import { JsonObject } from '@ggui-ai/protocol';
-import { LLMToolDef } from '../llm.js';
+export { A as AgentConfig, L as LLMResponse, P as ProviderRetryInfo, c as callLLM, a as createAgent } from '../llm-router-BEVtbAb9.js';
 export { WORKFLOWS, WorkflowId, pickWorkflow } from '../workflows.js';
 export { LlmTraceEvent, LlmTraceKind, LlmTraceProvider, LlmTraceSink, getLlmTraceSink, setLlmTraceSink } from './llm-trace-sink.js';
 export { ValidatorTraceEvent, ValidatorTraceSink, getValidatorTraceSink, setValidatorTraceSink } from './validator-trace-sink.js';
 export { ProcessMode } from '../policy.js';
 export { computeHarnessId, computeHarnessName, hashClassification } from '../hash.js';
+import '@ggui-ai/protocol';
 import '../axes-CzLEMDeB.js';
-import '../types-public-C36k1q6s.js';
+import '../types-public-DIpjC-OA.js';
 import '../types-BOvHNG7K.js';
-
-interface AgentConfig {
-    provider: 'anthropic' | 'openai' | 'google' | 'openrouter';
-    model: string;
-    /**
-     * Sampling temperature. When defined it is threaded into the provider
-     * request; when undefined the provider default is used (unchanged
-     * behavior for all existing callers).
-     */
-    temperature?: number;
-}
-interface LLMResponse {
-    text: string;
-    inputTokens: number;
-    outputTokens: number;
-}
-interface LLMTool {
-    name: string;
-    description: string;
-    parameters: JsonObject;
-    handler: (args: JsonObject) => Promise<{
-        content: Array<{
-            text: string;
-        }>;
-        isError?: boolean;
-    }>;
-}
-interface LLMWithToolsResponse {
-    text: string;
-    inputTokens: number;
-    outputTokens: number;
-    turnsUsed: number;
-}
-interface LLMToolCall {
-    /** Provider-specific call ID (for sendToolResult) */
-    id?: string;
-    name: string;
-    input: JsonObject;
-}
-interface LLMToolCallResponse {
-    toolCalls: LLMToolCall[];
-    inputTokens: number;
-    outputTokens: number;
-    /**
-     * Tokens read from / written to the prompt cache, when the provider
-     * reports them. Optional because not every provider exposes
-     * prompt-cache accounting — absent means "unreported", never zero.
-     */
-    cacheReadTokens?: number;
-    cacheCreationTokens?: number;
-}
-/** Result of executing a tool — passed to sendToolResult to close the API contract. */
-interface LLMToolResult {
-    /** Tool call ID from the response (for providers that need it) */
-    callId?: string;
-    /** Tool name */
-    name: string;
-    /** Text result of executing the tool */
-    result: string;
-    /** Whether the tool execution failed */
-    isError?: boolean;
-}
-declare abstract class LLMAgent {
-    abstract readonly provider: AgentConfig['provider'];
-    private client;
-    protected lastSessionId: string | undefined;
-    protected abstract resolveModel(model: string): string;
-    protected abstract createClient(): Promise<unknown>;
-    protected getClient<T>(): Promise<T>;
-    /** Text-only call — no tools */
-    abstract callText(model: string, systemPrompt: string, userPrompt: string, maxTokens?: number, temperature?: number): Promise<LLMResponse>;
-    /**
-     * Single-turn function calling — returns tool calls without executing them.
-     * Each provider uses its native function/tool calling:
-     *   - Anthropic: tool_use blocks
-     *   - OpenAI: function_call output items
-     *   - Google: functionCall parts
-     * SDK handles JSON escaping — safe for code, diffs, and other content.
-     */
-    abstract callTools(model: string, systemPrompt: string, userPrompt: string, tools: LLMToolDef[], toolChoice?: 'required' | 'auto', 
-    /**
-     * Optional scoped fallback tools. If the primary tools fail with a
-     * transport-class error (e.g. `malformed_tool_call` on Gemini after
-     * retry exhaustion), the provider may retry once with these narrower
-     * tools before throwing. Universal signal — not provider-gated.
-     */
-    scopedTools?: LLMToolDef[]): Promise<LLMToolCallResponse>;
-    /** Multi-turn agentic loop — executes tools internally */
-    abstract callWithTools(model: string, systemPrompt: string, userPrompt: string, tools: LLMTool[], maxTurns: number): Promise<LLMWithToolsResponse>;
-    /**
-     * Pre-warm cache for repeated callTools() calls with the same system prompt + tools.
-     * Override in providers that support server-side context caching (e.g., Google).
-     * No-op by default (Anthropic/OpenAI handle caching automatically per-request).
-     */
-    warmCache(_model: string, _systemPrompt: string, _tools: LLMToolDef[], _toolChoice?: 'required' | 'auto'): Promise<void>;
-    /** Cleanup any cached resources. Call after generation completes. No-op by default. */
-    cleanup(): Promise<void>;
-    /** Reset session state between independent generation runs. */
-    resetSession(): void;
-    /**
-     * Send tool execution results back to the provider to close the API contract.
-     * Call this after executing tools from callTools() and before the next callTools().
-     *
-     * For providers with server-side state (Google, OpenAI), this sends the
-     * function results so the next callTools() can chain properly.
-     * For stateless providers (Anthropic), this is a no-op.
-     *
-     * Override in providers that need it.
-     */
-    sendToolResult(_results: LLMToolResult[]): Promise<void>;
-    /**
-     * Execute an API call. No retry — if it fails, it fails.
-     * Logs the error with provider context and re-throws.
-     */
-    protected apiCall<T>(fn: () => Promise<T>): Promise<T>;
-}
-/**
- * Create a fresh agent instance for the given provider.
- * Each call returns a new instance — no shared state between callers.
- */
-declare function createAgent(provider: AgentConfig['provider']): LLMAgent;
-declare function callLLM(config: AgentConfig, systemPrompt: string, userPrompt: string, maxTokens?: number): Promise<LLMResponse>;
+import '../llm.js';
 
 /**
  * Fingerprint a materialized Harness. `h.id` is already a deterministic
@@ -142,4 +21,4 @@ declare function callLLM(config: AgentConfig, systemPrompt: string, userPrompt:
  */
 declare function hashHarness(h: Harness): string;
 
-export { type AgentConfig, Harness, type LLMResponse, callLLM, createAgent, hashHarness };
+export { Harness, hashHarness };

package/dist/harness/index.js

@@ -27,14 +27,16 @@ var OpenRouterError;
 var init_types = __esm({
   "src/adapters/openrouter/types.ts"() {
     OpenRouterError = class extends Error {
-      constructor(message, status, code) {
+      constructor(message, status, code, headers) {
         super(message);
         this.status = status;
         this.code = code;
+        this.headers = headers;
         this.name = "OpenRouterError";
       }
       status;
       code;
+      headers;
       get isTransient() {
         return this.status === 408 || this.status === 429 || this.status === 502 || this.status === 503;
       }
@@ -79,7 +81,7 @@ var init_client = __esm({
         if (!response.ok) {
           const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
           const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status);
+          throw new OpenRouterError(message, response.status, void 0, response.headers);
         }
         return response.json();
       }
@@ -97,7 +99,7 @@ var init_client = __esm({
         if (!response.ok) {
           const errorBody = await response.json().catch(() => ({ error: { message: response.statusText } }));
           const message = errorBody.error?.message ?? response.statusText;
-          throw new OpenRouterError(message, response.status);
+          throw new OpenRouterError(message, response.status, void 0, response.headers);
         }
         if (!response.body) {
           throw new OpenRouterError("No response body for streaming request", 500);
@@ -517,11 +519,11 @@ var stateFragments = {
     axis: "state",
     value: "merge",
     cacheTier: "axisDelta",
-    promptText: "## State: merge (live entity reconciliation)\n1. Seed `const [items, setItems] = useState(props.items ?? [])`.\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` \u2014 merge by id, do NOT append.\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\n4. Per-item actions pass `{ id, ... }` in the payload.\n5. Never push the stream payload into an append-only list unless realtime=append.",
+    promptText: "## State: merge (live entity reconciliation)\n1. Seed `const [items, setItems] = useState(props.items ?? [])` AND re-seed on prop change: `useEffect(() => setItems(props.items ?? []), [props.items])` \u2014 a `ggui_amend` repaint must move the list.\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` \u2014 merge by id, do NOT append.\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\n4. Per-item actions pass `{ id, ... }` in the payload.\n5. Never push the stream payload into an append-only list unless realtime=append.",
     boilerplateMarker: [
       "",
       "  // \u2500\u2500 Live entity state (merge-by-id) \u2500\u2500",
-      "  // useState(props.items ?? []); merge stream events by item.id; never append.",
+      "  // useState(props.items ?? []); re-seed via useEffect on [props.items]; merge stream events by item.id; never append.",
       ""
     ].join("\n")
   },
@@ -639,13 +641,13 @@ var realtimeFragments = {
     axis: "realtime",
     value: "merge",
     cacheTier: "axisDelta",
-    promptText: "## Realtime: merge\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough \u2014 the local list must update on each event for the DOM to re-render.\n\n```tsx\nconst stream = useStream<UpdateT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\n}, [stream.latest]);\n// Render `items.map(...)` \u2014 NOT props.items, NOT stream.all.\n```\n\nNever append \u2014 stream=merge means the entity already exists locally."
+    promptText: "## Realtime: merge\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough \u2014 the local list must update on each event for the DOM to re-render.\n\n```tsx\nconst stream = useStream<UpdateT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint \u2014 props stay the source of truth\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\n}, [stream.latest]);\n// Render `items.map(...)` \u2014 NOT props.items, NOT stream.all.\n```\n\nNever append \u2014 stream=merge means the entity already exists locally."
   },
   append: {
     axis: "realtime",
     value: "append",
     cacheTier: "axisDelta",
-    promptText: "## Realtime: append\nStream events are new entities; APPEND to local state. Subscribing alone is not enough \u2014 the local list must update for the DOM to re-render.\n\n```tsx\nconst stream = useStream<EventT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => [...prev, stream.latest!]);\n}, [stream.latest]);\n// Render `items.map(...)` \u2014 NOT props.items, NOT stream.all (which accumulates only post-mount).\n```\n\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once."
+    promptText: "## Realtime: append\nStream events are new entities; APPEND to local state. Subscribing alone is not enough \u2014 the local list must update for the DOM to re-render.\n\n```tsx\nconst stream = useStream<EventT>('streamName');\nconst [items, setItems] = useState(props.items);\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint \u2014 props stay the source of truth\nuseEffect(() => {\n  if (!stream.latest) return;\n  setItems((prev) => [...prev, stream.latest!]);\n}, [stream.latest]);\n// Render `items.map(...)` \u2014 NOT props.items, NOT stream.all (which accumulates only post-mount).\n```\n\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once."
   },
   status: {
     axis: "realtime",
@@ -663,7 +665,7 @@ var realtimeFragments = {
     axis: "realtime",
     value: "mixed",
     cacheTier: "axisDelta",
-    promptText: "## Realtime: mixed\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL \u2014 subscribing alone never re-renders the DOM.\n\nExample (chat-interface \u2014 message=append, typing=presence):\n\n```tsx\nconst messages = useStream<MessageT>('message');\nconst typing = useStream<TypingT>('typing');\nconst [messageList, setMessageList] = useState(props.messages);\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\n\nuseEffect(() => {\n  if (!messages.latest) return;\n  setMessageList((prev) => [...prev, messages.latest!]);\n}, [messages.latest]);\n\nuseEffect(() => {\n  if (!typing.latest) return;\n  setTypingUsers((prev) => {\n    const next = new Set(prev);\n    if (typing.latest!.active) next.add(typing.latest!.sender);\n    else next.delete(typing.latest!.sender);\n    return next;\n  });\n}, [typing.latest]);\n```\n\nDo NOT treat all events the same. Do NOT skip the local-state sync \u2014 `useStream` alone won't trigger DOM updates of your derived view.",
+    promptText: "## Realtime: mixed\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL \u2014 subscribing alone never re-renders the DOM.\n\nExample (chat-interface \u2014 message=append, typing=presence):\n\n```tsx\nconst messages = useStream<MessageT>('message');\nconst typing = useStream<TypingT>('typing');\nconst [messageList, setMessageList] = useState(props.messages);\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\n\nuseEffect(() => setMessageList(props.messages), [props.messages]); // re-seed on ggui_amend repaint\n\nuseEffect(() => {\n  if (!messages.latest) return;\n  setMessageList((prev) => [...prev, messages.latest!]);\n}, [messages.latest]);\n\nuseEffect(() => {\n  if (!typing.latest) return;\n  setTypingUsers((prev) => {\n    const next = new Set(prev);\n    if (typing.latest!.active) next.add(typing.latest!.sender);\n    else next.delete(typing.latest!.sender);\n    return next;\n  });\n}, [typing.latest]);\n```\n\nDo NOT treat all events the same. Do NOT skip the local-state sync \u2014 `useStream` alone won't trigger DOM updates of your derived view.",
     boilerplateMarker: [
       "",
       "  // \u2500\u2500 Mixed stream handlers \u2500\u2500",
@@ -883,6 +885,15 @@ function jsonSchemaTypeToTs(schema) {
   if (schema.enum?.length) {
     return schema.enum.map((v) => typeof v === "string" ? `'${v}'` : String(v)).join(" | ");
   }
+  if (Array.isArray(schema.type)) {
+    const { nullable: _nullable, ...rest } = schema;
+    const members = [...new Set(schema.type)].map(
+      (member) => jsonSchemaTypeToTs({ ...rest, type: member })
+    );
+    const unique = [...new Set(members)];
+    if (schema.nullable && !unique.includes("null")) unique.push("null");
+    return unique.join(" | ");
+  }
   let result;
   switch (schema.type) {
     case "string":
@@ -900,7 +911,8 @@ function jsonSchemaTypeToTs(schema) {
     case "array": {
       if (schema.items) {
         const itemType = jsonSchemaTypeToTs(schema.items);
-        result = schema.items.type === "object" && schema.items.properties ? `Array<${itemType}>` : itemType.includes("|") ? `(${itemType})[]` : `${itemType}[]`;
+        const itemsDeclareObject = Array.isArray(schema.items.type) ? schema.items.type.includes("object") : schema.items.type === "object";
+        result = itemsDeclareObject && schema.items.properties ? `Array<${itemType}>` : itemType.includes("|") ? `(${itemType})[]` : `${itemType}[]`;
       } else {
         result = "unknown[]";
       }
@@ -1033,13 +1045,14 @@ function generateBoilerplate(_userPrompt, contract, shellType, screen, composedS
   const propsFields = [];
   const propsProperties = contract?.propsSpec?.properties ?? {};
   for (const [key, entry] of Object.entries(propsProperties)) {
-    const required = entry.required !== false;
+    const required = entry.required === true;
     const nullable = entry.schema.nullable === true;
     const tsType = jsonSchemaTypeToTs(entry.schema);
     const fullType = nullable ? `${tsType} | null` : tsType;
     const parts = [];
     if (entry.description) parts.push(entry.description);
     if (entry.default !== void 0) parts.push(`(default: ${JSON.stringify(entry.default)})`);
+    if (!required) parts.push("(optional \u2014 the agent may omit it; guard or fall back)");
     const desc = parts.length > 0 ? ` // ${parts.join(" ")}` : "";
     propsFields.push(`  ${key}${required ? "" : "?"}: ${fullType};${desc}`);
   }
@@ -1785,13 +1798,15 @@ A \`DataContract\` declares everything a GguiSession exchanges with the outside
 
 ## Defensive coding for absent / late-arriving data
 
-Props arrive via \`ggui_update\` and may be partial on first render. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
+Props arrive at mount and may be partial on first render; later prop changes reach the SAME mounted component via \`ggui_amend\` (in-place repaint) on the live channel. Stream channels start empty and fill over time. Context slots start at their declared default (often \`null\`). **Never assume a field exists before you read it.**
 
+- **Optional contract props**: a \`Props\` field marked \`?\` in the boilerplate may be omitted by the agent ENTIRELY \u2014 the wire gate only enforces \`required: true\` entries, and the harness verifies your component with those props stripped. Guard them (\`?? default\`, \`?.\`, or an empty-state branch) from the FIRST render.
 - **Array iteration**: always default to \`[]\` before \`.map\`/\`.filter\`/\`.length\`. Use \`(props.items ?? []).map(...)\` not \`props.items.map(...)\`. Same for stream.all, stream.latest, etc.
 - **Object access**: optional-chain through nested fields. \`props.user?.name ?? 'Anonymous'\` not \`props.user.name\`.
 - **Number ops**: default before arithmetic. \`(props.count ?? 0) + 1\` not \`props.count + 1\`.
 - **Stream latest**: \`useStream\` returns \`{latest: T | null, all: T[], isComplete: boolean}\`. The default \`all\` is \`[]\` so it's safe to map; \`latest\` is null until the first frame arrives \u2014 guard before reading \`.foo\`.
 - **Stream reconciliation**: when a stream event carries an \`action\` discriminant (e.g. \`create | move | edit | delete\`), the channel is a CRUD feed \u2014 your handler MUST branch on EVERY value: append on \`create\`, drop on \`delete\`, replace-by-id on \`move\` / \`edit\`. Merging only the "edit" case silently loses created and deleted items. Reconcile into the SAME state that seeds from \`props\` (e.g. \`useState(() => props.tasks ?? [])\`) so the seed data and the live feed render as one list \u2014 and handle an event whose id is not yet present (a \`create\` for an unknown item) by inserting it, not ignoring it.
+- **Props re-sync on repaint**: props the agent owns are the source of truth for display \u2014 prefer rendering DIRECTLY from \`props\` (controlled, no local copy). When local optimistic state genuinely needs a prop seed (a click bumps a count before the agent confirms), it MUST re-sync on prop change \u2014 \`useEffect(() => setCount(props.count ?? 0), [props.count])\` \u2014 or a \`ggui_amend\` repaint applies the new props while the display keeps the stale local value. BAD: \`const [count, setCount] = useState(props.count ?? 0)\` alone. GOOD: the same seed + the one-line re-sync effect.
 - **Loading state**: while data is still absent, render \`<Skeleton>\` placeholders \u2014 never a blank screen. \`<Skeleton variant="text" />\` for a text line, \`variant="circle"\` for an avatar slot, default \`rect\` for a block.
 - **Empty state**: when a list or results array is empty, render \`<EmptyState title="\u2026" description="\u2026" />\` \u2014 a region that renders nothing when empty looks broken to the user.
 
@@ -1919,7 +1934,7 @@ Every value change is mirrored to the host LLM's context automatically (debounce
 
 **When NOT to use it.** Local UI state the contract did NOT declare \u2014 \`isDropdownOpen\`, hover flags, animation phase, ephemeral toggles. For those, use a plain \`useState\` directly. The runtime ignores undeclared state.
 
-**\`contextSpec\` direction is one-way: client \u2192 agent.** The agent uses \`propsSpec\` (via \`ggui_update\`) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` \u2014 there is no return path.
+**\`contextSpec\` direction is one-way: client \u2192 agent.** The agent uses \`propsSpec\` (via \`ggui_amend\` for in-place repaints of this mount, or \`ggui_update\` when it mints a new history card) and \`streamSpec\` (via the live channel) to push state TO the client. Don't try to write to the agent via \`contextSpec\` \u2014 there is no return path.
 
 **Schema mismatches drop silently.** If you set a value that doesn't match the slot's schema (e.g. a string into a \`{type: 'number'}\` slot), the runtime logs a dev \`console.warn\` and skips the post. Make sure your setter calls produce values that match the declared shape.
 
@@ -2815,6 +2830,34 @@ function errorSummary(e) {
   }
   return `${e.constructor.name}${status}${code}: ${e.message.slice(0, 120)}${body}`;
 }
+function isRateLimited(e) {
+  if (!(e instanceof Error) || !("status" in e)) return false;
+  return e.status === 429;
+}
+function extractStatus(e) {
+  if (!(e instanceof Error) || !("status" in e)) return void 0;
+  const status = e.status;
+  return typeof status === "number" ? status : void 0;
+}
+function extractRetryAfterSec(e) {
+  if (!(e instanceof Error) || !("headers" in e)) return void 0;
+  const headers = e.headers;
+  if (headers === null || typeof headers !== "object" || !("get" in headers) || typeof headers.get !== "function") {
+    return void 0;
+  }
+  const raw = headers.get("retry-after");
+  if (raw === null) return void 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+var MAX_RETRY_ATTEMPTS = 2;
+var RETRY_AFTER_CAP_SEC = 15;
+var DEFAULT_BACKOFF_BASE_MS = 1e3;
+var DEFAULT_BACKOFF_MAX_MS = 8e3;
+var MAX_TOTAL_RETRY_DELAY_MS = 2e4;
 var LLMAgent = class {
   client = null;
   // ── Session state for server-side chaining ──────────────
@@ -2822,6 +2865,19 @@ var LLMAgent = class {
   // Enables turn 2+ to skip re-sending system prompt + history.
   // Call resetSession() between independent generation runs.
   lastSessionId;
+  /**
+   * Explicit per-call routing override — see `AgentConfig.routeOverride`.
+   * Absent when constructed via the bare `new XAgent()` form (every
+   * existing call site), so `createClient()`/`resolveModel()` fall
+   * back to `process.env` exactly as before.
+   */
+  routeOverride;
+  /** See `AgentConfig.onRetry` (#489). Absent is a no-op. */
+  onRetry;
+  constructor(routeOverride, onRetry) {
+    this.routeOverride = routeOverride;
+    this.onRetry = onRetry;
+  }
   async getClient() {
     if (!this.client) {
       this.client = await this.createClient();
@@ -2855,36 +2911,104 @@ var LLMAgent = class {
   async sendToolResult(_results) {
   }
   /**
-   * Execute an API call. No retry — if it fails, it fails.
-   * Logs the error with provider context and re-throws.
+   * Execute an API call, retrying once or twice on HTTP 429
+   * (rate-limited) before giving up (#489).
+   *
+   * Policy: on a 429, honor the provider's `Retry-After` header when
+   * present (capped at `RETRY_AFTER_CAP_SEC` — a provider asking for a
+   * longer wait is treated as "don't retry", not "wait longer": making
+   * the caller sit through 15+ more seconds on a single failed call is
+   * a bad experience regardless of what's driving the request);
+   * otherwise fall back to exponential backoff with jitter, capped at
+   * `DEFAULT_BACKOFF_MAX_MS` per attempt. Stops after
+   * `MAX_RETRY_ATTEMPTS` retries OR once the cumulative delay would
+   * exceed `MAX_TOTAL_RETRY_DELAY_MS`, whichever comes first. Any
+   * non-429 error, or a 429 with no attempts left, is logged and
+   * re-thrown immediately — unchanged from the pre-#489 behavior.
+   *
+   * **Budget scope (final-review correction):** `MAX_TOTAL_RETRY_DELAY_MS`
+   * bounds a single `apiCall()` invocation, not a whole generation. A
+   * generation issues many sequential `apiCall()` calls (coding turns,
+   * tool-result round-trips, eval rounds); under sustained throttling
+   * each one can independently add up to `MAX_TOTAL_RETRY_DELAY_MS`, so
+   * a generation with k rate-limited calls can add up to roughly `k *
+   * MAX_TOTAL_RETRY_DELAY_MS` to how long it holds its caller's
+   * resources (e.g. the caller's concurrency slot) — not a flat 20s
+   * ceiling. No shared per-generation budget is threaded here by
+   * design (accepted ruling, not an oversight): the caller's own
+   * queue/admission backstop is what bounds how long other
+   * queued work waits, independent of any one generation's retry
+   * total.
    */
   async apiCall(fn) {
     const start = Date.now();
-    try {
-      return await fn();
-    } catch (e) {
-      const ms = Date.now() - start;
-      console.error(`[${this.provider}] API error after ${ms}ms: ${errorSummary(e)}`);
-      throw e;
+    let totalDelayMs = 0;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await fn();
+      } catch (e) {
+        const ms = Date.now() - start;
+        if (attempt >= MAX_RETRY_ATTEMPTS || !isRateLimited(e)) {
+          console.error(`[${this.provider}] API error after ${ms}ms: ${errorSummary(e)}`);
+          throw e;
+        }
+        const retryAfterSec = extractRetryAfterSec(e);
+        if (retryAfterSec !== void 0 && retryAfterSec > RETRY_AFTER_CAP_SEC) {
+          console.error(
+            `[${this.provider}] API error after ${ms}ms (retry-after ${retryAfterSec}s exceeds ${RETRY_AFTER_CAP_SEC}s cap, not retrying): ${errorSummary(e)}`
+          );
+          throw e;
+        }
+        const delayMs = retryAfterSec !== void 0 ? retryAfterSec * 1e3 : Math.min(DEFAULT_BACKOFF_BASE_MS * 2 ** attempt, DEFAULT_BACKOFF_MAX_MS) + Math.floor(Math.random() * 250);
+        if (totalDelayMs + delayMs > MAX_TOTAL_RETRY_DELAY_MS) {
+          console.error(
+            `[${this.provider}] API error after ${ms}ms (retry budget exhausted, not retrying): ${errorSummary(e)}`
+          );
+          throw e;
+        }
+        totalDelayMs += delayMs;
+        const info = {
+          provider: this.provider,
+          attempt: attempt + 1,
+          maxAttempts: MAX_RETRY_ATTEMPTS,
+          status: extractStatus(e),
+          retryAfterSec,
+          delayMs,
+          message: errorSummary(e)
+        };
+        console.warn(
+          `[${this.provider}] rate-limited (attempt ${info.attempt}/${info.maxAttempts}), retrying in ${delayMs}ms`
+        );
+        try {
+          this.onRetry?.(info);
+        } catch (observerError) {
+          console.warn(
+            `[${this.provider}] onRetry observer threw (ignored, retry proceeds): ${errorSummary(observerError)}`
+          );
+        }
+        await sleep(delayMs);
+      }
     }
   }
 };
 var AnthropicAgent = class extends LLMAgent {
   provider = "anthropic";
   resolveModel(model) {
-    if (process.env.CLAUDE_CODE_USE_BEDROCK === "1") {
+    const useBedrock = this.routeOverride?.useBedrock ?? process.env.CLAUDE_CODE_USE_BEDROCK === "1";
+    if (useBedrock) {
       return getBedrockModelId(model);
     }
     return model.startsWith("anthropic/") ? model.slice("anthropic/".length) : model;
   }
   async createClient() {
-    if (process.env.CLAUDE_CODE_USE_BEDROCK === "1") {
+    const useBedrock = this.routeOverride?.useBedrock ?? process.env.CLAUDE_CODE_USE_BEDROCK === "1";
+    if (useBedrock) {
       const { AnthropicBedrock } = await import('@anthropic-ai/bedrock-sdk');
       return new AnthropicBedrock({
         awsRegion: process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION ?? "us-east-1"
       });
     }
-    return createAnthropicClient(process.env.ANTHROPIC_API_KEY);
+    return createAnthropicClient(this.routeOverride?.apiKey ?? process.env.ANTHROPIC_API_KEY);
   }
   async callText(model, systemPrompt, userPrompt, maxTokens, temperature) {
     const client = await this.getClient();
@@ -2956,6 +3080,73 @@ var AnthropicAgent = class extends LLMAgent {
       throw e;
     }
   }
+  async callVision(model, systemPrompt, userPrompt, image, maxTokens) {
+    const client = await this.getClient();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    const imageBlock = {
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: image.mediaType,
+        data: image.base64
+      }
+    };
+    try {
+      const response = await this.apiCall(
+        () => client.messages.create({
+          model: resolvedModel,
+          max_tokens: maxTokens ?? 1500,
+          system: systemPrompt,
+          messages: [
+            {
+              role: "user",
+              content: [imageBlock, { type: "text", text: userPrompt }]
+            }
+          ]
+        })
+      );
+      const text = response.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "anthropic",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        result: {
+          inputTokens: response.usage.input_tokens,
+          outputTokens: response.usage.output_tokens,
+          text
+        }
+      });
+      return {
+        text,
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens
+      };
+    } catch (e) {
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "anthropic",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        error: { message: e instanceof Error ? e.message : String(e) }
+      });
+      throw e;
+    }
+  }
   async callTools(model, systemPrompt, userPrompt, tools, toolChoice = "required", _scopedTools) {
     const client = await this.getClient();
     const traceId = newLlmTraceId();
@@ -3155,7 +3346,7 @@ var OpenAIAgent = class extends LLMAgent {
   }
   async createClient() {
     const { default: OpenAISDK } = await import('openai');
-    return new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY });
+    return new OpenAISDK({ apiKey: this.routeOverride?.apiKey ?? process.env.OPENAI_API_KEY });
   }
   async callText(model, systemPrompt, userPrompt, maxTokens, temperature) {
     const client = await this.getClient();
@@ -3326,7 +3517,7 @@ var GoogleAgent = class extends LLMAgent {
   async createClient() {
     const { GoogleGenAI: GoogleGenAISDK } = await import('@google/genai');
     return new GoogleGenAISDK({
-      apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY,
+      apiKey: this.routeOverride?.apiKey ?? (process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY),
       httpOptions: { timeout: 3e5 }
       // 5 min — Pro models can be slow
     });
@@ -3351,6 +3542,72 @@ var GoogleAgent = class extends LLMAgent {
       outputTokens: interaction.usage?.total_output_tokens ?? 0
     };
   }
+  async callVision(model, systemPrompt, userPrompt, image, maxTokens) {
+    const client = await this.getClient();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+    try {
+      const response = await this.apiCall(
+        () => client.models.generateContent({
+          model: resolvedModel,
+          contents: [
+            {
+              role: "user",
+              parts: [
+                { inlineData: { mimeType: image.mediaType, data: image.base64 } },
+                { text: userPrompt }
+              ]
+            }
+          ],
+          config: {
+            systemInstruction: systemPrompt,
+            ...maxTokens ? { maxOutputTokens: maxTokens } : {}
+          }
+        })
+      );
+      const text = response.candidates?.[0]?.content?.parts?.map((p) => p.text || "").join("") || "";
+      const usage = response.usageMetadata;
+      const result = {
+        text,
+        inputTokens: usage?.promptTokenCount ?? 0,
+        outputTokens: usage?.candidatesTokenCount ?? 0
+      };
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "google",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        result: {
+          inputTokens: result.inputTokens,
+          outputTokens: result.outputTokens,
+          text
+        }
+      });
+      return result;
+    } catch (e) {
+      const endedAt = Date.now();
+      emitLlmTraceEvent({
+        id: traceId,
+        at: startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        provider: "google",
+        model: resolvedModel,
+        kind: "callVision",
+        systemPrompt,
+        userPrompt,
+        error: { message: e instanceof Error ? e.message : String(e) }
+      });
+      throw e;
+    }
+  }
   async callTools(model, systemPrompt, userPrompt, tools, _toolChoice = "required", scopedTools) {
     const client = await this.getClient();
     const interactionTools = tools.map((t) => ({
@@ -3553,7 +3810,7 @@ var OpenRouterAgent = class extends LLMAgent {
   async createClient() {
     const { OpenRouterClient: OpenRouterClient2 } = await Promise.resolve().then(() => (init_client(), client_exports));
     return new OpenRouterClient2({
-      apiKey: process.env.OPENROUTER_API_KEY
+      apiKey: this.routeOverride?.apiKey ?? process.env.OPENROUTER_API_KEY
     });
   }
   async callText(model, systemPrompt, userPrompt, maxTokens, temperature) {
@@ -3679,21 +3936,24 @@ var OpenRouterAgent = class extends LLMAgent {
     return { text: finalText, inputTokens: totalInput, outputTokens: totalOutput, turnsUsed };
   }
 };
-function createAgent(provider) {
+function createAgent(providerOrConfig) {
+  const provider = typeof providerOrConfig === "string" ? providerOrConfig : providerOrConfig.provider;
+  const routeOverride = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.routeOverride;
+  const onRetry = typeof providerOrConfig === "string" ? void 0 : providerOrConfig.onRetry;
   switch (provider) {
     case "anthropic":
-      return new AnthropicAgent();
+      return new AnthropicAgent(routeOverride, onRetry);
     case "openai":
-      return new OpenAIAgent();
+      return new OpenAIAgent(routeOverride, onRetry);
     case "google":
-      return new GoogleAgent();
+      return new GoogleAgent(routeOverride, onRetry);
     case "openrouter":
-      return new OpenRouterAgent();
+      return new OpenRouterAgent(routeOverride, onRetry);
   }
 }
 async function callLLM(config, systemPrompt, userPrompt, maxTokens) {
   const start = Date.now();
-  const agent = createAgent(config.provider);
+  const agent = createAgent(config);
   const result = await agent.callText(
     config.model,
     systemPrompt,