@steve31415/baselib 2.4.3 → 3.0.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/auth.d.ts

@@ -3,11 +3,20 @@ import type { Logger } from './log-core.js';
 import { ServiceCaller, S2sOptions } from './s2s.js';
 export declare const DEFAULT_AUTH_URL = "https://auth.apps.snewman.net";
 export declare const SESSION_COOKIE = "pw_session";
+/** The `code` in a 403 JSON body when a signed-in user is refused by the
+ *  app's userAccess policy (as opposed to any other 403). */
+export declare const ACCESS_DENIED_CODE = "app_access_denied";
+/** A user's fleet role, assigned in auth2's users table. */
+export type UserRole = 'owner' | 'invited';
+/** Which signed-in users an app admits. 'owner' (the default): only the
+ *  fleet owner(s). 'invited': any active fleet user. */
+export type UserAccessPolicy = 'owner' | 'invited';
 export interface AuthedUser {
     type: 'user';
     email: string;
     name?: string;
     userId?: string;
+    role: UserRole;
 }
 export type Identity = AuthedUser | ServiceCaller;
 declare module 'hono' {
@@ -22,16 +31,20 @@ export interface RequireIdentityOptions extends S2sOptions {
     /** Injectable for tests (defaults to global fetch). */
     whoamiFetch?: typeof fetch;
     logger?: Logger;
-    /** Distinguishes API requests (401) from page requests (redirect).
-     *  Default: path starts with /api/ or client prefers JSON. */
+    /** Distinguishes API requests (401/403 JSON) from page requests (redirect
+     *  / denial page). Default: path starts with /api/ or client prefers JSON. */
     isApiRequest?: (c: Context) => boolean;
     cacheTtl?: {
         hitMs?: number;
         missMs?: number;
     };
+    /** Which signed-in users this app admits. Default 'owner': only users
+     *  whose auth2 role is owner. Pass 'invited' only for an app that is
+     *  multi-user by design, and say so in its SPEC. Applies to browser
+     *  sessions and the test bypass alike; service callers are governed by
+     *  grants, not by this. */
+    userAccess?: UserAccessPolicy;
 }
-export declare function requireIdentity(opts: RequireIdentityOptions): import("hono").MiddlewareHandler<any, string, {}, (Response & import("hono").TypedResponse<undefined, 302, "redirect">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 401 | 403 | 429, "json">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 503, "json">)>;
+/** The one place the policy is evaluated. */
+export declare function userAllowed(policy: UserAccessPolicy, user: Pick<AuthedUser, 'role'>): boolean;
+export declare function requireIdentity(opts: RequireIdentityOptions): import("hono").MiddlewareHandler<any, string, {}, Response>;

package/dist/auth.js

@@ -1,27 +1,49 @@
-// Identity middleware for consuming apps (design §3.4).
+// Identity middleware for consuming apps (design §3.4; per-app access:
+// ~/migration/research/per-app-access-design.md).
 //
 // Resolves who is calling, in order:
 //   1. Test bypass (AUTH_MODE=test): X-Test-S2S-Caller → service caller;
-//      X-Test-User header or TEST_USER env → user. Credential verification is
-//      bypassed; authorization (grants, app-level user checks) still runs.
+//      X-Test-User header or TEST_USER env → user, with the fleet role from
+//      X-Test-User-Role / TEST_USER_ROLE (default 'invited'). Credential
+//      verification is bypassed; authorization (grants, the userAccess
+//      policy, app-level checks) still runs.
 //   2. Authorization: Bearer → service-to-service OIDC (s2s.ts).
 //   3. pw_session cookie → whoami call to the auth service, cached
 //      in-instance (10 min hits / 30 s misses — the old-world numbers).
 //
+// Then the user-access policy: by default an app admits only users whose
+// auth2 role is 'owner'; `userAccess: 'invited'` admits any active fleet
+// user. Being on the fleet sign-in allowlist never grants access by itself,
+// so a port that forgets the question is closed, not open. Service callers
+// are governed by grants, not by this policy.
+//
 // Unauthenticated: APIs get 401 JSON, pages redirect to the auth service's
-// login with a return URL. Auth-service *failures* (network, 5xx) return 503
-// and never redirect — a redirect on failure loops forever (old-world lesson).
+// login with a return URL. Denied users get 403 (JSON with a stable `code`
+// on APIs, a plain "not enabled" page otherwise). Auth-service *failures*
+// (network, 5xx, a whoami answer with no role) return 503 and never
+// redirect — a redirect on failure loops forever (old-world lesson).
 import { createHash } from 'node:crypto';
 import { createMiddleware } from 'hono/factory';
 import { authMode } from './config.js';
 import { RateLimiter, resolveS2sCaller } from './s2s.js';
 export const DEFAULT_AUTH_URL = 'https://auth.apps.snewman.net';
 export const SESSION_COOKIE = 'pw_session';
+/** The `code` in a 403 JSON body when a signed-in user is refused by the
+ *  app's userAccess policy (as opposed to any other 403). */
+export const ACCESS_DENIED_CODE = 'app_access_denied';
+/** The one place the policy is evaluated. */
+export function userAllowed(policy, user) {
+    return policy === 'invited' || user.role === 'owner';
+}
+function parseRole(value) {
+    return value === 'owner' || value === 'invited' ? value : undefined;
+}
 export function requireIdentity(opts) {
     const authUrl = (opts.authUrl ?? DEFAULT_AUTH_URL).replace(/\/$/, '');
     const whoamiFetch = opts.whoamiFetch ?? fetch;
     const hitMs = opts.cacheTtl?.hitMs ?? 600_000;
     const missMs = opts.cacheTtl?.missMs ?? 30_000;
+    const policy = opts.userAccess ?? 'owner';
     const limiter = new RateLimiter(opts.rateLimitPerMin ?? 600);
     const cache = new Map();
     const isApi = opts.isApiRequest ??
@@ -37,17 +59,33 @@ export function requireIdentity(opts) {
         }
         return c.redirect(`${authUrl}/login?redirect=${encodeURIComponent(returnUrl)}`);
     };
+    // WARN, not ERROR: a fleet user opening an owner-only app is the policy
+    // working as designed (an s2s grant denial is ERROR because it usually
+    // means a missing grant during development).
+    const accessDenied = (c, user) => {
+        opts.logger?.warn('user access denied', { email: user.email, policy, path: c.req.path });
+        c.header('cache-control', 'no-store');
+        if (isApi(c)) {
+            return c.json({ error: 'not enabled for this account', code: ACCESS_DENIED_CODE, email: user.email }, 403);
+        }
+        return c.html(accessDeniedPage({ host: c.req.header('host') ?? 'This app', email: user.email, authUrl }), 403);
+    };
     return createMiddleware(async (c, next) => {
+        const admit = (user) => {
+            if (!userAllowed(policy, user))
+                return accessDenied(c, user);
+            c.set('identity', user);
+            c.set('user', user);
+            return next();
+        };
         // Test-mode user bypass (service-caller test bypass is handled by
         // resolveS2sCaller below, so both paths stay testable).
         if (authMode() === 'test' && !c.req.header('x-test-s2s-caller')) {
             const email = c.req.header('x-test-user') ?? process.env.TEST_USER;
             if (!email)
                 return unauthenticated(c);
-            const user = { type: 'user', email };
-            c.set('identity', user);
-            c.set('user', user);
-            return next();
+            const role = parseRole(c.req.header('x-test-user-role') ?? process.env.TEST_USER_ROLE) ?? 'invited';
+            return admit({ type: 'user', email, role });
         }
         // Service-to-service path.
         if (c.req.header('authorization') || c.req.header('x-test-s2s-caller')) {
@@ -72,9 +110,7 @@ export function requireIdentity(opts) {
         if (cached && cached.expires > Date.now()) {
             if (!cached.user)
                 return unauthenticated(c);
-            c.set('identity', cached.user);
-            c.set('user', cached.user);
-            return next();
+            return admit(cached.user);
         }
         let res;
         try {
@@ -86,11 +122,17 @@ export function requireIdentity(opts) {
         }
         if (res.ok) {
             const data = (await res.json());
-            const user = { type: 'user', email: data.email, name: data.name, userId: data.user_id };
+            const role = parseRole(data.role);
+            if (!role) {
+                // An auth service from before roles existed (a rollback), or a
+                // protocol change: a fault, not an "invited" answer. Fail closed,
+                // loudly, and without caching so recovery is instant.
+                opts.logger?.error('whoami answer has no role', { email: data.email, role: data.role });
+                return c.json({ error: 'auth service unavailable' }, 503);
+            }
+            const user = { type: 'user', email: data.email, name: data.name, userId: data.user_id, role };
             cache.set(key, { expires: Date.now() + hitMs, user });
-            c.set('identity', user);
-            c.set('user', user);
-            return next();
+            return admit(user);
         }
         if (res.status === 401) {
             cache.set(key, { expires: Date.now() + missMs });
@@ -100,3 +142,35 @@ export function requireIdentity(opts) {
         return c.json({ error: 'auth service unavailable' }, 503);
     });
 }
+// The fleet-wide "not enabled" page, in the auth service's plain style so
+// every app shows the same thing. Carries nothing but the request's host,
+// the user's address, and the configured auth URL.
+function accessDeniedPage(p) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Not enabled — Plasticine</title>
+<style>
+  :root { --accent: #23a55a; --ink: #1a1a1a; --muted: #6b7280; }
+  body { font-family: system-ui, sans-serif; color: var(--ink); background: #fff;
+         display: flex; min-height: 100vh; margin: 0; align-items: center; justify-content: center; }
+  main { text-align: center; padding: 2rem; max-width: 32rem; }
+  h1 { font-size: 1.4rem; margin-bottom: 0.5rem; }
+  h1 .dot { color: var(--accent); }
+  p.muted { color: var(--muted); font-size: 0.95rem; }
+  a { color: var(--accent); }
+</style>
+</head>
+<body><main>
+<h1>Plasticine<span class="dot">.</span></h1>
+<p><strong>${escapeHtml(p.host)}</strong> is not enabled for your account.</p>
+<p class="muted">You are signed in as ${escapeHtml(p.email)}. To use a different account,
+<a href="${escapeHtml(p.authUrl)}/">sign out</a> first.</p>
+</main></body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+}

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;