@celestea/llm 2.7.1

package/dist/fallback.js

@@ -0,0 +1,304 @@
+/**
+ * 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 { LlmError, retryAfterMsOf, TIMEOUT_ERROR_PREFIX } from "./errors.js";
+import { hostOf } from "./host.js";
+export const DEFAULT_FALLBACK_POLICY = {
+    maxAttempts: 2,
+    cooldownMs: 60_000,
+    failureThreshold: 3,
+    notRetryableStatuses: [400, 401, 403, 404, 422],
+    retryableStatuses: [408, 425, 429, 500, 502, 503, 504],
+    respectRetryAfter: true,
+};
+/** Target health, shared by every session of one process (§4.2.2 cooldown). */
+export class FallbackState {
+    failures = new Map();
+    benchUntil = new Map();
+    consecutiveFailures(name) {
+        return this.failures.get(name) ?? 0;
+    }
+    cooldownUntil(name) {
+        return this.benchUntil.get(name) ?? 0;
+    }
+    isCooling(name, now) {
+        return this.cooldownUntil(name) > now;
+    }
+    /** One failed attempt; `failureThreshold` in a row benches the target. */
+    noteFailure(name, now, policy) {
+        const failures = this.consecutiveFailures(name) + 1;
+        this.failures.set(name, failures);
+        if (failures >= policy.failureThreshold)
+            this.benchUntil.set(name, now + policy.cooldownMs);
+    }
+    noteSuccess(name) {
+        this.failures.set(name, 0);
+        this.benchUntil.set(name, 0);
+    }
+    snapshot(now) {
+        const names = new Set([...this.failures.keys(), ...this.benchUntil.keys()]);
+        return [...names].sort().map((name) => ({
+            name,
+            cooling: this.isCooling(name, now),
+            consecutive_failures: this.consecutiveFailures(name),
+            cooldown_until: this.cooldownUntil(name),
+        }));
+    }
+}
+const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Cooled-down targets go LAST: a benched target is never the preferred one. */
+export function orderTargets(targets, state, now) {
+    const warm = targets.filter((t) => !state.isCooling(t.name, now));
+    const cold = targets.filter((t) => state.isCooling(t.name, now));
+    return [...warm, ...cold];
+}
+export function createFallbackLlm(opts) {
+    const targets = opts.targets.filter((t) => t.name.trim() !== "");
+    if (targets.length === 0)
+        throw new Error("fallback: at least one target is required");
+    const rt = {
+        opts,
+        targets,
+        policy: { ...DEFAULT_FALLBACK_POLICY, ...(opts.policy ?? {}) },
+        state: opts.state ?? new FallbackState(),
+        now: opts.now ?? Date.now,
+        sleep: opts.sleep ?? sleepMs,
+        clients: new Map(),
+        failed: 0,
+        lastReason: null,
+        effective: null,
+    };
+    return {
+        generate: (req) => Promise.resolve(attemptLoop(rt, req)),
+        effective: () => rt.effective,
+        chain: () => orderTargets(targets, rt.state, rt.now()).map((t) => t.name),
+        lastReason: () => rt.lastReason,
+        failedAttempts: () => rt.failed,
+    };
+}
+/** One client per target, built on first use (its own base_url/key/timeouts). */
+function clientOf(rt, target) {
+    const known = rt.clients.get(target.name);
+    if (known !== undefined)
+        return known;
+    const built = rt.opts.clientFor(target);
+    rt.clients.set(target.name, built);
+    return built;
+}
+/** One failed attempt: count it, and bench the target if it keeps failing. */
+function noteFailure(rt, target, info) {
+    rt.failed += 1;
+    rt.lastReason = info.reason;
+    rt.state.noteFailure(target.name, rt.now(), rt.policy);
+}
+/** The switch itself is the event the host publishes (§4.2.3). */
+function announce(rt, next, attempt, from, info) {
+    rt.opts.onAttempt?.({
+        attempt,
+        target: next.name,
+        model: next.model,
+        from,
+        reason: info.reason,
+        httpStatus: info.httpStatus,
+        produced: info.produced,
+    });
+}
+/** `Retry-After` is honoured up to `cooldownMs`; beyond it we move on. */
+async function honourRetryAfter(rt, info) {
+    if (!rt.policy.respectRetryAfter || info.retryAfterMs === null)
+        return;
+    if (info.retryAfterMs > rt.policy.cooldownMs)
+        return;
+    if (info.retryAfterMs > 0)
+        await rt.sleep(info.retryAfterMs);
+}
+/** The whole attempt loop, lazily: the first events are pulled by the loop. */
+async function* attemptLoop(rt, req) {
+    const plan = orderTargets(rt.targets, rt.state, rt.now()).slice(0, Math.max(1, rt.policy.maxAttempts));
+    let from = null;
+    let lastError = null;
+    for (let attempt = 0; attempt < plan.length; attempt++) {
+        const target = plan[attempt];
+        const step = rt.opts.steps?.beginStep({
+            provider: target.provider,
+            model: target.model,
+            base_url_host: hostOf(target.baseUrl ?? null),
+            attempt,
+            fallback_from: from,
+        });
+        let stream;
+        try {
+            stream = await clientOf(rt, target).generate(req);
+        }
+        catch (error) {
+            const info = describeFailure(error, 0, rt.policy);
+            step?.close({ kind: "error", error_kind: info.kind, http_status: info.httpStatus, retryable: info.retryable });
+            noteFailure(rt, target, info);
+            if (!info.retryable)
+                throw error;
+            lastError = error;
+            // W835 (P1-2): only wait for Retry-After when another target will run.
+            // An exhausted chain must fail fast instead of sleeping up to cooldownMs.
+            const next = plan[attempt + 1];
+            if (next !== undefined) {
+                await honourRetryAfter(rt, info);
+                announce(rt, next, attempt + 1, target.name, info);
+            }
+            from = target.name;
+            continue;
+        }
+        rt.effective = { name: target.name, model: target.model };
+        const outcome = yield* consume(stream, step, rt.policy);
+        if (outcome.kind === "done") {
+            rt.state.noteSuccess(target.name);
+            return;
+        }
+        noteFailure(rt, target, outcome.info);
+        // produced > 0 = the lock: the attempt is never redone (§4.2.2).
+        if (outcome.info.produced > 0 || !outcome.info.retryable) {
+            yield outcome.terminal;
+            return;
+        }
+        lastError = outcome.error;
+        // W835 (P1-2): no last-target Retry-After sleep (see the catch branch above).
+        const next = plan[attempt + 1];
+        if (next !== undefined) {
+            await honourRetryAfter(rt, outcome.info);
+            announce(rt, next, attempt + 1, target.name, outcome.info);
+        }
+        from = target.name;
+    }
+    throw lastError ?? new LlmError("llm fallback: every target failed", "generate", { retryable: false });
+}
+/** Forward one attempt's events, counting what the consumer has already seen. */
+async function* consume(stream, step, policy) {
+    let produced = 0;
+    let closed = false;
+    // W835 (P1-3): close the step EXACTLY once. The `finally` covers the case the
+    // old code missed: the consumer abandoned the attempt (break / cancel), the
+    // generator is returned, and the usage already recorded must still be booked
+    // instead of silently dropped.
+    const closeStep = (outcome) => {
+        if (closed)
+            return;
+        closed = true;
+        step?.close(outcome);
+    };
+    try {
+        for await (const event of stream) {
+            if (isProducedEvent(event))
+                produced += 1;
+            if (event.kind === "done") {
+                closeStep({ kind: "ok" });
+                // The terminal event is FORWARDED, not swallowed: the loop derives the
+                // turn's `assistant_message` from it (loop.ts:246-253).
+                yield event;
+                return { kind: "done" };
+            }
+            // The step buffer is fed HERE, exactly like the W728 observer does: a
+            // usage frame belongs to the attempt that produced it (§3.2.3).
+            if (event.kind === "usage")
+                step?.record(event.usage);
+            if (event.kind === "failed" || event.kind === "interrupted") {
+                const info = describeEvent(event, produced);
+                closeStep({ kind: "error", error_kind: info.kind, http_status: null, retryable: info.retryable });
+                return { kind: "failed", info, terminal: event, error: errorOfEvent(event, info) };
+            }
+            yield event;
+        }
+        const info = describeEvent({ kind: "interrupted" }, produced);
+        closeStep({ kind: "error", error_kind: info.kind, http_status: null, retryable: info.retryable });
+        return { kind: "failed", info, terminal: { kind: "interrupted" }, error: errorOfEvent({ kind: "interrupted" }, info) };
+    }
+    catch (error) {
+        const info = describeFailure(error, produced, policy);
+        closeStep({ kind: "error", error_kind: info.kind, http_status: info.httpStatus, retryable: info.retryable });
+        return { kind: "failed", info, terminal: { kind: "interrupted" }, error };
+    }
+    finally {
+        // Early `return()` from the consumer (break / cancel): book the attempt as
+        // ok so its already-recorded usage keeps its row. A no-op on every normal
+        // exit because [closeStep] is idempotent.
+        closeStep({ kind: "ok" });
+    }
+}
+/** `text`/`thinking` reaching the consumer = the attempt cannot be redone. */
+export function isProducedEvent(event) {
+    return event.kind === "text" || event.kind === "thinking";
+}
+/**
+ * Classify a thrown failure. `produced > 0` overrides everything: a failure
+ * after visible output is terminal, whatever its status said.
+ */
+export function describeFailure(error, produced, policy = DEFAULT_FALLBACK_POLICY) {
+    const rec = typeof error === "object" && error !== null ? error : {};
+    const message = typeof rec["message"] === "string" ? rec["message"] : String(error);
+    const status = typeof rec["httpStatus"] === "number" ? rec["httpStatus"] : null;
+    const stage = typeof rec["timeoutStage"] === "string" ? rec["timeoutStage"] : null;
+    const isTimeout = rec["isTimeout"] === true || rec["kind"] === "timeout" || message.startsWith(TIMEOUT_ERROR_PREFIX);
+    const kind = typeof rec["kind"] === "string" ? rec["kind"] : "generate";
+    const base = { produced, httpStatus: status, message, retryAfterMs: retryAfterMsOf(error) };
+    if (produced > 0)
+        return { ...base, reason: reasonOf(status, isTimeout, stage, kind), kind, retryable: false };
+    if (status !== null) {
+        return { ...base, reason: `http_${status}`, kind, retryable: statusRetryable(status, policy) };
+    }
+    if (isTimeout)
+        return { ...base, reason: `timeout_${stage ?? "idle"}`, kind: "timeout", retryable: true };
+    if (rec["retryable"] === true)
+        return { ...base, reason: "network", kind, retryable: true };
+    if (kind === "stream")
+        return { ...base, reason: "stream", kind, retryable: true };
+    return { ...base, reason: "generate", kind, retryable: false };
+}
+/** Classify a terminal stream event (`failed{kindOf}` / `interrupted`). */
+export function describeEvent(event, produced) {
+    const base = { produced, retryable: produced === 0, httpStatus: null, retryAfterMs: null };
+    if (event.kind === "interrupted") {
+        return { ...base, reason: "interrupted", kind: "stream", message: "stream interrupted" };
+    }
+    const kindOf = event.kindOf;
+    const kind = kindOf === "timeout" ? "timeout" : kindOf;
+    const reason = kindOf === "timeout" ? "timeout_idle" : kindOf;
+    return { ...base, reason, kind, message: event.message };
+}
+function reasonOf(status, isTimeout, stage, kind) {
+    if (status !== null)
+        return `http_${status}`;
+    if (isTimeout)
+        return `timeout_${stage ?? "idle"}`;
+    return kind === "stream" ? "stream" : "generate";
+}
+/** A status is worth another target unless it is a request/credential problem. */
+function statusRetryable(status, policy) {
+    if (policy.notRetryableStatuses.includes(status))
+        return false;
+    return status >= 500 || policy.retryableStatuses.includes(status);
+}
+/** The error a terminal event maps to when the whole chain is exhausted. */
+function errorOfEvent(event, info) {
+    const kind = event.kind === "interrupted" ? "stream" : event.kindOf === "generate" ? "generate" : "stream";
+    return new LlmError(info.message, kind, { retryable: info.retryable });
+}

