@celestea/studio 2.7.1

package/dist/runtime/host-autowake.js

@@ -0,0 +1,86 @@
+/**
+ * W769 — the studio host's auto-wake wiring.
+ *
+ * The loop itself is `@celestea/runtime`'s `AutowakeLoop` (mailbox → busy check →
+ * wake). This module owns the studio-specific part: WHICH conversations have a
+ * loop (one per host session, keyed by session id / `cli-main` for the detached
+ * generation) and how the loop reads the state of the generation in force.
+ *
+ * It lives outside the adapter on purpose: `real-runtime-adapter.ts` sits at the
+ * eslint size budget, and "which sessions can be woken" is a policy of its own —
+ * a worker's receipt is addressed to the session that spawned it, so the set of
+ * queues that can carry one is exactly the set of live host sessions.
+ */
+import { AutowakeLoop, HOST_SESSION_ID, keyOfSession } from "@celestea/runtime";
+/** Mailbox + busy + the USER's next-turn lane depth, from one entry (or null). */
+export function autowakeStateOf(entry) {
+    return entry === null
+        ? null
+        : {
+            mailbox: entry.runtime.workers?.mailbox ?? null,
+            busy: entry.inFlight,
+            userPending: entry.runtime.pendingInjections("next-turn"),
+        };
+}
+/** The studio's log line for auto-wake decisions (stderr, like boot recovery). */
+export function autowakeLog(session, line) {
+    process.stderr.write(`[celestea-studio-ts] autowake ${session ?? HOST_SESSION_ID}: ${line}\n`);
+}
+export class HostAutowake {
+    loops = new Map();
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Is auto-wake on? (`CELESTEA_AUTOWAKE`, default on.) */
+    get running() {
+        return this.opts.enabled;
+    }
+    /** Live loops (diagnostics / tests). */
+    get count() {
+        return this.loops.size;
+    }
+    /**
+     * Mount the (idempotent) loop of one host conversation. Called from the
+     * generation's build callback: the hooks read the CURRENT entry on every pass,
+     * so a rebuilt instance is picked up without re-mounting anything.
+     */
+    ensure(session) {
+        if (!this.opts.enabled)
+            return;
+        const key = keyOfSession(session);
+        if (this.loops.has(key))
+            return;
+        const loop = new AutowakeLoop({
+            queueKey: session ?? HOST_SESSION_ID,
+            mailbox: () => this.opts.lookup(session)?.mailbox ?? null,
+            isBusy: () => this.opts.lookup(session)?.busy ?? false,
+            userPending: () => this.opts.lookup(session)?.userPending ?? 0,
+            wake: (input) => this.opts.wake(session, input),
+            log: (line) => autowakeLog(session, line),
+        });
+        this.loops.set(key, loop);
+        loop.start();
+    }
+    /**
+     * W794: a DELETED session never comes back under that id, so its loop is
+     * unparked for good — otherwise it keeps re-binding to a generation that can
+     * never exist again and re-logs `no live generation to bind` forever (the
+     * timer is real). A rebuild / idle eviction must NOT call this: the same id
+     * recomposes, and its loop has to be waiting for it. Idempotent.
+     */
+    async forget(session) {
+        const key = keyOfSession(session);
+        const loop = this.loops.get(key);
+        if (loop === undefined)
+            return;
+        this.loops.delete(key);
+        await loop.stop();
+    }
+    /** Unpark every loop (process shutdown; idempotent). */
+    async stop() {
+        const loops = [...this.loops.values()];
+        this.loops.clear();
+        await Promise.all(loops.map((loop) => loop.stop()));
+    }
+}

package/dist/runtime/image-downgrade.d.ts

