wave-agent-sdk 1.0.8 → 1.0.10

package/builtin/skills/settings/MCP.md

@@ -1,137 +0,0 @@
-# Model Context Protocol (MCP) Configuration
-
-The Model Context Protocol (MCP) allows Wave to connect to external servers that provide additional tools and context. This document explains how to configure and use MCP servers in Wave.
-
-## Configuration File: `.mcp.json`
-
-MCP servers are configured in a `.mcp.json` file. Wave looks for this file in your project root:
-
-1.  **Project Scope**: `.mcp.json` in your project root (Project-specific MCP servers)
-
-## Configuration Structure
-
-The `.mcp.json` file contains a list of MCP server configurations.
-
-```json
-{
-  "mcpServers": {
-    "sqlite": {
-      "command": "uvx",
-      "args": ["mcp-server-sqlite", "--db-path", "/path/to/your/database.db"]
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
-      }
-    }
-  }
-}
-```
-
-### Fields for each server:
-
-- `type`: (Optional) The transport type: `"stdio"`, `"sse"`, or `"http"`. If omitted, Wave infers the type from other fields (URL → `"http"`, command → `"stdio"`). Set explicitly for clarity and to avoid the default behavior.
-- `command`: (For stdio) The executable to run (e.g., `npx`, `uvx`, `python`, `node`).
-- `args`: (For stdio) An array of command-line arguments for the executable.
-- `env`: (Optional) A record of environment variables for the server process.
-- `url`: (For `sse`/`http`) The endpoint URL of a remote MCP server.
-- `headers`: (For `sse`/`http`) A record of HTTP headers to send with requests (e.g., `{"Authorization": "Bearer token"}`).
-
-## Transport Types
-
-Wave supports three MCP transport types. When `type` is not specified, Wave uses the following defaults:
-- If `url` is provided → defaults to `"http"` (Streamable HTTP)
-- If `command` is provided → defaults to `"stdio"`
-
-### stdio
-
-The server is launched as a local subprocess. Use for locally installed MCP servers.
-
-```json
-{
-  "mcpServers": {
-    "sqlite": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["mcp-server-sqlite", "--db-path", "/path/to/db"]
-    }
-  }
-}
-```
-
-### http (Streamable HTTP)
-
-The recommended transport for remote servers. Uses the MCP Streamable HTTP protocol.
-
-```json
-{
-  "mcpServers": {
-    "remote-api": {
-      "type": "http",
-      "url": "https://mcp-server.example.com/mcp",
-      "headers": {
-        "Authorization": "Bearer your-token"
-      }
-    }
-  }
-}
-```
-
-### sse (Server-Sent Events)
-
-Legacy transport for remote servers that only support SSE. Use `"http"` for new servers unless the server requires SSE.
-
-```json
-{
-  "mcpServers": {
-    "legacy-server": {
-      "type": "sse",
-      "url": "https://mcp-server.example.com/sse"
-    }
-  }
-}
-```
-
-> **Note**: When `type` is not specified, URL-based servers default to `"http"` with no SSE fallback. If you need SSE, set `type: "sse"` explicitly.
-
-## Using MCP Tools
-
-Once configured, Wave will automatically connect to the MCP servers when it starts. Tools provided by these servers will be available to the agent with a prefix:
-
-`mcp__[serverName]__[toolName]`
-
-For example, if you have a server named `sqlite` with a tool named `query`, it will be available as `mcp__sqlite__query`.
-
-## Permissions for MCP Tools
-
-By default, MCP tools require user permission before execution. When you grant permission, you can choose to "Allow always" for a specific tool. These persistent rules are stored in your `settings.json` under the `permissions` field.
-
-## Plugin MCP Servers
-
-When MCP servers are registered via a **plugin**, Wave automatically injects the `WAVE_PLUGIN_ROOT` environment variable into the server process. Additionally, `${WAVE_PLUGIN_ROOT}` in the `command`, `args`, and `env` fields is substituted with the plugin's directory path before the server is spawned (matching Claude Code's `${CLAUDE_PLUGIN_ROOT}` behavior).
-
-```json
-{
-  "mcpServers": {
-    "my-plugin-server": {
-      "command": "${WAVE_PLUGIN_ROOT}/bin/mcp-server",
-      "args": ["--config", "${WAVE_PLUGIN_ROOT}/config/server.json"]
-    }
-  }
-}
-```
-
-Your MCP server code can also read `WAVE_PLUGIN_ROOT` as an environment variable:
-
-```ts
-// Inside your MCP server (e.g., a Node.js script)
-const pluginRoot = process.env.WAVE_PLUGIN_ROOT;
-```
-
-## Troubleshooting
-
-- **Server Connection**: If a server fails to connect, Wave will log an error. You can check the status of MCP servers by asking the agent.
-- **Tool Availability**: If a tool is not appearing, ensure the server is running and the `.mcp.json` configuration is correct.
-- **Logs**: MCP server `stderr` is often used for logging and can be helpful for debugging connection issues.

