@celestea/llm 2.7.1

package/dist/factory.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Production provider factory (W511).
+ *
+ * The one place a resolved runtime profile becomes a NETWORK-backed `Llm`:
+ *
+ *   base_url          profile.base_url > CELESTEA_BASE_URL > DEEPSEEK_BASE_URL
+ *                     > https://api.deepseek.com
+ *   api key           env[profile.api_key_env] ONLY (default DEEPSEEK_API_KEY):
+ *                     never a file, never written back, never echoed
+ *   reasoning_effort  profile value, verbatim (free string, never folded)
+ *   max_output_tokens profile value
+ *   timeouts          CELESTEA_LLM_{CONNECT,RESPONSE,STREAM_IDLE}_TIMEOUT_MS
+ *                     > profile key > built-in default (0 disables a stage)
+ *
+ * `context_window_tokens` is not a request field (the engine trims with it); it
+ * is surfaced in `liveLlmView()` so a startup log can report the live window
+ * next to the model.
+ *
+ * `CELESTEA_LLM_MODE` picks live vs offline. This package is network-only, so it
+ * only REPORTS the mode (the deterministic offline seam is host-side, an
+ * injected test seam in apps/studio).
+ */
+import { OpenAiCompatClient } from "./client.js";
+import { type LlmProfile } from "./profile.js";
+import type { EnvLike, TimeoutTiers } from "./timeouts.js";
+/** `live` = the real provider; `offline` = the host's deterministic seam. */
+export declare const LLM_MODE_ENV = "CELESTEA_LLM_MODE";
+/** Base-URL fallback used by the host (wins over DEEPSEEK_BASE_URL). */
+export declare const LLM_BASE_URL_ENV = "CELESTEA_BASE_URL";
+export type LlmMode = "live" | "offline";
+/** The profile subset the live factory consumes. */
+export interface LiveLlmProfile extends LlmProfile {
+    context_window_tokens?: number | null;
+}
+/** Secret-free view of a live adapter (safe to log / serialize). */
+export interface LiveLlmView {
+    mode: LlmMode;
+    model: string;
+    baseUrl: string;
+    reasoningEffort: string | null;
+    maxOutputTokens: number | null;
+    contextWindow: number | null;
+    timeouts: TimeoutTiers;
+    hasApiKey: boolean;
+}
+/**
+ * Read the mode. Absent/blank or "live" = live (the deployment default); only
+ * an explicit "offline" turns the network off. Anything else is a config typo
+ * and fails fast instead of silently reaching (or not reaching) a provider.
+ */
+export declare function resolveLlmMode(env?: EnvLike): LlmMode;
+/** Fill `base_url` from CELESTEA_BASE_URL when the profile leaves it empty. */
+export declare function withBaseUrlFallback(profile?: LiveLlmProfile | null, env?: EnvLike): LiveLlmProfile;
+/** Build the live OpenAI-compatible client behind the `Llm` seam. */
+export declare function createLiveLlm(profile?: LiveLlmProfile | null, env?: EnvLike): OpenAiCompatClient;
+/** Secret-free view of the live configuration (never carries the key). */
+export declare function liveLlmView(profile?: LiveLlmProfile | null, env?: EnvLike, mode?: LlmMode): LiveLlmView;

package/dist/factory.js

