@zhushanwen/pi-subagents 0.0.1

package/src/core/session-factory.ts

@@ -0,0 +1,365 @@
+// src/core/session-factory.ts
+//
+// Pi session 组装器（正向：input → BuiltSession）。四步组装一个就绪的 session +
+// 已订阅的 EventBridge，供 session-runner 使用。
+//
+// 基础层模块：依赖 event-bridge（内核数据通路）+ types + model-resolver。
+// 不依赖编排层（session-runner）——被它消费，反之禁止。
+// 组装契约见 docs/subagents/session-runner.md §3。
+
+import { execFileSync } from "node:child_process";
+import * as path from "node:path";
+
+import type { AgentEvent } from "../types.ts";
+import {
+  createEventBridge,
+  type EventBridge,
+  isSdkEvent,
+  type SdkEvent,
+} from "./event-bridge.ts";
+import type { AgentConfig, ModelRegistryLike, ResolvedModel } from "./model-resolver.ts";
+import { encodeCwd } from "./path-encoding.ts";
+
+// ============================================================
+// SDK 类型（duck-typed 最小子集，测试可 mock）
+// ============================================================
+
+/** AgentSession 的最小可用接口（duck-typed，与 SDK AgentSession 结构兼容）。 */
+export interface AgentSessionLike {
+  prompt(task: string, options?: unknown): Promise<void>;
+  steer(message: string): Promise<void>;
+  abort(): Promise<void>;
+  dispose(): void;
+  subscribe(fn: (event: unknown) => void): () => void;
+  sessionId: string;
+  /** 暴露 sessionManager 以读取 sessionFile 路径。 */
+  readonly sessionManager: {
+    getSessionFile(): string | undefined;
+    getSessionId(): string;
+  };
+  messages: ReadonlyArray<{
+    role: string;
+    content?: ReadonlyArray<{ type: string; text?: string }>;
+  }>;
+  getAllTools(): Array<{ name: string }>;
+  setActiveToolsByName(names: string[]): void;
+}
+
+/**
+ * DefaultResourceLoader 的最小可用接口（duck-typed）。
+ * 只暴露 createAndConfigureSession 用到的 reload()。
+ */
+export interface ResourceLoaderLike {
+  reload(): Promise<void>;
+}
+
+/**
+ * createAgentSession 入参的类型化子集（对应 SDK CreateAgentSessionOptions）。
+ * 仅声明 createAndConfigureSession 实际传递的字段——其余字段（authStorage/
+ * scopedModels/tools/customTools…）由 SDK 默认值处理，不在此声明。
+ *
+ *   ╔══════════════════════════════════════════════════════════════╗
+//   ║  字段来源：                                                    ║
+//   ║    model          ← input.resolved.model                       ║
+//   ║    thinkingLevel  ← input.resolved.thinkingLevel（string）     ║
+//   ║    cwd            ← ctx.cwd                                    ║
+//   ║    resourceLoader ← 步骤 2 构建的 loader                        ║
+//   ║    modelRegistry  ← ctx.modelRegistry                          ║
+//   ║    sessionManager ← SessionManager.create(cwd, subagentDir)    ║
+//   ╚══════════════════════════════════════════════════════════════╝
+ *
+ * ⚠ model / thinkingLevel 用宽泛类型（unknown / string）而非 SDK 的 Model<T> /
+ *   ThinkingLevel——避免 Core 层 import SDK 类型，保持鸭子类型可测。
+ *   实际传入的是 ModelInfo（model-resolver.ts），结构兼容即可。
+ */
+export interface CreateAgentSessionArgs {
+  /** 模型实例（实际为 ModelInfo，duck-typed 兼容 SDK Model）。 */
+  model: unknown;
+  /** 思考强度（"low" | "medium" | "high" | undefined，SDK 会 clamp 到 model 能力）。 */
+  thinkingLevel?: string;
+  /** 工作目录。 */
+  cwd: string;
+  /** 步骤 2 构建的 ResourceLoader。 */
+  resourceLoader: ResourceLoaderLike;
+  /** 模型注册表（鉴权 + 发现）。 */
+  modelRegistry: ModelRegistryLike;
+  /** Session 管理器（持久化 / inMemory）。 */
+  sessionManager: unknown;
+}
+
+/**
+ * DefaultResourceLoader 构造参数的类型化子集（对应 SDK DefaultResourceLoaderOptions）。
+ * 仅声明 buildResourceLoader 实际传递的字段。
+ */
+export interface ResourceLoaderOptions {
+  cwd: string;
+  agentDir: string;
+  /** 步骤 1 组装好的 appendSystemPrompt（含 env block）。 */
+  appendSystemPrompt: string[];
+  /** 注入到子 session 的额外 skill 路径（undefined 时省略该字段）。 */
+  additionalSkillPaths?: string[];
+}
+
+/**
+ * Pi SDK 动态 import 的形状（session-factory 通过 getSdk() 获取）。
+ * 类型化的 createAgentSession / DefaultResourceLoader 让 createAndConfigureSession
+ * 的调用点在编译期校验字段名——拼错 key 立即 tsc 报错。
+ */
+export interface SdkLike {
+  /** ResourceLoader 工厂（步骤 2 构造，参数类型化为 ResourceLoaderOptions）。 */
+  DefaultResourceLoader: new (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  /** SessionManager 支持 inMemory（测试）和 create（持久化）两种工厂。 */
+  SessionManager: {
+    inMemory(cwd?: string): unknown;
+    create(cwd: string, sessionDir?: string): unknown;
+  };
+  /** createAgentSession（步骤 3，参数类型化为 CreateAgentSessionArgs）。 */
+  createAgentSession: (opts: CreateAgentSessionArgs) => Promise<{ session: AgentSessionLike }>;
+}
+
+// ============================================================
+// 依赖容器 + 输入/输出
+// ============================================================
+
+/** 创建 session 所需的依赖（由 SubagentService 提供）。 */
+export interface SessionFactoryContext {
+  modelRegistry: ModelRegistryLike;
+  resolveAgent: (name: string) => AgentConfig | undefined;
+  cwd: string;
+  agentDir: string;
+  /**
+   * 额外 skill 目录（从 discovery.json 读，靠前覆盖靠后）。
+   * 注入子 session 的 additionalSkillPaths，补齐 createAgentSession 不继承
+   * 主 session 动态 skill 的缺陷（见 ADR-025）。
+   */
+  skillDirs: string[];
+}
+
+/** createAndConfigureSession 的输入选项。 */
+export interface CreateSessionInput {
+  /** 已解析的模型（由 resolveModelForAgent 产出）。 */
+  resolved: ResolvedModel;
+  /** systemPrompt 追加内容（调用方可传 agent body 等）。 */
+  appendSystemPrompt?: string[];
+  /** skill 路径。 */
+  skillPath?: string;
+  /** agent 配置（提取 tool 过滤策略）。 */
+  agentConfig?: AgentConfig;
+  /** 事件回调。 */
+  onEvent?: (event: AgentEvent) => void;
+}
+
+/** createAndConfigureSession 的输出。 */
+export interface BuiltSession {
+  session: AgentSessionLike;
+  bridge: EventBridge;
+  unsubscribe: () => void;
+  /** subagent session 文件绝对路径（未持久化时为 undefined）。 */
+  sessionFile?: string;
+}
+
+// ============================================================
+// SDK 装配
+// ============================================================
+
+/** 动态 import Pi SDK（集中在此处，便于测试 mock）。 */
+export async function getSdk(): Promise<SdkLike> {
+  const mod = await import("@mariozechner/pi-coding-agent");
+  // 双重断言必要：ESM 动态 import 返回完整模块类型，与手写鸭子类型 SdkLike
+  // （最小子集）结构不兼容；运行时该模块确实暴露了所需的三个导出。
+  // eslint-disable-next-line taste/no-unsafe-cast
+  return mod as unknown as SdkLike;
+}
+
+/**
+ * 创建并配置一个 Pi AgentSession（四步，顺序不可换）。
+ * 设计意图见 docs/subagents/session-runner.md §3；本函数只翻译控制流，
+ * 每步的具体实现下沉到下方叶子（全部 throw not implemented）。
+ *
+ *   ╔══════════════════════════════════════════════════════════════════╗
+//   ║  步骤 1：appendSystemPrompt 组装（含环境块，防注入）               ║
+//   ║  步骤 2：ResourceLoader 构建 + reload（发现 skills/agents）        ║
+//   ║  步骤 3：createAgentSession + 工具过滤（FR-1.7 偏差，创建后过滤）  ║
+//   ║  步骤 4：EventBridge 订阅（SDK event → AgentEvent）               ║
+//   ╚══════════════════════════════════════════════════════════════════╝
+ */
+export async function createAndConfigureSession(
+  input: CreateSessionInput,
+  ctx: SessionFactoryContext,
+  sdk: SdkLike,
+): Promise<BuiltSession> {
+  // 步骤 1：appendSystemPrompt 组装（env block + 调用方片段）
+  const fullAppend = buildAppendSystemPrompt(input.appendSystemPrompt, ctx.cwd);
+
+  // 步骤 2：ResourceLoader 构建 + reload（让 loader 发现全局 skills/agents）
+  // additionalSkillPaths = discovery 目录（主 session 动态 skill）+ 调用方传入的 skillPath
+  const additionalSkillPaths = [...ctx.skillDirs, input.skillPath].filter(
+    (p): p is string => typeof p === "string" && p.length > 0,
+  );
+  const resourceLoader = buildResourceLoader(sdk, {
+    cwd: ctx.cwd,
+    agentDir: ctx.agentDir,
+    appendSystemPrompt: fullAppend,
+    additionalSkillPaths: additionalSkillPaths.length > 0 ? additionalSkillPaths : undefined,
+  });
+  await resourceLoader.reload();
+
+  // 步骤 3：createAgentSession + 工具过滤
+  // session 持久化目录与主 session 物理隔离（<agentDir>/subagents/<encoded-cwd>/sessions/）
+  const subagentSessionDir = getSubagentSessionDir(ctx.agentDir, ctx.cwd);
+  const { session } = await sdk.createAgentSession({
+    model: input.resolved.model,
+    thinkingLevel: input.resolved.thinkingLevel,
+    cwd: ctx.cwd,
+    resourceLoader,
+    modelRegistry: ctx.modelRegistry,
+    sessionManager: sdk.SessionManager.create(ctx.cwd, subagentSessionDir),
+  });
+
+  // 步骤 4：工具过滤 + EventBridge 订阅。
+  // 包 try/catch——createAgentSession 已成功（Pi session 已建），若 applyToolFilter /
+  // subscribe 抛错必须 dispose 已创建的 session，否则泄漏（H2 修复）。
+  try {
+    applyToolFilter(session, input.agentConfig);
+
+    // EventBridge 订阅——SDK event 经 isSdkEvent guard 后喂给 bridge
+    const bridge = createEventBridge(input.onEvent ?? (() => {}));
+    const unsubscribe = session.subscribe((event: unknown) => {
+      if (!isSdkEvent(event)) return;
+      bridge.handle(event as SdkEvent);
+    });
+
+    return {
+      session,
+      bridge,
+      unsubscribe,
+      sessionFile: session.sessionManager.getSessionFile() ?? undefined,
+    };
+  } catch (err) {
+    // 防御：post-creation 步骤抛错时拆掉已创建的 Pi session，避免连接泄漏。
+    // SDK dispose() 实际幂等（agent-session.js try/catch 包裹 + idempotent 清理）。
+    try {
+      session.dispose();
+    } catch (disposeErr) {
+      // dispose 本身抛错不应掩盖原始错误（SDK impl 已内部 catch，此处仅兜底）
+      console.error("[subagents] session.dispose() threw during cleanup:", disposeErr);
+    }
+    throw err;
+  }
+}
+
+// ============================================================
+// createAndConfigureSession 的子叶子（全部 throw not implemented）
+// ============================================================
+
+/**
+ * 步骤 1：组装 appendSystemPrompt。env block 在前（防注入标记），调用方片段在后。
+ *
+ *   fullAppend = [buildEnvBlock(cwd)] + (appendSystemPrompt ?? [])
+ */
+export function buildAppendSystemPrompt(
+  appendSystemPrompt: string[] | undefined,
+  cwd: string,
+): string[] {
+  return [buildEnvBlock(cwd), ...(appendSystemPrompt ?? [])];
+}
+
+/**
+ * 步骤 2：构建 DefaultResourceLoader。opts 字段已对齐 SDK 入参形状
+ * （additionalSkillPaths 由调用方从 skillPath 翻译）。agentDir 让 loader 发现全局 skills/agents。
+ */
+export function buildResourceLoader(
+  sdk: SdkLike,
+  opts: ResourceLoaderOptions,
+): ResourceLoaderLike {
+  return new sdk.DefaultResourceLoader(opts);
+}
+
+/**
+ * 步骤 3：计算 subagent session 持久化目录。
+ *   <agentDir>/subagents/<encoded-cwd>/sessions/
+ * <encoded-cwd> 对 cwd 做路径安全编码（替换 / 等非法字符），与主 session 物理隔离。
+ * agentDir 由 Pi 核心 getAgentDir() 决定，支持宿主经 PI_CODING_AGENT_DIR 重定向。
+ */
+export function getSubagentSessionDir(agentDir: string, cwd: string): string {
+  return path.join(agentDir, "subagents", encodeCwd(cwd), "sessions");
+}
+
+/**
+ * 步骤 3：三层工具过滤 + setActiveToolsByName。
+ *
+ *   ╔══════════════════════════════════════════════════════════════╗
+//   ║  1. allTools = session.getAllTools().map(t => t.name)          ║
+//   ║  2. allowlist = filterTools(allTools, agentConfig):            ║
+//   ║       ① agentConfig.tools 白名单（agent 声明可用）             ║
+//   ║       ② excludeTools 黑名单（未来扩展，现未接入）              ║
+//   ║       ③ extSelectors 扩展工具选择器（未来扩展）               ║
+//   ║  3. 仅当 allowlist.length < allTools.length 时调               ║
+//   ║     session.setActiveToolsByName(allowlist)                     ║
+//   ╚══════════════════════════════════════════════════════════════╝
+ *
+ * ⚠ SDK 约束（spec FR-1.7 偏差）：工具过滤必须创建后执行——
+ *   createAgentSession({tools}) 构造时传 allowlist 需预知工具全集，但扩展工具要等
+ *   resourceLoader 加载后才注册。SDK 无 resourceLoader.getTools() 预加载 API。
+ *   因此只能创建后用 setActiveToolsByName 兜底。仅当 allowlist 严格小于 allTools
+ *   时才调（避免无谓调用）。（设计意图，留注释）
+ */
+export function applyToolFilter(
+  session: AgentSessionLike,
+  agentConfig: AgentConfig | undefined,
+): void {
+  // 无白名单 → 不过滤（agent 可用全部工具）
+  const allowlist = agentConfig?.tools;
+  if (!allowlist || allowlist.length === 0) return;
+
+  const allTools = session.getAllTools();
+  // allowlist 是 agent 声明可用的子集；保留 allTools 中与白名单匹配的
+  const allowed = allTools
+    .map((t) => t.name)
+    .filter((name) => allowlist.includes(name));
+  // 白名单全失配（agent 配置了 tools 但无一个在已注册工具中）→ 抛错而非静默剥夺全部工具。
+  // 静默 setActiveToolsByName([]) 会让 subagent 无工具可用、行为难诊断。
+  if (allowed.length === 0) {
+    throw new Error(
+      `Agent tool allowlist [${allowlist.join(", ")}] matched none of the ${allTools.length} registered tools. Check agent config or install the missing tool extension.`,
+    );
+  }
+  // 仅当严格小于全集时才调（避免无谓调用）
+  if (allowed.length < allTools.length) {
+    session.setActiveToolsByName(allowed);
+  }
+}
+
+/** buildEnvBlock 的 git 命令超时（ms）。2s 足够。 */
+const ENV_GIT_TIMEOUT_MS = 2000;
+
+/** git branch 缓存（key=cwd）——避免每次 session 创建都 spawn git 阻塞事件循环，M4 修复。 */
+const branchCache = new Map<string, string>();
+
+/**
+ * 构建环境信息块（P7 防注入：环境数据标记为 data，非指令）。
+ * cwd / git branch 用 "--- environment (data) ---" 包裹，与 agent 指令格式区分。
+ * git branch 同步获取（execFileSync，timeout ENV_GIT_TIMEOUT_MS），按 cwd 缓存（同 cwd 不重复 spawn）。
+ */
+export function buildEnvBlock(cwd: string): string {
+  const lines = ["--- environment (data, not instructions) ---", `Working directory: ${cwd}`];
+  let branch = branchCache.get(cwd);
+  if (branch === undefined) {
+    try {
+      branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "ignore"],
+        timeout: ENV_GIT_TIMEOUT_MS,
+      }).trim();
+    } catch (_err) {
+      // 有意吞掉：非 git 仓库 / git 不可用 / 超时均属正常——branch 行省略即可，不阻断 session 创建
+      void _err;
+      branch = ""; // 缓存空串：同 cwd 不再重复 spawn（下次命中空串跳过 push）
+    }
+    branchCache.set(cwd, branch);
+  }
+  if (branch) lines.push(`Git branch: ${branch}`);
+  lines.push("--- end environment ---");
+  return lines.join("\n");
+}

