@celestea/runtime 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# `@celestea/runtime` (L2 · 装配层)
+
+一句职责：**把插件按显式顺序挂进一个 `Context`，交回一个「已装配、可驱动、可换代」的引擎代（Gen）**。
+对应旧实现 `crates/runtime/{compose.rs,run.rs}` + `celestea_studio/src/main.rs` 的 statusline / 换代部分。
+
+```
+core ← runtime → session / llm / tools / agent-loop / workers
+```
+
+依赖方向：**只向下**。runtime 位于 L2，可以依赖全部 L1，但**不 import 任何一个 L1 实现**——
+具体 agent loop 走 `ComposeConfig.loopFactory`，事件映射走 `frameMapper`，会话日志走
+`sessionBinding`/插件，worker 日志工厂走 `workers.logFactory`。这样 P3 期间可以在
+`packages/agent-loop` / `packages/tools` 并行开发的同时用 fake 验证装配层。
+
+## 公开 API（只从 `src/index.ts` 收口）
+
+| 导出 | 作用 |
+|---|---|
+| `compose(config)` → `Runtime` | 组装一代引擎（见下方顺序） |
+| `ComposeConfig` | profile + 插件列表 + loopFactory/frameMapper/usage/status/workers/shutdownHooks/now |
+| `Runtime` | 句柄 + 生命周期：`runTurn` / `cancelTurn` / `statusline` / `rebind` / `shutdown` / `release` |
+| `GenerationHub` / `Gen` / `createGen` / `migrateReceipts` | 热换代：原子翻转 + 回执迁移 + 旧代拆解 |
+| `SessionBinding` / `createSessionBinding` / `bindSession` | 会话绑定与重绑（同一目录重建绑定） |
+| `TurnRunner` / `LoopFactory` / `LoopBindings` / `TurnOptions` / `resolveOutcome` | 单轮驱动语义（单并发槽、取消、终态） |
+| `StatusTracker` / `createStatusTracker` / `statuslineOf` / `estimatedContextChars` | steps / tokens_per_sec / context usage |
+| `UsageTracker` / `createUsageTracker` / `usageStatus` / `cacheHitRatioRounded` | latest / total / cache_hit_ratio |
+| `loopEventToFrame` / `TurnFrame` / `loopEventToSse` 等价物 | LoopEvent → SSE 帧（契约映射） |
+| `agentConfigFromProfile` / `MIN_STEPS` | profile → `AgentConfig`（步数下限 4096） |
+| `sanitizeProfile` / `sanitizeConfigJson` | 面向 `/api/config` 的消毒投影（白名单 + 出口脱敏） |
+| `TURN_ABORT_SERVICE` / `TURN_SINK_SERVICE` / `USAGE_TRACKER_SERVICE` / `STATUS_TRACKER_SERVICE` / `HOST_SESSION_ID` | 运行时服务 token 与宿主会话 id |
+| `TurnBusyError` / `RuntimeReleasedError` / `ComposeError` | 机器可读错误（409 / 410 / 装配失败） |
+
+## compose 顺序（顺序即语义，测试锁定）
+
+1. 运行时服务：`EVENT_BUS_SERVICE` / `USAGE_TRACKER_SERVICE` / `STATUS_TRACKER_SERVICE`；
+2. `sessionBinding`（若给）：打开宿主日志并提供 `SESSION_LOG_SERVICE`；
+3. `config.plugins` 按序 mount（**后注册覆盖先注册**，测试可挂 fake 顶掉真实现）；
+4. worker 接线：宿主没提供注册表时，**最后**挂默认 workers 插件（三个工具要落进已解析的 `ToolRegistry`）；
+5. 解析 seam：`SessionLog`（必需）+ `LlmRegistry`/`ToolRegistry`/`AgentLoop`（可选，缺则 `null`）；
+6. 驱动接线：把 Llm/ToolRegistry/AgentLoop 交给 worker 注册表（`spawn_worker` 才会被后台驱动），
+   并把宿主会话登记进会话注册表（回执可寻址）；
+7. 组装 `TurnRunner`（loopFactory + frameMapper + usage + 回执 drain）。
+
+## 生命周期语义
+
+- **热换代**：`hub.swap(gen)` = ① 同步翻转 `this.gen = next`（读者要么拿到旧代、要么拿到新代，
+  永远看不到混合状态）② 把旧代 mailbox 里 pending 的宿主回执迁到新代 ③ 再 shutdown + release 旧代。
+- **会话重绑**：`runtime.rebind(binding)` 重新 `binding.open()`（**同一 session id + 同一目录**），
+  重新 provide `SESSION_LOG_SERVICE`，并同步 runtime 的 session 句柄；turn 进行中重绑 → `TurnBusyError`。
+- **shutdown**：**幂等 + 可重入**。停驱动（abort + join）→ 跑宿主 teardown hooks（杀进程）→
+  purge mailbox → clear 会话注册表。重复调用是 no-op，并发调用共享同一个 promise（hook 只跑一次）。
+- **release**：显式断开强引用（`parts = null`），配合 workers 工具持 `WeakRef`，
+  解开 `Runtime → ctx → ToolRegistry → worker tool → registry` 环，让被换代的代可被回收（W248）。
+- **取消**：`runTurn(input, {signal})` 把调用方 signal 链进本轮 signal，注入 loop bindings
+  与 turn scope（`TURN_ABORT_SERVICE`）；`cancelTurn()` 取消进行中的轮次。
+
+## runTurn 语义
+
+- **单并发 busy 槽**：进行中再发起 → `TurnBusyError`（409，`kind: "turn_busy"`），不排队。
+- **回执注入**：轮次开始前先把宿主 mailbox 的 pending 消息按 FIFO 注入 session log
+  （`[from W1] …`），因此 worker 回执在宿主**下一轮真实可见**（W232）。
+- **事件流**：loop 的每个 `LoopEvent` → 喂 `StatusTracker`（tool_call 记一步；text/thinking 记字符）
+  → 映射成一个 `TurnFrame`（SSE 名 + payload）→ 交给 `sink`。
+- **终态**：以 session log 的 `turn_end` 为准（唯一真源）；本轮没写 `turn_end` 时：
+  抛错则向上抛（装配失败不是终态）、已取消则 `cancelled`、静默停止则 `interrupted`——
+  撕裂的一轮**绝不**报成 `completed`。
+
+## StatusTracker / UsageTracker
+
+- steps：一次 tool **call** 记一步（tool_result 不重复计，W263 口径）；
+- tokens_per_sec：text/thinking delta 字符的速率（近似 token 速率，~1:1），**只在本轮有流时段的区间上平均**
+  （相邻 delta 间隔 > `GAP_MS` = 1s 视为无流间断，不计入分母；每个区间下限 `MIN_ACTIVE_MS` = 1s）；
+  窗口有样本时给响应式的 5s 滑窗速率（W754），窗口空时（停顿 > 5s 或轮次结束）回落到**本轮活动区间均值**（W763，
+  `turnRate` / `turnSpanMs` / `pushTurnDelta`，区间按停顿压缩，内存 O(停顿次数) 而非 O(delta 数)）；
+  只有本轮还没有任何 delta（TTFT）才是 0，`beginTurn()` 重置；时钟可注入（`now`）；
+- context usage：优先真实 usage（`latest().prompt_tokens > 0` → `estimated:false` /
+  `usage_prompt_tokens`），否则回退 session log 字符估算（`estimated:true` / `session_event_chars`）；
+- usage：`latest` + `total`，`cache_hit_ratio = cache_read / prompt_tokens`（clamp [0,1]、4 位小数、分母 0 时为 0）。
+
+## 接入真实实现（apps/studio 侧）
+
+```ts
+const usage = new UsageTracker();                       // 或 agent-loop 的同名 tracker（结构等价）
+const runtime = compose({
+  profile,
+  plugins: [sessionPlugin, llmPlugin, toolsPlugin, agentLoopPlugin, /* … */],
+  loopFactory: ({ config, signal, sink, usage }) => new DefaultAgentLoop(config, { signal, sink, usage }),
+  frameMapper: loopEventToSse,                          // 可选：用 agent-loop 的映射
+  usage,
+  workers: { resultsDir: "results" },
+  shutdownHooks: [() => processRegistry.killAll()],
+});
+```
+
+## 测试
+
+`packages/runtime/src/*.test.ts`（61 例，全部用 fake：内存 SessionLog / 脚本化 AgentLoop /
+记录型 ToolRegistry / 队列型 Llm）：
+
+- `compose.test.ts`：挂载顺序与覆盖语义、worker 插件最后挂载并注册三工具、缺 session 报错、
+  agentConfig 推导、消毒 config 无密钥；
+- `turn.test.ts`：事件→帧顺序、终态取自日志、单并发 409、取消传播（含 turn scope token）、
+  宿主回执 FIFO 注入；
+- `lifecycle.test.ts`：shutdown 幂等/可重入/hook 只跑一次、release 断引用、会话重绑（同目录）、
+  换代无混合态（并发读者）、回执迁移、buildAndSwap；
+- `status.test.ts`：steps 口径、速率（窗口 + 本轮活动区间均值，注入时钟）、context usage 真实/估算回退、cache_hit_ratio。

