@ggui-ai/ui-gen 0.9.0 → 0.11.0

package/src/harness/coding/run-eval-round.ts

@@ -121,6 +121,29 @@ export interface EvalRoundResult {
 /** Cap feedback to N issues per eval-fix turn so the LLM stays surgical. */
 const MAX_FEEDBACK_ISSUES = 3;
 
+/**
+ * Pick the ≤{@link MAX_FEEDBACK_ISSUES} issues an eval-fix turn feeds
+ * back. Provenance-aware (Exp 54 P1 addendum): ONE slot is reserved
+ * for the first deterministic tier-0 fail (axis/mode checks —
+ * machine-verified findings) when one exists; the rest fill
+ * fails-first then warns. Without the reservation, the merge order
+ * put deterministic findings last and any round with ≥3 LLM-judge
+ * fails silently starved them — the model never saw a precision-1.00
+ * structural finding while the stuck detector blamed it for not
+ * fixing it. Exactly one slot, so crash-class LLM fails keep the
+ * other two. Exported for the pins.
+ */
+export function selectActionableFeedback(issues: readonly EvalIssue[]): EvalIssue[] {
+  const pool = issues.filter((i) => i.result === "fail" || i.result === "warn");
+  const reserved = pool.find((i) => i.tier === 0 && i.result === "fail");
+  return [
+    ...(reserved ? [reserved] : []),
+    ...pool
+      .filter((i) => i !== reserved)
+      .sort((a, b) => (a.result === "fail" ? 0 : 1) - (b.result === "fail" ? 0 : 1)),
+  ].slice(0, MAX_FEEDBACK_ISSUES);
+}
+
 /**
  * Fingerprint a fail issue for cross-round stuck detection. Identifies the
  * "same fail" without being thrown by minor description-text variation.
@@ -424,6 +447,13 @@ export async function runEvalRound(
               // inside the same concurrent generation, so the race is
               // real here too, not just on the coding turn).
               routeOverride: evaluationAgent.routeOverride,
+              // #489 — thread the same provider-429-retry observer.
+              // Without this, a rate-limited retry inside the
+              // evaluation agent's apiCall() happens (the base-class
+              // retry loop is unconditional) but never reaches the
+              // caller, silently missing the host application's
+              // structured log.
+              onRetry: evaluationAgent.onRetry,
             },
             preWarmedContext,
           )
@@ -437,6 +467,14 @@ export async function runEvalRound(
               passThreshold: visualThreshold,
               sampleProps: visualEvaluation?.sampleProps,
               viewport: visualEvaluation?.viewport,
+              // #484/#489 — same threading as the LLM-eval leg above:
+              // the visual eval's multimodal call runs inside the same
+              // concurrent generation, so it needs the same routing
+              // override (never fall back to `process.env`) and the
+              // same provider-429-retry observer (retries reach the
+              // host application's structured log).
+              routeOverride: visualEvalAgent.routeOverride,
+              onRetry: visualEvalAgent.onRetry,
             },
           )
         : null,
@@ -758,10 +796,19 @@ export async function runEvalRound(
     // Feeding too many issues at once causes the LLM to make many simultaneous
     // changes, breaking JSX nesting in complex components. Prioritize fails
     // first, then warns, capped to keep fixes surgical.
-    const allActionable = evalResult.issues
-      .filter((i) => i.result === "fail" || i.result === "warn")
-      .sort((a, b) => (a.result === "fail" ? 0 : 1) - (b.result === "fail" ? 0 : 1))
-      .slice(0, MAX_FEEDBACK_ISSUES);
+    //
+    // Provenance-aware selection (Exp 54 P1 addendum): deterministic
+    // tier-0 fails (axis/mode checks — machine-verified, precision-1.00
+    // findings) get ONE reserved slot, first. Before this, the merge
+    // order (`allIssues = [...llm, ...visual, ...mode]`) + stable sort
+    // + slice meant any round where the LLM leg emitted ≥3 fails
+    // silently starved every deterministic finding — the model never
+    // saw it, the fingerprint set still recorded it, and the stuck
+    // detector exited on an issue that was never delivered (2/9 cells
+    // shipped a P0 structural defect this way, one displaced by
+    // design-token nits). Exactly one slot is reserved so crash-class
+    // LLM fails keep the other two.
+    const allActionable = selectActionableFeedback(evalResult.issues);
     const issueLines = allActionable.map((issue) => {
       const tag = issue.result === "fail" ? "FAIL" : "WARN";
       return `[${tag}] ${issue.category}${issue.subcategory ? "/" + issue.subcategory : ""}: ${issue.description}\n  Fix: ${issue.fix}`;
@@ -777,7 +824,16 @@ export async function runEvalRound(
       evalResult,
       evalRoundsUsed,
       prevModeSubcats: updatedPrevModeSubcats,
-      prevFailFingerprints: currFailFingerprints,
+      // DELIVERED fails only (Exp 54 P1 addendum, proposal 2): the
+      // stuck detector's premise is "the LLM saw these and did not
+      // resolve them" — recording fails that the MAX_FEEDBACK_ISSUES
+      // cap cut from the feedback turns truncation into a premature
+      // stuck-exit (the model never saw the issue it is blamed for
+      // not fixing). An undelivered fail recurring next round now
+      // reads as NEW, gets delivered, and earns its fix round.
+      prevFailFingerprints: new Set(
+        allActionable.filter((i) => i.result === "fail").map(fingerprintFail),
+      ),
       preWarmedContext,
       evalTokens,
       evalLlmMs,

package/src/harness/index.ts

@@ -27,7 +27,7 @@ export type {
 } from "./types-public.js";
 export { defaultApplyPatch, applyLineRanges } from "../patch.js";
 export { callLLM, createAgent } from "./llm-router.js";
-export type { AgentConfig, LLMResponse } from "./llm-router.js";
+export type { AgentConfig, LLMResponse, ProviderRetryInfo } from "./llm-router.js";
 export {
   computeHarnessId,
   computeHarnessName,

package/src/harness/llm-router.ts

@@ -10,6 +10,7 @@
 
 import type Anthropic from '@anthropic-ai/sdk';
 import type {
+  ImageBlockParam,
   TextBlock,
   TextBlockParam,
   ToolUseBlock,
@@ -68,6 +69,36 @@ export interface AgentConfig {
     /** 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 {
@@ -76,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;
@@ -182,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
 // =============================================================================
@@ -204,8 +317,12 @@ export abstract class LLMAgent {
    */
   protected readonly routeOverride: AgentConfig['routeOverride'];
 
-  constructor(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;
@@ -294,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);
+      }
     }
   }
 
@@ -331,11 +523,11 @@ 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.
+    // 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) {
@@ -445,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,
@@ -997,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,
@@ -1479,15 +1835,38 @@ export function createAgent(providerOrConfig: AgentConfig['provider'] | AgentCon
     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(routeOverride);
+      return new AnthropicAgent(routeOverride, onRetry);
     case 'openai':
-      return new OpenAIAgent(routeOverride);
+      return new OpenAIAgent(routeOverride, onRetry);
     case 'google':
-      return new GoogleAgent(routeOverride);
+      return new GoogleAgent(routeOverride, onRetry);
     case 'openrouter':
-      return new OpenRouterAgent(routeOverride);
+      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);
   }
 }
 

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

@@ -54,6 +54,13 @@ export interface AgentSpec {
    * 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