package/builtin/skills/settings/MEMORY.md

@@ -1,76 +0,0 @@
-# Wave Memory
-
-Wave provides multiple memory layers to give the agent context-specific instructions and knowledge. Memory files are standard Markdown files loaded automatically at startup.
-
-## Memory Layers
-
-Wave looks for memory in the following locations, loaded in order of increasing priority:
-
-1. **User Memory**: `~/.wave/AGENTS.md` — Global instructions across all projects
-2. **Project Memory**: `AGENTS.md` in the project root — Project-specific instructions
-3. **Memory Rules**: `.wave/rules/*.md` and `~/.wave/rules/*.md` — Modular, path-scoped rules (see below)
-
-> `CLAUDE.md` is also supported as a fallback for both user and project memory, for compatibility with existing repositories.
-
-## User Memory
-
-Stored at `~/.wave/AGENTS.md`. Use it for cross-project preferences and global instructions, e.g. "always write tests for new features", "prefer functional style".
-
-## Project Memory
-
-### Project Memory File
-
-The `AGENTS.md` file in the project root is the primary project-level memory. It is checked into the repository and shared with all contributors. Use it for:
-
-- Build and test commands (e.g. "use pnpm not npm")
-- Project structure and architecture conventions
-- Coding standards and patterns
-
-### Memory Rules
-
-Memory rules are modular Markdown files that provide path-scoped instructions. They are discovered in:
-
-- **Project scope**: `.wave/rules/*.md` (checked into the repo)
-- **User scope**: `~/.wave/rules/*.md` (personal, not shared)
-
-Each file can optionally include YAML frontmatter to scope rules to specific file paths:
-
-```markdown
----
-paths:
-  - "src/api/**/*.ts"
-  - "src/services/**/*.ts"
----
-
-# API and Service Guidelines
-
-- Always use `async/await` for asynchronous operations.
-- Use `Zod` for input validation.
-```
-
-#### YAML Frontmatter Fields
-
-- `paths`: (Optional) A list of glob patterns. The rules in this file will only be active when the agent is working with files that match these patterns. If omitted, the rules are always active.
-- `priority`: (Optional) A number controlling rule precedence. Higher priority rules override lower ones on conflict.
-
-#### How Memory Rules are Loaded
-
-- Wave recursively discovers all `.md` files in `.wave/rules/` and `~/.wave/rules/`.
-- **Path-specific activation**: If a rule has a `paths` field, it is only included in the agent's context when a file being read or modified matches the glob patterns.
-- **Unconditional rules**: Rules without a `paths` field are always active.
-- **Priority**: Project-level rules take priority over user-level rules if there is a conflict.
-
-#### Best Practices
-
-- **Keep rules focused**: Create separate files for different topics (e.g. `testing.md`, `ui-components.md`).
-- **Leverage path scoping**: Use the `paths` field to keep the agent's context window clean and relevant.
-- **Share with your team**: Commit `.wave/rules/` to your git repository.
-
-## Auto-Memory
-
-In addition to manual memory files, Wave has an **auto-memory** feature that automatically extracts and remembers important information across sessions. This is stored in `~/.wave/projects/<project-id>/memory/MEMORY.md`.
-
-You can control auto-memory in `settings.json`:
-
-- `autoMemoryEnabled`: Enable or disable auto-memory (default: `true`).
-- `autoMemoryFrequency`: Frequency of auto-memory extraction turns (default: `1`).

package/builtin/skills/settings/MODELS.md