@@ -0,0 +1,49 @@
+/**
+ * W804 (multimodal P0 section 7.6): the host-visible report of ONE image
+ * downgrade. Extracted from the runtime adapter so that file stays inside its
+ * line budget.
+ *
+ * Three channels: a `status` frame (the statusline and the info block share it)
+ * and an audit line on the process log. The turn itself is NOT failed.
+ *
+ * W863: the report is DEDUPLICATED per session. The decorator fires on EVERY
+ * image-bearing request (`packages/llm/src/image-fallback.ts`), and a multi-step
+ * turn re-sends the same history image at every step — so one turn used to emit
+ * N identical frames and the UI stacked N identical blocks. The memo below
+ * lives in a per-adapter reporter (never module state): one entry per session,
+ * keyed by the (model, cause) signature that defines "this is NEWS".
+ */
+import type { ImageDowngradeInfo } from "@celestea/llm";
+import type { StudioBus } from "../sse.js";
+/**
+ * W863: the dedupe signature of one downgrade — exactly the (model, cause) pair
+ * the requirement fixes. `cause` is normalized the same way `copyOf` does, so a
+ * pre-W855 producer (cause absent) and an explicit `upstream_rejected` are the
+ * SAME signature. Deliberately NOT keyed on httpStatus/message/placeholder: for
+ * one (model, cause) the visible copy is identical in shape, and the verbatim
+ * upstream body is not what the user acts on.
+ */
+export declare function downgradeSignature(info: ImageDowngradeInfo): string;
+/** One reporter per host adapter: the per-session memo + the two channels. */
+export interface ImageDowngradeReporter {
+    /** Returns true when this report was NEW (emitted + audited), false when deduped. */
+    report(sessionId: string | null, info: ImageDowngradeInfo): boolean;
+}
+/**
+ * W863 (§A): make the host report ONE downgrade per session per (model, cause).
+ *   - every later frame with the same signature is swallowed ENTIRELY (no emit
+ *     AND no audit line: the process log must never claim what the UI did not
+ *     show);
+ *   - a new model or a new cause is news again (the user must see that the
+ *     situation changed);
+ *   - `sessionId` is the partition key (`null` = the detached session), so two
+ *     sessions never silence each other. State is per reporter instance and JS
+ *     is single-threaded, so there is no cross-session race to guard.
+ * Scope is the SESSION (not the turn): see the W863 report for the boundary.
+ */
+export declare function createImageDowngradeReporter(deps: {
+    bus: () => StudioBus | null;
+    /** Audit sink (defaults to console.warn); injected so tests can count lines. */
+    warn?: (line: string) => void;
+}): ImageDowngradeReporter;
+export declare function reportImageDowngrade(bus: StudioBus | null, sessionId: string | null, info: ImageDowngradeInfo, warn?: (line: string) => void): void;

package/dist/runtime/image-downgrade.js

