@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/loop/message-hub.js

@@ -0,0 +1,439 @@
+import { randomUUID } from 'node:crypto';
+import { wrapSubagentResult } from '../subagent/milestone-body.js';
+import { wrapSystemReminder } from '../turn/loop-reminder.js';
+/**
+ * 「这批 parts 是否值得落一条 assistant chat_message」的判据——单纯的空
+ * text part（`{type:'text',text:''}`）不算，其余任意 part（非空 text /
+ * tool-call / tool-result / reasoning）都算。
+ *
+ * 两个消费方（`record` 跳过全空的一步、`close` 判这一轮是否留下过东西）**必须
+ * 用同一份**：两处对「有没有内容」的认定一分叉，就会有一批 part 落不进库、或
+ * 者一条空气泡凭空出现。
+ */
+function hasMeaningfulParts(parts) {
+    return parts.some(p => p.type !== 'text' || p.text.trim().length > 0);
+}
+/**
+ * 一轮的记录器 —— `openTurn` 造，`close` 收，**一轮一个**。
+ *
+ * 它存在的理由是「这一轮落过什么」需要一个家：那两笔记账（领到过消息没有、
+ * 落过 assistant 段没有）过去是 `buildRootHost` 里的两个闭包变量，中心这边则
+ * 只有 `openTurn` 没有收尾点。**刻意不做成中心里的 `Map<runId, …>`**：那张表
+ * 要在三条终态路径上都记得删，漏一条漏一类会话，症状是内存慢慢涨（同
+ * `TurnContext.turnState` 那条判据）。生命周期跟着对象走，结构上不可能泄漏。
+ *
+ * **三位一体的 id 在这里**：`runId` = `streamId` = 本轮 assistant `chat_message`
+ * 行的主键 = `AgentEvent.messageId`。前端靠 `messageId` 把流式增量路由到气泡
+ * （`chunk.id`），而「`messageId` 恒等于 `runId`」是「换轮」那一轮的产物——在那
+ * 之前它们是两个东西，靠一族分段判据互相对应。拆开来各生成各的，等于把那族
+ * 判据原样请回来。
+ */
+export class TurnRecorder {
+    hub;
+    sessionId;
+    runId;
+    streamId;
+    /**
+     * 这一轮有没有从 inbox 领到过东西。与 `wrote` 一起把两件在收尾时长得一模一样
+     * 的事分开：「模型被问了话但一个字没说」（该留一条可见占位）与「压根没有输入
+     * 可跑」（该一行都不落）。两者的终态都是 completed、都没落过任何 step。
+     */
+    drained = false;
+    /** 这一轮有没有真的落过 assistant 段（`close` 拿它决定要不要补一条）。 */
+    wrote = false;
+    /** 最近一次落库覆盖到的事件 seq（`metadata.flushedSeq`），收尾时原样保留。 */
+    flushedSeq = null;
+    /**
+     * 本轮「开跑」事件的服务端时刻（ms），落进 `metadata.runStartedAt`。
+     *
+     * 前端运行状态行的「已跑 N 秒」靠它：开跑事件在第一次落库后就从会话流里
+     * 退役了，刷新之后流里再也找不到这一轮从什么时候开始——没有这一列就只能按
+     * 前端本地计时，刷新一次数字就从零重来。取**事件的 `ts`** 而不是在这里
+     * `Date.now()`：与流里那条开跑事件是同一个数，刷新前后显示不跳。
+     */
+    runStartedAt = null;
+    constructor(hub, sessionId, runId, streamId) {
+        this.hub = hub;
+        this.sessionId = sessionId;
+        this.runId = runId;
+        this.streamId = streamId;
+    }
+    /**
+     * 本轮的一条事件出去（`RunTurnArgs.sink` 接的就是这里）。
+     *
+     * **这是两条通道汇合的那一点**：同一个对象既往 `chat_message` 写，也往流上
+     * 发。此前 SSE 是内核直连总线（`sink: e => bus.publish(e)` 写在 loop 的
+     * `runTick` 里）、落库绕回会话层，两条路从来没在同一个地方碰过头——而「同一次
+     * 工具调用在流里和库里长得不一样」正是从那里长出来的（那次分叉已经由「落库
+     * 只从事件账本重建」修掉，这一步是把结构本身补齐：`bus.publish` 全仓只剩这
+     * 一个调用点，`TurnRecorder` 是「这一轮怎么到达外面」的完整答案）。
+     *
+     * **内核仍然不认识总线**：它只知道一个同步投递口（判据见 `RunTurnArgs.sink`），
+     * 这里是那个口的下游。**同步**：账本 `append` 是同步可回读的，投递不能反过来
+     * 要求它等（判据见 `TurnJournal`）。
+     *
+     * 抛错怎么办由账本那一侧管（记 warn、事件照常进账本——观测非承重，绝不能把
+     * 一轮成功的生成变成 failed）。
+     *
+     * **会话级事件不走这里**（`publishSessionEvent`：自动命名、孤儿 sweep 的补发
+     * run-finish）：它们没有正在跑的这一轮，也就没有 recorder；它们自己会话面
+     * 分配游标，见 `StreamBus.publishSessionEvent`。
+     */
+    emit(event) {
+        // 按 runId 认「本轮自己的」开跑：同一个 sink 上还会流过子 Agent 的事件。
+        if (event.type === 'run-start' &&
+            event.runId === this.runId &&
+            this.runStartedAt === null) {
+            this.runStartedAt = event.ts;
+        }
+        this.hub.publish(event);
+    }
+    /** 取出本轮要处理的消息（落库在同一事务里，见 `MessageHub.take`）。 */
+    async take() {
+        const out = await this.hub.take(this.sessionId);
+        this.drained ||= out.length > 0;
+        return out;
+    }
+    /** 探一眼本会话的 inbox 还有没有排队的（换轮判据，只探不取）。 */
+    hasPending() {
+        return this.hub.hasPending(this.sessionId);
+    }
+    /**
+     * 本轮又产出了这一截 parts —— 增量落进 `runId` 那一行（首次 INSERT，之后
+     * jsonb 追加）。全空的一步直接跳过，不留一条空气泡、也不翻「落过」的账。
+     */
+    async record(parts, uptoSeq = null) {
+        if (!hasMeaningfulParts(parts))
+            return;
+        await this.hub.appendAssistantStep({
+            messageId: this.runId,
+            runId: this.runId,
+            sessionId: this.sessionId,
+            parts,
+            flushedSeq: uptoSeq,
+            runStartedAt: this.runStartedAt,
+        });
+        if (uptoSeq != null)
+            this.flushedSeq = uptoSeq;
+        // **写成功了才算落过**。提前置位的话，一轮里每次写库都失败时 `close` 会跳过
+        // 占位、直接去 finalize 一条不存在的行（UPDATE 0 行、静默）——这一轮在流里
+        // 出现过、刷新后却什么都没有，看起来像系统把回复吃了。置位放在 await 之后，
+        // 全部失败时 `close` 至少会补一条可见占位（终态是 failed，文案会说原因）。
+        this.wrote = true;
+    }
+    /**
+     * 收尾：盖终态 metadata 与整轮 usage。
+     *
+     * 三条路，**判据全在这一个方法里**（过去分散在宿主的 `persist` 与内核的
+     * `TurnResult.parts` 之间）：
+     *
+     * 1. **空转轮**（没领到、没落过、且 completed）→ **一行都不落**。占位文案说的
+     *    是「模型本轮没有返回任何内容」，而这一轮模型压根没被问过话；落下去就是
+     *    一条凭空出现的助手气泡，更要命的是子会话的 `finalizeIfIdle` 会把它当成
+     *    这一轮的新产出回投给父。成因是 wake 与真正 drain 之间那段窗口里那批货
+     *    没了（最常见的是用户在 QueueBar 上撤回）。
+     *    **限定 completed**：failed / aborted / rejected 即使零产出也必须留下可见
+     *    痕迹，那才是占位文案存在的理由。
+     * 2. **一个字都没落过**（但被问过话，或终态不是 completed）→ 补一条可见占位。
+     * 3. **落过** → 只盖终态，不再追加任何 parts。
+     *
+     * @returns 这一轮在对话流里留下东西了没有。宿主据此决定要不要安排自动命名
+     *   （空转轮没有任何新消息，命名的材料都不存在）。
+     */
+    async close(terminal) {
+        if (!this.drained && !this.wrote && terminal.status === 'completed') {
+            return false;
+        }
+        if (!this.wrote) {
+            await this.record([
+                { type: 'text', text: emptyReplyPlaceholder(terminal) },
+            ]);
+        }
+        await this.hub.finalizeAssistantTurn({
+            messageId: this.runId,
+            runId: this.runId,
+            metadata: {
+                // 终态整体重写 metadata，落库边界要跟着带过去——前端刷新后仍靠它把
+                // 宽限期内重放的事件丢掉。
+                ...(this.flushedSeq != null ? { flushedSeq: this.flushedSeq } : {}),
+                ...(this.runStartedAt != null
+                    ? { runStartedAt: this.runStartedAt }
+                    : {}),
+                status: terminal.status,
+                stopReason: terminal.stopReason,
+                ...(terminal.error ? { error: terminal.error } : {}),
+                ...terminal.metadata,
+            },
+            usage: terminal.usage,
+        });
+        return true;
+    }
+}
+/**
+ * 零产出时的可见文案，带上原因让用户知道发生了什么。
+ *
+ * **`error` 优先于 `stopReason`**：失败路径上 stopReason 一律是那个常量
+ * `'error'`，「原因：error」等于没说——真正的解释在 `error` 里（内核已经把
+ * provider 的原话归一化成中文，见 `provider-error.ts`）。stopReason 只在没有
+ * error 时兜底，它对 aborted/rejected 那两类才是有信息的。
+ */
+function emptyReplyPlaceholder(t) {
+    const detail = t.error ?? t.stopReason;
+    const reason = detail ? `，原因：${detail}` : '';
+    switch (t.status) {
+        case 'aborted':
+            return `本轮已中断，且未产生任何内容${reason}`;
+        case 'failed':
+            return `本轮生成失败，未产生任何内容${reason}`;
+        case 'rejected':
+            return `本轮被拦截，未产生任何内容${reason}`;
+        default:
+            return `模型本轮没有返回任何内容${reason}`;
+    }
+}
+/**
+ * 取 parts 里的文本（子 Agent 回执包围栏时用）。里程碑 payload 当前恒是单个
+ * text part（`finalizeIfIdle` 写死），拼接只是不对这一点做硬假设。
+ */
+function textOfParts(parts) {
+    return parts
+        .filter((p) => p.type === 'text')
+        .map(p => p.text)
+        .join('\n');
+}
+/**
+ * inbox 行 → 内核的 `DrainedTurnMessage`。
+ *
+ * **落库与注入模型是两份形态**：`parts` 是纯正文（前端回执气泡直接显示它），
+ * `modelParts` 把同一段正文包进 `<subagent-result …>` 围栏 —— 子 Agent 的产出是
+ * 不可信外部输入，裸拼的话它与之后的平台文案在字节层面无从区分（见
+ * `milestone-body.ts#wrapSubagentResult`）。围栏不落库：落库的是数据，围栏是
+ * 呈现层，否则前端还得把标签再剥回去。
+ *
+ * `source`（toolName/handle/status/stopReason）经 metadata 落进 `chat_message`，
+ * 前端据它认出回执并打状态 Tag —— **不从正文里用正则抠 handle**。
+ */
+function toTurnMessage(d) {
+    if (d.kind === 'system_reminder') {
+        // 与 tool_result 同一条分工：落库纯正文 + `metadata.kind`，围栏只进模型。
+        // 刷新后从库里重建时由投影层按同一个 kind 再包一次（`wrapStoredUserText`），
+        // 两条路读的是同一个标记。
+        const kind = typeof d.source?.kind === 'string' ? d.source.kind : null;
+        if (!kind) {
+            throw new Error('system_reminder inbox row must carry source.kind');
+        }
+        return {
+            id: d.messageId,
+            parts: d.parts,
+            modelParts: [
+                {
+                    type: 'text',
+                    text: wrapSystemReminder(textOfParts(d.parts)),
+                },
+            ],
+            // `source` 整个落进 metadata：投递方随行带的判据（如待办提醒的完成数）
+            // 要经 `TurnContext.inbound` 回到它自己手里；`kind` 是必带的那一个。
+            metadata: { ...d.source, kind },
+        };
+    }
+    if (d.kind !== 'tool_result')
+        return { id: d.messageId, parts: d.parts };
+    const s = (d.source ?? {});
+    return {
+        id: d.messageId,
+        parts: d.parts,
+        modelParts: [
+            {
+                type: 'text',
+                text: wrapSubagentResult(textOfParts(d.parts), {
+                    handle: s.handle,
+                    status: s.status,
+                    reason: s.stopReason,
+                }),
+            },
+        ],
+        metadata: { source: d.source },
+    };
+}
+/** 进程被杀、一个字都没落库就中断的那一轮补的可见正文（会随历史喂回模型，故写的是事实）。 */
+export const INTERRUPTED_PLACEHOLDER = '本轮已中断（服务重启），未产生任何内容。';
+/**
+ * 消息中心：会话里「一条消息」的产生、排队、落库与寻址，只此一处。
+ *
+ * ## 边界
+ *
+ * **中心是 `ConversationStore` 写方法的唯一调用方**（`ContextStore` 那三样除外：
+ * 上下文预算的 tracker 直接用，那是 agent-base 里就有的分工——决策归预算，
+ * checkpoint 落库在那边也经中心，这里由端口的原子契约代替）。宿主要投递消息走
+ * `post`，别直接 `store.enqueue`：消息主键的铸造、取出时的形态换算都在这里。
+ *
+ * **不归中心的**：tick 调度 / 会话锁 / 续租是 loop（`LoopDriver`）的活；跑次归
+ * `RunStore`；上下文预算的决策归 `ContextBudgetTracker`；内核的工作内存与事件
+ * 账本归 `TurnRun`（账本要被内核同步回读，中心只可能是它的下游 sink）。
+ */
+export class MessageHub {
+    store;
+    bus;
+    constructor(store, 
+    // 本轮事件的去向（`TurnRecorder.emit` 的下游）。**唯一的 `bus.publish` 调用点**。
+    bus) {
+        this.store = store;
+        this.bus = bus;
+    }
+    /** run 级事件投递。只有 `TurnRecorder.emit` 调它，公开只为让它能被替身观测。 */
+    publish(event) {
+        this.bus.publish(event);
+    }
+    /**
+     * 投递。**所有入口唯一的一个**（用户发言、派生子 Agent 的首个 prompt、追加任务、
+     * 里程碑回投）。落库用的 id 在这里产生并返回：前端拿它做气泡收敛，必须与库里
+     * 那一行同源。
+     *
+     * **不负责唤醒**：投递方紧接着自己 `wake`（或用 `LoopDriver.post`，两步一起）。
+     */
+    async post(input) {
+        const messageId = randomUUID();
+        await this.store.enqueue({
+            sessionId: input.sessionId,
+            kind: input.kind,
+            sourceKind: input.sourceKind,
+            sourceUserId: input.sourceUserId ?? null,
+            source: input.source ?? null,
+            parts: input.parts,
+            messageId,
+        });
+        return { messageId };
+    }
+    /**
+     * 取出本会话待处理的全部消息，**并在同一个事务里落库**（判据在
+     * `ConversationStore.takeInbox`），返回内核要的形态。
+     *
+     * **一轮只被调一次**（内核的第一次迭代，模型开口之前）：轮内后来进来的消息由
+     * `hasPending` 探到后换轮，留给下一个 tick 的这同一个点。所以这里刚落库的
+     * user 行永远早于本轮的任何 assistant 输出。
+     */
+    async take(sessionId) {
+        const taken = await this.store.takeInbox(sessionId, item => {
+            const m = toTurnMessage(item);
+            return {
+                id: m.id,
+                sessionId,
+                role: 'user',
+                parts: m.parts,
+                ...(m.metadata ? { metadata: m.metadata } : {}),
+            };
+        });
+        // 回填落库后的真实 id：内核随后把它随 `inbox-drained` 事件推给前端就地插
+        // 气泡，而之后的 refetch 要按同一个 id 收敛掉那条气泡。
+        return taken.map(({ item, message }) => ({
+            ...toTurnMessage(item),
+            id: message.id,
+        }));
+    }
+    /**
+     * 只探不取。换轮判据（内核每次调模型前探一下，见 `TurnHost.hasPendingInbox`），
+     * 以及 loop / sweep 判「这个会话还有没有货」的同一个问题。
+     */
+    hasPending(sessionId) {
+        return this.store.hasPending(sessionId);
+    }
+    /** 撤回：只删「自己的」「还没被取走的」那一项。 */
+    withdraw(id, userId) {
+        return this.store.withdraw(id, userId);
+    }
+    /** 本会话的待处理队列。 */
+    listPending(sessionId) {
+        return this.store.listPending(sessionId);
+    }
+    /** 此刻还有待处理项的全部会话 id。供启动时补唤醒（wake 是瞬时广播，inbox 是持久的）。 */
+    listSessionIdsWithPending() {
+        return this.store.listSessionIdsWithPending();
+    }
+    /**
+     * 一轮开张：铸那个**三位一体**的 id（`runId` = `streamId` = 本轮 assistant 行主键
+     * = `AgentEvent.messageId`），返回本轮的记录器。值本身只是一个 uuid，这个方法的
+     * 意义是**只有一处会铸它**。
+     */
+    openTurn(sessionId) {
+        const id = randomUUID();
+        return new TurnRecorder(this, sessionId, id, id);
+    }
+    /** 落一条消息（按 id 幂等，见 `ConversationStore.appendMessage`）。 */
+    appendMessage(message) {
+        return this.store.appendMessage(message);
+    }
+    /**
+     * setup 阶段失败的可见占位（会话 / agent / 模型解析就抛错，流从未开、`runTurn`
+     * 根本没跑）——不补这条用户会看到彻底的沉默：消息已经进了 inbox，界面上什么都
+     * 不会发生。文案由调用方定（`LoopHost.describeSetupError`）。
+     */
+    async appendSetupError(sessionId, text) {
+        await this.store.appendMessage({
+            sessionId,
+            role: 'assistant',
+            parts: [{ type: 'text', text }],
+            metadata: { status: 'failed', stopReason: 'setup-error' },
+        });
+    }
+    /**
+     * assistant 段落的落库原语（`TurnRecorder.record` 用）。首次建行、之后追加。
+     *
+     * `flushedSeq`：这批 parts 覆盖到的最后一个事件的 seq，**与 parts 同一次写入**
+     * `metadata.flushedSeq`，写成功后才让会话流退役 seq ≤ 它的事件——分开写的话会
+     * 出现「流里已经删了、库里的边界还是旧的」，刷新后前端按旧边界去重，把不该丢的
+     * 尾巴当成重放丢掉。
+     */
+    async appendAssistantStep(opts) {
+        await this.store.appendAssistantStep({
+            messageId: opts.messageId,
+            runId: opts.runId,
+            sessionId: opts.sessionId,
+            parts: opts.parts,
+            metadataPatch: {
+                ...(opts.flushedSeq != null ? { flushedSeq: opts.flushedSeq } : {}),
+                ...(opts.runStartedAt != null
+                    ? { runStartedAt: opts.runStartedAt }
+                    : {}),
+            },
+        });
+        if (opts.flushedSeq != null) {
+            this.bus.retireUpTo(opts.runId, opts.flushedSeq);
+        }
+    }
+    /** 一轮收尾：在 `messageId`（= runId）那一行上盖终态 metadata 与整轮 usage。 */
+    finalizeAssistantTurn(opts) {
+        return this.store.finalizeAssistantTurn(opts);
+    }
+    /**
+     * 收尾一轮被进程死亡打断的轮次在对话流里的痕迹（`OrphanRunSweeper` 用），返回受
+     * 影响的行 id。
+     *
+     * 两条路，判据是「有没有落过库的 assistant 段」：
+     * - **产出过** → 只给还没盖终态的段盖上。已产出的正文原样保留，不追加任何
+     *   解释性文字——那会把模型没说过的话写进它的历史。
+     * - **一个字都没落库**（run 刚 open 就被杀）→ 补一条可见占位。不补的话用户
+     *   那句话孤零零挂着、下面什么都没有，看起来像系统把消息吃了。
+     *
+     * 会话已删（`sessionId` 为 null）时补不了占位，也没必要。
+     */
+    async closeInterruptedTurn(runId, sessionId) {
+        const segments = await this.store.listTurnSegmentIds(runId);
+        if (segments.length > 0 || !sessionId) {
+            return this.store.finalizeInterruptedTurn(runId);
+        }
+        // 第 0 段的行 id 就是 runId（见 `openTurn`）。
+        await this.store.appendAssistantStep({
+            messageId: runId,
+            runId,
+            sessionId,
+            parts: [{ type: 'text', text: INTERRUPTED_PLACEHOLDER }],
+        });
+        await this.store.finalizeAssistantTurn({
+            messageId: runId,
+            runId,
+            metadata: { status: 'aborted', stopReason: 'aborted' },
+        });
+        return [runId];
+    }
+}
+//# sourceMappingURL=message-hub.js.map