@@ -0,0 +1,75 @@
+/**
+ * Production provider factory (W511).
+ *
+ * The one place a resolved runtime profile becomes a NETWORK-backed `Llm`:
+ *
+ *   base_url          profile.base_url > CELESTEA_BASE_URL > DEEPSEEK_BASE_URL
+ *                     > https://api.deepseek.com
+ *   api key           env[profile.api_key_env] ONLY (default DEEPSEEK_API_KEY):
+ *                     never a file, never written back, never echoed
+ *   reasoning_effort  profile value, verbatim (free string, never folded)
+ *   max_output_tokens profile value
+ *   timeouts          CELESTEA_LLM_{CONNECT,RESPONSE,STREAM_IDLE}_TIMEOUT_MS
+ *                     > profile key > built-in default (0 disables a stage)
+ *
+ * `context_window_tokens` is not a request field (the engine trims with it); it
+ * is surfaced in `liveLlmView()` so a startup log can report the live window
+ * next to the model.
+ *
+ * `CELESTEA_LLM_MODE` picks live vs offline. This package is network-only, so it
+ * only REPORTS the mode (the deterministic offline seam is host-side, an
+ * injected test seam in apps/studio).
+ */
+import { OpenAiCompatClient } from "./client.js";
+import { LlmError } from "./errors.js";
+import { resolveClientConfig, tiersFromConfig } from "./profile.js";
+/** `live` = the real provider; `offline` = the host's deterministic seam. */
+export const LLM_MODE_ENV = "CELESTEA_LLM_MODE";
+/** Base-URL fallback used by the host (wins over DEEPSEEK_BASE_URL). */
+export const LLM_BASE_URL_ENV = "CELESTEA_BASE_URL";
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+/**
+ * Read the mode. Absent/blank or "live" = live (the deployment default); only
+ * an explicit "offline" turns the network off. Anything else is a config typo
+ * and fails fast instead of silently reaching (or not reaching) a provider.
+ */
+export function resolveLlmMode(env = process.env) {
+    const raw = (env[LLM_MODE_ENV] ?? "").trim().toLowerCase();
+    if (raw === "" || raw === "live")
+        return "live";
+    if (raw === "offline")
+        return "offline";
+    throw new LlmError(`${LLM_MODE_ENV} must be 'live' or 'offline', got '${raw}'`, "generate");
+}
+/** Fill `base_url` from CELESTEA_BASE_URL when the profile leaves it empty. */
+export function withBaseUrlFallback(profile, env = process.env) {
+    const base = profile ?? {};
+    if (nonEmpty(base.base_url) !== undefined)
+        return base;
+    const fromEnv = nonEmpty(env[LLM_BASE_URL_ENV]);
+    return fromEnv === undefined ? base : { ...base, base_url: fromEnv };
+}
+/** Build the live OpenAI-compatible client behind the `Llm` seam. */
+export function createLiveLlm(profile, env = process.env) {
+    return OpenAiCompatClient.fromProfile(withBaseUrlFallback(profile, env), env);
+}
+/** Secret-free view of the live configuration (never carries the key). */
+export function liveLlmView(profile, env = process.env, mode = resolveLlmMode(env)) {
+    const effective = withBaseUrlFallback(profile, env);
+    const config = resolveClientConfig(effective, env);
+    const window = effective.context_window_tokens;
+    return {
+        mode,
+        model: config.model,
+        baseUrl: config.baseUrl,
+        reasoningEffort: config.reasoningEffort,
+        maxOutputTokens: config.maxOutputTokens,
+        contextWindow: typeof window === "number" && window > 0 ? window : null,
+        // W835 (R3 batch D / P2-1): the view must use the same null-when-disabled
+        // mapping as client.timeouts(), else a disabled stage is printed as "0ms".
+        timeouts: tiersFromConfig(config),
+        hasApiKey: config.apiKey !== "",
+    };
+}

