@celestea/runtime 2.7.1

package/dist/compact/plan.js

@@ -0,0 +1,98 @@
+/**
+ * Compaction planning — port of `celestea_studio/src/compact.rs:60-190`.
+ *
+ * The plan is a pure function of (events, summary, keep):
+ *   1. split the log into COMPLETE turns (`turn_start ..= turn_end`); an
+ *      unterminated tail and everything before the first `turn_start` are
+ *      dropped — only a closed turn may enter the new log;
+ *   2. refuse to compact at or below [COMPACT_THRESHOLD] complete turns;
+ *   3. new log = one synthetic head turn (turn-1: the summary) + the last K
+ *      complete turns, renumbered turn-2..turn-(K+1) but otherwise byte-identical
+ *      (tool / thinking rows stay inside their turn, the outcome is preserved).
+ *
+ * The `turn-<n>` prefix is the engine-native turn id: `PersistentSessionLog`
+ * only recognises that prefix when it restores its counter, so renumbering is
+ * what keeps the next live turn id from colliding with what is on disk.
+ */
+import { clip, SUMMARY_KEEP_MAX_CHARS } from "./transcript.js";
+/** Complete turns at or below this count are "not enough history" to compact. */
+export const COMPACT_THRESHOLD = 8;
+/** How many most-recent complete turns survive a compaction. */
+export const COMPACT_KEEP_TURNS = 4;
+/** Head turn user message prefix (the summary is appended verbatim). */
+export const COMPACT_HEAD_PREFIX = "【上下文压缩】";
+/** Head turn assistant message (fixed text, not model-generated). */
+export const COMPACT_HEAD_ASSISTANT = "上下文已压缩，以上为历史摘要。";
+/** Note of the "nothing to do" branch. */
+export const COMPACT_NOTE_SKIPPED = "历史不足，无需压缩";
+/** Note of the compacted branch (`已压缩：摘要轮 + 最近K轮`). */
+export function compactNote(keep) {
+    return `已压缩：摘要轮 + 最近${keep}轮`;
+}
+/** Engine-native turn id (`turn-<n>`). */
+export function compactTurnId(n) {
+    return `turn-${n}`;
+}
+/**
+ * Cut the event stream into complete turns. A repeated/nested `turn_start`
+ * discards the previous unterminated fragment; rows before the first
+ * `turn_start` are dropped.
+ */
+export function splitCompleteTurns(events) {
+    const turns = [];
+    let current = null;
+    for (const ev of events) {
+        if (ev.type === "turn_start") {
+            current = [ev];
+            continue;
+        }
+        if (current === null)
+            continue; // orphan before the first turn_start
+        current.push(ev);
+        if (ev.type === "turn_end") {
+            turns.push(current);
+            current = null;
+        }
+    }
+    return turns;
+}
+/** Number of complete turns (the threshold predicate). */
+export function countCompleteTurns(events) {
+    return splitCompleteTurns(events).length;
+}
+/**
+ * Replace a turn's boundary ids with `id`; every other row is copied verbatim,
+ * including the terminal outcome (renumbering is not a semantic rewrite).
+ */
+export function renumberTurn(turn, id) {
+    return turn.map((ev) => {
+        if (ev.type === "turn_start")
+            return { type: "turn_start", id };
+        if (ev.type === "turn_end")
+            return { type: "turn_end", id, ...(ev.outcome === undefined ? {} : { outcome: ev.outcome }) };
+        return ev;
+    });
+}
+/** The complete turns a compaction with `keep` preserves (never empty). */
+export function keptTurns(events, keep) {
+    const turns = splitCompleteTurns(events);
+    const k = Math.max(1, Math.min(keep, turns.length));
+    return turns.slice(turns.length - k);
+}
+/**
+ * The post-compaction event list, or null when the log is at/below the
+ * threshold (nothing to compact). `keep` is clamped to `[1, turn count]`.
+ */
+export function planCompaction(events, summary, keep) {
+    if (countCompleteTurns(events) <= COMPACT_THRESHOLD)
+        return null;
+    const head = compactTurnId(1);
+    const out = [
+        { type: "turn_start", id: head },
+        { type: "user_message", text: `${COMPACT_HEAD_PREFIX}${clip(summary.trim(), SUMMARY_KEEP_MAX_CHARS)}`, origin: "compact" },
+        { type: "assistant_message", text: COMPACT_HEAD_ASSISTANT },
+        { type: "turn_end", id: head, outcome: "completed" },
+    ];
+    keptTurns(events, keep).forEach((turn, i) => out.push(...renumberTurn(turn, compactTurnId(i + 2))));
+    return out;
+}

