@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

package/src/orchestration/skill-discovery.ts

@@ -1,115 +0,0 @@
-/**
- * Skill path discovery — resolve a skill name to its directory or SKILL.md path.
- *
- * Symmetric to execution/agent-registry.ts (which discovers agents): this module owns
- * the resource-discovery concern for skills across project / user / npm sources.
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-
-// ── Skill path resolution (with npm dir cache) ─────────────────────
-
-const skillCandidatesCache = new Map<string, string[]>();
-
-/** List npm skill candidate paths — cached per npmSkillsDir. */
-function getNpmSkillCandidates(npmSkillsDir: string): string[] {
-  const cached = skillCandidatesCache.get(npmSkillsDir);
-  if (cached) return cached;
-
-  const candidates: string[] = [];
-  try {
-    for (const pkg of fs.readdirSync(npmSkillsDir)) {
-      candidates.push(path.join(npmSkillsDir, pkg, "skills"));
-    }
-  } catch { /* npm dir not found — no npm skills available */ void undefined; }
-  skillCandidatesCache.set(npmSkillsDir, candidates);
-  return candidates;
-}
-
-/**
- * Resolve a skill name to its directory or SKILL.md path.
- * Search order:
- * 1. Project-level: .agents/skills/<name>/
- * 2. Global: <agentDir>/skills/<name>/（agentDir = getAgentDir()，实例隔离：
- *    PI_CODING_AGENT_DIR 场景读隔离目录，不碰 ~/.pi/agent）
- * 3. npm packages: <agentDir>/npm/node_modules/<pkg>/skills/<name>/
- * Returns the directory path if found, undefined otherwise.
- *
- * IF8(#14)：结果按 skillName 缓存（含未命中 undefined 也缓存，DM3）——调用点
- * agent-opts-resolver 每次 agent({skill}) call 一次，同 skill 名重复的逐候选
- * existsSync 全部消重。缓存生命周期 = session：index.ts 在 session_start 调
- * clearSkillPathCache 失效两级缓存（对齐同包 subagent-list-injector 的 session
- * 生命周期缓存模式）。不做进程级缓存的原因：pi 同一进程可能有多个 session
- * （TUI /new、/fork 同进程换 session），运行中安装的 skill（写入 project/user/npm
- * 任一源）需要对新 session 可见——进程级缓存会让曾 miss 的 skill 名（含缓存了
- * undefined 的未命中条目）在同进程后续 session 中永久不可见。session 内复用是
- * IF8/DM3 的主要收益（同一次 run 内同 skill 名重复调用消重），保持不变。
- */
-const skillMemo = new Map<string, string | undefined>();
-
-/**
- * 清空 resolveSkillPath 两级缓存（skillMemo 结果缓存 + npm 候选列表缓存）。
- * 两个消费点：测试隔离（beforeEach）与 index.ts session_start（session 生命周期
- * 失效——npm 源新装包产生的候选目录也要重新可见）。
- */
-export function clearSkillPathCache(): void {
-  skillMemo.clear();
-  skillCandidatesCache.clear();
-}
-
-/**
- * 把 skillName 解析到 rootDir 内的候选路径；越界（穿越）返回 undefined。
- *
- * 为什么需要守卫：path.resolve/path.join 会吸收 `..`（"../../x" 落到 skills 根
- * 之外），随后的 existsSync 命中会把 skills 树外的目录当 skill 目录返回——skill 名
- * 是名字不是路径，不该具备树外寻址能力。resolve 后与规范化 skills 根做前缀比较
- * （startsWith(root + sep)；恰好等于根也拒绝——"." 会把根自身当 skill 目录），
- * 越界 = 该候选不存在：全部候选越界时 resolveSkillPath 返回 undefined，调用方
- * （agent-opts-resolver）收到 not found（与 workflow name 拒绝的反馈风格一致）。
- *
- * 根内归一化仍允许（"a/../b" resolve 后在根内——守卫只拒逃逸，不拒归一化）。
- */
-function resolveWithinRoot(rootDir: string, skillName: string): string | undefined {
-  const root = path.resolve(rootDir);
-  const resolved = path.resolve(root, skillName);
-  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
-    return undefined;
-  }
-  return resolved;
-}
-
-export function resolveSkillPath(skillName: string): string | undefined {
-  // has 先行区分「缓存了未命中(undefined)」与「无条目」——未命中也缓存（DM3）
-  if (skillMemo.has(skillName)) {
-    return skillMemo.get(skillName);
-  }
-
-  const candidates: string[] = [];
-  const pushCandidate = (dir: string | undefined): void => {
-    if (dir !== undefined) candidates.push(dir);
-  };
-  // Project-level
-  pushCandidate(resolveWithinRoot(path.resolve(process.cwd(), ".agents/skills"), skillName));
-  // Global user skills
-  pushCandidate(resolveWithinRoot(path.join(getAgentDir(), "skills"), skillName));
-
-  // npm package skills (cached)
-  const npmSkillsDir = path.join(getAgentDir(), "npm/node_modules");
-  for (const pkgSkillsBase of getNpmSkillCandidates(npmSkillsDir)) {
-    pushCandidate(resolveWithinRoot(pkgSkillsBase, skillName));
-  }
-
-  for (const dir of candidates) {
-    if (fs.existsSync(dir)) {
-      skillMemo.set(skillName, dir);
-      return dir;
-    }
-  }
-
-  // 未命中也缓存：防止不存在的 skill 名反复全候选 existsSync（DM3）
-  skillMemo.set(skillName, undefined);
-  return undefined;
-}

