@ggui-ai/ui-gen 0.9.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,
@@ -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

package/src/provider-adapter.ts

@@ -1,7 +1,18 @@
 /**
  * Provider adapter contract — the narrow surface every concrete LLM
- * provider client (Anthropic, Google, OpenAI, OpenRouter) implements
- * before the generator wires them in.
+ * provider client (Anthropic, Google, OpenAI, OpenRouter, Bedrock)
+ * implements.
+ *
+ * **Real role:** a provider-agnostic one-shot LLM caller for
+ * lightweight callers that need a single `complete()` round-trip — NOT
+ * a generation harness. The primary consumer is the negotiator's LLM
+ * seam (`@ggui-ai/mcp-server`'s `llm-backed-negotiator.ts`, via
+ * {@link selectAdapter} from `./providers/index.js`); other lightweight
+ * one-shot callers use it the same way. It is explicitly NOT part of
+ * the generation dispatch path: `createUiGenerator()` accepts no
+ * adapter option, and generation-call 429 retry/backoff lives entirely
+ * in `harness/llm-router.ts`'s `apiCall()` — a separate retry story for
+ * a separate call shape (an agentic SDK loop, not a single completion).
  *
  * The contract is deliberately defined independently of concrete
  * adapters so:
@@ -9,10 +20,9 @@
  *   - Adapter implementations can be written against a stable surface —
  *     every concrete adapter MUST pass
  *     {@link providerAdapterContract} or it isn't a `ProviderAdapter`.
- *   - Downstream callers (`createUiGenerator`, render handlers, retry /
- *     backoff plumbing) build against ONE structured failure shape
- *     ({@link ProviderError}) instead of inventing per-provider error
- *     UX.
+ *   - Downstream one-shot callers build against ONE structured failure
+ *     shape ({@link ProviderError}) instead of inventing per-provider
+ *     error UX.
  *   - The negotiator + cache layers can branch on
  *     `error.kind === 'rate-limited'` etc. without parsing strings.
  *

package/src/providers/bedrock.ts

@@ -7,8 +7,8 @@
  *
  * ## Why this adapter exists
  *
- * Anyone running the generator on an AWS-credentialed host (EC2, ECS,
- * Lambda, EKS) can target Bedrock without managing API keys: IAM is
+ * Anyone running a one-shot LLM caller on an AWS-credentialed host
+ * (EC2, ECS, Lambda, EKS) can target Bedrock without managing API keys: IAM is
  * the auth boundary, AWS rotates host credentials automatically, and
  * a misconfigured IAM role surfaces as a clear `AccessDeniedException`
  * the SDK funnels through `mapError`. The alternative — parking a
@@ -198,8 +198,9 @@ export interface BedrockAdapterOptions {
  *
  * No API key — IAM is the auth boundary. The returned `ProviderAdapter`
  * satisfies the same contract as `createAnthropicAdapter`, so it
- * slots into `createUiGenerator({ adapter })` interchangeably (modulo
- * the per-provider model-id namespace differences).
+ * slots into any one-shot `ProviderAdapter` caller (e.g. `selectAdapter`)
+ * interchangeably (modulo the per-provider model-id namespace
+ * differences).
  */
 export function createBedrockAdapter(
   options: BedrockAdapterOptions = {},

package/src/providers/index.ts

@@ -5,6 +5,15 @@
  * providers ggui supports today: Anthropic (direct API), Google,
  * OpenAI, OpenRouter, and AWS Bedrock (Anthropic models via IAM).
  *
+ * **Real role:** a provider-agnostic one-shot LLM caller for
+ * lightweight callers that need a single `complete()` round-trip — NOT
+ * the generation dispatch path. `createUiGenerator()` accepts no
+ * adapter option; generation-call retry/backoff lives entirely in
+ * `harness/llm-router.ts`'s `apiCall()`. The primary consumer is the
+ * negotiator's LLM seam (`@ggui-ai/mcp-server`'s
+ * `llm-backed-negotiator.ts`, via {@link selectAdapter}); other
+ * lightweight one-shot callers use it the same way.
+ *
  * Every adapter satisfies the structural
  * {@link import('../provider-adapter.js').ProviderAdapter} contract.
  * The four direct-API adapters compose
@@ -15,15 +24,18 @@
  * because rolling our own AWS SigV4 signer for one provider isn't a
  * reasonable trade.
  *
- * Typical usage from the CLI:
+ * Typical usage — a one-shot completion:
  *
  *   ```ts
  *   import { createAnthropicAdapter } from '@ggui-ai/ui-gen/providers';
- *   import { createUiGenerator } from '@ggui-ai/ui-gen';
  *
  *   const adapter = createAnthropicAdapter();
- *   const generator = createUiGenerator({ adapter });
- *   const result = await generator.generate({ request, llm, providerKey, blueprints });
+ *   const result = await adapter.complete({
+ *     apiKey,
+ *     route: { provider: 'anthropic', model: 'claude-haiku-4-5-20251001' },
+ *     systemPrompt,
+ *     userPrompt,
+ *   });
  *   ```
  *
  * Bedrock pool path (no API key — IAM at process boot):