@@ -1,119 +0,0 @@
-# Model Configuration
-
-Wave allows you to configure model-specific parameters directly in your `settings.json`. This gives you fine-grained control over reasoning quality, token cost, and latency for different models.
-
-## Model Overrides
-
-You can define overrides for specific models in the `models` field. The key should be the exact model name used by Wave.
-
-```json
-{
-  "models": {
-    "claude-3-7-sonnet-20250219": {
-      "options": {
-        "thinking": {
-          "type": "enabled",
-          "budget_tokens": 1024
-        },
-        "temperature": 1.0
-      }
-    },
-    "o3-mini": {
-      "options": {
-        "reasoning_effort": "high"
-      }
-    },
-    "gpt-4o": {
-      "options": {
-        "temperature": 0.5
-      }
-    }
-  }
-}
-```
-
-## Supported Parameters
-
-Generation parameters are nested under the `options` field within each model's configuration. Wave supports passing arbitrary parameters to the underlying AI provider. Common parameters include:
-
-- `temperature`: Controls randomness (0.0 to 2.0).
-- `maxTokens`: Maximum number of tokens to generate in the response.
-- `reasoning_effort`: (OpenAI specific) Controls the reasoning effort for models like `o1` and `o3-mini`. Values: `low`, `medium`, `high`.
-- `thinking`: (Claude specific) Configures the thinking/reasoning capabilities for Claude 3.7+ models.
-  - `type`: `"enabled"` or `"disabled"`.
-  - `budget_tokens`: Maximum tokens to use for thinking.
-
-## Model Capabilities
-
-Wave needs to know whether a model supports certain features. Instead of guessing from the model name, you declare these explicitly via the `capabilities` field. Note that `capabilities` is set at the top level of the model configuration, **not** inside the `options` field — `options` is reserved for generation parameters only.
-
-- `vision` (default: `true`): Whether the model can accept image inputs. When `false`, images are stripped and replaced with text placeholders.
-- `promptCaching` (default: `false`): Whether the model supports ephemeral prompt caching (e.g., Anthropic's `cache_control` markers). When `true`, Wave injects cache markers on the system prompt and last user message.
-
-```json
-{
-  "models": {
-    "claude-3-7-sonnet-20250219": {
-      "capabilities": {
-        "vision": true,
-        "promptCaching": true
-      }
-    },
-    "deepseek-r1": {
-      "capabilities": {
-        "vision": false,
-        "promptCaching": false
-      }
-    }
-  }
-}
-```
-
-You can also set `capabilities` at the top level of `settings.json` to apply to the default model:
-
-```json
-{
-  "capabilities": {
-    "vision": true,
-    "promptCaching": false
-  }
-}
-```
-
-## Unsetting Default Parameters
-
-If a model does not support a default parameter (like `temperature` for some reasoning models), you can explicitly set it to `null` inside the `options` field to ensure it is not sent to the provider.
-
-```json
-{
-  "models": {
-    "o1-preview": {
-      "options": {
-        "temperature": null
-      }
-    }
-  }
-}
-```
-
-## Global Model Selection
-
-You can also set the default models Wave uses via environment variables in `settings.json`:
-
-```json
-{
-  "env": {
-    "WAVE_MODEL": "gemini-3-flash",
-    "WAVE_FAST_MODEL": "gemini-2.5-flash",
-    "WAVE_VISION_MODEL": "qwen-vl-max",
-    "WAVE_MAX_INPUT_TOKENS": "100000",
-    "WAVE_MAX_OUTPUT_TOKENS": "4096"
-  }
-}
-```
-
-`WAVE_VISION_MODEL` names a vision-capable model for the built-in `vision` subagent. Setting it registers the subagent, whose frontmatter `model: visionModel` resolves to this value — so a fast non-vision main model can delegate image recognition. Leave it unset to disable the built-in `vision` subagent.
-
-## Live Reload
-
-Model configurations support **live reload**. When you modify the `models` field or model-related environment variables in `settings.json`, the changes take effect immediately without restarting Wave.

package/builtin/skills/settings/PERMISSIONS.md

@@ -1,88 +0,0 @@
-# Tool Permissions & Safe Zone
-
-Wave includes a robust permission system to protect your system while allowing the AI to be productive. This system is centered around the "Safe Zone" and configurable permission modes.
-
-## The Safe Zone
-
-The Safe Zone is a set of directories where Wave is allowed to perform potentially sensitive operations (like editing or writing files) with reduced friction.
-
-By default, the Safe Zone includes:
-- The current project directory.
-- The Wave configuration directories (`~/.wave/` and `.wave/`).
-- The system temporary directory.
-
-You can extend the Safe Zone by adding `additionalDirectories` to your `permissions` configuration in `settings.json`.
-
-## Permission Modes
-
-The `permissionMode` setting determines how Wave handles requests to use restricted tools (e.g., `Bash`, `Edit`, `Write`, `AskUserQuestion`).
-
-| Mode | Description |
-| :--- | :--- |
-| `default` | **Recommended.** Wave will ask for your permission before using any restricted tool. |
-| `bypassPermissions` | **Use with caution.** Wave will execute all tools without asking for permission. |
-| `acceptEdits` | Wave will automatically allow `Edit` and `Write` operations within the Safe Zone. It will still ask for permission for `Bash` and operations outside the Safe Zone. |
-| `plan` | Restricted mode for editing the plan file (usually internal). |
-| `dontAsk` | Wave will automatically deny all restricted tools without asking. This is the most restrictive mode. |
-
-### Example Configuration
-
-```json
-{
-  "permissions": {
-    "permissionMode": "default",
-    "additionalDirectories": ["/home/user/my-exports"],
-    "allow": ["ls -R", "git status"],
-    "deny": ["rm -rf"]
-  }
-}
-```
-
-## Allow and Deny Rules
-
-You can pre-approve or explicitly forbid specific operations using `allow` and `deny` rules.
-
-- **`allow`**: An array of string patterns (e.g., bash commands or file paths) that are always permitted.
-- **`deny`**: An array of string patterns that are always forbidden.
-
-When a tool is called, Wave checks:
-1. If the operation matches a `deny` rule, it is rejected.
-2. If the operation matches an `allow` rule, it is permitted.
-3. If no rules match, the behavior depends on the `permissionMode`.
-
-### Rule Syntax
-
-Rules use the format `ToolName(pattern)`. The wildcard `*` has different semantics depending on the tool type:
-
-**Bash rules** — `*` matches everything including `/` (regex-style):
-
-```json
-{ "allow": ["Bash(git status*)", "Bash(npm run *)"] }
-```
-
-- `Bash(git status*)` matches `git status`, `git status -s`, `git status --short`
-- `Bash(npm run *)` matches `npm run build`, `npm run test:unit`
-- `*` → `.*` regex conversion, so `Bash(node */scripts/*.mjs*)` matches `node plugins/code2cwspec/scripts/check-manifest.mjs`
-
-**File tool rules** (`Read`, `Write`, `Edit`) — `*` does NOT cross `/` (glob-style, use `**` for directories):
-
-```json
-{ "allow": ["Read(**/*.env)", "Write(src/**/*.ts)"] }
-```
-
-- `Read(*.env)` matches `local.env` but NOT `config/local.env`
-- `Read(**/*.env)` matches `local.env`, `config/local.env`, `a/b/c.env`
-- Uses `minimatch` glob semantics
-
-| Tool | `*` matches `/`? | Semantics | Example |
-| :--- | :--- | :--- | :--- |
-| `Bash(...)` | Yes | Regex `.*` | `Bash(npm *)` → any npm command |
-| `Read(...)` | No | Glob (use `**`) | `Read(**/*.env)` → any depth `.env` |
-| `Write(...)` | No | Glob (use `**`) | `Write(src/**/*.ts)` → any `.ts` in src |
-| `Edit(...)` | No | Glob (use `**`) | `Edit(**/*.json)` → any `.json` |
-
-## Managing Permissions via CLI
-
-You can also manage permissions directly through the Wave interface:
-- When Wave asks for permission, you can select "Always allow" to add a rule to your `settings.local.json`.
-- You can ask Wave to "Update my permission mode to acceptEdits".

package/builtin/skills/settings/PLUGINS.md

@@ -1,171 +0,0 @@
-# Wave Plugins & Plugin Marketplaces
-
-This guide covers creating plugins, publishing plugin marketplaces, and installing plugins from marketplaces.
-
-## Plugins
-
-Plugins bundle skills, hooks, MCP servers, LSP servers, and slash commands into a reusable package.
-
-### Creating a Plugin
-
-A plugin is any directory containing a `.wave-plugin/plugin.json` manifest:
-
-```json
-{
-  "name": "my-plugin",
-  "description": "A plugin that adds code review capabilities",
-  "version": "1.0.0",
-  "author": {
-    "name": "Your Name"
-  }
-}
-```
-
-Plugin name must match `^[a-z0-9-]+$` (lowercase letters, numbers, hyphens only).
-
-Place resources in standard directories within the plugin:
-
-| Directory / File | Purpose |
-|-----------------|---------|
-| `skills/` | Skill directories, each containing a `SKILL.md` file |
-| `commands/` | Custom slash command definitions |
-| `hooks/hooks.json` | Hook configuration |
-| `.lsp.json` | LSP server configuration |
-| `.mcp.json` | MCP server configuration |
-
-Only `plugin.json` should exist in `.wave-plugin/` — any other files there will cause a validation error.
-
-### Installing a Plugin Locally
-
-Add a plugin directly in `settings.json`:
-
-```json
-{
-  "plugins": [
-    {
-      "type": "local",
-      "path": "/path/to/my-plugin"
-    }
-  ]
-}
-```
-
-### `${WAVE_PLUGIN_ROOT}` Placeholder
-
-Plugin skills, hooks, MCP servers, and LSP servers can reference their parent plugin's directory using `${WAVE_PLUGIN_ROOT}`. Wave substitutes this placeholder with the plugin's absolute directory path at load time, and also injects `WAVE_PLUGIN_ROOT` as an environment variable into spawned processes.
-
-Example hook command:
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${WAVE_PLUGIN_ROOT}/hooks/session-start\"",
-            "async": false
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Plugin Marketplaces
-
-A plugin marketplace is a git repository containing a `.wave-plugin/marketplace.json` that lists available plugins.
-
-### Marketplace Manifest
-
-```json
-{
-  "name": "my-plugins",
-  "owner": {
-    "name": "Your Name"
-  },
-  "plugins": [
-    {
-      "name": "review-plugin",
-      "description": "Adds a /review command for code reviews",
-      "source": "./plugins/review-plugin"
-    },
-    {
-      "name": "remote-plugin",
-      "description": "Plugin hosted on a remote git repo",
-      "source": "https://github.com/user/remote-plugin.git"
-    }
-  ]
-}
-```
-
-- `source` can be a **relative path** (resolved from the marketplace repo root) or a **git URL** (`https://`, `git@`, `ssh://`) for remote repos.
-- Each plugin at its source path must have its own `.wave-plugin/plugin.json` manifest.
-
-### Registering a Marketplace
-
-Add a marketplace in `settings.json`:
-
-```json
-{
-  "marketplaces": {
-    "my-plugins": {
-      "source": {
-        "source": "github",
-        "repo": "user/my-plugins"
-      }
-    }
-  }
-}
-```
-
-**Source types:**
-
-| Type | Format | Example |
-|------|--------|---------|
-| GitHub | `{ "source": "github", "repo": "owner/repo", "ref": "branch" }` | Clones from `github.com/owner/repo` |
-| Git URL | `{ "source": "git", "url": "https://...", "ref": "branch" }` | Clones from any git remote |
-| Directory | `{ "source": "directory", "path": "/local/path" }` | Uses a local directory |
-
-### Installing from a Marketplace
-
-Install a plugin using the format `plugin-name@marketplace-name`:
-
-```
-/install-plugin my-plugin@my-plugins
-```
-
-Wave clones the marketplace repo, reads the manifest, and copies the plugin to its cache directory.
-
-### Creating a Plugin Marketplace
-
-1. Create a git repository
-2. Add `.wave-plugin/marketplace.json` at the root
-3. Add plugin directories with their own `.wave-plugin/plugin.json`
-4. Register the marketplace in your `settings.json` using a github, git, or directory source
-5. Plugins are cloned to the cache directory on install
-
-### Updating Plugins
-
-Marketplaces with `autoUpdate: true` are checked for updates on startup:
-
-```json
-{
-  "marketplaces": {
-    "my-plugins": {
-      "source": { "source": "github", "repo": "user/my-plugins" },
-      "autoUpdate": true
-    }
-  }
-}
-```
-
-### Marketplace Scopes
-
-Marketplace declarations can be scoped:
-- **User scope**: `~/.wave/settings.json` — available in all projects
-- **Project scope**: `.wave/settings.json` — available in this project only
-- **Local scope**: `.wave/settings.local.json` — not committed to git
-
-Later scopes override earlier ones (local > project > user).