package/src/orchestration/worker-handle.ts

@@ -1,115 +0,0 @@
-/**
- * Workflow Extension — Worker Handle
- *
- * node:worker_threads.Worker 的线程句柄封装。技术资源，Infra 层具体类（D-12）。
- * RunRuntime 直接持有，不经 interface（§domain-models 9）。
- *
- * 核心职责：竞态防护（G-025）。
- *
- * 背景：一个 run 可经历多个 WorkerHandle（终止/重试各换一个）。
- * 需防止「terminate(old) → start(new) → old exit fires」竞态——
- * WorkerHandle 把守卫内化：terminate 后 isCurrent=false，
- * 已终止 handle 的 onMessage/onError/onExit 回调自动 no-op（无需调用方比对引用）。
- *
- * 层归属：Infra（D-12）。仅依赖 node:worker_threads（Node 原生）。
- */
-
-import { type Worker } from "node:worker_threads";
-
-// ── Handler signatures ───────────────────────────────────────
-
-/** Worker → Main 业务消息回调。 */
-export type WorkerMessageHandler = (raw: unknown) => void;
-/** Worker 线程 uncaught error 回调。 */
-export type WorkerErrorHandler = (err: Error) => void;
-/** Worker 线程 exit 回调（code=0 正常退出，非 0 崩溃）。 */
-export type WorkerExitHandler = (code: number) => void;
-
-// ── WorkerHandle ──────────────────────────────────────────────
-
-export class WorkerHandle {
-  private readonly worker: Worker;
- /**
- * 竞态守卫。true = 此 handle 仍是当前活动 handle；false = 已 terminate，
- * 后续事件（已终止 worker 延迟触发的 message/error/exit）必须忽略。
- *
- * 终止后置 false 并永不回升（幂等语义）。新 handle 由调用方（WorkerHost）
- * 重新创建，已终止 handle 留在内存里直到 GC，但其回调全部 no-op。
- */
-  private current = true;
-
-  constructor(worker: Worker) {
-    this.worker = worker;
-  }
-
- /** 此 handle 是否仍是当前活动 handle（terminate 后 false，G-025）。 */
-  get isCurrent(): boolean {
-    return this.current;
-  }
-
- /** 底层 Worker（WorkerHost/RunRuntime 偶尔需要直接访问，如 ref/href）。 */
-  get raw(): Worker {
-    return this.worker;
-  }
-
- /**
- * 向 worker 发送消息。terminate 后 no-op（已终止 handle 的 postMessage 无意义）。
- */
-  postMessage(msg: unknown): void {
-    if (!this.current) return;
-    this.worker.postMessage(msg);
-  }
-
- /**
- * 终止 worker 线程。幂等——重复调用安全，第二次起 no-op。
- * 置 isCurrent=false 后再 await worker.terminate，确保并发 exit 事件
- * 在 terminate resolve 之前到达时也被守卫拦下。
- */
-  async terminate(): Promise<void> {
-    if (!this.current) return;
-    this.current = false;
-    try {
-      await this.worker.terminate();
-    } catch (err) {
- // terminate 失败不阻断（worker 可能已退出）。current 已 false，安全。
- // 不向上抛——调用方（RunRuntime.release）不应被底层线程错误打断。
-      void err;
-    }
-  }
-
- /**
- * 绑定 message 回调。仅当 isCurrent 时触发——已终止 handle 的事件被吞掉。
- * 返回 this 便于链式 onMessage(...).onError(...).onExit(...)。
- */
-  onMessage(handler: WorkerMessageHandler): this {
-    this.worker.on("message", (raw: unknown) => {
-      if (!this.current) return;
-      handler(raw);
-    });
-    return this;
-  }
-
- /**
- * 绑定 error 回调。仅当 isCurrent 时触发。
- */
-  onError(handler: WorkerErrorHandler): this {
-    this.worker.on("error", (err: Error) => {
-      if (!this.current) return;
-      handler(err);
-    });
-    return this;
-  }
-
- /**
- * 绑定 exit 回调。仅当 isCurrent 时触发——这是 G-025 的关键守卫：
- * terminate(old) → startWorker(new) → old exit 触发时，old handle.current
- * 已为 false，回调 no-op，不会误删 new worker。
- */
-  onExit(handler: WorkerExitHandler): this {
-    this.worker.on("exit", (code: number) => {
-      if (!this.current) return;
-      handler(code);
-    });
-    return this;
-  }
-}