package/dist/fallback-config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Fallback chain configuration (iteration E §4.2.4) — a sidecar, never a profile.
+ *
+ * The chain is read from `<data dir>/fallbacks.json` or from `CELESTEA_LLM_FALLBACKS`
+ * (the same JSON, inline), and the capability is gated by `CELESTEA_LLM_FALLBACK`
+ * (`on|1|true|yes`; **default off** — §4.3 P1, D9). Keeping it here instead of in
+ * `Profile` is deliberate: `Profile` is the frozen 12-key contract, so widening it
+ * would drag `contracts/` and the legacy side along (§4.2.4 "诚实取舍").
+ *
+ * Two disciplines are enforced in code, not in prose:
+ *   - the config records env var NAMES only — a key value can never reach here
+ *     (§4.5 R4-3), and `available()` answers "is the credential present" without
+ *     ever reading a value out of the environment;
+ *   - a chain that is switched on but broken is REPORTED (`problems[]`), never
+ *     silently downgraded to "no fallback" (U7: `enabled:true` must say that a
+ *     target is unusable instead of skipping it quietly).
+ */
+import type { FallbackPolicy, LlmTarget } from "./fallback.js";
+/** `<data dir>/fallbacks.json` (§4.2.4). */
+export declare const FALLBACKS_FILE = "fallbacks.json";
+/** `on|1|true|yes` enables the decorator; anything else (and absent) is OFF. */
+export declare const ENV_FALLBACK_SWITCH = "CELESTEA_LLM_FALLBACK";
+/** The same JSON inline (wins over the file). */
+export declare const ENV_FALLBACKS = "CELESTEA_LLM_FALLBACKS";
+/** The parsed sidecar. `version` is the file's own schema version. */
+export interface FallbackConfig {
+    version: number;
+    /** Config-level switch; the env switch still has to be on as well. */
+    enabled: boolean;
+    targets: LlmTarget[];
+    policy: Partial<FallbackPolicy>;
+    /** `env` | `file` — where the chain came from (diagnostics/statusline). */
+    source: "env" | "file";
+    /** Non-fatal findings (missing key, no targets, …): never silent. */
+    problems: string[];
+}
+/** Is the capability switched on? Default OFF (§4.2.4 / D9). */
+export declare function fallbackEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The configured chain, or null when the switch is off / nothing is configured.
+ * A malformed JSON, a non-object, or a chain with zero targets is a `problem`,
+ * and the caller decides what to report.
+ */
+export declare function loadFallbackConfig(opts: {
+    dataDir?: string | null;
+    env?: NodeJS.ProcessEnv;
+}): FallbackConfig | null;
+/** Parse + validate one config document; unparsable input is a reported problem. */
+export declare function parseConfig(raw: string, source: "env" | "file"): FallbackConfig;
+/**
+ * Credential inventory (U7) — env var NAMES only, never values: a target that
+ * names an `apiKeyEnv` which the process does not define is UNAVAILABLE, and the
+ * caller must report it instead of dropping the target silently.
+ */
+export declare function targetAvailability(targets: readonly LlmTarget[], env?: NodeJS.ProcessEnv): Array<{
+    name: string;
+    model: string;
+    available: boolean;
+    missingEnv: string | null;
+}>;
+/** The `problems[]` of a chain, including the credentials it cannot use (U7). */
+export declare function configProblems(config: FallbackConfig, env?: NodeJS.ProcessEnv): string[];

package/dist/fallback-config.js

