@zhushanwen/subagent-core 0.2.0

package/src/orchestration/skill-discovery.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 { getHostServices } from "../core/host-services.ts";
+
+// ── 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: 宿主注入 skills 根中 source "user-pi" 条目（pi 壳 = <agentDir>/skills，
+ *    现取 getAgentDir()——实例隔离：PI_CODING_AGENT_DIR 场景读隔离目录，不碰
+ *    ~/.pi/agent；见 pi-host.ts skillRoots 契约）
+ * 3. npm packages: 宿主注入 skills 根中 source "npm" 条目下的 <pkg>/skills/<name>/
+ *    （pi 壳 = <agentDir>/npm/node_modules）
+ *
+ * 根来源（u0-data-discovery 注入化）：getAgentDir() 运行时触点收敛为
+ * discoveryRoots()?.skills 注入消费。按 source 标签取根是本模块的结构性要求而非
+ * 对标签的语义解释——user 根直接解析 <root>/<name>/，npm 根需先枚举 <pkg> 一层，
+ * 两类根的消费形状不同，无法像 resource-discovery 那样整体按序扫描；标签字面
+ * （user-pi/npm）与 pi 壳 skillRoots 契约一致，core 不新增标签字面量。
+ * 未配置宿主（discoveryRoots 缺席）→ 空根列表 → 仅 project 根可命中（生产宿主在
+ * 扩展初始化最早处 configureCore，此形态只出现在测试/裸 core 消费方）。
+ * 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));
+
+  // 宿主注入根（每调用现取——与 pi-host 的 getAgentDir 现取语义一致，实例切换即生效）。
+  // 可选链从 discoveryRoots 起截断（discoveryRoots 是可选方法，缺席 = 空根列表）。
+  const injectedSkillRoots = getHostServices().discoveryRoots?.()?.skills ?? [];
+
+  // Global user skills（source "user-pi" 条目；宿主未提供该标签根时此源缺席）
+  const userSkillsRoot = injectedSkillRoots.find((root) => root.source === "user-pi");
+  if (userSkillsRoot !== undefined) {
+    pushCandidate(resolveWithinRoot(userSkillsRoot.dir, skillName));
+  }
+
+  // npm package skills (cached)（source "npm" 条目 = node_modules 基座）
+  const npmSkillsRoot = injectedSkillRoots.find((root) => root.source === "npm");
+  if (npmSkillsRoot !== undefined) {
+    for (const pkgSkillsBase of getNpmSkillCandidates(npmSkillsRoot.dir)) {
+      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

@@ -0,0 +1,115 @@
+/**
+ * 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

@@ -0,0 +1,98 @@
+/**
+ * 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;
+  }
+}