@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/dist/subagent/subagent-sessions.js

@@ -0,0 +1,295 @@
+import { silentLogger, } from '../ports/logger.js';
+import { DELEGATE_TOOL_NAME } from '../tools/builtin-names.js';
+import { buildMilestoneBody, isFailedTerminal, normalizeMilestoneStatus, } from './milestone-body.js';
+import { scanSubagentOutput } from './output-scan.js';
+import { MAX_LIVE_SUBS_PER_TREE } from './spawn-guards.js';
+/** 兜底扫描的缺省「空闲多久才算嫌疑」。 */
+export const SUBAGENT_SWEEP_IDLE_MS = 60_000;
+/**
+ * 子会话的生命周期：派生（受理段，**不 await 子跑完**）、追加任务、取回执、收尾回投、
+ * 兜底扫描。搬自 agent-base `SubagentSessionService`，会话行走 `SessionStore`、消息走
+ * `MessageHub`，派生判据交给宿主的 `SpawnPolicy`。
+ *
+ * 子会话此后由 loop 独立驱动（inbox + 唤醒），**同步与异步是同一条实现**：子会话都是
+ * 独立持久跑的，区别只在父等不等它（`Delegate`）。
+ *
+ * 宿主要接两处：`LoopHost.afterTick` 里调 `finalizeIfIdle`，启动时调一次 `sweepStale`。
+ */
+export class SubagentSessions {
+    deps;
+    logger;
+    maxLivePerTree;
+    constructor(deps) {
+        this.deps = deps;
+        this.logger = (deps.logger ?? silentLogger)('SubagentSessions');
+        this.maxLivePerTree = deps.maxLivePerTree ?? MAX_LIVE_SUBS_PER_TREE;
+    }
+    /** 新建：问宿主 → 占名额 → 建会话 → 宿主补料 → 投任务 → 唤醒，即返 handle。 */
+    async spawn(req) {
+        const check = await this.deps.policy.checkSpawn(req);
+        if (!check.ok)
+            return check;
+        // 先占名额，占不到不建会话（避免建了又要回滚）。
+        const took = await this.deps.treeBudget.tryIncr(req.rootSessionId, this.maxLivePerTree);
+        if (!took)
+            return { ok: false, reason: 'tree_full' };
+        try {
+            const child = await this.deps.sessions.createSubSession({
+                rootSessionId: req.rootSessionId,
+                parentRunId: req.parentRunId,
+                subagentName: req.agentName,
+                userId: req.userId,
+                title: req.title,
+                metadata: check.metadata ?? req.sessionMetadata,
+                ...(check.attrs ? { attrs: check.attrs } : {}),
+            });
+            const created = await this.deps.policy.onSubagentCreated?.({
+                ...req,
+                childSessionId: child.id,
+            });
+            await this.deliver(child.id, req.prompt, req.userId);
+            const notes = created?.notes ?? [];
+            return notes.length > 0
+                ? { ok: true, childSessionId: child.id, notes }
+                : { ok: true, childSessionId: child.id };
+        }
+        catch (err) {
+            // 建会话 / 投递失败：把刚占的名额还回去，不留泄漏。
+            await this.deps.treeBudget.decr(req.rootSessionId).catch(() => undefined);
+            throw err;
+        }
+    }
+    /**
+     * 追加任务前的目标校验——**必须先于投递**，且与投递分两步：同步等待的租约要夹在
+     * 「校验通过」与「投递」之间（见 `Delegate` 的追加任务那段）。
+     *
+     * 归属判据是「**直接子**」（子的 `parentRunId` 所属会话 == 当前会话），不是「同一棵
+     * 树」：孙辈的 handle 本就不会出现在父的上下文里，能续到孙只可能是编了个 id 或从子的
+     * 产出正文里抄了一个。
+     */
+    async resolveFollowUpTarget(input) {
+        const child = await this.deps.sessions.getSession(input.childSessionId);
+        if (!child || child.kind !== 'subagent') {
+            return { ok: false, reason: 'not_found' };
+        }
+        const owner = child.parentRunId
+            ? await this.deps.runs.getSessionId(child.parentRunId)
+            : null;
+        if (owner !== input.parentSessionId) {
+            return { ok: false, reason: 'not_own_child' };
+        }
+        return { ok: true, cursorBefore: child.lastMilestoneSeq };
+    }
+    /**
+     * 把追加任务投进子会话并唤醒它。与派生尾段**逐字相同**的通道，子那边零特判——「子
+     * 记得自己写过什么」不是这里做的，是会话本身没被丢弃。子此刻仍在跑就是软插话。
+     *
+     * **不占名额**：名额记的是「同时有几个**新派生**的子」，与「存活 = 游标为 null」同一个口径。
+     */
+    async deliverFollowUp(input) {
+        await this.deliver(input.childSessionId, input.prompt, input.userId);
+    }
+    /**
+     * 子已到达 idle 终态后，取它自 `since` 以来的回执。**与收尾回投 inbox 的那份同源**
+     * （同一个取数 + 同一套中和）——换个 `run_in_background` 值就换一份结论，是没法排查
+     * 的那类 bug。追加任务传发起前的游标，否则父会连同上一轮全文再收一遍。
+     */
+    async buildResult(childSessionId, since = null) {
+        const out = await this.collectOutput(childSessionId, since);
+        return this.resultOf(out);
+    }
+    /**
+     * 里程碑游标是否已越过 `cursor`（＝子在这次等待期间到达过一次 idle 终态）。null 即
+     * 「首次 settle 了没有」。**追加任务不能沿用「非 null 即完成」**——那个条件在追加发起的
+     * 一瞬间就成立（上一轮推进过），父会立刻拿着上一轮的结果返回。
+     */
+    async hasAdvancedPast(childSessionId, cursor) {
+        const child = await this.deps.sessions.getSession(childSessionId);
+        const now = child?.lastMilestoneSeq ?? null;
+        if (now === null)
+            return false;
+        return cursor === null || now > cursor;
+    }
+    /** loop 设置 tick 时要的子会话信息（深度、钉住的子 Agent 名……）。会话不存在返回 null。 */
+    async tickInfo(sessionId) {
+        const session = await this.deps.sessions.getSession(sessionId);
+        if (!session)
+            return null;
+        if (session.kind !== 'subagent') {
+            return {
+                kind: session.kind,
+                depth: 0,
+                parentRunId: null,
+                agentName: null,
+                title: session.title,
+            };
+        }
+        const depth = session.parentRunId
+            ? (await this.deps.runs.getDepth(session.parentRunId)) + 1
+            : 0;
+        return {
+            kind: 'subagent',
+            depth,
+            parentRunId: session.parentRunId,
+            agentName: session.subagentName,
+            title: session.title,
+        };
+    }
+    /**
+     * 子会话空转终态 → 把新产出中和后作为里程碑回投父 inbox 并唤醒父。
+     *
+     * loop 在每个 tick 收尾（锁已释放、re-wake 之前）对每个会话**无条件**调（`LoopHost.afterTick`），
+     * 这里自查：非子会话直接返回。
+     *
+     * **只还一次名额**：「存活」= 从派生到首次 idle 终态，判据是游标为 null。被追加任务
+     * 续跑后再次 idle 只回投新产出、不再还。
+     *
+     * **并发安全**：两次抢锁成功的唤醒可能并发进来、读到同一个旧游标。所有副作用都收在一次
+     * 乐观 CAS（`SessionStore.advanceMilestone`）之后：先按**旧**游标取产出，再把游标推进到
+     * 产出的最大 seq（无产出从序列取号）；只有 CAS 成功的那一个回投 + 唤醒 + 还名额。
+     *
+     * 全程不抛：失败只记日志，兜底扫描是后备。
+     */
+    async finalizeIfIdle(childSessionId) {
+        try {
+            const child = await this.deps.sessions.getSession(childSessionId);
+            if (!child || child.kind !== 'subagent')
+                return;
+            // 有待处理的消息 → 软插话进来了，子会被重新唤醒续跑，不回投、不还名额。
+            if (await this.deps.hub.hasPending(childSessionId))
+                return;
+            const parentSessionId = child.parentRunId
+                ? await this.deps.runs.getSessionId(child.parentRunId)
+                : null;
+            if (!parentSessionId) {
+                this.logger.warn(`finalizeIfIdle(${childSessionId}): cannot locate parent session ` +
+                    `(parentRunId=${child.parentRunId ?? 'null'}) — skipped`);
+                return;
+            }
+            // 按**旧**游标取产出——CAS 前不得推进游标。
+            const oldCursor = child.lastMilestoneSeq;
+            const out = await this.collectOutput(childSessionId, oldCursor);
+            // 无新产出且非首次 → 已还过名额、也无可投，直接返回。两种情况要突破：
+            // 1. 失败态即便无新文本也必须把「子挂了」上报给父。
+            // 2. 有父正同步等着这次续跑：父的判据就是游标，这里一返回游标就停在原地，父只能
+            //    空等到超时——而子其实跑完了，只是一个字都没说。
+            if (!out.produce &&
+                !out.failed &&
+                oldCursor !== null &&
+                !(await this.deps.awaitLease.isAwaited(childSessionId))) {
+                return;
+            }
+            const watermark = out.watermark ?? (await this.deps.hub.store.reserveSeq(childSessionId));
+            const claimed = await this.deps.sessions.advanceMilestone(childSessionId, oldCursor, watermark);
+            if (!claimed)
+                return;
+            // 父正同步等着 → 产物由它自己取，这里**不投 inbox**（否则父既同步拿到、下一轮又收到
+            // 一条重复回执）。必须在 CAS **之后**：父的判据正是游标，先 claim 再 CAS 的话父可能
+            // 在完成信号落库之前就被判成「已接管」。
+            const awaitedByParent = await this.deps.awaitLease.claim(childSessionId, 'finalizer');
+            if (!awaitedByParent) {
+                const result = this.resultOf(out);
+                await this.deps.hub.post({
+                    sessionId: parentSessionId,
+                    kind: 'tool_result',
+                    sourceKind: 'tool',
+                    sourceUserId: null,
+                    // 围栏由 `MessageHub.take` 取出时包：落库的是数据，围栏是给模型的呈现层。
+                    source: {
+                        // 标的是「这是一份子 Agent 回执」这个**类别**，不是触发它的工具——
+                        // 追加任务的回执也写这个名字，收尾只看会话状态，本就不知道是谁发起的。
+                        toolName: DELEGATE_TOOL_NAME,
+                        handle: childSessionId,
+                        status: result.status,
+                        stopReason: result.stopReason,
+                        // 与 stopReason 分开带：那是协议码，这是人话。只有失败才带（已中和）。
+                        error: out.failed ? out.error : null,
+                    },
+                    parts: [{ type: 'text', text: result.body }],
+                });
+                await this.deps.wake.wake(parentSessionId);
+            }
+            if (oldCursor === null) {
+                await this.deps.treeBudget.decr(child.rootSessionId);
+            }
+        }
+        catch (err) {
+            this.logger.error(`finalizeIfIdle(${childSessionId}) failed: ${String(err)}`);
+        }
+    }
+    /**
+     * 兜底：子 loop 可能在回投 / 还名额之前崩掉或丢锁。对每个嫌疑重跑一次收尾（幂等），
+     * 再把每棵被碰过的树的名额覆盖为真值。**先收尾后校正**：收尾会把游标从 null 推成非
+     * null，校正读到的才是收尾之后的存活数。宿主在启动时调一次（fire-and-forget）。
+     */
+    async sweepStale() {
+        const stale = await this.deps.sessions.listSubagentSessionsForSweep(this.deps.sweepIdleMs ?? SUBAGENT_SWEEP_IDLE_MS);
+        const touchedRoots = new Set();
+        for (const session of stale) {
+            touchedRoots.add(session.rootSessionId);
+            await this.finalizeIfIdle(session.id);
+        }
+        const counts = await this.deps.sessions.countAliveSubsByRoot();
+        const countByRoot = new Map(counts.map(r => [r.rootSessionId, r.count]));
+        for (const rootId of touchedRoots) {
+            await this.deps.treeBudget.set(rootId, countByRoot.get(rootId) ?? 0);
+        }
+        if (stale.length > 0) {
+            this.logger.warn(`sweepStale: finalized ${stale.length} stale session(s), corrected ${touchedRoots.size} tree(s)`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    async deliver(sessionId, prompt, userId) {
+        await this.deps.hub.post({
+            sessionId,
+            kind: 'user_message',
+            sourceKind: 'user',
+            sourceUserId: userId,
+            parts: [{ type: 'text', text: prompt }],
+        });
+        await this.deps.wake.wake(sessionId);
+    }
+    /**
+     * 子会话自 `since` 以来的 assistant 产出与终态。游标是消息 `seq`（会话内单调）——
+     * **不是时间戳**：挂钟会回拨，回拨之后新产出会被判成「旧的」直接跳过，父收到的回执
+     * 格式完好、内容缺一段。
+     *
+     * `watermark` = 取到的行里最大的 seq；没取到行时为 null（调用方从序列取号）。游标取自
+     * **取到的那些行**而不是独立取一个「当下」——后者可能跨到尚未取到的消息之后。
+     */
+    async collectOutput(childSessionId, since) {
+        const rows = await this.deps.hub.store.listMessages(childSessionId, {
+            role: 'assistant',
+            afterSeq: since,
+        });
+        const produce = rows
+            .flatMap(r => r.parts
+            .filter((p) => p.type === 'text')
+            .map(p => p.text))
+            .join('\n')
+            .trim();
+        // 终态取自**最后一条** assistant 行的 metadata（`TurnRecorder.close` 盖的）。
+        const lastMeta = (rows[rows.length - 1]?.metadata ?? null);
+        const watermark = rows.reduce((max, r) => (max === null || r.seq > max ? r.seq : max), null);
+        return {
+            produce: produce ? scanSubagentOutput(produce).text : '',
+            status: lastMeta?.status,
+            stopReason: lastMeta?.stopReason ?? null,
+            error: lastMeta?.error ? scanSubagentOutput(lastMeta.error).text : null,
+            failed: isFailedTerminal(lastMeta?.status),
+            watermark,
+        };
+    }
+    resultOf(out) {
+        return {
+            body: buildMilestoneBody(out.produce, {
+                status: out.status,
+                stopReason: out.stopReason,
+                error: out.error,
+            }),
+            status: normalizeMilestoneStatus(out.status),
+            stopReason: out.failed ? out.stopReason : null,
+        };
+    }
+}
+//# sourceMappingURL=subagent-sessions.js.map

package/dist/subagent/subagent-sessions.js.map

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

package/dist/testing/contracts.d.ts

@@ -0,0 +1,37 @@
+import type { SessionLock, SubagentAwaitLease, TreeBudget, WakeChannel } from '../ports/coordination.js';
+import { type QuestionStore } from '../ports/question-store.js';
+import type { RunStore } from '../ports/run-store.js';
+import type { SessionStore } from '../ports/session-store.js';
+import type { StreamBus } from '../ports/stream-bus.js';
+import type { VendorFileCache } from '../ports/vendor-file-cache.js';
+/**
+ * 端口的契约用例：进程内实现与各适配包（Redis 等）跑同一套，保证换实现不换语义。
+ * 每个用例用随机 id，适配器实现可以共用一个后端实例。
+ *
+ * 用法：`describeStreamBusContract('redis', () => makeBus())`。
+ * 工厂可以返回 `{ impl, cleanup }`，cleanup 在用例结束时调用。
+ */
+type Factory<T> = () => T | {
+    impl: T;
+    cleanup?: () => void | Promise<void>;
+} | Promise<T | {
+    impl: T;
+    cleanup?: () => void | Promise<void>;
+}>;
+export declare function describeStreamBusContract(name: string, factory: Factory<StreamBus>): void;
+export declare function describeSessionLockContract(name: string, factory: Factory<SessionLock>): void;
+export declare function describeWakeChannelContract(name: string, factory: Factory<WakeChannel>): void;
+export declare function describeSubagentAwaitLeaseContract(name: string, factory: Factory<SubagentAwaitLease>): void;
+export declare function describeTreeBudgetContract(name: string, factory: Factory<TreeBudget>): void;
+export declare function describeRunStoreContract(name: string, factory: Factory<RunStore>, 
+/** 建一条能被 `findStaleRunning(0)` 看到的旧跑次所需的等待（毫秒），缺省 5。 */
+staleDelayMs?: number): void;
+/**
+ * `SessionStore` 契约（子会话行与里程碑游标）。`listSubagentSessionsForSweep` 要看消息与
+ * 更新时间，跟宿主的消息表绑在一起，不在这里测。
+ */
+export declare function describeSessionStoreContract(name: string, factory: Factory<SessionStore>): void;
+export declare function describeQuestionStoreContract(name: string, factory: Factory<QuestionStore>): void;
+export declare function describeVendorFileCacheContract(name: string, factory: Factory<VendorFileCache>): void;
+export {};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/testing/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/testing/contracts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,WAAW,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AAGvC;;;;;;GAMG;AACH,KAAK,OAAO,CAAC,CAAC,IAAI,MACd,CAAC,GACD;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,GACjD,OAAO,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAAC;AAwDnE,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,QAqI5B;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,QA2C9B;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,QAuC9B;AAED,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,kBAAkB,CAAC,QAiCrC;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,QA0C7B;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;AAC1B,wDAAwD;AACxD,YAAY,SAAI,QA+EjB;AAWD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,QA6E/B;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,QAwLhC;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,QAiHlC"}