@zhushanwen/pi-subagent-workflow 0.1.0

package/src/orchestration/node-ops.ts

@@ -0,0 +1,192 @@
+/**
+ * Workflow Extension — node-ops
+ *
+ * 单节点操作 free functions（D-12）。
+ *
+ * 2 个导出函数：
+ * - retryNode(run, callId, deps) — 重置 call + 主线程重跑（不 replaceRuntime）
+ * - skipNode(run, callId, deps) — 标记 call done + 占位 result
+ *
+ * **D.5（方案 A）**：retryNode 的语义是「重试单个失败 call」——只重置 call 状态 +
+ * 主线程直接调 executeAgentCall，worker 不重启，已完成调用不受影响（worker 重启是
+ * worker-error-retry handleWorkerError 的语义，不在本职责内）。
+ *
+ * **retryNode 不影响脚本流程**：worker 在首次失败结果被 postAgentResult 投递后即
+ * resolve 并删除该 callId 的 pending Promise（worker-script-builder agent-result 分支）。
+ * retryNode 的二次 postMessage 因此被 worker 丢弃——新结果只更新 trace/TUI，
+ * 回不到脚本（脚本早已带着首次结果往下走）。这是 D.5「不重启 worker」的直接后果：
+ * 要让新结果回到脚本必须重启 worker 重跑整个脚本（旧 orchestrator.ts 语义），
+ * 与「不干扰已完成调用」的设计意图冲突。故 retryNode 定位为「失败节点的诊断性重跑
+ * + trace 刷新」，不承诺改变脚本输出。tool-workflow 的描述已如实声明此语义。
+ *
+ * **G6-001**：retryNode 前置 status==="running"（paused 下拒绝，要 retry 先 resume）。
+ *
+ * 层归属：Engine。依赖 LifecycleDeps + WorkflowRun + executeAgentCall。
+ *
+ * 参考：domain-models.md §失败处理矩阵（retryNode 语义）、clarification.md D.5/G6-001。
+ */
+
+import { postBudgetUpdate } from "./error-recovery.ts";
+import { executeAgentCall } from "./execute-agent-call.ts";
+import type { LifecycleDeps } from "./models/ports.ts";
+import type { AgentResult } from "./models/types.ts";
+import type { WorkflowRun } from "./models/workflow-run.ts";
+
+// ── skipNode 占位结果 ────────────────────────────────────────
+
+/** skipNode 注入的占位结果（零 usage，避免污染 budget）。 */
+const SKIP_PLACEHOLDER: AgentResult = {
+  content: "",
+  usage: {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    contextTokens: 0,
+    turns: 0,
+  },
+};
+
+// ── retryNode ────────────────────────────────────────────────
+
+/**
+ * 重试单个失败 agent call（诊断性重跑 + trace 刷新，不影响脚本流程）。
+ *
+ * **D.5 修复**：不 replaceRuntime、不重启 worker。只重置 call 状态（status=pending,
+ * attempts=0, result=undefined）+ 同步 trace 节点 + 主线程直接调 executeAgentCall。
+ * worker 仍在运行，已完成调用不受影响。
+ *
+ * **结果不回到脚本**：见文件头说明——worker 在首次失败结果投递后已 resolve 并删除
+ * 该 callId 的 pending Promise，本函数末尾的 postMessage 通常被 worker 丢弃。新结果
+ * 只反映在 trace/TUI，不改变脚本输出（若需让脚本拿新结果，须重启 worker 重跑整个
+ * 脚本，与 D.5 冲突，未采用）。
+ *
+ * 与 worker-error-retry的区别：
+ * - handleWorkerError：worker 本身崩溃 → replaceRuntime 重启整个 worker
+ * - retryNode：单个 call 失败 → 主线程重跑该 call，worker 不动
+ *
+ * **G6-001**：前置 status==="running"。paused 下抛错（要 retry 先 resume）。
+ *
+ * @param run WorkflowRun 聚合根
+ * @param callId 要重试的 call id（必须已存在于 run.state.calls）
+ * @param deps LifecycleDeps（runner 用于重跑 call）
+ * @throws run.state.status !== "running"（G6-001）
+ * @throws callId 不存在
+ */
+export async function retryNode(
+  run: WorkflowRun,
+  callId: number,
+  deps: LifecycleDeps,
+): Promise<void> {
+ // G6-001：前置 status==="running"
+  if (run.state.status !== "running") {
+    throw new Error(
+      `retryNode: requires status==="running" (current: ${run.state.status}, runId=${run.runId})`,
+    );
+  }
+
+  const call = run.state.calls.get(callId);
+  if (!call) {
+    throw new Error(`retryNode: call ${callId} not found in run ${run.runId}`);
+  }
+
+ // 重置 call 状态：done → pending（绕过 AgentCall 状态机守卫，因为是显式 reset 语义）
+  call.status = "pending";
+  call.attempts = 0;
+  call.result = undefined;
+  call.sessionId = undefined;
+
+ // 同步 trace 节点：回退到 pending
+  run.state.trace.update(callId, {
+    status: "pending",
+    result: undefined,
+    error: undefined,
+    completedAt: undefined,
+    sessionId: undefined,
+  });
+
+ // 主线程重跑（不重启 worker）——executeAgentCall 内部 markRunning + runner.run
+ // G6-001 保证 status==="running" ⟺ runtime defined；retryNode 已守 status==="running"
+ // 前置，故 run.runtime 必存在。非空断言，不再用 fallback 掩盖不变式违反。
+  const signal = run.runtime!.controller.signal;
+  await executeAgentCall(call, deps.runner, run.state.budget, signal, run.state.trace);
+
+ // 回发结果给 worker（best-effort：worker 通常已在首次失败结果投递后 resolve 并删除
+ // 该 callId 的 pending Promise，故本 postMessage 多被丢弃——见文件头 D.5 说明）。
+ // 保留是为覆盖「executeAgentCall 已完成但 dispatchAgentCall.then 尚未投递结果」的
+ // 极窄竞态窗口，以及与 skipNode 的回发路径对称。结果无论如何都已写入 trace/TUI。
+  if (call.result) {
+    run.runtime?.worker.postMessage({
+      type: "agent-result",
+      callId,
+      result: call.result,
+      cached: false,
+    });
+  }
+
+ // D-12 regression fix (round-2 #1)：retry 重跑消费 usage 后同步 worker $BUDGET
+  postBudgetUpdate(run);
+
+  await deps.store.save(run);
+}
+
+// ── skipNode ─────────────────────────────────────────────────
+
+/**
+ * 跳过单个 agent call（注入占位 result）。
+ *
+ * 标记 call.status="done" + 写入 SKIP_PLACEHOLDER result + 同步 trace 节点为 completed。
+ * 若 worker 仍活着，立即回发 agent-result（解锁 worker pending await）。
+ *
+ * 与 retryNode 的区别：skipNode 不重跑——直接用占位结果「假装完成」。
+ * 用于用户显式跳过失败节点继续执行的场景。
+ *
+ * 不要求 status==="running"——paused 下也可 skip（标记后 resume 时该 call 走 callCache
+ * replay）。但若 worker 已 terminate（runtime undefined），只标记不回发。
+ *
+ * @param run WorkflowRun 聚合根
+ * @param callId 要跳过的 call id（若不存在，仅注入到 calls Map 占位）
+ * @param deps LifecycleDeps（store 持久化）
+ */
+export async function skipNode(
+  run: WorkflowRun,
+  callId: number,
+  deps: LifecycleDeps,
+): Promise<void> {
+  const call = run.state.calls.get(callId);
+
+  if (call) {
+ // 已有 call：标记 done + 占位 result（绕过状态机守卫，显式 skip 语义）
+    call.status = "done";
+    call.result = SKIP_PLACEHOLDER;
+  }
+
+ // 同步 trace 节点
+  run.state.trace.update(callId, {
+    status: "completed",
+    result: SKIP_PLACEHOLDER,
+    completedAt: new Date().toISOString(),
+  });
+
+ // 若 worker 仍活着，回发 agent-result（解锁 worker pending await）
+  if (run.runtime) {
+    try {
+      run.runtime.worker.postMessage({
+        type: "agent-result",
+        callId,
+        result: SKIP_PLACEHOLDER,
+        cached: true,
+      });
+    } catch (err) {
+ // P1-8: worker 可能在 has 与 postMessage 间 exit——预期竞态，不恢复
+      void err;
+    }
+  }
+
+ // D-12 regression fix (round-2 #1)：skip 后同步 worker $BUDGET（占位 result 零 usage，
+ // 值不变，但保持 $BUDGET 与主线程一致）
+  postBudgetUpdate(run);
+
+  await deps.store.save(run);
+}

