@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/src/subagent/subagent-sessions.ts

@@ -0,0 +1,496 @@
+import type { MessageHub } from '../loop/message-hub.js';
+import type {
+  SubagentAwaitLease,
+  TreeBudget,
+  WakeChannel,
+} from '../ports/coordination.js';
+import {
+  type Logger,
+  type LoggerFactory,
+  silentLogger,
+} from '../ports/logger.js';
+import type { RunStore } from '../ports/run-store.js';
+import type { SessionRecord, SessionStore } from '../ports/session-store.js';
+import type { MessagePart } from '../schema/index.js';
+import type { ToolAgentContext } from '../tools/agent-tool.interface.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;
+
+/** 派一个新的子 Agent 的请求（`Delegate` 从 `ToolContext` 拼出来）。 */
+export interface SpawnRequest {
+  agentName: string;
+  /** 一句话任务标题（模型显式给，界面展示）。 */
+  title: string;
+  prompt: string;
+  /** 派它的会话（父）。 */
+  parentSessionId: string;
+  rootSessionId: string;
+  /** 父这一轮的跑次 id——子会话的 `parentRunId`，父会话经它找到。 */
+  parentRunId: string;
+  /** 父这一轮的深度。 */
+  depth: number;
+  userId: string | null;
+  /** 父这一轮跑的 agent（宿主的扩展字段：跑哪个、哪一版……）与模型能力。 */
+  agent: ToolAgentContext;
+  /** 父会话的附加信息；缺省照抄给子会话。 */
+  sessionMetadata: Readonly<Record<string, unknown>>;
+  /** 发起人此刻的权限点。缺省空（fail-closed）。 */
+  initiatorPermissions: ReadonlySet<string>;
+}
+
+/**
+ * 派不派得出（宿主回答）。
+ *
+ * - `unknown`：没有这个子 Agent（或此刻不可用）。`Delegate` 的报错让模型去核对花名册。
+ * - `refused`：有，但这一次不行——`message` 原样给模型，要说清「谁、为什么」不够格，
+ *   否则模型会换个名字再试（agent-base：权限点不够、「你自己就能看图，别派识图员」）。
+ * - `ok`：可以。`attrs` / `metadata` 写进子会话行（缺省：attrs 空、metadata 照抄父的）。
+ */
+export type SpawnCheck =
+  | {
+      ok: true;
+      attrs?: Readonly<Record<string, unknown>>;
+      metadata?: Readonly<Record<string, unknown>>;
+    }
+  | { ok: false; reason: 'unknown' }
+  | { ok: false; reason: 'refused'; message: string };
+
+/**
+ * 宿主的派生策略。花名册与这里**必须是同一个判据**（花名册不列只是不广告，模型凭名字
+ * 照样派得动）——用 `SubagentRegistry` 的话，`registrySpawnPolicy` 就是现成的一份。
+ */
+export interface SpawnPolicy {
+  checkSpawn(req: SpawnRequest): Promise<SpawnCheck>;
+  /**
+   * 子会话建好、任务投递**之前**：宿主为子会话定下它要用的东西（agent-base 分身：
+   * 派活快照）。子会话此刻还没有任务、不会被唤醒，第一轮就能读到。抛错 = 这次派生
+   * 失败（名额归还，错误上抛）。
+   *
+   * `notes` 拼在回执最前面（「技能《×××》已停用，未带」）；**为空就别给**，回执逐字不变。
+   */
+  onSubagentCreated?(
+    req: SpawnRequest & { childSessionId: string }
+  ): Promise<{ notes?: string[] }>;
+}
+
+export type SpawnOutcome =
+  | { ok: true; childSessionId: string; notes?: string[] }
+  | { ok: false; reason: 'unknown' | 'tree_full' }
+  | { ok: false; reason: 'refused'; message: string };
+
+/**
+ * 追加任务的目标校验结果。`cursorBefore` 是发起追加**之前**的里程碑游标：同步等待据它
+ * 判「这一轮跑完了没有」，取产出也只取它之后的。首次 idle 之前追加时为 null，语义退化
+ * 成「等首次 settle」。
+ */
+export type FollowUpTarget =
+  | { ok: true; cursorBefore: number | null }
+  | { ok: false; reason: 'not_found' | 'not_own_child' };
+
+/** 子会话一轮的回执（同步返回与回投 inbox 同源）。 */
+export interface SubagentResult {
+  body: string;
+  status: string;
+  /** 只有失败才带（正常收尾的 `stop` 写进「原因」是误导）。 */
+  stopReason: string | null;
+}
+
+/** loop 设置一个 tick 时要的子会话信息。 */
+export interface SubagentTickInfo {
+  kind: SessionRecord['kind'];
+  /** 子会话 = 父跑次深度 + 1；根会话 0。 */
+  depth: number;
+  parentRunId: string | null;
+  /** 子 Agent 名（钉在会话上的那个，可能是旧名）；根会话 null。 */
+  agentName: string | null;
+  title: string | null;
+}
+
+export interface SubagentSessionsDeps {
+  sessions: SessionStore;
+  /** 消息中心：投递（`post`）与读消息（`store`）。 */
+  hub: MessageHub;
+  wake: WakeChannel;
+  runs: RunStore;
+  awaitLease: SubagentAwaitLease;
+  treeBudget: TreeBudget;
+  policy: SpawnPolicy;
+  /** 每棵树同时存活的子 Agent 上限，缺省 `MAX_LIVE_SUBS_PER_TREE`。 */
+  maxLivePerTree?: number;
+  /** 兜底扫描的空闲门槛，缺省 `SUBAGENT_SWEEP_IDLE_MS`。 */
+  sweepIdleMs?: number;
+  logger?: LoggerFactory;
+}
+
+/**
+ * 子会话的生命周期：派生（受理段，**不 await 子跑完**）、追加任务、取回执、收尾回投、
+ * 兜底扫描。搬自 agent-base `SubagentSessionService`，会话行走 `SessionStore`、消息走
+ * `MessageHub`，派生判据交给宿主的 `SpawnPolicy`。
+ *
+ * 子会话此后由 loop 独立驱动（inbox + 唤醒），**同步与异步是同一条实现**：子会话都是
+ * 独立持久跑的，区别只在父等不等它（`Delegate`）。
+ *
+ * 宿主要接两处：`LoopHost.afterTick` 里调 `finalizeIfIdle`，启动时调一次 `sweepStale`。
+ */
+export class SubagentSessions {
+  private readonly logger: Logger;
+  readonly maxLivePerTree: number;
+
+  constructor(private readonly deps: SubagentSessionsDeps) {
+    this.logger = (deps.logger ?? silentLogger)('SubagentSessions');
+    this.maxLivePerTree = deps.maxLivePerTree ?? MAX_LIVE_SUBS_PER_TREE;
+  }
+
+  /** 新建：问宿主 → 占名额 → 建会话 → 宿主补料 → 投任务 → 唤醒，即返 handle。 */
+  async spawn(req: SpawnRequest): Promise<SpawnOutcome> {
+    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: {
+    childSessionId: string;
+    parentSessionId: string;
+  }): Promise<FollowUpTarget> {
+    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: {
+    childSessionId: string;
+    prompt: string;
+    userId: string | null;
+  }): Promise<void> {
+    await this.deliver(input.childSessionId, input.prompt, input.userId);
+  }
+
+  /**
+   * 子已到达 idle 终态后，取它自 `since` 以来的回执。**与收尾回投 inbox 的那份同源**
+   * （同一个取数 + 同一套中和）——换个 `run_in_background` 值就换一份结论，是没法排查
+   * 的那类 bug。追加任务传发起前的游标，否则父会连同上一轮全文再收一遍。
+   */
+  async buildResult(
+    childSessionId: string,
+    since: number | null = null
+  ): Promise<SubagentResult> {
+    const out = await this.collectOutput(childSessionId, since);
+    return this.resultOf(out);
+  }
+
+  /**
+   * 里程碑游标是否已越过 `cursor`（＝子在这次等待期间到达过一次 idle 终态）。null 即
+   * 「首次 settle 了没有」。**追加任务不能沿用「非 null 即完成」**——那个条件在追加发起的
+   * 一瞬间就成立（上一轮推进过），父会立刻拿着上一轮的结果返回。
+   */
+  async hasAdvancedPast(
+    childSessionId: string,
+    cursor: number | null
+  ): Promise<boolean> {
+    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: string): Promise<SubagentTickInfo | null> {
+    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: string): Promise<void> {
+    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(): Promise<void> {
+    const stale = await this.deps.sessions.listSubagentSessionsForSweep(
+      this.deps.sweepIdleMs ?? SUBAGENT_SWEEP_IDLE_MS
+    );
+    const touchedRoots = new Set<string>();
+    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)`
+      );
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+
+  private async deliver(
+    sessionId: string,
+    prompt: string,
+    userId: string | null
+  ): Promise<void> {
+    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（调用方从序列取号）。游标取自
+   * **取到的那些行**而不是独立取一个「当下」——后者可能跨到尚未取到的消息之后。
+   */
+  private async collectOutput(
+    childSessionId: string,
+    since: number | null
+  ): Promise<CollectedOutput> {
+    const rows = await this.deps.hub.store.listMessages(childSessionId, {
+      role: 'assistant',
+      afterSeq: since,
+    });
+    const produce = rows
+      .flatMap(r =>
+        r.parts
+          .filter(
+            (p): p is Extract<MessagePart, { type: 'text' }> =>
+              p.type === 'text'
+          )
+          .map(p => p.text)
+      )
+      .join('\n')
+      .trim();
+    // 终态取自**最后一条** assistant 行的 metadata（`TurnRecorder.close` 盖的）。
+    const lastMeta = (rows[rows.length - 1]?.metadata ?? null) as {
+      status?: string;
+      stopReason?: string | null;
+      error?: string | null;
+    } | null;
+    const watermark = rows.reduce<number | null>(
+      (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,
+    };
+  }
+
+  private resultOf(out: CollectedOutput): SubagentResult {
+    return {
+      body: buildMilestoneBody(out.produce, {
+        status: out.status,
+        stopReason: out.stopReason,
+        error: out.error,
+      }),
+      status: normalizeMilestoneStatus(out.status),
+      stopReason: out.failed ? out.stopReason : null,
+    };
+  }
+}
+
+interface CollectedOutput {
+  /** 已中和的产出正文。 */
+  produce: string;
+  status: string | undefined;
+  stopReason: string | null;
+  /** 已中和的错误原文。 */
+  error: string | null;
+  failed: boolean;
+  watermark: number | null;
+}