@steve31415/baselib 2.4.2 → 2.5.0

package/README.md

@@ -6,7 +6,7 @@ What it provides and why: `docs/SPEC.md`. How it's put together:
 `~/migration/research/base-services-design.md` (step 5).
 
 Server subpath exports: `config`, `log`, `auth`, `s2s`, `db`, `http`, `sync`,
-and `app-update`. Browser exports: `log-browser`, `rum`, `sync-browser`, and
+`app-update`, and `llm`. Browser exports: `log-browser`, `rum`, `sync-browser`, and
 `app-update-browser`.
 
 `sync` provides the Postgres event-log and server protocol primitives;
@@ -19,6 +19,10 @@ adapter, transport/auth-state integration, and update hooks. These modules do
 not decide authentication or ownership, contain app domain logic, or act as a
 generic Yjs or service-worker coordinator.
 
+`llm` is the fleet's one LLM client (Anthropic, Gemini, OpenAI): model
+registry, automatic cross-provider failover, portable JSON-schema output.
+Usage guide: `~/plasticine-way/docs/LLM.md`.
+
 Bins: `check-test-owners` — the fleet's structural test-coverage gate; every
 app runs it from `npm run verify`.
 

package/dist/deploy/deploy.js

@@ -209,7 +209,10 @@ export async function runDeploy(options) {
                 await evidence.save(`gate-${index}.log`, result.stdout + result.stderr);
                 timer.record(`gate:${gate}`, Date.now() - gateStart);
                 if (result.code !== 0) {
-                    const tail = (result.stderr.trim() || result.stdout.trim()).slice(-1500);
+                    // Quote the tail of BOTH streams: test runners put the failing spec on
+                    // stdout and only build/server noise on stderr, so stderr alone can
+                    // hide which test failed. stderr last, so it survives the cut.
+                    const tail = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join('\n').slice(-1500);
                     throw new Error(`gate failed: ${gate}\n${tail}`);
                 }
                 log(`gate passed: ${gate}`);

package/dist/llm/complete.d.ts

@@ -0,0 +1,11 @@
+import type { LLMRequest, LLMResponse } from './types.js';
+/**
+ * Call an LLM with automatic failover to alternative providers.
+ *
+ * Tries the requested model first. On any error, falls back to equivalent
+ * models from other providers. Skips providers whose API key is not set.
+ * Logs WARN on every failover attempt.
+ *
+ * Only models in the MODEL_REGISTRY are accepted. All calls get failover.
+ */
+export declare function llmComplete(request: LLMRequest): Promise<LLMResponse>;

package/dist/llm/complete.js

@@ -0,0 +1,145 @@
+import { LLMError } from './types.js';
+import { MODEL_REGISTRY, THINKING_HEADROOM_WARN_TOKENS } from './models.js';
+import { providers } from './providers/index.js';
+const DEFAULT_MAX_TOKENS = 2048;
+const DEFAULT_TEMPERATURE = 0.3;
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Call an LLM with automatic failover to alternative providers.
+ *
+ * Tries the requested model first. On any error, falls back to equivalent
+ * models from other providers. Skips providers whose API key is not set.
+ * Logs WARN on every failover attempt.
+ *
+ * Only models in the MODEL_REGISTRY are accepted. All calls get failover.
+ */
+export async function llmComplete(request) {
+    const entry = MODEL_REGISTRY[request.model];
+    if (!entry) {
+        throw new LLMError({
+            message: `Unknown model: ${request.model}. Known models: ${Object.keys(MODEL_REGISTRY).join(', ')}`,
+            provider: 'anthropic',
+            model: request.model,
+            isRetryable: false,
+        });
+    }
+    const maxTokens = request.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const temperature = request.temperature ?? DEFAULT_TEMPERATURE;
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // Models that think by default spend reasoning tokens out of the same
+    // `maxTokens` budget as the visible response, so a budget carried over from a
+    // non-thinking model can be consumed by reasoning and truncate the body —
+    // fatal when `jsonSchema` is in play, since a cut-off body will not parse.
+    // Truncation must never be silent (PW LLM.md), so flag the risk up front
+    // rather than leaving the caller to diagnose it from finishReason after the
+    // fact.
+    if (entry.thinksByDefault && maxTokens < THINKING_HEADROOM_WARN_TOKENS) {
+        request.logger?.warn('llm.thinking_budget_tight', {
+            model: request.model,
+            maxTokens,
+            recommendedMinimum: THINKING_HEADROOM_WARN_TOKENS,
+            hasJsonSchema: request.jsonSchema !== undefined,
+            ...(request.callSite ? { callSite: request.callSite } : {}),
+        });
+    }
+    // Build the ordered list of models to try: primary + fallbacks
+    const modelsToTry = [request.model, ...entry.fallbacks];
+    const failedAttempts = [];
+    for (const modelName of modelsToTry) {
+        const modelEntry = MODEL_REGISTRY[modelName];
+        if (!modelEntry)
+            continue;
+        const apiKey = request.apiKeys[modelEntry.provider];
+        if (!apiKey) {
+            request.logger?.debug('llm.skip_provider', {
+                model: modelName, provider: modelEntry.provider, reason: 'no API key',
+            });
+            continue;
+        }
+        const provider = providers[modelEntry.provider];
+        try {
+            const result = await provider.complete({
+                apiModelId: modelEntry.apiModelId,
+                prompt: request.prompt,
+                systemPrompt: request.systemPrompt,
+                maxTokens,
+                temperature,
+                supportsTemperature: modelEntry.supportsTemperature ?? true,
+                supportsThinkingBudgetZero: modelEntry.supportsThinkingBudgetZero ?? true,
+                effort: modelEntry.supportsEffort ? request.effort : undefined,
+                jsonSchema: request.jsonSchema,
+                apiKey,
+                logger: request.logger,
+                timeoutMs,
+                thinkingBudget: request.thinkingBudget,
+                callSite: request.callSite,
+                cacheSystemPrompt: request.cacheSystemPrompt,
+            });
+            // A model declining (safety refusal / content filter) comes back as a
+            // normal HTTP 200, so it never throws on its own. Treat it as a failed
+            // attempt so the loop fails over to the next provider, which may have
+            // different policies. Truncation and other non-declines are NOT retried
+            // here — those are the caller's concern (a re-run would likely truncate
+            // too). See FinishCategory.
+            if (result.finishCategory === 'declined') {
+                throw new LLMError({
+                    message: `Model declined to respond (finishReason: ${result.finishReason ?? 'unknown'})`,
+                    provider: modelEntry.provider,
+                    model: modelEntry.apiModelId,
+                    isRetryable: true,
+                    declined: true,
+                });
+            }
+            // If we failed over, log a final summary
+            if (failedAttempts.length > 0) {
+                request.logger?.warn('llm.failover_succeeded', {
+                    originalModel: request.model,
+                    fallbackModel: modelName,
+                    fallbackProvider: modelEntry.provider,
+                    attemptsBeforeSuccess: failedAttempts.length,
+                });
+            }
+            return {
+                text: result.text,
+                json: result.json,
+                provider: modelEntry.provider,
+                model: modelEntry.apiModelId,
+                tokensUsed: result.tokensUsed,
+                outputTokens: result.outputTokens,
+                cacheReadTokens: result.cacheReadTokens,
+                cacheCreationTokens: result.cacheCreationTokens,
+                finishReason: result.finishReason,
+                finishCategory: result.finishCategory,
+                latencyMs: result.latencyMs,
+                failedOver: failedAttempts.length > 0,
+                failedAttempts,
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            failedAttempts.push({
+                provider: modelEntry.provider,
+                model: modelEntry.apiModelId,
+                error: errorMessage,
+                declined: err instanceof LLMError && err.declined,
+            });
+            request.logger?.warn('llm.failover_attempt', {
+                failedModel: modelName,
+                failedProvider: modelEntry.provider,
+                error: errorMessage,
+                attemptNumber: failedAttempts.length,
+                nextModel: modelsToTry[failedAttempts.length] ?? 'none',
+            });
+        }
+    }
+    // All attempts exhausted. If every attempt was a decline (not an infra
+    // failure), mark the terminal error `declined` so callers can treat a
+    // genuinely-unanswerable request as an expected outcome rather than a defect.
+    throw new LLMError({
+        message: `All LLM providers failed for model ${request.model}. Attempts: ${failedAttempts.map((a) => `${a.provider}/${a.model}: ${a.error}`).join('; ')}`,
+        provider: entry.provider,
+        model: entry.apiModelId,
+        isRetryable: false,
+        declined: failedAttempts.length > 0 && failedAttempts.every((a) => a.declined === true),
+    });
+}

package/dist/llm/index.d.ts

@@ -0,0 +1,4 @@
+export { llmComplete } from './complete.js';
+export { MODEL_REGISTRY } from './models.js';
+export type { ModelEntry } from './models.js';
+export { LLMError, type LLMRequest, type LLMResponse, type FailedAttempt, type FinishCategory, type ProviderName, type ApiKeys, type JsonSchema, } from './types.js';

package/dist/llm/index.js

@@ -0,0 +1,10 @@
+// LLM API client with automatic provider failover (Anthropic, Gemini,
+// OpenAI). Ported into baselib from the old-world package
+// @steve31415/llm-failover 1.9.0 (plasticine-apps/llm-failover@95461e2);
+// the one deliberate change is the Logger type, which is baselib's own
+// (log-core.ts) instead of @steve31415/log-logger-ts. Usage guide:
+// ~/plasticine-way/docs/LLM.md.
+// Public API
+export { llmComplete } from './complete.js';
+export { MODEL_REGISTRY } from './models.js';
+export { LLMError, } from './types.js';

package/dist/llm/models.d.ts

@@ -0,0 +1,54 @@
+import type { ProviderName } from './types.js';
+export interface ModelEntry {
+    /** Provider that serves this model. */
+    provider: ProviderName;
+    /** The model ID to send in the API request. */
+    apiModelId: string;
+    /** Fallback models to try (in order) if this model's provider fails. */
+    fallbacks: string[];
+    /**
+     * Whether this model accepts the `temperature` request parameter.
+     * Defaults to `true` when absent. Set `false` for models that reject it
+     * outright (e.g. `400 invalid_request_error: "temperature is deprecated
+     * for this model."` — Anthropic's Opus 4.7+/Sonnet 5/Fable 5 family).
+     */
+    supportsTemperature?: boolean;
+    /**
+     * Whether this model accepts `thinkingBudget: 0` ("disable thinking").
+     * Defaults to `true`. Gemini 3.x models with a thinking floor of `minimal`
+     * or higher reject an explicit 0 budget with a 400; for those the adapter
+     * omits thinkingConfig instead, honoring the caller's intent of "as little
+     * thinking as this model allows".
+     */
+    supportsThinkingBudgetZero?: boolean;
+    /**
+     * Whether this model accepts Anthropic's `output_config.effort` parameter
+     * (verified on Sonnet 5 / Sonnet 4.6 2026-08-10; documented GA on Opus
+     * 4.6+/5). Defaults to `false`; the effort option is dropped for models
+     * without it.
+     */
+    supportsEffort?: boolean;
+    /**
+     * Whether this model performs hidden reasoning when the request omits any
+     * thinking configuration (which this library always does). Defaults to
+     * `false`. Anthropic's Opus 5 is the first model where thinking is on by
+     * default; its reasoning tokens are charged against the same `maxTokens`
+     * budget as the visible response, so a budget sized for a non-thinking model
+     * can be consumed by reasoning and truncate the body mid-token.
+     *
+     * Set this on any model whose default is to think, so llmComplete() can warn
+     * when the caller's output budget leaves no meaningful headroom.
+     */
+    thinksByDefault?: boolean;
+}
+/**
+ * Output budget below which a `thinksByDefault` model is considered at risk of
+ * having its visible response starved by reasoning tokens. Not a hard limit —
+ * llmComplete() only warns, since the right budget is task-specific.
+ */
+export declare const THINKING_HEADROOM_WARN_TOKENS = 4096;
+/**
+ * Model registry. Keys are the user-facing model names passed to llmComplete().
+ * Each entry maps to a provider, API model ID, and ordered fallback list.
+ */
+export declare const MODEL_REGISTRY: Record<string, ModelEntry>;

package/dist/llm/models.js

@@ -0,0 +1,166 @@
+/**
+ * Output budget below which a `thinksByDefault` model is considered at risk of
+ * having its visible response starved by reasoning tokens. Not a hard limit —
+ * llmComplete() only warns, since the right budget is task-specific.
+ */
+export const THINKING_HEADROOM_WARN_TOKENS = 4096;
+/**
+ * Model registry. Keys are the user-facing model names passed to llmComplete().
+ * Each entry maps to a provider, API model ID, and ordered fallback list.
+ */
+export const MODEL_REGISTRY = {
+    // 2026-08 suite refresh: current models are claude-sonnet-5 / claude-opus-5
+    // (Anthropic), the gpt-5.6 sol/terra/luna family (OpenAI), and the Gemini
+    // 3.5/3.6 GA line plus gemini-3.1-pro-preview (Google). Older names stay
+    // registered so existing callers keep working, but no fallback chain routes
+    // through a retiring model: gemini-2.5-pro and gemini-2.5-flash shut down
+    // 2026-10-16, and the gpt-4o snapshots retire from 2026-10 onward.
+    //
+    // The gpt-5.6 family are reasoning models: they reject non-default
+    // `temperature` (400 unsupported_value, verified 2026-08-09) and spend
+    // hidden reasoning tokens billed as output — hence `supportsTemperature:
+    // false` + `thinksByDefault: true` on each. (gpt-5.2 still accepts
+    // temperature; verified the same day.)
+    // --- Fast tier ---
+    'gemini-3.5-flash-lite': {
+        provider: 'gemini',
+        apiModelId: 'gemini-3.5-flash-lite',
+        fallbacks: ['gpt-5.6-luna', 'claude-haiku-4-5'],
+        // Default thinking_level is `minimal` — reasoning overhead is negligible,
+        // so no `thinksByDefault` headroom warning.
+        // Rejects thinkingBudget 0 (400, verified 2026-08-09).
+        supportsThinkingBudgetZero: false,
+    },
+    'gemini-3.6-flash': {
+        provider: 'gemini',
+        apiModelId: 'gemini-3.6-flash',
+        fallbacks: ['gpt-5.6-luna', 'claude-haiku-4-5'],
+        // Thinks by default (thinking_level defaults to `medium`); reasoning
+        // tokens are billed as output and count against maxOutputTokens.
+        thinksByDefault: true,
+        // Rejects thinkingBudget 0 (400, verified 2026-08-09).
+        supportsThinkingBudgetZero: false,
+    },
+    'gpt-5.6-luna': {
+        provider: 'openai',
+        apiModelId: 'gpt-5.6-luna',
+        fallbacks: ['gemini-3.5-flash-lite', 'claude-haiku-4-5'],
+        supportsTemperature: false,
+        thinksByDefault: true,
+    },
+    'claude-haiku-4-5': {
+        provider: 'anthropic',
+        apiModelId: 'claude-haiku-4-5-20251001',
+        fallbacks: ['gemini-3.5-flash-lite', 'gpt-5.6-luna'],
+    },
+    // Retiring 2026-10-16 — migrate callers to gemini-3.5-flash-lite.
+    'gemini-2.5-flash': {
+        provider: 'gemini',
+        apiModelId: 'gemini-2.5-flash',
+        fallbacks: ['gpt-5.6-luna', 'claude-haiku-4-5'],
+    },
+    'gemini-3.1-flash-lite': {
+        provider: 'gemini',
+        apiModelId: 'gemini-3.1-flash-lite',
+        fallbacks: ['claude-sonnet-4-6'],
+    },
+    'gemini-3-flash-preview': {
+        provider: 'gemini',
+        apiModelId: 'gemini-3-flash-preview',
+        fallbacks: ['claude-haiku-4-5', 'gpt-5.6-luna'],
+    },
+    'gpt-4o-mini': {
+        provider: 'openai',
+        apiModelId: 'gpt-4o-mini',
+        fallbacks: ['gemini-3.5-flash-lite', 'claude-haiku-4-5'],
+    },
+    // --- Mid tier ---
+    'claude-sonnet-5': {
+        provider: 'anthropic',
+        supportsEffort: true,
+        apiModelId: 'claude-sonnet-5',
+        fallbacks: ['gpt-5.6-terra', 'gemini-3.1-pro-preview'],
+        // Sonnet 5 rejects `temperature` (like Opus 4.7+/Fable 5). It supports
+        // adaptive thinking but does NOT think when the request omits `thinking`
+        // (verified 2026-08-09: thinking_tokens 0), so no thinksByDefault.
+        supportsTemperature: false,
+    },
+    'gpt-5.6-terra': {
+        provider: 'openai',
+        apiModelId: 'gpt-5.6-terra',
+        fallbacks: ['claude-sonnet-5', 'gemini-3.1-pro-preview'],
+        supportsTemperature: false,
+        thinksByDefault: true,
+    },
+    'claude-sonnet-4-6': {
+        provider: 'anthropic',
+        supportsEffort: true,
+        apiModelId: 'claude-sonnet-4-6',
+        fallbacks: ['gpt-5.6-terra', 'gemini-3.1-pro-preview'],
+    },
+    // Legacy: consumer-retired 2026-02; API snapshots retire 2026-10 onward.
+    // Migrate callers to gpt-5.6-terra (OpenAI's documented replacement).
+    'gpt-4o': {
+        provider: 'openai',
+        apiModelId: 'gpt-4o',
+        fallbacks: ['claude-sonnet-5', 'gemini-3.1-pro-preview'],
+    },
+    // --- Top tier ---
+    'claude-opus-5': {
+        provider: 'anthropic',
+        supportsEffort: true,
+        apiModelId: 'claude-opus-5',
+        fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
+        // Opus 4.7+ rejects `temperature` outright (400 invalid_request_error).
+        supportsTemperature: false,
+        // Unlike Opus 4.6/4.8, Opus 5 thinks by default when the request omits the
+        // `thinking` parameter (as this library does). Reasoning tokens are charged
+        // against `maxTokens` alongside the visible response, so budgets sized for
+        // a non-thinking Opus can truncate — see `thinksByDefault` on ModelEntry.
+        thinksByDefault: true,
+    },
+    'claude-opus-4-8': {
+        provider: 'anthropic',
+        supportsEffort: true,
+        apiModelId: 'claude-opus-4-8',
+        fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
+        // Opus 4.7+ rejects `temperature` outright (400 invalid_request_error).
+        supportsTemperature: false,
+    },
+    'claude-opus-4-6': {
+        provider: 'anthropic',
+        supportsEffort: true,
+        apiModelId: 'claude-opus-4-6',
+        fallbacks: ['gpt-5.6-sol', 'gemini-3.1-pro-preview'],
+    },
+    'gpt-5.6-sol': {
+        provider: 'openai',
+        apiModelId: 'gpt-5.6-sol',
+        fallbacks: ['claude-opus-5', 'gemini-3.1-pro-preview'],
+        supportsTemperature: false,
+        thinksByDefault: true,
+    },
+    'gpt-5.2': {
+        provider: 'openai',
+        apiModelId: 'gpt-5.2',
+        fallbacks: ['claude-opus-5', 'gemini-3.1-pro-preview'],
+    },
+    // Google's best Pro model as of 2026-08 — still Preview-labeled (no GA
+    // Gemini 3.x Pro exists), but the only Pro-class option once 2.5-pro
+    // retires. Accepts the legacy integer thinkingBudget (verified 2026-08-09).
+    'gemini-3.1-pro-preview': {
+        provider: 'gemini',
+        apiModelId: 'gemini-3.1-pro-preview',
+        fallbacks: ['claude-opus-5', 'gpt-5.6-sol'],
+        // Thinks by default (thinking_level defaults to `high`).
+        thinksByDefault: true,
+        // Rejects thinkingBudget 0 (400, verified 2026-08-09).
+        supportsThinkingBudgetZero: false,
+    },
+    // Retiring 2026-10-16 — migrate callers to gemini-3.1-pro-preview.
+    'gemini-2.5-pro': {
+        provider: 'gemini',
+        apiModelId: 'gemini-2.5-pro',
+        fallbacks: ['claude-opus-5', 'gpt-5.6-sol'],
+    },
+};

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

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

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;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -60,6 +60,10 @@
     "./app-update-browser": {
       "types": "./dist/app-update-browser/index.d.ts",
       "default": "./dist/app-update-browser/index.js"
+    },
+    "./llm": {
+      "types": "./dist/llm/index.d.ts",
+      "default": "./dist/llm/index.js"
     }
   },
   "bin": {