package/dist/host.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Host extraction for the fallback ledger columns (`base_url_host`).
+ *
+ * Kept in its own module so the fallback decorator can name the host of a
+ * target's base_url without importing the HTTP transport, and so the rule lives
+ * in exactly one place (the runtime's `ledger-llm.ts` mirrors it for the same
+ * column — both are "the host, or null when it is not a URL").
+ */
+/** Host of a base_url (`api.deepseek.com`), or null when it is not a URL. */
+export declare function hostOf(baseUrl: string | null): string | null;

package/dist/host.js

@@ -0,0 +1,19 @@
+/**
+ * Host extraction for the fallback ledger columns (`base_url_host`).
+ *
+ * Kept in its own module so the fallback decorator can name the host of a
+ * target's base_url without importing the HTTP transport, and so the rule lives
+ * in exactly one place (the runtime's `ledger-llm.ts` mirrors it for the same
+ * column — both are "the host, or null when it is not a URL").
+ */
+/** Host of a base_url (`api.deepseek.com`), or null when it is not a URL. */
+export function hostOf(baseUrl) {
+    if (baseUrl === null || baseUrl === "")
+        return null;
+    try {
+        return new URL(baseUrl).host;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/image-fallback.d.ts

@@ -0,0 +1,77 @@
+/**
+ * W804 (multimodal P0 section 7.6): the ONE automatic downgrade for the
+ * optimistic-default bet.
+ *
+ * Default `input_modalities = ["text","image"]` means we ASSUME every model
+ * accepts images. When that assumption is wrong the upstream answers 4xx with a
+ * known "image unsupported" report; the client classifies it as an
+ * [ImageUnsupportedError]. This decorator then:
+ *   1. replaces every ImageContent block with a visible placeholder text,
+ *   2. retries the SAME request ONCE,
+ *   3. reports the downgrade through `onDowngrade` (the host's three visible
+ *      channels: info block / statusline / audit).
+ *
+ * It never swallows the failure silently: the placeholder is in the retried
+ * request, and an unrecognised failure propagates unchanged. If the retry fails
+ * too, that failure propagates as an ordinary turn failure.
+ */
+import type { ImageRef, Llm, ModelRequestDraft } from "./seam.js";
+/**
+ * W855: WHY an image downgrade fired. The three causes reuse the ONE downgrade
+ * path (placeholder rewrite -> same-request retry -> onDowngrade); only the
+ * trigger and the user-facing copy differ.
+ *   - upstream_rejected     the upstream answered 4xx "image unsupported" (W804);
+ *   - timeout               response headers never arrived (suspected image
+ *                           rejection: the upstream may be slow to REJECT);
+ *   - configured_text_only  input_modalities explicitly excludes "image", so no
+ *                           image-bearing request is ever sent.
+ */
+export type ImageDowngradeCause = "upstream_rejected" | "timeout" | "configured_text_only";
+/** What the host renders/persists when a downgrade happens. */
+export interface ImageDowngradeInfo {
+    /** Effective model that triggered the downgrade (the model selector's value). */
+    model: string;
+    /** Machine-readable classification. NEVER changes: the contract/consumers key on this. */
+    reason: "IMAGE_UNSUPPORTED";
+    /**
+     * W855: the trigger discriminator. OPTIONAL on purpose - an older producer
+     * (or an embedded host) that predates this field stays valid and every
+     * consumer tolerates its absence (defaults to upstream_rejected).
+     */
+    cause?: ImageDowngradeCause;
+    /** The upstream HTTP status (400 on the reject path); null on the other two. */
+    httpStatus: number | null;
+    /**
+     * The error text, verbatim: the upstream body on the reject path, the timeout
+     * message ("llm timeout: response headers ...", threshold included) on the
+     * timeout path, and the configured-exclusion fact locally.
+     */
+    message: string;
+    /** The placeholder that replaced the images in the retried request. */
+    placeholder: string;
+}
+export interface ImageDowngradeLlmOptions {
+    inner: Llm;
+    /** Called exactly once per downgraded request, before the retry. */
+    onDowngrade?: (info: ImageDowngradeInfo) => void;
+    /**
+     * W855: true = the target model is EXPLICITLY configured as text-only
+     * (input_modalities without "image"). Evaluated against the request's OWN
+     * req.model at call time, so a model switch is never stale. Absent = the
+     * optimistic default (images allowed), i.e. the pre-W855 behaviour.
+     */
+    isTextOnly?: (model: string) => boolean;
+}
+/** The placeholder text (section 7.6 wording, one per image block). */
+export declare function imagePlaceholderText(ref: ImageRef, model: string): string;
+/**
+ * A copy of the request with every image block replaced by its placeholder and
+ * the request-scoped image table removed. Non-image content, tool calls and text
+ * are byte-for-byte unchanged.
+ */
+export declare function withImagePlaceholders(req: ModelRequestDraft, model: string): ModelRequestDraft;
+/**
+ * Wrap an `Llm` with the one-shot image downgrade. Text-only requests pass
+ * through untouched (no image scan cost beyond the check).
+ */
+export declare function createImageDowngradeLlm(options: ImageDowngradeLlmOptions): Llm;

package/dist/image-fallback.js

@@ -0,0 +1,129 @@
+/**
+ * W804 (multimodal P0 section 7.6): the ONE automatic downgrade for the
+ * optimistic-default bet.
+ *
+ * Default `input_modalities = ["text","image"]` means we ASSUME every model
+ * accepts images. When that assumption is wrong the upstream answers 4xx with a
+ * known "image unsupported" report; the client classifies it as an
+ * [ImageUnsupportedError]. This decorator then:
+ *   1. replaces every ImageContent block with a visible placeholder text,
+ *   2. retries the SAME request ONCE,
+ *   3. reports the downgrade through `onDowngrade` (the host's three visible
+ *      channels: info block / statusline / audit).
+ *
+ * It never swallows the failure silently: the placeholder is in the retried
+ * request, and an unrecognised failure propagates unchanged. If the retry fails
+ * too, that failure propagates as an ordinary turn failure.
+ */
+import { isImageUnsupportedError, isTimeoutError } from "./errors.js";
+import { messagesHaveImages } from "./wire.js";
+/**
+ * W855: ONLY a RESPONSE-HEADER timeout - not one byte ever arrived, so the
+ * request may simply be slow to be rejected - is treated as a suspected image
+ * rejection. A connect timeout, a mid-stream stall, a 401, etc. are rethrown
+ * unchanged: resending text cannot save them, and a second attempt would only
+ * waste a round-trip while swallowing the user's image.
+ */
+function isResponseHeaderTimeout(e) {
+    return isTimeoutError(e) && e.timeoutStage === "response";
+}
+/** The placeholder text (section 7.6 wording, one per image block). */
+export function imagePlaceholderText(ref, model) {
+    const label = ref.name !== undefined ? `${ref.attachment_id}（${ref.name}）` : ref.attachment_id;
+    return `[图片已省略：模型 "${model}" 未接受图像输入（上游 400）；attachment ${label}]`;
+}
+/**
+ * A copy of the request with every image block replaced by its placeholder and
+ * the request-scoped image table removed. Non-image content, tool calls and text
+ * are byte-for-byte unchanged.
+ */
+export function withImagePlaceholders(req, model) {
+    const messages = [];
+    for (const msg of req.messages ?? []) {
+        let changed = false;
+        const content = [];
+        for (const part of msg.content) {
+            if (part.type === "image") {
+                content.push({ type: "text", content: imagePlaceholderText(part.content, model) });
+                changed = true;
+            }
+            else {
+                content.push(part);
+            }
+        }
+        messages.push(changed ? { ...msg, content } : msg);
+    }
+    const { images: _images, ...rest } = req;
+    void _images;
+    return { ...rest, messages };
+}
+/** True when the request carries at least one image content block. */
+function hasImages(req) {
+    return messagesHaveImages(req.messages ?? []);
+}
+function firstPlaceholder(messages, model) {
+    for (const msg of messages) {
+        for (const part of msg.content) {
+            if (part.type === "image")
+                return imagePlaceholderText(part.content, model);
+        }
+    }
+    return "";
+}
+/**
+ * Wrap an `Llm` with the one-shot image downgrade. Text-only requests pass
+ * through untouched (no image scan cost beyond the check).
+ */
+export function createImageDowngradeLlm(options) {
+    return {
+        async generate(req) {
+            const model = req.model ?? "";
+            // Text-only requests pass through untouched: no rewrite, no extra call.
+            if (!hasImages(req))
+                return options.inner.generate(req);
+            const placeholder = firstPlaceholder(req.messages ?? [], model);
+            // W855 path 1: explicitly configured text-only -> never send the image
+            // request; go straight to the placeholder request. No upstream call
+            // carries the image; exactly one upstream call happens in total.
+            if (options.isTextOnly?.(model) === true) {
+                options.onDowngrade?.({
+                    model,
+                    reason: "IMAGE_UNSUPPORTED",
+                    cause: "configured_text_only",
+                    httpStatus: null,
+                    message: '模型 "' + model + '" 的 input_modalities 不含 "image"（按配置显式排除），本次带图请求未发送。',
+                    placeholder,
+                });
+                return await options.inner.generate(withImagePlaceholders(req, model));
+            }
+            try {
+                return await options.inner.generate(req);
+            }
+            catch (error) {
+                // W855 paths 2/3: a classified upstream 4xx image report, OR a
+                // response-header timeout (the suspected-slow-rejection case). Both
+                // reuse the SAME downgrade; every other failure propagates unchanged.
+                let cause = null;
+                let httpStatus = null;
+                if (isImageUnsupportedError(error)) {
+                    cause = "upstream_rejected";
+                    httpStatus = error.httpStatus;
+                }
+                else if (isResponseHeaderTimeout(error)) {
+                    cause = "timeout";
+                }
+                if (cause === null)
+                    throw error;
+                options.onDowngrade?.({
+                    model,
+                    reason: "IMAGE_UNSUPPORTED",
+                    cause,
+                    httpStatus,
+                    message: error instanceof Error ? error.message : String(error),
+                    placeholder,
+                });
+                return await options.inner.generate(withImagePlaceholders(req, model));
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @celestea/llm — OpenAI-compatible LLM provider (P2a public API).
+ *
+ * Parity target: `celestea_harness/crates/llm` — raw SSE transport, usage /
+ * cache-hit parsing, three timeout tiers, free-form reasoning_effort.
+ *
+ * Only this barrel is the package's public surface: provider internals
+ * (SSE framing, wire mapping, HTTP transport) stay private so callers depend on
+ * the `Llm` seam, not on the provider.
+ */
+export type { Content, ImageContent, ImageRef, Llm, LlmStream, Message, ModelRequest, ModelRequestDraft, ResolvedImages, Role, StreamEvent, TextContent, ToolCall, ToolCallContent, ToolSpec, } from "./seam.js";
+export { assistantText, assistantToolCall, collectMessageText, collectStream, messageToolCalls, ROLES, systemMessage, toolResultMessage, userMessage, } from "./seam.js";
+export type { LlmUsageFrame, Usage } from "./usage.js";
+export { cacheHitRatio, CACHE_READ_FLAT_KEYS, CACHE_READ_NESTED, parseUsage, REASONING_TOKENS_NESTED, USAGE_REQUIRED_KEYS, usageFromObject, usageIsEmpty, ZERO_USAGE, zeroUsage, } from "./usage.js";
+export type { LlmErrorKind, LlmErrorOptions, TimeoutStage } from "./errors.js";
+export { cancelledError, parseRetryAfterHeader, retryAfterMsOf, setRetryAfterMs, connectTimeoutError, errorKind, ImageUnsupportedError, IMAGE_UNSUPPORTED_MARKERS, isImageUnsupportedBody, isImageUnsupportedError, isRetryableStatus, isTimeoutError, LlmError, networkError, responseHeaderTimeoutError, RETRYABLE_HTTP_STATUSES, statusError, streamIdleTimeoutMessage, TIMEOUT_ERROR_PREFIX, timeoutError, } from "./errors.js";
+export type { EnvLike, TimeoutProfile, TimeoutTiers } from "./timeouts.js";
+export { CONNECT_TIMEOUT_ENV, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_RESPONSE_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_TIMEOUTS, isTimeoutMs, PROFILE_TIMEOUT_KEYS, readTimeoutProfile, RESPONSE_TIMEOUT_ENV, resolveTimeoutMs, resolveTimeoutTiers, STREAM_IDLE_TIMEOUT_ENV, } from "./timeouts.js";
+export type { LlmProfile, ResolvedClientConfig } from "./profile.js";
+export { API_KEY_ENV, BASE_URL_ENV, DEFAULT_BASE_URL, DEFAULT_MODEL, normalizeReasoningEffort, resolveApiKey, resolveClientConfig, tiersFromConfig, validateModel, } from "./profile.js";
+export type { LiveLlmProfile, LiveLlmView, LlmMode } from "./factory.js";
+export { createLiveLlm, liveLlmView, LLM_BASE_URL_ENV, LLM_MODE_ENV, resolveLlmMode, withBaseUrlFallback, } from "./factory.js";
+export type { FallbackAttemptInfo, FallbackLlm, FallbackLlmOptions, FallbackPolicy, FallbackStepHandle, FallbackStepSink, FailureInfo, LlmTarget, } from "./fallback.js";
+export { createFallbackLlm, DEFAULT_FALLBACK_POLICY, describeEvent, describeFailure, FallbackState, isProducedEvent, orderTargets, } from "./fallback.js";
+export type { FallbackConfig } from "./fallback-config.js";
+export { configProblems, ENV_FALLBACK_SWITCH, ENV_FALLBACKS, FALLBACKS_FILE, fallbackEnabled, loadFallbackConfig, parseConfig, targetAvailability, } from "./fallback-config.js";
+export type { OpenAiCompatOptions } from "./client.js";
+export { OpenAiCompatClient } from "./client.js";
+export { createDeepSeekLlm, createDeepSeekRegistry, DEEPSEEK_PROVIDER_NAME, LlmRegistry, } from "./provider.js";
+export type { WireContentPart, WireImagePart, WireTextPart } from "./wire.js";
+export { collectMessageParts, dataUrlFor, messageImageRefs, messagesHaveImages, resolvedImagesOf, wireMessagesFor, } from "./wire.js";
+export type { ImageDowngradeCause, ImageDowngradeInfo, ImageDowngradeLlmOptions } from "./image-fallback.js";
+export { createImageDowngradeLlm, imagePlaceholderText, withImagePlaceholders } from "./image-fallback.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @celestea/llm — OpenAI-compatible LLM provider (P2a public API).
+ *
+ * Parity target: `celestea_harness/crates/llm` — raw SSE transport, usage /
+ * cache-hit parsing, three timeout tiers, free-form reasoning_effort.
+ *
+ * Only this barrel is the package's public surface: provider internals
+ * (SSE framing, wire mapping, HTTP transport) stay private so callers depend on
+ * the `Llm` seam, not on the provider.
+ */
+export { assistantText, assistantToolCall, collectMessageText, collectStream, messageToolCalls, ROLES, systemMessage, toolResultMessage, userMessage, } from "./seam.js";
+export { cacheHitRatio, CACHE_READ_FLAT_KEYS, CACHE_READ_NESTED, parseUsage, REASONING_TOKENS_NESTED, USAGE_REQUIRED_KEYS, usageFromObject, usageIsEmpty, ZERO_USAGE, zeroUsage, } from "./usage.js";
+export { cancelledError, parseRetryAfterHeader, retryAfterMsOf, setRetryAfterMs, connectTimeoutError, errorKind, ImageUnsupportedError, IMAGE_UNSUPPORTED_MARKERS, isImageUnsupportedBody, isImageUnsupportedError, isRetryableStatus, isTimeoutError, LlmError, networkError, responseHeaderTimeoutError, RETRYABLE_HTTP_STATUSES, statusError, streamIdleTimeoutMessage, TIMEOUT_ERROR_PREFIX, timeoutError, } from "./errors.js";
+export { CONNECT_TIMEOUT_ENV, DEFAULT_CONNECT_TIMEOUT_MS, DEFAULT_RESPONSE_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DEFAULT_TIMEOUTS, isTimeoutMs, PROFILE_TIMEOUT_KEYS, readTimeoutProfile, RESPONSE_TIMEOUT_ENV, resolveTimeoutMs, resolveTimeoutTiers, STREAM_IDLE_TIMEOUT_ENV, } from "./timeouts.js";
+export { API_KEY_ENV, BASE_URL_ENV, DEFAULT_BASE_URL, DEFAULT_MODEL, normalizeReasoningEffort, resolveApiKey, resolveClientConfig, tiersFromConfig, validateModel, } from "./profile.js";
+export { createLiveLlm, liveLlmView, LLM_BASE_URL_ENV, LLM_MODE_ENV, resolveLlmMode, withBaseUrlFallback, } from "./factory.js";
+export { createFallbackLlm, DEFAULT_FALLBACK_POLICY, describeEvent, describeFailure, FallbackState, isProducedEvent, orderTargets, } from "./fallback.js";
+export { configProblems, ENV_FALLBACK_SWITCH, ENV_FALLBACKS, FALLBACKS_FILE, fallbackEnabled, loadFallbackConfig, parseConfig, targetAvailability, } from "./fallback-config.js";
+export { OpenAiCompatClient } from "./client.js";
+export { createDeepSeekLlm, createDeepSeekRegistry, DEEPSEEK_PROVIDER_NAME, LlmRegistry, } from "./provider.js";
+export { collectMessageParts, dataUrlFor, messageImageRefs, messagesHaveImages, resolvedImagesOf, wireMessagesFor, } from "./wire.js";
+export { createImageDowngradeLlm, imagePlaceholderText, withImagePlaceholders } from "./image-fallback.js";

package/dist/profile.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Provider profile -> client configuration (P2a).
+ *
+ * Mirrors `crates/runtime/src/compose.rs` (the DeepSeekConfig assembly):
+ * base_url = profile > DEEPSEEK_BASE_URL env > default; model from the profile;
+ * reasoning_effort passed through verbatim; timeouts resolved from the profile
+ * keys with the CELESTEA_LLM_* env vars taking precedence.
+ *
+ * The API key is read from the runtime configuration / environment ONLY. It is
+ * never written to disk, never logged, and never echoed into an error message
+ * or a serialized view (see OpenAiCompatClient.describe()).
+ */
+import { type EnvLike, type TimeoutProfile, type TimeoutTiers } from "./timeouts.js";
+/** Environment variable holding the provider API key. */
+export declare const API_KEY_ENV = "DEEPSEEK_API_KEY";
+/** Environment variable overriding the provider base URL. */
+export declare const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
+export declare const DEFAULT_BASE_URL = "https://api.deepseek.com";
+export declare const DEFAULT_MODEL = "deepseek-chat";
+/** The runtime profile subset this package consumes. */
+export interface LlmProfile extends TimeoutProfile {
+    model?: string | null;
+    base_url?: string | null;
+    /** Free-form tier string, injected into the request body verbatim. */
+    reasoning_effort?: string | null;
+    max_output_tokens?: number | null;
+    /** Name of the env var holding the API key (default DEEPSEEK_API_KEY). */
+    api_key_env?: string | null;
+}
+/** Fully resolved client configuration (carries the key; never logged). */
+export interface ResolvedClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** Free-form tier string, passed through verbatim (never folded/renamed). */
+    reasoningEffort: string | null;
+    maxOutputTokens: number | null;
+    /** 0 = that stage is disabled (same convention as the profile/env keys). */
+    connectTimeoutMs: number;
+    responseTimeoutMs: number;
+    streamIdleTimeoutMs: number;
+}
+/** The tiers as configured (null = disabled), derived from resolved ms values. */
+export declare function tiersFromConfig(config: ResolvedClientConfig): TimeoutTiers;
+/**
+ * Resolve the API key from the environment ONLY (`api_key_env` names the var).
+ * Returns null when unset/blank. This package never reads key files: that is
+ * the runtime's job (`resolve_api_key` in crates/runtime).
+ */
+export declare function resolveApiKey(profile?: LlmProfile | null, env?: EnvLike): string | null;
+/** Compose the effective client config from a runtime profile + environment. */
+export declare function resolveClientConfig(profile?: LlmProfile | null, env?: EnvLike): ResolvedClientConfig;
+/**
+ * reasoning_effort is a FREE STRING: user-defined tiers ("max",
+ * "xhigh-custom", provider-specific labels) reach the upstream exactly as
+ * written. Only null/undefined means "not configured" — no trimming, no
+ * folding onto an enum, no renaming.
+ */
+export declare function normalizeReasoningEffort(v: string | null | undefined): string | null;
+/**
+ * Model names are free-form: the OpenAI-compatible endpoint decides its own
+ * catalog (a local shim may expose deepseek-v4-flash), so the only hard rule is
+ * that a model must be supplied.
+ */
+export declare function validateModel(model: string): void;