package/dist/loop/message-hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-hub.js","sourceRoot":"","sources":["../../src/loop/message-hub.ts"],"names":[],"mappings":"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"}

package/dist/loop/orphan-run.sweeper.d.ts

@@ -0,0 +1,79 @@
+import { type SessionLock, type WakeChannel } from '../ports/coordination.js';
+import { type Logger } from '../ports/logger.js';
+import type { RunStore, StaleRun } from '../ports/run-store.js';
+import type { StreamBus } from '../ports/stream-bus.js';
+import type { MessageHub } from './message-hub.js';
+/**
+ * 两次 sweep 的间隔。也是「进程被杀后多久那一轮才会被收尾」的上界之一——
+ * 另一个是会话锁的自然过期（`LOCK_TTL_MS`），两者相加即最坏延迟。
+ */
+export declare const SWEEP_INTERVAL_MS = 60000;
+/** run 开跑多久之后才纳入候选：给「run 刚记下、锁的抢占与本次探测交叉」留出宽限。 */
+export declare const ORPHAN_MIN_AGE_MS = 60000;
+export declare const INTERRUPTED_ERROR = "\u670D\u52A1\u4E2D\u65AD\uFF08\u8FDB\u7A0B\u91CD\u542F\uFF09\uFF0C\u672C\u8F6E\u672A\u8DD1\u5B8C\u3002";
+export interface OrphanRunSweeperDeps {
+    runs: RunStore;
+    lock: SessionLock;
+    wake: WakeChannel;
+    hub: MessageHub;
+    bus: StreamBus;
+    logger?: Logger;
+    /**
+     * 宿主挂在这一轮上的同步等待一并作废（提问面板、确认面板……）：那一轮可能正死在
+     * 「等用户回答」上，留着它用户对着的是一个答了也没人接的面板。只对有会话的孤儿调。
+     *
+     * **抛错不影响收尾的其余几步**（照样补发 run-finish），只记日志。
+     */
+    onRunOrphaned?(run: StaleRun & {
+        sessionId: string;
+    }): Promise<void>;
+    /** 缺省 `SWEEP_INTERVAL_MS`。 */
+    intervalMs?: number;
+    /** 缺省 `ORPHAN_MIN_AGE_MS`。 */
+    minAgeMs?: number;
+}
+/**
+ * 收尾「进程被杀留下的半截轮次」。
+ *
+ * 一轮的终态**只存在于跑它的那个进程的内存里**：跑次的 `finish()`、消息上的终态
+ * metadata 都在 tick 跑完那一刻才写。进程没了，这两个写入永远不会发生——跑次永久
+ * 停在 running、前端把那条没盖终态的消息当成「一轮真的还在飞」，每次刷新都卡成
+ * 「进行中」，点停止也救不回来（活跃登记簿随进程没了）。
+ *
+ * 判据是 **「该会话此刻有没有 loop 持锁」**：锁在整个 tick 期间持有并定期续租，
+ * 而 `finish()` 发生在 `release()` 之前，故「无锁 + 仍 running」是确定的孤儿，多
+ * 实例部署下也不会误伤别的实例正在跑的轮次。这条判据继承了会话锁的口径（锁过期 =
+ * 跑它的 loop 已经死了），误判的后果也是收敛的：`markInterrupted` 只在仍 running
+ * 时翻牌，那个进程后来恢复并 `finish()` 会覆盖成真实终态。
+ *
+ * **周期跑而不是只在启动跑一次**：进程被杀时会话锁不会主动释放，要等 TTL 自然
+ * 过期。启动那一刻锁多半还在，启动那次会（正确地）跳过所有候选。
+ */
+export declare class OrphanRunSweeper {
+    private readonly deps;
+    private timer?;
+    private readonly logger;
+    constructor(deps: OrphanRunSweeperDeps);
+    /**
+     * 启动：立刻扫一次、把 inbox 有积压的会话各叫醒一次，之后周期扫。都是
+     * fire-and-forget，绝不阻塞 / 拖垮启动。返回停止函数（同 `dispose`）。
+     */
+    start(): () => void;
+    dispose(): void;
+    /**
+     * 扫一轮孤儿 run 并收尾，返回收了几条。no-throw 到单条粒度：一条坏记录不能中断
+     * sweep（否则它后面那些本可以修好的轮次会一直卡着）。
+     */
+    sweep(): Promise<number>;
+    /** 单条候选的处置。返回它是否真的由本次调用收的尾。 */
+    private finalizeOrphan;
+    private publishRunFinish;
+    /**
+     * 把「inbox 里还有待处理项」的会话各叫醒一次（wake 是瞬时广播，没有持久化；进程
+     * 在「已投递、loop 还没取」之间被杀，那条消息就只剩存储里一行，谁也不会再来叫醒
+     * 它）。只在启动跑：正常运行期间 `onWake` 收尾时会自查并重新广播。多实例同时启动
+     * 各 wake 一次也无害——抢锁只有一个赢。
+     */
+    wakePendingInboxes(): Promise<number>;
+}
+//# sourceMappingURL=orphan-run.sweeper.d.ts.map

package/dist/loop/orphan-run.sweeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-run.sweeper.d.ts","sourceRoot":"","sources":["../../src/loop/orphan-run.sweeper.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,kDAAkD;AAClD,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAE7C,eAAO,MAAM,iBAAiB,2GAAsB,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,UAAU,CAAC;IAChB,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,CAAC,GAAG,EAAE,QAAQ,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,KAAK,CAAC,CAAiC;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,IAAI,EAAE,oBAAoB;IAIvD;;;OAGG;IACH,KAAK,IAAI,MAAM,IAAI;IAiBnB,OAAO,IAAI,IAAI;IAKf;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAwB9B,+BAA+B;YACjB,cAAc;IAiC5B,OAAO,CAAC,gBAAgB;IAwBxB;;;;;OAKG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;CAkB5C"}