@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/execution/subprocess-agent-runner.ts

@@ -1,303 +0,0 @@
-// src/execution/subprocess-agent-runner.ts
-//
-// Wave 4: SubprocessAgentRunner 委托重写
-//
-// 从"自己 spawn pi"改为"委托 SubagentService.executeAndAwait"。
-// MF-3: 从 orchestration/infra 迁入 execution，同层委托 SubagentService。
-//
-// 接线层级：
-//   [跨模块 port] implements AgentRunner（orchestration/models/ports.ts）
-//   [模块内直调] mapToExecuteOptions + mergeTimeoutSignal（execute-options-mapper）
-//   [P4 路由层]  engine/routing.ts routeEngine（三层优先级 + probe + fallback 三守卫，D9）
-//   [引擎层]     EnginePort.run（pi = 本地 DI 绑定实例；非 pi = registry.getEngine 动态获取）
-//   [模块内直调] this.subagentService.executeAndAwait（PiEngine 内部委托目标）
-//
-// 设计基线：
-//   D-A2（映射归 adapter）/ D-A8（onEvent 桥接）/ D-A9（timeoutMs 合并 signal）/
-//   D-008（model 填底，不调 resolveModel）/ BC-9（timeoutMs 行为）/ BC-10（live-record 进度）
-
-import type { AgentRunner } from "../orchestration/models/ports.ts";
-import type { AgentCallOpts, AgentResult } from "../orchestration/models/types.ts";
-import type { AgentEvent } from "../shared/agent-event.ts";
-import { getEngineDataDir } from "./engine/common/data-dir.ts";
-import { JournalWriter } from "./engine/common/event-journal.ts";
-import { createPiEngine, PI_POOL_KEY } from "./engine/engines/pi/registration.ts";
-import { executeOptionsToTaskSpec } from "./engine/engines/pi/task-spec-mapper.ts";
-import { resolveJournalPath } from "./engine/paths.ts";
-import type { EnginePort, RunContext } from "./engine/port.ts";
-import { routeEngine, resolveEngineRouting, type EngineRouteResult, type EngineRoutingInput } from "./engine/routing.ts";
-import { getEngine, hasEngine, listEngines } from "./engine/registry.ts";
-import type { AgentOutcome, EngineHandle } from "./engine/types.ts";
-import { mapToExecuteOptions, mergeTimeoutSignal } from "./execute-options-mapper.ts";
-import { getModelConfigService } from "./model-config-service.ts";
-import type { ModelInfo } from "./model-resolver.ts";
-import { registerSpawnedChildForRecord } from "./session-runner.ts";
-import type { SubagentStream } from "./stream-sink.ts";
-import type { SubagentService } from "./subagent-service.ts";
-import type { ExecuteOptions } from "./types.ts";
-
-// ── 构造依赖（per-session 注入）──
-
-/**
- * SAR 构造参数。
- *
- * per-session（makeDeps 时创建，随 session 销毁）：
- *   - subagentService: 进程单例（getSubagentService()），委托目标
- *   - ctxModel: 当前 session 主 agent 模型（D-008 model 填底，opts.model 空时用此）
- *
- * resolveAgentOpts 在 orchestration 层完成（M2 修正后单参数，只处理 schema SO 指令 + skill），
- * 结果填进 AgentCallOpts.skillPath/schemaEnv/appendSystemPrompt，SAR 收已解析的 opts。
- * 不含 agent/session 目录/临时文件集合依赖（agent ref 交 resolveIdentity，无临时文件）。
- */
-export interface SubprocessAgentRunnerDeps {
-  subagentService: SubagentService;
-  ctxModel?: ModelInfo;
-}
-
-/**
- * AgentRunner port 实现——委托 SubagentService.executeAndAwait。
- *
- * 层归属：execution（MF-3 从 orchestration 迁入）。implements orchestration 层 port。
- *
- * 行为契约（BC-1/BC-2/BC-9/BC-10）：
- *   - opts 形状不变（AgentCallOpts，含 resolveAgentOpts 填的 skillPath/schemaEnv）
- *   - result 形状不变（workflow AgentResult: content/parsedOutput/usage/error/toolCalls）
- *   - 不 reject——失败信息入 result.error（与 executeAgentCall 契约一致）
- *   - timeoutMs 合并 signal（D-A9）；onEvent 桥接 AgentEvent→workflow liveRecord（D-A8）
- *
- * [P1 引擎接线] 执行经 EnginePort。pi 引擎绑定本 SAR 的服务引用（per-session DI——
- * 单测注入 mock 时全局单例不可见；生产环境两者是同一进程单例对象），行为零变化；
- * 非 pi 引擎（P4 路由可达：frontmatter/调用参数/全局默认指定）经 registry.getEngine
- * 动态获取——「引擎身份」的归属边界在注册表，SAR 不感知具体引擎实现。
- *
- * [P4 配置路由] 每次运行经 engine/routing.ts 解析三层优先级（调用参数 opts.engine >
- * agent frontmatter engine > 全局默认 'pi'）+ probe + fallback 三守卫（D9）。路由失败
- * （engine_not_found / engine_probe_failed / model_not_available）不 reject，入
- * result.error——与 executeAgentCall 契约一致。
- */
-export class SubprocessAgentRunner implements AgentRunner {
-  private readonly subagentService: SubagentService;
-  private ctxModel: ModelInfo | undefined;
-  /** pi 引擎（per-session DI 绑定，缺省执行路径——见类注释）。 */
-  private readonly piEngine: EnginePort;
-
-  constructor(deps: SubprocessAgentRunnerDeps) {
-    this.subagentService = deps.subagentService;
-    this.ctxModel = deps.ctxModel;
-    this.piEngine = createPiEngine(() => this.subagentService);
-  }
-
-  /**
-   * 刷新主 agent model 缓存。model_select 事件时由 index.ts 调用。
-   * H1 修复：旧实现 ctxModel 是 readonly，session_start 后固化，
-   * model_select 只刷新 ModelConfigService._ctxModel 不更新 SAR →
-   * workflow 路径用过期模型。
-   */
-  updateCtxModel(model: ModelInfo | undefined): void {
-    this.ctxModel = model;
-  }
-
-  /**
-   * 执行单次 agent 调用：路由（P4）→ EnginePort.run → PiEngine 委托
-   * SubagentService.executeAndAwait。
-   *
-   * 接线链路：
-   *   routeEngine（三层 + probe + 守卫）→ mergeTimeoutSignal → mapToExecuteOptions →
-   *   AgentTaskSpec → engine.run（PiEngine：spec → ExecuteOptions 还原 + engine 留痕）→
-   *   executeAndAwait → AgentOutcome → AgentResult
-   *
-   * 错误处理：不 reject。
-   *   - 路由失败（未注册 id / probe 失败 + 守卫或 strict）→ AgentResult.error（错误码前缀）
-   *   - executeAndAwait 内部失败 → 返回 AgentResult(success:false) → 已映射 error 字段
-   *   - executeAndAwait throw（嵌套超限 BC-12）→ catch → AgentResult.error
-   *   - spawn 级失败已由 runSpawn 内部收口为 failed AgentResult（不逃逸）
-   */
-  async run(
-    opts: AgentCallOpts,
-    signal: AbortSignal,
-    onEvent?: (event: AgentEvent) => void,
-    stream?: SubagentStream,
-  ): Promise<AgentResult> {
-    const startedAt = Date.now();
-
-    // ── P4 路由：三层优先级 + probe + fallback 三守卫（D9①/D7）──
-    // 路由在最前——引擎身份决定 journal 路径与后续一切执行面；失败（未注册 id /
-    // probe 失败 + strict/守卫）按「不 reject」契约转 result.error。
-    // pi 快路径同步短路（不经 routeEngine 的 await）：pi 恒免探、无 fallback 可言、
-    // engineFor('pi') 本地 DI 绑定恒可用——不引入微任务边界，缺省路径时序与 P1 接线
-    // 前完全一致（下游依赖「run 内首个 await 前已触达 executeAndAwait」的时序契约）。
-    let routingInput: EngineRoutingInput;
-    let route: EngineRouteResult;
-    try {
-      routingInput = this.buildRoutingInput(opts);
-      const routing = resolveEngineRouting(routingInput);
-      if (routing.engineId === "pi") {
-        route = {
-          engine: this.piEngine,
-          engineId: "pi",
-          requestedEngineId: "pi",
-          source: routing.source,
-        };
-      } else {
-        route = await routeEngine({
-          routing: routingInput,
-          taskModel: opts.model,
-          strict: getModelConfigService()?.getGlobalConfig().engineRouting?.strict === true,
-          probe: (engineId) => this.engineFor(engineId).probe(),
-          getEngineFn: (engineId) => this.engineFor(engineId),
-          // pi 经本地 DI 绑定恒可用（不依赖 registry 全局注册态——SAR 持有服务引用），
-          // has/list 注入同一口径，engine_not_found 文案不会把本地 pi 漏报成未注册
-          hasEngineFn: (engineId) => engineId === "pi" || hasEngine(engineId),
-          listEnginesFn: () => (hasEngine("pi") ? listEngines() : ["pi", ...listEngines()]),
-        });
-      }
-    } catch (err) {
-      // buildRoutingInput 的 agent 解析期校验（未注册 frontmatter engine）与路由失败
-      // （probe + strict/守卫）一并在此收口——「不 reject」契约
-      return errorResult(err, startedAt);
-    }
-
-    // ── P2 event journal 接线（设计 D6 第②级；对齐点③：路径权威 = 引擎池 key）──
-    // host 在 onEvent 回调内统一落盘（全引擎免费获得②级数据源）。初始 poolKey 用 pi
-    // 缺省占位（pi 恒 'shared'）；非池化稳定引擎（zcode）在 prepare 期经
-    // RunContext.onPoolResolved 声明实际池 key → writer.retarget——保证 journal 落盘
-    // 路径与 handle.poolKey 同源（handle.journalPath 由本方法 run 返回后回填）。
-    //
-    // taskId 为宿主侧任务标识（journal 文件名与池引用计数 key）——executeAndAwait
-    // 不外露内部 record id（取真实 id 需 hook record store 且改 createRecordForMode
-    // 签名，影响面大；P4 决策：保留占位，`sa-` 前缀与 record id 同构。影响面：record
-    // GC 时无法按 taskId 联动删 journal（journal 依赖 30 天 TTL 自然回收），read ②级
-    // 经 handle.journalPath 自描述定位不受影响）。
-    const taskId = `sa-${crypto.randomUUID()}`;
-    const journal = new JournalWriter({
-      path: resolveJournalPath(getEngineDataDir(), route.engineId, PI_POOL_KEY, taskId),
-      taskId,
-      engineId: route.engineId,
-    });
-    const retargetJournal = (poolKey: string): void => {
-      journal.retarget(resolveJournalPath(getEngineDataDir(), route.engineId, poolKey, taskId));
-    };
-    // 包装：先写 journal 再转发原 onEvent（原 onEvent 未传时也恒传包装版——
-    // 下游 onEvent 通道是事件生成后的纯转发，无行为分支，仅多一次入队）
-    const journalingOnEvent = (event: AgentEvent): void => {
-      journal.append(event);
-      onEvent?.(event);
-    };
-
-    try {
-      // ── D-A9: timeoutMs 合并 signal（超时 abort 带 HOST_TIMEOUT_ABORT_REASON 标记）──
-      const mergedSignal = mergeTimeoutSignal(signal, opts.timeoutMs);
-
-      // ── D-A2 + D-008: AgentCallOpts → ExecuteOptions 映射 ──
-      const mappedOpts: ExecuteOptions = mapToExecuteOptions(opts, this.ctxModel);
-
-      // ── P1/P4 引擎接线：EnginePort.run ──
-      const runCtx: RunContext = {
-        taskId,
-        poolKey: PI_POOL_KEY,
-        signal: mergedSignal,
-        onEvent: journalingOnEvent,
-        ctxModel: this.ctxModel,
-        ...(route.engineFallback !== undefined ? { engineFallback: route.engineFallback } : {}),
-        onPoolResolved: retargetJournal,
-        // [U0 D10] 终止链路径①：引擎 spawn 的子进程注册进 session-runner 的
-        // spawnedChildren 记账（dispose killAll 收割兜底对 workflow 域引擎任务生效）；
-        // taskId（'sa-' 前缀）即记账 key，与 chat 域 kickOffEngineRun 的 record.id 同构
-        onChildSpawned: (child) => registerSpawnedChildForRecord(taskId, child),
-        ...(stream !== undefined ? { stream } : {}),
-        // 解耦形态（有 schemaEnv 无 schema）的兜底通道——耦合形态下引擎从 task.schema
-        // 派生等值，此值被忽略（见 RunContext.schemaEnv 注释）
-        ...(mappedOpts.schemaEnv !== undefined ? { schemaEnv: mappedOpts.schemaEnv } : {}),
-      };
-      const { handle, outcome } = await route.engine.run(
-        // 泛化为中立声明（PiEngine 内部再还原回 ExecuteOptions——往返保真，
-        // 由 engines/pi/__tests__/task-spec-mapper.test.ts 逐字段锁定）
-        executeOptionsToTaskSpec(mappedOpts),
-        runCtx,
-      );
-      // handle.journalPath 回填（§3.3.6：read ②级的自描述定位符——运行期落盘路径
-      // 权威在 writer，handle 记录最终路径供跨重启 read 消费）
-      backfillJournalPath(handle, journal.path);
-      return outcomeToRunnerResult(outcome);
-    } catch (err) {
-      // executeAndAwait throw（嵌套超限 ForkDepthExceededError，BC-12）或未预期异常 → 不 reject，入 error。
-      const message = err instanceof Error ? err.message : String(err);
-      return {
-        content: "",
-        durationMs: Date.now() - startedAt,
-        error: message,
-        toolCalls: [],
-      };
-    } finally {
-      // run 终态后 flush + fsync 一次（§3.3.6 写入纪律）；写失败已由 writer 内部
-      // warn + failed 收口，close 不抛（journal 是②级尽力而为数据源）
-      await journal.close();
-    }
-  }
-
-  // ── 内部 ──
-
-  /**
-   * 引擎获取：pi 走 per-session DI 绑定（mock 语义 + 生产同单例，P1 行为零变化）；
-   * 非 pi 经 registry.getEngine 动态获取（P4：引擎身份归属注册表，未注册 id 抛
-   * EngineNotFoundError——路由期已前置校验，这里是防御性兜底）。
-   */
-  private engineFor(engineId: string): EnginePort {
-    if (engineId === "pi") return this.piEngine;
-    return getEngine(engineId);
-  }
-
-  /**
-   * 三层路由输入装配（D9）：调用参数（opts.engine，workflow step 级透传）> agent
-   * frontmatter（ModelConfigService.getAgentConfig——loadByPath mtime 缓存，幂等）>
-   * 全局默认（config.json defaultEngine）。单例未就绪（session_start 前/测试 mock）
-   * 时各层缺省——落内置 'pi'。
-   */
-  private buildRoutingInput(opts: AgentCallOpts): EngineRoutingInput {
-    const service = getModelConfigService();
-    const agentEngine =
-      opts.agent !== undefined && opts.agent !== "" ? service?.getAgentConfig(opts.agent)?.engine : undefined;
-    const globalDefault = service?.getGlobalConfig().defaultEngine;
-    return {
-      ...(opts.engine !== undefined && opts.engine !== "" ? { callEngine: opts.engine } : {}),
-      ...(agentEngine !== undefined && agentEngine !== "" ? { agentEngine } : {}),
-      ...(globalDefault !== undefined && globalDefault !== "" ? { globalDefaultEngine: globalDefault } : {}),
-    };
-  }
-}
-
-/** 路由期错误 → AgentResult.error（错误码前缀格式保留——engine_not_found 等）。 */
-function errorResult(err: unknown, startedAt: number): AgentResult {
-  return {
-    content: "",
-    durationMs: Date.now() - startedAt,
-    error: err instanceof Error ? err.message : String(err),
-    toolCalls: [],
-  };
-}
-
-/** handle.journalPath 回填（一次写者：SAR 是 handle 的首个消费者）。 */
-function backfillJournalPath(handle: EngineHandle, journalPath: string): void {
-  handle.data.journalPath = journalPath;
-}
-
-/**
- * AgentOutcome → workflow AgentResult：剥离引擎层新增字段（engineId/engineFallback/
- * exitCode——engineFallback 经 record（pi 路径）/outcome（zcode 路径）留痕，GUI 投影
- * 通道在后续 wave 接线，workflow 引擎不消费）。其余字段由 PiEngine 从 executeAndAwait
- * 的返回值逐字段映射而来，字段全集完整性由 pi-engine 单测锁定（缺字段会在该处转红，
- * 不会静默丢失）。
- */
-function outcomeToRunnerResult(outcome: AgentOutcome): AgentResult {
-  return {
-    content: outcome.content,
-    parsedOutput: outcome.parsedOutput,
-    usage: outcome.usage,
-    durationMs: outcome.durationMs,
-    error: outcome.error,
-    sessionId: outcome.sessionId,
-    sessionFile: outcome.sessionFile,
-    worktreePath: outcome.worktreePath,
-    toolCalls: outcome.toolCalls,
-  };
-}

