@ggui-ai/ui-gen 0.8.0 → 0.10.0

package/dist/llm-router-BEVtbAb9.d.ts

@@ -0,0 +1,213 @@
+import { JsonObject } from '@ggui-ai/protocol';
+import { LLMToolDef } from './llm.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;
+    /**
+     * 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`. */
+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;
+}
+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;
+    /**
+     * 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']);
+    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, 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 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.
+ *
+ * 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`.
+ */
+declare function createAgent(provider: AgentConfig['provider']): LLMAgent;
+declare function createAgent(config: AgentConfig): LLMAgent;
+declare function callLLM(config: AgentConfig, systemPrompt: string, userPrompt: string, maxTokens?: number): Promise<LLMResponse>;
+
+export { type AgentConfig as A, type LLMResponse as L, type ProviderRetryInfo as P, createAgent as a, callLLM as c };

package/dist/patch.d.ts

@@ -1,7 +1,7 @@
 import { PatchFn } from './harness/types-public.js';
 import '@ggui-ai/protocol';
 import './axes-CzLEMDeB.js';
-import './types-public-C36k1q6s.js';
+import './types-public-DIpjC-OA.js';
 import './types-BOvHNG7K.js';
 import './llm.js';
 import './policy.js';

package/dist/provider-adapter.d.ts

