wave-agent-sdk 0.19.8 → 1.0.0

package/builtin/plugins/sdd/.wave-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "sdd",
+  "description": "Spec-first workflow: specify skill, SessionStart guidance, and spec-count validation.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Wave Team"
+  }
+}

package/builtin/plugins/sdd/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${WAVE_PLUGIN_ROOT}/scripts/session-start.js\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/builtin/plugins/sdd/scripts/session-start.js

@@ -0,0 +1,24 @@
+#!/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 } }),
+);

package/builtin/plugins/sdd/scripts/spec-count.js

@@ -0,0 +1,77 @@
+#!/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} 条模板警告——见上方。`);
+}

package/builtin/plugins/sdd/skills/specify/SKILL.md

@@ -0,0 +1,47 @@
+---
+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"）

package/builtin/plugins/sdd/skills/specify/templates/spec-template.md

@@ -0,0 +1,47 @@
+---
+name: "[功能名称]"
+description: "[一句话简短描述]"
+order: [数字，控制组内排序]
+---
+
+# 功能规格说明：[功能名称]
+
+**创建日期**：[日期]
+
+## 用户场景与测试 *（必填）*
+
+### 用户故事：[简要标题]（优先级：P1）
+
+作为[角色]，我希望[操作]，以便[价值/目的]。
+
+**为什么是这个优先级**：[解释其价值以及为何具有此优先级]
+
+**独立测试**：[描述如何独立测试——例如，"可以通过 [具体操作] 进行完整测试，并交付 [具体价值]"]
+
+**验收场景**：
+
+1. **假设** [初始状态]，**当** [操作]，**则** [预期结果]
+2. **假设** [初始状态]，**当** [操作]，**则** [预期结果]
+
+---
+
+### 用户故事：[简要标题]（优先级：P2）
+
+作为[角色]，我希望[操作]，以便[价值/目的]。
+
+**为什么是这个优先级**：[解释其价值以及为何具有此优先级]
+
+**独立测试**：[描述如何独立测试]
+
+**验收场景**：
+
+1. **假设** [初始状态]，**当** [操作]，**则** [预期结果]
+
+---
+
+[根据需要添加更多用户故事，每个都分配优先级]
+
+### 边界情况
+
+- **[问题？]** [答案/处理方式]
+- **[问题？]** [答案/处理方式]

package/builtin/skills/settings/ENV.md

@@ -17,13 +17,13 @@ Environment variables are configured in the `env` field of `settings.json`. It i
 
 ## Supported `WAVE_*` Environment Variables
 
-Wave uses several environment variables to control its core functionality.
+Wave uses several environment variables to control its core functionality. Variables marked **OS env only** are read from the OS environment (or constructor / stdio `initialize` params) and are **NOT** read from settings.json `env` — set them in your shell, not in the `env` field.
 
 | Variable | Description | Default |
 | :--- | :--- | :--- |
 | `WAVE_API_KEY` | API key for the AI gateway. | - |
 | `WAVE_BASE_URL` | Base URL for the AI gateway. | - |
-| `WAVE_SERVER_URL` | Server URL for SSO authentication. | `https://codechat.codewave.163.com` |
+| `WAVE_SERVER_URL` | Server URL for SSO authentication. **OS env only** — set via OS env or `options.serverUrl`; not read from settings.json `env` (avoids a startup 401 race). | `https://codechat.codewave.163.com` |
 | `WAVE_CUSTOM_HEADERS` | Custom HTTP headers for the AI gateway. Newline-separated `Key: Value` pairs (e.g., `"X-Foo: bar\nAuthorization: Bearer xxx"`). | - |
 | `WAVE_MODEL` | The primary AI model to use for the agent. | `gemini-3-flash` |
 | `WAVE_FAST_MODEL` | The fast AI model to use for quick tasks. | `gemini-2.5-flash` |
