@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/dist/loop/orphan-run.sweeper.js

@@ -0,0 +1,145 @@
+import { LOCK_TTL_MS, } from '../ports/coordination.js';
+import { silentLogger } from '../ports/logger.js';
+/**
+ * 两次 sweep 的间隔。也是「进程被杀后多久那一轮才会被收尾」的上界之一——
+ * 另一个是会话锁的自然过期（`LOCK_TTL_MS`），两者相加即最坏延迟。
+ */
+export const SWEEP_INTERVAL_MS = 60_000;
+/** run 开跑多久之后才纳入候选：给「run 刚记下、锁的抢占与本次探测交叉」留出宽限。 */
+export const ORPHAN_MIN_AGE_MS = LOCK_TTL_MS;
+export const INTERRUPTED_ERROR = '服务中断（进程重启），本轮未跑完。';
+/**
+ * 收尾「进程被杀留下的半截轮次」。
+ *
+ * 一轮的终态**只存在于跑它的那个进程的内存里**：跑次的 `finish()`、消息上的终态
+ * metadata 都在 tick 跑完那一刻才写。进程没了，这两个写入永远不会发生——跑次永久
+ * 停在 running、前端把那条没盖终态的消息当成「一轮真的还在飞」，每次刷新都卡成
+ * 「进行中」，点停止也救不回来（活跃登记簿随进程没了）。
+ *
+ * 判据是 **「该会话此刻有没有 loop 持锁」**：锁在整个 tick 期间持有并定期续租，
+ * 而 `finish()` 发生在 `release()` 之前，故「无锁 + 仍 running」是确定的孤儿，多
+ * 实例部署下也不会误伤别的实例正在跑的轮次。这条判据继承了会话锁的口径（锁过期 =
+ * 跑它的 loop 已经死了），误判的后果也是收敛的：`markInterrupted` 只在仍 running
+ * 时翻牌，那个进程后来恢复并 `finish()` 会覆盖成真实终态。
+ *
+ * **周期跑而不是只在启动跑一次**：进程被杀时会话锁不会主动释放，要等 TTL 自然
+ * 过期。启动那一刻锁多半还在，启动那次会（正确地）跳过所有候选。
+ */
+export class OrphanRunSweeper {
+    deps;
+    timer;
+    logger;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = deps.logger ?? silentLogger('');
+    }
+    /**
+     * 启动：立刻扫一次、把 inbox 有积压的会话各叫醒一次，之后周期扫。都是
+     * fire-and-forget，绝不阻塞 / 拖垮启动。返回停止函数（同 `dispose`）。
+     */
+    start() {
+        void this.sweep().catch(err => this.logger.error(`orphan sweep failed at boot: ${String(err)}`));
+        void this.wakePendingInboxes().catch(err => this.logger.error(`inbox wake failed at boot: ${String(err)}`));
+        this.timer ??= setInterval(() => {
+            void this.sweep().catch(err => this.logger.error(`orphan sweep failed: ${String(err)}`));
+        }, this.deps.intervalMs ?? SWEEP_INTERVAL_MS);
+        // 定时器不该拖着进程不让它退出。
+        this.timer.unref?.();
+        return () => this.dispose();
+    }
+    dispose() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /**
+     * 扫一轮孤儿 run 并收尾，返回收了几条。no-throw 到单条粒度：一条坏记录不能中断
+     * sweep（否则它后面那些本可以修好的轮次会一直卡着）。
+     */
+    async sweep() {
+        const candidates = await this.deps.runs.findStaleRunning(this.deps.minAgeMs ?? ORPHAN_MIN_AGE_MS);
+        if (candidates.length === 0)
+            return 0;
+        let swept = 0;
+        for (const run of candidates) {
+            try {
+                if (await this.finalizeOrphan(run))
+                    swept++;
+            }
+            catch (err) {
+                this.logger.error(`orphan sweep: finalize run ${run.id} failed: ${String(err)}`);
+            }
+        }
+        if (swept > 0) {
+            this.logger.warn(`orphan sweep: finalized ${swept} interrupted run(s) of ${candidates.length} candidate(s)`);
+        }
+        return swept;
+    }
+    /** 单条候选的处置。返回它是否真的由本次调用收的尾。 */
+    async finalizeOrphan(run) {
+        const { sessionId } = run;
+        // 会话还在跑 → 不是孤儿。会话已删（sessionId 为 null）则没有锁可问，照常收尾。
+        if (sessionId && (await this.deps.lock.isHeld(sessionId)))
+            return false;
+        // 翻牌失败 = 别人抢先收过尾了，后面几步一律不做。
+        if (!(await this.deps.runs.markInterrupted(run.id, INTERRUPTED_ERROR))) {
+            return false;
+        }
+        const messageIds = await this.deps.hub.closeInterruptedTurn(run.id, sessionId);
+        if (sessionId && this.deps.onRunOrphaned) {
+            try {
+                await this.deps.onRunOrphaned({ ...run, sessionId });
+            }
+            catch (err) {
+                this.logger.warn(`orphan sweep: onRunOrphaned for session ${sessionId} failed: ${String(err)}`);
+            }
+        }
+        // 补发一条 run-finish 到会话面：**已经开着页面的用户不必刷新**就能看到这轮
+        // 收尾。刷新过来的用户则靠上面盖进库的终态 metadata——两条路都要有：流有保留
+        // 期，metadata 是永久的。
+        if (sessionId && run.rootSessionId) {
+            this.publishRunFinish(run, sessionId, run.rootSessionId, messageIds[0]);
+        }
+        return true;
+    }
+    publishRunFinish(run, sessionId, rootSessionId, messageId) {
+        const event = {
+            // 会话面自己分配游标，seq 对它无意义。
+            seq: 0,
+            streamId: run.streamId,
+            rootSessionId,
+            sessionId,
+            runId: run.id,
+            // 没有落库过任何 assistant 段时退回 runId —— 那也正是第一段本该用的 id。
+            messageId: messageId ?? run.id,
+            parentRunId: run.parentRunId,
+            depth: run.depth,
+            ts: Date.now(),
+            type: 'run-finish',
+            payload: { status: 'aborted', stopReason: 'aborted' },
+        };
+        this.deps.bus.publishSessionEvent(event);
+    }
+    /**
+     * 把「inbox 里还有待处理项」的会话各叫醒一次（wake 是瞬时广播，没有持久化；进程
+     * 在「已投递、loop 还没取」之间被杀，那条消息就只剩存储里一行，谁也不会再来叫醒
+     * 它）。只在启动跑：正常运行期间 `onWake` 收尾时会自查并重新广播。多实例同时启动
+     * 各 wake 一次也无害——抢锁只有一个赢。
+     */
+    async wakePendingInboxes() {
+        const sessionIds = await this.deps.hub.listSessionIdsWithPending();
+        for (const sessionId of sessionIds) {
+            try {
+                await this.deps.wake.wake(sessionId);
+            }
+            catch (err) {
+                this.logger.error(`inbox wake: wake(${sessionId}) failed: ${String(err)}`);
+            }
+        }
+        if (sessionIds.length > 0) {
+            this.logger.warn(`inbox wake: re-woke ${sessionIds.length} session(s) with pending items at boot`);
+        }
+        return sessionIds.length;
+    }
+}
+//# sourceMappingURL=orphan-run.sweeper.js.map

