@steve31415/baselib 2.4.3 → 3.0.0

package/dist/llm/providers/anthropic.js

@@ -0,0 +1,122 @@
+import { LLMError } from '../types.js';
+/** Classify Anthropic's `stop_reason` (already lowercase from the API). */
+function classifyFinish(stopReason) {
+    switch (stopReason) {
+        case 'refusal': return 'declined';
+        case 'max_tokens':
+        case 'model_context_window_exceeded': return 'truncated';
+        case 'end_turn':
+        case 'stop_sequence':
+        case 'tool_use':
+        case 'pause_turn': return 'complete';
+        default: return 'other';
+    }
+}
+export const anthropicProvider = {
+    name: 'anthropic',
+    async complete(request) {
+        const endpoint = 'https://api.anthropic.com/v1/messages';
+        request.logger?.info('llm.request', {
+            provider: 'anthropic', model: request.apiModelId, endpoint,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+        const startTime = Date.now();
+        const body = {
+            model: request.apiModelId,
+            max_tokens: request.maxTokens,
+            messages: [{ role: 'user', content: request.prompt }],
+        };
+        // Some models (Opus 4.7+, Sonnet 5, Fable 5) reject `temperature`
+        // outright with a 400 — omit the field entirely rather than sending it.
+        if (request.supportsTemperature) {
+            body.temperature = request.temperature;
+        }
+        // Output-effort control (Sonnet 4.6+/Opus 4.6+/Sonnet 5/Opus 5): lower
+        // effort trades thoroughness for latency/cost. Only ever set here when the
+        // registry marks the model effort-capable (gated in complete.ts).
+        if (request.effort) {
+            body.output_config = { effort: request.effort };
+        }
+        if (request.systemPrompt) {
+            body.system = request.cacheSystemPrompt
+                ? [{ type: 'text', text: request.systemPrompt, cache_control: { type: 'ephemeral' } }]
+                : request.systemPrompt;
+        }
+        // JSON schema: use tool_use to get structured output
+        if (request.jsonSchema) {
+            body.tools = [{
+                    name: request.jsonSchema.name,
+                    description: `Generate structured output matching the ${request.jsonSchema.name} schema`,
+                    input_schema: request.jsonSchema.schema,
+                }];
+            body.tool_choice = { type: 'tool', name: request.jsonSchema.name };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), request.timeoutMs);
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': request.apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error && err.name === 'AbortError'
+                ? `Anthropic API timeout after ${request.timeoutMs}ms`
+                : `Anthropic API network error: ${err instanceof Error ? err.message : String(err)}`;
+            throw new LLMError({
+                message,
+                provider: 'anthropic',
+                model: request.apiModelId,
+                isRetryable: true,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new LLMError({
+                message: `Anthropic API error: ${response.status} - ${errorText.slice(0, 500)}`,
+                provider: 'anthropic',
+                model: request.apiModelId,
+                statusCode: response.status,
+                isRetryable: response.status >= 500 || response.status === 429,
+            });
+        }
+        const data = await response.json();
+        const latencyMs = Date.now() - startTime;
+        const outputTokens = data.usage?.output_tokens ?? undefined;
+        const tokensUsed = (data.usage?.input_tokens || 0) + (data.usage?.output_tokens || 0);
+        const cacheReadTokens = data.usage?.cache_read_input_tokens ?? undefined;
+        const cacheCreationTokens = data.usage?.cache_creation_input_tokens ?? undefined;
+        const finishReason = data.stop_reason ?? undefined;
+        let text;
+        let json;
+        if (request.jsonSchema) {
+            const toolUse = data.content?.find((c) => c.type === 'tool_use');
+            json = toolUse?.input;
+            text = json !== undefined ? JSON.stringify(json) : '';
+        }
+        else {
+            text = data.content?.find((c) => c.type === 'text')?.text || '';
+        }
+        request.logger?.info('llm.response', {
+            provider: 'anthropic', model: request.apiModelId,
+            status: response.status, latencyMs, tokensUsed, outputTokens, finishReason,
+            ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}),
+            ...(cacheCreationTokens !== undefined ? { cacheCreationTokens } : {}),
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+        return {
+            text, json, tokensUsed, outputTokens, cacheReadTokens, cacheCreationTokens,
+            finishReason, finishCategory: classifyFinish(finishReason), latencyMs,
+        };
+    },
+};

package/dist/llm/providers/gemini.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderAdapter } from '../types.js';
+export declare const geminiProvider: ProviderAdapter;

package/dist/llm/providers/gemini.js

@@ -0,0 +1,128 @@
+import { LLMError } from '../types.js';
+/** Gemini `finishReason` enum values that mean the model was content-blocked. */
+const GEMINI_DECLINE_REASONS = new Set([
+    'safety', 'recitation', 'prohibited_content', 'blocklist', 'spii', 'image_safety',
+]);
+/** Classify Gemini's `finishReason` (lowercased by the caller). */
+function classifyFinish(finishReason) {
+    if (finishReason === undefined)
+        return 'other';
+    if (GEMINI_DECLINE_REASONS.has(finishReason))
+        return 'declined';
+    if (finishReason === 'max_tokens')
+        return 'truncated';
+    if (finishReason === 'stop')
+        return 'complete';
+    return 'other';
+}
+/** Recursively strip fields that Gemini's API doesn't support (e.g. additionalProperties). */
+function stripUnsupportedSchemaFields(schema) {
+    if (Array.isArray(schema)) {
+        return schema.map(stripUnsupportedSchemaFields);
+    }
+    if (schema !== null && typeof schema === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(schema)) {
+            if (key === 'additionalProperties')
+                continue;
+            result[key] = stripUnsupportedSchemaFields(value);
+        }
+        return result;
+    }
+    return schema;
+}
+export const geminiProvider = {
+    name: 'gemini',
+    async complete(request) {
+        const endpoint = `https://generativelanguage.googleapis.com/v1beta/models/${request.apiModelId}:generateContent`;
+        request.logger?.info('llm.request', {
+            provider: 'gemini', model: request.apiModelId, endpoint,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+        const startTime = Date.now();
+        const generationConfig = {
+            maxOutputTokens: request.maxTokens,
+        };
+        // Contract parity with the Anthropic/OpenAI adapters: omit `temperature`
+        // for models whose registry entry says they reject it.
+        if (request.supportsTemperature) {
+            generationConfig.temperature = request.temperature;
+        }
+        if (request.jsonSchema) {
+            generationConfig.responseMimeType = 'application/json';
+            generationConfig.responseSchema = stripUnsupportedSchemaFields(request.jsonSchema.schema);
+        }
+        // Gemini thinking models reason before answering; the reasoning tokens
+        // count against maxOutputTokens. Capping the thinking budget reserves
+        // headroom for the visible response so a long reasoning pass can't
+        // truncate it. Models with a thinking floor (registry
+        // `supportsThinkingBudgetZero: false`) reject an explicit 0 budget with a
+        // 400 — for those a 0 means "as little thinking as possible", which their
+        // default already is, so the config is omitted entirely.
+        if (request.thinkingBudget !== undefined
+            && (request.thinkingBudget !== 0 || request.supportsThinkingBudgetZero)) {
+            generationConfig.thinkingConfig = { thinkingBudget: request.thinkingBudget };
+        }
+        const body = {
+            contents: [{ parts: [{ text: request.prompt }] }],
+            generationConfig,
+        };
+        if (request.systemPrompt) {
+            body.systemInstruction = { parts: [{ text: request.systemPrompt }] };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), request.timeoutMs);
+        let response;
+        try {
+            response = await fetch(`${endpoint}?key=${request.apiKey}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error && err.name === 'AbortError'
+                ? `Gemini API timeout after ${request.timeoutMs}ms`
+                : `Gemini API network error: ${err instanceof Error ? err.message : String(err)}`;
+            throw new LLMError({
+                message,
+                provider: 'gemini',
+                model: request.apiModelId,
+                isRetryable: true,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new LLMError({
+                message: `Gemini API error: ${response.status} - ${errorText.slice(0, 500)}`,
+                provider: 'gemini',
+                model: request.apiModelId,
+                statusCode: response.status,
+                isRetryable: response.status >= 500 || response.status === 429,
+            });
+        }
+        const data = await response.json();
+        const latencyMs = Date.now() - startTime;
+        const text = data.candidates?.[0]?.content?.parts?.[0]?.text || '';
+        const tokensUsed = data.usageMetadata?.totalTokenCount || 0;
+        const outputTokens = data.usageMetadata?.candidatesTokenCount ?? undefined;
+        const finishReason = data.candidates?.[0]?.finishReason?.toLowerCase() ?? undefined;
+        let json;
+        if (request.jsonSchema) {
+            try {
+                json = JSON.parse(text);
+            }
+            catch { /* leave as text */ }
+        }
+        request.logger?.info('llm.response', {
+            provider: 'gemini', model: request.apiModelId,
+            status: response.status, latencyMs, tokensUsed, outputTokens, finishReason,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+        return { text, json, tokensUsed, outputTokens, finishReason, finishCategory: classifyFinish(finishReason), latencyMs };
+    },
+};

package/dist/llm/providers/index.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderAdapter, ProviderName } from '../types.js';
+export declare const providers: Record<ProviderName, ProviderAdapter>;

package/dist/llm/providers/index.js

@@ -0,0 +1,8 @@
+import { anthropicProvider } from './anthropic.js';
+import { geminiProvider } from './gemini.js';
+import { openaiProvider } from './openai.js';
+export const providers = {
+    anthropic: anthropicProvider,
+    gemini: geminiProvider,
+    openai: openaiProvider,
+};

package/dist/llm/providers/openai.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderAdapter } from '../types.js';
+export declare const openaiProvider: ProviderAdapter;

package/dist/llm/providers/openai.js

@@ -0,0 +1,183 @@
+import { LLMError } from '../types.js';
+/** True when a JSON-schema `type` value denotes (or includes) an object. */
+function isObjectSchema(type) {
+    return type === 'object' || (Array.isArray(type) && type.includes('object'));
+}
+/**
+ * Widen a property schema so OpenAI strict mode permits `null`. OpenAI has no
+ * notion of an optional property (every property must be `required`), so an
+ * originally-optional field is emulated by making its type nullable — the model
+ * may then emit `null` to mean "absent". A nullable enum must also list `null`
+ * among its allowed values, or the union with `null` is unsatisfiable.
+ */
+function makeNullable(propSchema) {
+    if (propSchema === null || typeof propSchema !== 'object' || Array.isArray(propSchema)) {
+        return propSchema;
+    }
+    const s = propSchema;
+    const type = s.type;
+    let nextType;
+    if (typeof type === 'string') {
+        nextType = type === 'null' ? type : [type, 'null'];
+    }
+    else if (Array.isArray(type)) {
+        nextType = type.includes('null') ? type : [...type, 'null'];
+    }
+    else {
+        // No concrete `type` to widen (e.g. anyOf/$ref) — leave as-is.
+        return s;
+    }
+    const result = { ...s, type: nextType };
+    if (Array.isArray(s.enum) && !s.enum.includes(null)) {
+        result.enum = [...s.enum, null];
+    }
+    return result;
+}
+/**
+ * Transform a portable JSON schema into the shape OpenAI's strict Structured
+ * Outputs mode requires: every object must set `additionalProperties: false`
+ * and list ALL of its properties in `required`. Callers author one portable
+ * schema (which also works on Anthropic's tool_use and Gemini's responseSchema,
+ * both of which tolerate missing `additionalProperties` and optional fields);
+ * this keeps the OpenAI-specific dialect local to this adapter, mirroring the
+ * Gemini adapter's own `stripUnsupportedSchemaFields`. Returns a deep copy — the
+ * caller's schema object is never mutated (it is reused across failover attempts).
+ */
+function toStrictSchema(node) {
+    if (Array.isArray(node))
+        return node.map(toStrictSchema);
+    if (node === null || typeof node !== 'object')
+        return node;
+    const obj = node;
+    const originalRequired = new Set(Array.isArray(obj.required)
+        ? obj.required.filter((k) => typeof k === 'string')
+        : []);
+    // Deep-copy + recurse into every child first so nested objects/arrays are
+    // normalized before we widen originally-optional properties above them.
+    const out = {};
+    for (const [key, value] of Object.entries(obj)) {
+        out[key] = toStrictSchema(value);
+    }
+    const properties = out.properties;
+    if (isObjectSchema(out.type) && properties !== null && typeof properties === 'object') {
+        const propMap = properties;
+        const keys = Object.keys(propMap);
+        for (const key of keys) {
+            if (!originalRequired.has(key)) {
+                propMap[key] = makeNullable(propMap[key]);
+            }
+        }
+        out.required = keys;
+        out.additionalProperties = false;
+    }
+    return out;
+}
+/** Classify OpenAI's `finish_reason` (already lowercase from the API). */
+function classifyFinish(finishReason) {
+    switch (finishReason) {
+        case 'content_filter': return 'declined';
+        case 'length': return 'truncated';
+        case 'stop':
+        case 'tool_calls':
+        case 'function_call': return 'complete';
+        default: return 'other';
+    }
+}
+export const openaiProvider = {
+    name: 'openai',
+    async complete(request) {
+        const endpoint = 'https://api.openai.com/v1/chat/completions';
+        request.logger?.info('llm.request', {
+            provider: 'openai', model: request.apiModelId, endpoint,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+        const startTime = Date.now();
+        const messages = [];
+        if (request.systemPrompt) {
+            messages.push({ role: 'system', content: request.systemPrompt });
+        }
+        messages.push({ role: 'user', content: request.prompt });
+        const body = {
+            model: request.apiModelId,
+            max_completion_tokens: request.maxTokens,
+            messages,
+        };
+        // Reasoning models (the gpt-5.6 family) reject any non-default
+        // `temperature` with 400 unsupported_value — omit it per the registry flag.
+        if (request.supportsTemperature) {
+            body.temperature = request.temperature;
+        }
+        if (request.jsonSchema) {
+            body.response_format = {
+                type: 'json_schema',
+                json_schema: {
+                    name: request.jsonSchema.name,
+                    // Normalize the portable schema into OpenAI's strict dialect
+                    // (additionalProperties:false everywhere, all properties required,
+                    // originally-optional ones made nullable). Without this, strict mode
+                    // rejects the request with a 400 and this provider is dead as a
+                    // failover target for any schema using optional fields.
+                    schema: toStrictSchema(request.jsonSchema.schema),
+                    strict: true,
+                },
+            };
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), request.timeoutMs);
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${request.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error && err.name === 'AbortError'
+                ? `OpenAI API timeout after ${request.timeoutMs}ms`
+                : `OpenAI API network error: ${err instanceof Error ? err.message : String(err)}`;
+            throw new LLMError({
+                message,
+                provider: 'openai',
+                model: request.apiModelId,
+                isRetryable: true,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new LLMError({
+                message: `OpenAI API error: ${response.status} - ${errorText.slice(0, 500)}`,
+                provider: 'openai',
+                model: request.apiModelId,
+                statusCode: response.status,
+                isRetryable: response.status >= 500 || response.status === 429,
+            });
+        }
+        const data = await response.json();
+        const latencyMs = Date.now() - startTime;
+        const text = data.choices?.[0]?.message?.content || '';
+        const outputTokens = data.usage?.completion_tokens ?? undefined;
+        const tokensUsed = (data.usage?.prompt_tokens || 0) + (data.usage?.completion_tokens || 0);
+        const finishReason = data.choices?.[0]?.finish_reason ?? undefined;
+        let json;
+        if (request.jsonSchema) {
+            try {
+                json = JSON.parse(text);
+            }
+            catch { /* leave as text */ }
+        }
+        request.logger?.info('llm.response', {
+            provider: 'openai', model: request.apiModelId,
+            status: response.status, latencyMs, tokensUsed, outputTokens, finishReason,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+        return { text, json, tokensUsed, outputTokens, finishReason, finishCategory: classifyFinish(finishReason), latencyMs };
+    },
+};

package/dist/llm/types.d.ts

@@ -0,0 +1,203 @@
+import type { Logger } from '../log-core.js';
+/** Supported LLM provider names. */
+export type ProviderName = 'anthropic' | 'gemini' | 'openai';
+/** API keys for each provider. Only keys for available providers need to be set. */
+export interface ApiKeys {
+    anthropic?: string;
+    gemini?: string;
+    openai?: string;
+}
+/** JSON schema definition for structured output. */
+export interface JsonSchema {
+    /** Schema name (used by OpenAI and Anthropic). */
+    name: string;
+    /** JSON Schema object. */
+    schema: Record<string, unknown>;
+}
+/** Request to llmComplete(). */
+export interface LLMRequest {
+    /** Model name from the registry (e.g. 'claude-sonnet-4-6', 'gemini-2.5-flash'). */
+    model: string;
+    /** The user prompt. */
+    prompt: string;
+    /** Optional system prompt. */
+    systemPrompt?: string;
+    /** Max output tokens. Default: 2048. */
+    maxTokens?: number;
+    /** Temperature. Default: 0.3. */
+    temperature?: number;
+    /** If provided, requests structured JSON output matching this schema. */
+    jsonSchema?: JsonSchema;
+    /** API keys for available providers. */
+    apiKeys: ApiKeys;
+    /** Logger instance for structured logging. */
+    logger?: Logger;
+    /** Timeout per provider attempt in ms. Default: 60000. */
+    timeoutMs?: number;
+    /**
+     * Cap on reasoning/thinking tokens for models that support hidden reasoning
+     * (currently Gemini 2.5 family). Reasoning tokens are charged against the
+     * same budget as output tokens, so when thinking is unbounded it can starve
+     * the visible response and cause mid-string truncation. Setting this
+     * reserves headroom for the response. Ignored by providers that don't
+     * expose a thinking budget.
+     */
+    thinkingBudget?: number;
+    /**
+     * Output-effort level for models that support Anthropic's `output_config.
+     * effort` (registry `supportsEffort`). Lower effort trades thoroughness for
+     * latency/cost. Currently honored on Anthropic models only; when a call
+     * fails over to another provider the fallback runs at its own defaults.
+     */
+    effort?: 'low' | 'medium' | 'high';
+    /**
+     * Optional short identifier for the calling feature (e.g. 'video_classify',
+     * 'message_prioritize', 'log_summary'). Included in llm.request and
+     * llm.response log meta so cost/usage reports can attribute spend to the
+     * specific feature driving the call. No behavioral effect.
+     */
+    callSite?: string;
+    /**
+     * If true, request Anthropic prompt caching for the system prompt. The
+     * library wraps the system string in a content-block array with
+     * `cache_control: { type: 'ephemeral' }`. Non-Anthropic providers ignore
+     * this flag (they have no equivalent caching mechanism here). Has no
+     * effect when `systemPrompt` is empty.
+     */
+    cacheSystemPrompt?: boolean;
+}
+/**
+ * Semantic classification of a provider's finish reason, normalized across
+ * providers so the failover loop needs no provider-specific knowledge:
+ * - `complete`  — the model finished normally (incl. tool/function calls).
+ * - `truncated` — output was cut off by the token budget. The caller's concern;
+ *   does NOT trigger failover, since a re-run would likely truncate too.
+ * - `declined`  — the model actively refused / was content-filtered. Triggers
+ *   failover to the next provider, which may have different policies.
+ * - `other`     — anything unrecognized (including a missing finish reason).
+ *
+ * Each provider adapter maps its native finish reason to one of these, keeping
+ * provider-specific vocabulary local to the adapter that owns it.
+ */
+export type FinishCategory = 'complete' | 'truncated' | 'declined' | 'other';
+/** Successful response from llmComplete(). */
+export interface LLMResponse {
+    /** The text output (or JSON stringified if jsonSchema was used). */
+    text: string;
+    /** Parsed JSON output when jsonSchema was requested. */
+    json?: unknown;
+    /** The provider that produced this response. */
+    provider: ProviderName;
+    /** The API model ID that produced this response. */
+    model: string;
+    /** Total tokens used (input + output). */
+    tokensUsed: number;
+    /** Output tokens only, when the provider reports them separately. */
+    outputTokens?: number;
+    /**
+     * Prompt-cache tokens read from the cache (Anthropic only, when caching is
+     * used). These are billed at a reduced rate vs. regular input tokens.
+     */
+    cacheReadTokens?: number;
+    /**
+     * Prompt-cache tokens written to the cache (Anthropic only, when caching is
+     * used). These are billed at a premium over regular input tokens.
+     */
+    cacheCreationTokens?: number;
+    /**
+     * Normalized finish reason from the provider, when available.
+     * Lowercased common values: 'stop', 'max_tokens', 'tool_use', 'content_filter',
+     * 'safety', 'length', 'other'. Provider-specific strings may also appear.
+     */
+    finishReason?: string;
+    /** Semantic classification of {@link finishReason}; see {@link FinishCategory}. */
+    finishCategory?: FinishCategory;
+    /** Wall-clock latency of the successful call in ms. */
+    latencyMs: number;
+    /** True if the primary model failed and a fallback was used. */
+    failedOver: boolean;
+    /** Details of each failed attempt before the successful one. */
+    failedAttempts: FailedAttempt[];
+}
+/** Details of a failed provider attempt. */
+export interface FailedAttempt {
+    provider: ProviderName;
+    model: string;
+    error: string;
+    /** True when this attempt failed because the model declined (vs. an infra error). */
+    declined?: boolean;
+}
+/** Error thrown when an LLM provider call fails. */
+export declare class LLMError extends Error {
+    provider: ProviderName;
+    model: string;
+    statusCode?: number;
+    isRetryable: boolean;
+    /**
+     * True when this error is the model actively declining to respond (safety
+     * refusal / content filter) rather than an infrastructure failure. On the
+     * terminal "all providers failed" error, true only when *every* attempt was
+     * a decline. Callers can use this to classify severity — e.g. log WARN, not
+     * ERROR, since an across-the-board decline is an expected external outcome,
+     * not a defect.
+     */
+    declined: boolean;
+    constructor(opts: {
+        message: string;
+        provider: ProviderName;
+        model: string;
+        statusCode?: number;
+        isRetryable: boolean;
+        declined?: boolean;
+    });
+}
+export interface ProviderAdapter {
+    name: ProviderName;
+    complete(request: ProviderCallRequest): Promise<ProviderCallResponse>;
+}
+export interface ProviderCallRequest {
+    apiModelId: string;
+    prompt: string;
+    systemPrompt?: string;
+    maxTokens: number;
+    temperature: number;
+    /**
+     * Whether the target model accepts the `temperature` parameter, per the
+     * MODEL_REGISTRY entry's `supportsTemperature` flag. Providers that always
+     * accept temperature can ignore this; providers with models that reject it
+     * must omit `temperature` from the request body when this is `false`.
+     */
+    supportsTemperature: boolean;
+    /**
+     * Whether the target model accepts `thinkingBudget: 0`, per the registry
+     * entry's `supportsThinkingBudgetZero` flag. When `false`, the Gemini
+     * adapter omits thinkingConfig for a 0 budget instead of sending it (the
+     * model would 400); non-zero budgets pass through unchanged.
+     */
+    supportsThinkingBudgetZero: boolean;
+    jsonSchema?: JsonSchema;
+    apiKey: string;
+    logger?: Logger;
+    timeoutMs: number;
+    thinkingBudget?: number;
+    /** Effort level, pre-gated by the registry's `supportsEffort` (absent when unsupported). */
+    effort?: 'low' | 'medium' | 'high';
+    callSite?: string;
+    cacheSystemPrompt?: boolean;
+}
+export interface ProviderCallResponse {
+    text: string;
+    json?: unknown;
+    tokensUsed: number;
+    /** Output tokens only, when the provider reports them separately. */
+    outputTokens?: number;
+    /** Prompt-cache read tokens (Anthropic, when caching is used). */
+    cacheReadTokens?: number;
+    /** Prompt-cache creation tokens (Anthropic, when caching is used). */
+    cacheCreationTokens?: number;
+    /** Normalized finish reason (lowercased common values where known). */
+    finishReason?: string;
+    /** Semantic classification of {@link finishReason}; see {@link FinishCategory}. */
+    finishCategory?: FinishCategory;
+    latencyMs: number;
+}

package/dist/llm/types.js

@@ -0,0 +1,25 @@
+/** Error thrown when an LLM provider call fails. */
+export class LLMError extends Error {
+    provider;
+    model;
+    statusCode;
+    isRetryable;
+    /**
+     * True when this error is the model actively declining to respond (safety
+     * refusal / content filter) rather than an infrastructure failure. On the
+     * terminal "all providers failed" error, true only when *every* attempt was
+     * a decline. Callers can use this to classify severity — e.g. log WARN, not
+     * ERROR, since an across-the-board decline is an expected external outcome,
+     * not a defect.
+     */
+    declined;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'LLMError';
+        this.provider = opts.provider;
+        this.model = opts.model;
+        this.statusCode = opts.statusCode;
+        this.isRetryable = opts.isRetryable;
+        this.declined = opts.declined ?? false;
+    }
+}