package/dist/agent-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Profile -> `AgentConfig` projection (`runtime/src/compose.rs:196-204`).
+ *
+ * The step cap is floored at [MIN_STEPS]: the engine loop runs
+ * `for step in 0..max_steps`, so `max_steps = 0` means ZERO steps (not
+ * unlimited). A profile that leaves the cap unset therefore gets a high cap
+ * instead of an engine that cannot take a single step (studio W218).
+ */
+import { type AgentConfig } from "@celestea/core";
+import type { Profile } from "./profile.js";
+/** Step-cap floor: covers realistic long turns while still bounding runaway loops. */
+export declare const MIN_STEPS = 4096;
+/** Trim factor of the window that triggers old-message trimming. */
+export declare const CONTEXT_TRIM_THRESHOLD = 0.8;
+/** How many most-recent messages survive a trim (plus the system message). */
+export declare const CONTEXT_KEEP_RECENT = 10;
+/** Derive the loop configuration from a profile (identity prompt included). */
+export declare function agentConfigFromProfile(profile: Profile, overrides?: Partial<AgentConfig>): AgentConfig;

package/dist/agent-config.js

@@ -0,0 +1,31 @@
+/**
+ * Profile -> `AgentConfig` projection (`runtime/src/compose.rs:196-204`).
+ *
+ * The step cap is floored at [MIN_STEPS]: the engine loop runs
+ * `for step in 0..max_steps`, so `max_steps = 0` means ZERO steps (not
+ * unlimited). A profile that leaves the cap unset therefore gets a high cap
+ * instead of an engine that cannot take a single step (studio W218).
+ */
+import { defaultAgentConfig } from "@celestea/core";
+/** Step-cap floor: covers realistic long turns while still bounding runaway loops. */
+export const MIN_STEPS = 4096;
+/** Trim factor of the window that triggers old-message trimming. */
+export const CONTEXT_TRIM_THRESHOLD = 0.8;
+/** How many most-recent messages survive a trim (plus the system message). */
+export const CONTEXT_KEEP_RECENT = 10;
+/** Derive the loop configuration from a profile (identity prompt included). */
+export function agentConfigFromProfile(profile, overrides = {}) {
+    const base = defaultAgentConfig();
+    const steps = profile.max_steps > 0 ? profile.max_steps : MIN_STEPS;
+    return {
+        ...base,
+        model: profile.model,
+        system_prompt: profile.system_prompt,
+        max_steps: steps,
+        max_parallel_tool_calls: profile.max_parallel_tool_calls,
+        context_window_tokens: profile.context_window_tokens,
+        context_trim_threshold: CONTEXT_TRIM_THRESHOLD,
+        context_keep_recent: CONTEXT_KEEP_RECENT,
+        ...overrides,
+    };
+}