@@ -0,0 +1,90 @@
+/**
+ * W804 (multimodal P0 section 7.6): the host-visible report of ONE image
+ * downgrade. Extracted from the runtime adapter so that file stays inside its
+ * line budget.
+ *
+ * Three channels: a `status` frame (the statusline and the info block share it)
+ * and an audit line on the process log. The turn itself is NOT failed.
+ *
+ * W863: the report is DEDUPLICATED per session. The decorator fires on EVERY
+ * image-bearing request (`packages/llm/src/image-fallback.ts`), and a multi-step
+ * turn re-sends the same history image at every step — so one turn used to emit
+ * N identical frames and the UI stacked N identical blocks. The memo below
+ * lives in a per-adapter reporter (never module state): one entry per session,
+ * keyed by the (model, cause) signature that defines "this is NEWS".
+ */
+/** W855: the user-facing message + executable hint of one downgrade cause. */
+function copyOf(info, cause) {
+    if (cause === "timeout") {
+        return {
+            message: '模型 "' + info.model + '" 未在超时时间内响应图像输入，本轮已自动降级为「仅文本 + 图片占位」并重试；图片内容未送达模型（超时原文：' + info.message + '）。',
+            hint: '下一步：切换到支持图像输入的模型，或确认该模型 input_modalities 含 "image"；若上游持续超时，请检查网络/网关后重试。',
+        };
+    }
+    if (cause === "configured_text_only") {
+        return {
+            message: '模型 "' + info.model + '" 已按配置声明为纯文本（input_modalities 不含 "image"），本轮已自动降级为「仅文本 + 图片占位」，未向上游发送图像。',
+            hint: '下一步：确认该模型 input_modalities 含 "image" 才能接收图片；否则请切换到支持图像输入的模型。',
+        };
+    }
+    return {
+        message: '模型 "' + info.model + '" 拒绝了图像输入（上游 ' + String(info.httpStatus ?? 400) + '），本轮已自动降级为「仅文本 + 图片占位」继续，图片内容未送达模型。',
+        hint: '下一步：切换到支持图像输入的模型，或确认该模型 input_modalities 含 "image"；若确实不支持请设为 ["text"]。',
+    };
+}
+/**
+ * W863: the dedupe signature of one downgrade — exactly the (model, cause) pair
+ * the requirement fixes. `cause` is normalized the same way `copyOf` does, so a
+ * pre-W855 producer (cause absent) and an explicit `upstream_rejected` are the
+ * SAME signature. Deliberately NOT keyed on httpStatus/message/placeholder: for
+ * one (model, cause) the visible copy is identical in shape, and the verbatim
+ * upstream body is not what the user acts on.
+ */
+export function downgradeSignature(info) {
+    return info.model + "\u0000" + (info.cause ?? "upstream_rejected");
+}
+/**
+ * W863 (§A): make the host report ONE downgrade per session per (model, cause).
+ *   - every later frame with the same signature is swallowed ENTIRELY (no emit
+ *     AND no audit line: the process log must never claim what the UI did not
+ *     show);
+ *   - a new model or a new cause is news again (the user must see that the
+ *     situation changed);
+ *   - `sessionId` is the partition key (`null` = the detached session), so two
+ *     sessions never silence each other. State is per reporter instance and JS
+ *     is single-threaded, so there is no cross-session race to guard.
+ * Scope is the SESSION (not the turn): see the W863 report for the boundary.
+ */
+export function createImageDowngradeReporter(deps) {
+    const lastBySession = new Map();
+    const warn = deps.warn ?? ((line) => console.warn(line));
+    return {
+        report(sessionId, info) {
+            const key = sessionId ?? "";
+            const signature = downgradeSignature(info);
+            if (lastBySession.get(key) === signature)
+                return false;
+            lastBySession.set(key, signature);
+            reportImageDowngrade(deps.bus(), sessionId, info, warn);
+            return true;
+        },
+    };
+}
+export function reportImageDowngrade(bus, sessionId, info, warn = (line) => console.warn(line)) {
+    // W855: an absent cause = a pre-W855 producer -> the historical 400 wording.
+    const cause = info.cause ?? "upstream_rejected";
+    const { message, hint } = copyOf(info, cause);
+    bus?.emit("status", 0, {
+        phase: "error",
+        model: info.model,
+        reason: info.reason,
+        cause,
+        http_status: info.httpStatus,
+        message,
+        hint,
+        placeholder: info.placeholder,
+    }, sessionId);
+    // Audit: the process log (the session log keeps its frozen event vocabulary).
+    warn("[W804/W855] image downgrade session=" + (sessionId ?? "-") +
+        " model=" + info.model + " cause=" + cause + " status=" + String(info.httpStatus));
+}

package/dist/runtime/inbox-message.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalize a drained injection into the inbox shape the SSE publisher expects.
+ *
+ * The inbox's own message type is richer than the wire payload (`at`, defaulted
+ * `lane`/`kind`/`source`), and the host needs the WIRE shape to publish a
+ * `placement: "context"` frame (W515 §2). Keeping the mapping here — instead of
+ * inline in the adapter — keeps the adapter about the HTTP contract.
+ */
+import type { PendingInjection } from "@celestea/core";
+import type { InjectedMessage } from "@celestea/runtime";
+export declare function inboxMessageOf(message: PendingInjection): InjectedMessage;

package/dist/runtime/inbox-message.js

