wave-agent-sdk 0.15.2 → 0.15.4

package/builtin/skills/settings/ENV.md

@@ -1,69 +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.
-
-| Variable | Description | Default |
-| :--- | :--- | :--- |
-| `WAVE_API_KEY` | API key for the AI gateway. | - |
-| `WAVE_BASE_URL` | Base URL for the AI gateway. | - |
-| `WAVE_CUSTOM_HEADERS` | Custom HTTP headers for the AI gateway (JSON string). | - |
-| `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_MAX_INPUT_TOKENS` | Maximum number of input tokens allowed. | `96000` |
-| `WAVE_MAX_OUTPUT_TOKENS` | Maximum number of output tokens allowed. | `8192` |
-| `WAVE_DISABLE_AUTO_MEMORY` | Set to `1` or `true` to disable the auto-memory feature. | `false` |
-| `WAVE_TASK_LIST_ID` | Explicitly set the task list ID for the session. | (Session ID) |
-| `WAVE_PROMPT_CACHE_REGEX` | Regex pattern to match model names that support prompt caching. Models matching this pattern will have cache control markers applied. | `claude` |
-
-## Configuration Scopes
-
-Environment variables can be set in different scopes, with the following 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=...`)
-
-## Custom Environment Variables
-
-You can also define custom environment variables in the `env` field. These variables will be available to:
-
-- **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.
-
-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.
-
-## 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.

package/builtin/skills/settings/HOOKS.md

@@ -1,192 +0,0 @@
-# Wave Hooks Configuration
-
-Hooks allow you to automate tasks when certain events occur in Wave. This document provides detailed guidance on how to configure hooks in `settings.json`.
-
-## Hook Events
-
-Wave supports the following hook events:
-
-- `PreToolUse`: Triggered before a tool is executed.
-- `PostToolUse`: Triggered after a tool has finished executing.
-- `UserPromptSubmit`: Triggered when a user submits a prompt.
-- `PermissionRequest`: Triggered when Wave requests permission to use a tool.
-- `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.
-- `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.
-
-## Hook Configuration Structure
-
-Hooks are configured in the `hooks` field of `settings.json`. Each event can have multiple hook configurations.
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write",
-        "hooks": [
-          {
-            "command": "pnpm lint",
-            "description": "Run lint before writing files"
-          }
-        ]
-      }
-    ],
-    "PermissionRequest": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "command": "echo \"Permission requested for Bash tool\" >> hooks.log",
-            "description": "Log permission requests for Bash"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Hook Configuration Fields
-
-- `matcher`: (Optional) A pattern to match against the tool name (e.g., "Write", "Read*", "/^Edit/"). Only applicable for `PreToolUse`, `PostToolUse`, and `PermissionRequest`.
-- `hooks`: An array of hook commands to execute.
-  - `command`: The shell command to execute.
-  - `description`: A brief description of the hook's purpose.
-  - `async`: (Optional) Whether the hook should run in the background without blocking (default: `false`).
-  - `timeout`: (Optional) Maximum execution time in seconds (default: `600`).
-
-## Hook Input JSON
-
-Wave provides detailed context to hook processes via `stdin` as a JSON object. This allows hooks to make informed decisions based on the current state.
-
-### Common Fields
-- `session_id`: The current session ID.
-- `transcript_path`: Path to the session transcript file (JSON).
-- `cwd`: The current working directory.
-- `hook_event_name`: The name of the triggering event.
-
-### Event-Specific Fields
-- `tool_name`: (PreToolUse, PostToolUse, PermissionRequest) The name of the tool.
-- `tool_input`: (PreToolUse, PostToolUse, PermissionRequest) The input parameters passed to the tool.
-- `tool_response`: (PostToolUse) The result of the tool execution.
-- `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.
-- `source`: (SessionStart) The session start source: `"startup"`, `"resume"`, or `"compact"`.
-- `agent_type`: (SessionStart) The agent type identifier.
-- `end_source`: (SessionEnd) The session end source: `"exit"`, `"stop"`, or `"compact"`.
-
-## Hook Exit Codes
-
-Hooks can communicate status and control Wave's behavior using exit codes:
-
-- **Exit 0**: Success. Wave continues its normal execution.
-- **Exit 2**: Blocking Error. Wave blocks the current operation and provides feedback based on the event:
-    - `UserPromptSubmit`: Blocks prompt processing and shows `stderr` as a user error.
-    - `PreToolUse`: Blocks tool execution and provides `stderr` to the agent as feedback.
-    - `PostToolUse`: Appends `stderr` to the tool result as feedback for the agent.
-    - `Stop`: Blocks the stop operation and provides `stderr` to the agent.
-    - `SessionStart` / `SessionEnd`: Shows `stderr` in an error block, but does not block startup or shutdown.
-- **Other Exits (e.g., Exit 1)**: Non-blocking error. Wave continues execution but shows `stderr` as a warning to the user.
-
-## SessionStart Hooks
-
-`SessionStart` hooks fire during session initialization. They can inject context and messages into the session via stdout.
-
-### Stdout Processing
-
-Hook stdout is processed as follows:
-- If stdout is valid JSON with `hookSpecificOutput.additionalContext` (Claude Code format), that value is injected as additional context.
-- If stdout is valid JSON with `initialUserMessage` at the top level, that value is injected as the initial user message.
-- If stdout is not JSON, the entire output is appended as additional context.
-
-Example hook output:
-```json
-{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "User prefers concise responses"}, "initialUserMessage": "Here is my current task..."}
-```
-
-### Example Configuration
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Project uses pnpm and TypeScript\"}}'",
-            "description": "Inject project context at session start"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## SessionEnd Hooks
-
-`SessionEnd` hooks fire during agent destruction (fire-and-forget, non-blocking). They are useful for cleanup tasks, resource teardown, and analytics.
-
-### Input
-SessionEnd hooks receive `end_source` in the JSON input indicating how the session ended:
-- `"exit"`: User exited the session
-- `"stop"`: Session was explicitly stopped
-- `"compact"`: Session was compacted
-
-### Example Configuration
-```json
-{
-  "hooks": {
-    "SessionEnd": [
-      {
-        "hooks": [
-          {
-            "command": "echo '{\"session_id\": \"$WAVE_SESSION_ID\"}' >> /tmp/session-analytics.log",
-            "description": "Log session end for analytics",
-            "async": true
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Live Reload
-
-Hook configurations support **live reload**. When you modify hooks in `settings.json`, the changes take effect immediately without restarting Wave.
-
-## Plugin Hooks
-
-When hooks are registered via a **plugin**, Wave automatically:
-
-1. Substitutes `${WAVE_PLUGIN_ROOT}` with the plugin's directory path in the command string
-2. Injects `WAVE_PLUGIN_ROOT` as an environment variable into the hook process
-
-```json
-{
-  "hooks": {
-    "WorktreeCreate": [
-      {
-        "hooks": [
-          {
-            "command": "${WAVE_PLUGIN_ROOT}/scripts/setup-worktree.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-The shell also receives `WAVE_PLUGIN_ROOT` as an env var, so `$WAVE_PLUGIN_ROOT` works in the hook script itself.
-
-## Best Practices
-
-- **Keep hooks fast**: Long-running hooks can slow down your workflow unless they are `async`.
-- **Use descriptive names**: Help yourself and others understand what each hook does.
-- **Test your hooks**: Run the commands manually first to ensure they work as expected.
-- **Use local overrides**: For machine-specific hooks, use `.wave/settings.local.json`.

package/builtin/skills/settings/MCP.md

@@ -1,92 +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:
-
-- `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) The endpoint URL of a remote MCP server (e.g., `https://example.com/sse`).
-
-## Remote MCP Servers (SSE)
-
-Wave also supports connecting to remote MCP servers via SSE (Server-Sent Events).
-
-```json
-{
-  "mcpServers": {
-    "remote-server": {
-      "url": "https://mcp-server.example.com/sse"
-    }
-  }
-}
-```
-
-## 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_RULES.md

@@ -1,60 +0,0 @@
-# Wave Memory Rules Configuration
-
-Memory rules allow you to provide context-specific instructions and guidelines to the agent. This document explains how to create and manage memory rules in Wave.
-
-## What are Memory Rules?
-
-Memory rules are Markdown files that contain instructions for the agent. They are used to:
-- Enforce coding styles and conventions.
-- Provide project-specific context (e.g., "always use pnpm").
-- Define architectural patterns and best practices.
-- Share common knowledge across the team.
-
-## Creating Memory Rules
-
-Wave looks for memory rules in the following locations:
-
-1.  **User Scope**: `~/.wave/rules/*.md` (Global memory rules)
-2.  **Project Scope**: `.wave/rules/*.md` (Project-specific memory rules)
-3.  **Project Root**: `AGENTS.md` (Legacy project-level memory rules)
-
-### File Structure
-
-A memory rule file is a standard Markdown file. It can optionally include YAML frontmatter to scope the 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.
-- Follow the repository pattern for data access.
-```
-
-### 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.
-
-## How Memory Rules are Loaded
-
-Wave automatically discovers and loads all `.md` files in the `.wave/rules/` directory and its immediate subdirectories.
-
-- **Path-Specific Activation**: If a memory rule has a `paths` field, it is only included in the agent's context if *any* file currently being read or modified matches the glob patterns.
-- **Union of Rules**: If multiple files are in context, Wave activates the union of all matching memory rules.
-- **Priority**: Project-level memory rules take priority over user-level memory rules if there is a conflict.
-
-## Best Practices
-
-- **Keep rules focused**: Create separate files for different topics (e.g., `testing.md`, `ui-components.md`).
-- **Use clear instructions**: Write rules in a way that is easy for the agent to understand and follow.
-- **Leverage path scoping**: Use the `paths` field to keep the agent's context window clean and relevant.
-- **Share rules with your team**: Commit `.wave/rules/` to your git repository to ensure everyone on the team has the same context.
-
-## Auto-Memory
-
-In addition to manual memory rules, Wave also has an **auto-memory** feature that automatically remembers important information across sessions. This is stored in `~/.wave/projects/<project-id>/memory/MEMORY.md`. You can disable this feature in `settings.json` by setting `"autoMemoryEnabled": false`.

package/builtin/skills/settings/MODELS.md

@@ -1,71 +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": {
-      "thinking": {
-        "type": "enabled",
-        "budget_tokens": 1024
-      },
-      "temperature": 1.0
-    },
-    "o3-mini": {
-      "reasoning_effort": "high"
-    },
-    "gpt-4o": {
-      "temperature": 0.5
-    }
-  }
-}
-```
-
-## Supported Parameters
-
-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.
-
-## 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` to ensure it is not sent to the provider.
-
-```json
-{
-  "models": {
-    "o1-preview": {
-      "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_MAX_INPUT_TOKENS": "100000",
-    "WAVE_MAX_OUTPUT_TOKENS": "4096"
-  }
-}
-```
-
-## 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,57 +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`.
-
-## 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".