package/src/execution/temp-prompt.ts

@@ -1,62 +0,0 @@
-// src/core/temp-prompt.ts
-//
-// 将 agent systemPrompt 写入临时文件，供 pi CLI --append-system-prompt 使用。
-// Core 叶子原语（node 内置 + 同目录 bestEffort 清理 helper）。注意 bestEffort
-// 经 extension-logger 有到 pi 的传递依赖（仅日志通路，无 pi 运行时调用）。
-//
-// pi CLI 的 --append-system-prompt 接受文件路径（非内联字符串），故 spawn 前
-// 需把 systemPrompt 落盘。每次调用创建唯一临时目录，用完由 runSpawn 清理。
-//
-// 移植自 nicobailon subagent example，去掉 withFileMutationQueue（目录已唯一，
-// 无并发写入风险，queue 冗余）。
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { bestEffort } from "./best-effort.ts";
-
-/** 临时 prompt 文件创建结果。dir 供调用方清理。 */
-export interface TempPromptFile {
-  /** 临时目录绝对路径（mkdtemp 创建，调用方负责删除）。 */
-  dir: string;
-  /** prompt 文件绝对路径（dir 下）。 */
-  filePath: string;
-}
-
-/**
- * 将 systemPrompt 写入临时文件。
- *
- * @param agentName agent 名称（用于文件名，非法字符替换为 _）
- * @param prompt systemPrompt 全文
- * @returns 临时文件信息（dir + filePath）
- *
- * 安全：文件权限 0o600（仅 owner 读写），防止其他用户读取 prompt 内容。
- * 目录用 mkdtemp 保证唯一，无需额外锁。
- */
-export async function writePromptToTempFile(
-  agentName: string,
-  prompt: string,
-): Promise<TempPromptFile> {
-  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
-  const safeName = agentName.replace(/[^\w.-]+/g, "_");
-  const filePath = path.join(dir, `prompt-${safeName}.md`);
-  await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
-  return { dir, filePath };
-}
-
-/**
- * 删除临时 prompt 目录（含文件）。best-effort，失败不抛。
- *
- * runSpawn 的 finally 调用，确保临时文件不泄漏。子进程可能仍持有文件句柄
- * （--append-system-prompt 读取后即释放），rm 用 recursive 容错。
- */
-export async function cleanupTempPrompt(file: TempPromptFile): Promise<void> {
-  try {
-    await fs.promises.rm(file.dir, { recursive: true, force: true });
-  } catch (err) {
-    // best-effort：临时文件泄漏不影响功能，OS tmpdir 清理机制兜底；失败经
-    // bestEffort 记 debug 日志（对齐 idle-gc / finalize-record 的清理惯例）
-    bestEffort(err, `cleanup temp prompt dir ${file.dir}`);
-  }
-}