package/dist/autowake.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Host auto-wake (W769) — the TS counterpart of the legacy `autowake_loop`
+ * (`crates/../src/main.rs:1044-1187`, semantics in
+ * `docs/DEVELOPMENT.md` §2.6).
+ *
+ * The problem it solves: a worker's completion receipt is delivered into its
+ * HOST session's mailbox, and the host only drains that mailbox at a turn
+ * boundary — so without a loop the receipt lies in the queue until the user
+ * happens to type something. Auto-wake is "delivery wakes the agent".
+ *
+ * The shape here is the legacy one, adapted to this repo's per-session
+ * generations:
+ *   - the loop PARKS on the mailbox notification ([SessionMailbox.onQueued]) and
+ *     rebinds to whatever generation is in force on every pass, so a rebuilt
+ *     instance (a config/grant epoch bump) is picked up without a stale
+ *     subscription — `mailbox()` is a hook, never a captured object;
+ *   - a BUSY host leaves the message QUEUED (it is not drained) and retries on
+ *     the legacy cadence (250ms): nothing is lost and nothing is consumed twice;
+ *   - on wake it drains the WHOLE queue FIFO into one input
+ *     (`[from <label>] <content>`, blank-line separated) and asks the host to run
+ *     ONE ordinary turn — the host's own turn path, so SSE/status/audit are the
+ *     manual ones (legacy note: "SSE 与手动 turn 完全一致");
+ *   - hard errors are logged with a small backoff (500ms); the loop never
+ *     throws, never panics and never spins hot;
+ *   - `stop()` unparks immediately and is what a shutdown hook calls.
+ *
+ * The loop knows nothing about sessions, HTTP or workers: the host supplies the
+ * three facts it needs (mailbox, busy, wake).
+ */
+import type { MailboxMessage, MailboxSendOptions, SessionMailbox } from "@celestea/workers";
+/** Env knob: `0/off/false/no` (case-insensitive) disables auto-wake. */
+export declare const ENV_AUTOWAKE = "CELESTEA_AUTOWAKE";
+/** Busy-host retry cadence (the message stays queued). */
+export declare const AUTOWAKE_BUSY_RETRY_MS = 250;
+/** Backoff after a hard error / an unresolvable mailbox. */
+export declare const AUTOWAKE_ERROR_BACKOFF_MS = 500;
+/**
+ * Safety net for a notification that cannot arrive: a mailbox that appeared
+ * while the loop was parked (an instance REBUILD hands the session a brand-new
+ * mailbox, and the loop only subscribes to it on its next pass), or a queue that
+ * was refilled by something that is not this mailbox. The notification path is
+ * the mechanism (it wakes in the same tick); this floor only bounds how long a
+ * generation swap can delay a receipt — it is the TS stand-in for the legacy
+ * loop's `gen_epoch` watch, at the same cadence as the busy-retry.
+ */
+export declare const AUTOWAKE_POLL_MS = 250;
+/** `CELESTEA_AUTOWAKE`: default ON; the four literals turn it off. */
+export declare function autowakeEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * The turn input of one wake: every drained message in FIFO order, labelled with
+ * its sender (the legacy loop joins with a blank line).
+ */
+export declare function autowakeInput(messages: readonly MailboxMessage[]): string;
+/** The mailbox surface the loop needs (structural: `SessionMailbox` satisfies it). */
+export interface AutowakeMailbox {
+    onQueued(listener: (to: string, message: MailboxMessage) => void): () => void;
+    poll(to: string): MailboxMessage[];
+    pending(to: string): number;
+    send(to: string, content: string, fromLabel: string, opts?: MailboxSendOptions): MailboxMessage;
+}
+/** What the host must tell the loop (all three are read fresh on every pass). */
+export interface AutowakeHooks {
+    /** Queue key of the host conversation in this generation (`cli-main` / the session id). */
+    queueKey: string;
+    /** The mailbox IN FORCE right now; null = no live generation to bind. */
+    mailbox: () => AutowakeMailbox | null;
+    /** Is the host currently running a turn? */
+    isBusy: () => boolean;
+    /**
+     * W855 (C8): messages the USER parked on the `next-turn` lane, read fresh on
+     * every pass. The loop only OBSERVES this count: it must never drain the lane
+     * (the turn-start `drainPending` is its single consumer), which is what makes
+     * double delivery structurally impossible. Absent/0 = the pre-C8 mailbox-only
+     * trigger.
+     */
+    userPending?: () => number;
+    /**
+     * Claim the slot and run ONE ordinary turn with `input`. Return `false` when
+     * the slot was taken in the window (the loop re-queues and retries); throwing
+     * is a hard error and is logged.
+     *
+     * W855 (C8): `null` means "wake for the user lane only" — the turn has no
+     * input of its own and the turn-start drain supplies the content.
+     */
+    wake: (input: string | null) => boolean;
+    /** Diagnostics sink (default: silent). */
+    log?: (line: string) => void;
+}
+/** Injectable timers so the loop is testable without sleeping. */
+export interface AutowakeTiming {
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+}
+export interface AutowakeOptions {
+    busyRetryMs?: number;
+    errorBackoffMs?: number;
+    pollMs?: number;
+    timing?: AutowakeTiming;
+}
+/** One auto-wake loop, bound to ONE host conversation. */
+export declare class AutowakeLoop {
+    private readonly hooks;
+    private readonly busyRetryMs;
+    private readonly errorBackoffMs;
+    private readonly pollMs;
+    private readonly timing;
+    private stopped;
+    private notified;
+    private unpark;
+    private unsubscribe;
+    private bound;
+    private running;
+    /** Consecutive passes that could not hand the queue to a host (log throttle). */
+    private stalled;
+    constructor(hooks: AutowakeHooks, options?: AutowakeOptions);
+    get isStopped(): boolean;
+    /** Start the loop (idempotent). */
+    start(): void;
+    /**
+     * Stop for good: unbind, unpark and wait for the pass in flight to return.
+     * Safe to call twice; never rejects.
+     */
+    stop(): Promise<void>;
+    /** Test/diagnostic handle: the pass currently in flight (null when idle). */
+    get pass(): Promise<void> | null;
+    private loop;
+    /** Resolve the current mailbox and (re)subscribe when the generation moved. */
+    private bind;
+    private requeue;
+    private notify;
+    /** Park until the next notification or the safety-net timeout. */
+    private waitForWork;
+    private pause;
+    private park;
+    /** Log with the legacy loop's thrift: first attempt, then every 20th. */
+    private report;
+}
+/** Factory form (ARCHITECTURE.md §6.1). */
+export declare function createAutowakeLoop(hooks: AutowakeHooks, options?: AutowakeOptions): AutowakeLoop;
+/** Type guard-ish helper: the `SessionMailbox` of a runtime, when it has one. */
+export declare function autowakeMailboxOf(mailbox: SessionMailbox | null | undefined): AutowakeMailbox | null;