@@ -0,0 +1,20 @@
+/**
+ * Normalize a drained injection into the inbox shape the SSE publisher expects.
+ *
+ * The inbox's own message type is richer than the wire payload (`at`, defaulted
+ * `lane`/`kind`/`source`), and the host needs the WIRE shape to publish a
+ * `placement: "context"` frame (W515 §2). Keeping the mapping here — instead of
+ * inline in the adapter — keeps the adapter about the HTTP contract.
+ */
+export function inboxMessageOf(message) {
+    return {
+        text: message.text,
+        from: message.from,
+        at: 0,
+        lane: message.lane ?? "next-turn",
+        kind: message.kind ?? "user",
+        id: message.id ?? "",
+        source: message.source ?? { kind: "user", form: "message" },
+        duplicate: false,
+    };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The real engine assembly of `apps/studio` (P5 integration).
+ *
+ * `createRealRuntimeAdapter` is the production `RuntimeAdapter`: it composes
+ * `packages/runtime` (real agent loop + real tool registry + real session log)
+ * with an OFFLINE `Llm` seam, so the whole HTTP contract can be exercised end to
+ * end without a provider. The P4 fake adapter stays in
+ * `../fake-runtime-adapter.ts` for deterministic HTTP-layer tests.
+ */
+export * from "./engine-profile.js";
+export * from "./engine-session.js";
+export * from "./engine-plugins.js";
+export * from "./llm-assembly.js";
+export * from "./provider-target.js";
+export * from "./offline-llm.js";
+export * from "./worker-bridge.js";
+export * from "./real-runtime-adapter.js";

package/dist/runtime/index.js

@@ -0,0 +1,17 @@
+/**
+ * The real engine assembly of `apps/studio` (P5 integration).
+ *
+ * `createRealRuntimeAdapter` is the production `RuntimeAdapter`: it composes
+ * `packages/runtime` (real agent loop + real tool registry + real session log)
+ * with an OFFLINE `Llm` seam, so the whole HTTP contract can be exercised end to
+ * end without a provider. The P4 fake adapter stays in
+ * `../fake-runtime-adapter.ts` for deterministic HTTP-layer tests.
+ */
+export * from "./engine-profile.js";
+export * from "./engine-session.js";
+export * from "./engine-plugins.js";
+export * from "./llm-assembly.js";
+export * from "./provider-target.js";
+export * from "./offline-llm.js";
+export * from "./worker-bridge.js";
+export * from "./real-runtime-adapter.js";

package/dist/runtime/ledger-view.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The usage ledger's HOST-side views (E-P1, capability 3, W785).
+ *
+ * `RealEngine` (real-runtime-adapter.ts) owns the lifecycle of the process-wide
+ * ledger file, but it does not own the SHAPES the HTTP layer promises. Those live
+ * here as three pure functions so the adapter stays a thin seam (and stays inside
+ * the §4.1 file budget):
+ *
+ *   - [usageLedgerView] — `GET /api/usage/ledger`: the runtime's own `queryLedger`
+ *     over the file's records, or the honest `ok:false` when there is no ledger;
+ *   - [costBlockView]   — `/api/status.cost`: one session's block, `null` when
+ *     there is no ledger (the handler then omits the optional key);
+ *   - [ledgerLabel]     — the label rows are booked under: the TRUSTED session
+ *     id the caller resolved (`<workspace>/<session>`, the SAME label
+ *     `session-compose.ts` books under), `sessionId ?? "cli-main"` when it is
+ *     null. W878: never inferred from `dir`.
+ *
+ * Both readers call `file.readAll()` on every request — the current file plus
+ * the rolled `.1` segment (P2-2), so a rotation cannot zero the cumulative
+ * view. The ledger stays the single source of truth, so nothing is cached and
+ * a row booked a millisecond ago is visible to the next poll.
+ */
+import { type LedgerCostBlock, type LedgerQuery, type LedgerQueryResult, type UsageLedgerFile } from "@celestea/runtime";
+/** `ok:false` = there is no ledger to read here; never a fabricated empty view. */
+export type LedgerUnavailable = {
+    ok: false;
+    error: string;
+};
+/** `GET /api/usage/ledger` over the process ledger (see the module header). */
+export declare function usageLedgerView(file: UsageLedgerFile | null, q: LedgerQuery): LedgerQueryResult | LedgerUnavailable;
+/** `/api/status.cost` over the process ledger (see the module header). */
+export declare function costBlockView(file: UsageLedgerFile | null, session: string | null, dir: string | null): LedgerCostBlock | null;
+/**
+ * The ledger label of a session — the same one its rows are booked under.
+ *
+ * W878: the id is an INPUT, not something to re-derive from `dir`. The `_dir`
+ * parameter is retained only because the adapter's `costBlock` seam already
+ * holds it; it is deliberately ignored.
+ */
+export declare function ledgerLabel(session: string | null, _dir: string | null): string;

package/dist/runtime/ledger-view.js

@@ -0,0 +1,56 @@
+/**
+ * The usage ledger's HOST-side views (E-P1, capability 3, W785).
+ *
+ * `RealEngine` (real-runtime-adapter.ts) owns the lifecycle of the process-wide
+ * ledger file, but it does not own the SHAPES the HTTP layer promises. Those live
+ * here as three pure functions so the adapter stays a thin seam (and stays inside
+ * the §4.1 file budget):
+ *
+ *   - [usageLedgerView] — `GET /api/usage/ledger`: the runtime's own `queryLedger`
+ *     over the file's records, or the honest `ok:false` when there is no ledger;
+ *   - [costBlockView]   — `/api/status.cost`: one session's block, `null` when
+ *     there is no ledger (the handler then omits the optional key);
+ *   - [ledgerLabel]     — the label rows are booked under: the TRUSTED session
+ *     id the caller resolved (`<workspace>/<session>`, the SAME label
+ *     `session-compose.ts` books under), `sessionId ?? "cli-main"` when it is
+ *     null. W878: never inferred from `dir`.
+ *
+ * Both readers call `file.readAll()` on every request — the current file plus
+ * the rolled `.1` segment (P2-2), so a rotation cannot zero the cumulative
+ * view. The ledger stays the single source of truth, so nothing is cached and
+ * a row booked a millisecond ago is visible to the next poll.
+ */
+import { HOST_SESSION_ID, ledgerCostBlock, queryLedger, } from "@celestea/runtime";
+/** `GET /api/usage/ledger` over the process ledger (see the module header). */
+export function usageLedgerView(file, q) {
+    if (file === null)
+        return { ok: false, error: "usage ledger disabled" };
+    try {
+        return queryLedger(file.readAll(), q);
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** `/api/status.cost` over the process ledger (see the module header). */
+export function costBlockView(file, session, dir) {
+    if (file === null)
+        return null;
+    try {
+        return ledgerCostBlock(file.readAll(), ledgerLabel(session, dir));
+    }
+    catch {
+        // Cost is a view: a broken ledger must not fail a status poll.
+        return null;
+    }
+}
+/**
+ * The ledger label of a session — the same one its rows are booked under.
+ *
+ * W878: the id is an INPUT, not something to re-derive from `dir`. The `_dir`
+ * parameter is retained only because the adapter's `costBlock` seam already
+ * holds it; it is deliberately ignored.
+ */
+export function ledgerLabel(session, _dir) {
+    return session ?? HOST_SESSION_ID;
+}

package/dist/runtime/llm-assembly.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Engine LLM assembly (W511): profile -> `Llm`, live by default.
+ *
+ * Two seams, one switch:
+ *   - LIVE     `@celestea/llm`'s OpenAI-compatible client, assembled from the
+ *              engine profile (model / base_url / reasoning_effort /
+ *              max_output_tokens) + the environment (api key, the three
+ *              CELESTEA_LLM_* timeouts);
+ *   - OFFLINE  the deterministic in-process seam (`createOfflineLlm`), still
+ *              available for tests and replay via `CELESTEA_LLM_MODE=offline`
+ *              or an injected `llm` factory on the adapter.
+ *
+ * `@celestea/llm` speaks its own (parity) seam types; core owns the seam the
+ * engine consumes. `liveEngineLlm` is the ONE adapter between them: requests
+ * pass through unchanged (identical shapes), stream events are copied field by
+ * field, and a provider stream-idle failure (`kindOf: "timeout"`) is reported
+ * as core's `"stream"` terminal — the message keeps the `llm timeout:` prefix,
+ * so the distinction survives in the transcript.
+ */
+import { type LiveLlmView, type LlmMode, type LlmTarget } from "@celestea/llm";
+import type { Llm } from "@celestea/core";
+import type { Profile } from "@celestea/runtime";
+import type { EngineProfile } from "../runtime-adapter.js";
+import { type ProviderLookup, type ProviderTarget } from "./provider-target.js";
+import type { Llm as ProviderLlm } from "@celestea/llm";
+/**
+ * The profile fields a live client needs, from either profile shape (`Profile`
+ * carries `context_window_tokens`, the host view `context_window`).
+ */
+export declare function llmProfileOf(profile: Profile | EngineProfile): {
+    model: string;
+    base_url: string;
+    api_key_env: string;
+    reasoning_effort: string | null;
+    max_output_tokens: number | null;
+    context_window_tokens: number;
+};
+/**
+ * The ONE provider-seam -> core-seam bridge: requests pass through unchanged and
+ * every event is copied field by field. Shared by [liveEngineLlm] and by the
+ * fallback decorator (E §4 P1), so a fallback turn is bridged exactly once and
+ * the two paths cannot drift.
+ */
+export declare function bridgeProviderLlm(inner: ProviderLlm): Llm;
+/** The live provider behind the core `Llm` seam. */
+export declare function liveEngineLlm(profile: Profile, env: NodeJS.ProcessEnv): Llm;
+/**
+ * ONE fallback target's client (E §4.2.1 P1): the composed profile with that
+ * target's own `model` / `base_url` / key env applied, so each target keeps its
+ * own credential and its own three timeout tiers (§4.2.1 "三档超时语义逐字不变").
+ * Only env var NAMES travel here; the value is resolved inside `createLiveLlm`.
+ */
+export declare function liveEngineLlmFor(base: Profile, target: LlmTarget, env: NodeJS.ProcessEnv): Llm;
+/** The engine's `Llm` for this generation: live, or the offline test seam. */
+export declare function createEngineLlm(profile: Profile, env: NodeJS.ProcessEnv, mode?: LlmMode): Llm;
+/** Secret-free description of the live adapter (startup logging / diagnostics). */
+export declare function engineLlmView(profile: Profile | EngineProfile, env: NodeJS.ProcessEnv, mode?: LlmMode): LiveLlmView;
+/**
+ * The startup profile: the host constants + env overrides ([defaultEngineProfile])
+ * with providers.json applied on top (model, base_url, and the api key into the
+ * process env — in memory only).
+ */
+export declare function startupEngineProfile(lookup: ProviderLookup, env: NodeJS.ProcessEnv, apiKeyEnv: string): {
+    profile: EngineProfile;
+    target: ProviderTarget;
+};

package/dist/runtime/llm-assembly.js

@@ -0,0 +1,114 @@
+/**
+ * Engine LLM assembly (W511): profile -> `Llm`, live by default.
+ *
+ * Two seams, one switch:
+ *   - LIVE     `@celestea/llm`'s OpenAI-compatible client, assembled from the
+ *              engine profile (model / base_url / reasoning_effort /
+ *              max_output_tokens) + the environment (api key, the three
+ *              CELESTEA_LLM_* timeouts);
+ *   - OFFLINE  the deterministic in-process seam (`createOfflineLlm`), still
+ *              available for tests and replay via `CELESTEA_LLM_MODE=offline`
+ *              or an injected `llm` factory on the adapter.
+ *
+ * `@celestea/llm` speaks its own (parity) seam types; core owns the seam the
+ * engine consumes. `liveEngineLlm` is the ONE adapter between them: requests
+ * pass through unchanged (identical shapes), stream events are copied field by
+ * field, and a provider stream-idle failure (`kindOf: "timeout"`) is reported
+ * as core's `"stream"` terminal — the message keeps the `llm timeout:` prefix,
+ * so the distinction survives in the transcript.
+ */
+import { createLiveLlm, liveLlmView, resolveLlmMode, } from "@celestea/llm";
+import { defaultEngineProfile } from "./engine-profile.js";
+import { createOfflineLlm } from "./offline-llm.js";
+import { applyProviderTarget, resolveProviderTarget, } from "./provider-target.js";
+/**
+ * The profile fields a live client needs, from either profile shape (`Profile`
+ * carries `context_window_tokens`, the host view `context_window`).
+ */
+export function llmProfileOf(profile) {
+    return {
+        model: profile.model,
+        base_url: profile.base_url,
+        api_key_env: profile.api_key_env,
+        reasoning_effort: profile.reasoning_effort,
+        max_output_tokens: profile.max_output_tokens,
+        context_window_tokens: "context_window_tokens" in profile ? profile.context_window_tokens : profile.context_window,
+    };
+}
+/** One provider stream event -> the core event the engine consumes. */
+function coreEvent(event) {
+    switch (event.kind) {
+        case "text":
+            return { kind: "text", text: event.text };
+        case "thinking":
+            return { kind: "thinking", text: event.text };
+        case "usage":
+            return { kind: "usage", usage: event.usage };
+        case "done":
+            return { kind: "done", message: event.message };
+        case "interrupted":
+            return { kind: "interrupted" };
+        case "failed":
+            return {
+                kind: "failed",
+                // core's union has no "timeout" member: an SSE idle guard is a broken
+                // stream there, and the "llm timeout:" prefix keeps the detail.
+                kindOf: event.kindOf === "generate" ? "generate" : "stream",
+                message: event.message,
+            };
+    }
+}
+/** Re-yield a provider stream as a core stream. */
+async function* coreStream(stream) {
+    for await (const event of stream)
+        yield coreEvent(event);
+}
+/**
+ * The ONE provider-seam -> core-seam bridge: requests pass through unchanged and
+ * every event is copied field by field. Shared by [liveEngineLlm] and by the
+ * fallback decorator (E §4 P1), so a fallback turn is bridged exactly once and
+ * the two paths cannot drift.
+ */
+export function bridgeProviderLlm(inner) {
+    return {
+        async generate(req) {
+            return coreStream(await inner.generate(req));
+        },
+    };
+}
+/** The live provider behind the core `Llm` seam. */
+export function liveEngineLlm(profile, env) {
+    return bridgeProviderLlm(createLiveLlm(llmProfileOf(profile), env));
+}
+/**
+ * ONE fallback target's client (E §4.2.1 P1): the composed profile with that
+ * target's own `model` / `base_url` / key env applied, so each target keeps its
+ * own credential and its own three timeout tiers (§4.2.1 "三档超时语义逐字不变").
+ * Only env var NAMES travel here; the value is resolved inside `createLiveLlm`.
+ */
+export function liveEngineLlmFor(base, target, env) {
+    return liveEngineLlm({
+        ...base,
+        model: target.model,
+        base_url: target.baseUrl ?? base.base_url,
+        api_key_env: target.apiKeyEnv ?? base.api_key_env,
+    }, env);
+}
+/** The engine's `Llm` for this generation: live, or the offline test seam. */
+export function createEngineLlm(profile, env, mode = resolveLlmMode(env)) {
+    return mode === "offline" ? createOfflineLlm() : liveEngineLlm(profile, env);
+}
+/** Secret-free description of the live adapter (startup logging / diagnostics). */
+export function engineLlmView(profile, env, mode) {
+    return liveLlmView(llmProfileOf(profile), env, mode);
+}
+/**
+ * The startup profile: the host constants + env overrides ([defaultEngineProfile])
+ * with providers.json applied on top (model, base_url, and the api key into the
+ * process env — in memory only).
+ */
+export function startupEngineProfile(lookup, env, apiKeyEnv) {
+    const base = defaultEngineProfile(env, apiKeyEnv);
+    const target = resolveProviderTarget(lookup, env, base);
+    return applyProviderTarget(base, target, lookup, env);
+}

package/dist/runtime/offline-llm.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The OFFLINE engine LLM — a deterministic, in-process `Llm` seam implementation.
+ *
+ * Purpose: the TS host must be testable and replayable with ZERO network access
+ * (`禁真网`). This adapter answers every `generate()` from a local script, so a
+ * real turn (real `DefaultAgentLoop`, real `ToolRegistry`, real session log)
+ * runs end to end without a provider.
+ *
+ * It is not a stub that fakes the loop: the loop, the tool dispatch, the log and
+ * the SSE frames are the production ones. Only the model is local.
+ *
+ * Two behaviours:
+ *   - a normal turn answers with the next scripted step (text / thinking /
+ *     tool calls / usage), defaulting to a deterministic `echo:` reply;
+ *   - a COMPACTION request (the four-section summarizer prompt) answers with a
+ *     deterministic four-section summary derived from the transcript, so a
+ *     compaction is reproducible byte for byte across runs.
+ *
+ * `deltaMs` interleaves real delays between frames: a test can abort mid-stream
+ * and observe the cooperative cancel path instead of a turn that already
+ * finished.
+ */
+import { type Llm, type Message, type ModelRequest, type StreamEvent, type ToolCall, type Usage } from "@celestea/core";
+/** One scripted model step. */
+export interface OfflineStep {
+    thinking?: string;
+    text?: string;
+    tool_calls?: readonly ToolCall[];
+    /** Answer with a provider failure instead of a done frame. */
+    fail?: string;
+    /** Answer with a torn stream (the `interrupted` terminal state). */
+    interrupted?: boolean;
+}
+export interface OfflineLlmOptions {
+    /**
+     * Steps consumed in order (a caller-supplied array is kept LIVE, so a test can
+     * append steps after the engine was composed); once exhausted the default
+     * deterministic echo step is used.
+     */
+    script?: OfflineStep[];
+    /** Delay between frames in ms (0 = as fast as the microtask queue allows). */
+    deltaMs?: number;
+    /** Text chunk size per `text` delta frame. */
+    chunkChars?: number;
+    /** Summary text override for compaction requests. */
+    summary?: (transcript: string) => string;
+    /**
+     * W729: every request the engine actually sent (`system` + messages), so a
+     * test can assert WHICH system prompt each session's turn carried instead of
+     * re-deriving it. Shared across instances when the caller passes one array.
+     */
+    onRequest?: (req: ModelRequest) => void;
+}
+export interface OfflineLlm extends Llm {
+    /** How many `generate()` calls were served (diagnostics / assertions). */
+    readonly calls: number;
+}
+/** Deterministic usage so `cache_hit_ratio` / `context_usage` are assertable. */
+export declare function offlineUsage(req: ModelRequest, answer: string): Usage;
+/** True when the request is the compaction summarizer (not a chat turn). */
+export declare function isCompactionRequest(req: ModelRequest): boolean;
+/** The default offline summary: four sections + a stable digest of the input. */
+export declare function offlineSummary(transcript: string): string;
+/** Split text into fixed-size chunks (never splitting a code point). */
+export declare function chunkText(text: string, size: number): string[];
+/** Assistant message of a step (tool calls win over text, like the provider). */
+export declare function stepMessage(step: OfflineStep): Message;
+/** The frame list of one scripted step (before timing is applied). */
+export declare function stepFrames(step: OfflineStep, req: ModelRequest, chunk: number): StreamEvent[];
+/** Build the deterministic offline engine LLM. */
+export declare function createOfflineLlm(opts?: OfflineLlmOptions): OfflineLlm;