wave-agent-sdk 1.1.5 → 1.3.0

package/dist/types/permissions.d.ts

@@ -15,6 +15,8 @@ export interface PermissionDecision {
     newPermissionMode?: PermissionMode;
     /** Signal to persist a new allowed rule */
     newPermissionRule?: string;
+    /** Signal to add a directory to this session's Safe Zone (not persisted) */
+    newAdditionalDirectory?: string;
 }
 /** Callback function for custom permission logic */
 export type PermissionCallback = (context: ToolPermissionContext) => Promise<PermissionDecision>;
@@ -32,6 +34,12 @@ export interface ToolPermissionContext {
     suggestedPrefix?: string;
     /** Whether to hide the persistent permission option (e.g., "Don't ask again") in the UI */
     hidePersistentOption?: boolean;
+    /**
+     * Absolute path of the directory holding an out-of-Safe-Zone target, set for
+     * Edit/Write when the target lies outside the Safe Zone. Lets the confirmation
+     * UI offer adding that directory to the session Safe Zone.
+     */
+    outsideSafeZoneDirectory?: string;
     /** The ID of the tool call that triggered this permission request */
     toolCallId?: string;
     /** The content of the plan being exited from */
@@ -41,6 +49,20 @@ export interface ToolPermissionContext {
 }
 /** List of tools that require permission checks in default mode */
 export declare const RESTRICTED_TOOLS: readonly ["Edit", "Bash", "Write", "EnterPlanMode", "ExitPlanMode", "AskUserQuestion", "Artifact"];
+/**
+ * Tools that must still reach the user when permission checks are bypassed
+ * (`bypassPermissions` mode, or `plan` mode in a session holding the bypass
+ * authorization) — aligned with Claude Code's `requiresUserInteraction`:
+ * its permission pipeline returns the tool's own ask result before the
+ * bypass step can allow it.
+ *
+ * - `AskUserQuestion`: the tool *is* the question; bypassing it would strand
+ *   the agent without an answer.
+ * - `ExitPlanMode`: leaving plan mode is the user's approval of the plan, so
+ *   it stays a user decision even in a "don't ask me" session. This is the
+ *   one remaining gate on plan mode for such sessions (see plan-mode.md).
+ */
+export declare const USER_INTERACTION_REQUIRED_TOOLS: readonly ["AskUserQuestion", "ExitPlanMode"];
 /** Type for restricted tool names */
 export type RestrictedTool = (typeof RESTRICTED_TOOLS)[number];
 export declare const OPERATION_CANCELLED_BY_USER = "Operation cancelled by user";

package/dist/types/permissions.js

@@ -13,4 +13,21 @@ export const RESTRICTED_TOOLS = [
     ASK_USER_QUESTION_TOOL_NAME,
     ARTIFACT_TOOL_NAME,
 ];
+/**
+ * Tools that must still reach the user when permission checks are bypassed
+ * (`bypassPermissions` mode, or `plan` mode in a session holding the bypass
+ * authorization) — aligned with Claude Code's `requiresUserInteraction`:
+ * its permission pipeline returns the tool's own ask result before the
+ * bypass step can allow it.
+ *
+ * - `AskUserQuestion`: the tool *is* the question; bypassing it would strand
+ *   the agent without an answer.
+ * - `ExitPlanMode`: leaving plan mode is the user's approval of the plan, so
+ *   it stays a user decision even in a "don't ask me" session. This is the
+ *   one remaining gate on plan mode for such sessions (see plan-mode.md).
+ */
+export const USER_INTERACTION_REQUIRED_TOOLS = [
+    ASK_USER_QUESTION_TOOL_NAME,
+    EXIT_PLAN_MODE_TOOL_NAME,
+];
 export const OPERATION_CANCELLED_BY_USER = "Operation cancelled by user";

package/dist/types/plugins.d.ts

@@ -1,7 +1,7 @@
 import { CustomSlashCommand } from "./commands.js";
 import { Skill } from "./skills.js";
 import { LspConfig } from "./lsp.js";
-import { McpConfig } from "./mcp.js";
+import { McpConfig, McpServerConfig } from "./mcp.js";
 import { PartialHookConfiguration } from "./configuration.js";
 import { SubagentConfiguration } from "../utils/subagentParser.js";
 /**
@@ -10,10 +10,20 @@ import { SubagentConfiguration } from "../utils/subagentParser.js";
 export interface PluginManifest {
     name: string;
     description: string;
-    version: string;
+    /**
+     * Optional: plugins in the Claude Code ecosystem often omit it (spec plugin
+     * A-022). Install and load both fall back to `1.0.0`.
+     */
+    version?: string;
     author?: {
         name: string;
     };
+    /**
+     * Inline MCP server declarations, equivalent to a sibling `.mcp.json`
+     * (spec plugin A-023). Claude Code also allows a path string or array of
+     * paths here; only the object form is supported.
+     */
+    mcpServers?: Record<string, McpServerConfig>;
 }
 /**
  * Plugin configuration in AgentOptions or wave.settings.json
@@ -22,10 +32,24 @@ export interface PluginConfig {
     type: "local";
     path: string;
 }
+/** A plugin root that failed to load during the most recent load/reload. */
+export interface PluginLoadFailure {
+    path: string;
+    error: string;
+}
+/** Result of `Agent.reloadPlugins()` / `PluginManager.reloadAllPlugins()`. */
+export interface PluginReloadResult {
+    /** Plugin names loaded after the reload. */
+    plugins: string[];
+    /** Plugins that could not be loaded; the reload does not roll back. */
+    failures: PluginLoadFailure[];
+}
 /**
  * Represents a loaded plugin in the system
  */
 export interface Plugin extends PluginManifest {
+    /** Always resolved on load: a missing manifest version becomes `1.0.0` (A-022). */
+    version: string;
     path: string;
     commands: CustomSlashCommand[];
     skills: Skill[];

package/dist/types/skills.d.ts

@@ -6,6 +6,17 @@ export interface SkillMetadata {
     name: string;
     description: string;
     type: "personal" | "project" | "builtin";
+    /**
+     * Path to the skill **directory** (the folder containing SKILL.md), never
+     * to SKILL.md itself. Directory-level contract — all consumers rely on it:
+     * - `SkillManager.prepareSkillContent` injects this value for
+     *   `${WAVE_SKILL_DIR}` / `${CLAUDE_SKILL_DIR}` substitutions and reports it
+     *   as the "Base directory for this skill";
+     * - `SkillManager.deleteSkill` removes this path with `rm(recursive)`.
+     * Callers that need the file itself must `join(skillPath, "SKILL.md")`
+     * (misreading this as the file path broke the desktop "Edit" action,
+     * bug 3466438649392128).
+     */
     skillPath: string;
     allowedTools?: string[];
     context?: "fork";
@@ -80,6 +91,21 @@ export interface SkillParseOptions {
     validateMetadata?: boolean;
     basePath?: string;
 }
+/**
+ * A skill invocation recorded for context restoration (post-compaction
+ * re-injection, spec core/message-compact 场景 4).
+ */
+export interface InvokedSkillRecord {
+    skillName: string;
+    timestamp: number;
+    /**
+     * The content the model actually saw when the skill was invoked — directory
+     * placeholders already substituted, prefixed with
+     * `Base directory for this skill: <path>`. Re-injecting the raw SKILL.md
+     * instead would hand the model a literal `${WAVE_SKILL_DIR}`.
+     */
+    content?: string;
+}
 export declare const SKILL_DEFAULTS: {
     readonly PERSONAL_SKILLS_DIR: ".wave/skills";
     readonly PROJECT_SKILLS_DIR: ".wave/skills";

package/dist/utils/bashParser.d.ts

@@ -37,6 +37,23 @@ export declare const DANGEROUS_COMMANDS: string[];
  * FR-019.2 through FR-019.7 in tool-permission-system.md.
  */
 export declare const READ_ONLY_COMMANDS: string[];
+/**
+ * Subset of READ_ONLY_COMMANDS whose arguments are file paths (as opposed to
+ * strings, names, or flags, e.g. echo, pwd, which, basename). These commands
+ * must stay within the Safe Zone: a read-only command accessing a path outside
+ * the working directory / additional directories requires confirmation.
+ * Aligned with Claude Code's PathCommand list.
+ */
+export declare const PATH_COMMANDS: string[];
+/**
+ * Extract file path arguments from a command's argument string.
+ * Tokens starting with "-" are treated as flags and skipped; everything after
+ * a "--" separator counts as a path. Quoted path arguments are unquoted.
+ * Non-path tokens (e.g. a grep pattern) are harmless: they resolve against the
+ * working directory and typically do not exist, so isPathInside falls back to
+ * the nearest existing parent (the workdir itself) and stays inside.
+ */
+export declare function extractPathArgs(args: string): string[];
 /**
  * Registry of commands and their expected subcommand depth for smart prefix extraction.
  * For example, 'git: 2' means 'git commit' is a valid prefix, but 'git' alone is not.

package/dist/utils/bashParser.js

@@ -500,6 +500,78 @@ export const READ_ONLY_COMMANDS = [
     "bc",
     "sleep",
 ];
+/**
+ * Subset of READ_ONLY_COMMANDS whose arguments are file paths (as opposed to
+ * strings, names, or flags, e.g. echo, pwd, which, basename). These commands
+ * must stay within the Safe Zone: a read-only command accessing a path outside
+ * the working directory / additional directories requires confirmation.
+ * Aligned with Claude Code's PathCommand list.
+ */
+export const PATH_COMMANDS = [
+    "ls",
+    "find",
+    "cat",
+    "head",
+    "tail",
+    "wc",
+    "sort",
+    "uniq",
+    "grep",
+    "egrep",
+    "fgrep",
+    "rg",
+    "file",
+    "stat",
+    "du",
+    "df",
+    "tree",
+    "diff",
+    "cmp",
+    "md5sum",
+    "sha256sum",
+    "sha1sum",
+    "xxd",
+    "od",
+    "hexdump",
+    "strings",
+    "readlink",
+    "realpath",
+    "jq",
+    "yq",
+    "cut",
+    "paste",
+    "column",
+    "tr",
+    "awk",
+    "sed",
+];
+/**
+ * Extract file path arguments from a command's argument string.
+ * Tokens starting with "-" are treated as flags and skipped; everything after
+ * a "--" separator counts as a path. Quoted path arguments are unquoted.
+ * Non-path tokens (e.g. a grep pattern) are harmless: they resolve against the
+ * working directory and typically do not exist, so isPathInside falls back to
+ * the nearest existing parent (the workdir itself) and stays inside.
+ */
+export function extractPathArgs(args) {
+    const tokens = args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) || [];
+    const pathArgs = [];
+    let afterDoubleDash = false;
+    for (const token of tokens) {
+        if (afterDoubleDash) {
+            pathArgs.push(token);
+            continue;
+        }
+        if (token === "--") {
+            afterDoubleDash = true;
+            continue;
+        }
+        if (!token.startsWith("-")) {
+            pathArgs.push(token);
+        }
+    }
+    return pathArgs.map((p) => p.replace(/^['"](.*)['"]$/, "$1"));
+}
 /**
  * Global scope flags for git that only change the target repository or
  * configuration, not the subcommand being run. Shared by TOOL_RULES (smart

package/dist/utils/bashStructure/bashLexer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Tokenizer for the structure-aware bash parser.
+ *
+ * Unlike `bashParser.ts`'s text-based heuristics, this tokenizer understands
+ * bash quoting so that structural tokens (;, &&, ||, |, &, ( ), do/done/fi…)
+ * are only recognized OUTSIDE quotes/substitutions, and words keep enough
+ * internal structure for the semantic layer to tell quoted `"$f"` from bare
+ * `$f`.
+ *
+ * Words are tokenized into parts:
+ *   - lit        literal text (single-quoted or plain)
+ *   - var        `$name` / `${name}` expansion (name kept raw, unexpanded)
+ *   - special    `$@` `$*` `$?` `$$` `$!` `$#` `$-` `$0`..`$9`
+ *   - cmdsub     `$(...)` or backtick command substitution (text = inner)
+ *   - arith      `$((...))` — unsupported (dynamic), fail closed
+ *   - brace      `{a,b}` brace expansion — unsupported (dynamic)
+ *   - process    `<(cmd)` / `>(cmd)` process substitution — unsupported
+ * Each part records whether it appeared inside double quotes (`q: 'double'`)
+ * or bare (`q: 'none'`); single-quoted text is fully literal.
+ *
+ * The tokenizer FAILS (returns null) on any construct it cannot safely delimit
+ * (unterminated quotes / $( / backticks / heredocs). Failures are surfaced by
+ * the caller as a fail-closed `unsupported` parse result.
+ */
+export type QuoteCtx = "none" | "single" | "double";
+export type WordPart = {
+    t: "lit";
+    v: string;
+    q: QuoteCtx;
+} | {
+    t: "var";
+    name: string;
+    q: "none" | "double";
+} | {
+    t: "special";
+    name: string;
+    q: "none" | "double";
+} | {
+    t: "cmdsub";
+    text: string;
+    q: "none" | "double";
+} | {
+    t: "arith";
+    q: "none" | "double";
+} | {
+    t: "brace";
+    v: string;
+    q: "none" | "double";
+} | {
+    t: "process";
+    text: string;
+    q: "none" | "double";
+};
+export interface WordToken {
+    t: "word";
+    /** Raw word text as written (quotes and $ references preserved). */
+    raw: string;
+    /** Inner structure for the semantic layer. */
+    parts: WordPart[];
+}
+export type OpToken = "&&" | "||" | "|" | "|&" | ";" | ";;" | ";&" | ";;&" | "&" | "(" | ")" | "newline" | "{" | "}";
+export interface OpTok {
+    t: "op";
+    op: OpToken;
+}
+export interface NlTok {
+    t: "nl";
+}
+export type Token = WordToken | OpTok | NlTok | {
+    t: "eof";
+};
+/** Raw tokenizer failure: a construct we cannot model → ask (fail closed). */
+export type LexFailureReason = "heredoc" | "unterminated" | "unexpected-char" | "length-limit";
+export declare function isVariableNameStart(ch: string): boolean;
+/**
+ * Classify a redirection operator word emitted by the tokenizer.
+ * Returns "plain" when the operator still needs a separate following target
+ * word (`>`, `2>`, `>>`, `&>`, `>&` …), "folded" when the target is already
+ * part of the operator token (`2>&1`, `>&-`), or null when the word is not a
+ * redirection operator.
+ *
+ * The raw word may carry an optional file-descriptor digit prefix (`2>`) and
+ * the dup operators `<&`/`>&` may fold their fd/- target when it directly
+ * touches the operator (`2>&1` must stay one token so the reconstructed text
+ * remains faithful — legacy `2>& 1` text checks would mis-read the target).
+ */
+export declare function redirectOpKind(raw: string): "plain" | "folded" | null;
+/** True when the raw text is a redirection operator (fd prefix allowed). */
+export declare function isRedirectRaw(raw: string): boolean;
+/** Whether a word token is a redirection operator (raw literal, no quoting). */
+export declare function isRedirectWord(w: WordToken): boolean;
+/**
+ * Tokenize a bash command string. Returns tokens or null on a lexical
+ * construct we deliberately do not support (fail closed).
+ */
+export declare function tokenize(input: string): Token[] | null;