@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/loop/loop-driver.js

@@ -0,0 +1,199 @@
+import { silentLogger } from '../ports/logger.js';
+import { ActiveTickRegistry } from './active-tick.registry.js';
+/** 锁 TTL 60s（`LOCK_TTL_MS`），20s 续租留足冗余。 */
+export const LOCK_RENEW_INTERVAL_MS = 20_000;
+/**
+ * 停机时留给在跑的 tick 自行收尾的预算。`docker stop` 默认 SIGTERM 之后 10s
+ * 才 SIGKILL，取 7s 留出余量给宿主其余的关闭钩子。
+ *
+ * 超时**不是**故障：`OrphanRunSweeper` 仍然兜底，只是用户要多等一会儿。故这里
+ * 宁可早点放手，也不能赌满 10s——被 SIGKILL 打断的话，连锁的主动释放都没做成。
+ */
+export const SHUTDOWN_DRAIN_MS = 7_000;
+const SHUTDOWN_POLL_MS = 50;
+/**
+ * inbox 驱动的 agent loop 调度器。`wake` 经 `WakeChannel` 广播（多实例时跨实例）；
+ * 每个实例的订阅者收到即 `onWake` —— 试抢会话锁，只有抢到的那个实例跑一个 tick
+ * （一次 `runTurn` 自驱 loop，drain-first）。tick 收尾释放锁后再查一次 inbox：
+ * 若期间又有新消息进来（插话 / 子 Agent 回投），重新 wake，闭合「刚 drain 完又来
+ * 一条、锁还没放」的丢唤醒窗口。
+ *
+ * 流的生命周期（open / close）完全落在 tick 内，与任何 HTTP 连接解耦。
+ */
+export class LoopDriver {
+    deps;
+    active;
+    logger;
+    unsubscribe;
+    constructor(deps) {
+        this.deps = deps;
+        this.active = new ActiveTickRegistry(deps.bus);
+        this.logger = deps.logger ?? silentLogger('');
+    }
+    /** 订阅唤醒。返回退订函数（`shutdown` 也会退订）。 */
+    start() {
+        this.unsubscribe ??= this.deps.wake.onWake(sessionId => {
+            void this.onWake(sessionId).catch(err => this.logger.error(`onWake(${sessionId}) failed: ${String(err)}`));
+        });
+        return () => this.stopListening();
+    }
+    stopListening() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    /**
+     * 投递一条消息并唤醒（**post-first**：先写 inbox 再 wake）。宿主的准入检查
+     * （会话能不能发言等）在调它之前自己做。
+     */
+    async post(input) {
+        const out = await this.deps.hub.post(input);
+        await this.deps.wake.wake(input.sessionId);
+        return out;
+    }
+    /** 该会话此刻在本进程跑着的流，没有则 null。 */
+    activeStreamOf(sessionId) {
+        return this.active.streamOf(sessionId);
+    }
+    /**
+     * 会话级中断：解析该会话当前活跃 tick 的流 → abort。跨实例 best-effort（tick 跑在
+     * 别的实例上时这里查不到）。返回是否真的中断了一条流。宿主挂着的同步等待（提问
+     * 面板等）自己作废。
+     */
+    stopSession(sessionId) {
+        const streamId = this.active.streamOf(sessionId);
+        if (!streamId)
+            return false;
+        this.deps.bus.abort(streamId);
+        return true;
+    }
+    /**
+     * 停机前把本进程正在跑的 tick 全部 abort 掉，并**等它们收完尾**。
+     *
+     * 不做的话，那些轮次的终态就随进程一起没了：跑次停在 running、消息没盖终态。
+     * sweeper 能修，但代价是至少一个锁 TTL（进程被杀时锁不会主动释放）。主动重启
+     * 占了重启的绝大多数，这条路让它们几乎瞬时收尾，sweeper 退回去只兜底真正的崩溃。
+     *
+     * **走的是内核既有的 abort 路径**：`bus.abort` → `runTurn` 照常以 aborted 收尾 →
+     * `host.persist` 盖终态、发 `run-finish`，等价于用户点了停止。
+     *
+     * **必须等**：abort 只是置了标记，立刻返回就等于没做。等到登记簿清空为准，超时
+     * 则放手交给 sweeper。返回是否在预算内清空。
+     */
+    async shutdown(budgetMs = SHUTDOWN_DRAIN_MS) {
+        this.stopListening();
+        const streams = this.active.streamIds();
+        if (streams.length === 0)
+            return true;
+        this.logger.warn(`shutdown: aborting ${streams.length} in-flight tick(s) so they land a terminal state`);
+        for (const streamId of streams)
+            this.deps.bus.abort(streamId);
+        const deadline = Date.now() + budgetMs;
+        while (this.active.size > 0) {
+            if (Date.now() >= deadline) {
+                this.logger.warn(`shutdown: ${this.active.size} tick(s) still running after ${budgetMs}ms; OrphanRunSweeper will finish them`);
+                return false;
+            }
+            await new Promise(resolve => setTimeout(resolve, SHUTDOWN_POLL_MS));
+        }
+        return true;
+    }
+    async onWake(sessionId) {
+        const { lock, hub, wake } = this.deps;
+        const token = await lock.acquire(sessionId);
+        if (!token)
+            return; // 已有 loop 在跑，它会 re-drain
+        const renew = setInterval(() => void lock.renew(sessionId, token).catch(() => undefined), this.deps.renewIntervalMs ?? LOCK_RENEW_INTERVAL_MS);
+        try {
+            // 抢到锁之后再确认一次真有货。每一个投递方都是 post-first，另外两个唤醒源
+            // （下面的 re-wake、启动时的 `wakePendingInboxes`）本就以 `hasPending` 为
+            // 条件——所以「持锁而 inbox 空」只有一个成因：这批货在 wake 与抢锁之间没了
+            // （被上一个 tick 领走或被用户撤回）。空跑一趟会开流、开跑次、发 run-start /
+            // run-finish，前端建一个空气泡再收起来。
+            //
+            // **不能直接 return**：跳过的只是 tick，下面的 release 与重新自查必须照走，
+            // 否则一次 wake 落在「查完到释放锁」之间就丢了。
+            if (await hub.hasPending(sessionId)) {
+                await this.runTick(sessionId);
+            }
+        }
+        finally {
+            clearInterval(renew);
+            await lock.release(sessionId, token);
+        }
+        // 必须排在 re-wake 之前，判据见 `LoopHost.afterTick`。
+        await this.deps.host.afterTick?.(sessionId);
+        // 关丢唤醒：释放后再查一次，非空则重新广播（锁此刻空闲，可被重新抢到）。
+        if (await hub.hasPending(sessionId)) {
+            await wake.wake(sessionId);
+        }
+        else {
+            // idle 广播：tick 跑完且 inbox 已空。尽力而为——发不出去只记日志，消费方
+            // 各自有兜底。
+            await wake
+                .idle(sessionId)
+                .catch(err => this.logger.warn(`publish idle(${sessionId}) failed: ${String(err)}`));
+        }
+    }
+    async runTick(sessionId) {
+        const { bus, hub, host, runtime } = this.deps;
+        const setup = await this.resolveSetup(sessionId);
+        // 三位一体的 id 由消息中心铸，**别在这里各生成各的**。recorder 的生命周期
+        // 正好是这个 tick。
+        const recorder = hub.openTurn(sessionId);
+        const { runId, streamId } = recorder;
+        const { nextSeq } = bus.open(streamId);
+        this.active.open(sessionId, streamId);
+        try {
+            // **不给兜底信号**——`open` 之后 `signalOf` 必然有值，拿不到是接线坏了；拿
+            // 一个永不 abort 的空信号顶上去，会把「停止按钮按了没反应」变成一个不报错的
+            // 静默症状。
+            const abortSignal = bus.signalOf(streamId);
+            if (!abortSignal) {
+                throw new Error(`stream ${streamId} opened without an abort signal`);
+            }
+            const args = await host.buildTurn(setup, {
+                sessionId,
+                runId,
+                streamId,
+                recorder,
+            });
+            await runtime.runTurn({
+                ...args,
+                nextSeq,
+                // 事件的去向：本轮的 recorder（消息中心）。内核只认识一个同步投递口。
+                sink: e => recorder.emit(e),
+                abortSignal,
+            });
+        }
+        catch (err) {
+            this.logger.error(`tick ${streamId} crashed: ${String(err)}`);
+        }
+        finally {
+            bus.close(streamId);
+            this.active.close(sessionId, streamId);
+        }
+    }
+    /**
+     * setup 阶段：任一步都可能抛（agent 已停用、模型已删除……）。流此时还没开，唯一
+     * 能让用户看到「发生了什么」的办法是补一条可见占位。落占位失败只记日志（不能
+     * 反过来吞掉 / 替换原始 setup 错误），随后原样重新抛出，交由 `onWake` 的 finally
+     * 照常 release 锁。
+     */
+    async resolveSetup(sessionId) {
+        try {
+            return await this.deps.host.setupTick(sessionId);
+        }
+        catch (err) {
+            const text = this.deps.host.describeSetupError?.(err) ??
+                `本轮无法启动：${err instanceof Error ? err.message : String(err)}`;
+            try {
+                await this.deps.hub.appendSetupError(sessionId, text);
+            }
+            catch (persistErr) {
+                this.logger.error(`appendSetupError(${sessionId}) failed: ${String(persistErr)}`);
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=loop-driver.js.map

package/dist/loop/loop-driver.js.map

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

package/dist/loop/message-hub.d.ts

@@ -0,0 +1,236 @@
+import type { ConversationMessage, ConversationStore, InboxItem, InboxMessageKind, InboxSourceKind } from '../ports/conversation-store.js';
+import type { StreamBus } from '../ports/stream-bus.js';
+import type { AgentEvent } from '../schema/agent-event.js';
+import type { MessagePart } from '../schema/index.js';
+import type { DrainedTurnMessage } from '../turn/turn-envelope.js';
+/**
+ * 一次投递。**没有 `messageId` 字段是有意的**：落库主键由中心自己铸，投递方只交
+ * 「这条消息是什么」。
+ */
+export interface PostInput {
+    sessionId: string;
+    kind: InboxMessageKind;
+    sourceKind: InboxSourceKind;
+    /** 谁发的（系统触发为 null）。撤回按它判归属。 */
+    sourceUserId?: string | null;
+    /**
+     * 结构化来源（子 Agent 回执的 handle/status/stopReason；`system_reminder` 则必须
+     * 带 `{ kind }`——落库 `metadata.kind` 与投影层的围栏读的都是它，漏了这条行会以
+     * 裸 user 文本进上下文）。
+     */
+    source?: Record<string, unknown> | null;
+    parts: MessagePart[];
+}
+/**
+ * 一轮的终态，交给 `TurnRecorder.close`。
+ *
+ * **`status` 与 `metadata` 分开收**：前者是中心自己要用的判据（空转轮闸门、
+ * 占位文案的措辞），后者是宿主追加的那几个数（上下文预算的 contextTokens /
+ * contextWindow / contextThreshold）——中心不解释它们，只负责跟终态一起落进
+ * 同一个 metadata 对象。
+ */
+export interface TurnTerminal {
+    status: 'completed' | 'aborted' | 'rejected' | 'failed';
+    stopReason?: string;
+    error?: string;
+    usage?: Record<string, number>;
+    /** 宿主追加的终态字段（键由宿主定义，中心原样合并）。 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 一轮的记录器 —— `openTurn` 造，`close` 收，**一轮一个**。
+ *
+ * 它存在的理由是「这一轮落过什么」需要一个家：那两笔记账（领到过消息没有、
+ * 落过 assistant 段没有）过去是 `buildRootHost` 里的两个闭包变量，中心这边则
+ * 只有 `openTurn` 没有收尾点。**刻意不做成中心里的 `Map<runId, …>`**：那张表
+ * 要在三条终态路径上都记得删，漏一条漏一类会话，症状是内存慢慢涨（同
+ * `TurnContext.turnState` 那条判据）。生命周期跟着对象走，结构上不可能泄漏。
+ *
+ * **三位一体的 id 在这里**：`runId` = `streamId` = 本轮 assistant `chat_message`
+ * 行的主键 = `AgentEvent.messageId`。前端靠 `messageId` 把流式增量路由到气泡
+ * （`chunk.id`），而「`messageId` 恒等于 `runId`」是「换轮」那一轮的产物——在那
+ * 之前它们是两个东西，靠一族分段判据互相对应。拆开来各生成各的，等于把那族
+ * 判据原样请回来。
+ */
+export declare class TurnRecorder {
+    private readonly hub;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly streamId: string;
+    /**
+     * 这一轮有没有从 inbox 领到过东西。与 `wrote` 一起把两件在收尾时长得一模一样
+     * 的事分开：「模型被问了话但一个字没说」（该留一条可见占位）与「压根没有输入
+     * 可跑」（该一行都不落）。两者的终态都是 completed、都没落过任何 step。
+     */
+    private drained;
+    /** 这一轮有没有真的落过 assistant 段（`close` 拿它决定要不要补一条）。 */
+    private wrote;
+    /** 最近一次落库覆盖到的事件 seq（`metadata.flushedSeq`），收尾时原样保留。 */
+    private flushedSeq;
+    /**
+     * 本轮「开跑」事件的服务端时刻（ms），落进 `metadata.runStartedAt`。
+     *
+     * 前端运行状态行的「已跑 N 秒」靠它：开跑事件在第一次落库后就从会话流里
+     * 退役了，刷新之后流里再也找不到这一轮从什么时候开始——没有这一列就只能按
+     * 前端本地计时，刷新一次数字就从零重来。取**事件的 `ts`** 而不是在这里
+     * `Date.now()`：与流里那条开跑事件是同一个数，刷新前后显示不跳。
+     */
+    private runStartedAt;
+    constructor(hub: MessageHub, sessionId: string, runId: string, streamId: string);
+    /**
+     * 本轮的一条事件出去（`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: AgentEvent): void;
+    /** 取出本轮要处理的消息（落库在同一事务里，见 `MessageHub.take`）。 */
+    take(): Promise<DrainedTurnMessage[]>;
+    /** 探一眼本会话的 inbox 还有没有排队的（换轮判据，只探不取）。 */
+    hasPending(): Promise<boolean>;
+    /**
+     * 本轮又产出了这一截 parts —— 增量落进 `runId` 那一行（首次 INSERT，之后
+     * jsonb 追加）。全空的一步直接跳过，不留一条空气泡、也不翻「落过」的账。
+     */
+    record(parts: MessagePart[], uptoSeq?: number | null): Promise<void>;
+    /**
+     * 收尾：盖终态 metadata 与整轮 usage。
+     *
+     * 三条路，**判据全在这一个方法里**（过去分散在宿主的 `persist` 与内核的
+     * `TurnResult.parts` 之间）：
+     *
+     * 1. **空转轮**（没领到、没落过、且 completed）→ **一行都不落**。占位文案说的
+     *    是「模型本轮没有返回任何内容」，而这一轮模型压根没被问过话；落下去就是
+     *    一条凭空出现的助手气泡，更要命的是子会话的 `finalizeIfIdle` 会把它当成
+     *    这一轮的新产出回投给父。成因是 wake 与真正 drain 之间那段窗口里那批货
+     *    没了（最常见的是用户在 QueueBar 上撤回）。
+     *    **限定 completed**：failed / aborted / rejected 即使零产出也必须留下可见
+     *    痕迹，那才是占位文案存在的理由。
+     * 2. **一个字都没落过**（但被问过话，或终态不是 completed）→ 补一条可见占位。
+     * 3. **落过** → 只盖终态，不再追加任何 parts。
+     *
+     * @returns 这一轮在对话流里留下东西了没有。宿主据此决定要不要安排自动命名
+     *   （空转轮没有任何新消息，命名的材料都不存在）。
+     */
+    close(terminal: TurnTerminal): Promise<boolean>;
+}
+/** 进程被杀、一个字都没落库就中断的那一轮补的可见正文（会随历史喂回模型，故写的是事实）。 */
+export declare const INTERRUPTED_PLACEHOLDER = "\u672C\u8F6E\u5DF2\u4E2D\u65AD\uFF08\u670D\u52A1\u91CD\u542F\uFF09\uFF0C\u672A\u4EA7\u751F\u4EFB\u4F55\u5185\u5BB9\u3002";
+/**
+ * 消息中心：会话里「一条消息」的产生、排队、落库与寻址，只此一处。
+ *
+ * ## 边界
+ *
+ * **中心是 `ConversationStore` 写方法的唯一调用方**（`ContextStore` 那三样除外：
+ * 上下文预算的 tracker 直接用，那是 agent-base 里就有的分工——决策归预算，
+ * checkpoint 落库在那边也经中心，这里由端口的原子契约代替）。宿主要投递消息走
+ * `post`，别直接 `store.enqueue`：消息主键的铸造、取出时的形态换算都在这里。
+ *
+ * **不归中心的**：tick 调度 / 会话锁 / 续租是 loop（`LoopDriver`）的活；跑次归
+ * `RunStore`；上下文预算的决策归 `ContextBudgetTracker`；内核的工作内存与事件
+ * 账本归 `TurnRun`（账本要被内核同步回读，中心只可能是它的下游 sink）。
+ */
+export declare class MessageHub {
+    readonly store: ConversationStore;
+    private readonly bus;
+    constructor(store: ConversationStore, bus: StreamBus);
+    /** run 级事件投递。只有 `TurnRecorder.emit` 调它，公开只为让它能被替身观测。 */
+    publish(event: AgentEvent): void;
+    /**
+     * 投递。**所有入口唯一的一个**（用户发言、派生子 Agent 的首个 prompt、追加任务、
+     * 里程碑回投）。落库用的 id 在这里产生并返回：前端拿它做气泡收敛，必须与库里
+     * 那一行同源。
+     *
+     * **不负责唤醒**：投递方紧接着自己 `wake`（或用 `LoopDriver.post`，两步一起）。
+     */
+    post(input: PostInput): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * 取出本会话待处理的全部消息，**并在同一个事务里落库**（判据在
+     * `ConversationStore.takeInbox`），返回内核要的形态。
+     *
+     * **一轮只被调一次**（内核的第一次迭代，模型开口之前）：轮内后来进来的消息由
+     * `hasPending` 探到后换轮，留给下一个 tick 的这同一个点。所以这里刚落库的
+     * user 行永远早于本轮的任何 assistant 输出。
+     */
+    take(sessionId: string): Promise<DrainedTurnMessage[]>;
+    /**
+     * 只探不取。换轮判据（内核每次调模型前探一下，见 `TurnHost.hasPendingInbox`），
+     * 以及 loop / sweep 判「这个会话还有没有货」的同一个问题。
+     */
+    hasPending(sessionId: string): Promise<boolean>;
+    /** 撤回：只删「自己的」「还没被取走的」那一项。 */
+    withdraw(id: string, userId: string): Promise<InboxItem | null>;
+    /** 本会话的待处理队列。 */
+    listPending(sessionId: string): Promise<InboxItem[]>;
+    /** 此刻还有待处理项的全部会话 id。供启动时补唤醒（wake 是瞬时广播，inbox 是持久的）。 */
+    listSessionIdsWithPending(): Promise<string[]>;
+    /**
+     * 一轮开张：铸那个**三位一体**的 id（`runId` = `streamId` = 本轮 assistant 行主键
+     * = `AgentEvent.messageId`），返回本轮的记录器。值本身只是一个 uuid，这个方法的
+     * 意义是**只有一处会铸它**。
+     */
+    openTurn(sessionId: string): TurnRecorder;
+    /** 落一条消息（按 id 幂等，见 `ConversationStore.appendMessage`）。 */
+    appendMessage(message: Parameters<ConversationStore['appendMessage']>[0]): Promise<ConversationMessage>;
+    /**
+     * setup 阶段失败的可见占位（会话 / agent / 模型解析就抛错，流从未开、`runTurn`
+     * 根本没跑）——不补这条用户会看到彻底的沉默：消息已经进了 inbox，界面上什么都
+     * 不会发生。文案由调用方定（`LoopHost.describeSetupError`）。
+     */
+    appendSetupError(sessionId: string, text: string): Promise<void>;
+    /**
+     * assistant 段落的落库原语（`TurnRecorder.record` 用）。首次建行、之后追加。
+     *
+     * `flushedSeq`：这批 parts 覆盖到的最后一个事件的 seq，**与 parts 同一次写入**
+     * `metadata.flushedSeq`，写成功后才让会话流退役 seq ≤ 它的事件——分开写的话会
+     * 出现「流里已经删了、库里的边界还是旧的」，刷新后前端按旧边界去重，把不该丢的
+     * 尾巴当成重放丢掉。
+     */
+    appendAssistantStep(opts: {
+        messageId: string;
+        runId: string;
+        sessionId: string;
+        parts: MessagePart[];
+        flushedSeq?: number | null;
+        /** 本轮开跑时刻（ms，见 `TurnRecorder.runStartedAt`）。 */
+        runStartedAt?: number | null;
+    }): Promise<void>;
+    /** 一轮收尾：在 `messageId`（= runId）那一行上盖终态 metadata 与整轮 usage。 */
+    finalizeAssistantTurn(opts: {
+        messageId: string;
+        runId: string;
+        metadata: Record<string, unknown>;
+        usage?: Record<string, number>;
+    }): Promise<void>;
+    /**
+     * 收尾一轮被进程死亡打断的轮次在对话流里的痕迹（`OrphanRunSweeper` 用），返回受
+     * 影响的行 id。
+     *
+     * 两条路，判据是「有没有落过库的 assistant 段」：
+     * - **产出过** → 只给还没盖终态的段盖上。已产出的正文原样保留，不追加任何
+     *   解释性文字——那会把模型没说过的话写进它的历史。
+     * - **一个字都没落库**（run 刚 open 就被杀）→ 补一条可见占位。不补的话用户
+     *   那句话孤零零挂着、下面什么都没有，看起来像系统把消息吃了。
+     *
+     * 会话已删（`sessionId` 为 null）时补不了占位，也没必要。
+     */
+    closeInterruptedTurn(runId: string, sessionId: string | null): Promise<string[]>;
+}
+//# sourceMappingURL=message-hub.d.ts.map

package/dist/loop/message-hub.d.ts.map

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