@ggui-ai/ui-gen 0.24.0 → 0.26.0

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

@@ -1,265 +0,0 @@
-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).
-     *
-     * Capability is the ROUTER's: Anthropic Opus 4.7+ and the 5-family
-     * (`claude-opus-4-7*`, `claude-fable-5*`, `claude-opus-5*`,
-     * `claude-sonnet-5*`, incl. Bedrock ids) return HTTP 400 on a
-     * non-default `temperature`/`top_p`/`top_k`, so the Anthropic adapter
-     * STRIPS the value for those ids (one log line naming model + param)
-     * and reports the effective sampling on `LLMResponse.sampling`. Callers
-     * keep expressing intent; disclosure reads the applied value.
-     */
-    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;
-        /**
-         * Anthropic-only (ggui#1185): run on the machine's own Claude Code
-         * LOGIN instead of a key — the route decision `auth: 'claude-code-login'`
-         * lands here, and `createAgent` / `createVisionAgent` select
-         * `ClaudeCodeLoginAgent` (one `query()` per call) instead of the raw
-         * API client. Every agent the harness builds — coding, evaluation,
-         * visual judge — takes the same decision. Off unless set; a real key
-         * never coexists with it (the router refuses a non-anthropic route).
-         */
-        readonly claudeCodeLogin?: 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;
-}
-/**
- * What sampling the provider ACTUALLY received for a text call — so a
- * caller that asked for `temperature: 0` (a disclosed reproducibility
- * property, e.g. the benchmark judge panel) can record the effective
- * value instead of the requested one. `'provider-default'` means no
- * temperature reached the provider: either the caller passed none, or
- * the adapter stripped it because the model rejects sampling params
- * (Anthropic Opus 4.7+ / 5-family → HTTP 400 on non-default
- * `temperature`/`top_p`/`top_k`); `strippedReason` names the second case.
- */
-interface AppliedSampling {
-    readonly temperature: number | 'provider-default';
-    readonly strippedReason?: string;
-}
-interface LLMResponse {
-    text: string;
-    inputTokens: number;
-    outputTokens: number;
-    /**
-     * Effective sampling for this call (see {@link AppliedSampling}).
-     * Every provider's `callText` sets it; absent only on paths that
-     * predate the field — treat absence as unknown, never as "as
-     * requested".
-     */
-    sampling?: AppliedSampling;
-}
-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;
-    /** Prompt-cache reads summed over the loop's turns, when the provider reports them (absent = unreported, never zero). */
-    cacheReadTokens?: number;
-}
-interface LLMToolCall {
-    /** Provider-specific call ID (for sendToolResult) */
-    id?: string;
-    name: string;
-    input: JsonObject;
-}
-interface LLMToolCallResponse {
-    toolCalls: LLMToolCall[];
-    inputTokens: number;
-    outputTokens: number;
-    /**
-     * The tool-choice mode the provider ACTUALLY received. Callers ask
-     * for `'required'` (Anthropic `tool_choice: any`); Claude Fable 5.1 and
-     * Opus 5.5 reject forced tool choice with HTTP 400, so the Anthropic
-     * and OpenRouter adapters downgrade to `'auto'` for those families and
-     * report it here. A
-     * downgraded call may legitimately return zero tool calls — the
-     * evaluator's `criteriaCoverage` records that as `skipped`, never as
-     * a pass. Absent = predates the field (treat as unknown).
-     */
-    appliedToolChoice?: 'required' | 'auto';
-    /**
-     * 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 };