package/src/execution/tombstone-store.ts

@@ -1,72 +0,0 @@
-// src/runtime/execution/tombstone-store.ts
-//
-// Cancelled 状态的 sidecar 持久化。
-//
-// 背景：用户 cancel background subagent 时 session.abort() → prompt() reject →
-// session.jsonl 被中途截断（无最终 assistant message，无 stopReason 标记）。所以
-// cancelled 状态无法从 session.jsonl 可靠检测。本模块在 session.jsonl 旁写一个
-// `.cancelled` sidecar 文件（单行 JSON），collectRecords 重建时读它 override status。
-//
-// 设计：单条 cancelled = 单 sidecar，无全局 index 可损坏，无并发问题，被现有
-// session-file-gc 的目录扫描自然清理（GC 已扩展为也清理 .cancelled）。YAGNI 更重方案。
-
-import * as fs from "node:fs";
-
-// ============================================================
-// 类型
-// ============================================================
-
-/** Tombstone 内容（单行 JSON）。 */
-export interface CancelledTombstone {
-  id: string;
-  status: "cancelled";
-  agent: string;
-  startedAt: number;
-  endedAt: number;
-}
-
-// ============================================================
-// 公开函数
-// ============================================================
-
-/**
- * 在 session.jsonl 旁写 cancelled tombstone。
- * best-effort：任何 I/O 错误静默（cancel 已成功，持久化是次要的——内存 record 即将被
- * archive 淘汰，下次读靠 tombstone 标记 cancelled）。
- */
-export function writeCancelledTombstone(sessionFile: string, meta: CancelledTombstone): void {
-  try {
-    const tombstonePath = `${sessionFile}.cancelled`;
-    fs.writeFileSync(tombstonePath, `${JSON.stringify(meta)}\n`, "utf-8");
-  } catch (_e) {
-    void _e; // 静默：写失败不阻断 cancel 主流程（status 已在内存 record 上设好）。
-  }
-}
-
-/**
- * 读 session.jsonl 旁的 cancelled tombstone。
- * 返回 undefined：sidecar 不存在 / 损坏 / 解析失败。
- */
-export function readCancelledTombstone(sessionFile: string): CancelledTombstone | undefined {
-  let raw: string;
-  try {
-    raw = fs.readFileSync(`${sessionFile}.cancelled`, "utf-8");
-  } catch {
-    return undefined; // sidecar 不存在（正常——非 cancelled record 无 sidecar）。
-  }
-  try {
-    const parsed = JSON.parse(raw) as Partial<CancelledTombstone>;
-    if (
-      typeof parsed.id === "string" &&
-      parsed.status === "cancelled" &&
-      typeof parsed.agent === "string" &&
-      typeof parsed.startedAt === "number" &&
-      typeof parsed.endedAt === "number"
-    ) {
-      return parsed as CancelledTombstone;
-    }
-    return undefined; // 结构不合法 → 降级。
-  } catch {
-    return undefined; // JSON 损坏 → 降级。
-  }
-}