@@ -32,23 +32,29 @@ Wave uses several environment variables to control its core functionality.
 | `WAVE_DISABLE_AUTO_MEMORY` | Set to `1` or `true` to disable the auto-memory feature. | `false` |
 | `WAVE_AUTO_MEMORY_FREQUENCY` | Auto memory update frequency. `1` = every turn, `2` = every 2 turns, etc. | `1` |
 | `WAVE_TASK_LIST_ID` | Explicitly set the task list ID for the session. | (Session ID) |
-| `WAVE_PLUGIN_GIT_TIMEOUT_MS` | Timeout in milliseconds for git operations when installing plugins. | `300000` |
+| `WAVE_PLUGIN_GIT_TIMEOUT_MS` | Timeout in milliseconds for git operations when installing plugins. **OS env only** (infrastructure). | `300000` |
 
 ## Configuration Scopes
 
-Environment variables can be set in different scopes, with the following precedence (highest to lowest):
+Environment variables can be set in different scopes. Wave merges scopes from lowest to highest priority and stores the result in the agent's **per-session environment snapshot**. The snapshot takes priority over OS environment variables but is **NOT written to `process.env`** — this keeps multiple sessions in one `wave --stdio` process from polluting each other.
+
+Precedence (highest to lowest):
 
 1.  **Local Scope**: `.wave/settings.local.json` (Local overrides, ignored by git)
 2.  **Project Scope**: `.wave/settings.json` (Project-specific settings, shared via git)
 3.  **User Scope**: `~/.wave/settings.json` (Global settings for all projects)
-4.  **System Environment**: Variables set in your shell (e.g., `export WAVE_API_KEY=...`)
+4.  **System Environment**: Variables set in your shell (e.g., `export WAVE_API_KEY=...`). Used as a fallback when a key is absent from the settings snapshot.
+
+> Settings `env` shadows (does not mutate) OS env: a key set in both settings.json `env` and the OS environment resolves to the settings value for that session, while the OS value remains untouched and visible to unrelated processes.
 
 ## Custom Environment Variables
 
-You can also define custom environment variables in the `env` field. These variables will be available to:
+You can also define custom environment variables in the `env` field. These variables are stored in the session's environment snapshot and will be available to:
+
+- **Hooks**: Any shell command executed as a hook will have these variables in its environment (merged on top of OS env).
+- **Tools**: Tools like `Bash` will have access to these variables (merged on top of OS env).
 
-- **Hooks**: Any shell command executed as a hook will have these variables in its environment.
-- **Tools**: Tools like `Bash` will have access to these variables.
+In `wave --stdio` mode one process hosts multiple sessions; each session keeps its own snapshot, so sessions with different `env` do not pollute each other (no "last session wins").
 
 Example:
 ```json
@@ -62,7 +68,7 @@ Example:
 
 ## Live Reload
 
-Environment variables configured in `settings.json` support **live reload**. When you modify the `env` field in any `settings.json` file (user, project, or local scope), the changes take effect immediately without requiring a Wave session restart.
+Environment variables configured in `settings.json` support **live reload**. When you modify the `env` field in any `settings.json` file (user, project, or local scope), the changes take effect immediately without requiring a Wave session restart — the session's environment snapshot is refreshed and subsequent resolve calls / subprocess spawns use the new values.
 
 ## Best Practices
 

package/builtin/skills/settings/HOOKS.md

@@ -13,7 +13,7 @@ Wave supports the following hook events:
 - `Stop`: Triggered when Wave finishes its response cycle (no more tool calls).
 - `SubagentStop`: Triggered when a subagent finishes its response cycle.
 - `WorktreeCreate`: Triggered when a new worktree is created.
-- `WorktreeRemove`: Triggered when a worktree is removed (e.g., via ExitWorktree with `action: "remove"`). Non-blocking. The hook receives `worktree_path` in the JSON input. Useful for cleanup tasks (e.g., `docker compose -p $(basename "$worktree_path") down`) after worktree deletion.
+- `WorktreeRemove`: Triggered before a worktree is removed (e.g., via ExitWorktree with `action: "remove"`). Non-blocking. Fires **before** the worktree directory is deleted so hooks can still read files inside it. The hook receives `worktree_path` in the JSON input. Useful for cleanup tasks (e.g., `docker compose -p $(basename "$worktree_path") down`).
 - `CwdChanged`: Triggered when the working directory changes (e.g., entering/exiting a worktree). Non-blocking.
 - `SessionStart`: Triggered during session initialization. Hooks can inject `additionalContext` and `initialUserMessage` via stdout.
 - `SessionEnd`: Triggered during agent destruction (fire-and-forget, non-blocking). Useful for cleanup, resource teardown, and analytics.
@@ -79,7 +79,7 @@ Wave provides detailed context to hook processes via `stdin` as a JSON object. T
 - `user_prompt`: (UserPromptSubmit) The text submitted by the user.
 - `subagent_type`: (If executed by a subagent) The type of the subagent.
 - `name`: (WorktreeCreate) The name of the new worktree.
-- `worktree_path`: (WorktreeRemove) The absolute path to the removed worktree.
+- `worktree_path`: (WorktreeRemove) The absolute path of the worktree about to be removed. Derive the worktree name with `basename "$worktree_path"`.
 - `old_cwd`: (CwdChanged) The previous working directory.
 - `new_cwd`: (CwdChanged) The new working directory.
 - `compact_instructions`: (PreCompact) Custom instructions for the compaction, if any.
@@ -165,6 +165,31 @@ SessionEnd hooks receive `end_source` in the JSON input indicating how the sessi
 }
 ```
 