package/src/orchestration/worker-host.ts

@@ -1,98 +0,0 @@
-/**
- * Workflow Extension — Worker Host
- *
- * WorkerHost port 的 Infra 实现。
- *
- * 职责：启动一个 Worker thread 运行 workflow 脚本，返回 WorkerHandle，
- * 并把 worker 的 message/error/exit 事件绑定到调用方注入的 WorkerHandlers。
- *
- * 层归属：Infra（D-12）。implements Engine 层的 WorkerHost port。
- *
- * 设计：
- * - WorkerHostImpl implements WorkerHost（而非散落的 free function）。
- * - 返回 WorkerHandle（封装），而非裸 Worker——onExit 传 handle 给
- * handlers.onExit(code, handle)，调用方用 handle.isCurrent 做竞态防护（C.3 + G-025）。
- * - eval:true + 内联 buildWorkerScript 源码字符串（C.2：不用不存在的 bootstrap 文件）。
- * - workerData: { scriptPath, args, workspace, meta }（不含 callCache/budget——
- * 这些是 RunState 字段，由 lifecycle 在调用 start 前注入到 args 或独立处理）。
- * - temp file 清理逻辑移到 Engine lifecycle，本处不管。
- */
-
-import { Worker } from "node:worker_threads";
-
-import type { WorkerHandlers, WorkerHost } from "./models/ports.ts";
-import type { RunSpec } from "./models/run-spec.ts";
-import { WorkerHandle } from "./worker-handle.ts";
-import { buildWorkerScript } from "./worker-script-builder.ts";
-
-// ── WorkerHostImpl ───────────────────────────────────────────
-
-export class WorkerHostImpl implements WorkerHost {
- /**
- * 启动一个 Worker thread 运行 workflow 脚本。
- *
- * 1. 用 buildWorkerScript(spec.scriptSource) 包装用户脚本（注入 agent/parallel/
- * pipeline/$ARGS/$BUDGET 等全局，AC-4 格式契约由 buildWorkerScript 保证）
- * 2. new Worker(code, { eval: true, workerData })（C.2 修复：eval 内联源码，
- * 不 require bootstrap 文件）
- * 3. 包装为 WorkerHandle，绑定 onMessage/onError/onExit 回调到 handlers
- * 4. onExit 传 handle 给 handlers.onExit(code, handle)（C.3 修复——调用方用
- * handle.isCurrent 做竞态防护，G-025）
- *
- * 返回的 WorkerHandle 由调用方（lifecycle）保存到 RunRuntime.worker。
- * 终止/崩溃重建（rebuild）时由 RunRuntime.release 接管。
- */
-  start(
-    spec: RunSpec,
-    args: Record<string, unknown>,
-    handlers: WorkerHandlers,
-  ): WorkerHandle {
-    const workerCode = buildWorkerScript(spec.scriptSource);
-
-    const worker = new Worker(workerCode, {
-      eval: true,
-      workerData: {
-        scriptPath: spec.scriptPath,
-        args,
-        workspace: process.cwd(),
-        meta: {
-          name: spec.scriptName,
-          description: spec.description,
-        },
- // D-12 regression fix (round-2 #1)：注入 budget，否则 worker 内 $BUDGET.total 恒为 0。
- // 旧 agent-call-handler.ts 删除时同时丢失了 budget 注入和 budget-update 发送方，
- // 导致依赖 $BUDGET 做动态预算分支的脚本静默得到全 0。
-        budget: {
-          maxTokens: spec.budgetTokens,
-          usedTokens: 0,
-          usedCost: 0,
-        },
-        // Option B symmetric single-path: model/thinkingLevel flow through
-        // workerData → $MODEL/$THINKING_LEVEL worker globals (injected by
-        // worker-script-builder) → agent() fallback. Not merged into args.
-        model: spec.model,
-        thinkingLevel: spec.thinkingLevel,
-      },
-    });
-
-    const handle = new WorkerHandle(worker);
-
- // 绑定事件——WorkerHandle 内部用 isCurrent 守卫，terminate 后回调 no-op（G-025）。
- // handlers 的 onMessage/onError/onExit 都是 async，这里 void 掉 promise（worker 事件
- // 不能 await，且 handler 内部错误由 lifecycle 统一捕获）。
-    handle.onMessage((raw) => {
-      void handlers.onMessage(raw);
-    });
-    handle.onError((err) => {
-      void handlers.onError(err);
-    });
-    handle.onExit((code) => {
- // C.3 修复：传 handle 给 onExit，调用方用 handle.isCurrent 做竞态防护。
- // 注意：此时 handle.isCurrent 仍为 true（onExit 回调仅在 isCurrent 时触发，
- // WorkerHandle 的内部守卫已过滤掉 terminate 后的 stale exit）。
-      void handlers.onExit(code, handle);
-    });
-
-    return handle;
-  }
-}