package/src/execution/turn-limiter.ts

@@ -1,102 +0,0 @@
-// src/core/turn-limiter.ts
-//
-// soft/hard turn 限制器。maxTurns 到达 → steer 提醒收尾；
-// graceTurns 后仍不结束 → abort。
-
-/** steer 提醒消息：要求 agent 总结已完成/未完成/下一步，不得谎报完成。 */
-const WRAP_UP_MESSAGE = [
-  "You have reached your turn limit. Wrap up now:",
-  "1. Summarize what you have completed (with evidence: file paths, command output).",
-  "2. List what remains undone and why.",
-  "3. State the single most important next step for whoever continues.",
-  "Do NOT claim the task is complete if any part remains unfinished.",
-].join(" ");
-
-/**
- * 预防性 wrap-up 提示（启动时注入 --append-system-prompt）。
- *
- * spawn 模式下 runSpawn 无法在达 maxTurns 时运行时注入 steer（pi `--mode json` 是
- * single-shot，无 stdin 命令通道；见 session-runner.ts limiter 注释）。作为短期补偿，
- * 在启动时预置此预防性指令，让 agent 在感知接近上限时主动收尾。
- *
- * 长期方案是切到 pi `--mode rpc`（支持运行时 steer 命令），见 follow-up。
- */
-export const WRAP_UP_HINT = [
-  `You have a turn limit. As you sense you are approaching it, proactively wrap up:`,
-  "1. Summarize what you have completed (with evidence: file paths, command output).",
-  "2. List what remains undone and why.",
-  "3. State the single most important next step for whoever continues.",
-  "Do NOT claim the task is complete if any part remains unfinished.",
-].join(" ");
-
-/** turn limiter 配置。 */
-export interface TurnLimiterOptions {
-  maxTurns: number;
-  graceTurns: number;
-  steer: (msg: string) => void;
-  abort: () => void;
-}
-
-/**
- * soft/hard turn 限制。
- *
- *   onTurnEnd(currentTurns):
- *     已 aborted 或 maxTurns<=0（禁用）→ 直接 return
- *     currentTurns >= maxTurns 且未 steer → steer(WRAP_UP_MESSAGE)（仅一次）
- *     已 steer 且 currentTurns >= maxTurns + graceTurns → abort()（仅一次）
- *
- * maxTurns<=0 表示不限（limit=Infinity，永不触发）。
- * graceTurns<=0 时 steer 后下一 turn 即 abort。
- */
-export interface TurnLimiter {
-  /** 每次 turn_end 调用。 */
-  onTurnEnd(currentTurns: number): void;
-  /**
-   * 重置 steered/aborted 标志（新一轮开始）。
-   *
-   * chatMode 下 agent_settled 时调用——每轮（message → agent_settled）独立计数，
-   * maxTurns 不跨轮累计（续聊本质是无限轮，累计上限违背 G1）。
-   * 非 chatMode 不调用，行为不变（全程累计）。
-   */
-  reset(): void;
-  /** 是否已发过 steer（诊断用）。 */
-  readonly didSteer: boolean;
-  /** 是否已 abort（诊断用）。 */
-  readonly didAbort: boolean;
-}
-
-/** 工厂函数。 */
-export function createTurnLimiter(opts: TurnLimiterOptions): TurnLimiter {
-  let steered = false;
-  let aborted = false;
-  const limit = opts.maxTurns > 0 ? opts.maxTurns : Infinity;
-  const grace = opts.graceTurns > 0 ? opts.graceTurns : 0;
-
-  const onTurnEnd = (turn: number): void => {
-    if (aborted || !Number.isFinite(limit)) return;
-    if (!steered && turn >= limit) {
-      steered = true;
-      opts.steer(WRAP_UP_MESSAGE);
-    }
-    if (steered && turn >= limit + grace) {
-      aborted = true;
-      opts.abort();
-    }
-  };
-
-  const reset = (): void => {
-    steered = false;
-    aborted = false;
-  };
-
-  return {
-    onTurnEnd,
-    reset,
-    get didSteer(): boolean {
-      return steered;
-    },
-    get didAbort(): boolean {
-      return aborted;
-    },
-  };
-}