wave-agent-sdk 1.0.9 → 1.1.0

package/dist/agent.d.ts

@@ -23,7 +23,9 @@ export declare class Agent {
     private messageQueue;
     private dispatchPromise;
     private isAborting;
+    private isDestroyed;
     private dispatchAborted;
+    private asyncWorkRegistry;
     private memoryRuleManager;
     private liveConfigManager;
     private taskManager;
@@ -122,6 +124,13 @@ export declare class Agent {
         }>;
         type?: "message" | "bang";
     }): boolean;
+    /**
+     * Terminal-lifecycle guard for public APIs. destroy() is terminal: after it
+     * returns, no new work may start on this agent. Silent drops hid misuse until
+     * a ghost async side effect surfaced later (issue #1808); throwing surfaces
+     * the contract violation immediately at the call site.
+     */
+    private assertNotDestroyed;
     /**
      * Unified dispatch trigger — checks state machine before processing.
      * Handles user messages, bang commands, and background task notifications
@@ -244,12 +253,6 @@ export declare class Agent {
      * Background the current foreground task
      */
     backgroundCurrentTask(): Promise<void>;
-    /**
-     * Trigger WorktreeRemove hook before agent destruction.
-     * Called from CLI exit dialog when user chooses to remove the worktree.
-     * Non-blocking: errors logged but don't prevent removal.
-     */
-    triggerWorktreeRemoveHook(worktreePath: string): Promise<void>;
     /** Destroy managers, clean up resources */
     destroy(): Promise<void>;
     /**

package/dist/agent.js

@@ -53,7 +53,8 @@ export class Agent {
     constructor(options) {
         this.bangManager = null;
         this.dispatchPromise = null; // Track current dispatch for teardown
-        this.isAborting = false; // Guard: prevents tryDispatch from firing during abortMessage
+        this.isAborting = false; // Transient guard: prevents tryDispatch from firing during abortMessage (reset when the abort completes)
+        this.isDestroyed = false; // Terminal guard: set in destroy(), never reset — no dispatch may ever start after destroy
         this.dispatchAborted = false; // Set on abort while a dispatch is running: suppress the .finally re-check so preserved notifications don't get dispatched after abort
         this.sessionStartTime = Date.now();
         const { logger, workdir, systemPrompt, stream = true } = options;
@@ -113,6 +114,7 @@ export class Agent {
         this.bangManager = this.container.get("BangManager");
         this.cronManager = this.container.get("CronManager");
         this.messageQueue = this.container.get("MessageQueue");
+        this.asyncWorkRegistry = this.container.get("AsyncWorkRegistry");
         // Wire up CWD change callback from AIManager to sync Agent's workdir
         this.aiManager.setOnCwdChange((newCwd) => {
             this.workdir = newCwd;
@@ -256,6 +258,17 @@ export class Agent {
         }
         return updated;
     }
+    /**
+     * Terminal-lifecycle guard for public APIs. destroy() is terminal: after it
+     * returns, no new work may start on this agent. Silent drops hid misuse until
+     * a ghost async side effect surfaced later (issue #1808); throwing surfaces
+     * the contract violation immediately at the call site.
+     */
+    assertNotDestroyed() {
+        if (this.isDestroyed) {
+            throw new Error("Agent destroyed");
+        }
+    }
     /**
      * Unified dispatch trigger — checks state machine before processing.
      * Handles user messages, bang commands, and background task notifications
@@ -263,6 +276,8 @@ export class Agent {
      * onLoadingChange(false), and onCommandRunningChange(false).
      */
     tryDispatch() {
+        if (this.isDestroyed)
+            return; // Terminal: agent destroyed, never dispatch again
         if (this.isAborting)
             return; // Suppress dispatch during abort to prevent queued notifications from being dispatched as a side-effect
         if (this.dispatchAborted)
@@ -274,7 +289,7 @@ export class Agent {
         if (this.aiManager.isLoading || this.isCommandRunning)
             return;
         this.messageQueue.transitionTo("dispatching");
-        this.dispatchPromise = this.processQueuedMessage()
+        this.dispatchPromise = this.asyncWorkRegistry.track(this.processQueuedMessage()
             .catch((error) => {
             this.logger?.error("Failed to process queued message:", error);
         })
@@ -285,7 +300,7 @@ export class Agent {
                 this.tryDispatch(); // Re-check after processing
             }
             this.dispatchAborted = false;
-        });
+        }));
     }
     /**
      * Process the next queued item when the agent becomes idle.
@@ -499,6 +514,7 @@ export class Agent {
     }
     /** Execute bash command (bang command) */
     async bang(command) {
+        this.assertNotDestroyed();
         // If the agent is busy, enqueue the bang command
         if (this.aiManager.isLoading || this.isCommandRunning) {
             this.messageQueue.enqueue({ type: "bang", content: command });
@@ -625,37 +641,14 @@ export class Agent {
         await this.foregroundTaskManager.backgroundCurrentTask();
         this.options.callbacks?.onBackgroundCurrentTask?.();
     }
-    /**
-     * Trigger WorktreeRemove hook before agent destruction.
-     * Called from CLI exit dialog when user chooses to remove the worktree.
-     * Non-blocking: errors logged but don't prevent removal.
-     */
-    async triggerWorktreeRemoveHook(worktreePath) {
-        if (!this.hookManager.hasHooks("WorktreeRemove")) {
-            return;
-        }
-        try {
-            const sessionId = this.messageManager.getSessionId();
-            const transcriptPath = this.messageManager.getTranscriptPath();
-            const hookResults = await this.hookManager.executeHooks("WorktreeRemove", {
-                event: "WorktreeRemove",
-                projectDir: this.workdir,
-                timestamp: new Date(),
-                sessionId,
-                transcriptPath,
-                cwd: this.workdir,
-                worktreePath,
-                env: Object.fromEntries(Object.entries(this.configurationService.getMergedEnv()).filter((e) => e[1] !== undefined)),
-            });
-            // Process results via messageManager (may not be visible during shutdown)
-            this.hookManager.processHookResults("WorktreeRemove", hookResults, this.messageManager);
-        }
-        catch (error) {
-            this.logger?.warn("WorktreeRemove hooks execution failed:", error);
-        }
-    }
     /** Destroy managers, clean up resources */
     async destroy() {
+        // Terminal guard: suppress any dispatch triggered during teardown (e.g. the
+        // onLoadingChange(false) fired by abortAIMessage() below, or the dispatch
+        // .finally re-check). Without this, leftover queued messages would be
+        // dispatched fire-and-forget and outlive the agent. Never reset: destroy()
+        // is terminal, no dispatch should ever start afterwards.
+        this.isDestroyed = true;
         // Log session_end event and shutdown telemetry
         await logOTelEvent("session_end", {
             duration: String(Math.round((Date.now() - this.sessionStartTime) / 1000)),
@@ -717,7 +710,13 @@ export class Agent {
         }
         // Cleanup remote settings polling
         remoteSettingsService.shutdown();
-        // Cleanup memory store
+        // Drain live async work (dispatch, background subagents, fork subagents):
+        // abort steps above make them settle; wait for them so no async side
+        // effect outlives the agent. Timeout fallback keeps destroy bounded.
+        const drained = await this.asyncWorkRegistry.drain();
+        if (!drained) {
+            this.logger?.error(`Async work did not drain: ${this.asyncWorkRegistry.size} live work item(s) remain after destroy`);
+        }
     }
     /**
      * Trigger the rewind UI callback
@@ -738,6 +737,7 @@ export class Agent {
      * @returns Promise that resolves to the AI's answer
      */
     async askBtw(question, abortSignal, onContent, onReasoning) {
+        this.assertNotDestroyed();
         const result = await this.aiManager.runBtwFork(question, abortSignal, onContent, onReasoning);
         return result.content ?? result.error ?? "No response received";
     }
@@ -760,6 +760,7 @@ export class Agent {
      * @returns Promise that resolves to the background task ID
      */
     async forkSubagent(prompt, options, abortSignal) {
+        this.assertNotDestroyed();
         return this.aiManager.runForkSubagent(prompt, options, abortSignal);
     }
     /**
@@ -789,6 +790,7 @@ export class Agent {
      * ```
      */
     async sendMessage(content, images) {
+        this.assertNotDestroyed();
         // If the agent is busy, enqueue the message — unless it's an immediate
         // slash command (e.g., /clear, /compact) that should execute
         // right away even while AI is processing

package/dist/builtin/index.d.ts

@@ -0,0 +1 @@
+export declare const BUILTIN_CONTENT: Record<string, string>;

package/dist/builtin/index.js

@@ -0,0 +1,20 @@
+import { artifactSkill } from "./skills/artifact.js";
+import { code_reviewSkill } from "./skills/code-review.js";
+import { deep_researchSkill } from "./skills/deep-research.js";
+import { initSkill } from "./skills/init.js";
+import { loopSkill } from "./skills/loop.js";
+import { simplifySkill } from "./skills/simplify.js";
+import { settingsSkills } from "./skills/settings.js";
+import { subagents } from "./subagents.js";
+import { sddPlugin } from "./plugins.js";
+export const BUILTIN_CONTENT = {
+    ...artifactSkill,
+    ...code_reviewSkill,
+    ...deep_researchSkill,
+    ...initSkill,
+    ...loopSkill,
+    ...simplifySkill,
+    ...settingsSkills,
+    ...subagents,
+    ...sddPlugin,
+};

package/dist/builtin/plugins.d.ts

@@ -0,0 +1 @@
+export declare const sddPlugin: Record<string, string>;

package/dist/builtin/plugins.js

@@ -0,0 +1,225 @@
+export const sddPlugin = {
+    "plugins/sdd/.wave-plugin/plugin.json": `{
+  "name": "sdd",
+  "description": "Spec-first workflow: specify skill, SessionStart guidance, and spec-count validation.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Wave Team"
+  }
+}
+`,
+    "plugins/sdd/hooks/hooks.json": `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \\"\${WAVE_PLUGIN_ROOT}/scripts/session-start.js\\""
+          }
+        ]
+      }
+    ]
+  }
+}
+`,
+    "plugins/sdd/scripts/session-start.js": `#!/usr/bin/env node
+// SessionStart hook for the sdd built-in plugin.
+// Emits the spec-first workflow guidance as additionalContext (JSON form),
+// resolving the absolute path to the plugin's spec-count validator so the
+// agent can run it from its bash tool (which does not carry WAVE_PLUGIN_ROOT).
+import path from "node:path";
+
+const root =
+  process.env.WAVE_PLUGIN_ROOT ||
+  path.dirname(new URL("..", import.meta.url).pathname);
+const specCount = \`node \${JSON.stringify(path.join(root, "scripts", "spec-count.js"))}\`;
+
+const guidance = [
+  "Spec-First Workflow（规格优先工作流）：",
+  "- 需求增加或变更时，优先更新 spec：先更新对应规格说明（新增用户故事、验收场景），待用户确认 spec 后再实现代码。spec 是功能设计的权威来源，不是 changelog。",
+  "- 边界模糊时也先写 spec 草稿请用户确认，不要直接改代码。",
+  "- 规格编写技能（specify）由 AI 自动触发：对话中涉及新需求或需求变更时主动创建或更新规格文件，不需要用户手动调用（不出现在斜杠命令列表中）。",
+  \`- 新增或修改 spec 后运行校验：\${specCount}（自动检测 docs/specs/，否则 specs/，否则退出）。\`,
+].join("\\n");
+
+// JSON form → parsed as hookSpecificOutput.additionalContext by the hook manager.
+console.log(
+  JSON.stringify({ hookSpecificOutput: { additionalContext: guidance } }),
+);
+`,
+    "plugins/sdd/scripts/spec-count.js": `#!/usr/bin/env node
+// Generic, self-contained spec validator. Counts user stories and acceptance
+// scenarios under the project's specs directory and warns on missing sections.
+// Detects the specs dir: prefers docs/specs/, else specs/, else exits gracefully.
+// No dependency on any project's VitePress/docs-site modules.
+import fs from "node:fs";
+import path from "node:path";
+
+function detectSpecsDir() {
+  for (const dir of ["docs/specs", "specs"]) {
+    const resolved = path.resolve(process.cwd(), dir);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+  return null;
+}
+
+function walk(dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(fullPath, out);
+    else if (entry.isFile() && entry.name.endsWith(".md")) out.push(fullPath);
+  }
+  return out;
+}
+
+function countUserStories(content) {
+  const m = content.match(/^### 用户故事[：:]/gm);
+  return m ? m.length : 0;
+}
+
+function countAcceptanceScenarios(content) {
+  const m = content.match(/^\\d+\\.\\s+\\*\\*假设\\*\\*/gm);
+  return m ? m.length : 0;
+}
+
+const specsDir = detectSpecsDir();
+if (!specsDir) {
+  console.log("未找到规格目录（docs/specs/ 或 specs/），跳过校验。");
+  process.exit(0);
+}
+
+const files = walk(specsDir).sort();
+const totals = { specs: 0, us: 0, ac: 0 };
+const warnings = [];
+
+// index.md is conventionally a directory listing page, not a spec — skip it.
+const specFiles = files.filter(
+  (fp) => path.basename(fp).toLowerCase() !== "index.md",
+);
+
+for (const fp of specFiles) {
+  const content = fs.readFileSync(fp, "utf-8");
+  const usCount = countUserStories(content);
+  const acCount = countAcceptanceScenarios(content);
+  const rel = path.relative(process.cwd(), fp);
+  totals.specs++;
+  totals.us += usCount;
+  totals.ac += acCount;
+  if (!content.match(/^## 用户场景与测试/m))
+    warnings.push(\`\${rel}: 缺少 "## 用户场景与测试" 章节\`);
+  if (usCount === 0)
+    warnings.push(\`\${rel}: 未找到用户故事（期望 \\\`### 用户故事：\\\`）\`);
+  if (acCount === 0)
+    warnings.push(
+      \`\${rel}: 未找到验收场景（期望 \\\`N. **假设** … **当** … **则** …\\\`）\`,
+    );
+  console.log(\`\${rel}  用户故事: \${usCount}  验收场景: \${acCount}\`);
+}
+
+console.log("---");
+console.log(
+  \`规格: \${totals.specs}  用户故事: \${totals.us}  验收场景: \${totals.ac}\`,
+);
+if (warnings.length) {
+  for (const w of warnings) console.warn(\`⚠ \${w}\`);
+  console.warn(\`⚠ \${warnings.length} 条模板警告——见上方。\`);
+}
+`,
+    "plugins/sdd/skills/specify/SKILL.md": `---
+name: specify
+description: 根据自然语言描述创建或更新功能规格说明，生成包含用户故事与验收场景的规格文件。
+user-invocable: false
+---
+
+## 用户输入
+
+\`\`\`text
+$ARGUMENTS
+\`\`\`
+
+## 流程
+
+本技能由 AI 在会话中自动触发（不占用手动斜杠命令）。触发时机：用户提出新的需求、修改需求或涉及功能边界时，若对应规格尚未创建或已过期，则主动创建或更新规格说明。$ARGUMENTS 通常为空——需求描述直接来自对话上下文，不要让用户重复。
+
+根据对话中的功能描述，执行以下步骤：
+
+1. **确定规格文件路径**：
+   - **确定规格根目录**：优先复用项目中已有的规格目录——若 \`docs/specs/\` 存在则用之，否则若 \`specs/\` 存在则用之，否则默认 \`specs/\`（并在完成报告中说明所选目录，便于用户纠正）。
+   - **选择分组**：若规格目录下已有分组子目录，沿用其既有分组约定；否则默认扁平结构（直接放在规格根目录下）。
+   - 根据功能描述生成 2-4 个词的 slug（小写、连字符、保留缩写词），与组内已有文件名不冲突
+   - 规格文件路径：\`<规格根目录>/<分组>/<slug>.md\`（无分组时为 \`<规格根目录>/<slug>.md\`）
+
+2. **加载模板** \`\${WAVE_SKILL_DIR}/templates/spec-template.md\`，了解必需章节。
+
+3. **编写规格说明**：
+   - 解析用户描述，提取关键概念：角色、操作、数据、约束
+   - 对于不明确的部分，根据上下文和行业标准做出合理推断
+   - 仅在关键决策处标记 \`[待澄清：具体问题]\`（最多 3 处）
+   - 填写 frontmatter（\`name\` 为功能中文名、\`description\` 为一句话简述、\`order\` 为控制组内排序的数字）
+   - 填写「用户场景与测试」章节，包含按优先级排序的用户故事（P1、P2、P3...），每个故事以「作为…，我希望…，以便…」描述，附 \`**为什么是这个优先级**\` 与 \`**独立测试**\`（不适用的可省略）
+   - 为每个用户故事编写可测试的验收场景（**假设** … **当** … **则** …）
+   - 写入规格文件，替换所有占位符
+
+4. **如果存在 \`[待澄清]\` 标记**（最多 3 处）：
+   - 将每个标记作为问题展示，附带建议答案
+   - 等待用户回复后更新规格文件
+
+5. 报告完成，输出规格文件路径。
+
+## 指南
+
+- 关注用户**需要什麼**和**为什么**，而非如何实现
+- 不包含实现细节（不涉及技术栈、API、代码结构）
+- 每个验收场景必须可测试、无歧义
+- 删除不适用的可选章节（不要留 "N/A"）
+`,
+    "plugins/sdd/skills/specify/templates/spec-template.md": `---
+name: "[功能名称]"
+description: "[一句话简短描述]"
+order: [数字，控制组内排序]
+---
+
+# 功能规格说明：[功能名称]
+
+**创建日期**：[日期]
+
+## 用户场景与测试 *（必填）*
+
+### 用户故事：[简要标题]（优先级：P1）
+
+作为[角色]，我希望[操作]，以便[价值/目的]。
+
+**为什么是这个优先级**：[解释其价值以及为何具有此优先级]
+
+**独立测试**：[描述如何独立测试——例如，"可以通过 [具体操作] 进行完整测试，并交付 [具体价值]"]
+
+**验收场景**：
+
+1. **假设** [初始状态]，**当** [操作]，**则** [预期结果]
+2. **假设** [初始状态]，**当** [操作]，**则** [预期结果]
+
+---
+
+### 用户故事：[简要标题]（优先级：P2）
+
+作为[角色]，我希望[操作]，以便[价值/目的]。
+
+**为什么是这个优先级**：[解释其价值以及为何具有此优先级]
+
+**独立测试**：[描述如何独立测试]
+
+**验收场景**：
+
+1. **假设** [初始状态]，**当** [操作]，**则** [预期结果]
+
+---
+
+[根据需要添加更多用户故事，每个都分配优先级]
+
+### 边界情况
+
+- **[问题？]** [答案/处理方式]
+- **[问题？]** [答案/处理方式]
+`,
+};

package/dist/builtin/skills/artifact.d.ts

@@ -0,0 +1 @@
+export declare const artifactSkill: Record<string, string>;

package/dist/builtin/skills/artifact.js

@@ -0,0 +1,18 @@
+import { ARTIFACT_TOOL_NAME } from "../../constants/tools.js";
+export const artifactSkill = {
+    "skills/artifact/SKILL.md": `---
+name: artifact
+description: Publish a local HTML or Markdown file as a shareable web page
+disable-model-invocation: true
+---
+
+# Artifact: Publish a File as a Shareable Web Page
+
+Publish a local \`.html\` or \`.md\` file as a default-private, shareable web page.
+
+- If a file path was provided ($ARGUMENTS / $1), use it directly as the \`file_path\`.
+- Otherwise, infer which file to publish from the conversation context; if it is not clear, ask the user which file to publish.
+
+Call the \`${ARTIFACT_TOOL_NAME}\` tool with the resolved \`file_path\` (and \`favicon\` if relevant), then report the resulting URL to the user.
+`,
+};

package/dist/builtin/skills/code-review.d.ts

@@ -0,0 +1 @@
+export declare const code_reviewSkill: Record<string, string>;

package/{builtin/skills/code-review/SKILL.md → dist/builtin/skills/code-review.js}

@@ -1,7 +1,9 @@
----
+import { AGENT_TOOL_NAME, BASH_TOOL_NAME, GLOB_TOOL_NAME, GREP_TOOL_NAME, READ_TOOL_NAME, } from "../../constants/tools.js";
+export const code_reviewSkill = {
+    "skills/code-review/SKILL.md": `---
 name: code-review
 description: Review the current diff for correctness bugs and reuse/simplification/efficiency cleanups at the given effort level (low/medium: fewer, high-confidence findings; high/max: broader coverage, may include lower-confidence findings)
-allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(git show:*), Bash(git blame:*), Bash(git remote:*), Bash(command -v:*), Bash(gh pr comment:*), Bash(gh pr view:*), Bash(glab mr note:*), Bash(glab mr view:*), Read, Glob, Grep, Agent
+allowed-tools: ${BASH_TOOL_NAME}(git diff:*), ${BASH_TOOL_NAME}(git status:*), ${BASH_TOOL_NAME}(git log:*), ${BASH_TOOL_NAME}(git show:*), ${BASH_TOOL_NAME}(git blame:*), ${BASH_TOOL_NAME}(git remote:*), ${BASH_TOOL_NAME}(command -v:*), ${BASH_TOOL_NAME}(gh pr comment:*), ${BASH_TOOL_NAME}(gh pr view:*), ${BASH_TOOL_NAME}(glab mr note:*), ${BASH_TOOL_NAME}(glab mr view:*), ${READ_TOOL_NAME}, ${GLOB_TOOL_NAME}, ${GREP_TOOL_NAME}, ${AGENT_TOOL_NAME}
 disable-model-invocation: true
 ---
 
@@ -13,25 +15,25 @@ Review the current branch's changes for correctness bugs and quality issues.
 
 First, collect the diff and metadata:
 
-```
+\`\`\`
 GIT STATUS:
-!`git status`
+!\`git status\`
 
 FILES MODIFIED:
-!`git diff --name-only $(git merge-base HEAD main)...HEAD 2>/dev/null || git diff --name-only HEAD~1...HEAD`
+!\`git diff --name-only $(git merge-base HEAD main)...HEAD 2>/dev/null || git diff --name-only HEAD~1...HEAD\`
 
 COMMITS:
-!`git log --no-decorate $(git merge-base HEAD main 2>/dev/null || echo HEAD~1)...HEAD`
+!\`git log --no-decorate $(git merge-base HEAD main 2>/dev/null || echo HEAD~1)...HEAD\`
 
 DIFF CONTENT:
-!`git diff $(git merge-base HEAD main 2>/dev/null || echo HEAD~1)...HEAD`
-```
+!\`git diff $(git merge-base HEAD main 2>/dev/null || echo HEAD~1)...HEAD\`
+\`\`\`
 
 If there are no changes, stop and tell the user.
 
 ## Phase 2: Determine Effort Level
 
-Parse `$ARGUMENTS` for an effort level:
+Parse \`$ARGUMENTS\` for an effort level:
 - **low**: Launch 2 agents, confidence threshold 90 (only near-certain findings)
 - **medium** (default): Launch 3 agents, confidence threshold 80
 - **high**: Launch 4 agents, confidence threshold 70
@@ -39,7 +41,7 @@ Parse `$ARGUMENTS` for an effort level:
 
 ## Phase 3: Launch Review Agents in Parallel
 
-Use the Agent tool to launch all agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+Use the ${AGENT_TOOL_NAME} tool to launch all agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
 
 ### Agent 1: Bug Scanner (all effort levels)
 
@@ -63,7 +65,7 @@ Review the changes for efficiency: unnecessary work, missed concurrency, hot-pat
 
 ## Phase 4: Confidence Scoring
 
-For each issue found in Phase 3, launch a parallel Agent to independently score the issue. The scoring agent receives the PR diff, the issue description, and the list of AGENTS.md files (if any). It returns a confidence score from 0-100.
+For each issue found in Phase 3, launch a parallel ${AGENT_TOOL_NAME} to independently score the issue. The scoring agent receives the PR diff, the issue description, and the list of AGENTS.md files (if any). It returns a confidence score from 0-100.
 
 Give the scoring agent this rubric verbatim:
 
@@ -79,18 +81,18 @@ Give the scoring agent this rubric verbatim:
 2. If no issues remain, say so and stop — do not post anything.
 3. Otherwise, detect the platform and CLI availability:
 
-```
+\`\`\`
 REMOTE URL:
-!`git remote get-url origin 2>/dev/null || echo "no-remote"`
+!\`git remote get-url origin 2>/dev/null || echo "no-remote"\`
 
 GH CLI:
-!`command -v gh 2>/dev/null || echo "not-installed"`
+!\`command -v gh 2>/dev/null || echo "not-installed"\`
 
 GLAB CLI:
-!`command -v glab 2>/dev/null || echo "not-installed"`
-```
+!\`command -v glab 2>/dev/null || echo "not-installed"\`
+\`\`\`
 
-4. **Post as comment** (preferred): If the remote URL contains `github` and `gh` is installed, check if a PR exists for the current branch (`gh pr view --json number`), then post the review as a comment: `gh pr comment --body "<review content>"`. If the remote URL contains `gitlab` and `glab` is installed, check if an MR exists for the current branch (`glab mr view`), then post the review as a note: `glab mr note --message "<review content>"`.
+4. **Post as comment** (preferred): If the remote URL contains \`github\` and \`gh\` is installed, check if a PR exists for the current branch (\`gh pr view --json number\`), then post the review as a comment: \`gh pr comment --body "<review content>"\`. If the remote URL contains \`gitlab\` and \`glab\` is installed, check if an MR exists for the current branch (\`glab mr view\`), then post the review as a note: \`glab mr note --message "<review content>"\`.
 5. **Output directly** (fallback): If no CLI is installed, no PR/MR exists, or the platform is unrecognized, output the findings directly instead.
 
 Whether posting or outputting, use this format:
@@ -103,11 +105,11 @@ Found N issues:
 
 1. <brief description of bug> (AGENTS.md says "<...>")
 
-   `<file>:<line range>`
+   \`<file>:<line range>\`
 
 2. <brief description of bug> (bug due to <file and code snippet>)
 
-   `<file>:<line range>`
+   \`<file>:<line range>\`
 
 ---
 
@@ -135,3 +137,5 @@ Examples of false positives to exclude:
 ## Input
 
 $ARGUMENTS
+`,
+};

package/dist/builtin/skills/deep-research.d.ts

@@ -0,0 +1 @@
+export declare const deep_researchSkill: Record<string, string>;

package/{builtin/skills/deep-research/SKILL.md → dist/builtin/skills/deep-research.js}

@@ -1,4 +1,6 @@
----
+import { WORKFLOW_TOOL_NAME } from "../../constants/tools.js";
+export const deep_researchSkill = {
+    "skills/deep-research/SKILL.md": `---
 name: deep-research
 description: Deep research harness — fan-out web searches, fetch sources, adversarially verify claims, synthesize a cited report
 context: fork
@@ -8,9 +10,9 @@ Deep research harness — fan-out web searches, fetch sources, adversarially ver
 
 BEFORE invoking the workflow, check if the question is specific enough to research directly — if underspecified (e.g., "what car to buy" without budget/use-case/region), ask 2-3 clarifying questions to narrow scope. Then pass the refined question as args, weaving the answers in.
 
-1. Call the Workflow tool with the following script, passing the user's question as the `args` parameter:
+1. Call the ${WORKFLOW_TOOL_NAME} tool with the following script, passing the user's question as the \`args\` parameter:
 
-```
+\`\`\`
 export const meta = {
   name: 'deep-research',
   description: 'Deep research harness — fan-out web searches, fetch sources, adversarially verify claims, synthesize a cited report',
@@ -27,12 +29,12 @@ const question = args
 
 phase('Scope')
 const angles = await agent(
-  'Decompose this research question into exactly 5 distinct search angles that together provide comprehensive coverage: "' + question + '"\n\nReturn a JSON array of 5 short angle labels. Example: ["overview and background", "technical details and specifications", "recent developments and news", "alternative perspectives and criticisms", "practical implications and case studies"]',
+  'Decompose this research question into exactly 5 distinct search angles that together provide comprehensive coverage: "' + question + '"\\n\\nReturn a JSON array of 5 short angle labels. Example: ["overview and background", "technical details and specifications", "recent developments and news", "alternative perspectives and criticisms", "practical implications and case studies"]',
   { label: 'scope', phase: 'Scope' }
 )
 const angleList = (() => {
   try {
-    const match = String(angles).match(/\[[\s\S]*\]/)
+    const match = String(angles).match(/\\[[\\s\\S]*\\]/)
     return match ? JSON.parse(match[0]) : ['overview', 'technical details', 'recent developments', 'alternative perspectives', 'practical implications']
   } catch { return ['overview', 'technical details', 'recent developments', 'alternative perspectives', 'practical implications'] }
 })()
@@ -48,8 +50,8 @@ const searches = await parallel(angleList.map(angle => () =>
 phase('Fetch')
 const allUrls = searches.filter(Boolean).flatMap(r => {
   if (typeof r !== 'string') return []
-  return r.split('\n').filter(l => l.trim().startsWith('http') || l.trim().startsWith('- http'))
-}).map(u => u.replace(/^-\s*/, '').trim())
+  return r.split('\\n').filter(l => l.trim().startsWith('http') || l.trim().startsWith('- http'))
+}).map(u => u.replace(/^-\\s*/, '').trim())
 const sources = [...new Set(allUrls)].slice(0, 15)
 const fetched = await pipeline(sources.length > 0 ? sources : ['No specific URLs found — synthesize from search results'], source =>
   agent('Fetch and extract key falsifiable claims from: ' + source + '. For each claim, note the source URL and whether it is supported by evidence. Return each claim as a separate bullet.', {
@@ -59,12 +61,12 @@ const fetched = await pipeline(sources.length > 0 ? sources : ['No specific URLs
 )
 
 phase('Verify')
-const claimsText = fetched.filter(Boolean).join('\n')
-const claimLines = claimsText.split('\n').filter(l => l.trim().startsWith('-') || l.trim().startsWith('•') || l.trim().startsWith('*'))
+const claimsText = fetched.filter(Boolean).join('\\n')
+const claimLines = claimsText.split('\\n').filter(l => l.trim().startsWith('-') || l.trim().startsWith('•') || l.trim().startsWith('*'))
 const claimsToVerify = claimLines.length > 0 ? claimLines : [claimsText]
 const verified = await parallel(claimsToVerify.slice(0, 12).map((claim, i) => () =>
   parallel([0, 1, 2].map(voteIdx => () =>
-    agent('You are a skeptical fact-checker (vote ' + (voteIdx + 1) + '/3). For the following claim, search for evidence that REFUTES it. Claim: "' + claim + '"\n\nIf you find strong evidence against it, respond REFUTED with the counter-evidence. If the claim holds up, respond CONFIRMED. Be rigorous — only refute if you find direct contradictory evidence.', {
+    agent('You are a skeptical fact-checker (vote ' + (voteIdx + 1) + '/3). For the following claim, search for evidence that REFUTES it. Claim: "' + claim + '"\\n\\nIf you find strong evidence against it, respond REFUTED with the counter-evidence. If the claim holds up, respond CONFIRMED. Be rigorous — only refute if you find direct contradictory evidence.', {
       label: 'verify:claim' + i + ':vote' + voteIdx,
       phase: 'Verify'
     })
@@ -77,14 +79,16 @@ const verifiedClaims = verified.flatMap((votes, i) => {
 })
 
 phase('Synthesize')
-const confirmedClaims = verifiedClaims.filter(c => c.status === 'confirmed').map(c => c.claim).join('\n')
-const contestedClaims = verifiedClaims.filter(c => c.status === 'contested').map(c => c.claim + ' (contested)').join('\n')
+const confirmedClaims = verifiedClaims.filter(c => c.status === 'confirmed').map(c => c.claim).join('\\n')
+const contestedClaims = verifiedClaims.filter(c => c.status === 'contested').map(c => c.claim + ' (contested)').join('\\n')
 const report = await agent(
-  'Synthesize a comprehensive cited report answering: "' + question + '".\n\nConfirmed claims:\n' + (confirmedClaims || 'None') + '\n\nContested claims (include with caveat):\n' + (contestedClaims || 'None') + '\n\nMerge semantic duplicates. Rank findings by confidence level. Include: 1) Executive summary 2) Key findings with citations, ranked by confidence 3) Contested findings (with caveats) 4) Areas of uncertainty 5) Conclusion.',
+  'Synthesize a comprehensive cited report answering: "' + question + '".\\n\\nConfirmed claims:\\n' + (confirmedClaims || 'None') + '\\n\\nContested claims (include with caveat):\\n' + (contestedClaims || 'None') + '\\n\\nMerge semantic duplicates. Rank findings by confidence level. Include: 1) Executive summary 2) Key findings with citations, ranked by confidence 3) Contested findings (with caveats) 4) Areas of uncertainty 5) Conclusion.',
   { label: 'synthesize', phase: 'Synthesize' }
 )
 
 return report
-```
+\`\`\`
 
 2. After the workflow starts, inform the user that deep research is running and they can use /workflows to monitor progress.
+`,
+};