@@ -2,8 +2,19 @@ import { LlmProvider, LlmRoute } from '@ggui-ai/protocol';
 
 /**
  * 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:
@@ -11,10 +22,9 @@ import { LlmProvider, LlmRoute } from '@ggui-ai/protocol';
  *   - 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/dist/provider-adapter.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/provider-adapter.ts"],"names":[],"mappings":";AAqPO,SAAS,kBAAkB,IAAA,EAMhB;AAChB,EAAA,MAAM,GAAA,GAAqB;AAAA,IACzB,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,UAAU,IAAA,CAAK,QAAA;AAAA,IACf,SAAS,IAAA,CAAK,OAAA;AAAA,IACd,GAAI,KAAK,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,EAAQ,IAAA,CAAK,MAAA,EAAO,GAAI,EAAC;AAAA,IAC3D,GAAI,KAAK,aAAA,KAAkB,MAAA,GACvB,EAAE,aAAA,EAAe,IAAA,CAAK,aAAA,EAAc,GACpC;AAAC,GACP;AACA,EAAA,OAAO,GAAA;AACT;AAQO,SAAS,kBAAkB,MAAA,EAAmC;AACnE,EAAA,IAAI,MAAA,KAAW,KAAK,OAAO,cAAA;AAC3B,EAAA,IAAI,MAAA,KAAW,KAAK,OAAO,WAAA;AAC3B,EAAA,IAAI,MAAA,KAAW,KAAK,OAAO,cAAA;AAC3B,EAAA,IAAI,MAAA,IAAU,GAAA,IAAO,MAAA,GAAS,GAAA,EAAK,OAAO,cAAA;AAC1C,EAAA,IAAI,MAAA,IAAU,GAAA,IAAO,MAAA,GAAS,GAAA,EAAK,OAAO,cAAA;AAC1C,EAAA,OAAO,SAAA;AACT;AAcO,SAAS,qBAAA,CACd,UACA,OAAA,EACoB;AACpB,EAAA,IAAI,CAAC,OAAA,CAAQ,MAAA,IAAU,OAAA,CAAQ,MAAA,CAAO,WAAW,CAAA,EAAG;AAClD,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,OAAO,iBAAA,CAAkB;AAAA,QACvB,IAAA,EAAM,gBAAA;AAAA,QACN,QAAA;AAAA,QACA,OAAA,EAAS,GAAG,QAAQ,CAAA,qBAAA;AAAA,OACrB;AAAA,KACH;AAAA,EACF;AACA,EAAA,IAAI,CAAC,QAAQ,KAAA,EAAO,KAAA,IAAS,QAAQ,KAAA,CAAM,KAAA,CAAM,WAAW,CAAA,EAAG;AAC7D,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,OAAO,iBAAA,CAAkB;AAAA,QACvB,IAAA,EAAM,cAAA;AAAA,QACN,QAAA;AAAA,QACA,OAAA,EAAS,GAAG,QAAQ,CAAA,sBAAA;AAAA,OACrB;AAAA,KACH;AAAA,EACF;AACA,EAAA,OAAO,EAAE,IAAI,IAAA,EAAK;AACpB","file":"provider-adapter.js","sourcesContent":["/**\n * Provider adapter contract — the narrow surface every concrete LLM\n * provider client (Anthropic, Google, OpenAI, OpenRouter) implements\n * before the generator wires them in.\n *\n * The contract is deliberately defined independently of concrete\n * adapters so:\n *\n *   - Adapter implementations can be written against a stable surface —\n *     every concrete adapter MUST pass\n *     {@link providerAdapterContract} or it isn't a `ProviderAdapter`.\n *   - Downstream callers (`createUiGenerator`, render handlers, retry /\n *     backoff plumbing) build against ONE structured failure shape\n *     ({@link ProviderError}) instead of inventing per-provider error\n *     UX.\n *   - The negotiator + cache layers can branch on\n *     `error.kind === 'rate-limited'` etc. without parsing strings.\n *\n * **Scope:**\n *\n *   - Defines the interface, the response shape, the error shape,\n *     and a contract test runner that asserts every adapter\n *     satisfies the seam.\n *   - Does NOT call any LLM. The contract is structural; this\n *     package's own tests exercise the runner against a deterministic\n *     fixture adapter (`provider-adapter-mock.test-util.ts`).\n *\n * **Design choices, locked:**\n *\n *   - One discriminated `ProviderError.kind` union, not per-provider\n *     subclasses. Every provider's raw error funnels through\n *     `mapError` into one of these kinds. Callers branch on `kind`.\n *   - Every error carries `provider` + `message`; transport-shaped\n *     errors carry `status`; backoff-shaped errors carry\n *     `retryAfterSec`. Optional fields don't appear when they don't\n *     apply (no `status: undefined` noise in serialized logs).\n *   - `validateConfig` is synchronous + does NO I/O. It catches the\n *     \"operator never configured the provider\" case (missing key,\n *     malformed model id) before we attempt a network call.\n *   - `complete` is the single-completion seam. Streaming, tool\n *     calling, function calling, and harness retry land in higher\n *     layers — adapters stay narrow.\n */\nimport type { LlmProvider, LlmRoute } from '@ggui-ai/protocol';\n\n/**\n * One LLM completion request as the adapter sees it. Plain data so\n * tests can construct it without DI.\n *\n * `route` is a discriminated `LlmRoute` — `(provider, model)` typed\n * together so the model id is structurally constrained to its\n * provider's namespace (per the `MODELS` registry in\n * `@ggui-ai/protocol/types/llm-route`). This makes the #22 / #42 bug\n * class — passing a LiteLLM-prefixed `'anthropic/claude-haiku-4-5'`\n * where Anthropic expected the wire id `'claude-haiku-4-5-20251001'` —\n * a compile error at every adapter call site. The adapter reads the\n * wire-canonical string off `request.route.model` and passes it\n * verbatim to the provider SDK; no transformation step exists to\n * forget.\n */\nexport interface ProviderRequest {\n  /** API key. Resolved upstream by `@ggui-ai/cli/byok-resolver`. */\n  readonly apiKey: string;\n  /**\n   * Discriminated `(provider, model)` route. `route.model` is the\n   * wire-canonical id the provider's API expects — adapters pass it\n   * verbatim with no stripping or remapping.\n   */\n  readonly route: LlmRoute;\n  /** System prompt text. Adapter wires it into the provider's slot. */\n  readonly systemPrompt: string;\n  /** User prompt text. */\n  readonly userPrompt: string;\n  /**\n   * Optional cap on output tokens. Adapters MUST honor when the\n   * provider supports it; when absent, adapters use the provider\n   * default.\n   */\n  readonly maxTokens?: number;\n  /**\n   * Optional cancellation. Adapters MUST forward into the provider\n   * SDK's abort surface and reject with `ProviderError{kind:'aborted'}`\n   * when fired.\n   */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Successful provider response, normalized.\n *\n * Tool-calling output, multi-turn dialogue, structured-output\n * coercion all land in higher layers — this contract intentionally\n * stays narrow: text + usage + finish reason. The harness layer\n * composes adapters into multi-turn loops.\n */\nexport interface ProviderResponse {\n  /** The completion text returned by the provider. */\n  readonly text: string;\n  /** Token usage, per-call. Required — adapters synthesize 0 if the\n   *  provider didn't report it (and document that in their adapter). */\n  readonly usage: {\n    readonly inputTokens: number;\n    readonly outputTokens: number;\n  };\n  /**\n   * Why the model stopped. Mapped through a normalized union so\n   * callers don't have to know each provider's vocabulary.\n   *\n   *   - `'stop'`         model emitted EOS / stop sequence\n   *   - `'length'`       hit `maxTokens` or provider context limit\n   *   - `'content-filter'` provider safety filter intervened\n   *   - `'other'`        anything else (provider-specific reason)\n   */\n  readonly finishReason: 'stop' | 'length' | 'content-filter' | 'other';\n}\n\n/**\n * The structured failure contract. Every concrete adapter's\n * `mapError` MUST funnel raw provider errors into this shape so\n * downstream code branches on `kind`, not on string parsing.\n *\n * Discriminator + optional carriers:\n *\n *   - `'no-credentials'`   — no key supplied (pre-flight failure;\n *                            usually surfaced by `validateConfig`,\n *                            not `mapError`).\n *   - `'unauthorized'`     — provider returned 401. Key invalid /\n *                            revoked / wrong type.\n *   - `'forbidden'`        — provider returned 403. Quota exhausted,\n *                            org-level block, model not allowed for\n *                            this key. (Distinct from 401 because\n *                            \"rotate the key\" doesn't help.)\n *   - `'rate-limited'`     — provider returned 429. Carries\n *                            `retryAfterSec` when the provider\n *                            advertised one (`Retry-After` header).\n *   - `'server-error'`     — provider returned 5xx. Retryable.\n *   - `'client-error'`     — provider returned other 4xx. Usually\n *                            non-retryable (bad model id, malformed\n *                            request).\n *   - `'network'`          — TCP-level failure, DNS, EAI_AGAIN, etc.\n *                            No `status`. Retryable.\n *   - `'invalid-response'` — provider returned 2xx with a body the\n *                            adapter couldn't parse. Bug in the\n *                            adapter or in the provider; treat as\n *                            non-retryable.\n *   - `'aborted'`          — caller aborted via `signal`.\n *   - `'unknown'`          — last-resort bucket. Adapters that hit\n *                            this should be patched to map the\n *                            specific case explicitly.\n */\nexport type ProviderErrorKind =\n  | 'no-credentials'\n  | 'unauthorized'\n  | 'forbidden'\n  | 'rate-limited'\n  | 'server-error'\n  | 'client-error'\n  | 'network'\n  | 'invalid-response'\n  | 'aborted'\n  | 'unknown';\n\nexport interface ProviderError {\n  readonly kind: ProviderErrorKind;\n  readonly provider: LlmProvider;\n  /** Human-readable message. Safe to log; should not contain key\n   *  material — adapters MUST scrub before placing here. */\n  readonly message: string;\n  /** HTTP status when transport-shaped. Absent for pre-flight,\n   *  network, aborted, invalid-response. */\n  readonly status?: number;\n  /**\n   * Seconds to wait before retrying. Set ONLY for `'rate-limited'`\n   * when the provider advertised a `Retry-After` header. Higher-level\n   * retry policy uses this when present; falls back to its own\n   * exponential backoff when absent.\n   */\n  readonly retryAfterSec?: number;\n}\n\n/**\n * Pre-flight config validation. Synchronous, no I/O. Catches:\n *\n *   - missing or empty API key       → no-credentials\n *   - missing or empty model id      → client-error\n *\n * Adapters MAY widen the check with provider-specific rules\n * (e.g. \"openrouter model id MUST contain a `/`\"). Failures\n * surface through the same {@link ProviderError} so callers branch\n * on one union.\n */\nexport type ProviderValidation =\n  | { readonly ok: true }\n  | { readonly ok: false; readonly error: ProviderError };\n\n/**\n * The contract every provider client implements.\n */\nexport interface ProviderAdapter {\n  /** Provider this adapter speaks to. Stable identifier; lets the\n   *  caller route a `ProviderRequest` to the right adapter. */\n  readonly provider: LlmProvider;\n  /**\n   * Pre-flight check. MUST return synchronously and MUST NOT touch\n   * the network. Returns `{ok: true}` when the request is at least\n   * structurally valid; returns `{ok: false, error}` otherwise.\n   */\n  validateConfig(request: Pick<ProviderRequest, 'apiKey' | 'route'>): ProviderValidation;\n  /**\n   * Single-completion call. Resolves with `{ok: true, response}` on\n   * success or `{ok: false, error}` on any failure (network,\n   * provider 4xx/5xx, abort). Implementations MUST:\n   *\n   *   1. Funnel every raw provider error through `mapError`.\n   *   2. NOT throw. The result discriminator IS the error path.\n   *   3. Forward `request.signal` into the provider SDK's abort\n   *      mechanism + return `kind:'aborted'` when fired.\n   */\n  complete(request: ProviderRequest): Promise<ProviderResult>;\n  /**\n   * Map an arbitrary thrown / rejected value into a\n   * {@link ProviderError}. Exposed (not just internal) so test\n   * harnesses + retry policies can normalize errors without going\n   * through `complete`.\n   *\n   * MUST NEVER throw — `mapError(unknown)` is the safety net.\n   */\n  mapError(raw: unknown): ProviderError;\n}\n\n/**\n * Discriminated result of a `complete` call. Mirrors `validateConfig`\n * so callers never have to handle thrown errors from this seam.\n */\nexport type ProviderResult =\n  | { readonly ok: true; readonly response: ProviderResponse }\n  | { readonly ok: false; readonly error: ProviderError };\n\n// ─── Helpers concrete adapters compose with ────────────────────────\n\n/**\n * Build a `ProviderError` of the supplied kind. Centralized so\n * concrete adapters don't drift on field shape. Provider-aware so\n * callers don't have to thread it through.\n */\nexport function makeProviderError(args: {\n  readonly kind: ProviderErrorKind;\n  readonly provider: LlmProvider;\n  readonly message: string;\n  readonly status?: number;\n  readonly retryAfterSec?: number;\n}): ProviderError {\n  const out: ProviderError = {\n    kind: args.kind,\n    provider: args.provider,\n    message: args.message,\n    ...(args.status !== undefined ? { status: args.status } : {}),\n    ...(args.retryAfterSec !== undefined\n      ? { retryAfterSec: args.retryAfterSec }\n      : {}),\n  };\n  return out;\n}\n\n/**\n * Map an HTTP status code to the canonical error kind. Adapters\n * call this from `mapError` after they've classified the failure as\n * \"the provider returned a status we understand\". Network / abort /\n * pre-flight live outside this mapping.\n */\nexport function statusToErrorKind(status: number): ProviderErrorKind {\n  if (status === 401) return 'unauthorized';\n  if (status === 403) return 'forbidden';\n  if (status === 429) return 'rate-limited';\n  if (status >= 500 && status < 600) return 'server-error';\n  if (status >= 400 && status < 500) return 'client-error';\n  return 'unknown';\n}\n\n/**\n * Default `validateConfig` implementation. Concrete adapters\n * compose this and add their own provider-specific checks on top.\n *\n * Catches the two universal failures: missing key + missing model.\n * Returns `{ok: true}` when both are present.\n *\n * The model-id check is defense-in-depth — typed `LlmRoute` callers\n * cannot construct a route with an empty model string, but the\n * adapter still validates at runtime in case the request crossed an\n * untyped JSON boundary (e.g. deserialized from a wire format).\n */\nexport function defaultValidateConfig(\n  provider: LlmProvider,\n  request: Pick<ProviderRequest, 'apiKey' | 'route'>,\n): ProviderValidation {\n  if (!request.apiKey || request.apiKey.length === 0) {\n    return {\n      ok: false,\n      error: makeProviderError({\n        kind: 'no-credentials',\n        provider,\n        message: `${provider}: no API key supplied`,\n      }),\n    };\n  }\n  if (!request.route?.model || request.route.model.length === 0) {\n    return {\n      ok: false,\n      error: makeProviderError({\n        kind: 'client-error',\n        provider,\n        message: `${provider}: model id is required`,\n      }),\n    };\n  }\n  return { ok: true };\n}\n"]}
+{"version":3,"sources":["../src/provider-adapter.ts"],"names":[],"mappings":";AA+PO,SAAS,kBAAkB,IAAA,EAMhB;AAChB,EAAA,MAAM,GAAA,GAAqB;AAAA,IACzB,MAAM,IAAA,CAAK,IAAA;AAAA,IACX,UAAU,IAAA,CAAK,QAAA;AAAA,IACf,SAAS,IAAA,CAAK,OAAA;AAAA,IACd,GAAI,KAAK,MAAA,KAAW,MAAA,GAAY,EAAE,MAAA,EAAQ,IAAA,CAAK,MAAA,EAAO,GAAI,EAAC;AAAA,IAC3D,GAAI,KAAK,aAAA,KAAkB,MAAA,GACvB,EAAE,aAAA,EAAe,IAAA,CAAK,aAAA,EAAc,GACpC;AAAC,GACP;AACA,EAAA,OAAO,GAAA;AACT;AAQO,SAAS,kBAAkB,MAAA,EAAmC;AACnE,EAAA,IAAI,MAAA,KAAW,KAAK,OAAO,cAAA;AAC3B,EAAA,IAAI,MAAA,KAAW,KAAK,OAAO,WAAA;AAC3B,EAAA,IAAI,MAAA,KAAW,KAAK,OAAO,cAAA;AAC3B,EAAA,IAAI,MAAA,IAAU,GAAA,IAAO,MAAA,GAAS,GAAA,EAAK,OAAO,cAAA;AAC1C,EAAA,IAAI,MAAA,IAAU,GAAA,IAAO,MAAA,GAAS,GAAA,EAAK,OAAO,cAAA;AAC1C,EAAA,OAAO,SAAA;AACT;AAcO,SAAS,qBAAA,CACd,UACA,OAAA,EACoB;AACpB,EAAA,IAAI,CAAC,OAAA,CAAQ,MAAA,IAAU,OAAA,CAAQ,MAAA,CAAO,WAAW,CAAA,EAAG;AAClD,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,OAAO,iBAAA,CAAkB;AAAA,QACvB,IAAA,EAAM,gBAAA;AAAA,QACN,QAAA;AAAA,QACA,OAAA,EAAS,GAAG,QAAQ,CAAA,qBAAA;AAAA,OACrB;AAAA,KACH;AAAA,EACF;AACA,EAAA,IAAI,CAAC,QAAQ,KAAA,EAAO,KAAA,IAAS,QAAQ,KAAA,CAAM,KAAA,CAAM,WAAW,CAAA,EAAG;AAC7D,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,OAAO,iBAAA,CAAkB;AAAA,QACvB,IAAA,EAAM,cAAA;AAAA,QACN,QAAA;AAAA,QACA,OAAA,EAAS,GAAG,QAAQ,CAAA,sBAAA;AAAA,OACrB;AAAA,KACH;AAAA,EACF;AACA,EAAA,OAAO,EAAE,IAAI,IAAA,EAAK;AACpB","file":"provider-adapter.js","sourcesContent":["/**\n * Provider adapter contract — the narrow surface every concrete LLM\n * provider client (Anthropic, Google, OpenAI, OpenRouter, Bedrock)\n * implements.\n *\n * **Real role:** a provider-agnostic one-shot LLM caller for\n * lightweight callers that need a single `complete()` round-trip — NOT\n * a generation harness. The primary consumer is the negotiator's LLM\n * seam (`@ggui-ai/mcp-server`'s `llm-backed-negotiator.ts`, via\n * {@link selectAdapter} from `./providers/index.js`); other lightweight\n * one-shot callers use it the same way. It is explicitly NOT part of\n * the generation dispatch path: `createUiGenerator()` accepts no\n * adapter option, and generation-call 429 retry/backoff lives entirely\n * in `harness/llm-router.ts`'s `apiCall()` — a separate retry story for\n * a separate call shape (an agentic SDK loop, not a single completion).\n *\n * The contract is deliberately defined independently of concrete\n * adapters so:\n *\n *   - Adapter implementations can be written against a stable surface —\n *     every concrete adapter MUST pass\n *     {@link providerAdapterContract} or it isn't a `ProviderAdapter`.\n *   - Downstream one-shot callers build against ONE structured failure\n *     shape ({@link ProviderError}) instead of inventing per-provider\n *     error UX.\n *   - The negotiator + cache layers can branch on\n *     `error.kind === 'rate-limited'` etc. without parsing strings.\n *\n * **Scope:**\n *\n *   - Defines the interface, the response shape, the error shape,\n *     and a contract test runner that asserts every adapter\n *     satisfies the seam.\n *   - Does NOT call any LLM. The contract is structural; this\n *     package's own tests exercise the runner against a deterministic\n *     fixture adapter (`provider-adapter-mock.test-util.ts`).\n *\n * **Design choices, locked:**\n *\n *   - One discriminated `ProviderError.kind` union, not per-provider\n *     subclasses. Every provider's raw error funnels through\n *     `mapError` into one of these kinds. Callers branch on `kind`.\n *   - Every error carries `provider` + `message`; transport-shaped\n *     errors carry `status`; backoff-shaped errors carry\n *     `retryAfterSec`. Optional fields don't appear when they don't\n *     apply (no `status: undefined` noise in serialized logs).\n *   - `validateConfig` is synchronous + does NO I/O. It catches the\n *     \"operator never configured the provider\" case (missing key,\n *     malformed model id) before we attempt a network call.\n *   - `complete` is the single-completion seam. Streaming, tool\n *     calling, function calling, and harness retry land in higher\n *     layers — adapters stay narrow.\n */\nimport type { LlmProvider, LlmRoute } from '@ggui-ai/protocol';\n\n/**\n * One LLM completion request as the adapter sees it. Plain data so\n * tests can construct it without DI.\n *\n * `route` is a discriminated `LlmRoute` — `(provider, model)` typed\n * together so the model id is structurally constrained to its\n * provider's namespace (per the `MODELS` registry in\n * `@ggui-ai/protocol/types/llm-route`). This makes the #22 / #42 bug\n * class — passing a LiteLLM-prefixed `'anthropic/claude-haiku-4-5'`\n * where Anthropic expected the wire id `'claude-haiku-4-5-20251001'` —\n * a compile error at every adapter call site. The adapter reads the\n * wire-canonical string off `request.route.model` and passes it\n * verbatim to the provider SDK; no transformation step exists to\n * forget.\n */\nexport interface ProviderRequest {\n  /** API key. Resolved upstream by `@ggui-ai/cli/byok-resolver`. */\n  readonly apiKey: string;\n  /**\n   * Discriminated `(provider, model)` route. `route.model` is the\n   * wire-canonical id the provider's API expects — adapters pass it\n   * verbatim with no stripping or remapping.\n   */\n  readonly route: LlmRoute;\n  /** System prompt text. Adapter wires it into the provider's slot. */\n  readonly systemPrompt: string;\n  /** User prompt text. */\n  readonly userPrompt: string;\n  /**\n   * Optional cap on output tokens. Adapters MUST honor when the\n   * provider supports it; when absent, adapters use the provider\n   * default.\n   */\n  readonly maxTokens?: number;\n  /**\n   * Optional cancellation. Adapters MUST forward into the provider\n   * SDK's abort surface and reject with `ProviderError{kind:'aborted'}`\n   * when fired.\n   */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Successful provider response, normalized.\n *\n * Tool-calling output, multi-turn dialogue, structured-output\n * coercion all land in higher layers — this contract intentionally\n * stays narrow: text + usage + finish reason. The harness layer\n * composes adapters into multi-turn loops.\n */\nexport interface ProviderResponse {\n  /** The completion text returned by the provider. */\n  readonly text: string;\n  /** Token usage, per-call. Required — adapters synthesize 0 if the\n   *  provider didn't report it (and document that in their adapter). */\n  readonly usage: {\n    readonly inputTokens: number;\n    readonly outputTokens: number;\n  };\n  /**\n   * Why the model stopped. Mapped through a normalized union so\n   * callers don't have to know each provider's vocabulary.\n   *\n   *   - `'stop'`         model emitted EOS / stop sequence\n   *   - `'length'`       hit `maxTokens` or provider context limit\n   *   - `'content-filter'` provider safety filter intervened\n   *   - `'other'`        anything else (provider-specific reason)\n   */\n  readonly finishReason: 'stop' | 'length' | 'content-filter' | 'other';\n}\n\n/**\n * The structured failure contract. Every concrete adapter's\n * `mapError` MUST funnel raw provider errors into this shape so\n * downstream code branches on `kind`, not on string parsing.\n *\n * Discriminator + optional carriers:\n *\n *   - `'no-credentials'`   — no key supplied (pre-flight failure;\n *                            usually surfaced by `validateConfig`,\n *                            not `mapError`).\n *   - `'unauthorized'`     — provider returned 401. Key invalid /\n *                            revoked / wrong type.\n *   - `'forbidden'`        — provider returned 403. Quota exhausted,\n *                            org-level block, model not allowed for\n *                            this key. (Distinct from 401 because\n *                            \"rotate the key\" doesn't help.)\n *   - `'rate-limited'`     — provider returned 429. Carries\n *                            `retryAfterSec` when the provider\n *                            advertised one (`Retry-After` header).\n *   - `'server-error'`     — provider returned 5xx. Retryable.\n *   - `'client-error'`     — provider returned other 4xx. Usually\n *                            non-retryable (bad model id, malformed\n *                            request).\n *   - `'network'`          — TCP-level failure, DNS, EAI_AGAIN, etc.\n *                            No `status`. Retryable.\n *   - `'invalid-response'` — provider returned 2xx with a body the\n *                            adapter couldn't parse. Bug in the\n *                            adapter or in the provider; treat as\n *                            non-retryable.\n *   - `'aborted'`          — caller aborted via `signal`.\n *   - `'unknown'`          — last-resort bucket. Adapters that hit\n *                            this should be patched to map the\n *                            specific case explicitly.\n */\nexport type ProviderErrorKind =\n  | 'no-credentials'\n  | 'unauthorized'\n  | 'forbidden'\n  | 'rate-limited'\n  | 'server-error'\n  | 'client-error'\n  | 'network'\n  | 'invalid-response'\n  | 'aborted'\n  | 'unknown';\n\nexport interface ProviderError {\n  readonly kind: ProviderErrorKind;\n  readonly provider: LlmProvider;\n  /** Human-readable message. Safe to log; should not contain key\n   *  material — adapters MUST scrub before placing here. */\n  readonly message: string;\n  /** HTTP status when transport-shaped. Absent for pre-flight,\n   *  network, aborted, invalid-response. */\n  readonly status?: number;\n  /**\n   * Seconds to wait before retrying. Set ONLY for `'rate-limited'`\n   * when the provider advertised a `Retry-After` header. Higher-level\n   * retry policy uses this when present; falls back to its own\n   * exponential backoff when absent.\n   */\n  readonly retryAfterSec?: number;\n}\n\n/**\n * Pre-flight config validation. Synchronous, no I/O. Catches:\n *\n *   - missing or empty API key       → no-credentials\n *   - missing or empty model id      → client-error\n *\n * Adapters MAY widen the check with provider-specific rules\n * (e.g. \"openrouter model id MUST contain a `/`\"). Failures\n * surface through the same {@link ProviderError} so callers branch\n * on one union.\n */\nexport type ProviderValidation =\n  | { readonly ok: true }\n  | { readonly ok: false; readonly error: ProviderError };\n\n/**\n * The contract every provider client implements.\n */\nexport interface ProviderAdapter {\n  /** Provider this adapter speaks to. Stable identifier; lets the\n   *  caller route a `ProviderRequest` to the right adapter. */\n  readonly provider: LlmProvider;\n  /**\n   * Pre-flight check. MUST return synchronously and MUST NOT touch\n   * the network. Returns `{ok: true}` when the request is at least\n   * structurally valid; returns `{ok: false, error}` otherwise.\n   */\n  validateConfig(request: Pick<ProviderRequest, 'apiKey' | 'route'>): ProviderValidation;\n  /**\n   * Single-completion call. Resolves with `{ok: true, response}` on\n   * success or `{ok: false, error}` on any failure (network,\n   * provider 4xx/5xx, abort). Implementations MUST:\n   *\n   *   1. Funnel every raw provider error through `mapError`.\n   *   2. NOT throw. The result discriminator IS the error path.\n   *   3. Forward `request.signal` into the provider SDK's abort\n   *      mechanism + return `kind:'aborted'` when fired.\n   */\n  complete(request: ProviderRequest): Promise<ProviderResult>;\n  /**\n   * Map an arbitrary thrown / rejected value into a\n   * {@link ProviderError}. Exposed (not just internal) so test\n   * harnesses + retry policies can normalize errors without going\n   * through `complete`.\n   *\n   * MUST NEVER throw — `mapError(unknown)` is the safety net.\n   */\n  mapError(raw: unknown): ProviderError;\n}\n\n/**\n * Discriminated result of a `complete` call. Mirrors `validateConfig`\n * so callers never have to handle thrown errors from this seam.\n */\nexport type ProviderResult =\n  | { readonly ok: true; readonly response: ProviderResponse }\n  | { readonly ok: false; readonly error: ProviderError };\n\n// ─── Helpers concrete adapters compose with ────────────────────────\n\n/**\n * Build a `ProviderError` of the supplied kind. Centralized so\n * concrete adapters don't drift on field shape. Provider-aware so\n * callers don't have to thread it through.\n */\nexport function makeProviderError(args: {\n  readonly kind: ProviderErrorKind;\n  readonly provider: LlmProvider;\n  readonly message: string;\n  readonly status?: number;\n  readonly retryAfterSec?: number;\n}): ProviderError {\n  const out: ProviderError = {\n    kind: args.kind,\n    provider: args.provider,\n    message: args.message,\n    ...(args.status !== undefined ? { status: args.status } : {}),\n    ...(args.retryAfterSec !== undefined\n      ? { retryAfterSec: args.retryAfterSec }\n      : {}),\n  };\n  return out;\n}\n\n/**\n * Map an HTTP status code to the canonical error kind. Adapters\n * call this from `mapError` after they've classified the failure as\n * \"the provider returned a status we understand\". Network / abort /\n * pre-flight live outside this mapping.\n */\nexport function statusToErrorKind(status: number): ProviderErrorKind {\n  if (status === 401) return 'unauthorized';\n  if (status === 403) return 'forbidden';\n  if (status === 429) return 'rate-limited';\n  if (status >= 500 && status < 600) return 'server-error';\n  if (status >= 400 && status < 500) return 'client-error';\n  return 'unknown';\n}\n\n/**\n * Default `validateConfig` implementation. Concrete adapters\n * compose this and add their own provider-specific checks on top.\n *\n * Catches the two universal failures: missing key + missing model.\n * Returns `{ok: true}` when both are present.\n *\n * The model-id check is defense-in-depth — typed `LlmRoute` callers\n * cannot construct a route with an empty model string, but the\n * adapter still validates at runtime in case the request crossed an\n * untyped JSON boundary (e.g. deserialized from a wire format).\n */\nexport function defaultValidateConfig(\n  provider: LlmProvider,\n  request: Pick<ProviderRequest, 'apiKey' | 'route'>,\n): ProviderValidation {\n  if (!request.apiKey || request.apiKey.length === 0) {\n    return {\n      ok: false,\n      error: makeProviderError({\n        kind: 'no-credentials',\n        provider,\n        message: `${provider}: no API key supplied`,\n      }),\n    };\n  }\n  if (!request.route?.model || request.route.model.length === 0) {\n    return {\n      ok: false,\n      error: makeProviderError({\n        kind: 'client-error',\n        provider,\n        message: `${provider}: model id is required`,\n      }),\n    };\n  }\n  return { ok: true };\n}\n"]}

package/dist/providers/index.d.ts

@@ -1,5 +1,4 @@
 import { ProviderAdapter } from '../provider-adapter.js';
-import { AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
 import { LlmProvider } from '@ggui-ai/mcp-server-core';
 import '@ggui-ai/protocol';
 
@@ -72,95 +71,36 @@ interface OpenRouterAdapterOptions {
 declare function createOpenRouterAdapter(options?: OpenRouterAdapterOptions): ProviderAdapter;
 
 /**
- * Concrete AWS Bedrock `ProviderAdapter` — invokes Anthropic Claude
- * models on Bedrock via the official `@anthropic-ai/bedrock-sdk`
- * package. IAM-based auth (no API key in flight); the AWS credential
- * chain (IRSA pod token / `~/.aws/credentials` / env vars) supplies
- * SigV4 signatures automatically.
- *
- * ## 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
- * 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
- * provider API key in a secrets store and lazily fetching it on first
- * render — works but adds operational surface (a seed ceremony,
- * key-rotation discipline, a misconfig mode where the secret is
- * empty); Bedrock removes all of it.
- *
- * ## Wire shape
- *
- * The Bedrock SDK's `client.messages.create(...)` mirrors the direct
- * Anthropic API surface 1:1 — same request body fields (`model`,
- * `max_tokens`, `system`, `messages`), same response shape (`content[]`
- * with `{type:'text', text}` blocks, `stop_reason`, `usage`). Both
- * adapters therefore share ONE success-envelope parser —
- * {@link parseAnthropicMessagesResponse} in `./anthropic-wire.ts`.
- * Streaming is supported by the SDK
- * (`client.messages.stream(...)` returns an async iterable) but this
- * adapter uses the non-streaming `create(...)` call to match the
- * single-completion {@link ProviderAdapter} contract; higher layers
- * (`UiGenerator`) compose multi-turn loops above the seam.
- *
- * ## Auth — no API key in `ProviderRequest`
- *
- * The {@link ProviderAdapter} contract types `ProviderRequest.apiKey`
- * as a required string because direct API providers need it on the
- * wire. Bedrock doesn't — the SDK signs requests with AWS credentials
- * resolved at process boot. Two compatible options were considered:
- *
- *   1. Add an `auth: 'apiKey' | 'iam'` discriminator to
- *      `ProviderAdapter` + thread it through every adapter.
- *   2. Override `validateConfig` so this adapter accepts (and ignores)
- *      whatever the caller puts in `apiKey` — `'iam'` / sentinel /
- *      empty string all pass.
- *
- * Option 2 wins on cost: ZERO callers, contract, or tests change.
- * Callers pass a sentinel (e.g. `'bedrock-iam'`) so the model-id
- * check still gates on a non-empty value. Future work could add the
- * discriminator if a third auth mode (e.g. cross-account assume-role)
- * lands.
- *
- * ## Model IDs — pass-through
- *
- * Bedrock and the direct Anthropic API use OVERLAPPING but DISTINCT
- * model id namespaces:
- *
- *   - Direct API: `claude-haiku-4-5`, `claude-opus-4-7`, etc.
- *   - Bedrock foundation models: `anthropic.claude-sonnet-4-6`
- *   - Bedrock cross-region inference profiles: `us.anthropic.claude-haiku-4-5-20251001-v1:0`
- *
- * The adapter passes whatever `request.model` contains straight to
- * Bedrock — translation lives in the caller (model picker / deployment
- * config). Supply a Bedrock foundation-model or inference-profile id,
- * not a direct-API model name.
- *
- * ## Failure mapping
- *
- * The bedrock-sdk throws `APIError` subclasses (`AuthenticationError`,
- * `PermissionDeniedError`, `RateLimitError`, `InternalServerError`,
- * etc.) that all carry a numeric `.status` property. We classify them
- * by structural duck-typing (`typeof err.status === 'number'`) rather
- * than `instanceof Anthropic.APIError` because pnpm hoisting often
- * resolves multiple `@anthropic-ai/sdk` versions across the workspace
- * — the bedrock-sdk's nested SDK and ui-gen's direct SDK can diverge,
- * and `instanceof` then silently returns false for valid errors.
- * Duck-typing on `.status` is robust to that drift and matches the
- * SDK's documented API contract (every subclass exposes `.status`).
- *
- * Transport-shaped errors (`APIConnectionError`, `APIUserAbortError`)
- * carry NO status — they fall through to {@link classifyFetchError}
- * for the standard `network` / `aborted` mapping.
- *
- * AWS-specific failure modes (`AccessDeniedException` — wrong IAM
- * grants; `ThrottlingException` — Bedrock rate limit;
- * `ValidationException` — bad model id) all surface as `APIError`
- * subclasses in the SDK, distinguished by `.status` (403 / 429 / 400
- * respectively).
+ * Which Bedrock endpoint a model id resolves to. The namespaces are
+ * disjoint (see the docstring above), so the shape of the id fully
+ * determines the endpoint — no configuration knob needed.
  */
-
+type BedrockEndpoint = 'runtime' | 'mantle';
+/**
+ * Structural slice of the two SDK clients the adapter actually drives —
+ * the seam that lets tests inject a stub without standing up a real
+ * AWS client. Both `AnthropicBedrock` and `AnthropicBedrockMantle`
+ * satisfy it (the adapter's single-completion contract only ever calls
+ * non-streaming `messages.create`; the response is parsed from
+ * `unknown` by `parseAnthropicMessagesResponse`, so the SDK's
+ * version-volatile `Message` type is deliberately not part of the
+ * seam).
+ */
+interface BedrockMessagesClient {
+    readonly messages: {
+        create(body: {
+            model: string;
+            max_tokens: number;
+            system?: string;
+            messages: Array<{
+                role: 'user';
+                content: string;
+            }>;
+        }, options?: {
+            signal?: AbortSignal;
+        }): Promise<unknown>;
+    };
+}
 /**
  * Constructor options for the Bedrock adapter.
  *
@@ -181,19 +121,22 @@ interface BedrockAdapterOptions {
     readonly region?: string;
     /**
      * Optional client factory override — used by tests to inject a
-     * mock or stub `AnthropicBedrock` client without actually hitting
-     * AWS. Production callers leave this unset; the adapter constructs
-     * the real client lazily on first `complete(...)` call.
+     * mock or stub client without actually hitting AWS. Called with the
+     * endpoint the request's model id routed to (`'runtime'` →
+     * `AnthropicBedrock`, `'mantle'` → `AnthropicBedrockMantle`).
+     * Production callers leave this unset; the adapter constructs the
+     * real client lazily on first `complete(...)` call per endpoint.
      */
-    readonly clientFactory?: (region: string) => AnthropicBedrock;
+    readonly clientFactory?: (region: string, endpoint: BedrockEndpoint) => BedrockMessagesClient;
 }
 /**
  * Construct an AWS Bedrock provider adapter.
  *
  * 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).
  */
 declare function createBedrockAdapter(options?: BedrockAdapterOptions): ProviderAdapter;
 
@@ -204,6 +147,15 @@ declare function createBedrockAdapter(options?: BedrockAdapterOptions): Provider
  * 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
@@ -214,15 +166,18 @@ declare function createBedrockAdapter(options?: BedrockAdapterOptions): Provider
  * 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):

package/dist/providers/index.js

@@ -1,4 +1,4 @@
-import { AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
+import { AnthropicBedrockMantle, AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
 
 // src/provider-adapter.ts
 function makeProviderError(args) {
@@ -609,14 +609,19 @@ function createOpenRouterAdapter(options = {}) {
 }
 var PROVIDER5 = "bedrock";
 var DEFAULT_MAX_TOKENS2 = 4096;
+function bedrockEndpointFor(model) {
+  return model.startsWith("anthropic.") ? "mantle" : "runtime";
+}
 function createBedrockAdapter(options = {}) {
   const region = options.region ?? process.env["AWS_REGION"] ?? "us-east-1";
-  const clientFactory = options.clientFactory ?? ((r) => new AnthropicBedrock({ awsRegion: r }));
-  let cachedClient = null;
-  function getClient() {
-    if (cachedClient) return cachedClient;
-    cachedClient = clientFactory(region);
-    return cachedClient;
+  const clientFactory = options.clientFactory ?? ((r, endpoint) => endpoint === "mantle" ? new AnthropicBedrockMantle({ awsRegion: r }) : new AnthropicBedrock({ awsRegion: r }));
+  const cachedClients = {};
+  function getClient(endpoint) {
+    const cached = cachedClients[endpoint];
+    if (cached) return cached;
+    const created = clientFactory(region, endpoint);
+    cachedClients[endpoint] = created;
+    return created;
   }
   function mapError(raw) {
     if (raw && typeof raw === "object" && "status" in raw) {
@@ -667,7 +672,7 @@ function createBedrockAdapter(options = {}) {
           error: classifyFetchError(null, PROVIDER5, request.signal)
         };
       }
-      const client = getClient();
+      const client = getClient(bedrockEndpointFor(request.route.model));
       let raw;
       try {
         raw = await client.messages.create(