package/dist/autowake.js

@@ -0,0 +1,262 @@
+/**
+ * Host auto-wake (W769) — the TS counterpart of the legacy `autowake_loop`
+ * (`crates/../src/main.rs:1044-1187`, semantics in
+ * `docs/DEVELOPMENT.md` §2.6).
+ *
+ * The problem it solves: a worker's completion receipt is delivered into its
+ * HOST session's mailbox, and the host only drains that mailbox at a turn
+ * boundary — so without a loop the receipt lies in the queue until the user
+ * happens to type something. Auto-wake is "delivery wakes the agent".
+ *
+ * The shape here is the legacy one, adapted to this repo's per-session
+ * generations:
+ *   - the loop PARKS on the mailbox notification ([SessionMailbox.onQueued]) and
+ *     rebinds to whatever generation is in force on every pass, so a rebuilt
+ *     instance (a config/grant epoch bump) is picked up without a stale
+ *     subscription — `mailbox()` is a hook, never a captured object;
+ *   - a BUSY host leaves the message QUEUED (it is not drained) and retries on
+ *     the legacy cadence (250ms): nothing is lost and nothing is consumed twice;
+ *   - on wake it drains the WHOLE queue FIFO into one input
+ *     (`[from <label>] <content>`, blank-line separated) and asks the host to run
+ *     ONE ordinary turn — the host's own turn path, so SSE/status/audit are the
+ *     manual ones (legacy note: "SSE 与手动 turn 完全一致");
+ *   - hard errors are logged with a small backoff (500ms); the loop never
+ *     throws, never panics and never spins hot;
+ *   - `stop()` unparks immediately and is what a shutdown hook calls.
+ *
+ * The loop knows nothing about sessions, HTTP or workers: the host supplies the
+ * three facts it needs (mailbox, busy, wake).
+ */
+/** Env knob: `0/off/false/no` (case-insensitive) disables auto-wake. */
+export const ENV_AUTOWAKE = "CELESTEA_AUTOWAKE";
+/** Busy-host retry cadence (the message stays queued). */
+export const AUTOWAKE_BUSY_RETRY_MS = 250;
+/** Backoff after a hard error / an unresolvable mailbox. */
+export const AUTOWAKE_ERROR_BACKOFF_MS = 500;
+/**
+ * Safety net for a notification that cannot arrive: a mailbox that appeared
+ * while the loop was parked (an instance REBUILD hands the session a brand-new
+ * mailbox, and the loop only subscribes to it on its next pass), or a queue that
+ * was refilled by something that is not this mailbox. The notification path is
+ * the mechanism (it wakes in the same tick); this floor only bounds how long a
+ * generation swap can delay a receipt — it is the TS stand-in for the legacy
+ * loop's `gen_epoch` watch, at the same cadence as the busy-retry.
+ */
+export const AUTOWAKE_POLL_MS = 250;
+/** `CELESTEA_AUTOWAKE`: default ON; the four literals turn it off. */
+export function autowakeEnabled(env = process.env) {
+    const raw = (env[ENV_AUTOWAKE] ?? "").trim().toLowerCase();
+    return raw !== "0" && raw !== "off" && raw !== "false" && raw !== "no";
+}
+/**
+ * The turn input of one wake: every drained message in FIFO order, labelled with
+ * its sender (the legacy loop joins with a blank line).
+ */
+export function autowakeInput(messages) {
+    return messages.map((m) => (m.from_label === "" ? m.content : `[from ${m.from_label}] ${m.content}`)).join("\n\n");
+}
+const REAL_TIMING = {
+    setTimeout: (fn, ms) => {
+        const handle = setTimeout(fn, ms);
+        // The repo's timer rule: a PARKED loop must never keep the process alive
+        // (same as the watchdog's sweep and the idle reclaimer).
+        handle.unref?.();
+        return handle;
+    },
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+/** One auto-wake loop, bound to ONE host conversation. */
+export class AutowakeLoop {
+    hooks;
+    busyRetryMs;
+    errorBackoffMs;
+    pollMs;
+    timing;
+    stopped = false;
+    notified = false;
+    unpark = null;
+    unsubscribe = null;
+    bound = null;
+    running = null;
+    /** Consecutive passes that could not hand the queue to a host (log throttle). */
+    stalled = 0;
+    constructor(hooks, options = {}) {
+        this.hooks = hooks;
+        this.busyRetryMs = options.busyRetryMs ?? AUTOWAKE_BUSY_RETRY_MS;
+        this.errorBackoffMs = options.errorBackoffMs ?? AUTOWAKE_ERROR_BACKOFF_MS;
+        this.pollMs = options.pollMs ?? AUTOWAKE_POLL_MS;
+        this.timing = options.timing ?? REAL_TIMING;
+    }
+    get isStopped() {
+        return this.stopped;
+    }
+    /** Start the loop (idempotent). */
+    start() {
+        if (this.running !== null)
+            return;
+        this.running = this.loop();
+    }
+    /**
+     * Stop for good: unbind, unpark and wait for the pass in flight to return.
+     * Safe to call twice; never rejects.
+     */
+    async stop() {
+        this.stopped = true;
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.bound = null;
+        this.unpark?.();
+        const running = this.running;
+        this.running = null;
+        if (running !== null)
+            await running.catch(() => undefined);
+    }
+    /** Test/diagnostic handle: the pass currently in flight (null when idle). */
+    get pass() {
+        return this.running;
+    }
+    // --- the loop ----------------------------------------------------------
+    async loop() {
+        // Let the mounting host finish publishing the instance this loop belongs to
+        // (the studio mounts it from inside the generation's own build callback, so
+        // one microtask later the entry exists and the first bind succeeds).
+        await Promise.resolve();
+        while (!this.stopped) {
+            const mailbox = this.bind();
+            if (mailbox === null) {
+                this.report("no live generation to bind; retrying");
+                await this.pause(this.errorBackoffMs);
+                continue;
+            }
+            const userPending = this.hooks.userPending?.() ?? 0;
+            if (mailbox.pending(this.hooks.queueKey) === 0 && userPending === 0 && !this.notified) {
+                await this.waitForWork();
+                continue;
+            }
+            this.notified = false;
+            if (this.hooks.isBusy()) {
+                // Leave BOTH sources queued (the lane is not ours to drain) and retry.
+                await this.pause(this.busyRetryMs);
+                continue;
+            }
+            const drained = mailbox.poll(this.hooks.queueKey);
+            if (drained.length === 0 && userPending === 0)
+                continue;
+            // W855 (C8): the user lane is NEVER drained here — `drainPending` does it
+            // inside the turn. When only the lane has work the wake carries `null`
+            // ("no own input") and the drained lane message is the turn content.
+            const input = drained.length === 0 ? null : autowakeInput(drained);
+            let started = false;
+            try {
+                started = this.hooks.wake(input);
+            }
+            catch (error) {
+                // W855 (C8): a synchronous throw happens before the turn slot is
+                // claimed, so the drained messages were NOT consumed — hand them back
+                // instead of losing them (the old comment claimed the opposite).
+                this.stalled += 1;
+                this.report(`turn error: ${error instanceof Error ? error.message : String(error)}; ${drained.length} message(s) re-queued`);
+                this.requeue(drained);
+                await this.pause(this.errorBackoffMs);
+                continue;
+            }
+            if (started) {
+                this.stalled = 0;
+                continue;
+            }
+            // Lost the race for the turn slot: hand the SAME messages to whatever
+            // generation is in force NOW (never the one they were popped from) and
+            // retry — nothing is lost, nothing is consumed twice.
+            this.stalled += 1;
+            this.requeue(drained);
+            this.report(`host busy; ${drained.length} message(s) re-queued (attempt ${this.stalled})`);
+            await this.pause(this.busyRetryMs);
+        }
+    }
+    /** Resolve the current mailbox and (re)subscribe when the generation moved. */
+    bind() {
+        let mailbox = null;
+        try {
+            mailbox = this.hooks.mailbox();
+        }
+        catch (error) {
+            this.report(`mailbox lookup failed: ${error instanceof Error ? error.message : String(error)}`);
+            mailbox = null;
+        }
+        if (mailbox !== this.bound) {
+            this.unsubscribe?.();
+            this.unsubscribe = null;
+            this.bound = mailbox;
+            if (mailbox !== null) {
+                this.unsubscribe = mailbox.onQueued((to) => {
+                    if (to === this.hooks.queueKey)
+                        this.notify();
+                });
+            }
+        }
+        return mailbox;
+    }
+    requeue(messages) {
+        let mailbox = null;
+        try {
+            mailbox = this.hooks.mailbox();
+        }
+        catch {
+            mailbox = null;
+        }
+        if (mailbox === null) {
+            this.report("cannot re-queue: no live generation (messages stay consumed)");
+            return;
+        }
+        for (const message of messages) {
+            mailbox.send(this.hooks.queueKey, message.content, message.from_label, {
+                kind: message.kind,
+                source: message.source,
+            });
+        }
+    }
+    notify() {
+        this.notified = true;
+        this.unpark?.();
+    }
+    /** Park until the next notification or the safety-net timeout. */
+    waitForWork() {
+        if (this.notified) {
+            this.notified = false;
+            return Promise.resolve();
+        }
+        return this.park(this.pollMs);
+    }
+    pause(ms) {
+        if (this.stopped)
+            return Promise.resolve();
+        return this.park(ms);
+    }
+    park(ms) {
+        return new Promise((resolve) => {
+            const timer = this.timing.setTimeout(() => {
+                this.unpark = null;
+                resolve();
+            }, ms);
+            this.unpark = () => {
+                this.timing.clearTimeout(timer);
+                this.unpark = null;
+                resolve();
+            };
+        });
+    }
+    /** Log with the legacy loop's thrift: first attempt, then every 20th. */
+    report(line) {
+        if (this.stalled > 1 && this.stalled % 20 !== 0)
+            return;
+        this.hooks.log?.(line);
+    }
+}
+/** Factory form (ARCHITECTURE.md §6.1). */
+export function createAutowakeLoop(hooks, options = {}) {
+    return new AutowakeLoop(hooks, options);
+}
+/** Type guard-ish helper: the `SessionMailbox` of a runtime, when it has one. */
+export function autowakeMailboxOf(mailbox) {
+    return mailbox ?? null;
+}

package/dist/compact/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `compact` — context compaction (`celestea_studio/src/compact.rs`).
+ *
+ * W259 semantics: only COMPLETE turns count, the newest K survive renumbered,
+ * and the pre-compaction log is always recoverable from the single-copy
+ * `cli-main.jsonl.precompact` backup. The summary itself is produced through
+ * the `Llm` seam (see ./summarize.ts), so this package needs no provider.
+ */
+export * from "./plan.js";
+export * from "./transcript.js";
+export * from "./rewrite.js";
+export * from "./summarize.js";
+export * from "./run.js";

package/dist/compact/index.js

@@ -0,0 +1,13 @@
+/**
+ * `compact` — context compaction (`celestea_studio/src/compact.rs`).
+ *
+ * W259 semantics: only COMPLETE turns count, the newest K survive renumbered,
+ * and the pre-compaction log is always recoverable from the single-copy
+ * `cli-main.jsonl.precompact` backup. The summary itself is produced through
+ * the `Llm` seam (see ./summarize.ts), so this package needs no provider.
+ */
+export * from "./plan.js";
+export * from "./transcript.js";
+export * from "./rewrite.js";
+export * from "./summarize.js";
+export * from "./run.js";

package/dist/compact/plan.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 type { SessionEvent } from "@celestea/core";
+/** Complete turns at or below this count are "not enough history" to compact. */
+export declare const COMPACT_THRESHOLD = 8;
+/** How many most-recent complete turns survive a compaction. */
+export declare const COMPACT_KEEP_TURNS = 4;
+/** Head turn user message prefix (the summary is appended verbatim). */
+export declare const COMPACT_HEAD_PREFIX = "\u3010\u4E0A\u4E0B\u6587\u538B\u7F29\u3011";
+/** Head turn assistant message (fixed text, not model-generated). */
+export declare const COMPACT_HEAD_ASSISTANT = "\u4E0A\u4E0B\u6587\u5DF2\u538B\u7F29\uFF0C\u4EE5\u4E0A\u4E3A\u5386\u53F2\u6458\u8981\u3002";
+/** Note of the "nothing to do" branch. */
+export declare const COMPACT_NOTE_SKIPPED = "\u5386\u53F2\u4E0D\u8DB3\uFF0C\u65E0\u9700\u538B\u7F29";
+/** Note of the compacted branch (`已压缩：摘要轮 + 最近K轮`). */
+export declare function compactNote(keep: number): string;
+/** Engine-native turn id (`turn-<n>`). */
+export declare function compactTurnId(n: number): string;
+/**
+ * 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 declare function splitCompleteTurns(events: readonly SessionEvent[]): SessionEvent[][];
+/** Number of complete turns (the threshold predicate). */
+export declare function countCompleteTurns(events: readonly SessionEvent[]): number;
+/**
+ * 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 declare function renumberTurn(turn: readonly SessionEvent[], id: string): SessionEvent[];
+/** The complete turns a compaction with `keep` preserves (never empty). */
+export declare function keptTurns(events: readonly SessionEvent[], keep: number): SessionEvent[][];
+/**
+ * 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 declare function planCompaction(events: readonly SessionEvent[], summary: string, keep: number): SessionEvent[] | null;