package/dist/compact/rewrite.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Atomic log rewrite (port of `celestea_studio/src/compact.rs:344-390`).
+ *
+ * The order is the durability contract:
+ *   1. the CURRENT file is copied to `cli-main.jsonl.precompact` (single copy,
+ *      overwritten) — the pre-compaction history is always recoverable;
+ *   2. the new log is written to a same-directory `cli-main.jsonl.tmp-<pid>` and
+ *      fsynced (a temp file on another device would make `rename` a copy);
+ *   3. `rename` replaces the log atomically: a concurrent reader sees either the
+ *      whole old log or the whole new one, never a half-written file.
+ *
+ * A failed rename removes the temp file, so a retry cannot be poisoned by a
+ * stale partial write.
+ */
+import { type SessionEvent } from "@celestea/core";
+/** Single-copy backup of the pre-compaction log. */
+export declare const COMPACT_BACKUP_FILE = "cli-main.jsonl.precompact";
+/** Same-directory temp prefix (rename must not cross devices). */
+export declare const COMPACT_TMP_PREFIX = "cli-main.jsonl.tmp-";
+/** The log as one JSONL record per event, every record newline-terminated. */
+export declare function serializeEventLog(events: readonly SessionEvent[]): string;
+/** Rewrite `path` with `events` (backup + fsync + atomic rename + dir fsync). */
+export declare function rewriteAtomic(path: string, events: readonly SessionEvent[], pid?: number): void;

package/dist/compact/rewrite.js

