@celestea/runtime 2.7.1

package/dist/inbox.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SessionInbox — the per-session delivery queue with TWO LANES (W513 + W515 §1).
+ *
+ * One inbox per session runtime instance. It is the ONE place a message can be
+ * delivered into a session, and the lane it lands in decides WHEN it is seen:
+ *
+ *   - `next-turn` — drained by the turn driver at the TURN START, before the
+ *     turn's own input (a follow-up sent while the session is idle; a receipt
+ *     that arrived while nothing was running). Reported as `placement: "queued"`.
+ *   - `next-step` — drained by the loop at EVERY STEP BOUNDARY, right before the
+ *     next model call (a user interjection sent while the turn is running; a
+ *     receipt that arrives mid-turn). Reported as `placement: "steering"`.
+ *
+ * Invariants:
+ *   - a message with an `id` already accepted is DROPPED as a duplicate (a
+ *     receipt delivered twice is injected once);
+ *   - while `next-step` is non-empty the turn must not reach its terminal state
+ *     (enforced by the loop, see `@celestea/agent-loop`);
+ *   - both transport paths (a host API call and a session-mailbox receipt) end
+ *     in the same lanes, so the injection mechanism is literally the same one.
+ *
+ * The two hooks (`onQueued`, `onDelivered`) let the host publish the placement
+ * over SSE without the inbox knowing anything about a transport.
+ *
+ * E §1.3 P1 ①: the lanes and the dedup ledger are PERSISTABLE. `bindPersistence`
+ * attaches a sink (the session's `checkpoint.json`, see `inbox-checkpoint.ts`);
+ * binding RESTORES whatever the previous process left queued and then writes on
+ * every change, so "accepted but not yet injected" survives a crash — the
+ * G1-4 failure mode, where a user's message vanished silently.
+ *
+ * Restoration is DELIBERATELY silent (no `onQueued` hook): a message queued by a
+ * process that died was already announced by that process, and re-announcing it
+ * would show the client a placement that did not change.
+ */
+import type { DeliverySource, InjectionKind, InjectionLane, InjectionPlacement } from "@celestea/core";
+/** One message waiting to be appended to the session log. */
+export interface InjectedMessage {
+    text: string;
+    /** Attribution label (`""` = the user, otherwise `[from <label>] text`). */
+    from: string;
+    /** Arrival time (diagnostics / tests). */
+    at: number;
+    /** Lane the message waits in. */
+    lane: InjectionLane;
+    kind: InjectionKind;
+    /** Idempotency key (`""` = never deduplicated). */
+    id: string;
+    /** Envelope, so a settlement notice is not mistaken for a deliberate relay. */
+    source: DeliverySource;
+    /** True when this push was dropped because the id was already accepted. */
+    duplicate: boolean;
+}
+export interface InboxHooks {
+    /** A message was accepted into a lane (placement `queued` / `steering`). */
+    onQueued?: (message: InjectedMessage, placement: InjectionPlacement) => void;
+    /** A message left a lane and is now part of the model-visible log. */
+    onDelivered?: (message: InjectedMessage) => void;
+}
+export interface SessionInbox {
+    /** Move one message into `lane`; a duplicate id is dropped (`duplicate: true`). */
+    push(text: string, lane: InjectionLane, opts?: InboxPushOptions): InjectedMessage;
+    /** Take everything waiting in one lane, in arrival order. */
+    drain(lane: InjectionLane): InjectedMessage[];
+    /** Messages waiting (one lane, or both). */
+    pending(lane?: InjectionLane): number;
+    /** E §1.3 P1 ①: restore from, and persist every change to, `sink`. */
+    bindPersistence(sink: InboxSink): void;
+    /** The persistable state: both lanes plus the bounded delivered-id ledger. */
+    snapshot(): InboxSnapshot;
+}
+/** Both lanes plus the accepted-id memory, exactly as they persist. */
+export interface InboxSnapshot {
+    next_turn: InjectedMessage[];
+    next_step: InjectedMessage[];
+    delivered_ids: string[];
+}
+/** Where a snapshot goes (the session's checkpoint sidecar in production). */
+export interface InboxSink {
+    /** The snapshot of the PREVIOUS process, or null when there is none usable. */
+    load(): InboxSnapshot | null;
+    save(snapshot: InboxSnapshot): void;
+}
+export interface InboxPushOptions {
+    from?: string;
+    id?: string;
+    kind?: InjectionKind;
+    source?: DeliverySource;
+}
+/** How many ids are remembered for duplicate detection (bounded memory). */
+export declare const DELIVERED_ID_MEMORY = 512;
+/** Placement a lane implies, before the drain: queued vs steering. */
+export declare function placementOfLane(lane: InjectionLane): InjectionPlacement;
+/** Build one inbox; `now` and the placement hooks are injectable. */
+export declare function createSessionInbox(now?: () => number, hooks?: InboxHooks): SessionInbox;

package/dist/inbox.js

@@ -0,0 +1,139 @@
+/**
+ * SessionInbox — the per-session delivery queue with TWO LANES (W513 + W515 §1).
+ *
+ * One inbox per session runtime instance. It is the ONE place a message can be
+ * delivered into a session, and the lane it lands in decides WHEN it is seen:
+ *
+ *   - `next-turn` — drained by the turn driver at the TURN START, before the
+ *     turn's own input (a follow-up sent while the session is idle; a receipt
+ *     that arrived while nothing was running). Reported as `placement: "queued"`.
+ *   - `next-step` — drained by the loop at EVERY STEP BOUNDARY, right before the
+ *     next model call (a user interjection sent while the turn is running; a
+ *     receipt that arrives mid-turn). Reported as `placement: "steering"`.
+ *
+ * Invariants:
+ *   - a message with an `id` already accepted is DROPPED as a duplicate (a
+ *     receipt delivered twice is injected once);
+ *   - while `next-step` is non-empty the turn must not reach its terminal state
+ *     (enforced by the loop, see `@celestea/agent-loop`);
+ *   - both transport paths (a host API call and a session-mailbox receipt) end
+ *     in the same lanes, so the injection mechanism is literally the same one.
+ *
+ * The two hooks (`onQueued`, `onDelivered`) let the host publish the placement
+ * over SSE without the inbox knowing anything about a transport.
+ *
+ * E §1.3 P1 ①: the lanes and the dedup ledger are PERSISTABLE. `bindPersistence`
+ * attaches a sink (the session's `checkpoint.json`, see `inbox-checkpoint.ts`);
+ * binding RESTORES whatever the previous process left queued and then writes on
+ * every change, so "accepted but not yet injected" survives a crash — the
+ * G1-4 failure mode, where a user's message vanished silently.
+ *
+ * Restoration is DELIBERATELY silent (no `onQueued` hook): a message queued by a
+ * process that died was already announced by that process, and re-announcing it
+ * would show the client a placement that did not change.
+ */
+/** How many ids are remembered for duplicate detection (bounded memory). */
+export const DELIVERED_ID_MEMORY = 512;
+/** Placement a lane implies, before the drain: queued vs steering. */
+export function placementOfLane(lane) {
+    return lane === "next-step" ? "steering" : "queued";
+}
+/** Build one inbox; `now` and the placement hooks are injectable. */
+export function createSessionInbox(now = Date.now, hooks = {}) {
+    const lanes = { "next-turn": [], "next-step": [] };
+    const seen = [];
+    const seenSet = new Set();
+    let sink = null;
+    /** Bounded FIFO memory of accepted ids (oldest evicted first). */
+    const remember = (id) => {
+        if (id === "" || !seenSet.has(id)) {
+            if (id !== "") {
+                seenSet.add(id);
+                seen.push(id);
+                if (seen.length > DELIVERED_ID_MEMORY) {
+                    const oldest = seen.shift();
+                    if (oldest !== undefined)
+                        seenSet.delete(oldest);
+                }
+            }
+            return false;
+        }
+        return true;
+    };
+    const snapshot = () => ({
+        next_turn: lanes["next-turn"].map((m) => ({ ...m })),
+        next_step: lanes["next-step"].map((m) => ({ ...m })),
+        delivered_ids: [...seen],
+    });
+    const save = () => {
+        try {
+            sink?.save(snapshot());
+        }
+        catch (e) {
+            // Persistence is observation: a sidecar that cannot be written must never
+            // lose the message that is still safely in memory (the checkpoint's rule).
+            process.stderr.write(`[celestea-runtime] inbox not persisted: ${String(e)}\n`);
+        }
+    };
+    const restore = (state) => {
+        for (const message of state.next_turn)
+            lanes["next-turn"].push(message);
+        for (const message of state.next_step)
+            lanes["next-step"].push(message);
+        // A restored message was ALREADY accepted once: re-remembering its id keeps
+        // the duplicate rule valid across the restart (and across processes).
+        for (const message of [...lanes["next-turn"], ...lanes["next-step"]])
+            remember(message.id);
+        for (const id of state.delivered_ids)
+            remember(id);
+    };
+    return {
+        bindPersistence(next) {
+            sink = next;
+            // Fail-safe on BOTH sides: an unreadable queue is an EMPTY queue (the same
+            // discipline the recovery decision table uses) — a broken sidecar must
+            // never stop a session from composing.
+            try {
+                const state = next.load();
+                if (state !== null)
+                    restore(state);
+            }
+            catch (e) {
+                process.stderr.write(`[celestea-runtime] inbox not restored: ${String(e)}\n`);
+            }
+        },
+        snapshot,
+        push(text, lane, opts = {}) {
+            const id = opts.id ?? "";
+            const message = {
+                text,
+                from: opts.from ?? "",
+                at: now(),
+                lane,
+                kind: opts.kind ?? "user",
+                id,
+                source: opts.source ?? { kind: "user", form: "message" },
+                duplicate: remember(id),
+            };
+            if (!message.duplicate) {
+                lanes[lane].push(message);
+                save();
+                hooks.onQueued?.(message, placementOfLane(lane));
+            }
+            return message;
+        },
+        drain(lane) {
+            const taken = lanes[lane].splice(0, lanes[lane].length);
+            if (taken.length > 0)
+                save();
+            for (const message of taken)
+                hooks.onDelivered?.(message);
+            return taken;
+        },
+        pending(lane) {
+            if (lane !== undefined)
+                return lanes[lane].length;
+            return lanes["next-turn"].length + lanes["next-step"].length;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `@celestea/runtime` — the assembly layer (L2): `compose(profile)` mounts every
+ * plugin into one `Context` and hands back a wired, runnable engine generation.
+ *
+ * Responsibility: assembly (plugin mount order, seam resolution, sanitized
+ * config), lifecycle (hot swap, session rebind, idempotent shutdown, explicit
+ * release), turn driving (single concurrency slot, frame stream,
+ * cancellation, terminal state from the log), and the statusline
+ * (`StatusTracker` + `UsageTracker`).
+ *
+ * Dependency direction: runtime -> core + L1 packages. Assembly stays
+ * injection-based (the concrete agent loop arrives through
+ * `ComposeConfig.loopFactory`, the frame mapper through `frameMapper`, the
+ * session log through `sessionBinding`/plugins, and the worker registry either
+ * through a host plugin or the built-in worker wiring); the two L1 edges this
+ * package does import are the worker seam (`@celestea/workers`) and the
+ * session-log/checkpoint contract (`@celestea/session`, E §1.3 P0).
+ *
+ * Module map (legacy -> TS):
+ *   profile.ts         frozen 12-key profile + compose step list  (runtime/config.rs)
+ *   agent-config.ts    profile -> AgentConfig + step floor       (compose.rs:196-204)
+ *   sanitize.ts        sanitized config projection for /api/config
+ *   usage.ts           UsageTracker (latest/total/cache_hit_ratio) (agent-loop/loop.rs)
+ *   status.ts          StatusTracker + statusline payload        (studio/main.rs:253-620)
+ *   frames.ts          LoopEvent -> SSE frame mapping            (studio/main.rs:667-713)
+ *   session-binding.ts session id/dir + log opener + rebind      (compose.rs:131-146)
+ *   turn-runner.ts     one turn: busy slot, sink, cancel, outcome (runtime/run.rs)
+ *   inbox.ts           per-session mid-turn injection queue      (W513)
+ *   inbox-checkpoint.ts W787: queue + delivered ids -> checkpoint.json (§1.3 P1)
+ *   session-registry.ts session id -> independent Runtime        (W513)
+ *   worker-wiring.ts   worker driver seams + host receipt drain  (compose.rs:148-193)
+ *   watchdog-mount.ts  W740: mount the liveness watchdog (workers/watchdog.ts)
+ *   runtime.ts         Runtime handles + lifecycle               (compose.rs:44-281)
+ *   recovery.ts        boot recovery: close a turn a crash left open (E §1.3)
+ *   gen.ts             Gen + GenerationHub (hot swap)            (studio/main.rs:340-420)
+ *   compose.ts         compose(config) — mount order             (runtime/compose.rs)
+ *   host/              W747: the ENGINE-side host assembly (log/binding +
+ *                      provider targeting); see host/index.ts (apps/studio/src/runtime)
+ *   compact/           context compaction (W259)                 (studio/src/compact.rs)
+ *   tokens.ts          runtime service tokens
+ *   errors.ts          TurnBusyError / RuntimeReleasedError / ComposeError
+ *
+ * Public API = this file. Everything else is an internal module.
+ */
+export * from "./profile.js";
+export * from "./tokens.js";
+export * from "./errors.js";
+export * from "./agent-config.js";
+export * from "./sanitize.js";
+export * from "./usage.js";
+export * from "./pricing.js";
+export * from "./ledger.js";
+export * from "./ledger-llm.js";
+export * from "./ledger-query.js";
+export * from "./status.js";
+export * from "./frames.js";
+export * from "./session-binding.js";
+export * from "./retention.js";
+export * from "./turn-runner.js";
+export * from "./inbox.js";
+export * from "./inbox-checkpoint.js";
+export * from "./session-registry.js";
+export * from "./recovery.js";
+export * from "./worker-wiring.js";
+export * from "./watchdog-mount.js";
+export * from "./runtime.js";
+export * from "./gen.js";
+export * from "./autowake.js";
+export * from "./compose.js";
+export * from "./host/index.js";
+export * from "./compact/index.js";

package/dist/index.js

@@ -0,0 +1,71 @@
+/**
+ * `@celestea/runtime` — the assembly layer (L2): `compose(profile)` mounts every
+ * plugin into one `Context` and hands back a wired, runnable engine generation.
+ *
+ * Responsibility: assembly (plugin mount order, seam resolution, sanitized
+ * config), lifecycle (hot swap, session rebind, idempotent shutdown, explicit
+ * release), turn driving (single concurrency slot, frame stream,
+ * cancellation, terminal state from the log), and the statusline
+ * (`StatusTracker` + `UsageTracker`).
+ *
+ * Dependency direction: runtime -> core + L1 packages. Assembly stays
+ * injection-based (the concrete agent loop arrives through
+ * `ComposeConfig.loopFactory`, the frame mapper through `frameMapper`, the
+ * session log through `sessionBinding`/plugins, and the worker registry either
+ * through a host plugin or the built-in worker wiring); the two L1 edges this
+ * package does import are the worker seam (`@celestea/workers`) and the
+ * session-log/checkpoint contract (`@celestea/session`, E §1.3 P0).
+ *
+ * Module map (legacy -> TS):
+ *   profile.ts         frozen 12-key profile + compose step list  (runtime/config.rs)
+ *   agent-config.ts    profile -> AgentConfig + step floor       (compose.rs:196-204)
+ *   sanitize.ts        sanitized config projection for /api/config
+ *   usage.ts           UsageTracker (latest/total/cache_hit_ratio) (agent-loop/loop.rs)
+ *   status.ts          StatusTracker + statusline payload        (studio/main.rs:253-620)
+ *   frames.ts          LoopEvent -> SSE frame mapping            (studio/main.rs:667-713)
+ *   session-binding.ts session id/dir + log opener + rebind      (compose.rs:131-146)
+ *   turn-runner.ts     one turn: busy slot, sink, cancel, outcome (runtime/run.rs)
+ *   inbox.ts           per-session mid-turn injection queue      (W513)
+ *   inbox-checkpoint.ts W787: queue + delivered ids -> checkpoint.json (§1.3 P1)
+ *   session-registry.ts session id -> independent Runtime        (W513)
+ *   worker-wiring.ts   worker driver seams + host receipt drain  (compose.rs:148-193)
+ *   watchdog-mount.ts  W740: mount the liveness watchdog (workers/watchdog.ts)
+ *   runtime.ts         Runtime handles + lifecycle               (compose.rs:44-281)
+ *   recovery.ts        boot recovery: close a turn a crash left open (E §1.3)
+ *   gen.ts             Gen + GenerationHub (hot swap)            (studio/main.rs:340-420)
+ *   compose.ts         compose(config) — mount order             (runtime/compose.rs)
+ *   host/              W747: the ENGINE-side host assembly (log/binding +
+ *                      provider targeting); see host/index.ts (apps/studio/src/runtime)
+ *   compact/           context compaction (W259)                 (studio/src/compact.rs)
+ *   tokens.ts          runtime service tokens
+ *   errors.ts          TurnBusyError / RuntimeReleasedError / ComposeError
+ *
+ * Public API = this file. Everything else is an internal module.
+ */
+export * from "./profile.js";
+export * from "./tokens.js";
+export * from "./errors.js";
+export * from "./agent-config.js";
+export * from "./sanitize.js";
+export * from "./usage.js";
+export * from "./pricing.js";
+export * from "./ledger.js";
+export * from "./ledger-llm.js";
+export * from "./ledger-query.js";
+export * from "./status.js";
+export * from "./frames.js";
+export * from "./session-binding.js";
+export * from "./retention.js";
+export * from "./turn-runner.js";
+export * from "./inbox.js";
+export * from "./inbox-checkpoint.js";
+export * from "./session-registry.js";
+export * from "./recovery.js";
+export * from "./worker-wiring.js";
+export * from "./watchdog-mount.js";
+export * from "./runtime.js";
+export * from "./gen.js";
+export * from "./autowake.js";
+export * from "./compose.js";
+export * from "./host/index.js";
+export * from "./compact/index.js";

package/dist/ledger-io.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Internal helpers of the usage ledger (W836 R3 batch F), split out so
+ * `ledger.ts` stays inside the repository file budget:
+ *   - [readLedgerRecords] parses ONE ledger file (current or rolled `.1`);
+ *   - [LedgerKeySet] is the BOUNDED idempotency-key memory (P2-5): keys are
+ *     evicted per closed turn, with a size cap as the backstop.
+ */
+/** Every readable record of one ledger path (an unparsable line is skipped). */
+export declare function readLedgerRecords<T>(path: string): T[];
+/** Bounded in-process idempotency keys: per-turn eviction + a size cap. */
+export declare class LedgerKeySet {
+    private readonly max;
+    private readonly keys;
+    constructor(max: number);
+    /** True when this writer already booked the key (the row must be skipped). */
+    has(key: string): boolean;
+    /** Size of the memory (bounded-memory diagnostics / tests). */
+    get size(): number;
+    /** Remember one booked key, trimming the OLDEST keys past the cap. */
+    add(key: string): void;
+    /**
+     * Drop the keys of ONE closed turn: an in-flight turn keeps its keys, so a
+     * duplicate step booked while it is still open is still refused. A `null`
+     * turn id (an out-of-turn row) is left to the size cap.
+     */
+    evictTurn(session: string, turnId: string | null): void;
+}

package/dist/ledger-io.js

@@ -0,0 +1,74 @@
+/**
+ * Internal helpers of the usage ledger (W836 R3 batch F), split out so
+ * `ledger.ts` stays inside the repository file budget:
+ *   - [readLedgerRecords] parses ONE ledger file (current or rolled `.1`);
+ *   - [LedgerKeySet] is the BOUNDED idempotency-key memory (P2-5): keys are
+ *     evicted per closed turn, with a size cap as the backstop.
+ */
+import { readFileSync } from "node:fs";
+/** Every readable record of one ledger path (an unparsable line is skipped). */
+export function readLedgerRecords(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed === "object" && parsed !== null)
+                out.push(parsed);
+        }
+        catch {
+            // A torn/foreign line never hides the rows around it.
+        }
+    }
+    return out;
+}
+/** Bounded in-process idempotency keys: per-turn eviction + a size cap. */
+export class LedgerKeySet {
+    max;
+    keys = new Set();
+    constructor(max) {
+        this.max = max;
+    }
+    /** True when this writer already booked the key (the row must be skipped). */
+    has(key) {
+        return this.keys.has(key);
+    }
+    /** Size of the memory (bounded-memory diagnostics / tests). */
+    get size() {
+        return this.keys.size;
+    }
+    /** Remember one booked key, trimming the OLDEST keys past the cap. */
+    add(key) {
+        this.keys.add(key);
+        if (this.keys.size <= this.max)
+            return;
+        let excess = this.keys.size - this.max;
+        for (const key2 of this.keys) {
+            if (excess <= 0)
+                break;
+            this.keys.delete(key2);
+            excess -= 1;
+        }
+    }
+    /**
+     * Drop the keys of ONE closed turn: an in-flight turn keeps its keys, so a
+     * duplicate step booked while it is still open is still refused. A `null`
+     * turn id (an out-of-turn row) is left to the size cap.
+     */
+    evictTurn(session, turnId) {
+        if (turnId === null)
+            return;
+        const prefix = `${session}|${turnId}|`;
+        for (const key of this.keys)
+            if (key.startsWith(prefix))
+                this.keys.delete(key);
+    }
+}

package/dist/ledger-llm.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The `Llm` step observer (iteration E §3.2.3, W728 P0) — one ledger step per
+ * model call, including the calls that FAIL.
+ *
+ * A decorator, not a new seam: `generate` and every stream event pass through
+ * byte-for-byte unchanged, and a rejection is re-thrown untouched. What it adds
+ * is the two facts only this seam can see:
+ *   - the step BOUNDARIES (a stream that tears after a usage frame is one error
+ *     row, not an ok row plus an error row, §3.2.3);
+ *   - the structured failure cause — W723's `LlmError.httpStatus/retryable`
+ *     (`packages/llm/src/errors.ts`), read structurally so this package keeps
+ *     importing nothing from `@celestea/llm` (runtime composes L1, it does not
+ *     depend on it).
+ *
+ * This is observation only: failures and retries book a row, they never change
+ * what the engine does with the response (§3.5, "纯新增观测").
+ */
+import type { Llm } from "@celestea/core";
+import type { LedgerStepOutcome, LedgerStepSink } from "./ledger.js";
+/** What the observer knows about the target it wraps (config, not per-call). */
+export interface LedgerLlmOptions {
+    inner: Llm;
+    sink: LedgerStepSink;
+    /** Provider row id (`providers.json`), when the host resolved one. */
+    provider?: string | null;
+    /** Model of the composed profile; the request's own model wins per call. */
+    model?: string | null;
+    base_url_host?: string | null;
+    /** 0 = first attempt (§5.2); P1's fallback decorator passes the real value. */
+    attempt?: number;
+    /** Target name this attempt failed over from (P1); null in P0. */
+    fallback_from?: string | null;
+}
+/** Wrap one `Llm` so every model step is booked (success, failure and abort). */
+export declare function createLedgerLlm(opts: LedgerLlmOptions): Llm;
+/**
+ * The structured failure of a thrown value. W723's `LlmError` carries
+ * `kind`/`httpStatus`/`retryable`; anything else is an unclassified local
+ * failure, reported as the turn-outcome kind the loop will use ("generate").
+ */
+export declare function failureOf(error: unknown): LedgerStepOutcome;
+/** A mid-stream terminal failure: no HTTP status exists (the response was 2xx). */
+export declare function streamFailure(event: {
+    kindOf: string;
+    message: string;
+}): LedgerStepOutcome;
+/** 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/ledger-llm.js

@@ -0,0 +1,115 @@
+/**
+ * The `Llm` step observer (iteration E §3.2.3, W728 P0) — one ledger step per
+ * model call, including the calls that FAIL.
+ *
+ * A decorator, not a new seam: `generate` and every stream event pass through
+ * byte-for-byte unchanged, and a rejection is re-thrown untouched. What it adds
+ * is the two facts only this seam can see:
+ *   - the step BOUNDARIES (a stream that tears after a usage frame is one error
+ *     row, not an ok row plus an error row, §3.2.3);
+ *   - the structured failure cause — W723's `LlmError.httpStatus/retryable`
+ *     (`packages/llm/src/errors.ts`), read structurally so this package keeps
+ *     importing nothing from `@celestea/llm` (runtime composes L1, it does not
+ *     depend on it).
+ *
+ * This is observation only: failures and retries book a row, they never change
+ * what the engine does with the response (§3.5, "纯新增观测").
+ */
+/** Wrap one `Llm` so every model step is booked (success, failure and abort). */
+export function createLedgerLlm(opts) {
+    return {
+        async generate(req) {
+            const step = opts.sink.beginStep({
+                provider: opts.provider ?? null,
+                model: req.model === "" ? (opts.model ?? null) : req.model,
+                base_url_host: opts.base_url_host ?? null,
+                attempt: opts.attempt ?? 0,
+                fallback_from: opts.fallback_from ?? null,
+            });
+            let stream;
+            try {
+                stream = await opts.inner.generate(req);
+            }
+            catch (error) {
+                step.close(failureOf(error));
+                throw error;
+            }
+            return observeStep(stream, step);
+        },
+    };
+}
+/** The stream of one step, forwarded unchanged and closed exactly once. */
+function observeStep(stream, step) {
+    const inner = stream[Symbol.asyncIterator]();
+    const iterator = {
+        async next() {
+            let result;
+            try {
+                result = await inner.next();
+            }
+            catch (error) {
+                step.close(failureOf(error));
+                throw error;
+            }
+            if (result.done === true) {
+                step.close({ kind: "ok" });
+                return result;
+            }
+            const event = result.value;
+            if (event.kind === "usage")
+                step.record(event.usage);
+            else if (event.kind === "failed")
+                step.close(streamFailure(event));
+            else if (event.kind === "interrupted")
+                step.close({ kind: "error", error_kind: "stream" });
+            return result;
+        },
+        async return() {
+            // The consumer abandoned the step (cancel/close): whatever usage it
+            // already produced is real money and keeps its row (§3.2.3 "取消").
+            step.close({ kind: "ok" });
+            await inner.return?.();
+            return { done: true, value: undefined };
+        },
+    };
+    return { [Symbol.asyncIterator]: () => iterator };
+}
+/**
+ * The structured failure of a thrown value. W723's `LlmError` carries
+ * `kind`/`httpStatus`/`retryable`; anything else is an unclassified local
+ * failure, reported as the turn-outcome kind the loop will use ("generate").
+ */
+export function failureOf(error) {
+    const rec = typeof error === "object" && error !== null ? error : {};
+    const kind = rec["kind"];
+    const status = rec["httpStatus"];
+    const retryable = rec["retryable"];
+    return {
+        kind: "error",
+        error_kind: typeof kind === "string" ? kind : "generate",
+        http_status: typeof status === "number" ? status : null,
+        retryable: typeof retryable === "boolean" ? retryable : null,
+    };
+}
+/** A mid-stream terminal failure: no HTTP status exists (the response was 2xx). */
+export function streamFailure(event) {
+    return {
+        kind: "error",
+        error_kind: event.kindOf,
+        http_status: null,
+        // The canonical timeout prefix survives into the message (W511/W723), so an
+        // idle-stall is still recognisable as retryable.
+        retryable: event.message.startsWith("llm timeout") ? true : null,
+    };
+}
+/** 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;
+    }
+}