package/src/orchestration/script-lint.ts

@@ -0,0 +1,387 @@
+/**
+ * Workflow Extension — 静态 lint
+ *
+ * 在执行前捕获常见的 workflow 脚本 API 误用。纯函数，零副作用，零 IO。
+ *
+ * 设计：
+ * - lint 是编排层关注（非技术资源），归属 Engine 层。
+ * - **entry-point 检查**：脚本必须含 agent/parallel/pipeline 之一，否则视为 error。
+ * WorkflowScript.validate 直接委托 lintScript，故 entry-point 检查必须在此。
+ * - LintFinding/LintResult 类型规范的 canonical 源在本文件。
+ *
+ * 检查项：
+ * 1. 必须含 agent/parallel/pipeline 入口（error）
+ * 2. agent 选项中 outputSchema 当 key 用 → 应为 schema（error）
+ * 3. result.output / result.parsedOutput / result.content → agent 返回未包装值（error）
+ * 4. readFileSync/writeFileSync 传状态 → 脆弱（warning）
+ * 5. unlinkSync 清理状态 → 与 subprocess 文件读竞态（warning）
+ * 6. 顶层未 await 的异步 IIFE + 内部调 agent/parallel/pipeline → 子进程被提前 kill（error）
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §7（validate 语义）。
+ */
+
+/** Lint 检查发现项。 */
+export interface LintFinding {
+ /** error = 会导致运行时崩溃; warning = 可能的错误 */
+  severity: "error" | "warning";
+  line: number;
+  message: string;
+  suggestion: string;
+}
+
+/** Lint 检查结果。 */
+export interface LintResult {
+  valid: boolean;
+  findings: LintFinding[];
+}
+
+/** 必须命中其一——workflow 脚本不调用任何编排函数等于空跑。 */
+const ENTRY_POINT_PATTERNS = [/\bagent\s*\(/, /\bparallel\s*\(/, /\bpipeline\s*\(/] as const;
+
+/**
+ * 检查脚本是否含至少一个编排入口（agent/parallel/pipeline）。
+ * 无入口视为 error——空跑脚本无意义。
+ */
+function checkEntryPoint(source: string): LintFinding[] {
+  const hasEntryPoint = ENTRY_POINT_PATTERNS.some((p) => p.test(source));
+  if (hasEntryPoint) return [];
+  return [
+    {
+      severity: "error",
+      line: 0,
+      message: "Workflow script must call agent(), parallel(), or pipeline() at least once.",
+      suggestion: "Add at least one agent(), parallel(), or pipeline() invocation.",
+    },
+  ];
+}
+
+/**
+ * 检查单行 lint 问题，返回该行的发现项（可能为空）。
+ */
+function checkLine(lineText: string, lineNum: number): LintFinding[] {
+  const results: LintFinding[] = [];
+
+ // 跳过注释行
+  const trimmed = lineText.trim();
+  if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+    return results;
+  }
+
+ // result.output / result.parsedOutput / result.content
+  const resultAccessPatterns: Array<{ regex: RegExp; field: string }> = [
+    { regex: /\bresult\s*\.\s*output\b/, field: "output" },
+    { regex: /\bresult\s*\.\s*parsedOutput\b/, field: "parsedOutput" },
+    { regex: /\bresult\s*\.\s*content\b/, field: "content" },
+  ];
+  for (const p of resultAccessPatterns) {
+    if (p.regex.test(lineText)) {
+      results.push({
+        severity: "error",
+        line: lineNum,
+        message: `\`result.${p.field}\` does not exist. agent() returns the unwrapped value directly.`,
+        suggestion: "Use `const value = await agent(...)` and access `value` directly.",
+      });
+    }
+  }
+
+ // 文件传状态（readFileSync of STATE）
+  if (/readFileSync\(.*STATE.*\)|readFileSync\(.*state.*\.json/i.test(lineText)) {
+    results.push({
+      severity: "warning",
+      line: lineNum,
+      message: "Reading a state file between agent calls is fragile (subprocess file access).",
+      suggestion: "Use agent() with `schema` to get structured output directly, avoiding file I/O for state passing.",
+    });
+  }
+
+ // unlinkSync 清理状态
+  if (/unlinkSync.*state/i.test(lineText)) {
+    results.push({
+      severity: "warning",
+      line: lineNum,
+      message: "unlinkSync in finally may race with agent subprocess file reads.",
+      suggestion: "Avoid file-based state passing; use agent() `schema` for structured output.",
+    });
+  }
+
+  return results;
+}
+
+/**
+ * 找出 source 中所有 agent 调用跨度，检查错误的选项 key。
+ *
+ * agent 调用可能跨多行：
+ * agent({
+ * prompt: ...,
+ * outputSchema, ← error: 应为 schema
+ * })
+ *
+ * 定位 agent 调用边界，检查 outputSchema 是否作为 key（非 value 如 `schema: outputSchema`）。
+ */
+function checkAgentCalls(source: string): LintFinding[] {
+  const findings: LintFinding[] = [];
+  const lines = source.split("\n");
+
+  let inAgentCall = false;
+  let depth = 0;
+  let agentStartLine = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+ // 跳过注释
+    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+      continue;
+    }
+
+ // 检测 agent 调用开始
+    if (!inAgentCall && /\bagent\s*\(/.test(line)) {
+      inAgentCall = true;
+      depth = 0;
+      agentStartLine = i;
+ // 从 agent( 开始计括号
+      const afterAgent = line.replace(/^.*?\bagent\s*\(/, "(");
+      for (const ch of afterAgent) {
+        if (ch === "(" || ch === "{" || ch === "[") depth++;
+        if (ch === ")" || ch === "}" || ch === "]") depth--;
+      }
+      if (depth <= 0) {
+ // 单行 agent 调用
+        checkAgentCallOptions(lines, agentStartLine, i, findings);
+        inAgentCall = false;
+      }
+      continue;
+    }
+
+    if (inAgentCall) {
+      for (const ch of line) {
+        if (ch === "(" || ch === "{" || ch === "[") depth++;
+        if (ch === ")" || ch === "}" || ch === "]") depth--;
+      }
+      if (depth <= 0) {
+        checkAgentCallOptions(lines, agentStartLine, i, findings);
+        inAgentCall = false;
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * 检查 agent 调用内的错误选项 key。
+ * 只标记 outputSchema 作为 KEY（属性名）使用的情况，不标记作为 VALUE。
+ *
+ * Error: { outputSchema } ← 简写属性（outputSchema 是 key）
+ * Error: { outputSchema: ... } ← 显式 key
+ * OK: { schema: outputSchema } ← outputSchema 是 value，`schema` 是 key
+ * OK: const outputSchema = {} ← 变量声明（在 agent 调用外）
+ */
+function checkAgentCallOptions(
+  lines: string[],
+  startLine: number,
+  endLine: number,
+  findings: LintFinding[],
+): void {
+  for (let i = startLine; i <= endLine; i++) {
+    const line = lines[i];
+
+ // 跳过变量声明（const/let/var outputSchema = ...）
+    if (/\b(?:const|let|var)\s+outputSchema\b/.test(line)) {
+      continue;
+    }
+
+ // 匹配：outputSchema 作为对象 key（简写或显式）
+    if (/\boutputSchema\s*[,\}]/.test(line) || /\boutputSchema\s*:/.test(line)) {
+ // 排除：outputSchema 作为 value（在另一个 key 的冒号后）
+ // e.g. "schema: outputSchema," — outputSchema 前是冒号
+      const beforeOutput = line.substring(0, line.indexOf("outputSchema"));
+      if (/:\s*$/.test(beforeOutput)) {
+        continue; // outputSchema 是 value，不是 key
+      }
+
+      findings.push({
+        severity: "error",
+        line: i + 1,
+        message: "`outputSchema` is not a valid agent() option.",
+        suggestion: "Use `schema` instead of `outputSchema`.",
+      });
+    }
+  }
+}
+
+// ── 顶层未 await 的异步 IIFE 检测 ───────────────────────────
+
+/**
+ * 匹配未 await 的 async IIFE 起点（粗筛）。
+ *
+ * 形式：`(async function`、`(async ()`、`(async (args)` 后跟 `=>`
+ * 不匹配：`await (async ...`（lookbehind 排除）
+ */
+const BARE_ASYNC_IIFE_PATTERN = /(^|[;\n\s{}(])(?<!await\s)\(async\s+(?:function\b|\(\)|\([^)]*\)\s*=>)/g;
+
+/**
+ * 判断 IIFE 调用表达式是否被某个上下文「接住」（return/赋值/await 链等）。
+ *
+ * 返回 true 表示 IIFE 的 Promise 被接住（合法或可能合法）；
+ * false 表示 IIFE 是孤立语句表达式（fire-and-forget）。
+ *
+ * 判断方法：扫描 IIFE 起点 `(async` 前的非空白 token：
+ *   - 遇到 `=` `return` `await` `(` `[` `,` → 接住
+ *   - 遇到 `;` `{` `}` 或行首 → 孤立语句
+ *
+ * 例：
+ *   `const x = (async ...` → '=' 接住
+ *   `return (async ...` → 'return' 接住
+ *   `(async ...` 行首 → 孤立
+ *   `}; (async ...` → 孤立（前一个语句结束后新起一个）
+ */
+function isIIFEAwaited(source: string, iifeStart: number): boolean {
+  let i = iifeStart - 1;
+  while (i >= 0) {
+    const ch = source[i];
+    if (/\s/.test(ch)) {
+      i--;
+      continue;
+    }
+    // 当前字符是标识符字符 → 向前扫完整标识符
+    if (/[A-Za-z0-9_$]/.test(ch)) {
+      // return / await / yield / 变量名（如 `foo(async ...`）→ 接住
+      return true;
+    }
+    // 单字符操作符
+    if (ch === "=" || ch === "(" || ch === "[" || ch === "," || ch === "?" || ch === ":") {
+      return true;
+    }
+    if (ch === ";" || ch === "{" || ch === "}" || ch === ")") {
+      return false;
+    }
+    // 其他字符（如 `.` `+`），保守视为接住（避免误报）
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 检测未 await 的 async IIFE，且其内部调用了 agent/parallel/pipeline。
+ *
+ * 严重度分级：
+ * - **error**：IIFE 是孤立语句表达式（fire-and-forget）+ 内部调 agent。
+ *   这是 daily-news-impact 的 bug 模式——worker 外层 IIFE 不等内层就 post return，
+ *   主线程 transition done → releaseRuntime → controller.abort() → SIGKILL 子进程。
+ * - **warning**：IIFE 被 `=`/`return`/`(` 等接住（可能后续 await），但内部调 agent。
+ *   提醒作者确认 Promise 真的被 await，不阻断运行。
+ *
+ * 误报规避（不报）：
+ * - await 前缀的 IIFE（lookbehind 排除）
+ * - IIFE 内不含 agent/parallel/pipeline（stock-screening 这类纯 execSync 合法）
+ *
+ * 局限：纯正则 + 括号配对，无法做数据流分析。「赋值后稍后 await」「return 给外层 await」
+ * 都识别为「接住」（warning 而非 error），避免阻断合法写法。
+ */
+function checkBareAsyncIIFE(source: string): LintFinding[] {
+  if (!ENTRY_POINT_PATTERNS.some((p) => p.test(source))) return [];
+
+ // 用 matchAll 检查所有 IIFE（脚本可能有多个，每个都需独立判断）
+  const findings: LintFinding[] = [];
+  for (const match of source.matchAll(BARE_ASYNC_IIFE_PATTERN)) {
+    const iifeStart = match.index ?? 0;
+    const finding = analyzeIIFE(source, iifeStart);
+    if (finding) findings.push(finding);
+  }
+  return findings;
+}
+
+/**
+ * 分析单个 IIFE 起点是否触发 finding。
+ *
+ * 返回 LintFinding（error 或 warning）或 undefined（IIFE 内无 agent/无闭合）。
+ * 详见 checkBareAsyncIIFE 的 [HISTORICAL] 教训记录。
+ */
+function analyzeIIFE(source: string, iifeStart: number): LintFinding | undefined {
+  const iifeLine = source.slice(0, iifeStart).split("\n").length;
+
+  const firstBrace = source.indexOf("{", iifeStart);
+  if (firstBrace === -1) return undefined;
+
+  let depth = 0;
+  let iifeEnd = -1;
+  for (let i = firstBrace; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        iifeEnd = i;
+        break;
+      }
+    }
+  }
+  if (iifeEnd === -1) return undefined;
+
+  const iifeBody = source.slice(firstBrace, iifeEnd);
+  const hasAgentInside = ENTRY_POINT_PATTERNS.some((p) => p.test(iifeBody));
+  if (!hasAgentInside) return undefined;
+
+  const awaited = isIIFEAwaited(source, iifeStart);
+  if (awaited) {
+    return {
+      severity: "warning",
+      line: iifeLine,
+      message:
+        "Async IIFE wrapping agent() is assigned/returned but must be awaited. If the surrounding context does not await this Promise, the worker will post `return` early and kill in-flight agent() subprocesses.",
+      suggestion:
+        "Verify the surrounding code awaits this IIFE's Promise. When unsure, prefer top-level await directly (the worker already wraps your script in an async IIFE).",
+    };
+  }
+
+  return {
+    severity: "error",
+    line: iifeLine,
+    message:
+      "Top-level async IIFE is a fire-and-forget statement. The worker's outer IIFE will post `return` before agent() resolves, killing the subprocess via runtime abort.",
+    suggestion:
+      "Remove the IIFE wrapper and use top-level await directly (the worker already wraps your script in an async IIFE). Or `await` the IIFE: `await (async function main() { ... })();`.",
+  };
+}
+
+/**
+ * 静态检查 workflow 脚本合法性。
+ *
+ * @param source 脚本源码（原始文件内容）
+ * @returns LintResult（valid = 无 error 级 finding）
+ */
+export function lintScript(source: string): LintResult {
+  const lines = source.split("\n");
+  const findings: LintFinding[] = [];
+
+ // 入口检查（必须有 agent/parallel/pipeline 之一）
+  findings.push(...checkEntryPoint(source));
+
+ // 逐行检查（result.output、文件传状态等）
+  for (let i = 0; i < lines.length; i++) {
+    findings.push(...checkLine(lines[i], i + 1));
+  }
+
+  // agent 调用上下文检查（outputSchema 作为 key）
+  findings.push(...checkAgentCalls(source));
+
+ // [HISTORICAL] 顶层未 await 的异步 IIFE + 内部调 agent——子进程被提前 kill。
+ // 教训来源：daily-news-impact.js 用 (async function main(){...})();() 包裹整个脚本，
+ // worker 外层 IIFE 不等内层 IIFE 就 postMessage("return")，主线程 transition done
+ // → release runtime → controller.abort() → spawn 后 2ms SIGKILL 子进程。
+ // 诊断耗时 4 轮：先后误判为 model 故障 / 工具缺失 / turn-signal abort / ConcurrencyGate 异常，
+ // 最终靠 worker-host → handleReturn → release → abort 的调用栈定位。
+  findings.push(...checkBareAsyncIIFE(source));
+
+  // 按行号排序，稳定输出
+  findings.sort((a, b) => a.line - b.line);
+
+  return {
+    valid: !findings.some((f) => f.severity === "error"),
+    findings,
+  };
+}

package/src/orchestration/skill-discovery.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 os from "node:os";
+import * as path from "node:path";
+
+// ── 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: ~/.pi/agent/skills/<name>/
+ * 3. npm packages: ~/.pi/agent/npm/node_modules/<pkg>/skills/<name>/
+ * Returns the directory path if found, undefined otherwise.
+ */
+export function resolveSkillPath(skillName: string): string | undefined {
+  const candidates = [
+ // Project-level
+    path.resolve(process.cwd(), ".agents/skills", skillName),
+ // Global user skills
+    path.join(os.homedir(), ".pi/agent/skills", skillName),
+  ];
+
+ // npm package skills (cached)
+  const npmSkillsDir = path.join(os.homedir(), ".pi/agent/npm/node_modules");
+  for (const pkgSkillsBase of getNpmSkillCandidates(npmSkillsDir)) {
+    candidates.push(path.join(pkgSkillsBase, skillName));
+  }
+
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) {
+      return dir;
+    }
+  }
+
+  return undefined;
+}