package/dist/loop/orphan-run.sweeper.js.map

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

package/dist/loop/root-host.d.ts

@@ -0,0 +1,51 @@
+import { type ContextBudgetTracker } from '../context/context-budget-tracker.js';
+import type { ContextStore } from '../ports/context-store.js';
+import { type ProjectionOptions } from '../turn/parts-to-model-messages.js';
+import type { TurnHost, TurnResult } from '../turn/turn-envelope.js';
+import type { TurnRecorder } from './message-hub.js';
+/** `createRootTurnHost` 的入参。 */
+export interface RootTurnHostOptions {
+    /** 本轮的记录器（`MessageHub.openTurn`；`LoopDriver` 交给 `LoopHost.buildTurn` 的那一个）。 */
+    recorder: TurnRecorder;
+    /**
+     * system prompt 拼装。**只放 tick 间稳定的内容**——它一变，后面全部历史在前缀
+     * 缓存里一起 miss。
+     */
+    assembleSystem: (agentPrompt: string) => Promise<string>;
+    /**
+     * 本轮的上下文预算（`createContextBudgetTracker`，**一个 tick 一个**：它持有轮初
+     * 那批行的快照，跨 tick 复用会让快照过期）。给了就由它投影历史、经 `turnState`
+     * 交给 `beforeModelCall` 钩子、终态落 `contextThreshold`——三方同一个实例。
+     *
+     * 不给 = 不腾空间：历史按存储里现有的两个指针直接投影。
+     */
+    budget?: ContextBudgetTracker | null;
+    /** 不给 `budget` 时投影历史的来源（通常就是 `MessageHub.store`）。 */
+    contextStore?: ContextStore;
+    /**
+     * 本轮模型的上下文窗口，随终态落进 metadata（`contextWindow`）。**分母跟着分子一起
+     * 落**：事后去查模型行会取到此刻那一版，历史那一轮的比例就成了拿今天的分母除
+     * 昨天的分子。null / 不给 = 不落。
+     */
+    contextWindow?: number | null;
+    /** 投影选项（宿主登记的提醒类行 `reminderKinds`、工具旧名 `toolNameAliases`）。 */
+    projection?: Pick<ProjectionOptions, 'reminderKinds' | 'toolNameAliases'>;
+    /**
+     * 收尾之后的宿主钩子（自动命名、轮后追问、形式的轮末钩子……）。`wrote` = 这一轮在
+     * 对话流里留下东西了没有（空转轮为 false，命名的材料压根不存在）。
+     *
+     * **别在这里抛**：它的调用方是一轮的收尾，这里的失败不该改写那一轮的结局。要做
+     * 慢活就自己 fire-and-forget。
+     */
+    afterPersist?: (result: TurnResult, wrote: boolean) => void | Promise<void>;
+}
+/**
+ * 根 turn 的参考宿主：把内核那几个与消息有关的钩子（drain / 换轮探测 / 增量落库 /
+ * 收尾）接到本轮的 `TurnRecorder` 上，另外接上下文预算。**一轮一行**：一次 tick 的
+ * 全部产出落成 `id = runId` 的一条 assistant 消息。
+ *
+ * 宿主自己的东西（system prompt 拼什么、轮后做什么）经入参注入；需要更多时照着本
+ * 函数自己写一个 `TurnHost` 也完全可以，内核只认接口。
+ */
+export declare function createRootTurnHost(opts: RootTurnHostOptions): TurnHost;
+//# sourceMappingURL=root-host.d.ts.map