@@ -0,0 +1,79 @@
+/**
+ * Atomic log rewrite (port of `celestea_studio/src/compact.rs:344-390`).
+ *
+ * The order is the durability contract:
+ *   1. the CURRENT file is copied to `cli-main.jsonl.precompact` (single copy,
+ *      overwritten) — the pre-compaction history is always recoverable;
+ *   2. the new log is written to a same-directory `cli-main.jsonl.tmp-<pid>` and
+ *      fsynced (a temp file on another device would make `rename` a copy);
+ *   3. `rename` replaces the log atomically: a concurrent reader sees either the
+ *      whole old log or the whole new one, never a half-written file.
+ *
+ * A failed rename removes the temp file, so a retry cannot be poisoned by a
+ * stale partial write.
+ */
+import { closeSync, copyFileSync, existsSync, fsyncSync, openSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { serializeSessionEvent } from "@celestea/core";
+/** Single-copy backup of the pre-compaction log. */
+export const COMPACT_BACKUP_FILE = "cli-main.jsonl.precompact";
+/** Same-directory temp prefix (rename must not cross devices). */
+export const COMPACT_TMP_PREFIX = "cli-main.jsonl.tmp-";
+/** The log as one JSONL record per event, every record newline-terminated. */
+export function serializeEventLog(events) {
+    let text = "";
+    for (const ev of events)
+        text += `${serializeSessionEvent(ev)}\n`;
+    return text;
+}
+/** Copy the current log to the backup path (only when it exists). */
+function backupCurrent(path, backup) {
+    if (existsSync(path))
+        copyFileSync(path, backup);
+}
+/** Write `text` to `tmp` and fsync it before it can replace anything. */
+function writeDurable(tmp, text) {
+    writeFileSync(tmp, text, "utf8");
+    const fd = openSync(tmp, "r+");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * fsync the PARENT directory so the rename itself is durable (P2-6, W836):
+ * the tmp file's own fsync orders its CONTENT, but only the directory fsync
+ * orders the directory ENTRY, which is what a power loss could otherwise undo.
+ */
+function fsyncDirectory(dir) {
+    try {
+        const fd = openSync(dir, "r");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        // Best effort: a filesystem that cannot fsync a directory must not fail a
+        // compaction (the content was already fsynced through the tmp file).
+    }
+}
+/** Rewrite `path` with `events` (backup + fsync + atomic rename + dir fsync). */
+export function rewriteAtomic(path, events, pid = process.pid) {
+    const dir = dirname(path);
+    const tmp = join(dir, `${COMPACT_TMP_PREFIX}${pid}`);
+    backupCurrent(path, join(dir, COMPACT_BACKUP_FILE));
+    writeDurable(tmp, serializeEventLog(events));
+    try {
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e instanceof Error ? e : new Error(String(e));
+    }
+    fsyncDirectory(dir);
+}

package/dist/compact/run.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Compaction orchestration (port of `celestea_studio/src/compact.rs:410-500`).
+ *
+ * One call is: read -> parse -> threshold -> summarize -> plan -> atomic rewrite.
+ * Every branch is explicit and observable, because the HTTP layer has to answer
+ * three different ways:
+ *   - `compacted:false` (at/below [COMPACT_THRESHOLD] complete turns) is a
+ *     NORMAL 200 with the frozen "历史不足，无需压缩" note;
+ *   - `compacted:true` carries `kept_turns` and the "已压缩…" note;
+ *   - a read/summary/write failure throws — the caller turns it into a 500 with
+ *     the message (never a silent no-op that left the log untouched).
+ *
+ * Parsing mirrors the host's `parse_session_jsonl`: blank lines are padding and
+ * parsing STOPS at the first unparsable record (a torn tail is not content).
+ */
+import { type SessionEvent } from "@celestea/core";
+import type { Summarizer } from "./summarize.js";
+export interface CompactionInput {
+    /** Absolute path of the session log (`<session dir>/cli-main.jsonl`). */
+    logPath: string;
+    summarize: Summarizer;
+    /** Surviving complete turns (default [COMPACT_KEEP_TURNS]). */
+    keep?: number;
+    /** Injection seams for tests (defaults: real fs). */
+    readText?: (path: string) => string;
+    write?: (path: string, events: readonly SessionEvent[]) => void;
+}
+export interface CompactionResult {
+    compacted: boolean;
+    /** Present (as a number) only when `compacted === true`. */
+    kept_turns: number | null;
+    note: string;
+    /** Complete turns found in the log BEFORE the decision. */
+    turns_before: number;
+    /** The new event list, or null when nothing was compacted. */
+    events: SessionEvent[] | null;
+}
+/** JSONL text -> events; blank lines are padding, a torn tail stops parsing. */
+export declare function parseEventLog(text: string): SessionEvent[];
+/**
+ * Run one compaction. Throws on read/summarize/write failure; returns the
+ * skipped branch when the history is too short to be worth a summary request.
+ */
+export declare function runCompaction(input: CompactionInput): Promise<CompactionResult>;

package/dist/compact/run.js

@@ -0,0 +1,59 @@
+/**
+ * Compaction orchestration (port of `celestea_studio/src/compact.rs:410-500`).
+ *
+ * One call is: read -> parse -> threshold -> summarize -> plan -> atomic rewrite.
+ * Every branch is explicit and observable, because the HTTP layer has to answer
+ * three different ways:
+ *   - `compacted:false` (at/below [COMPACT_THRESHOLD] complete turns) is a
+ *     NORMAL 200 with the frozen "历史不足，无需压缩" note;
+ *   - `compacted:true` carries `kept_turns` and the "已压缩…" note;
+ *   - a read/summary/write failure throws — the caller turns it into a 500 with
+ *     the message (never a silent no-op that left the log untouched).
+ *
+ * Parsing mirrors the host's `parse_session_jsonl`: blank lines are padding and
+ * parsing STOPS at the first unparsable record (a torn tail is not content).
+ */
+import { readFileSync } from "node:fs";
+import { parseSessionEvent } from "@celestea/core";
+import { COMPACT_KEEP_TURNS, COMPACT_NOTE_SKIPPED, compactNote, countCompleteTurns, planCompaction } from "./plan.js";
+import { rewriteAtomic } from "./rewrite.js";
+import { renderTranscript } from "./transcript.js";
+/** JSONL text -> events; blank lines are padding, a torn tail stops parsing. */
+export function parseEventLog(text) {
+    const events = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const parsed = parseSessionEvent(line.trim());
+        if (!parsed.ok)
+            break;
+        events.push(parsed.event);
+    }
+    return events;
+}
+function readLog(input) {
+    try {
+        return (input.readText ?? ((p) => readFileSync(p, "utf8")))(input.logPath);
+    }
+    catch (e) {
+        throw new Error(`读取会话日志失败：${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/**
+ * Run one compaction. Throws on read/summarize/write failure; returns the
+ * skipped branch when the history is too short to be worth a summary request.
+ */
+export async function runCompaction(input) {
+    const keep = input.keep ?? COMPACT_KEEP_TURNS;
+    const events = parseEventLog(readLog(input));
+    const turns = countCompleteTurns(events);
+    if (turns <= 0 || planCompaction(events, "", keep) === null) {
+        return { compacted: false, kept_turns: null, note: COMPACT_NOTE_SKIPPED, turns_before: turns, events: null };
+    }
+    const summary = await input.summarize(renderTranscript(events));
+    const planned = planCompaction(events, summary, keep);
+    if (planned === null)
+        throw new Error("内部错误：压缩计划为空");
+    (input.write ?? rewriteAtomic)(input.logPath, planned);
+    return { compacted: true, kept_turns: Math.min(keep, turns), note: compactNote(keep), turns_before: turns, events: planned };
+}

package/dist/compact/summarize.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Summary generation for compaction, over the `Llm` SEAM
+ * (port of `celestea_studio/src/compact.rs:270-340`).
+ *
+ * The host does not talk HTTP here: it asks the same `Llm` the engine uses, so
+ * compose owns base_url / key / request format and this module stays free of
+ * provider knowledge (and of any sibling-package import).
+ *
+ * Failure model: a broken stream, a provider failure or an empty answer is an
+ * ERROR (never an empty summary), because a compaction that silently loses the
+ * history is worse than no compaction at all. A total timeout bounds the call.
+ */
+import { type Llm, type LlmStream, type ModelRequest } from "@celestea/core";
+/** Turns a transcript into a summary; throws on failure. */
+export type Summarizer = (transcript: string) => Promise<string>;
+export interface LlmSummarizerOptions {
+    llm: Llm;
+    model: string;
+    /** System prompt override (default: the frozen four-section contract). */
+    system?: string;
+    timeoutMs?: number;
+}
+/** The compaction request for one transcript. */
+export declare function summaryRequest(model: string, transcript: string, system?: string): ModelRequest;
+/** Reject when `promise` does not settle within `ms` (whole-call timeout). */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, what: string): Promise<T>;
+/** Concatenate the text deltas; `failed` / `interrupted` / empty are errors. */
+export declare function collectSummaryText(stream: LlmStream): Promise<string>;
+/** A [Summarizer] backed by any `Llm` implementation. */
+export declare function llmSummarizer(opts: LlmSummarizerOptions): Summarizer;

package/dist/compact/summarize.js

@@ -0,0 +1,70 @@
+/**
+ * Summary generation for compaction, over the `Llm` SEAM
+ * (port of `celestea_studio/src/compact.rs:270-340`).
+ *
+ * The host does not talk HTTP here: it asks the same `Llm` the engine uses, so
+ * compose owns base_url / key / request format and this module stays free of
+ * provider knowledge (and of any sibling-package import).
+ *
+ * Failure model: a broken stream, a provider failure or an empty answer is an
+ * ERROR (never an empty summary), because a compaction that silently loses the
+ * history is worse than no compaction at all. A total timeout bounds the call.
+ */
+import { userMessage } from "@celestea/core";
+import { COMPACT_SYSTEM_PROMPT, SUMMARY_MAX_TOKENS, SUMMARY_TIMEOUT_MS } from "./transcript.js";
+/** The compaction request for one transcript. */
+export function summaryRequest(model, transcript, system = COMPACT_SYSTEM_PROMPT) {
+    return { model, system, messages: [userMessage(transcript)], tools: [], max_tokens: SUMMARY_MAX_TOKENS, temperature: null };
+}
+/** Reject when `promise` does not settle within `ms` (whole-call timeout). */
+export async function withTimeout(promise, ms, what) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} timeout after ${ms}ms`)), ms);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Concatenate the text deltas; `failed` / `interrupted` / empty are errors. */
+export async function collectSummaryText(stream) {
+    let text = "";
+    for await (const ev of stream) {
+        if (ev.kind === "text") {
+            text += ev.text;
+            continue;
+        }
+        if (ev.kind === "failed")
+            throw new Error(`摘要请求失败：${ev.message}`);
+        if (ev.kind === "interrupted")
+            throw new Error("摘要请求中断（流未给出终态）");
+        if (ev.kind === "done")
+            break;
+    }
+    if (text.trim() === "")
+        throw new Error("摘要响应为空");
+    return text;
+}
+/** A [Summarizer] backed by any `Llm` implementation. */
+export function llmSummarizer(opts) {
+    const timeoutMs = opts.timeoutMs ?? SUMMARY_TIMEOUT_MS;
+    return async (transcript) => {
+        const req = summaryRequest(opts.model, transcript, opts.system ?? COMPACT_SYSTEM_PROMPT);
+        let stream;
+        try {
+            stream = await withTimeout(opts.llm.generate(req), timeoutMs, "摘要请求");
+        }
+        catch (e) {
+            throw new Error(`摘要请求失败：${e instanceof Error ? e.message : String(e)}`);
+        }
+        const text = await withTimeout(collectSummaryText(stream), timeoutMs, "摘要流读取");
+        const trimmed = text.trim();
+        if (trimmed === "")
+            throw new Error("摘要响应缺少正文");
+        return trimmed;
+    };
+}

package/dist/compact/transcript.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Summary-input rendering + the compaction prompt
+ * (port of `celestea_studio/src/compact.rs:34-54,180-262`).
+ *
+ * The transcript handed to the summarising model is a flat, human-readable
+ * rendering of the event stream (turn headings + per-role lines), clipped twice:
+ * per event (so one huge tool result cannot eat the budget) and as a whole,
+ * keeping the TAIL (recent history matters more than the opening pleasantries).
+ *
+ * All clipping is CHARACTER-wise, never byte-wise: a CJK transcript would
+ * otherwise be cut mid-code-point and the summary request would be invalid UTF-8.
+ */
+import { type ImageRef, type SessionEvent } from "@celestea/core";
+/** Per-event clip inside the transcript (tool results / texts). */
+export declare const TRANSCRIPT_EVENT_MAX_CHARS = 4000;
+/** Whole-transcript clip (~60k chars) before it is sent to the model. */
+export declare const SUMMARY_INPUT_MAX_CHARS = 60000;
+/** How much summary text is kept in the synthetic head turn. */
+export declare const SUMMARY_KEEP_MAX_CHARS = 20000;
+/** `max_tokens` of the summarising request. */
+export declare const SUMMARY_MAX_TOKENS = 4096;
+/** Whole-request timeout of the summarising call. */
+export declare const SUMMARY_TIMEOUT_MS = 90000;
+/** The four-section structured summary prompt (verbatim contract text). */
+export declare const COMPACT_SYSTEM_PROMPT: string;
+/** Character-wise clip with a truncation marker (`clip`). */
+export declare function clip(s: string, max: number): string;
+/** Keep the TAIL of a text, with a leading marker when it was cut (`clip_tail`). */
+export declare function clipTail(s: string, max: number): string;
+/** One event's transcript line (`render_transcript`'s match arms). */
+export declare function transcriptLine(ev: SessionEvent): string;
+/** W804: a byte-free placeholder for each attachment (summary input only). */
+export declare function attachmentNote(refs: readonly ImageRef[] | undefined): string;
+/** The whole summary input: every event line, then one tail clip. */
+export declare function renderTranscript(events: readonly SessionEvent[], max?: number): string;

package/dist/compact/transcript.js

@@ -0,0 +1,88 @@
+/**
+ * Summary-input rendering + the compaction prompt
+ * (port of `celestea_studio/src/compact.rs:34-54,180-262`).
+ *
+ * The transcript handed to the summarising model is a flat, human-readable
+ * rendering of the event stream (turn headings + per-role lines), clipped twice:
+ * per event (so one huge tool result cannot eat the budget) and as a whole,
+ * keeping the TAIL (recent history matters more than the opening pleasantries).
+ *
+ * All clipping is CHARACTER-wise, never byte-wise: a CJK transcript would
+ * otherwise be cut mid-code-point and the summary request would be invalid UTF-8.
+ */
+import { serdeJsonString } from "@celestea/core";
+/** Per-event clip inside the transcript (tool results / texts). */
+export const TRANSCRIPT_EVENT_MAX_CHARS = 4_000;
+/** Whole-transcript clip (~60k chars) before it is sent to the model. */
+export const SUMMARY_INPUT_MAX_CHARS = 60_000;
+/** How much summary text is kept in the synthetic head turn. */
+export const SUMMARY_KEEP_MAX_CHARS = 20_000;
+/** `max_tokens` of the summarising request. */
+export const SUMMARY_MAX_TOKENS = 4_096;
+/** Whole-request timeout of the summarising call. */
+export const SUMMARY_TIMEOUT_MS = 90_000;
+/** The four-section structured summary prompt (verbatim contract text). */
+export const COMPACT_SYSTEM_PROMPT = "你是上下文压缩器。把用户提供的会话记录压缩成一份中文结构化摘要，" +
+    "必须且只需包含以下四个小节（保留小节标题）：\n" +
+    "1) 正在进行的任务：当前目标、所处阶段、尚未完成的部分。\n" +
+    "2) 已做的决策：已经确定的技术/方案选择及其理由，包括被否决的方案。\n" +
+    "3) 关键事实与文件改动：涉及的文件路径、函数/接口名、配置项、数据结论、报错信息等可复用的硬事实。\n" +
+    "4) 待办：接下来要做的事，按优先级排列。\n" +
+    "要求：忠于原始记录，不得编造；保留路径、标识符、数字、命令原样；压缩冗余寒暄与重复内容；直接输出摘要正文，不要任何前言、结语或解释。";
+/** Character-wise clip with a truncation marker (`clip`). */
+export function clip(s, max) {
+    const chars = [...s];
+    if (chars.length <= max)
+        return s;
+    return `${chars.slice(0, max).join("")}…（截断）`;
+}
+/** Keep the TAIL of a text, with a leading marker when it was cut (`clip_tail`). */
+export function clipTail(s, max) {
+    const chars = [...s];
+    if (chars.length <= max)
+        return s;
+    return `（更早内容已截断，仅保留最近 ${max} 字符）\n${chars.slice(chars.length - max).join("")}`;
+}
+/** One event's transcript line (`render_transcript`'s match arms). */
+export function transcriptLine(ev) {
+    const quarter = TRANSCRIPT_EVENT_MAX_CHARS / 4;
+    switch (ev.type) {
+        case "turn_start":
+            return `\n--- 轮次 ${ev.id} ---\n`;
+        case "turn_end":
+            return "";
+        case "user_message":
+            // W804: attachments enter the summary as placeholders, NEVER as bytes.
+            return `【用户】${clip(ev.text, TRANSCRIPT_EVENT_MAX_CHARS)}${attachmentNote(ev.attachments)}\n`;
+        case "assistant_message":
+            return `【助手】${clip(ev.text, TRANSCRIPT_EVENT_MAX_CHARS)}\n`;
+        case "thinking_delta":
+            return `【思考】${clip(ev.text, quarter)}\n`;
+        case "tool_call":
+            return `【工具调用】${ev.name}(${clip(serdeJsonString(ev.args ?? null), quarter)})\n`;
+        case "tool_result":
+            return ev.error === null
+                ? `【工具结果】${clip(serdeJsonString(ev.value ?? null), quarter)}\n`
+                : `【工具结果】错误：${clip(ev.error, quarter)}\n`;
+        // W783: a question and its answer are host-side audit rows about a PAUSED
+        // turn. The transcript already carries what the model saw — the ordinary
+        // `tool_result` of `ask_user_question` — so projecting them too would
+        // summarise the same decision twice.
+        case "user_question":
+        case "user_answer":
+            return "";
+    }
+}
+/** W804: a byte-free placeholder for each attachment (summary input only). */
+export function attachmentNote(refs) {
+    if (refs === undefined || refs.length === 0)
+        return "";
+    return refs.map((ref) => `【图：${ref.media_type} ${ref.width}x${ref.height}】`).join("");
+}
+/** The whole summary input: every event line, then one tail clip. */
+export function renderTranscript(events, max = SUMMARY_INPUT_MAX_CHARS) {
+    let out = "";
+    for (const ev of events)
+        out += transcriptLine(ev);
+    return clipTail(out, max);
+}

package/dist/compose.d.ts

@@ -0,0 +1,117 @@
+/**
+ * compose — the composition root of `packages/runtime`
+ * (`crates/runtime/src/compose.rs:74-234`).
+ *
+ * Assembly order is SEMANTICS, not taste (ARCHITECTURE.md §3.2), so it is
+ * explicit and tested:
+ *
+ *   1. runtime services      event bus, usage accounting, status tracker;
+ *   2. session binding       `sessionBinding` (if given) opens the host log;
+ *   3. host plugins          `config.plugins` in order — a later `provide` of a
+ *                            token REPLACES an earlier one (patch semantics, so
+ *                            a test can mount a fake over a real implementation);
+ *   4. worker wiring         mount the default workers plugin only when the host
+ *                            did not provide a registry (worker tools must land
+ *                            in the tool registry, hence last);
+ *   4b. watchdog             W740: mount the liveness watchdog over the resolved
+ *                            worker registry and keep its stop handle, so the
+ *                            sweep timer dies with `shutdown`/`release`;
+ *   5. seam resolution       session (required) + llm / tools / agentLoop
+ *                            (optional, and `null` when no plugin provides them);
+ *   6. driver attach         hand Llm/ToolRegistry/AgentLoop to the worker
+ *                            registry so `spawn_worker` is driven, not merely
+ *                            registered, and register the host conversation so
+ *                            receipts have an address;
+ *   7. turn runner           bind the per-turn loop factory, sink mapper, usage
+ *                            accounting and receipt drain into one driver.
+ *
+ * Everything the runtime needs beyond `core` is injected: the concrete agent
+ * loop arrives as a `loopFactory`, the frame mapper as `frameMapper`, the worker
+ * log factory as `workers.logFactory`. That is what keeps this layer free of
+ * L1 implementation imports (and lets P3 tests drive it with fakes).
+ */
+import { type AgentConfig, type Plugin } from "@celestea/core";
+import { type ToolResultRetention } from "@celestea/agent-loop";
+import { type FrameMapper } from "./frames.js";
+import type { Profile } from "./profile.js";
+import { Runtime, type ShutdownHook } from "./runtime.js";
+import { type SessionBinding } from "./session-binding.js";
+import { type StatusTracker } from "./status.js";
+import type { TurnLedgerHooks } from "./ledger.js";
+import type { TurnContextRow } from "./turn-runner.js";
+import { type LoopFactory } from "./turn-runner.js";
+import { type UsageAccounting } from "./usage.js";
+import type { PendingInjection } from "@celestea/core";
+import { type SessionInbox } from "./inbox.js";
+import { type WorkerHost, type WorkerWiring } from "./worker-wiring.js";
+import { type MountedWatchdog, type WatchdogMountSettings } from "./watchdog-mount.js";
+export interface ComposeConfig {
+    profile: Profile;
+    /** Seam providers, mounted in order (later wins). */
+    plugins?: readonly Plugin[];
+    /** Host conversation binding (dir + log opener); a rebind reuses it. */
+    sessionBinding?: SessionBinding;
+    /** Loop budget overrides (defaults derive from the profile). */
+    agentConfig?: Partial<AgentConfig>;
+    /** Concrete agent loop per turn; absent = `AGENT_LOOP_SERVICE` from the Context. */
+    loopFactory?: LoopFactory;
+    /** LoopEvent -> SSE frame mapping; defaults to the contract mapping. */
+    frameMapper?: FrameMapper;
+    /** Shared usage accounting (pass the loop's own tracker to share one object). */
+    usage?: UsageAccounting;
+    /** Shared statusline tracker (steps + rate window). */
+    status?: StatusTracker;
+    /**
+     * Usage ledger turn hooks (W728 §3 P0): pass the session's `UsageLedger` so
+     * every turn books a `turn_total` row. Absent = no ledgering in this
+     * generation (the default; the studio host wires one).
+     */
+    ledger?: TurnLedgerHooks;
+    /** Worker orchestration wiring; `false` disables it. */
+    workers?: WorkerWiring | false;
+    /**
+     * W740: the liveness watchdog over this generation's worker registry.
+     * `false` never mounts it; a partial object overrides the resolved settings
+     * (`autostart: false` mounts the sweep but leaves the cadence to the caller,
+     * which is how tests drive `tick()` by hand); omitted = the environment
+     * (`celesteaWatchdogSettings(config.env)`, on by default).
+     */
+    watchdog?: Partial<WatchdogMountSettings> | false;
+    /** Process environment the watchdog settings are read from. */
+    env?: NodeJS.ProcessEnv;
+    /** Mid-turn injection queue (default: a fresh one per generation). */
+    inbox?: SessionInbox;
+    /**
+     * W515 §2: every message that LEAVES a lane (or the host mailbox) is reported
+     * with the boundary that consumed it, so the host can publish
+     * `placement: "context"` (the message is now model-visible) over SSE.
+     */
+    onInjected?: (messages: readonly PendingInjection[], boundary: "turn-start" | "step") => void;
+    /**
+     * W884: durable, engine-owned turn context (the skill catalog, name +
+     * description only). Called once per turn start; each row is appended to the
+     * log as user-role history BEFORE the receipts and the input. `[]` = nothing
+     * (a workspace without skills pays nothing). The provider is the HOST's,
+     * because only the host knows the session's workspace (W768).
+     */
+    turnContext?: () => readonly TurnContextRow[];
+    /** Host teardown hooks (process kills) — run once, in order, by `shutdown`. */
+    shutdownHooks?: readonly ShutdownHook[];
+    /** Injectable clock (status tracker rate window). */
+    now?: () => number;
+    /**
+     * W855: tool-result retention policy. Absent = built from the environment
+     * and the session directory (`<dir>/spills/`), so the host gets the default
+     * without wiring anything; `null` explicitly disables it.
+     */
+    retention?: ToolResultRetention | null;
+}
+/** Compose one engine generation. Throws [ComposeError] on a missing seam. */
+export declare function compose(config: ComposeConfig): Runtime;
+/**
+ * The plugin set that was mounted, in mount order (order is contract): the host
+ * plugins, then the workers plugin (when this root mounted it), then the W740
+ * watchdog — which is always LAST, because it may only adjudicate rows a fully
+ * mounted worker registry already owns.
+ */
+export declare function pluginNamesOf(plugins: readonly Plugin[], workerHost: WorkerHost | null, mounted?: MountedWatchdog | null): string[];