@ggui-ai/ui-gen 0.8.0 → 0.10.0

package/src/harness/llm-router.ts

@@ -10,6 +10,7 @@
 
 import type Anthropic from '@anthropic-ai/sdk';
 import type {
+  ImageBlockParam,
   TextBlock,
   TextBlockParam,
   ToolUseBlock,
@@ -53,6 +54,51 @@ export interface AgentConfig {
    * behavior for all existing callers).
    */
   temperature?: number;
+  /**
+   * Explicit per-call credentials/routing, bypassing `process.env`
+   * entirely when supplied. Absent (default) preserves today's
+   * behavior — each agent falls back to reading its provider's env
+   * var(s) directly, so existing callers (including self-hosters who
+   * set env vars once at process start) are unaffected. Use this to
+   * run concurrent generations safely in one process: two simultaneous
+   * calls with different `routeOverride`s never race on shared
+   * `process.env` state.
+   */
+  routeOverride?: {
+    readonly apiKey?: string;
+    /** Anthropic-only: force the Bedrock-IAM client instead of the direct API client. */
+    readonly useBedrock?: boolean;
+  };
+  /**
+   * Observer invoked once per retried attempt when `apiCall()` (#489)
+   * retries a rate-limited (HTTP 429) provider call. Fires AFTER the
+   * retry decision is made and BEFORE the delay is awaited — never on
+   * the terminal failure/success of the whole call. Purely an
+   * observability hook: it never influences whether or how long
+   * `apiCall()` retries. If the observer itself throws, `apiCall()`
+   * catches it, logs a `console.warn`, and proceeds to the retry
+   * delay unaffected — a broken observer cannot turn a recoverable
+   * 429 into an unrelated hard failure. Absent (default) is a no-op;
+   * `apiCall()` still logs every retry via `console.warn` regardless.
+   */
+  onRetry?: (info: ProviderRetryInfo) => void;
+}
+
+/** One retried attempt's context — passed to `AgentConfig.onRetry`. */
+export interface ProviderRetryInfo {
+  readonly provider: AgentConfig['provider'];
+  /** 1-based index of this retry (1 = first retry, 2 = second, …). */
+  readonly attempt: number;
+  /** Total retries `apiCall()` will attempt before giving up. */
+  readonly maxAttempts: number;
+  /** HTTP status of the failed call, when the caught error carries one. */
+  readonly status: number | undefined;
+  /** Provider-supplied `Retry-After` value in seconds, when present and within the cap. */
+  readonly retryAfterSec: number | undefined;
+  /** Delay actually awaited before the next attempt. */
+  readonly delayMs: number;
+  /** One-line error summary (same shape as the existing `console.error` line). */
+  readonly message: string;
 }
 
 export interface LLMResponse {
@@ -61,6 +107,35 @@ export interface LLMResponse {
   outputTokens: number;
 }
 
+/**
+ * Image payload for {@link VisionAgent.callVision}. Base64-encoded
+ * bytes plus their media type — the two fields every vision-capable
+ * provider SDK needs to reconstruct the image part.
+ */
+export interface VisionImageInput {
+  mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
+  base64: string;
+}
+
+/**
+ * The multimodal (image + text) call surface. Implemented by the
+ * providers whose SDK path supports vision input (Anthropic, Google);
+ * construct one via {@link createVisionAgent} so the call runs inside
+ * the same `apiCall()` retry/observability choke point as every text
+ * call — provider 429s retry with `Retry-After` honoring, `onRetry`
+ * reaches the caller's structured log, and `routeOverride` governs
+ * credentials and model routing instead of `process.env`.
+ */
+export interface VisionAgent {
+  callVision(
+    model: string,
+    systemPrompt: string,
+    userPrompt: string,
+    image: VisionImageInput,
+    maxTokens?: number,
+  ): Promise<LLMResponse>;
+}
+
 export interface LLMTool {
   name: string;
   description: string;
@@ -167,6 +242,59 @@ function errorSummary(e: unknown): string {
   return `${e.constructor.name}${status}${code}: ${e.message.slice(0, 120)}${body}`;
 }
 
+/** True when the caught value looks like an HTTP 429 from any provider SDK. */
+function isRateLimited(e: unknown): boolean {
+  if (!(e instanceof Error) || !('status' in e)) return false;
+  return (e as { status: unknown }).status === 429;
+}
+
+/** HTTP status of the caught error, when the SDK attached one. Duck-typed — matches `errorSummary`'s existing precedent. */
+function extractStatus(e: unknown): number | undefined {
+  if (!(e instanceof Error) || !('status' in e)) return undefined;
+  const status = (e as { status: unknown }).status;
+  return typeof status === 'number' ? status : undefined;
+}
+
+/**
+ * Duck-typed `Retry-After` extraction. Both `@anthropic-ai/sdk`'s and
+ * `openai`'s `APIError` attach a `Headers`-like `.headers` (with
+ * `.get()`) to the thrown error at construction time — this is the
+ * ONLY point in the call chain where that header is still reachable
+ * (confirmed by reading both SDKs' error constructors). Handles the
+ * delta-seconds form only (a plain integer/float string) — the rarer
+ * HTTP-date form parses to `NaN` and correctly falls through to
+ * `undefined` rather than fabricating a value. Google's `ApiError` has
+ * no `.headers` at all, so this always returns `undefined` for Google
+ * — expected, not a gap.
+ */
+function extractRetryAfterSec(e: unknown): number | undefined {
+  if (!(e instanceof Error) || !('headers' in e)) return undefined;
+  const headers = (e as { headers?: unknown }).headers;
+  if (
+    headers === null ||
+    typeof headers !== 'object' ||
+    !('get' in headers) ||
+    typeof (headers as { get?: unknown }).get !== 'function'
+  ) {
+    return undefined;
+  }
+  const raw = (headers as { get(name: string): string | null }).get('retry-after');
+  if (raw === null) return undefined;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : undefined;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Retry budget for `apiCall()` — see the docstring on `apiCall()` itself for the full policy. */
+const MAX_RETRY_ATTEMPTS = 2;
+const RETRY_AFTER_CAP_SEC = 15;
+const DEFAULT_BACKOFF_BASE_MS = 1000;
+const DEFAULT_BACKOFF_MAX_MS = 8000;
+const MAX_TOTAL_RETRY_DELAY_MS = 20000;
+
 // =============================================================================
 // LLMAgent — abstract base
 // =============================================================================
@@ -181,6 +309,21 @@ export abstract class LLMAgent {
   // Call resetSession() between independent generation runs.
   protected lastSessionId: string | undefined;
 
+  /**
+   * 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.
+   */
+  protected readonly routeOverride: AgentConfig['routeOverride'];
+
+  /** See `AgentConfig.onRetry` (#489). Absent is a no-op. */
+  protected readonly onRetry: AgentConfig['onRetry'];
+
+  constructor(routeOverride?: AgentConfig['routeOverride'], onRetry?: AgentConfig['onRetry']) {
+    this.routeOverride = routeOverride;
+    this.onRetry = onRetry;
+  }
 
   protected abstract resolveModel(model: string): string;
   protected abstract createClient(): Promise<unknown>;
@@ -268,17 +411,92 @@ export abstract class LLMAgent {
   }
 
   /**
-   * 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.
    */
   protected async apiCall<T>(fn: () => Promise<T>): Promise<T> {
     const start = Date.now();
-    try {
-      return await fn();
-    } catch (e: unknown) {
-      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: unknown) {
+        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 !== undefined && 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 !== undefined
+            ? retryAfterSec * 1000
+            : 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: ProviderRetryInfo = {
+          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) {
+          // Guard, not propagate — the docstring on AgentConfig.onRetry
+          // promises this is "purely an observability hook: it never
+          // influences whether or how long apiCall() retries". A
+          // caller-supplied observer that throws must not turn a
+          // recoverable 429 into an unrelated hard failure.
+          console.warn(
+            `[${this.provider}] onRetry observer threw (ignored, retry proceeds): ${errorSummary(observerError)}`,
+          );
+        }
+        await sleep(delayMs);
+      }
     }
   }
 
@@ -294,7 +512,9 @@ export class AnthropicAgent extends LLMAgent {
   protected resolveModel(model: string): string {
     // Bedrock IAM path — the upstream model id must be the cross-region
     // inference-profile form (`us.anthropic.*`), not the bare API id.
-    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/')
@@ -303,12 +523,14 @@ export class AnthropicAgent extends LLMAgent {
   }
 
   protected async createClient(): Promise<Anthropic | AnthropicBedrock> {
-    // Bedrock IAM path: `resolveRoute` (provider-router) sets
-    // CLAUDE_CODE_USE_BEDROCK=1 and clears ANTHROPIC_API_KEY for the
-    // pool-funded cloud pod. Auth is the pod's IRSA role — no API key.
-    // `AnthropicBedrock` is wire-compatible with `Anthropic` for the
-    // `.messages` API this agent uses.
-    if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') {
+    // Bedrock IAM path: when CLAUDE_CODE_USE_BEDROCK=1 (set by the
+    // deployment's provider routing), auth comes from the ambient AWS
+    // credential chain (instance role, env credentials, etc.) — no API
+    // key. `AnthropicBedrock` is wire-compatible with `Anthropic` for
+    // the `.messages` API this agent uses.
+    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:
@@ -319,8 +541,10 @@ export class AnthropicAgent extends LLMAgent {
     }
     // SDK construction lives in `adapters/claude/client.ts`. The BYOK
     // resolver writes the raw key into `process.env.ANTHROPIC_API_KEY`
-    // before this runs (see `applyRouteToEnv` in provider-router).
-    return createAnthropicClient(process.env.ANTHROPIC_API_KEY);
+    // before this runs (see `applyRouteToEnv` in provider-router) —
+    // `routeOverride.apiKey`, when supplied, skips that env round-trip
+    // entirely.
+    return createAnthropicClient(this.routeOverride?.apiKey ?? process.env.ANTHROPIC_API_KEY);
   }
 
   async callText(
@@ -413,6 +637,90 @@ export class AnthropicAgent extends LLMAgent {
     }
   }
 
+  async callVision(
+    model: string,
+    systemPrompt: string,
+    userPrompt: string,
+    image: VisionImageInput,
+    maxTokens?: number,
+  ): Promise<LLMResponse> {
+    const client = await this.getClient<Anthropic>();
+    const traceId = newLlmTraceId();
+    const startedAt = Date.now();
+    const resolvedModel = this.resolveModel(model);
+
+    const imageBlock: ImageBlockParam = {
+      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 is TextBlock => block.type === 'text')
+        .map((block) => block.text)
+        .join('');
+
+      const endedAt = Date.now();
+      // The image bytes stay OUT of the trace — a base64 screenshot
+      // would balloon every event; the prompts identify the call.
+      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: string,
     systemPrompt: string,
@@ -670,7 +978,7 @@ export class OpenAIAgent extends LLMAgent {
 
   protected async createClient(): Promise<OpenAI> {
     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(
@@ -928,7 +1236,8 @@ export class GoogleAgent extends LLMAgent {
   protected async createClient(): Promise<GoogleGenAI> {
     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: 300_000 }, // 5 min — Pro models can be slow
     });
   }
@@ -964,6 +1273,86 @@ export class GoogleAgent extends LLMAgent {
     };
   }
 
+  async callVision(
+    model: string,
+    systemPrompt: string,
+    userPrompt: string,
+    image: VisionImageInput,
+    maxTokens?: number,
+  ): Promise<LLMResponse> {
+    const client = await this.getClient<GoogleGenAI>();
+    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: LLMResponse = {
+        text,
+        inputTokens: usage?.promptTokenCount ?? 0,
+        outputTokens: usage?.candidatesTokenCount ?? 0,
+      };
+
+      const endedAt = Date.now();
+      // The image bytes stay OUT of the trace — a base64 screenshot
+      // would balloon every event; the prompts identify the call.
+      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: string,
     systemPrompt: string,
@@ -1248,7 +1637,7 @@ export class OpenRouterAgent extends LLMAgent {
   protected async createClient(): Promise<unknown> {
     const { OpenRouterClient } = await import('../adapters/openrouter/client');
     return new OpenRouterClient({
-      apiKey: process.env.OPENROUTER_API_KEY!,
+      apiKey: this.routeOverride?.apiKey ?? process.env.OPENROUTER_API_KEY!,
     });
   }
 
@@ -1432,17 +1821,52 @@ export class OpenRouterAgent extends LLMAgent {
 /**
  * Create a fresh agent instance for the given provider.
  * Each call returns a new instance — no shared state between callers.
+ *
+ * Accepts either a bare provider string (every pre-existing call
+ * site — the agent falls back to reading its provider's env var(s)
+ * directly) or a full {@link AgentConfig}, whose `routeOverride`
+ * (when present) is threaded into the constructed agent so it never
+ * touches `process.env`.
  */
-export function createAgent(provider: AgentConfig['provider']): LLMAgent {
+export function createAgent(provider: AgentConfig['provider']): LLMAgent;
+export function createAgent(config: AgentConfig): LLMAgent;
+export function createAgent(providerOrConfig: AgentConfig['provider'] | AgentConfig): LLMAgent {
+  const provider =
+    typeof providerOrConfig === 'string' ? providerOrConfig : providerOrConfig.provider;
+  const routeOverride =
+    typeof providerOrConfig === 'string' ? undefined : providerOrConfig.routeOverride;
+  const onRetry = typeof providerOrConfig === 'string' ? undefined : 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);
+  }
+}
+
+/** Providers whose agent implements {@link VisionAgent}. */
+export type VisionProvider = 'anthropic' | 'google';
+
+/**
+ * Construct an agent for a multimodal (image + text) call. Same
+ * threading contract as {@link createAgent} — `routeOverride` and
+ * `onRetry` from the config reach the constructed agent — with the
+ * provider narrowed to the ones whose SDK path supports vision input,
+ * so the returned type carries `callVision` statically instead of
+ * every caller re-proving it.
+ */
+export function createVisionAgent(
+  config: AgentConfig & { provider: VisionProvider },
+): LLMAgent & VisionAgent {
+  switch (config.provider) {
+    case 'anthropic':
+      return new AnthropicAgent(config.routeOverride, config.onRetry);
+    case 'google':
+      return new GoogleAgent(config.routeOverride, config.onRetry);
   }
 }
 
@@ -1457,7 +1881,7 @@ export async function callLLM(
   maxTokens?: number,
 ): Promise<LLMResponse> {
   const start = Date.now();
-  const agent = createAgent(config.provider);
+  const agent = createAgent(config);
   const result = await agent.callText(
     config.model,
     systemPrompt,
@@ -1479,7 +1903,7 @@ export async function callLLMWithTools(
   maxTurns: number = 10,
 ): Promise<LLMWithToolsResponse> {
   const start = Date.now();
-  const agent = createAgent(config.provider);
+  const agent = createAgent(config);
   const result = await agent.callWithTools(
     config.model,
     systemPrompt,

package/src/harness/llm-trace-sink.ts

@@ -39,7 +39,8 @@ export type LlmTraceKind =
   | 'callText'
   | 'callTools'
   | 'callWithTools'
-  | 'callStructured';
+  | 'callStructured'
+  | 'callVision';
 
 /**
  * One LLM call. Emitted **after** the call completes (success or error)

package/src/harness/runtime.ts

@@ -31,6 +31,7 @@ import { WIRE_DOCUMENTATION } from "../tools/get-wire.js";
 import { renderPitfallsBlock } from "./pitfalls.js";
 import type { GadgetDescriptor, DataContract, JsonObject } from "@ggui-ai/protocol";
 import { buildSystemPrompt as buildSystemPromptSkeleton } from "../boilerplate.js";
+import type { AgentConfig } from "./llm-router.js";
 
 // Re-export the boilerplate generator so existing internal importers
 // (create-harness.ts, benchmarks/preview-boilerplate.ts) keep working.
@@ -46,6 +47,20 @@ type Provider = "anthropic" | "openai" | "google" | "openrouter";
 export interface AgentSpec {
   provider: Provider;
   model: string;
+  /**
+   * Explicit per-call credentials/routing (#484) — see
+   * `AgentConfig.routeOverride`. Threaded through unchanged so
+   * `createAgent()` can bypass `process.env` when the caller supplies
+   * it. Absent for every pre-existing caller.
+   */
+  routeOverride?: AgentConfig["routeOverride"];
+  /**
+   * Retry observer (#489) — see `AgentConfig.onRetry`. Threaded
+   * through unchanged so `createAgent()` can notify the caller when
+   * `apiCall()` retries a rate-limited request. Absent for every
+   * pre-existing caller (no-op).
+   */
+  onRetry?: AgentConfig["onRetry"];
 }
 
 export interface SingleComponentParams {

package/src/index.ts

@@ -2,14 +2,13 @@
  * `@ggui-ai/ui-gen` — open-source UI generation harness.
  *
  * Implements the `UiGenerator` contract from `@ggui-ai/mcp-server-core`.
- * `createUiGenerator()` returns a callable provider-backed generator:
+ * `createUiGenerator()` returns a callable provider-backed generator.
+ * Provider routing, compilation, and the system prompt are all
+ * internal to the harness — the factory takes no `adapter` option:
  *
  *   import { createUiGenerator } from '@ggui-ai/ui-gen';
- *   import { createAnthropicAdapter } from '@ggui-ai/ui-gen/providers';
  *
- *   const generator = createUiGenerator({
- *     adapter: createAnthropicAdapter(),
- *   });
+ *   const generator = createUiGenerator();
  *   const result = await generator.generate({ request, llm, providerKey, blueprints });
  *
  * The `./harness` / `./workflows` / `./classifier` / `./fragments`
@@ -21,6 +20,7 @@ export {
   extractComponentCode,
 } from './create-ui-generator.js';
 export type { CreateUiGeneratorOptions } from './create-ui-generator.js';
+export type { ProviderRetryInfo } from './harness/llm-router.js';
 
 // Generator registry seam re-export. The interface + slug helpers live
 // in `@ggui-ai/mcp-server-core`; the in-memory factory lives in