package/dist/loop/root-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-host.d.ts","sourceRoot":"","sources":["../../src/loop/root-host.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,gCAAgC;AAChC,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,QAAQ,EAAE,YAAY,CAAC;IACvB;;;OAGG;IACH,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACrC,qDAAqD;IACrD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,iBAAiB,CAAC,CAAC;IAC1E;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,QAAQ,CA6CtE"}

package/dist/loop/root-host.js

@@ -0,0 +1,65 @@
+import { CONTEXT_BUDGET_TURN_STATE_KEY, } from '../context/context-budget-tracker.js';
+import { partsToModelMessages, } from '../turn/parts-to-model-messages.js';
+/**
+ * 根 turn 的参考宿主：把内核那几个与消息有关的钩子（drain / 换轮探测 / 增量落库 /
+ * 收尾）接到本轮的 `TurnRecorder` 上，另外接上下文预算。**一轮一行**：一次 tick 的
+ * 全部产出落成 `id = runId` 的一条 assistant 消息。
+ *
+ * 宿主自己的东西（system prompt 拼什么、轮后做什么）经入参注入；需要更多时照着本
+ * 函数自己写一个 `TurnHost` 也完全可以，内核只认接口。
+ */
+export function createRootTurnHost(opts) {
+    const { recorder, budget } = opts;
+    const sessionId = recorder.sessionId;
+    if (!budget && !opts.contextStore) {
+        throw new Error('createRootTurnHost: need either budget or contextStore');
+    }
+    return {
+        // 经 tracker 投影：投影出来的历史与它随后用来算切点的那份行快照必须是同一批
+        // （腾空间时替换的是这次投影出来的头部）。
+        loadContext: () => budget ? budget.load() : projectStored(opts, sessionId),
+        ...(budget
+            ? { turnState: new Map([[CONTEXT_BUDGET_TURN_STATE_KEY, budget]]) }
+            : {}),
+        assembleSystem: opts.assembleSystem,
+        // 取出 inbox 并落库（同一个事务）；「本轮领到过东西没有」由 recorder 记账。
+        drainInbox: () => recorder.take(),
+        // 换轮判断点：只探不取，消息留给下一个 tick 的 drain。
+        hasPendingInbox: () => recorder.hasPending(),
+        onAssistantStep: (parts, uptoSeq) => recorder.record(parts, uptoSeq),
+        persist: async (result) => {
+            const threshold = budget?.threshold ?? null;
+            const wrote = await recorder.close({
+                status: result.status,
+                stopReason: result.stopReason,
+                error: result.error,
+                usage: result.usage,
+                metadata: {
+                    // 下一轮开头的压力基线。落在 metadata 而不是 usage：后者是「这一轮花了
+                    // 多少」的累加账单，这个是「上下文当时有多大」的一次快照。
+                    ...(result.contextTokens !== undefined
+                        ? { contextTokens: result.contextTokens }
+                        : {}),
+                    ...(opts.contextWindow != null
+                        ? { contextWindow: opts.contextWindow }
+                        : {}),
+                    // 界面上「快满了」的判据读它，不自己再算一遍比例。
+                    ...(threshold !== null
+                        ? { contextThreshold: Math.round(threshold) }
+                        : {}),
+                },
+            });
+            await opts.afterPersist?.(result, wrote);
+        },
+    };
+}
+async function projectStored(opts, sessionId) {
+    const store = opts.contextStore;
+    const { rows, prunedUptoSeq, compactedUptoSeq } = await store.loadContextInputs(sessionId);
+    return partsToModelMessages(rows, {
+        prunedUptoSeq,
+        compactedUptoSeq,
+        ...opts.projection,
+    });
+}
+//# sourceMappingURL=root-host.js.map