+## WorktreeRemove Hooks
+
+`WorktreeRemove` hooks fire **before** the worktree directory is deleted, so they can still read files inside it. They are non-blocking (Notification type): the hook never replaces `git worktree remove` itself. Useful for cleaning up external resources that were provisioned for the worktree (databases, containers, etc.).
+
+### Input
+WorktreeRemove hooks receive `worktree_path` in the JSON input (alongside the common fields `session_id`, `transcript_path`, `cwd`, `hook_event_name`). The worktree name can be derived via `basename "$worktree_path"`.
+
+### Example Configuration
+```json
+{
+  "hooks": {
+    "WorktreeRemove": [
+      {
+        "hooks": [
+          {
+            "command": "worktree_path=$(jq -r '.worktree_path') && docker compose -p \"$(basename \"$worktree_path\")\" down || true",
+            "description": "Tear down the worktree's docker compose project before removal"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Live Reload
 
 Hook configurations support **live reload**. When you modify hooks in `settings.json`, the changes take effect immediately without restarting Wave.

package/dist/agent.d.ts

@@ -24,6 +24,7 @@ export declare class Agent {
     private reversionManager;
     private messageQueue;
     private dispatchPromise;
+    private isAborting;
     private memoryRuleManager;
     private liveConfigManager;
     private taskManager;

package/dist/agent.js

@@ -14,7 +14,10 @@ import { remoteSettingsService } from "./services/remoteSettingsService.js";
 export class Agent {
     // Dynamic configuration getter methods
     getGatewayConfig() {
-        return this.configurationService.resolveGatewayConfig();
+        return {
+            ...this.configurationService.resolveGatewayConfig(),
+            sessionId: this.messageManager.getSessionId(),
+        };
     }
     getModelConfig() {
         return this.configurationService.resolveModelConfig(undefined, undefined, undefined, this.getPermissionMode());
@@ -52,6 +55,7 @@ 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.sessionStartTime = Date.now();
         const { logger, workdir, systemPrompt, stream = true } = options;
         // Set working directory early as we need it for loading configuration
@@ -278,6 +282,8 @@ export class Agent {
      * onLoadingChange(false), and onCommandRunningChange(false).
      */
     tryDispatch() {
+        if (this.isAborting)
+            return; // Suppress dispatch during abort to prevent queued notifications from being dispatched as a side-effect
         if (this.messageQueue.state !== "idle")
             return;
         if (!this.messageQueue.hasPending())
@@ -632,17 +638,25 @@ export class Agent {
     }
     /** Unified interrupt method, interrupts both AI messages and command execution */
     abortMessage() {
-        if (this.aiManager.isLoading || this.isCommandRunning) {
-            // Clear user-facing queue items first to prevent processQueuedMessage
-            // from dequeuing when abortAIMessage triggers onLoadingChange(false).
-            // Notifications are preserved so background task results aren't lost.
-            this.messageQueue.clear();
-            this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
+        // Guard: prevent tryDispatch (triggered by abortAIMessage → setIsLoading(false))
+        // from dispatching preserved notifications as a new AI turn during the abort.
+        this.isAborting = true;
+        try {
+            if (this.aiManager.isLoading || this.isCommandRunning) {
+                // Clear user-facing queue items first to prevent processQueuedMessage
+                // from dequeuing when abortAIMessage triggers onLoadingChange(false).
+                // Notifications are preserved so background task results aren't lost.
+                this.messageQueue.clear();
+                this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
+            }
+            this.messageQueue.transitionTo("idle"); // Reset state on abort
+            this.abortAIMessage(); // This will abort tools including Agent tool (subagents)
+            this.abortBashCommand();
+            this.abortSlashCommand();
+        }
+        finally {
+            this.isAborting = false;
         }
-        this.messageQueue.transitionTo("idle"); // Reset state on abort
-        this.abortAIMessage(); // This will abort tools including Agent tool (subagents)
-        this.abortBashCommand();
-        this.abortSlashCommand();
     }
     /** Interrupt bash command execution */
     abortBashCommand() {
@@ -691,7 +705,7 @@ export class Agent {
                 transcriptPath,
                 cwd: this.workdir,
                 worktreePath,
-                env: Object.fromEntries(Object.entries(process.env).filter((e) => e[1] !== undefined)),
+                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);

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 export * from "./tools/buildTool.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export * from "./utils/tokenCalculation.js";
 export * from "./utils/gitUtils.js";
 export * from "./utils/nameGenerator.js";
 export * from "./utils/worktreeSession.js";
+export * from "./utils/worktreeUtils.js";
 export { loadMergedWaveConfig } from "./services/configurationService.js";
 export * from "./types/index.js";
 // Export tool building utilities

package/dist/managers/aiManager.d.ts

@@ -53,6 +53,14 @@ export declare class AIManager {
     private get permissionManager();
     private get planManager();
     private get configurationService();
+    /**
+     * OS env merged with the per-session env snapshot. Falls back to process.env
+     * when ConfigurationService is absent or its getMergedEnv is missing (e.g. in
+     * unit tests with partial mocks), so hook-context env construction never
+     * throws. Use this (not the non-null `configurationService` getter) when
+     * building hook context env.
+     */
+    private get mergedEnv();
     getGatewayConfig(): GatewayConfig;
     getModelConfig(): ModelConfig;
     getMaxInputTokens(): number;
@@ -103,6 +111,23 @@ export declare class AIManager {
         customInstructions?: string;
         abortSignal?: AbortSignal;
     }): Promise<void>;
+    /**
+     * Build the system prompt used by the main agent loop. Extracted so the
+     * compaction fork can mirror it exactly — the forked request prefix must
+     * match the main conversation's for the prompt cache to be reused.
+     */
+    private buildMainSystemPrompt;
+    private resolveFilteredTools;
+    /**
+     * Fork-path compaction: run a bounded agent loop over a copy of the
+     * conversation using the same system prompt, tools, model, and generation
+     * params as the main loop, so the forked request prefix matches exactly
+     * and the prompt cache is reused. Tool calls are denied locally (the model
+     * is told to summarize, not act) and their rejections are fed back for
+     * another turn. Returns undefined content when the model never produces
+     * text; the caller treats that as a compaction failure.
+     */
+    private runCompactFork;
     /**
      * Build post-compact context restoration content.
      * Restores file reads, working directory, plan mode, skills, and background tasks.