wave-agent-sdk 1.0.9 → 1.0.10

package/dist/utils/convertMessagesForAPI.js

@@ -102,10 +102,29 @@ export function convertMessagesForAPI(messages, options) {
                                 });
                             }
                             else {
-                                // Non-vision model: replace images with a text placeholder
+                                // Non-vision model: replace images with a text placeholder and
+                                // append [Image source: <path>] metadata for MCP images that
+                                // were persisted to temp files, so the main model can delegate
+                                // recognition to a vision subagent (which reads the path with
+                                // the Read tool). Images without a persisted path (e.g. legacy
+                                // history) fall back to the placeholder only.
+                                const contentParts = [
+                                    {
+                                        type: "text",
+                                        text: "[Tool returned an image, but the current model does not support image recognition]",
+                                    },
+                                ];
+                                toolBlock.images.forEach((image) => {
+                                    if (image.path) {
+                                        contentParts.push({
+                                            type: "text",
+                                            text: `[Image source: ${image.path}]`,
+                                        });
+                                    }
+                                });
                                 imageUserMessages.push({
                                     role: "user",
-                                    content: "[Tool returned an image, but the current model does not support image recognition]",
+                                    content: contentParts,
                                 });
                             }
                         }

package/dist/utils/messageOperations.d.ts