package/dist/loop/root-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-host.js","sourceRoot":"","sources":["../../src/loop/root-host.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,6BAA6B,GAE9B,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EACL,oBAAoB,GAErB,MAAM,oCAAoC,CAAC;AAyC5C;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAyB;IAC1D,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC;IACrC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO;QACL,4CAA4C;QAC5C,uBAAuB;QACvB,WAAW,EAAE,GAA4B,EAAE,CACzC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC;QACzD,GAAG,CAAC,MAAM;YACR,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,6BAA6B,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE;YACnE,CAAC,CAAC,EAAE,CAAC;QACP,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,gDAAgD;QAChD,UAAU,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE;QACjC,mCAAmC;QACnC,eAAe,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE;QAC5C,eAAe,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;QACpE,OAAO,EAAE,KAAK,EAAC,MAAM,EAAC,EAAE;YACtB,MAAM,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,IAAI,CAAC;YAC5C,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC;gBACjC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,QAAQ,EAAE;oBACR,6CAA6C;oBAC7C,+BAA+B;oBAC/B,GAAG,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS;wBACpC,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE;wBACzC,CAAC,CAAC,EAAE,CAAC;oBACP,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI;wBAC5B,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE;wBACvC,CAAC,CAAC,EAAE,CAAC;oBACP,2BAA2B;oBAC3B,GAAG,CAAC,SAAS,KAAK,IAAI;wBACpB,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;wBAC7C,CAAC,CAAC,EAAE,CAAC;iBACR;aACF,CAAC,CAAC;YACH,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC3C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,IAAyB,EACzB,SAAiB;IAEjB,MAAM,KAAK,GAAG,IAAI,CAAC,YAA4B,CAAC;IAChD,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,gBAAgB,EAAE,GAC7C,MAAM,KAAK,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC3C,OAAO,oBAAoB,CAAC,IAAI,EAAE;QAChC,aAAa;QACb,gBAAgB;QAChB,GAAG,IAAI,CAAC,UAAU;KACnB,CAAC,CAAC;AACL,CAAC"}

package/dist/ports/context-store.d.ts

