wave-agent-sdk 1.2.0 → 1.3.0

package/dist/agent.d.ts

@@ -1,6 +1,6 @@
 import { type QueuedMessage } from "./managers/messageQueue.js";
 import { SlashCommand, CustomSlashCommand, AgentOptions } from "./types/index.js";
-import type { Message, McpServerStatus, GatewayConfig, ModelConfig, Usage, PermissionMode, ForegroundTask, SkillMetadata } from "./types/index.js";
+import type { Message, McpServerStatus, GatewayConfig, ModelConfig, Usage, PermissionMode, ForegroundTask, SkillMetadata, PluginReloadResult } from "./types/index.js";
 import type { HookEvent, HookEventConfig } from "./types/hooks.js";
 import type { WorktreeSession } from "./utils/worktreeSession.js";
 export declare class Agent {
@@ -43,12 +43,39 @@ export declare class Agent {
     getGatewayConfig(): GatewayConfig;
     getModelConfig(): ModelConfig;
     getMaxInputTokens(): number;
-    getLanguage(): string | undefined;
+    getLanguage(): string;
+    /**
+     * Re-read the merged configuration (user/project/local settings.json + remote
+     * managed settings) and apply it to this session **without rebuilding it**:
+     * hooks / permissions / env follow immediately, the settings.json-derived
+     * values the running turn reads are re-pinned at the next turn start.
+     *
+     * THE save path calls this explicitly after writing the user-level
+     * settings.json: that file is commonly *created* by that very write, so the
+     * file watcher — armed at session start on a path that did not exist yet —
+     * must not be the only trigger (docs/specs/core/agent-config.md
+     * 「设置实时重载」). Idempotent with the watcher (a concurrent reload is
+     * de-duplicated).
+     */
+    reloadConfiguration(): Promise<void>;
+    /**
+     * Re-read every plugin from disk and swap its contribution into this running
+     * session in place — the `/reload-plugins` command. Commands, skills,
+     * agents, hooks, MCP servers and LSP servers all follow; the session itself
+     * (sessionId, transcript, in-flight work) is untouched, so this is not a
+     * rebuild. Every live session in the process must call this to see the new
+     * state; sessions created afterwards pick it up from disk on their own.
+     *
+     * Busts the prompt cache for the tool-schema prefix (the skill and agent
+     * lists are inlined) — deliberately accepted, see
+     * docs/specs/ecosystem/plugin.md「插件变更的就地重载」.
+     */
+    reloadPlugins(): Promise<PluginReloadResult>;
     /**
      * Set the active model for the agent session
      * @param model - The ID of the model to use
      */
-    setModel(model: string): void;
+    setModel(model: string): Promise<void>;
     /**
      * Get all configured models from settings.json and defaults
      * @returns Array of model IDs
@@ -246,8 +273,35 @@ export declare class Agent {
     /**
      * Restore a session by ID, switching to the target session without destroying the Agent instance
      * @param sessionId - The ID of the session to restore
+     * @param options.workdir - The directory the target session lives in. Pass it
+     *   when the target was recorded under a different project directory (e.g.
+     *   another worktree of the same repo); the session transcript, project rules
+     *   and memory are then re-pointed at it.
+     */
+    restoreSession(sessionId: string, options?: {
+        workdir?: string;
+    }): Promise<void>;
+    /**
+     * Set this session's user-visible title.
+     *
+     * The title is appended to the session's own JSONL file as a `custom-title`
+     * entry (see `setSessionCustomTitle`), so every host that reads session files
+     * — this process, a later run, the IDE plugins, the desktop app — shows the
+     * same label. A blank title is a no-op.
+     */
+    renameSession(title: string): Promise<void>;
+    /** Shared wiring for the InteractionService entry points. */
+    private interactionContext;
+    /**
+     * Re-point every directory-derived piece of session state at `workdir`
+     * (used when restoring a session recorded in another directory).
+     *
+     * The memory cache needs no explicit clearing: moving to a session always
+     * changes the session id, and the resulting `onSessionIdChange` already
+     * clears it. Project rules do — they are discovered once at startup and
+     * resolved relative to the workdir.
      */
-    restoreSession(sessionId: string): Promise<void>;
+    private switchSessionWorkdir;
     abortAIMessage(): void;
     /** Execute a bash-mode command (`!command`) */
     bang(command: string): Promise<void>;

package/dist/agent.js

@@ -3,8 +3,9 @@ import { configValidator } from "./utils/configValidator.js";
 import path from "node:path";
 import { parseTaskNotificationXml } from "./utils/notificationXml.js";
 import { InitializationService } from "./services/initializationService.js";
-import { InteractionService } from "./services/interactionService.js";
+import { InteractionService, } from "./services/interactionService.js";
 import { ConfigurationService } from "./services/configurationService.js";
+import { setSessionCustomTitle } from "./services/session.js";
 import { setupAgentContainer } from "./utils/containerSetup.js";
 import { initializeTelemetry, shutdownTelemetry, } from "./telemetry/instrumentation.js";
 import { logOTelEvent } from "./telemetry/events.js";
@@ -26,12 +27,47 @@ export class Agent {
     getLanguage() {
         return this.configurationService.resolveLanguage();
     }
+    /**
+     * Re-read the merged configuration (user/project/local settings.json + remote
+     * managed settings) and apply it to this session **without rebuilding it**:
+     * hooks / permissions / env follow immediately, the settings.json-derived
+     * values the running turn reads are re-pinned at the next turn start.
+     *
+     * THE save path calls this explicitly after writing the user-level
+     * settings.json: that file is commonly *created* by that very write, so the
+     * file watcher — armed at session start on a path that did not exist yet —
+     * must not be the only trigger (docs/specs/core/agent-config.md
+     * 「设置实时重载」). Idempotent with the watcher (a concurrent reload is
+     * de-duplicated).
+     */
+    async reloadConfiguration() {
+        await this.liveConfigManager.reload();
+    }
+    /**
+     * Re-read every plugin from disk and swap its contribution into this running
+     * session in place — the `/reload-plugins` command. Commands, skills,
+     * agents, hooks, MCP servers and LSP servers all follow; the session itself
+     * (sessionId, transcript, in-flight work) is untouched, so this is not a
+     * rebuild. Every live session in the process must call this to see the new
+     * state; sessions created afterwards pick it up from disk on their own.
+     *
+     * Busts the prompt cache for the tool-schema prefix (the skill and agent
+     * lists are inlined) — deliberately accepted, see
+     * docs/specs/ecosystem/plugin.md「插件变更的就地重载」.
+     */
+    async reloadPlugins() {
+        const result = await this.pluginManager.reloadAllPlugins();
+        // Plugin skills arrive after SkillManager.initialize(), so their slash
+        // commands have to be re-derived explicitly (same as at startup).
+        this.slashCommandManager.registerSkillCommands(this.skillManager.getAvailableSkills());
+        return result;
+    }
     /**
      * Set the active model for the agent session
      * @param model - The ID of the model to use
      */
-    setModel(model) {
-        this.configurationService.setModel(model);
+    async setModel(model) {
+        await this.configurationService.setModel(model);
         this.options.callbacks?.onModelChange?.(model);
     }
     /**
@@ -503,6 +539,11 @@ export class Agent {
             taskManager: this.taskManager,
             resolveAndValidateConfig: () => this.resolveAndValidateConfig(),
         }, options);
+        // Freeze the session-level bypass authorization now that settings.json (and
+        // thus `permissions.defaultMode`) has been loaded. Later mode switches and
+        // config reloads must not change it — it records what the user authorized
+        // when the session started.
+        this.permissionManager.captureBypassAuthorization();
         // Initialize OpenTelemetry (awaited to ensure ALS context is ready before
         // startInteractionSpan is called, preventing trace context fragmentation)
         const telemetryConfig = this.configurationService.resolveTelemetryConfig();
@@ -530,9 +571,33 @@ export class Agent {
     /**
      * Restore a session by ID, switching to the target session without destroying the Agent instance
      * @param sessionId - The ID of the session to restore
+     * @param options.workdir - The directory the target session lives in. Pass it
+     *   when the target was recorded under a different project directory (e.g.
+     *   another worktree of the same repo); the session transcript, project rules
+     *   and memory are then re-pointed at it.
+     */
+    async restoreSession(sessionId, options) {
+        await InteractionService.restoreSession(this.interactionContext(), sessionId, options);
+    }
+    /**
+     * Set this session's user-visible title.
+     *
+     * The title is appended to the session's own JSONL file as a `custom-title`
+     * entry (see `setSessionCustomTitle`), so every host that reads session files
+     * — this process, a later run, the IDE plugins, the desktop app — shows the
+     * same label. A blank title is a no-op.
      */
-    async restoreSession(sessionId) {
-        await InteractionService.restoreSession({
+    async renameSession(title) {
+        const applied = await setSessionCustomTitle(this.sessionId, this.workdir, title);
+        // Keep the in-memory value in step: it is what gets written back at the
+        // next flush point if the entry has since slid out of the tail window.
+        if (applied) {
+            this.messageManager.setCustomTitle(applied);
+        }
+    }
+    /** Shared wiring for the InteractionService entry points. */
+    interactionContext() {
+        return {
             messageManager: this.messageManager,
             slashCommandManager: this.slashCommandManager,
             hookManager: this.hookManager,
@@ -544,7 +609,22 @@ export class Agent {
             taskManager: this.taskManager,
             options: this.options,
             abortMessage: () => this.abortMessage(),
-        }, sessionId);
+            switchWorkdir: (workdir) => this.switchSessionWorkdir(workdir),
+        };
+    }
+    /**
+     * Re-point every directory-derived piece of session state at `workdir`
+     * (used when restoring a session recorded in another directory).
+     *
+     * The memory cache needs no explicit clearing: moving to a session always
+     * changes the session id, and the resulting `onSessionIdChange` already
+     * clears it. Project rules do — they are discovered once at startup and
+     * resolved relative to the workdir.
+     */
+    async switchSessionWorkdir(workdir) {
+        this.setWorkdir(workdir);
+        this.messageManager.setWorkdir(workdir);
+        await this.memoryRuleManager.setWorkdir(workdir);
     }
     abortAIMessage() {
         this.aiManager.abortAIMessage();
@@ -711,6 +791,10 @@ export class Agent {
             this.logger?.warn(`SessionEnd hooks failed: ${error.message}`);
         }
         await this.messageManager.saveSession();
+        // Flush point: the transcript is about to be left behind for other
+        // processes to list, so re-append the metadata entries at EOF. Must come
+        // after saveSession (which returns early when nothing is unsaved).
+        await this.messageManager.reAppendSessionMetadata();
         this.abortAIMessage(); // This will abort tools including Agent tool (subagents)
         this.abortBashCommand();
         this.abortSlashCommand();
@@ -832,19 +916,7 @@ export class Agent {
             }
             // Immediate slash command: fall through to InteractionService
         }
-        await InteractionService.sendMessage({
-            messageManager: this.messageManager,
-            slashCommandManager: this.slashCommandManager,
-            hookManager: this.hookManager,
-            workdir: this.workdir,
-            configurationService: this.configurationService,
-            logger: this.logger,
-            aiManager: this.aiManager,
-            subagentManager: this.subagentManager,
-            taskManager: this.taskManager,
-            options: this.options,
-            abortMessage: () => this.abortMessage(),
-        }, content, images);
+        await InteractionService.sendMessage(this.interactionContext(), content, images);
     }
     // ========== Additional Directories ==========
     /**

package/dist/builtin/index.js

@@ -5,6 +5,7 @@ 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 { waveDaemonSkill } from "./skills/wave-daemon.js";
 import { subagents } from "./subagents.js";
 import { sddPlugin } from "./plugins.js";
 export const BUILTIN_CONTENT = {
@@ -15,6 +16,7 @@ export const BUILTIN_CONTENT = {
     ...loopSkill,
     ...simplifySkill,
     ...settingsSkills,
+    ...waveDaemonSkill,
     ...subagents,
     ...sddPlugin,
 };

package/dist/builtin/skills/settings.js

@@ -924,18 +924,7 @@ Wave clones the marketplace repo, reads the manifest, and copies the plugin to i
 
 ### 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
-    }
-  }
-}
-\`\`\`
+Every registered marketplace is refreshed when you open a plugin marketplace surface — the settings page's plugin marketplace view, or the CLI plugin manager (\`/plugin\`). Each checkout is pulled (or cloned if missing). Refreshing a marketplace does **not** upgrade installed plugins, and there is no per-marketplace switch for it. Plugin upgrades only happen through an explicit action: updating a single plugin, or updating a whole marketplace (\`wave plugin marketplace update [name]\`, or the batch entry in either UI) to upgrade all of its plugins in batch.
 
 ### Marketplace Scopes
 

package/dist/builtin/skills/wave-daemon.d.ts

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

package/dist/builtin/skills/wave-daemon.js

@@ -0,0 +1,194 @@
+import { BASH_TOOL_NAME, READ_TOOL_NAME } from "../../constants/tools.js";
+export const waveDaemonSkill = {
+    "skills/wave-daemon/SKILL.md": `---
+name: wave-daemon
+description: Delegate a development or research task to a background wave daemon session — session creation in an isolated worktree, dispatching messages, aborting and re-scoping, monitoring progress, approving permissions, answering AskUserQuestion, and tearing sessions down with destroy.
+allowed-tools: ${BASH_TOOL_NAME}(wave daemon *), ${BASH_TOOL_NAME}(git *), ${READ_TOOL_NAME}
+---
+
+# Wave daemon delegation
+
+Delegate development work (code changes, bug fixes, features) and research work (reading code and producing conclusions — which often turns into code changes) to a **wave daemon session** instead of doing the long task inline. A daemon session runs in the background with no UI window, keeps generating while no client is attached, and survives client disconnects.
+
+The authoritative command reference is the Wave documentation, CLI → *Daemon client commands* (\`docs/cli.md\` in the Wave repo). This skill is the playbook: what to run, in what order, and the traps to avoid.
+
+## 0. Mental model
+
+- \`wave --daemon <socket>\` starts the daemon (server side). \`wave daemon <subcommand>\` is the client that talks to it. The two never interfere.
+- Every client subcommand connects to the fixed socket \`~/.wave/daemon.sock\` (\`$HOME/.wave/daemon.sock\`); there is no \`--socket\` override, so you are always talking to this machine's daemon for the current user.
+- The daemon is **resident**: once started it does not exit when idle. It goes away only when stopped (\`wave daemon stop\`), killed, restarted after a CLI upgrade, or the machine restarts. It is not supervised by pm2/systemd, so it does not come back by itself.
+- Every subcommand except \`stop\` starts a daemon on demand when the socket is absent, then retries. "No daemon is running" is therefore never a problem to work around — just run the command.
+- Sessions are persisted as transcripts under \`~/.wave/projects/<project>/<sessionId>.jsonl\`, so a session can be re-hosted from disk after the daemon restarts.
+- All subcommands are non-interactive: results on stdout, diagnostics on stderr.
+
+## 1. Daemon lifecycle
+
+\`\`\`bash
+wave daemon stop      # graceful: every hosted session is destroyed (each saves its transcript), the socket is removed, the process exits; idempotent ("Daemon is not running" when none is up)
+wave daemon restart   # stop the old daemon (if any), then start a fresh one from the current CLI
+\`\`\`
+
+**After upgrading the CLI, restart the daemon** — it runs the code it was started with and will not pick up a new build on its own. This is the main reason \`restart\` exists.
+
+One-off edge: \`stop\` / \`restart\` cannot stop a daemon that predates the \`shutdown\` RPC (i.e. one still running an older build). The wait times out — \`daemon did not exit within 10000ms\` — because the old process ignores the request and the socket stays up. Kill that process yourself, then run any client subcommand (e.g. \`wave daemon list\`) to start a daemon from the current CLI; \`restart\` works normally from then on.
+
+## 2. Creating a session
+
+\`\`\`bash
+wave daemon create --worktree [name] --workdir <dir> --permission-mode bypassPermissions
+\`\`\`
+
+- Prints the new sessionId on the first line (scripts read it from there), plus a second line with the worktree path and branch when \`--worktree\` was used.
+- \`--worktree\` creates the session in a fresh git worktree, so it never touches your main checkout. The name is optional — one is generated when omitted.
+- \`--permission-mode\` defaults to \`bypassPermissions\` for daemon-created sessions, so a session created this way raises no approval prompts at all. Passing the flag explicitly is redundant but fine and self-documenting. Valid modes: \`default\`, \`bypassPermissions\`, \`acceptEdits\`, \`plan\`, \`dontAsk\`.
+- \`--workdir\` defaults to the current directory.
+
+## 3. Dispatching work and following up
+
+\`\`\`bash
+wave daemon send <sessionId> <message>                # async dispatch (the default)
+wave daemon send <sessionId> <message> --wait 600     # wait up to 600s and print the reply
+\`\`\`
+
+- The default is fire-and-forget: the command exits 0 (printing \`Sent message to session: <sessionId>\`) as soon as the message is **delivered**. On an idle session it lands in history and the turn starts; on a busy session it is queued and takes effect when the current turn finishes.
+- \`--wait <seconds>\` blocks until the reply to *that* message arrives and prints only the assistant's final reply text. On timeout it exits non-zero; if the session is stuck on a pending approval it says so and points at \`respond\`.
+- A \`send --wait\` failure of \`Message aborted before producing a reply\` means the turn was interrupted mid-generation — the message was delivered, it just never produced text.
+
+**An interrupted send is not a lost message.** If the shell or tool running \`wave daemon send\` is interrupted or times out, the message may already have been delivered and be executing in the daemon. Verify with \`wave daemon status <sessionId>\` before resending — a duplicate send duplicates the work.
+
+To block on the work instead of checking it, follow the send with \`wave daemon wait <sessionId> --from-busy\` — the flag covers the moment right after an async send where the session still reports idle (§5).
+
+## 4. Changing your mind: abort first
+
+A \`send\` to a *generating* session is queued, not applied immediately — the current turn runs to completion first. To correct a task or change its scope mid-flight:
+
+\`\`\`bash
+wave daemon abort <sessionId>     # interrupt in-flight generation (subagents, bash commands and queued messages included)
+wave daemon send <sessionId> <corrected task>
+\`\`\`
+
+\`abort\` is idempotent and a no-op on an idle session, so it is safe to run without checking first. It does not clear completed history, and it does **not** touch the session's permission mode — the session stays live in the daemon's memory.
+
+## 5. Monitoring
+
+\`\`\`bash
+wave daemon list                   # sessions currently live in the daemon's in-memory registry
+wave daemon status <sessionId>     # one session: status, pending approvals, and the last message
+wave daemon wait <sessionId>       # block until it settles, then print that same snapshot
+wave daemon status <id> --lines 0  # status line only — no message text (single-shot snapshot)
+wave daemon status <id> --lines 5  # widen the context window when the last message is not enough
+\`\`\`
+
+\`status\` reports one of three states — \`idle\`, \`generating\`, or \`waiting for approval\` (listed with the pending request ids). It is plain text; there is no \`--json\`.
+
+\`--lines N\` prints the last N messages. **The default is 1** — the last message alone — because message text is never truncated, so a single long report is already tens of thousands of characters; the default has to stay bounded. N counts messages, not output lines.
+
+- \`--lines 0\` prints no message text at all — just the header and the \`Status:\` line. Use it when a snapshot only needs the status (cheaper than pulling a report you will not read).
+- text is whitespace-collapsed, and tool-only messages print nothing (they still count toward N);
+- it is the last N **messages**, so behind a long tail of intermediate narration ("still investigating…") the final report can fall outside the window.
+
+So the final report is what the default \`status <id>\` already gives you; raise \`--lines\` only when the last message is not the report you want.
+
+**To wait for the report, use \`wave daemon wait <sessionId>\`** — do not build a polling loop. It attaches, blocks until your session settles, then prints exactly what \`status <id> --lines N\` prints, so \`msg=$(wave daemon wait <id>)\` captures the report itself. Your session's own \`loadingChange\` push is only the **wake-up**: the idle verdict is read from the daemon registry when it wakes, and the daemon broadcasts every session's notifications to every connection, so a concurrent session's push is ignored (it can neither end the wait nor count as the busy phase). Its exit code is the contract:
+
+| exit | meaning |
+| ---- | ------- |
+| \`0\` | the session went idle — the snapshot on stdout is the final report |
+| \`3\` | the session is hanging on a permission approval — the snapshot lists the pending request ids; answer them with \`respond\` (§6) and \`wait\` again |
+| \`1\` | error — daemon unreachable, unknown sessionId, the session was destroyed while you waited, or \`--timeout\` elapsed |
+
+- A session that is already idle when you call it returns \`0\` immediately (it never hangs).
+- **\`--from-busy\` for the send-then-wait race.** An async \`send\` returns as soon as the message is *delivered*, so for a moment the session still reports idle and a plain \`wait\` would return before the turn even started. \`--from-busy\` makes the wait first observe a busy phase **of that session** (its own push, or the registry reporting it as generating), then idle — a concurrent session being busy does not count.
+- \`--timeout <seconds>\` bounds the wait (default: wait forever); on expiry it exits \`1\`.
+- \`--lines N\` (default 1) and \`--lines 0\` behave exactly as in \`status\`; progress lines go to stderr, stdout carries only the snapshot.
+- **Waiting on a session someone else destroys.** If another client runs \`wave daemon destroy <id>\` while you are blocked in \`wait\` (the daemon itself staying up), the wait does not hang: it notices the session left the registry and exits \`1\` with \`Session <id> no longer exists (destroyed while waiting)\` — a gone session is never reported as finished. The daemon drops the session from its registry *before* running the teardown, so this holds for the whole destroy window (the abort that clears the loading flag cannot be mistaken for a finished turn).
+- **A re-keyed or in-place-reconfigured session is not a destroyed one.** A live session can change its id (a cleared chat mints a new one): the daemon announces it and the wait follows the *same* session on the new id instead of exiting \`1\` (\`send --wait\` follows it too, so the reply is not missed). A config reload rebuilds the session's agent in place: while that runs the session stays listed, is reported busy (never "listed + idle"), reads keep answering, and writes are refused with a retryable error — so the wait keeps waiting; only a **failed** rebuild drops the session, and then \`1\` with the same "no longer exists" error is correct.
+
+**Unattended monitoring needs no wrapper script.** Those three exits cover every way a session can end: \`0\` = finished (stdout is the report), \`3\` = blocked on an approval (go \`respond\`, then \`wait\` again), \`1\` = error, including the session being destroyed out from under you. So \`msg=$(wave daemon wait <id>)\` plus a branch on the exit code replaces the hand-rolled poller completely — there is no fourth case left to poll for.
+
+If the CLI on that host predates \`wave daemon wait\`, fall back to a **background poll** — run it in the background rather than blocking on \`send --wait\`:
+
+\`\`\`bash
+while true; do
+  out=$(wave daemon status "$SESSION_ID" --lines 0)
+  echo "$out"
+  case "$out" in
+    *"Status: idle"*|*"waiting for approval"*) break ;;
+  esac
+  sleep 30
+done
+\`\`\`
+
+That loop is a pattern to re-create per session with whatever background-execution mechanism your host offers (on Windows, PowerShell's \`Start-Sleep\` in place of \`sleep\`), and one poller per session so they do not interfere. Prefer \`wait\`: one process, no poll latency, and an exit code that tells idle (0) apart from waiting-for-approval (3) and from error (1, a destroyed session included). \`waiting for approval\` is an action signal (go answer it, §6); \`idle\` means the turn settled and is worth a look.
+
+Do not hand-parse the transcript jsonl (\`~/.wave/projects/<project>/<sessionId>.jsonl\`) to recover a report — \`status <id>\` / \`wait <id>\` are the supported paths. If you ever do read the raw file: each line is one message (\`{"timestamp":…,"role":…,"blocks":[…]}\`) and text lives in \`blocks[].content\` on the \`{"type":"text"}\` block. There is no \`blocks[].text\` field, so a lookup by \`text\` silently returns nothing and looks like "the session never reported".
+
+An \`idle\` reading can also be a transient pause between turns (waiting on a verification run, a CI job, or a pending approval). Re-check \`status\` before concluding the task is finished, and if the session goes back to \`generating\`, block on it again (or \`wait --from-busy\` if the busy phase has not started yet).
+
+## 6. Permission approvals
+
+\`\`\`bash
+wave daemon respond <sessionId> <requestId> --allow
+wave daemon respond <sessionId> <requestId> --deny --reason "why"
+wave daemon respond <sessionId> <requestId> --allow --rule "Bash(ls)"              # persist this allow rule for the session
+wave daemon respond <sessionId> <requestId> --allow --mode bypassPermissions      # switch the session's permission mode
+\`\`\`
+
+- Exactly one of \`--allow\` / \`--deny\` is required. \`respond\` validates the requestId first (\`Request not found or already handled\`) and refuses to touch another session's request.
+- \`--mode\` also applies a mode switch, so after that one answer the session stops asking. Requests already queued still need their own \`respond\`.
+- An \`acceptEdits\` session asks for approval on every shell command; approving them one at a time cannot keep up with generation. Switch the mode with \`--mode bypassPermissions\` instead of responding in a loop.
+
+**The root cause of an approval flood is a restarted daemon process.** The permission mode is not recorded in the session transcript, so when a new daemon process re-hosts a session from disk (after \`stop\` / a kill, a CLI-upgrade restart, or a machine reboot), the mode is re-derived from the current configuration — \`permissions.defaultMode\` from settings, else \`default\`. A session created with \`bypassPermissions\` therefore comes back as \`default\` and starts asking for approvals.
+
+- \`abort\` does **not** cause this: the session stays in the daemon's memory with its mode intact. If approvals suddenly flood after a long interruption, look for a daemon restart, not for \`abort\`.
+- Recovery is one command: \`respond <requestId> --allow --mode bypassPermissions\`.
+- The symptom can be masked: if the repository's settings set \`permissions.defaultMode: bypassPermissions\`, the re-derived mode is bypass anyway and you will never see the fallback.
+
+## 7. AskUserQuestion requests
+
+\`status\` renders a pending \`AskUserQuestion\` in full: every question as \`Q<i> [header] <question>\`, with its options numbered from 0. Those option numbers are what \`--answer\` accepts.
+
+\`\`\`bash
+wave daemon respond <sessionId> <requestId> --allow --answer "0"       # option 0 of the only question
+wave daemon respond <sessionId> <requestId> --allow --answer "1,0"     # one option number per question, in order
+\`\`\`
+
+The older form still works: a JSON object keyed by the full question text, with the chosen option label as the value — exactly what the GUI dialog submits:
+
+\`\`\`bash
+wave daemon respond <sessionId> <requestId> --allow --answer '{"<full question text>":"<option label>"}'
+\`\`\`
+
+Whether to answer at all depends on whether the user is around:
+
+- If the user can see the session (they have the desktop app open), do not answer for them — relay the question and let them choose.
+- If the user has explicitly handed the work over and is away ("I'm offline, it's on you"), answer with the recommended option (the first one, or an option the question marks as recommended), then report what you answered so they can override it.
+
+Answering resolves the request and the session resumes generating on its own — no extra nudge is needed, though \`status\` may briefly still read \`generating\`.
+
+## 8. Finishing: destroy, and the worktree
+
+\`\`\`bash
+wave daemon destroy <sessionId> --remove-worktree
+\`\`\`
+
+- \`destroy\` is idempotent, and does not require the session to be live in the registry.
+- \`--remove-worktree\` is **two steps**: it resolves the session's worktree from its working directory and removes it (path + branch, through the worktree-removal protocol, which also fires the WorktreeRemove hook) and then destroys the session. It refuses to remove the main working tree, so a session that was not created in a linked worktree just fails that step.
+- Because it is two steps, an interrupted \`destroy --remove-worktree\` can be **half-done**: the worktree directory, its branch and uncommitted changes are already gone while the session is still alive. After such an interruption verify all three: \`wave daemon list\` / \`status\` (is the session still there?), \`git worktree list\` and the repo's worktree directory (folder + branch), and \`~/.wave/projects/\` (transcript). A session that was killed but whose transcript survives is still recoverable from the jsonl.
+- Destroy is destructive and irreversible: confirm with the user before running it.
+
+Whose session is it? Only tear down sessions you created with \`wave daemon create\`. Never destroy a session created by the desktop app — the user may still be using it — or one you do not recognize. If you cannot tell who created it, ask.
+
+## 9. Checklist
+
+- Create with \`--worktree\` and \`--permission-mode bypassPermissions\` (the mode default is already bypass, so no approvals appear).
+- \`send\` is async by default; after any interruption, check \`status\` before resending.
+- \`abort\` before re-scoping a running session.
+- Read the final report by blocking: \`wave daemon wait <id>\` (exit 0 = idle, 3 = stuck on an approval, 1 = error — session unknown or destroyed mid-wait; defaults to the last message, raise \`--lines\` if that one is not it). Use \`status <id>\` when you want a snapshot without blocking.
+- To watch a session unattended, loop on \`wait\` and branch on its exit code — no shell polling script to maintain (§5).
+- An approval flood means the daemon process restarted and the mode fell back — recover with \`--mode bypassPermissions\`.
+- After a CLI upgrade, \`wave daemon restart\` (kill the old process first if \`restart\` times out).
+- \`destroy --remove-worktree\` last, after user confirmation, only for sessions you created.
+- Sessions the desktop app manages churn quickly on their own; a shifting \`wave daemon list\` is normal, not a fault.
+`,
+};

package/dist/constants/images.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Outbound image dimension budget: the per-side pixel ceiling we deliberately
+ * keep every image under, aligned with Claude Code's `IMAGE_MAX_WIDTH` /
+ * `IMAGE_MAX_HEIGHT`.
+ *
+ * Two gates enforce it and they must agree on the number:
+ *
+ * - the webview paste path (`packages/webview/src/utils/imageValidation.ts`)
+ *   downsamples an oversized paste in the browser, before it becomes a message;
+ * - the SDK's outbound rewrite pass (`utils/imageRewrite.ts`, via sharp) is the
+ *   catch-all for every other source (Read tool, file paths, hosts that cannot
+ *   re-encode).
+ *
+ * The value lives here rather than in `utils/imageBudget.ts` because the
+ * webview is a browser bundle: by contract it may only take *values* from
+ * `wave-agent-sdk/constants`, and `utils/*` is not a public subpath. Copying
+ * `2000` into the webview would let the two gates drift apart silently — the
+ * paste would shrink to one number while the SDK judged by another.
+ *
+ * Not to be confused with the gateway's *hard* bound: `MAX_IMAGE_DIMENSION_PX`
+ * in `utils/imageDimensions.ts` (8192px per side) is where the upstream starts
+ * rejecting the whole request with `HTTP 400 ... unsupported image`. That one is
+ * an immovable external limit; this one is our own conservative budget and can
+ * be raised freely when we want more image fidelity.
+ */
+export declare const OUTBOUND_IMAGE_MAX_DIMENSION_PX = 2000;

package/dist/constants/images.js

@@ -0,0 +1,26 @@
+/**
+ * Outbound image dimension budget: the per-side pixel ceiling we deliberately
+ * keep every image under, aligned with Claude Code's `IMAGE_MAX_WIDTH` /
+ * `IMAGE_MAX_HEIGHT`.
+ *
+ * Two gates enforce it and they must agree on the number:
+ *
+ * - the webview paste path (`packages/webview/src/utils/imageValidation.ts`)
+ *   downsamples an oversized paste in the browser, before it becomes a message;
+ * - the SDK's outbound rewrite pass (`utils/imageRewrite.ts`, via sharp) is the
+ *   catch-all for every other source (Read tool, file paths, hosts that cannot
+ *   re-encode).
+ *
+ * The value lives here rather than in `utils/imageBudget.ts` because the
+ * webview is a browser bundle: by contract it may only take *values* from
+ * `wave-agent-sdk/constants`, and `utils/*` is not a public subpath. Copying
+ * `2000` into the webview would let the two gates drift apart silently — the
+ * paste would shrink to one number while the SDK judged by another.
+ *
+ * Not to be confused with the gateway's *hard* bound: `MAX_IMAGE_DIMENSION_PX`
+ * in `utils/imageDimensions.ts` (8192px per side) is where the upstream starts
+ * rejecting the whole request with `HTTP 400 ... unsupported image`. That one is
+ * an immovable external limit; this one is our own conservative budget and can
+ * be raised freely when we want more image fidelity.
+ */
+export const OUTBOUND_IMAGE_MAX_DIMENSION_PX = 2000;

package/dist/constants/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Constants entry (`wave-agent-sdk/constants`).
+ *
+ * Hosts that drive the agent over JSON-RPC import shared values from here rather
+ * than from the SDK barrel: the barrel pulls in the whole agent runtime,
+ * including dependencies that do work while their module body evaluates and can
+ * therefore take a host down at load time. Every module re-exported below must
+ * stay dependency-free so this entry remains cheap to bundle.
+ */
+export * from "./images.js";
+export * from "./memory.js";
+export * from "./messages.js";
+export * from "./plugins.js";
+export * from "./subagents.js";
+export * from "./toolLimits.js";
+export * from "./tools.js";

package/dist/constants/index.js

@@ -0,0 +1,16 @@
+/**
+ * Constants entry (`wave-agent-sdk/constants`).
+ *
+ * Hosts that drive the agent over JSON-RPC import shared values from here rather
+ * than from the SDK barrel: the barrel pulls in the whole agent runtime,
+ * including dependencies that do work while their module body evaluates and can
+ * therefore take a host down at load time. Every module re-exported below must
+ * stay dependency-free so this entry remains cheap to bundle.
+ */
+export * from "./images.js";
+export * from "./memory.js";
+export * from "./messages.js";
+export * from "./plugins.js";
+export * from "./subagents.js";
+export * from "./toolLimits.js";
+export * from "./tools.js";

package/dist/constants/memory.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Auto-memory taxonomy and entrypoint limits.
+ *
+ * The entrypoint (`MEMORY.md`) is an index that is always loaded into the
+ * conversation context, so it needs a hard size bound. A line cap alone does
+ * not provide one: a 200-line index of very long lines was observed at close
+ * to 200 KB. Both caps apply and the tighter one wins.
+ *
+ * Aligned with Claude Code's `memdir/memdir.ts` (MAX_ENTRYPOINT_LINES /
+ * MAX_ENTRYPOINT_BYTES); the second bound is counted in characters, not bytes
+ * — Claude Code's constant carries the BYTES name but its value is derived
+ * from "~125 chars/line at 200 lines" and is compared against `String.length`.
+ */
+export declare const MEMORY_ENTRYPOINT_NAME = "MEMORY.md";
+export declare const MAX_MEMORY_ENTRYPOINT_LINES = 200;
+export declare const MAX_MEMORY_ENTRYPOINT_CHARS = 25000;
+/** Recommended per-line length for `MEMORY.md` index entries. */
+export declare const MEMORY_INDEX_LINE_GUIDANCE_CHARS = 150;
+export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+/**
+ * Parse a raw frontmatter value into a MemoryType. Invalid or missing values
+ * return undefined — files written before the taxonomy existed keep working
+ * and unknown types degrade gracefully.
+ */
+export declare function parseMemoryType(raw: unknown): MemoryType | undefined;

package/dist/constants/memory.js

@@ -0,0 +1,34 @@
+/**
+ * Auto-memory taxonomy and entrypoint limits.
+ *
+ * The entrypoint (`MEMORY.md`) is an index that is always loaded into the
+ * conversation context, so it needs a hard size bound. A line cap alone does
+ * not provide one: a 200-line index of very long lines was observed at close
+ * to 200 KB. Both caps apply and the tighter one wins.
+ *
+ * Aligned with Claude Code's `memdir/memdir.ts` (MAX_ENTRYPOINT_LINES /
+ * MAX_ENTRYPOINT_BYTES); the second bound is counted in characters, not bytes
+ * — Claude Code's constant carries the BYTES name but its value is derived
+ * from "~125 chars/line at 200 lines" and is compared against `String.length`.
+ */
+export const MEMORY_ENTRYPOINT_NAME = "MEMORY.md";
+export const MAX_MEMORY_ENTRYPOINT_LINES = 200;
+export const MAX_MEMORY_ENTRYPOINT_CHARS = 25000;
+/** Recommended per-line length for `MEMORY.md` index entries. */
+export const MEMORY_INDEX_LINE_GUIDANCE_CHARS = 150;
+export const MEMORY_TYPES = [
+    "user",
+    "feedback",
+    "project",
+    "reference",
+];
+/**
+ * Parse a raw frontmatter value into a MemoryType. Invalid or missing values
+ * return undefined — files written before the taxonomy existed keep working
+ * and unknown types degrade gracefully.
+ */
+export function parseMemoryType(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    return MEMORY_TYPES.find((t) => t === raw);
+}