@ggui-ai/ui-gen 0.8.0 → 0.9.0

package/dist/llm-router-1TyI0_TV.d.ts

@@ -0,0 +1,156 @@
+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;
+    };
+}
+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'];
+    constructor(routeOverride?: AgentConfig['routeOverride']);
+    protected abstract resolveModel(model: string): string;
+    protected abstract createClient(): Promise<unknown>;
+    protected getClient<T>(): Promise<T>;
+    /** Text-only call — no tools */
+    abstract callText(model: string, systemPrompt: string, userPrompt: string, maxTokens?: number, temperature?: number): Promise<LLMResponse>;
+    /**
+     * Single-turn function calling — returns tool calls without executing them.
+     * Each provider uses its native function/tool calling:
+     *   - Anthropic: tool_use blocks
+     *   - OpenAI: function_call output items
+     *   - Google: functionCall parts
+     * SDK handles JSON escaping — safe for code, diffs, and other content.
+     */
+    abstract callTools(model: string, systemPrompt: string, userPrompt: string, tools: LLMToolDef[], toolChoice?: 'required' | 'auto', 
+    /**
+     * Optional scoped fallback tools. If the primary tools fail with a
+     * transport-class error (e.g. `malformed_tool_call` on Gemini after
+     * retry exhaustion), the provider may retry once with these narrower
+     * tools before throwing. Universal signal — not provider-gated.
+     */
+    scopedTools?: LLMToolDef[]): Promise<LLMToolCallResponse>;
+    /** Multi-turn agentic loop — executes tools internally */
+    abstract callWithTools(model: string, systemPrompt: string, userPrompt: string, tools: LLMTool[], maxTurns: number): Promise<LLMWithToolsResponse>;
+    /**
+     * Pre-warm cache for repeated callTools() calls with the same system prompt + tools.
+     * Override in providers that support server-side context caching (e.g., Google).
+     * No-op by default (Anthropic/OpenAI handle caching automatically per-request).
+     */
+    warmCache(_model: string, _systemPrompt: string, _tools: LLMToolDef[], _toolChoice?: 'required' | 'auto'): Promise<void>;
+    /** Cleanup any cached resources. Call after generation completes. No-op by default. */
+    cleanup(): Promise<void>;
+    /** Reset session state between independent generation runs. */
+    resetSession(): void;
+    /**
+     * Send tool execution results back to the provider to close the API contract.
+     * Call this after executing tools from callTools() and before the next callTools().
+     *
+     * For providers with server-side state (Google, OpenAI), this sends the
+     * function results so the next callTools() can chain properly.
+     * For stateless providers (Anthropic), this is a no-op.
+     *
+     * Override in providers that need it.
+     */
+    sendToolResult(_results: LLMToolResult[]): Promise<void>;
+    /**
+     * Execute an API call. No retry — if it fails, it fails.
+     * Logs the error with provider context and re-throws.
+     */
+    protected apiCall<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Create a fresh agent instance for the given provider.
+ * Each call returns a new instance — no shared state between callers.
+ *
+ * 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, createAgent as a, callLLM as c };

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,11 +121,13 @@ 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.

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(