@@ -0,0 +1,69 @@
+import type { MessagePart } from '../schema/index.js';
+/**
+ * 上下文预算要的那一份会话历史里的一行。
+ *
+ * 只有投影与切点用得上的字段：`seq` 判阴影区，`kind` 让投影层认出 checkpoint 行
+ * （提到最前面 + 包围栏）——**漏给 `kind` 的症状是那条摘要排在保留下来的历史后面、
+ * 且不带围栏，两样都不报错**。宿主的行若把 kind 放在 metadata 里，在实现端口时
+ * 摊平到这里。
+ */
+export interface ContextRow {
+    seq: number;
+    role: string;
+    parts: MessagePart[];
+    kind?: string | null;
+}
+/**
+ * 上下文预算的一整套输入，**必须来自同一时刻**：指针比行新会让投影裁掉一段根本
+ * 没在 `rows` 里的历史（无害），反过来则会让刚推进过的指针被一份旧快照当成
+ * 「没推进」，白白重算一次。
+ */
+export interface ContextInputs {
+    /** 会话的全部消息行，按 seq 升序。 */
+    rows: ContextRow[];
+    /** 裁剪指针；null = 从未裁剪。 */
+    prunedUptoSeq: number | null;
+    /** 压缩指针；null = 从未压缩。 */
+    compactedUptoSeq: number | null;
+    /**
+     * 跨轮压力基线：上一轮最后一次模型调用报回的输入 token 数（`TurnResult.contextTokens`
+     * 由宿主落库的那个数）。null = 没有（会话头一轮，或宿主不记）。
+     */
+    baselineContextTokens: number | null;
+}
+/**
+ * 上下文预算的存储端口：读历史与两个指针、推进裁剪指针、提交一次压缩。
+ *
+ * **只是消费方视角的一个窄接口**。agent-base 里这三件分属两处——读与裁剪指针在
+ * 会话服务、checkpoint 落库在消息中心（`chat_message` 的唯一写入方）——宿主实现
+ * 本端口时照样可以各自委托过去，端口不要求它们合并。
+ */
+export interface ContextStore {
+    loadContextInputs(sessionId: string): Promise<ContextInputs>;
+    /**
+     * 推进裁剪指针。**只增不减**：实现必须取 `max(旧值, seq)`（SQL 里是
+     * `greatest(coalesce(…, 0), seq)`），两个并发 tick 各自算出切点时，晚到的那个
+     * 较小值不许把指针拉回去——拉回去等于让已经换成存根的正文重新进上下文，前缀
+     * 缓存整段 miss。
+     */
+    advancePrunedUpto(sessionId: string, seq: number): Promise<void>;
+    /**
+     * 提交一次压缩：落 checkpoint 行（role `user`、`kind = COMPACTION_CHECKPOINT_KIND`、
+     * 一个 text part 装摘要）+ 把压缩指针推到 `seq`（同样只增不减），**原子地**。
+     *
+     * 拆开就有两种半成品，都是静默的：只落了行 = 模型下一轮把同一段历史读两遍
+     * （原文和摘要各一份）；只推了指针 = 那段历史凭空消失，且指针退不回去。
+     *
+     * 返回落下的那一行：调用方要它的 `seq` 更新快照（下一次压缩的切点必须覆盖它）。
+     */
+    appendCheckpoint(input: {
+        sessionId: string;
+        /** 压缩切点（含）。 */
+        seq: number;
+        /** 纯摘要正文，**不带围栏**（围栏是投影时的呈现）。 */
+        summary: string;
+    }): Promise<ContextRow & {
+        id: string;
+    }>;
+}
+//# sourceMappingURL=context-store.d.ts.map

package/dist/ports/context-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.d.ts","sourceRoot":"","sources":["../../src/ports/context-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,wBAAwB;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE7D;;;;;OAKG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;;;;;;;OAQG;IACH,gBAAgB,CAAC,KAAK,EAAE;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,eAAe;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,iCAAiC;QACjC,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,UAAU,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1C"}

package/dist/ports/context-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context-store.js.map

package/dist/ports/context-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.js","sourceRoot":"","sources":["../../src/ports/context-store.ts"],"names":[],"mappings":""}

package/dist/ports/conversation-store.d.ts