@@ -0,0 +1,151 @@
+/**
+ * Fallback chain configuration (iteration E §4.2.4) — a sidecar, never a profile.
+ *
+ * The chain is read from `<data dir>/fallbacks.json` or from `CELESTEA_LLM_FALLBACKS`
+ * (the same JSON, inline), and the capability is gated by `CELESTEA_LLM_FALLBACK`
+ * (`on|1|true|yes`; **default off** — §4.3 P1, D9). Keeping it here instead of in
+ * `Profile` is deliberate: `Profile` is the frozen 12-key contract, so widening it
+ * would drag `contracts/` and the legacy side along (§4.2.4 "诚实取舍").
+ *
+ * Two disciplines are enforced in code, not in prose:
+ *   - the config records env var NAMES only — a key value can never reach here
+ *     (§4.5 R4-3), and `available()` answers "is the credential present" without
+ *     ever reading a value out of the environment;
+ *   - a chain that is switched on but broken is REPORTED (`problems[]`), never
+ *     silently downgraded to "no fallback" (U7: `enabled:true` must say that a
+ *     target is unusable instead of skipping it quietly).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** `<data dir>/fallbacks.json` (§4.2.4). */
+export const FALLBACKS_FILE = "fallbacks.json";
+/** `on|1|true|yes` enables the decorator; anything else (and absent) is OFF. */
+export const ENV_FALLBACK_SWITCH = "CELESTEA_LLM_FALLBACK";
+/** The same JSON inline (wins over the file). */
+export const ENV_FALLBACKS = "CELESTEA_LLM_FALLBACKS";
+/** Is the capability switched on? Default OFF (§4.2.4 / D9). */
+export function fallbackEnabled(env = process.env) {
+    const raw = (env[ENV_FALLBACK_SWITCH] ?? "").trim().toLowerCase();
+    return ["on", "1", "true", "yes"].includes(raw);
+}
+/**
+ * The configured chain, or null when the switch is off / nothing is configured.
+ * A malformed JSON, a non-object, or a chain with zero targets is a `problem`,
+ * and the caller decides what to report.
+ */
+export function loadFallbackConfig(opts) {
+    const env = opts.env ?? process.env;
+    if (!fallbackEnabled(env))
+        return null;
+    const inline = (env[ENV_FALLBACKS] ?? "").trim();
+    if (inline !== "")
+        return parseConfig(inline, "env");
+    const dir = opts.dataDir;
+    if (dir === null || dir === undefined || dir === "")
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(join(dir, FALLBACKS_FILE), "utf8");
+    }
+    catch {
+        return null;
+    }
+    return parseConfig(raw, "file");
+}
+/** Parse + validate one config document; unparsable input is a reported problem. */
+export function parseConfig(raw, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return { version: 1, enabled: false, targets: [], policy: {}, source, problems: [`unparsable JSON (${text(e)})`] };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { version: 1, enabled: false, targets: [], policy: {}, source, problems: ["config must be a JSON object"] };
+    }
+    const rec = parsed;
+    const targets = parseTargets(rec["targets"]);
+    const problems = [];
+    if (targets.length === 0)
+        problems.push("no targets configured");
+    return {
+        version: typeof rec["version"] === "number" ? rec["version"] : 1,
+        enabled: rec["enabled"] !== false,
+        targets,
+        policy: parsePolicy(rec["policy"]),
+        source,
+        problems,
+    };
+}
+function parseTargets(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const rec = item;
+        const name = str(rec["name"]);
+        const model = str(rec["model"]);
+        if (name === null || model === null)
+            continue;
+        out.push({
+            name,
+            provider: str(rec["provider"]) ?? name,
+            model,
+            baseUrl: str(rec["baseUrl"]),
+            apiKeyEnv: str(rec["apiKeyEnv"]),
+        });
+    }
+    return out;
+}
+function parsePolicy(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return {};
+    const rec = raw;
+    const out = {};
+    for (const key of ["maxAttempts", "cooldownMs", "failureThreshold"]) {
+        const value = rec[key];
+        if (typeof value === "number" && Number.isFinite(value) && value >= 0)
+            out[key] = Math.floor(value);
+    }
+    for (const key of ["notRetryableStatuses", "retryableStatuses"]) {
+        const value = rec[key];
+        if (Array.isArray(value)) {
+            const statuses = value.filter((n) => typeof n === "number" && Number.isFinite(n));
+            if (statuses.length > 0)
+                out[key] = statuses;
+        }
+    }
+    if (typeof rec["respectRetryAfter"] === "boolean")
+        out.respectRetryAfter = rec["respectRetryAfter"];
+    return out;
+}
+/**
+ * Credential inventory (U7) — env var NAMES only, never values: a target that
+ * names an `apiKeyEnv` which the process does not define is UNAVAILABLE, and the
+ * caller must report it instead of dropping the target silently.
+ */
+export function targetAvailability(targets, env = process.env) {
+    return targets.map((target) => {
+        const envName = target.apiKeyEnv ?? null;
+        const missing = envName !== null && (env[envName] ?? "") === "";
+        return { name: target.name, model: target.model, available: !missing, missingEnv: missing ? envName : null };
+    });
+}
+/** The `problems[]` of a chain, including the credentials it cannot use (U7). */
+export function configProblems(config, env = process.env) {
+    const out = [...config.problems];
+    for (const t of targetAvailability(config.targets, env)) {
+        if (!t.available)
+            out.push(`target '${t.name}' has no credential (env ${t.missingEnv} is unset)`);
+    }
+    return out;
+}
+function str(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+function text(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/fallback.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Model fallback decorator (iteration E §4.2, P1) — a `Llm`, not a new seam.
+ *
+ * `createFallbackLlm({ targets, clientFor, policy, onAttempt, steps })` returns
+ * the SAME `Llm` interface the rest of the engine already consumes, which is why
+ * `agent-loop`'s `loop.ts` does not change one line (§4.6): the switch between
+ * targets happens entirely inside `generate`/the returned stream.
+ *
+ * The decorator owns exactly four things (§4.2.2, each mechanically testable):
+ *   1. the TRIGGER TABLE — which failures hand over to the next target and which
+ *      ones terminate (a 401/403/400 is a configuration problem: another model
+ *      cannot fix it). The table itself is data ([DEFAULT_FALLBACK_POLICY]);
+ *   2. the `produced` LOCK — once a text/thinking delta reached the consumer the
+ *      attempt is NEVER redone: redoing it would drop text the user already saw
+ *      and double-bill / double-write side effects (§4.5 R4-2);
+ *   3. target-level COOLDOWN — `failureThreshold` consecutive failures bench a
+ *      target for `cooldownMs`; a benched target is tried last, never first;
+ *   4. VISIBILITY — every hand-over is reported through `onAttempt` (the host
+ *      turns that into an SSE `status` frame, a local audit line and the
+ *      statusline's `effective_model`), and through the optional step sink, so
+ *      one user intent that cost N attempts is visible as N ledger rows.
+ *
+ * Honest boundaries (§4.5): availability fallback ONLY (no quality judgement),
+ * no key rotation, no persistent cooldown (that is P2).
+ */
+import type { Usage } from "@celestea/core";
+import { type LlmErrorKind } from "./errors.js";
+import type { Llm, StreamEvent } from "./seam.js";
+/** One fallback target: its own client, hence its own base_url/key/timeouts. */
+export interface LlmTarget {
+    /** Stable name used in the ledger (`fallback_from`), the SSE frame and audits. */
+    name: string;
+    /** `providers.json` row id, for the ledger's `provider` column. */
+    provider: string;
+    model: string;
+    /** Absent = inherit the composed profile's base_url. */
+    baseUrl?: string | null;
+    /** Env var NAME holding this target's key (never the key itself, §4.5 R4-3). */
+    apiKeyEnv?: string | null;
+}
+/** §4.2.1 defaults, verbatim. */
+export interface FallbackPolicy {
+    /** 1 primary + 1 fallback by default; never more targets than this. */
+    maxAttempts: number;
+    /** Target-level cooldown once a target has failed `failureThreshold` times. */
+    cooldownMs: number;
+    failureThreshold: number;
+    notRetryableStatuses: number[];
+    retryableStatuses: number[];
+    /** Honour `Retry-After`, but never wait longer than `cooldownMs` (§4.5 R4-4). */
+    respectRetryAfter: boolean;
+}
+export declare const DEFAULT_FALLBACK_POLICY: FallbackPolicy;
+/** What one CLOSED attempt is booked as (structurally = runtime's `LedgerStepSink`). */
+export interface FallbackStepHandle {
+    record(usage: Usage): void;
+    close(outcome: {
+        kind: "ok" | "error";
+        error_kind?: string | null;
+        http_status?: number | null;
+        retryable?: boolean | null;
+    }): void;
+}
+export interface FallbackStepSink {
+    beginStep(info: {
+        provider: string | null;
+        model: string | null;
+        base_url_host: string | null;
+        attempt: number;
+        fallback_from: string | null;
+    }): FallbackStepHandle;
+}
+/**
+ * One HAND-OVER, as reported to the host (SSE/audit/statusline). The hook fires
+ * when the decorator actually switches — not for the attempt that failed, and
+ * never when the failure is terminal (produced-lock / non-retryable status), so
+ * "a frame was emitted" always means "another target is being tried".
+ */
+export interface FallbackAttemptInfo {
+    /** Index of the attempt that is ABOUT to run (§5.2 numbering). */
+    attempt: number;
+    /** The target about to run. */
+    target: string;
+    model: string;
+    /** The target that just failed and is being left behind. */
+    from: string | null;
+    /** `http_503` / `timeout_idle` / `stream` / `network` / `generate`. */
+    reason: string;
+    httpStatus: number | null;
+    /** text/thinking deltas already delivered by the failing attempt. */
+    produced: number;
+}
+/** Target health, shared by every session of one process (§4.2.2 cooldown). */
+export declare class FallbackState {
+    private readonly failures;
+    private readonly benchUntil;
+    consecutiveFailures(name: string): number;
+    cooldownUntil(name: string): number;
+    isCooling(name: string, now: number): boolean;
+    /** One failed attempt; `failureThreshold` in a row benches the target. */
+    noteFailure(name: string, now: number, policy: FallbackPolicy): void;
+    noteSuccess(name: string): void;
+    snapshot(now: number): Array<{
+        name: string;
+        cooling: boolean;
+        consecutive_failures: number;
+        cooldown_until: number;
+    }>;
+}
+export interface FallbackLlmOptions {
+    targets: LlmTarget[];
+    /** Builds ONE client per target (own base_url/key/timeouts); called lazily. */
+    clientFor: (target: LlmTarget) => Llm;
+    policy?: Partial<FallbackPolicy>;
+    /** Process-shared cooldown/health; a private one is created when absent. */
+    state?: FallbackState;
+    /** Called once per failed attempt (the visibility hook). */
+    onAttempt?: (info: FallbackAttemptInfo) => void;
+    /** Per-attempt ledger booking; absent = no ledger hook. */
+    steps?: FallbackStepSink | null;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** The decorator + the read-only views the statusline needs (§4.2.3 #4). */
+export interface FallbackLlm extends Llm {
+    /** Target of the newest attempt (the EFFECTIVE model), null before any. */
+    effective(): {
+        name: string;
+        model: string;
+    } | null;
+    /** Targets in the order this process would try them right now (cooling last). */
+    chain(): string[];
+    /** Reason of the newest hand-over (`http_503`, …), null while none happened. */
+    lastReason(): string | null;
+    /** Failed attempts observed by THIS decorator (diagnostics/tests). */
+    failedAttempts(): number;
+}
+/** Cooled-down targets go LAST: a benched target is never the preferred one. */
+export declare function orderTargets(targets: readonly LlmTarget[], state: FallbackState, now: number): LlmTarget[];
+export declare function createFallbackLlm(opts: FallbackLlmOptions): FallbackLlm;
+/** One attempt's failure, in the vocabulary of §4.2.2's table. */
+export interface FailureInfo {
+    reason: string;
+    kind: LlmErrorKind;
+    retryable: boolean;
+    httpStatus: number | null;
+    retryAfterMs: number | null;
+    produced: number;
+    message: string;
+}
+/** `text`/`thinking` reaching the consumer = the attempt cannot be redone. */
+export declare function isProducedEvent(event: StreamEvent): boolean;
+/**
+ * Classify a thrown failure. `produced > 0` overrides everything: a failure
+ * after visible output is terminal, whatever its status said.
+ */
+export declare function describeFailure(error: unknown, produced: number, policy?: FallbackPolicy): FailureInfo;
+/** Classify a terminal stream event (`failed{kindOf}` / `interrupted`). */
+export declare function describeEvent(event: Extract<StreamEvent, {
+    kind: "failed";
+}> | {
+    kind: "interrupted";
+}, produced: number): FailureInfo;