@bolloon/bolloon-agent 0.5.4 → 0.6.0

package/dist/kernel/channel-actor.js

@@ -0,0 +1,297 @@
+/**
+ * **Channel Actor** (K5 第 2 步: 容器)
+ *
+ * 为什么需要它: `messageHistory` / `currentChannelId` / `currentAgentId` / `currentGoalId` 四个字段
+ * 在 Pi 实例上被**所有入口共享** —— 这正是"多通道串台 / 同 Channel 并发改 history"的根。
+ * K2 已按 leo 口径判定它们**不是 Run 状态**, 该由 Channel Actor 承载 (见 `plan-channel-actor.ts`)。
+ *
+ * 本文件是**纯新增的容器**: 不改任何现有行为 (Pi 仍按原样跑)。它提供三件事:
+ *   ① `ActorState` —— Actor 状态容器 (9 项, 与台账逐条对应);
+ *   ② `SerialMailbox` —— 同 Channel **串行**执行队列 (1 个 channel 同时只有 1 个任务在跑);
+ *   ③ `ChannelActor` —— 把两者绑起来: `submit()` 入队并串行执行 · `abort()` 取消当前任务。
+ *
+ * 纪律: 串行语义**真跑验证** (`src/test/kernel-channel-actor.test.ts` 的串行用例), 不靠"看起来对"。
+ */
+/** Actor 状态容器 —— 与 `ACTOR_STATE_ITEMS` 的 9 项一一对应 */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * **当前正在哪个 Actor 的 mailbox 任务里跑** (K5 第 5 步的前置安全网)。
+ *
+ * 为什么必须有: `SerialMailbox` 是**无重入**的 —— 一个已在 mailbox 里跑的任务若再往同一个 mailbox
+ * 投递并 await, 就是**自锁** (新任务排在"自己"后面)。入口投递 (步骤④) 一旦覆盖到"运行中会被调用"
+ * 的执行点 (LLM 回调 / judge / 工具内再问一次), 就会踩到这条。
+ * ⇒ 用 ALS 记住"我在谁的上下文里", 同 actor 重入时**直跑**, 不同 actor 照常排队。
+ */
+const actorCtx = new AsyncLocalStorage();
+/** 当前是否正跑在某个 Actor 的 mailbox 任务内 (诊断用) */
+export function currentActorContext() {
+    return actorCtx.getStore();
+}
+export function createActorState(init = {}) {
+    return {
+        channelId: init.channelId ?? '',
+        agentId: init.agentId ?? '',
+        goalBinding: init.goalBinding ?? '',
+        messageHistory: init.messageHistory ?? [],
+        mailbox: init.mailbox ?? { pending: 0, processed: 0 },
+        activeRun: init.activeRun ?? '',
+        cancellation: init.cancellation ?? null,
+        outboundStream: init.outboundStream ?? null,
+    };
+}
+/**
+ * 同 Channel **串行**邮箱。
+ *
+ * 契约 (K5 验收标准 ①):
+ *   · `submit()` 立即返回 promise, 任务**排队**执行;
+ *   · 同一个 mailbox 内**永不并发** —— 后一个任务在前一个 settle 之后才开始;
+ *   · 一个任务抛错**不阻塞**队列 (错误交给该任务自己的 promise, 队列继续);
+ *   · `pending` 是"已入队未完成"的数量, 用于观测 (不是背压实现)。
+ */
+export class SerialMailbox {
+    tail = Promise.resolve();
+    pendingCount = 0;
+    processedCount = 0;
+    get pending() { return this.pendingCount; }
+    get processed() { return this.processedCount; }
+    submit(task) {
+        this.pendingCount += 1;
+        const run = this.tail.then(async () => {
+            try {
+                return await task();
+            }
+            finally {
+                this.pendingCount -= 1;
+                this.processedCount += 1;
+            }
+        });
+        // 队列尾巴吞掉错误, 避免一个失败任务毒化后续任务 (错误仍由返回的 promise 抛给调用方)
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /** 等队列跑空 (测试与收尾用) */
+    async drain() {
+        await this.tail;
+    }
+}
+/**
+ * 把一个 Channel 的状态与串行队列绑在一起。
+ *
+ * 现在**只是容器**: 还没有任何入口往里投递 (K5 第 4 步才接)。
+ * 因此它不改变现有行为 —— 现有链路仍走 Pi 实例字段。
+ */
+export class ChannelActor {
+    state;
+    mailbox = new SerialMailbox();
+    constructor(init = {}) {
+        this.state = createActorState(init);
+    }
+    /** 投递一次执行 (串行执行)。执行期间 `state.activeRun` 由调用方/后续步骤写入 */
+    submit(fn) {
+        // 任务体内建立 ALS 上下文 ⇒ 任务内部的异步续体也能认出"自己在谁的上下文里"
+        return this.mailbox.submit(() => actorCtx.run(this, () => fn(this.state)));
+    }
+    /**
+     * **K5 第 4 步 — hydrate**: 实现体 (load → filter → 截断 → 替换) 住在 Actor, 业务侧只给纯变换。
+     * 走邮箱 ⇒ 与 append / persist 串行, 不会再出现"读-改-写"三拍被并发踩掉。
+     * 返回灌入条数 (0 = 没历史 / 空 / 加载失败由调用方处理)。
+     */
+    hydrateHistory(spec) {
+        return this.mailbox.submit(async () => {
+            const loaded = await spec.load();
+            if (!loaded)
+                return 0;
+            const next = spec.filter(loaded).slice(-spec.maxMessages);
+            if (next.length === 0)
+                return 0;
+            const arr = this.state.messageHistory;
+            arr.length = 0;
+            arr.push(...next);
+            return next.length;
+        });
+    }
+    /**
+     * **K5 第 4 步 — persist 的取数拍**: 取一份快照 (浅拷贝)。
+     * 走邮箱 ⇒ 拿到的是一致的 history, 不会与正在进行的 append 交错 (原来的 `this.messageHistory.map(...)`
+     * 是"边写边读", 压缩/工具回灌并发时可能落盘到半截状态)。
+     */
+    historySnapshot() {
+        return this.mailbox.submit(() => [...this.state.messageHistory]);
+    }
+    /** **K5 第 4 步 — append (排队版)**: 串行追加 (同 Channel 内排队) */
+    appendMessage(msg) {
+        return this.mailbox.submit(() => { this.state.messageHistory.push(msg); });
+    }
+    /**
+     * **K5 第 4 步 — append (同步漏斗版)**: 给"写完立刻要读到"的调用面用 (Pi 的 ReAct 循环里大量
+     * `push` 后马上读 `length`/索引) —— 不能改成 await, 否则会改变同拍可见性。
+     *
+     * 它提供的是**归属与可数性** (所有 history 写入收敛到唯一漏斗, 门可以断言"零处直写"),
+     * **不是并发安全** —— 并发安全由"入口投递进 mailbox"负责 (K5 第 5 步 / entriesWired)。
+     */
+    appendMessageSync(msg) {
+        this.state.messageHistory.push(msg);
+    }
+    /** **K5 第 4 步 — pop 漏斗** (与 appendMessageSync 同性质: 归属可数, 不负责并发) */
+    popMessageSync() {
+        return this.state.messageHistory.pop();
+    }
+    /**
+     * **K5 第 4 步 — compact 的落地拍 (rebase)**: 用压缩结果替换 history, 但**保住**变换期间新追加的尾部。
+     *
+     * 为什么必须有这一拍: 压缩流水线是 **async** —— 从"取快照"(`snapshotLen`) 到"落地"之间是 await 窗口,
+     * 期间 append 进来的消息会被整块替换**丢掉** (lost update)。这里把尾部原样接回去。
+     * (同步压缩路径不受影响: 取快照与替换在同一拍相邻两行, 没有窗口 —— 见 pi-sdk 的注释。)
+     */
+    rebaseHistory(compacted, snapshotLen) {
+        return this.mailbox.submit(() => {
+            const arr = this.state.messageHistory;
+            const at = Math.max(0, Math.min(snapshotLen, arr.length));
+            const tail = arr.slice(at);
+            arr.length = 0;
+            arr.push(...compacted, ...tail);
+            return { keptTail: tail.length };
+        });
+    }
+    /** **K5 第 4 步 — 整体替换漏斗** (hydrate 回灌 / 压缩后的整体赋值都走这里) */
+    replaceHistory(next) {
+        const arr = this.state.messageHistory;
+        arr.length = 0;
+        arr.push(...next);
+    }
+    /** 取消当前任务: 中断 signal, 队列继续 (后续任务看到的是新的 controller) */
+    abort(reason = 'aborted') {
+        this.state.cancellation?.abort(reason);
+        this.state.cancellation = null;
+    }
+    /** 开一个新的取消位 (进入一次执行时用) */
+    beginCancellation() {
+        const ac = new AbortController();
+        this.state.cancellation = ac;
+        return ac.signal;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Actor 注册表 (K5 第 3 步): 一个 channel 一个 actor
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 进程内注册表: **会话身份 → ChannelActor**。
+ *
+ * ⚠️ 键是**会话身份** (SessionStore key / 整条 peerId), **不是** channel 前缀 —— 这条是被全量回归打出来的:
+ *   第一版取 `peerId` 的 `:` 前段当键 ⇒ 同一 channel 下不同会话落进同一个桶 ⇒ 新 session 一构造
+ *   就看到别人的 history (4742 测试里 5 红, 症状统一 `expected 2/5/6 to be 0`)。
+ *   隔离粒度必须与被迁移状态原有的粒度一致: history 属于**会话**, 不属于 channel 前缀。
+ *
+ * ⚠️ **没有身份就不归属** (没有 'default' 兜底桶) —— 宁可不共享, 不许串台。这里先把"落点"建起来。
+ *
+ * ⚠️ 现在的定位 (不许夸大):
+ *   · 只做**归属**: 同一 channelId 永远拿到同一个 actor 实例, 不同 channelId 互不相干;
+ *   · **还没有任何入口把执行投递进来** (`submit()` 尚未被业务调用) ⇒ K5 进度里
+ *     `entriesWired` 仍是 **0/4**, 行为与迁移前一致;
+ *   · 进程内 (非持久): 重启后 actor 表为空 —— 持久化是后续步骤 (history/Goal/Run 的恢复)。
+ */
+const actors = new Map();
+/**
+ * 取(或建)某 channel 的 actor。
+ * `init` **只在新建时生效** (既有 actor 不会被 init 覆盖 —— 避免"后到的调用把先建的会话状态冲掉")。
+ */
+export function getOrCreateActor(actorKey, init = {}) {
+    const key = actorKey;
+    const existing = actors.get(key);
+    if (existing)
+        return existing;
+    // ⚠️ **不拿身份键当 channel 绑定**: `state.channelId` 的语义 = 会话当前绑定的 channel
+    //    (与 Pi 的 currentChannelId 一致, 由 prompt/入口设置)。工厂若预置成 peerId 前缀,
+    //    会让会话在入口设置之前就读到非空值 (snapshot / compaction cacheScope 都会跟着变) —— 静默行为变化。
+    const created = new ChannelActor({ ...init });
+    actors.set(key, created);
+    return created;
+}
+/** 只读探查 (不建) —— 测试与诊断用 */
+export function peekActor(actorKey) {
+    return actors.get(actorKey);
+}
+/** 当前 actor 数 (诊断用) */
+export function actorCount() {
+    return actors.size;
+}
+/** 清空注册表 —— **仅测试用** (避免测试之间互相污染) */
+export function resetActors() {
+    actors.clear();
+    channelQueues.clear();
+    privateActorsCreated = 0;
+}
+export async function deliverThroughActor(
+// 形参故意放宽成 `unknown`: 调用点的 receiver 类型五花八门 (AgentSession / 结构子集 / any),
+//   写成 `{ actor?: ChannelActor }` 会触发 TS 的弱类型检查 ("no properties in common") 而误报。
+//   实际用法由下面这行运行时取值保证 (取不到 actor 就直跑)。
+holder, run, opts = {}) {
+    const actor = holder?.actor;
+    if (!actor || typeof actor.submit !== 'function')
+        return run();
+    // **重入保护**: 已经跑在同一个 actor 的 mailbox 任务里 ⇒ 直跑。
+    //   否则"运行中被调用的执行点"(LLM 回调 / judge / 工具内再问) 会往自己的队列尾投递 ⇒ **自锁**。
+    if (actorCtx.getStore() === actor)
+        return run();
+    // channel 级串行 (opt-in): 走 channel 队列; 同样要防重入 (已在同一 channel 队列任务里 ⇒ 直跑)
+    if (opts.serializeByChannel) {
+        const ch = actor.state.channelId;
+        if (ch) {
+            const q = getChannelQueue(ch);
+            if (channelCtx.getStore() === q)
+                return run();
+            return q.submit(() => channelCtx.run(q, () => actor.submit(() => actorCtx.run(actor, () => run()))));
+        }
+    }
+    return actor.submit(run);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// channel 级串行锁 (K5 步骤⑤) —— **能力先落地, 默认不启用**
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * channel 级队列注册表: `channelId → 串行队列`。
+ *
+ * 为什么要它 / 为什么默认不启用 (证据在 `plan-channel-actor.ts` 的 `K5_CHANNEL_LOCK`):
+ *   · **证据**: web 的 channel 只有一个 `currentSessionId` ⇒ 用户消息都投到**同一个会话身份**
+ *     ⇒ 身份级串行 (mailbox) **已经把该 channel 的输入串起来了** —— 验收①在活跃会话上已成立。
+ *   · **能力**: 会话切换 (`[新会话] 已切换`) 后旧会话仍在内存, 此时两个身份可能并行 —— 若要"跨会话切换也串行",
+ *     需要 channel 级锁。
+ *   · **代价**: 同 channel 的**多个 agent** (P2P 多智能体) 也会被串起来 ⇒ 吞吐下降。
+ *     ⇒ 是否全局启用是**意图层**的决定 (leo), 这里只把能力与证据备好, 由台账的 `enabled` 开关控制。
+ */
+const channelQueues = new Map();
+/** 取(或建)某 channel 的串行队列 */
+export function getChannelQueue(channelId) {
+    const key = channelId || 'default';
+    let q = channelQueues.get(key);
+    if (!q) {
+        q = new SerialMailbox();
+        channelQueues.set(key, q);
+    }
+    return q;
+}
+/** 当前 channel 队列数 (诊断用) */
+export function channelQueueCount() {
+    return channelQueues.size;
+}
+/** channel 队列上下文 (重入判定用; 与 actorCtx 同理 —— 不许自锁) */
+const channelCtx = new AsyncLocalStorage();
+// ─────────────────────────────────────────────────────────────────────────────
+// 私有 actor (K5 步骤⑧): 给"没有会话身份"的 session 用
+// ─────────────────────────────────────────────────────────────────────────────
+let privateActorsCreated = 0;
+/**
+ * 造一个**私有** actor: **不注册**进 `actors`, 所以别人拿不到它 ⇒ 不可能串台。
+ *
+ * 为什么需要它 (K5 步骤⑧ 的前提): 要删掉 Pi 实例侧的"绑定前暂存"字段, 就必须保证**任何 session 都有 actor**。
+ * 没有身份时不许猜键 (猜就会共享) —— 那就给它一个**谁也拿不到**的私有 actor:
+ * 隔离性比"共享"更保守, 语义与"暂存字段"完全等价 (每个 session 自己一份)。
+ */
+export function createPrivateActor() {
+    privateActorsCreated += 1;
+    return new ChannelActor();
+}
+/** 已创建的私有 actor 数 (诊断/测试用: 证明"每个无身份 session 各拿一份") */
+export function privateActorCount() {
+    return privateActorsCreated;
+}

package/dist/kernel/control.js

@@ -0,0 +1,95 @@
+export const RUN_CONTROL_KINDS = ['record-recovery', 'set-run-status', 'wake-goal'];
+/** 每种请求**必须**携带的定位字段 (校验用; 缺了直接拒, 不许猜) */
+export const RUN_CONTROL_REQUIRED = {
+    'record-recovery': 'runId',
+    'set-run-status': 'runId',
+    'wake-goal': 'goalId',
+};
+/**
+ * 端口**不抛异常但明确拒绝** (`{ ok: false, reason }`) 的归一化判定。
+ *   为什么必须有: store 类原语用返回值表达"状态迁移被拒绝", 而控制面若只看"有没有抛",
+ *   就会把**被拒当成成功** (实测: pause/abort 路由依赖 `r.ok`/`r.reason` 回 409)。
+ *   ⇒ 约定: 端口返回 `{ ok: false }` ⇒ 控制面也报 ok=false, detail = `端口拒绝: <reason>`。
+ */
+function portRefusal(res) {
+    if (res && typeof res === 'object' && 'ok' in res) {
+        const r = res;
+        if (r.ok === false)
+            return `端口拒绝: ${String(r.reason ?? '未给原因')}`;
+    }
+    return null;
+}
+const audit = [];
+const AUDIT_MAX = 200;
+/** 审计流水 (最近 N 条; 测试与运维可读) */
+export function runControlAudit() {
+    return audit;
+}
+export function resetRunControlAudit() {
+    audit.length = 0;
+}
+/**
+ * 提交一条控制请求。**唯一入口** —— 校验 (kind 合法 / 定位字段齐 / origin 非空) → 派发到 port → 记审计。
+ * 一律**返回结果对象**, 不抛 (调用方不该用 try/catch 表达"请求被拒")。
+ */
+export async function submitRunControl(req, ports) {
+    const kind = req?.kind;
+    const finish = (ok, detail, port, result) => {
+        audit.push({
+            at: Date.now(),
+            kind,
+            origin: req?.origin ?? '(anonymous)',
+            target: String(req?.runId ?? req?.goalId ?? ''),
+            ok,
+            detail,
+        });
+        if (audit.length > AUDIT_MAX)
+            audit.splice(0, audit.length - AUDIT_MAX);
+        return { ok, kind, via: 'kernel-control', detail, port, result };
+    };
+    if (!RUN_CONTROL_KINDS.includes(kind))
+        return finish(false, `未知请求类型: ${String(req?.kind)}`);
+    if (!req.origin)
+        return finish(false, '缺少 origin (审计要求: 不许匿名请求)');
+    const need = RUN_CONTROL_REQUIRED[kind];
+    const target = need === 'runId' ? req.runId : req.goalId;
+    if (!target)
+        return finish(false, `${kind} 缺少 ${need}`);
+    if (kind === 'record-recovery') {
+        if (typeof ports.recordRecovery !== 'function')
+            return finish(false, 'port 未注入: recordRecovery');
+        try {
+            const res = await ports.recordRecovery(target, req.payload ?? {});
+            const refusal = portRefusal(res);
+            return refusal ? finish(false, refusal, 'recordRecovery', res) : finish(true, undefined, 'recordRecovery', res);
+        }
+        catch (err) {
+            return finish(false, `recordRecovery 失败: ${String(err?.message ?? err).slice(0, 160)}`);
+        }
+    }
+    if (kind === 'set-run-status') {
+        if (typeof ports.setRunStatus !== 'function')
+            return finish(false, 'port 未注入: setRunStatus');
+        const status = String(req.payload?.status ?? '');
+        if (!status)
+            return finish(false, 'set-run-status 缺少 payload.status');
+        try {
+            const res = await ports.setRunStatus(target, status, req.payload);
+            const refusal = portRefusal(res);
+            return refusal ? finish(false, refusal, 'setRunStatus', res) : finish(true, undefined, 'setRunStatus', res);
+        }
+        catch (err) {
+            return finish(false, `setRunStatus 失败: ${String(err?.message ?? err).slice(0, 160)}`);
+        }
+    }
+    if (typeof ports.setContinuation !== 'function')
+        return finish(false, 'port 未注入: setContinuation');
+    try {
+        const res = await ports.setContinuation(target, req.payload ?? {});
+        const refusal = portRefusal(res);
+        return refusal ? finish(false, refusal, 'setContinuation', res) : finish(true, undefined, 'setContinuation', res);
+    }
+    catch (err) {
+        return finish(false, `setContinuation 失败: ${String(err?.message ?? err).slice(0, 160)}`);
+    }
+}