@@ -0,0 +1,144 @@
+import type { MessagePart } from '../schema/index.js';
+import type { ContextStore } from './context-store.js';
+/**
+ * `user_message` 用户 / 父 Agent 说的话；`tool_result` 子 Agent 回执；
+ * `system_reminder` 平台自己插进会话的提醒——落库成带 `metadata.kind` 的 user 行，
+ * 投影层按那个标记包围栏。
+ */
+export type InboxMessageKind = 'user_message' | 'tool_result' | 'system_reminder';
+export type InboxSourceKind = 'user' | 'tool' | 'system';
+/** inbox 里排队的一条消息。 */
+export interface InboxItem {
+    id: string;
+    /** 投递序（单调递增）。**取出时按它排，不按挂钟**——挂钟会回拨。 */
+    seq: number;
+    sessionId: string;
+    kind: InboxMessageKind;
+    sourceKind: InboxSourceKind;
+    /** 谁发的（系统触发为 null）。撤回按它判归属。 */
+    sourceUserId: string | null;
+    /**
+     * 结构化来源（子 Agent 回执的 handle / status / stopReason；`system_reminder` 必须
+     * 带 `{ kind }`）。
+     */
+    source: Record<string, unknown> | null;
+    parts: MessagePart[];
+    /**
+     * 落库时要用的消息主键，投递那一刻由 `MessageHub.post` 铸好、随行贯通——前端拿到的
+     * id 与库里那一行同源。
+     */
+    messageId: string;
+}
+/** 会话里落了库的一条消息。 */
+export interface ConversationMessage {
+    id: string;
+    sessionId: string;
+    /** 会话内单调递增（裁剪 / 压缩指针按它判阴影区）。 */
+    seq: number;
+    role: 'user' | 'assistant';
+    parts: MessagePart[];
+    metadata: Record<string, unknown> | null;
+    tokenUsage?: Record<string, number> | null;
+}
+/** 要落的一条消息（`appendMessage` / `takeInbox` 的输入）。 */
+export interface NewConversationMessage {
+    /** 指定主键（幂等的基础）；省略则由存储生成。 */
+    id?: string;
+    sessionId: string;
+    role: 'user' | 'assistant';
+    parts: MessagePart[];
+    metadata?: Record<string, unknown>;
+    tokenUsage?: Record<string, number>;
+}
+/**
+ * 会话存储：消息行 + inbox + 两个上下文指针（继承 `ContextStore`）。
+ *
+ * **只是存储**。「一条消息怎么产生、取出时怎么换成模型要的形态、一轮怎么收尾」归
+ * runtime 的 `MessageHub` / `TurnRecorder`——它们是本端口唯一的写入方，宿主别绕过
+ * 它们直接写（agent-base 的边界原样保留：消息中心是 `chat_message` 与 `agent_inbox`
+ * 的唯一写入方）。读不受此限。
+ *
+ * 「会话有了新动静」（列表按更新时间排序）由实现自己在 `appendMessage` /
+ * `appendAssistantStep` / `takeInbox` 里顺带记；`appendCheckpoint` /
+ * `advancePrunedUpto` **不该**记（后台腾空间不是新动静）。
+ */
+export interface ConversationStore extends ContextStore {
+    /** 投递进 inbox。 */
+    enqueue(item: Omit<InboxItem, 'id' | 'seq'>): Promise<void>;
+    /**
+     * 取出本会话 inbox 里的全部消息并落库，**原子地**（取出与落库同一个事务）。
+     *
+     * 拆成「先取后写」两步的话，中间失败就两边都没有了——丢的是用户亲手发的话。
+     * 按 `seq` 升序处理；`toMessage` 把一条 inbox 项换成要落的那一行（纯函数，
+     * 由 `MessageHub` 给）。返回每一项与它落下的那一行，顺序同 `seq`。
+     *
+     * 落库按 id 幂等（同 `appendMessage`）。
+     */
+    takeInbox(sessionId: string, toMessage: (item: InboxItem) => NewConversationMessage): Promise<Array<{
+        item: InboxItem;
+        message: ConversationMessage;
+    }>>;
+    /** 只探不取。 */
+    hasPending(sessionId: string): Promise<boolean>;
+    /** 本会话的待处理队列（按 seq 升序）。 */
+    listPending(sessionId: string): Promise<InboxItem[]>;
+    /** 此刻还有待处理项的全部会话 id（去重）。供启动时补唤醒。 */
+    listSessionIdsWithPending(): Promise<string[]>;
+    /** 撤回：只删 `sourceUserId` 匹配的、还没被取走的那一项；返回被删项或 null。 */
+    withdraw(id: string, userId: string): Promise<InboxItem | null>;
+    /**
+     * 落一条消息。**按 id 幂等**：带 id 且已存在时返回已存在的那一行，不报错、
+     * 不返回空（撞主键静默返回空，再被当成功行用，是远离成因的 TypeError）。
+     */
+    appendMessage(message: NewConversationMessage): Promise<ConversationMessage>;
+    /**
+     * assistant 段的增量落库：`messageId` 那一行不存在就建（role assistant、
+     * `metadata = { runId, ...metadataPatch }`），存在就把 `parts` **追加**到既有
+     * parts 之后、`metadataPatch` 合并进既有 metadata。
+     */
+    appendAssistantStep(input: {
+        messageId: string;
+        runId: string;
+        sessionId: string;
+        parts: MessagePart[];
+        metadataPatch?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * 一轮收尾：`messageId` 那一行的 metadata **整体重写**为
+     * `{ runId, ...metadata }`；给了 usage 就写进 `tokenUsage`。
+     */
+    finalizeAssistantTurn(input: {
+        messageId: string;
+        runId: string;
+        metadata: Record<string, unknown>;
+        usage?: Record<string, number>;
+    }): Promise<void>;
+    /**
+     * 给一轮里所有**还没盖过终态**（`metadata.status` 为空）、`metadata.runId` 等于
+     * `runId` 的 assistant 行合并上 `{ status: 'aborted', stopReason: 'aborted' }`，
+     * 返回被改的行 id。按 metadata 里的 runId 找、按「缺 status」筛：存量数据里
+     * 一轮可能有多段（各自的 id），且对已收尾的段必须是 no-op（幂等）。
+     */
+    finalizeInterruptedTurn(runId: string): Promise<string[]>;
+    /** 一轮落过的 assistant 行 id（`metadata.runId` 等于它的，按 seq 升序）。 */
+    listTurnSegmentIds(runId: string): Promise<string[]>;
+    /**
+     * 会话的消息（按 seq 升序）。`filter` 缺省 = 全部；`role` 只要这一种，`afterSeq` 只要
+     * `seq > 它`的（子 Agent 回执按里程碑游标取「这一轮新说的话」）。
+     */
+    listMessages(sessionId: string, filter?: ListMessagesFilter): Promise<ConversationMessage[]>;
+    /**
+     * 从会话的 seq 序列上取走一个号，**不落任何行**，返回它。
+     *
+     * 子 Agent 一轮一个字都没说时，里程碑游标仍要**真的前进**（父的同步等待以它为判据），
+     * 而前进到的值必须大于此刻所有消息、又永远不等于将来的任何一条——否则那条消息会被
+     * `seq > 游标` 判成「已经回投过」而永远收不到。所以不能用 `游标 + 1`，只能从序列上
+     * 取号：取走的号不会再分配给任何行。
+     */
+    reserveSeq(sessionId: string): Promise<number>;
+}
+export interface ListMessagesFilter {
+    role?: 'user' | 'assistant';
+    afterSeq?: number | null;
+}
+//# sourceMappingURL=conversation-store.d.ts.map

package/dist/ports/conversation-store.d.ts.map

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

package/dist/ports/conversation-store.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=conversation-store.js.map

package/dist/ports/conversation-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-store.js","sourceRoot":"","sources":["../../src/ports/conversation-store.ts"],"names":[],"mappings":""}

package/dist/ports/coordination.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 跨实例协调的几个小端口：会话锁、唤醒 / 空闲广播、子 Agent 等待租约、树级名额。
+ * 搬自 agent-base `agent-core/loop/*` 与 `agent-core/subagent/{subagent-await,tree-budget}.service.ts`，
+ * 原来都直接用 Redis；这里只留语义，进程内实现见 `in-process/`，Redis 实现在
+ * `@qjp88995/agent-runtime-redis`。
+ */
+/** 会话锁的缺省 TTL：持有者崩溃后锁自然过期的上界。持有者要按更短的间隔续租。 */
+export declare const LOCK_TTL_MS = 60000;
+/**
+ * 「每会话同时至多一个 loop」的串行化原语。抢到给 token，续租 / 释放都比对 token，
+ * 不误伤「TTL 过期后被别人重新抢到」的锁。
+ */
+export interface SessionLock {
+    /** 抢锁；抢到返回 token，已被占返回 null。 */
+    acquire(sessionId: string): Promise<string | null>;
+    /** 续租；token 不再是持有者返回 false（调用方应当停止这一轮）。 */
+    renew(sessionId: string, token: string): Promise<boolean>;
+    /** 释放；token 不匹配时什么都不做。 */
+    release(sessionId: string, token: string): Promise<void>;
+    /** 只读探测此刻是否有人持锁，**不参与互斥**（判断完锁随时可能易主）。 */
+    isHeld(sessionId: string): Promise<boolean>;
+}
+/**
+ * 唤醒与空闲广播。
+ *
+ * - `wake`：「这个会话有活了」，所有实例都收到，各自去抢会话锁，只有一个跑成。
+ *   投递方（发言、子 Agent 回投、启动补唤醒）只依赖这个口，不依赖 loop 本身。
+ * - `idle`：「这个会话的一个 tick 跑完且 inbox 已空」。runtime 只广播事实，不认识消费方；
+ *   消费方要自己有兜底扫描（tick 在准备阶段就抛错的会话不会发 idle）。
+ *
+ * 投递是 at-most-once 的广播（与 Redis pub/sub 同语义）：订阅前发的收不到。
+ */
+export interface WakeChannel {
+    wake(sessionId: string): Promise<void>;
+    /** 订阅唤醒；返回取消订阅函数。 */
+    onWake(handler: (sessionId: string) => void): () => void;
+    idle(sessionId: string): Promise<void>;
+    /** 订阅空闲；返回取消订阅函数。 */
+    onIdle(handler: (sessionId: string) => void): () => void;
+}
+/** 等待租约的 TTL（秒级语义）：父每 `AWAIT_RENEW_INTERVAL_MS` 续一次。 */
+export declare const AWAIT_LEASE_TTL_MS = 60000;
+export declare const AWAIT_RENEW_INTERVAL_MS = 10000;
+/**
+ * 「父是否正在同步等这个子会话」的租约。
+ *
+ * 父放弃等待与子的收尾（finalizer）决定要不要把结果回投父 inbox，抢的是同一个原子 `claim`：
+ * 恰有一方胜出，既不会双份也不会两边都不管。父崩溃即停止续租，过期后 finalizer 自动恢复投递
+ * ——所以是租约，不是一个布尔列（父一崩就永久留成 true，是静默丢失）。
+ *
+ * 失败时的退化方向（实现要遵守）：一律退化成异步——`begin` 失败返回 false；
+ * `isAwaited` 拿不准当作没人等；`claim` 拿不准时 parent 得 true、finalizer 得 false。
+ */
+export interface SubagentAwaitLease {
+    /** 登记「父开始等这个子」。失败返回 false，调用方退回异步模式。 */
+    begin(childSessionId: string): Promise<boolean>;
+    /** 心跳续租。失败不抛。 */
+    renew(childSessionId: string): Promise<void>;
+    /** 有没有人正同步等这个子——只读，不消费租约。 */
+    isAwaited(childSessionId: string): Promise<boolean>;
+    /** 抢投递权（父与 finalizer 共用）。返回是否抢到。 */
+    claim(childSessionId: string, by: 'parent' | 'finalizer'): Promise<boolean>;
+}
+/**
+ * 树级（根会话）并发子 Agent 名额。`tryIncr` 必须是原子的「读比较写」，
+ * 否则并发派生会一起读到「未超限」而超发。
+ */
+export interface TreeBudget {
+    /** 当前值 < `limit` 则占一个名额返回 true，否则不变返回 false。 */
+    tryIncr(rootSessionId: string, limit: number): Promise<boolean>;
+    /** 释放一个名额；减到 ≤ 0 时清掉，不留负值。 */
+    decr(rootSessionId: string): Promise<void>;
+    /** 覆盖写（兜底扫描按实际存活数校正）。 */
+    set(rootSessionId: string, n: number): Promise<void>;
+}
+//# sourceMappingURL=coordination.d.ts.map

package/dist/ports/coordination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordination.d.ts","sourceRoot":"","sources":["../../src/ports/coordination.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8CAA8C;AAC9C,eAAO,MAAM,WAAW,QAAS,CAAC;AAElC;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnD,2CAA2C;IAC3C,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,0BAA0B;IAC1B,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,0CAA0C;IAC1C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7C;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,qBAAqB;IACrB,MAAM,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACzD,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,qBAAqB;IACrB,MAAM,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC1D;AAED,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,iBAAiB;IACjB,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,6BAA6B;IAC7B,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,oCAAoC;IACpC,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,8BAA8B;IAC9B,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,yBAAyB;IACzB,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD"}

package/dist/ports/coordination.js

@@ -0,0 +1,12 @@
+/**
+ * 跨实例协调的几个小端口：会话锁、唤醒 / 空闲广播、子 Agent 等待租约、树级名额。
+ * 搬自 agent-base `agent-core/loop/*` 与 `agent-core/subagent/{subagent-await,tree-budget}.service.ts`，
+ * 原来都直接用 Redis；这里只留语义，进程内实现见 `in-process/`，Redis 实现在
+ * `@qjp88995/agent-runtime-redis`。
+ */
+/** 会话锁的缺省 TTL：持有者崩溃后锁自然过期的上界。持有者要按更短的间隔续租。 */
+export const LOCK_TTL_MS = 60_000;
+/** 等待租约的 TTL（秒级语义）：父每 `AWAIT_RENEW_INTERVAL_MS` 续一次。 */
+export const AWAIT_LEASE_TTL_MS = 60_000;
+export const AWAIT_RENEW_INTERVAL_MS = 10_000;
+//# sourceMappingURL=coordination.js.map

package/dist/ports/coordination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordination.js","sourceRoot":"","sources":["../../src/ports/coordination.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8CAA8C;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC;AAoClC,wDAAwD;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC"}