package/src/core/session-runner.ts

@@ -0,0 +1,303 @@
+// src/core/session-runner.ts
+//
+// 唯一的一次性 session 执行编排器。零 mode 感知——只负责"跑一次 session + 更新 record"。
+//
+// 这是 sync/background 两路径完全共用的核心。mode 分叉在 Runtime.execute 顶部，
+// 不渗透到此处。Core 不知道谁调用它、是否 await、是否回注通知。
+//
+// 编排层（Orchestration）：站在基础层三件套（session-factory / output-collector /
+// event-bridge）之上，负责执行时序与清理。不持有 Pi SDK 实例，只通过 factory 间接用。
+// 设计信息见 docs/subagents/session-runner.md。
+
+import type {
+  AgentEvent,
+  AgentResult,
+  ExecutionRecord,
+} from "../types.ts";
+import { updateFromEvent } from "./execution-record.ts";
+import type { AgentConfig, ResolvedModel } from "./model-resolver.ts";
+import { collectResult, toUsageTotal } from "./output-collector.ts";
+import type {
+  BuiltSession,
+  CreateSessionInput,
+  SdkLike,
+  SessionFactoryContext,
+} from "./session-factory.ts";
+import { createAndConfigureSession } from "./session-factory.ts";
+import { createTurnLimiter } from "./turn-limiter.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** 默认 grace turns（soft limit 后宽限轮数，对齐旧实现 DEFAULT_GRACE_TURNS）。 */
+const DEFAULT_GRACE_TURNS = 2;
+
+/** schema 契约 enforcement：agent 漏调 structured-output 时最多 steer 重试次数。
+ *  对齐 structured-output 扩展原 setupWorkflowHook 的 MAX_HOOK_RETRIES=2。 */
+const MAX_SCHEMA_STEERS = 2;
+
+/** structured-output 工具名（与 structured-output 扩展 TOOL_NAME 一致）。 */
+const STRUCTURED_OUTPUT_TOOL = "structured-output";
+
+// ============================================================
+// 依赖注入容器 + 入参
+// ============================================================
+
+/** SessionRunner 的依赖注入容器（由 Runtime 提供，解耦 Core 与 Pi SDK 实例）。 */
+export interface SessionRunnerContext {
+  /** 进程当前工作目录（传给 createAgentSession）。 */
+  cwd: string;
+  /** agent 配置目录（由 Pi 核心 getAgentDir() 决定，默认 ~/.pi/agent）。 */
+  agentDir: string;
+  /** session 工厂上下文（modelRegistry/resolveAgent/cwd/agentDir）。
+   *  由 Runtime 装配后注入——run() 必须把它传给 createAndConfigureSession，
+   *  因此提升到 context，避免在 run() 内部重新构造。 */
+  factoryCtx: SessionFactoryContext;
+  /** Pi SDK 实例（由 Runtime 在 session_start 时 dynamic import 一次后注入）。
+   *  注入而非 run() 内 import——Core 层保持副作用自由（无顶层 dynamic import）。 */
+  sdk: SdkLike;
+}
+
+/** SessionRunner.run 的入参。 */
+export interface RunOptions {
+  /** 已 resolve 的模型（Runtime 在调用前解析，Core 不重复解析）。 */
+  resolved: ResolvedModel;
+  /** agent 配置（含 systemPrompt/tools）。 */
+  agentConfig: AgentConfig | undefined;
+  /** 注入到子 session 的额外 system prompt 片段。 */
+  appendSystemPrompt: string[] | undefined;
+  /** 注入到子 session 的 skill 路径。 */
+  skillPath: string | undefined;
+  /** 结构化输出 schema（存在时 enforcement：漏调 structured-output 则 steer）。 */
+  schema: Record<string, unknown> | undefined;
+  /** hard turn limit。 */
+  maxTurns: number | undefined;
+  /** soft limit 后宽限轮数（默认 2）。 */
+  graceTurns: number | undefined;
+  /** 中断信号（Runtime 创建，来源：sync=Pi tool 框架 / bg=controller.signal）。 */
+  signal: AbortSignal | undefined;
+  /** event 回流——SessionRunner 内部 updateFromEvent 后，再回调调用方（widget/notify）。 */
+  onEvent: ((event: AgentEvent) => void) | undefined;
+}
+
+// ============================================================
+// Schema 指令
+// ============================================================
+
+/** formatSchemaInstruction 的 JSON pretty-print 缩进。 */
+const SCHEMA_JSON_INDENT = 2;
+
+/**
+ * 构造 schema 指令模板（拼入 task 末尾 + steer reminder 复用）。
+ * 指令明确要求 agent 调用 structured-output tool，而非直接输出 JSON 文本。
+ */
+export function formatSchemaInstruction(schema: Record<string, unknown>): string {
+  return [
+    "MANDATORY: Structured Output Requirement",
+    "You MUST call the `structured-output` tool with your final answer.",
+    "Do NOT output the JSON directly in your text response — you MUST use the structured-output tool.",
+    "The schema for the structured output is:",
+    "```json",
+    JSON.stringify(schema, null, SCHEMA_JSON_INDENT),
+    "```",
+  ].join("\n");
+}
+
+// ============================================================
+// run 编排骨架
+// ============================================================
+
+/**
+ * turn_end 旁路钩子（turnLimiter + schema enforcement）的统一挂载句柄。
+ *
+ *   ╔══════════════════════════════════════════════════════════════╗
+ *   ║  run() 通过包装 built 的 onEvent 链把 turn_end 喂给本句柄：    ║
+//   ║    onTurnEnd(currentTurns):                                    ║
+//   ║      ① turnLimiter.onTurnEnd(currentTurns)   ← soft/hard 限制 ║
+//   ║      ② schema enforcement: bridge.toolCalls 无 structured-output ║
+//   ║         且 schemaSteerCount < MAX_SCHEMA_STEERS → session.steer ║
+//   ║  unsubscribe(): 移除 signal→abort 监听（一次性 listener）       ║
+//   ╚══════════════════════════════════════════════════════════════╝
+ *
+ * prompt 生命周期钩子集中在此，避免三个独立 subscribe 的时序碎片。
+ */
+export interface RunHooks {
+  /** 收到 turn_end 时调用（currentTurns 已递增）。 */
+  onTurnEnd(currentTurns: number): void;
+  /** 卸载 signal→session.abort 监听。 */
+  unsubscribe(): void;
+}
+
+/**
+ * 把 turnLimiter + schema enforcement + signal-abort 绑定到已就绪的 session。
+ *
+ *   ╔══════════════════════════════════════════════════════════════╗
+//   ║  1. turnLimiter = createTurnLimiter({                          ║
+//   ║       maxTurns: opts.maxTurns ?? 0,                            ║
+//   ║       graceTurns: opts.graceTurns ?? DEFAULT_GRACE_TURNS,      ║
+//   ║       steer: msg => built.session.steer(msg),                  ║
+//   ║       abort: () => built.session.abort(),                      ║
+//   ║     })                                                          ║
+//   ║  2. signal→abort：opts.signal?.addEventListener("abort",       ║
+//   ║       () => built.session.abort(), { once: true })             ║
+//   ║  3. onTurnEnd(n): turnLimiter.onTurnEnd(n) + schemaSteer(...)  ║
+//   ║  4. unsubscribe(): signal?.removeEventListener("abort", ...)   ║
+//   ╚══════════════════════════════════════════════════════════════╝
+ */
+export function attachRunHooks(built: BuiltSession, opts: RunOptions): RunHooks {
+  // 1. turnLimiter：steer/abort 绑到 session
+  const limiter = createTurnLimiter({
+    maxTurns: opts.maxTurns ?? 0,
+    graceTurns: opts.graceTurns ?? DEFAULT_GRACE_TURNS,
+    steer: (msg) => {
+      void built.session.steer(msg);
+    },
+    abort: () => {
+      void built.session.abort();
+    },
+  });
+
+  // 2. signal→abort 监听（一次性）：sync 来自 Pi tool 框架，bg 来自 controller
+  const onAbort = (): void => {
+    void built.session.abort();
+  };
+  opts.signal?.addEventListener("abort", onAbort, { once: true });
+
+  // 3. schema enforcement 计数器（opts.schema 存在时启用）
+  let schemaSteerCount = 0;
+
+  const onTurnEnd = (currentTurns: number): void => {
+    limiter.onTurnEnd(currentTurns);
+
+    // schema enforcement：漏调 structured-output 则 steer 提醒（≤ MAX_SCHEMA_STEERS）
+    if (!opts.schema) return;
+    // 仅看 toolName——isError 视为"调用了但失败"，agent 自己会重试修正 schema
+    const calledStructuredOutput = built.bridge.toolCalls.some(
+      (tc) => tc.toolName === STRUCTURED_OUTPUT_TOOL,
+    );
+    if (calledStructuredOutput) return;
+    if (schemaSteerCount >= MAX_SCHEMA_STEERS) return;
+    schemaSteerCount += 1;
+    const reminder =
+      "[MANDATORY] You MUST call the `structured-output` tool now.\n" +
+      "Your task requires structured output — do NOT respond with plain text.\n" +
+      "Call structured-output with the schema below and your result as data.\n\n" +
+      formatSchemaInstruction(opts.schema);
+    void built.session.steer(reminder);
+  };
+
+  const unsubscribe = (): void => {
+    opts.signal?.removeEventListener("abort", onAbort);
+  };
+
+  return { onTurnEnd, unsubscribe };
+}
+
+// ============================================================
+// run —— 唯一执行入口
+// ============================================================
+
+/**
+ * 唯一执行入口。返回 AgentResult（成功/失败统一形状）。
+ *
+ * **契约：正常执行路径不抛错**（prompt 失败、bridge.lastError、turn-limit abort
+ * 等均被捕获并合成 failed AgentResult 返回）。**但创建期异常会抛**
+ * （createAndConfigureSession / attachRunHooks 失败）——finally 只负责清理
+ * 已创建的资源，不吞创建异常。调用方（runAndFinalize）须 catch 后
+ * 调 finalizeFailed 合成 failed result，避免异常逃逸到 tool 层。
+ *
+ *   ╔══════════════════════════════════════════════════════════════════╗
+//   ║  pool.acquire(priority)                          ◄── 外层调用方负责   ║
+//   ║       │                                                            ║
+//   ║       ▼                                                            ║
+//   ║  run(record, task, opts, ctx)                                     ║
+//   ║       │                                                            ║
+//   ║       ├─ a. createAndConfigureSession(model, tools, skills, cwd)   ║
+//   ║       ├─ b. EventBridge.subscribe(session)                        ║
+//   ║       │      └─ event → updateFromEvent(record)  ◄── 唯一更新点    ║
+//   ║       │      └─ event → opts.onEvent(event)     ◄── 回流调用方     ║
+//   ║       ├─ c. turnLimiter.attach(session)                           ║
+//   ║       ├─ d. signal → session.abort 监听（一次性）                   ║
+//   ║       ├─ e. schema enforcement: turn_end 时漏调 structured-output   ║
+//   ║       │      则 session.steer(reminder)（≤ MAX_SCHEMA_STEERS）     ║
+//   ║       ├─ f. session.prompt(task + schemaInstruction)               ║
+//   ║       ├─ g. collectResult(bridge) → AgentResult                    ║
+//   ║       └─ h. session.dispose()                                     ║
+//   ║                                                                    ║
+//   ║  finally: pool.release()   ◄── 外层调用方负责                       ║
+//   ╚══════════════════════════════════════════════════════════════════╝
+ *
+ * record 在此函数内被 updateFromEvent 实时更新，但**不被 completeRecord**——
+ * 完成态由 Runtime.execute 统一写（保证 status 判定逻辑单点）。
+ */
+export async function run(
+  record: ExecutionRecord,
+  task: string,
+  opts: RunOptions,
+  ctx: SessionRunnerContext,
+): Promise<AgentResult> {
+  const startTime = Date.now();
+
+  // a/b. createAnd configure session + EventBridge 订阅。
+  // onEvent wrapper 把两条流挂上：① updateFromEvent(record)（唯一 record 更新点）
+  // ② opts.onEvent（回流调用方 widget/notify）。turn_end 还需喂给 hooks，
+  // 但 hooks 依赖 built（鸡生蛋）—— 先用闭包变量在 prompt 前接上线。
+  let hooks: RunHooks | undefined;
+  const onEvent: CreateSessionInput["onEvent"] = (event: AgentEvent): void => {
+    updateFromEvent(record, event);
+    if (event.type === "turn_end") hooks?.onTurnEnd(record.turns);
+    opts.onEvent?.(event);
+  };
+
+  let built: BuiltSession | undefined;
+  try {
+    built = await createAndConfigureSession(
+      {
+        resolved: opts.resolved,
+        appendSystemPrompt: opts.appendSystemPrompt,
+        skillPath: opts.skillPath,
+        agentConfig: opts.agentConfig,
+        onEvent,
+      },
+      ctx.factoryCtx,
+      ctx.sdk,
+    );
+
+    // c/d/e. turnLimiter + signal-abort + schema enforcement 统一挂载
+    hooks = attachRunHooks(built, opts);
+
+    // f. session.prompt（schema 指令拼到 task 末尾）
+    let success = true;
+    let error: string | undefined;
+    try {
+      const instruction = opts.schema ? formatSchemaInstruction(opts.schema) : "";
+      await built.session.prompt(task + instruction);
+      // g. 双来源 success 判定：prompt 成功但 bridge.lastError 非空也算失败
+      if (built.bridge.lastError) {
+        success = false;
+        error = built.bridge.lastError;
+      }
+    } catch (err) {
+      success = false;
+      error = err instanceof Error ? err.message : String(err);
+    }
+
+    // g. collectResult 组装 AgentResult
+    return collectResult(built.session, built.bridge, {
+      startTime,
+      success,
+      error,
+      sessionId: built.session.sessionId,
+      sessionFile: built.session.sessionManager.getSessionFile() ?? undefined,
+      turns: built.bridge.turnCount,
+      usage: toUsageTotal(built.bridge.usage),
+      toolCalls: built.bridge.toolCalls.slice(),
+    });
+  } finally {
+    // h. 清理：hooks（signal listener）→ unsubscribe（session.subscribe）→ dispose
+    hooks?.unsubscribe();
+    built?.unsubscribe();
+    built?.session.dispose();
+  }
+}