@@ -37,6 +37,7 @@ export interface UpdateToolBlockParams {
     images?: Array<{
         data: string;
         mediaType?: string;
+        path?: string;
     }>;
     compactParams?: string;
     parametersChunk?: string;

package/dist/utils/toolImagePersistence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Persistence for MCP tool-returned images.
+ *
+ * MCP tools can return image content blocks as in-memory base64. When the
+ * agent's model does not support vision, the image is written to a temp file
+ * so convertMessagesForAPI can attach `[Image source: <path>]` metadata and
+ * the main model can delegate recognition to the vision subagent (which reads
+ * the path with the Read tool). Vision-capable models keep the inline base64
+ * and never write to disk.
+ */
+export interface PersistedToolImage {
+    data: string;
+    mediaType?: string;
+    path?: string;
+}
+/**
+ * Persist base64 images to temp files under /tmp/wave-mcp-images/.
+ * Uses the OS tmpdir for simplicity and automatic OS cleanup (same convention
+ * as /tmp/wave-tool-results/). Returns each image unchanged (no path) when the
+ * write fails, so the caller degrades to the placeholder-only behavior.
+ */
+export declare function persistToolImages(images: Array<{
+    data: string;
+    mediaType?: string;
+}>): PersistedToolImage[];

package/dist/utils/toolImagePersistence.js

@@ -0,0 +1,56 @@
+/**
+ * Persistence for MCP tool-returned images.
+ *
+ * MCP tools can return image content blocks as in-memory base64. When the
+ * agent's model does not support vision, the image is written to a temp file
+ * so convertMessagesForAPI can attach `[Image source: <path>]` metadata and
+ * the main model can delegate recognition to the vision subagent (which reads
+ * the path with the Read tool). Vision-capable models keep the inline base64
+ * and never write to disk.
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { logger } from "./globalLogger.js";
+const MCP_IMAGES_DIR = path.join(os.tmpdir(), "wave-mcp-images");
+/** Map MCP mimeType to a file extension. Unknown types fall back to .png. */
+const MIME_TO_EXT = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "image/bmp": ".bmp",
+    "image/svg+xml": ".svg",
+    "image/avif": ".avif",
+    "image/x-icon": ".ico",
+    "image/tiff": ".tiff",
+};
+/**
+ * Persist base64 images to temp files under /tmp/wave-mcp-images/.
+ * Uses the OS tmpdir for simplicity and automatic OS cleanup (same convention
+ * as /tmp/wave-tool-results/). Returns each image unchanged (no path) when the
+ * write fails, so the caller degrades to the placeholder-only behavior.
+ */
+export function persistToolImages(images) {
+    return images.map((image) => {
+        try {
+            fs.mkdirSync(MCP_IMAGES_DIR, { recursive: true });
+            // Strip a data: URL prefix if present (MCP spec carries raw base64, but
+            // be defensive about dataURL-formatted data).
+            let data = image.data;
+            if (data.startsWith("data:")) {
+                const commaIndex = data.indexOf(",");
+                data = commaIndex >= 0 ? data.slice(commaIndex + 1) : data;
+            }
+            const ext = MIME_TO_EXT[image.mediaType || ""] || ".png";
+            const id = `${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+            const filePath = path.join(MCP_IMAGES_DIR, `mcp-image_${id}${ext}`);
+            fs.writeFileSync(filePath, Buffer.from(data, "base64"));
+            return { ...image, path: filePath };
+        }
+        catch (error) {
+            logger?.error("Failed to persist MCP tool image:", error);
+            return image;
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",
@@ -36,7 +36,6 @@
   },
   "files": [
     "dist",
-    "builtin",
     "README.md"
   ],
   "dependencies": {
@@ -51,7 +50,6 @@
     "@vscode/ripgrep": "^1.18.0",
     "chokidar": "^4.0.3",
     "cron-parser": "^5.5.0",
-    "find-up": "^8.0.0",
     "fuzzysort": "^3.1.0",
     "glob": "^13.0.0",
     "lru-cache": "^11.3.5",

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

@@ -1,8 +0,0 @@
-{
-  "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

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

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

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

@@ -1,77 +0,0 @@
-#!/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

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

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

package/builtin/skills/artifact/SKILL.md

@@ -1,14 +0,0 @@
----
-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 with the resolved `file_path` (and `favicon` if relevant), then report the resulting URL to the user.

package/builtin/skills/loop/SKILL.md

@@ -1,79 +0,0 @@
----
-name: loop
-description: Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo, defaults to 10m)
-allowed-tools: CronCreate, Skill
-user-invocable: true
----
-
-# /loop — schedule a recurring prompt
-
-Parse the input below into `[interval] <prompt…>` and schedule it with CronCreate.
-
-## Usage
-
-```
-/loop [interval] <prompt>
-
-Run a prompt or slash command on a recurring interval.
-
-Intervals: Ns, Nm, Nh, Nd (e.g. 5m, 30m, 2h, 1d). Minimum granularity is 1 minute.
-If no interval is specified, defaults to 10m.
-
-Examples:
-  /loop 5m /babysit-prs
-  /loop 30m check the deploy
-  /loop 1h /standup 1
-  /loop check the deploy          (defaults to 10m)
-  /loop check the deploy every 20m
-```
-
-## Parsing (in priority order)
-
-1. **Leading token**: if the first whitespace-delimited token matches `^\d+[smhd]$` (e.g. `5m`, `2h`), that's the interval; the rest is the prompt.
-2. **Trailing "every" clause**: otherwise, if the input ends with `every <N><unit>` or `every <N> <unit-word>` (e.g. `every 20m`, `every 5 minutes`, `every 2 hours`), extract that as the interval and strip it from the prompt. Only match when what follows "every" is a time expression — `check every PR` has no interval.
-3. **Default**: otherwise, interval is `10m` and the entire input is the prompt.
-
-If the resulting prompt is empty, show usage `/loop [interval] <prompt>` and stop — do not call CronCreate.
-
-Examples:
-- `5m /babysit-prs` → interval `5m`, prompt `/babysit-prs` (rule 1)
-- `check the deploy every 20m` → interval `20m`, prompt `check the deploy` (rule 2)
-- `run tests every 5 minutes` → interval `5m`, prompt `run tests` (rule 2)
-- `check the deploy` → interval `10m`, prompt `check the deploy` (rule 3)
-- `check every PR` → interval `10m`, prompt `check every PR` (rule 3 — "every" not followed by time)
-- `5m` → empty prompt → show usage
-
-## Interval → cron
-
-Supported suffixes: `s` (seconds, rounded up to nearest minute, min 1), `m` (minutes), `h` (hours), `d` (days). Convert:
-
-| Interval pattern      | Cron expression     | Notes                                    |
-|-----------------------|---------------------|------------------------------------------|
-| `Nm` where N ≤ 59   | `*/N * * * *`     | every N minutes                          |
-| `Nm` where N ≥ 60   | `0 */H * * *`     | round to hours (H = N/60, must divide 24)|
-| `Nh` where N ≤ 23   | `0 */N * * *`     | every N hours                            |
-| `Nd`                | `0 0 */N * *`     | every N days at midnight local           |
-| `Ns`                | treat as `ceil(N/60)m` | cron minimum granularity is 1 minute  |
-
-**If the interval doesn't cleanly divide its unit** (e.g. `7m` → `*/7 * * * *` gives uneven gaps at :56→:00; `90m` → 1.5h which cron can't express), pick the nearest clean interval and tell the user what you rounded to before scheduling.
-
-## Avoid the :00 and :30 minute marks
-
-When the user's request is approximate, pick a minute that is NOT 0 or 30:
-- "every morning around 9" → `57 8 * * *` or `3 9 * * *` (not `0 9 * * *`)
-- "hourly" → `7 * * * *` (not `0 * * * *`)
-
-Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past").
-
-## Action
-
-1. Call CronCreate with:
-   - `cron`: the expression from the table above
-   - `prompt`: the parsed prompt from above, verbatim (slash commands are passed through unchanged)
-   - `recurring`: `true`
-2. Briefly confirm: what's scheduled, the cron expression, the human-readable cadence, that recurring tasks auto-expire after 7 days, and that they can cancel sooner with CronDelete (include the job ID).
-3. **Then immediately execute the parsed prompt now** — don't wait for the first cron fire. If it's a slash command, run it directly; otherwise act on it directly.
-
-## Input
-
-$ARGUMENTS

package/builtin/skills/settings/ENV.md

@@ -1,78 +0,0 @@
-# Wave Environment Variables Configuration
-
-Environment variables allow you to customize Wave's behavior, configure AI models, and provide context to hooks and tools. This document provides detailed guidance on how to configure environment variables in `settings.json`.
-
-## The `env` Field
-
-Environment variables are configured in the `env` field of `settings.json`. It is a simple key-value pair of strings.
-
-```json
-{
-  "env": {
-    "WAVE_MODEL": "gemini-3-flash",
-    "MY_CUSTOM_VAR": "some-value"
-  }
-}
-```
-
-## Supported `WAVE_*` Environment Variables
-
-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. Resolution order: `options.serverUrl` → `process.env.WAVE_SERVER_URL` → default. Unlike other `WAVE_*` vars, a settings.json `env` value is also mirrored to `process.env` so process-level singletons (AuthService) see it without a per-session snapshot. | `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` |
-| `WAVE_VISION_MODEL` | Vision-capable model used by the built-in `vision` subagent for image recognition. When set, the built-in `vision` subagent is registered (its frontmatter `model: visionModel` resolves to this value); when unset, the subagent is not loaded. Useful when the main model is fast but non-vision (e.g. DeepSeek). | - (not registered) |
-| `WAVE_MAX_INPUT_TOKENS` | Maximum number of input tokens allowed. | `200000` |
-| `WAVE_MAX_OUTPUT_TOKENS` | Maximum number of output tokens allowed. | `32000` |
-| `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. **OS env only** (infrastructure). | `300000` |
-
-## Configuration Scopes
-
-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=...`). 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 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).
-
-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
-{
-  "env": {
-    "PROJECT_NAME": "my-awesome-project",
-    "DEPLOY_TARGET": "staging"
-  }
-}
-```
-
-## 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 — the session's environment snapshot is refreshed and subsequent resolve calls / subprocess spawns use the new values.
-
-## Best Practices
-
-- **Use Local Overrides for Secrets**: Never commit sensitive information like `WAVE_API_KEY` to `settings.json`. Use `settings.local.json` instead.
-- **Standard Naming**: Use uppercase and underscores for environment variable names (e.g., `MY_VARIABLE`).
-- **Avoid Overriding System Variables**: Be careful not to override standard system variables like `PATH` or `HOME` unless you have a specific reason to do so.