@warlock.js/ai-workspace 5.30.0 → 5.32.0

package/esm/contracts/workspace-policy.type.d.mts

@@ -7,34 +7,131 @@
  * The worktree and container backends from the design doc are deferred
  * past the W1 surface and intentionally absent from this union.
  */
-type WorkspaceBackendType = "local" | "mock";
+export type WorkspaceBackendType = "local" | "mock";
+/**
+ * How `run_shell` / `exec()` interpret a command line.
+ *
+ * - `"none"` (default) — **argv mode**: the line is tokenized into one argv
+ *   (quotes respected, no shell semantics) and spawned without a shell. Any
+ *   unquoted shell operator is refused with a message that says how to split
+ *   the line.
+ * - `"sh"` — **shell mode** (explicit opt-in): the line runs through
+ *   `/bin/sh -c` (`cmd.exe /d /v:off /s /c` on Windows). Before it runs, the
+ *   line is parsed and every simple command in it — inside `;`, `&&`, `||`,
+ *   pipes, subshells, `$( )` and backticks — is checked against the same
+ *   `deny` / `allow` / `denyPatterns` / `allowCommand` rules, and every
+ *   redirection target and `cd` directory against the path jail. Syntax the
+ *   parser cannot read with confidence is refused, never guessed at.
+ */
+export type WorkspaceShellInterpreter = "none" | "sh";
+/**
+ * A command pattern in `shell.denyPatterns`.
+ *
+ * - A **string** is tokenized like a command and matches a command whose
+ *   argv **starts with** those tokens — the executable compared by basename,
+ *   case-insensitively. `"git push --force"` matches
+ *   `git push --force origin main` but not `git push origin --force`.
+ * - A **RegExp** is tested against the command's argv joined with single
+ *   spaces, the executable reduced to its basename (`/usr/bin/git  push`
+ *   is tested as `"git push"`). Use it for option orders and spellings:
+ *   `/^git push\b.*(--force|-f\b)/`. A `g`/`y` flag is ignored.
+ */
+export type WorkspaceCommandPattern = string | RegExp;
+/** What {@link WorkspaceAllowCommand} is told about the command it checks. */
+export interface WorkspaceCommandCheckContext {
+  /** The full command line the checked command is part of. */
+  command: string;
+  /** The interpreter the line runs under. */
+  interpreter: WorkspaceShellInterpreter;
+  /**
+   * True when the argv is a command run through a wrapper the policy
+   * unwrapped (`time npm test` is checked as `["time", "npm", "test"]` and
+   * then as the nested `["npm", "test"]`) or by `find -exec`.
+   */
+  nested: boolean;
+}
+/**
+ * A host predicate over every simple command's argv. Return `true` to let
+ * the command through, `false` to refuse it, or a string to refuse it with
+ * that explanation (shown to the model). A throw refuses the command too —
+ * the hook fails closed. It can only narrow what `allow` / `deny` permit,
+ * never widen it, and it must be synchronous.
+ *
+ * @example
+ * allowCommand: (argv) =>
+ *   argv[0] === "git" && argv[1] === "push" ? "Pushing is done by the release job." : true
+ */
+export type WorkspaceAllowCommand = (argv: readonly string[], context: WorkspaceCommandCheckContext) => boolean | string;
+/**
+ * Background-command sub-policy. Present ⇒ `run_shell({ background: true })`
+ * and `startShell()` may start long-running commands (dev servers,
+ * watchers) that belong to the workspace; absent ⇒ background commands are
+ * refused. Every background command is killed — its whole process tree —
+ * by `workspace.dispose()`, and when the Node process exits.
+ */
+export interface WorkspaceBackgroundPolicy {
+  /** Most background commands running at once. Default `4`. */
+  maxJobs?: number;
+  /**
+   * Wall-clock cap for one background command, after which its process tree
+   * is killed (`status: "timed-out"`). Default: none — it runs until killed
+   * or disposed. A model-supplied `timeoutMs` can only lower it.
+   */
+  timeoutMs?: number;
+}
 /**
  * Shell-execution sub-policy for `run_shell` / `run_tests` and the
  * `exec()` direct method.
  *
- * **Command gating.** Each command is tokenized into an argv (quotes
- * respected, NO shell semantics) and executed without a shell; a command
- * containing unquoted shell metacharacters (`;`, `&`, `|`, backticks,
- * `$`, redirection, parentheses) is denied outright, so metacharacters
- * cannot chain extra commands past the gate. The argv's leading
- * executable basename is matched against `allow` / `deny`; **deny wins**
- * when a name appears in both. An empty/absent `allow` means no command
- * is permitted unless the policy explicitly opts in — the workspace is
- * fail-closed.
+ * **Command gating.** By default (`interpreter: "none"`) each command is
+ * tokenized into an argv (quotes respected, NO shell semantics) and executed
+ * without a shell; a command containing unquoted shell metacharacters (`;`,
+ * `&`, `|`, backticks, `$`, redirection, parentheses) is refused with a
+ * message that names the operator and suggests the split. With
+ * `interpreter: "sh"` the line runs through a shell, and every simple
+ * command in it is checked. Each command's executable basename is matched
+ * against `allow` / `deny`; **deny wins** (and matches case-insensitively).
+ * A non-empty `allow` is exhaustive. `denyPatterns` and `allowCommand`
+ * then refine the decision per argv. A command that would run another
+ * command out of the policy's sight (`bash -c`, `eval`, `xargs`, `sudo`, …)
+ * is refused when the policy has deny rules, unless it is named in `allow`.
  *
  * **Environment.** The spawned process does NOT inherit `process.env`.
  * The effective environment is `{ ...pick(process.env, inheritEnv), ...env }`
  * — so `run_shell` cannot find `node`/`npm` unless `inheritEnv` includes
- * `"PATH"`. This is deliberate isolation, documented loudly.
+ * `"PATH"`. This is deliberate isolation, documented loudly. Shell mode also
+ * drops the variables that change how a shell parses or starts (`ENV`,
+ * `BASH_ENV`, `SHELLOPTS`, `BASHOPTS`, `CDPATH`, `IFS`, `PS4`, `BASH_FUNC_*`).
  */
-interface WorkspaceShellPolicy {
+export interface WorkspaceShellPolicy {
   /** Allowed executable basenames (e.g. `["npm", "node"]`). */
   allow?: string[];
   /** Denied executable basenames — wins over `allow`. */
   deny?: string[];
+  /**
+   * Argument-level denials checked against every simple command (see
+   * {@link WorkspaceCommandPattern}), e.g. `["rm -rf /", "git push --force"]`.
+   */
+  denyPatterns?: WorkspaceCommandPattern[];
+  /**
+   * Host predicate over every simple command's argv (see
+   * {@link WorkspaceAllowCommand}).
+   */
+  allowCommand?: WorkspaceAllowCommand;
+  /**
+   * How the command line is interpreted. Default `"none"` (argv mode, no
+   * shell). `"sh"` is an explicit opt-in to shell syntax — pipes, `&&`,
+   * redirections — still checked per simple command (see
+   * {@link WorkspaceShellInterpreter}).
+   */
+  interpreter?: WorkspaceShellInterpreter;
   /** Per-command wall-clock cap; on expiry the process is SIGKILLed. */
   timeoutMs?: number;
-  /** Max bytes captured from stdout/stderr before output is truncated. */
+  /**
+   * Max bytes captured from stdout/stderr before output is truncated. For a
+   * background command it is the most output kept per command; older output
+   * is dropped first.
+   */
   maxOutputBytes?: number;
   /** Explicit environment variables injected into every spawned process. */
   env?: Record<string, string>;
@@ -43,12 +140,17 @@ interface WorkspaceShellPolicy {
    * Nothing from `process.env` leaks in unless listed here.
    */
   inheritEnv?: string[];
+  /**
+   * Enables background commands (see {@link WorkspaceBackgroundPolicy}).
+   * Absent ⇒ `run_shell({ background: true })` is refused.
+   */
+  background?: WorkspaceBackgroundPolicy;
 }
 /**
  * Read sub-policy controlling how much of a file a single read returns.
  * Applies equally to the `read_file` tool and the `readFile()` direct method.
  */
-interface WorkspaceReadPolicy {
+export interface WorkspaceReadPolicy {
   /**
    * Hard cap on the UTF-8 bytes of the `content` a single read returns,
    * line-number prefixes and newlines included. A window that would exceed
@@ -60,6 +162,23 @@ interface WorkspaceReadPolicy {
   /** Default number of lines a read returns when no explicit limit is given. */
   defaultLines?: number;
 }
+/**
+ * Directory-listing sub-policy for the `list_dir` tool and `listDir()`.
+ * `denyPaths` are always hidden from listings; `ignore` hides more without
+ * blocking access (an ignored file can still be read).
+ */
+export interface WorkspaceListPolicy {
+  /**
+   * Globs (`*`, `**`, `?`; a bare name also hides its contents) left out of
+   * listings. Default `["node_modules", ".git"]`; setting it replaces the
+   * default.
+   */
+  ignore?: string[];
+  /** Deepest `depth` a listing may ask for. Default `5`. */
+  maxDepth?: number;
+  /** Most entries one listing returns; the rest set `truncated`. Default `500`. */
+  maxEntries?: number;
+}
 /**
  * The full policy that bounds a workspace — the single source of truth
  * the policy engine enforces for both `.tools.*` and the direct methods.
@@ -79,7 +198,7 @@ interface WorkspaceReadPolicy {
  *   backend: "local",
  * };
  */
-interface WorkspacePolicy {
+export interface WorkspacePolicy {
   /** Absolute jail root — the workspace cannot read or write outside it. */
   cwd: string;
   /** Extra readable roots outside `cwd` (resolved absolute paths). */
@@ -90,9 +209,10 @@ interface WorkspacePolicy {
   shell?: WorkspaceShellPolicy;
   /** Read sub-policy (byte cap + default line window). */
   read?: WorkspaceReadPolicy;
+  /** Directory-listing sub-policy (ignore globs + bounds). */
+  list?: WorkspaceListPolicy;
   /** Executor the workspace runs on. Defaults to `"local"`. */
   backend?: WorkspaceBackendType;
 }
 //#endregion
-export { WorkspaceBackendType, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellPolicy };
 //# sourceMappingURL=workspace-policy.type.d.mts.map

package/esm/contracts/workspace-policy.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-policy.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-policy.type.ts"],"mappings":";;AAQA;;;;AAAgC;AAqBhC;;KArBY,oBAAA;;;;;;;;;;AAoCA;AAOZ;;;;AAUc;AAsBd;;;;UAtDiB,oBAAA;EAkEL;EAhEV,KAAA;EAgE8B;EA9D9B,IAAA;EAsDA;EApDA,SAAA;EAwDA;EAtDA,cAAA;EAwDA;EAtDA,GAAA,GAAM,MAAM;EAwDZ;;;AAA8B;EAnD9B,UAAA;AAAA;;;;;UAOe,mBAAA;;;;;;;;EAQf,QAAA;;EAEA,YAAY;AAAA;;;;;;;;;;;;;;;;;;;;UAsBG,eAAA;;EAEf,GAAA;;EAEA,UAAA;;EAEA,SAAA;;EAEA,KAAA,GAAQ,oBAAA;;EAER,IAAA,GAAO,mBAAA;;EAEP,OAAA,GAAU,oBAAA;AAAA"}
+{"version":3,"file":"workspace-policy.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-policy.type.ts"],"mappings":";;;;;;;;;YAQY;;;;;;;;;;;;;;;;YAiBA;;;;;;;;;;;;;YAcA,mCAAmC;;iBAG9B;;EAEf;;EAEA,aAAa;;;;;;EAMb;;;;;;;;;;;;;YAcU,yBACV,yBACA,SAAS;;;;;;;;iBAUM;;EAEf;;;;;;EAMA;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2Be;;EAEf;;EAEA;;;;;EAKA,eAAe;;;;;EAKf,eAAe;;;;;;;EAOf,cAAc;;EAEd;;;;;;EAMA;;EAEA,MAAM;;;;;EAKN;;;;;EAKA,aAAa;;;;;;iBAOE;;;;;;;;EAQf;;EAEA;;;;;;;iBAQe;;;;;;EAMf;;EAEA;;EAEA;;;;;;;;;;;;;;;;;;;;;iBAsBe;;EAEf;;EAEA;;EAEA;;EAEA,QAAQ;;EAER,OAAO;;EAEP,OAAO;;EAEP,UAAU"}

package/esm/contracts/workspace.contract.d.mts

@@ -1,7 +1,6 @@
-import { EditFileInput, EditFileResult, ExecOptions, GrepResult, ReadFileResult, RunShellResult, WorkspaceToolName } from "./tool-io.type.mjs";
+import { EditFileInput, EditFileResult, ExecOptions, GrepResult, ListDirOptions, ListDirResult, MultiEditInput, MultiEditResult, ReadFileResult, RunShellResult, ShellJobInfo, ShellOutputOptions, ShellOutputResult, StartShellOptions, TodoListResult, WorkspaceTodoInput, WorkspaceToolName } from "./tool-io.type.mjs";
 import { WorkspacePolicy } from "./workspace-policy.type.mjs";
 import { ToolContract } from "@warlock.js/ai";
-
 //#region ../../packages/ai-workspace/src/contracts/workspace.contract.d.ts
 /**
  * The agent-facing tool surface of a workspace. Each factory returns a
@@ -13,8 +12,12 @@ import { ToolContract } from "@warlock.js/ai";
  * expose the same capability under a custom tool name when wiring
  * multiple agents.
  */
-interface WorkspaceTools {
-  /** All seven tools as `ToolContract[]`, ready for `ai.agent({ tools })`. */
+export interface WorkspaceTools {
+  /**
+   * Every tool this workspace vends, as `ToolContract[]`, ready for
+   * `ai.agent({ tools })`. `shell_output` / `shell_kill` are included only
+   * when the policy enables background commands (`shell.background`).
+   */
   all(): ToolContract[];
   /** A named subset, e.g. `pick("readFile", "grep")` for least privilege. */
   pick(...names: WorkspaceToolName[]): ToolContract[];
@@ -26,14 +29,30 @@ interface WorkspaceTools {
   editFile(opts?: {
     name?: string;
   }): ToolContract;
+  /** The `multi_edit` tool (several replacements in one file, all or none). */
+  multiEdit(opts?: {
+    name?: string;
+  }): ToolContract;
   /** The `write_file` tool (atomic full-content write). */
   writeFile(opts?: {
     name?: string;
   }): ToolContract;
-  /** The `run_shell` tool (policy-gated command execution). */
+  /** The `list_dir` tool (bounded, jailed directory listing). */
+  listDir(opts?: {
+    name?: string;
+  }): ToolContract;
+  /** The `run_shell` tool (policy-gated command execution, optionally in the background). */
   runShell(opts?: {
     name?: string;
   }): ToolContract;
+  /** The `shell_output` tool (read a background command's new output). */
+  shellOutput(opts?: {
+    name?: string;
+  }): ToolContract;
+  /** The `shell_kill` tool (stop a background command). */
+  shellKill(opts?: {
+    name?: string;
+  }): ToolContract;
   /** The `run_tests` tool (runs the configured test command). */
   runTests(opts?: {
     name?: string;
@@ -47,6 +66,14 @@ interface WorkspaceTools {
   glob(opts?: {
     name?: string;
   }): ToolContract;
+  /** The `todo_write` tool (replace the workspace's todo list). */
+  todoWrite(opts?: {
+    name?: string;
+  }): ToolContract;
+  /** The `todo_read` tool (read the workspace's todo list). */
+  todoRead(opts?: {
+    name?: string;
+  }): ToolContract;
 }
 /**
  * The bounded place an agent reads, writes, and runs commands — a
@@ -54,12 +81,11 @@ interface WorkspaceTools {
  * ops layer, two ways to touch it: the agent uses `.tools.*`; you use the
  * direct methods.
  *
- * This is the **W1 surface only**: the policy jail, the seven tools, the
- * direct methods, `tools.all()` / `tools.pick()`, plus the two
- * composition projections `readonly()` and `scope()`. The transactional
- * lifecycle (`snapshot` / `restore` / `diff` / `changes`), hooks
- * (`on`), `dispose`, `usage`, and the worktree/container backends are
- * deferred to later phases and intentionally absent here.
+ * The surface: the policy jail, the tools, the direct methods,
+ * `tools.all()` / `tools.pick()`, the two composition projections
+ * `readonly()` and `scope()`, background commands, a todo list, and
+ * `dispose()`. Projections share their parent's background commands and
+ * todo list; disposing any of them disposes the whole workspace.
  *
  * @example
  * const ws = ai.workspace({ cwd: "/srv/acme-api", shell: { allow: ["npm"], inheritEnv: ["PATH"] } });
@@ -71,7 +97,7 @@ interface WorkspaceTools {
  * await ws.writeFile("src/routes.ts", BOILERPLATE);
  * const files = await ws.glob("src/models/**\/*.ts");
  */
-interface Workspace {
+export interface Workspace {
   /** The immutable policy bounding this workspace. */
   readonly policy: WorkspacePolicy;
   /** Agent-facing tool factories. */
@@ -93,12 +119,39 @@ interface Workspace {
   }>;
   /** Apply an exact-string edit under the read-before-edit stale guard. */
   editFile(input: EditFileInput): Promise<EditFileResult>;
+  /** Apply several exact-string edits to one file — all of them or none. */
+  multiEdit(input: MultiEditInput): Promise<MultiEditResult>;
+  /** List a jailed directory (bounded, ignores applied, symlinks not followed). */
+  listDir(path?: string, opts?: ListDirOptions): Promise<ListDirResult>;
   /**
    * Run a policy-gated shell command and capture its outcome. `signal`
    * cancels this one call: not started when already aborted, process tree
    * killed when it aborts mid-run, `cancelled: true` either way.
    */
   exec(command: string, opts?: ExecOptions): Promise<RunShellResult>;
+  /**
+   * Start a policy-checked background command owned by this workspace
+   * (needs `shell.background`). It runs until it exits, `shellKill(id)`,
+   * its timeout, or `dispose()`.
+   */
+  startShell(command: string, opts?: StartShellOptions): Promise<ShellJobInfo>;
+  /** New output of a background command since `since` (default: the last read). */
+  shellOutput(id: string, opts?: ShellOutputOptions): Promise<ShellOutputResult>;
+  /** Kill a background command's whole process tree. */
+  shellKill(id: string): Promise<ShellJobInfo>;
+  /** Every background command this workspace knows, oldest first. */
+  listShells(): ShellJobInfo[];
+  /** The workspace's todo list (what `todo_read` returns). */
+  readTodos(): TodoListResult;
+  /** Replace the workspace's todo list (what `todo_write` does). */
+  writeTodos(todos: WorkspaceTodoInput[]): TodoListResult;
+  /**
+   * Close the workspace: kill every background command's process tree and
+   * refuse new commands (a foreground command already running finishes on
+   * its own, or by its timeout / signal). Idempotent; resolves once the
+   * background processes are gone.
+   */
+  dispose(): Promise<void>;
   /** Search jailed file contents for a regex pattern. */
   grep(pattern: string, opts?: {
     glob?: string;
@@ -126,5 +179,4 @@ interface Workspace {
   scope(subdir: string): Workspace;
 }
 //#endregion
-export { Workspace, WorkspaceTools };
 //# sourceMappingURL=workspace.contract.d.mts.map

package/esm/contracts/workspace.contract.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace.contract.ts"],"mappings":";;;;;;;AAsBA;;;;;;;;UAAiB,cAAA;EAYqB;EAVpC,GAAA,IAAO,YAAA;EAcyB;EAZhC,IAAA,IAAQ,KAAA,EAAO,iBAAA,KAAsB,YAAA;EAcO;EAZ5C,QAAA,CAAS,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAFpC;EAIA,QAAA,CAAS,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAFpC;EAIA,SAAA,CAAU,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAFrC;EAIA,QAAA,CAAS,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAFpC;EAIA,QAAA,CAAS,IAAA;IAAS,IAAA;IAAe,OAAA;EAAA,IAAqB,YAAA;EAFpC;EAIlB,IAAA,CAAK,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAFd;EAIlB,IAAA,CAAK,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;AAAA;;;;;;;;;AAAY;AA0B9C;;;;;;;;;;;;;;UAAiB,SAAA;EAsCZ;EAAA,SApCM,MAAA,EAAQ,eAAA;EA0CK;EAAA,SAvCb,KAAA,EAAO,cAAA;EA6CM;;;;;;EArCtB,QAAA,CACE,IAAA,UACA,IAAA;IAAS,MAAA;IAAiB,KAAA;EAAA,IACzB,OAAA,CAAQ,cAAA;EAFT;EAKF,SAAA,CACE,IAAA,UACA,OAAA,WACC,OAAA;IAAU,IAAA;IAAc,YAAA;EAAA;EANhB;EASX,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,cAAA;EALtC;;;;;EAYF,IAAA,CAAK,OAAA,UAAiB,IAAA,GAAO,WAAA,GAAc,OAAA,CAAQ,cAAA;EAPnC;EAUhB,IAAA,CACE,OAAA,UACA,IAAA;IAAS,IAAA;IAAe,UAAA;EAAA,IACvB,OAAA,CAAQ,UAAA;EANN;EASL,IAAA,CAAK,OAAA,WAAkB,OAAA;EATD;EAYtB,MAAA,CAAO,IAAA,WAAe,OAAA;EAZ6B;EAenD,KAAA,CAAM,IAAA,WAAe,OAAA;EAXnB;EAcF,MAAA,CAAO,IAAA,WAAe,OAAA;EAbI;;;;;EAoB1B,QAAA,IAAY,SAAA;EAhBW;;;;;EAuBvB,KAAA,CAAM,MAAA,WAAiB,SAAA;AAAA"}
+{"version":3,"file":"workspace.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace.contract.ts"],"mappings":";;;;;;;;;;;;;;iBAgCiB;;;;;;EAMf,OAAO;;EAEP,QAAQ,OAAO,sBAAsB;;EAErC,SAAS;IAAS;MAAkB;;EAEpC,SAAS;IAAS;MAAkB;;EAEpC,UAAU;IAAS;MAAkB;;EAErC,UAAU;IAAS;MAAkB;;EAErC,QAAQ;IAAS;MAAkB;;EAEnC,SAAS;IAAS;MAAkB;;EAEpC,YAAY;IAAS;MAAkB;;EAEvC,UAAU;IAAS;MAAkB;;EAErC,SAAS;IAAS;IAAe;MAAqB;;EAEtD,KAAK;IAAS;MAAkB;;EAEhC,KAAK;IAAS;MAAkB;;EAEhC,UAAU;IAAS;MAAkB;;EAErC,SAAS;IAAS;MAAkB;;;;;;;;;;;;;;;;;;;;;;;;iBAyBrB;;WAEN,QAAQ;;WAGR,OAAO;;;;;;;EAQhB,SAAS,cAAc;IAAS;IAAiB;MAAmB,QAAQ;;EAG5E,UAAU,cAAc,kBAAkB;IAAU;IAAc;;;EAGlE,SAAS,OAAO,gBAAgB,QAAQ;;EAGxC,UAAU,OAAO,iBAAiB,QAAQ;;EAG1C,QAAQ,eAAe,OAAO,iBAAiB,QAAQ;;;;;;EAOvD,KAAK,iBAAiB,OAAO,cAAc,QAAQ;;;;;;EAOnD,WAAW,iBAAiB,OAAO,oBAAoB,QAAQ;;EAG/D,YAAY,YAAY,OAAO,qBAAqB,QAAQ;;EAG5D,UAAU,aAAa,QAAQ;;EAG/B,cAAc;;EAGd,aAAa;;EAGb,WAAW,OAAO,uBAAuB;;;;;;;EAQzC,WAAW;;EAGX,KAAK,iBAAiB;IAAS;IAAe;MAAyB,QAAQ;;EAG/E,KAAK,kBAAkB;;EAGvB,OAAO,eAAe;;EAGtB,MAAM,eAAe;;EAGrB,OAAO,eAAe;;;;;;EAOtB,YAAY;;;;;;EAOZ,MAAM,iBAAiB"}

package/esm/errors.d.mts

@@ -1,28 +1,63 @@
 import { AIError, AIErrorOptions } from "@warlock.js/ai";
-
 //#region ../../packages/ai-workspace/src/errors.d.ts
 /**
  * Why a workspace policy check rejected an operation.
  *
  * - `"path-escape"` — a resolved path fell outside the `cwd` jail (or an
  *   `allowPaths` root), or matched a `denyPaths` glob.
- * - `"denied-command"` — a shell command's leading executable basename
- *   was not in `shell.allow`, or was explicitly in `shell.deny`.
+ * - `"denied-command"` — the shell policy refused a command line (`reason`
+ *   says why: an executable outside `shell.allow` or inside `shell.deny`, a
+ *   metacharacter in argv mode, a redirection outside the jail in shell
+ *   mode, …), or a mutating method was called on a read-only projection.
  * - `"unsafe-pattern"` — a `grep` pattern was too long or matched a
  *   catastrophic-backtracking shape (nested quantifiers) that could hang
  *   the process (ReDoS).
  */
-type WorkspacePolicyViolation = "path-escape" | "denied-command" | "unsafe-pattern";
+export type WorkspacePolicyViolation = "path-escape" | "denied-command" | "unsafe-pattern";
+/**
+ * Why the shell policy refused a command. Set on every
+ * {@link WorkspacePolicyError} of type `"denied-command"` raised for a
+ * command line, so a host can phrase the refusal itself instead of parsing
+ * the message.
+ *
+ * - `"metacharacter"` — argv mode (the default `interpreter: "none"`) met an
+ *   unquoted shell operator (`&&`, `;`, `|`, `>`, `$`, backticks, …). The
+ *   message suggests how to split the line into separate commands.
+ * - `"unbalanced-quotes"` — a quote is never closed.
+ * - `"denied-executable"` — a command's executable is listed in `shell.deny`.
+ * - `"not-allowed"` — a command's executable is not in `shell.allow`, the
+ *   `shell.allowCommand` hook refused it, the workspace has no shell policy,
+ *   the line is empty, or background commands are not enabled.
+ * - `"denied-pattern"` — a command matched one of `shell.denyPatterns`.
+ * - `"nested-command"` — a command runs another command the policy cannot
+ *   inspect (`bash -c …`, `eval`, `xargs`, `sudo`, a wrapper with options the
+ *   policy cannot read), while the policy has deny rules it would bypass.
+ * - `"unsupported-syntax"` — shell mode (`interpreter: "sh"`) met syntax the
+ *   policy does not parse with confidence (compound commands, arithmetic,
+ *   brace expansion, background `&`, a command name decided at run time, …),
+ *   so the line is refused rather than guessed at.
+ * - `"path-escape"` — shell mode: a redirection target or `cd` directory
+ *   resolves outside the workspace jail or hits `denyPaths`.
+ */
+export type WorkspaceShellRefusalReason = "metacharacter" | "unbalanced-quotes" | "denied-executable" | "not-allowed" | "denied-pattern" | "nested-command" | "unsupported-syntax" | "path-escape";
 /**
  * Options for {@link WorkspacePolicyError} — the structured `type`
  * discriminator plus, where relevant, the offending path or command for
  * branchable diagnostics without parsing the message.
  */
-type WorkspacePolicyErrorOptions = AIErrorOptions & {
-  /** Which policy rule was violated. */type: WorkspacePolicyViolation; /** The offending workspace-relative path (for `"path-escape"`). */
-  path?: string; /** The offending command line (for `"denied-command"`). */
-  command?: string; /** The offending regex pattern (for `"unsafe-pattern"`). */
+export type WorkspacePolicyErrorOptions = AIErrorOptions & {
+  /** Which policy rule was violated. */
+  type: WorkspacePolicyViolation;
+  /** The offending workspace-relative path (for `"path-escape"`). */
+  path?: string;
+  /** The offending command line (for `"denied-command"`). */
+  command?: string;
+  /** The offending regex pattern (for `"unsafe-pattern"`). */
   pattern?: string;
+  /** Why the shell policy refused the command (for `"denied-command"`). */
+  reason?: WorkspaceShellRefusalReason;
+  /** The executable the refusal is about, when there is one. */
+  executable?: string;
 };
 /**
  * The workspace policy engine refused an operation — a path escaped the
@@ -41,7 +76,7 @@ type WorkspacePolicyErrorOptions = AIErrorOptions & {
  *   console.warn(`Blocked command: ${error.command}`);
  * }
  */
-declare class WorkspacePolicyError extends AIError {
+export declare class WorkspacePolicyError extends AIError {
   /** Which policy rule was violated. */
   readonly type: WorkspacePolicyViolation;
   /** The offending path, when the violation was a path escape. */
@@ -50,6 +85,14 @@ declare class WorkspacePolicyError extends AIError {
   readonly command?: string;
   /** The offending regex pattern, when the violation was `"unsafe-pattern"`. */
   readonly pattern?: string;
+  /**
+   * Why the shell policy refused a command line — set on every
+   * `"denied-command"` refusal of a command (see
+   * {@link WorkspaceShellRefusalReason}).
+   */
+  readonly reason?: WorkspaceShellRefusalReason;
+  /** The executable the shell refusal is about, when there is one. */
+  readonly executable?: string;
   constructor(message: string, options: WorkspacePolicyErrorOptions);
 }
 /**
@@ -61,18 +104,25 @@ declare class WorkspacePolicyError extends AIError {
  * - `"stale-hash"` — the file's current hash did not match the supplied
  *   `expectHash`; the file changed since it was read.
  */
-type WorkspaceEditFailure = "not-found" | "not-unique" | "stale-hash";
+export type WorkspaceEditFailure = "not-found" | "not-unique" | "stale-hash";
 /**
  * Options for {@link WorkspaceEditError} — the structured `type`
  * discriminator plus optional match-count / hash context for the
  * `"not-unique"` and `"stale-hash"` cases.
  */
-type WorkspaceEditErrorOptions = AIErrorOptions & {
-  /** Why the edit was rejected. */type: WorkspaceEditFailure; /** The edited file's workspace-relative path. */
-  path: string; /** How many times `oldString` matched (for `"not-unique"`). */
-  matches?: number; /** The hash the caller expected (for `"stale-hash"`). */
-  expectedHash?: string; /** The file's actual current hash (for `"stale-hash"`). */
+export type WorkspaceEditErrorOptions = AIErrorOptions & {
+  /** Why the edit was rejected. */
+  type: WorkspaceEditFailure;
+  /** The edited file's workspace-relative path. */
+  path: string;
+  /** How many times `oldString` matched (for `"not-unique"`). */
+  matches?: number;
+  /** The hash the caller expected (for `"stale-hash"`). */
+  expectedHash?: string;
+  /** The file's actual current hash (for `"stale-hash"`). */
   actualHash?: string;
+  /** 0-based index of the failing edit, for a `multiEdit` rejection. */
+  editIndex?: number;
 };
 /**
  * An `editFile` operation was rejected by the read-before-edit guard:
@@ -88,7 +138,7 @@ type WorkspaceEditErrorOptions = AIErrorOptions & {
  *   // re-read the file and retry the edit with the fresh hash
  * }
  */
-declare class WorkspaceEditError extends AIError {
+export declare class WorkspaceEditError extends AIError {
   /** Why the edit was rejected. */
   readonly type: WorkspaceEditFailure;
   /** The edited file's workspace-relative path. */
@@ -99,8 +149,44 @@ declare class WorkspaceEditError extends AIError {
   readonly expectedHash?: string;
   /** The file's actual current hash, for the `"stale-hash"` case. */
   readonly actualHash?: string;
+  /**
+   * For a `multiEdit` rejection, the 0-based index of the edit that failed.
+   * Nothing was written: a multi-edit applies all of its edits or none.
+   */
+  readonly editIndex?: number;
   constructor(message: string, options: WorkspaceEditErrorOptions);
 }
+/**
+ * Why a background-command operation failed.
+ *
+ * - `"not-found"` — no background command with that id exists in this
+ *   workspace (it never existed, or it finished long enough ago to be
+ *   pruned).
+ */
+export type WorkspaceJobFailure = "not-found";
+/** Options for {@link WorkspaceJobError}. */
+export type WorkspaceJobErrorOptions = AIErrorOptions & {
+  /** Why the operation failed. */
+  type: WorkspaceJobFailure;
+  /** The background command id the caller asked for. */
+  jobId: string;
+};
+/**
+ * A `shell_output` / `shell_kill` call (or `shellOutput()` / `shellKill()`)
+ * named a background command this workspace does not know. Returned to the
+ * agent as tool-error data like the other workspace errors.
+ *
+ * @example
+ * if (error instanceof WorkspaceJobError && error.type === "not-found") {
+ *   console.warn(`No background command ${error.jobId}`);
+ * }
+ */
+export declare class WorkspaceJobError extends AIError {
+  /** Why the operation failed. */
+  readonly type: WorkspaceJobFailure;
+  /** The background command id the caller asked for. */
+  readonly jobId: string;
+  constructor(message: string, options: WorkspaceJobErrorOptions);
+}
 //#endregion
-export { WorkspaceEditError, WorkspaceEditErrorOptions, WorkspaceEditFailure, WorkspacePolicyError, WorkspacePolicyErrorOptions, WorkspacePolicyViolation };
 //# sourceMappingURL=errors.d.mts.map

package/esm/errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/errors.ts"],"mappings":";;;;;AAaA;;;;AAAoC;AAOpC;;;;KAPY,wBAAA;;;;;;KAOA,2BAAA,GAA8B,cAAA;EAQjC,sCANP,IAAA,EAAM,wBAAwB,EA0BE;EAxBhC,IAAA,WA0BsB;EAxBtB,OAAA,WAsBwC;EApBxC,OAAA;AAAA;;;;;;;;;;;;AA8BwE;AAoB1E;;;;AAAgC;cA9BnB,oBAAA,SAA6B,OAAA;EAqCL;EAAA,SAnCnB,IAAA,EAAM,wBAAA;EAqCI;EAAA,SAnCV,IAAA;EAmChB;EAAA,SAjCgB,OAAA;EAmChB;EAAA,SAjCgB,OAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,2BAAA;AAAA;;AAqCnC;AAiBZ;;;;;;;KAlCY,oBAAA;;;;;;KAOA,yBAAA,GAA4B,cAAA;EAqCtB,iCAnChB,IAAA,EAAM,oBAAoB,EAqCP;EAnCnB,IAAA,UAmCoC;EAjCpC,OAAA,WAiCsE;EA/BtE,YAAA;EAEA,UAAA;AAAA;;;;;;;;;;;;;;;cAiBW,kBAAA,SAA2B,OAAA;;WAEtB,IAAA,EAAM,oBAAA;;WAEN,IAAA;;WAEA,OAAA;;WAEA,YAAA;;WAEA,UAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,yBAAA;AAAA"}
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/errors.ts"],"mappings":";;;;;;;;;;;;;;;YAeY;;;;;;;;;;;;;;;;;;;;;;;;;;YA2BA;;;;;;YAeA,8BAA8B;;EAExC,MAAM;;EAEN;;EAEA;;EAEA;;EAEA,SAAS;;EAET;;;;;;;;;;;;;;;;;;;qBAoBW,6BAA6B;;WAExB,MAAM;;WAEN;;WAEA;;WAEA;;;;;;WAMA,SAAS;;WAET;EAEhB,YAAmB,iBAAiB,SAAS;;;;;;;;;;;YAsBnC;;;;;;YAOA,4BAA4B;;EAEtC,MAAM;;EAEN;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;;;;;;;;qBAiBW,2BAA2B;;WAEtB,MAAM;;WAEN;;WAEA;;WAEA;;WAEA;;;;;WAKA;EAEhB,YAAmB,iBAAiB,SAAS;;;;;;;;;YAoBnC;;YAGA,2BAA2B;;EAErC,MAAM;;EAEN;;;;;;;;;;;;qBAaW,0BAA0B;;WAErB,MAAM;;WAEN;EAEhB,YAAmB,iBAAiB,SAAS"}

package/esm/errors.mjs

@@ -26,6 +26,8 @@ var WorkspacePolicyError = class extends AIError {
 		this.path = options.path;
 		this.command = options.command;
 		this.pattern = options.pattern;
+		this.reason = options.reason;
+		this.executable = options.executable;
 	}
 };
 /**
@@ -51,9 +53,28 @@ var WorkspaceEditError = class extends AIError {
 		this.matches = options.matches;
 		this.expectedHash = options.expectedHash;
 		this.actualHash = options.actualHash;
+		this.editIndex = options.editIndex;
+	}
+};
+/**
+* A `shell_output` / `shell_kill` call (or `shellOutput()` / `shellKill()`)
+* named a background command this workspace does not know. Returned to the
+* agent as tool-error data like the other workspace errors.
+*
+* @example
+* if (error instanceof WorkspaceJobError && error.type === "not-found") {
+*   console.warn(`No background command ${error.jobId}`);
+* }
+*/
+var WorkspaceJobError = class extends AIError {
+	constructor(message, options) {
+		super("TOOL_EXEC_FAILED", message, options);
+		this.name = "WorkspaceJobError";
+		this.type = options.type;
+		this.jobId = options.jobId;
 	}
 };
 
 //#endregion
-export { WorkspaceEditError, WorkspacePolicyError };
+export { WorkspaceEditError, WorkspaceJobError, WorkspacePolicyError };
 //# sourceMappingURL=errors.mjs.map

package/esm/errors.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../packages/ai-workspace/src/errors.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"@warlock.js/ai\";\n\n/**\n * Why a workspace policy check rejected an operation.\n *\n * - `\"path-escape\"` — a resolved path fell outside the `cwd` jail (or an\n *   `allowPaths` root), or matched a `denyPaths` glob.\n * - `\"denied-command\"` — a shell command's leading executable basename\n *   was not in `shell.allow`, or was explicitly in `shell.deny`.\n * - `\"unsafe-pattern\"` — a `grep` pattern was too long or matched a\n *   catastrophic-backtracking shape (nested quantifiers) that could hang\n *   the process (ReDoS).\n */\nexport type WorkspacePolicyViolation = \"path-escape\" | \"denied-command\" | \"unsafe-pattern\";\n\n/**\n * Options for {@link WorkspacePolicyError} — the structured `type`\n * discriminator plus, where relevant, the offending path or command for\n * branchable diagnostics without parsing the message.\n */\nexport type WorkspacePolicyErrorOptions = AIErrorOptions & {\n  /** Which policy rule was violated. */\n  type: WorkspacePolicyViolation;\n  /** The offending workspace-relative path (for `\"path-escape\"`). */\n  path?: string;\n  /** The offending command line (for `\"denied-command\"`). */\n  command?: string;\n  /** The offending regex pattern (for `\"unsafe-pattern\"`). */\n  pattern?: string;\n};\n\n/**\n * The workspace policy engine refused an operation — a path escaped the\n * jail (or hit a deny glob), or a shell command's executable was not\n * allowed.\n *\n * **Surface.** This is returned to the agent as tool-error *data*, never\n * a thrown run-killer — the agent reads the failure and self-corrects.\n * Extends the framework `AIError` (category `\"tool\"`, code\n * `TOOL_EXEC_FAILED`) so it flows through the same typed error contract\n * as every other AI error; branch on `error.type` for the specific\n * violation.\n *\n * @example\n * if (error instanceof WorkspacePolicyError && error.type === \"denied-command\") {\n *   console.warn(`Blocked command: ${error.command}`);\n * }\n */\nexport class WorkspacePolicyError extends AIError {\n  /** Which policy rule was violated. */\n  public readonly type: WorkspacePolicyViolation;\n  /** The offending path, when the violation was a path escape. */\n  public readonly path?: string;\n  /** The offending command, when the violation was a denied command. */\n  public readonly command?: string;\n  /** The offending regex pattern, when the violation was `\"unsafe-pattern\"`. */\n  public readonly pattern?: string;\n\n  public constructor(message: string, options: WorkspacePolicyErrorOptions) {\n    super(\"TOOL_EXEC_FAILED\", message, options);\n\n    this.name = \"WorkspacePolicyError\";\n    this.type = options.type;\n    this.path = options.path;\n    this.command = options.command;\n    this.pattern = options.pattern;\n  }\n}\n\n/**\n * Why an edit was rejected.\n *\n * - `\"not-found\"` — the `oldString` did not appear in the file.\n * - `\"not-unique\"` — `oldString` matched more than once and `replaceAll`\n *   was not set, so the edit is ambiguous.\n * - `\"stale-hash\"` — the file's current hash did not match the supplied\n *   `expectHash`; the file changed since it was read.\n */\nexport type WorkspaceEditFailure = \"not-found\" | \"not-unique\" | \"stale-hash\";\n\n/**\n * Options for {@link WorkspaceEditError} — the structured `type`\n * discriminator plus optional match-count / hash context for the\n * `\"not-unique\"` and `\"stale-hash\"` cases.\n */\nexport type WorkspaceEditErrorOptions = AIErrorOptions & {\n  /** Why the edit was rejected. */\n  type: WorkspaceEditFailure;\n  /** The edited file's workspace-relative path. */\n  path: string;\n  /** How many times `oldString` matched (for `\"not-unique\"`). */\n  matches?: number;\n  /** The hash the caller expected (for `\"stale-hash\"`). */\n  expectedHash?: string;\n  /** The file's actual current hash (for `\"stale-hash\"`). */\n  actualHash?: string;\n};\n\n/**\n * An `editFile` operation was rejected by the read-before-edit guard:\n * the `oldString` was absent, matched non-uniquely without `replaceAll`,\n * or the file's hash no longer matched the supplied `expectHash`.\n *\n * **Surface.** Like {@link WorkspacePolicyError}, returned to the agent\n * as tool-error *data* so it can re-read and retry. Extends `AIError`\n * (category `\"tool\"`, code `TOOL_EXEC_FAILED`); branch on `error.type`.\n *\n * @example\n * if (error instanceof WorkspaceEditError && error.type === \"stale-hash\") {\n *   // re-read the file and retry the edit with the fresh hash\n * }\n */\nexport class WorkspaceEditError extends AIError {\n  /** Why the edit was rejected. */\n  public readonly type: WorkspaceEditFailure;\n  /** The edited file's workspace-relative path. */\n  public readonly path: string;\n  /** How many times `oldString` matched, for the `\"not-unique\"` case. */\n  public readonly matches?: number;\n  /** The hash the caller expected, for the `\"stale-hash\"` case. */\n  public readonly expectedHash?: string;\n  /** The file's actual current hash, for the `\"stale-hash\"` case. */\n  public readonly actualHash?: string;\n\n  public constructor(message: string, options: WorkspaceEditErrorOptions) {\n    super(\"TOOL_EXEC_FAILED\", message, options);\n\n    this.name = \"WorkspaceEditError\";\n    this.type = options.type;\n    this.path = options.path;\n    this.matches = options.matches;\n    this.expectedHash = options.expectedHash;\n    this.actualHash = options.actualHash;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgDA,IAAa,uBAAb,cAA0C,QAAQ;CAUhD,AAAO,YAAY,SAAiB,SAAsC;EACxE,MAAM,oBAAoB,SAAS,OAAO;EAE1C,KAAK,OAAO;EACZ,KAAK,OAAO,QAAQ;EACpB,KAAK,OAAO,QAAQ;EACpB,KAAK,UAAU,QAAQ;EACvB,KAAK,UAAU,QAAQ;CACzB;AACF;;;;;;;;;;;;;;;AA6CA,IAAa,qBAAb,cAAwC,QAAQ;CAY9C,AAAO,YAAY,SAAiB,SAAoC;EACtE,MAAM,oBAAoB,SAAS,OAAO;EAE1C,KAAK,OAAO;EACZ,KAAK,OAAO,QAAQ;EACpB,KAAK,OAAO,QAAQ;EACpB,KAAK,UAAU,QAAQ;EACvB,KAAK,eAAe,QAAQ;EAC5B,KAAK,aAAa,QAAQ;CAC5B;AACF"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../packages/ai-workspace/src/errors.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"@warlock.js/ai\";\n\n/**\n * Why a workspace policy check rejected an operation.\n *\n * - `\"path-escape\"` — a resolved path fell outside the `cwd` jail (or an\n *   `allowPaths` root), or matched a `denyPaths` glob.\n * - `\"denied-command\"` — the shell policy refused a command line (`reason`\n *   says why: an executable outside `shell.allow` or inside `shell.deny`, a\n *   metacharacter in argv mode, a redirection outside the jail in shell\n *   mode, …), or a mutating method was called on a read-only projection.\n * - `\"unsafe-pattern\"` — a `grep` pattern was too long or matched a\n *   catastrophic-backtracking shape (nested quantifiers) that could hang\n *   the process (ReDoS).\n */\nexport type WorkspacePolicyViolation = \"path-escape\" | \"denied-command\" | \"unsafe-pattern\";\n\n/**\n * Why the shell policy refused a command. Set on every\n * {@link WorkspacePolicyError} of type `\"denied-command\"` raised for a\n * command line, so a host can phrase the refusal itself instead of parsing\n * the message.\n *\n * - `\"metacharacter\"` — argv mode (the default `interpreter: \"none\"`) met an\n *   unquoted shell operator (`&&`, `;`, `|`, `>`, `$`, backticks, …). The\n *   message suggests how to split the line into separate commands.\n * - `\"unbalanced-quotes\"` — a quote is never closed.\n * - `\"denied-executable\"` — a command's executable is listed in `shell.deny`.\n * - `\"not-allowed\"` — a command's executable is not in `shell.allow`, the\n *   `shell.allowCommand` hook refused it, the workspace has no shell policy,\n *   the line is empty, or background commands are not enabled.\n * - `\"denied-pattern\"` — a command matched one of `shell.denyPatterns`.\n * - `\"nested-command\"` — a command runs another command the policy cannot\n *   inspect (`bash -c …`, `eval`, `xargs`, `sudo`, a wrapper with options the\n *   policy cannot read), while the policy has deny rules it would bypass.\n * - `\"unsupported-syntax\"` — shell mode (`interpreter: \"sh\"`) met syntax the\n *   policy does not parse with confidence (compound commands, arithmetic,\n *   brace expansion, background `&`, a command name decided at run time, …),\n *   so the line is refused rather than guessed at.\n * - `\"path-escape\"` — shell mode: a redirection target or `cd` directory\n *   resolves outside the workspace jail or hits `denyPaths`.\n */\nexport type WorkspaceShellRefusalReason =\n  | \"metacharacter\"\n  | \"unbalanced-quotes\"\n  | \"denied-executable\"\n  | \"not-allowed\"\n  | \"denied-pattern\"\n  | \"nested-command\"\n  | \"unsupported-syntax\"\n  | \"path-escape\";\n\n/**\n * Options for {@link WorkspacePolicyError} — the structured `type`\n * discriminator plus, where relevant, the offending path or command for\n * branchable diagnostics without parsing the message.\n */\nexport type WorkspacePolicyErrorOptions = AIErrorOptions & {\n  /** Which policy rule was violated. */\n  type: WorkspacePolicyViolation;\n  /** The offending workspace-relative path (for `\"path-escape\"`). */\n  path?: string;\n  /** The offending command line (for `\"denied-command\"`). */\n  command?: string;\n  /** The offending regex pattern (for `\"unsafe-pattern\"`). */\n  pattern?: string;\n  /** Why the shell policy refused the command (for `\"denied-command\"`). */\n  reason?: WorkspaceShellRefusalReason;\n  /** The executable the refusal is about, when there is one. */\n  executable?: string;\n};\n\n/**\n * The workspace policy engine refused an operation — a path escaped the\n * jail (or hit a deny glob), or a shell command's executable was not\n * allowed.\n *\n * **Surface.** This is returned to the agent as tool-error *data*, never\n * a thrown run-killer — the agent reads the failure and self-corrects.\n * Extends the framework `AIError` (category `\"tool\"`, code\n * `TOOL_EXEC_FAILED`) so it flows through the same typed error contract\n * as every other AI error; branch on `error.type` for the specific\n * violation.\n *\n * @example\n * if (error instanceof WorkspacePolicyError && error.type === \"denied-command\") {\n *   console.warn(`Blocked command: ${error.command}`);\n * }\n */\nexport class WorkspacePolicyError extends AIError {\n  /** Which policy rule was violated. */\n  public readonly type: WorkspacePolicyViolation;\n  /** The offending path, when the violation was a path escape. */\n  public readonly path?: string;\n  /** The offending command, when the violation was a denied command. */\n  public readonly command?: string;\n  /** The offending regex pattern, when the violation was `\"unsafe-pattern\"`. */\n  public readonly pattern?: string;\n  /**\n   * Why the shell policy refused a command line — set on every\n   * `\"denied-command\"` refusal of a command (see\n   * {@link WorkspaceShellRefusalReason}).\n   */\n  public readonly reason?: WorkspaceShellRefusalReason;\n  /** The executable the shell refusal is about, when there is one. */\n  public readonly executable?: string;\n\n  public constructor(message: string, options: WorkspacePolicyErrorOptions) {\n    super(\"TOOL_EXEC_FAILED\", message, options);\n\n    this.name = \"WorkspacePolicyError\";\n    this.type = options.type;\n    this.path = options.path;\n    this.command = options.command;\n    this.pattern = options.pattern;\n    this.reason = options.reason;\n    this.executable = options.executable;\n  }\n}\n\n/**\n * Why an edit was rejected.\n *\n * - `\"not-found\"` — the `oldString` did not appear in the file.\n * - `\"not-unique\"` — `oldString` matched more than once and `replaceAll`\n *   was not set, so the edit is ambiguous.\n * - `\"stale-hash\"` — the file's current hash did not match the supplied\n *   `expectHash`; the file changed since it was read.\n */\nexport type WorkspaceEditFailure = \"not-found\" | \"not-unique\" | \"stale-hash\";\n\n/**\n * Options for {@link WorkspaceEditError} — the structured `type`\n * discriminator plus optional match-count / hash context for the\n * `\"not-unique\"` and `\"stale-hash\"` cases.\n */\nexport type WorkspaceEditErrorOptions = AIErrorOptions & {\n  /** Why the edit was rejected. */\n  type: WorkspaceEditFailure;\n  /** The edited file's workspace-relative path. */\n  path: string;\n  /** How many times `oldString` matched (for `\"not-unique\"`). */\n  matches?: number;\n  /** The hash the caller expected (for `\"stale-hash\"`). */\n  expectedHash?: string;\n  /** The file's actual current hash (for `\"stale-hash\"`). */\n  actualHash?: string;\n  /** 0-based index of the failing edit, for a `multiEdit` rejection. */\n  editIndex?: number;\n};\n\n/**\n * An `editFile` operation was rejected by the read-before-edit guard:\n * the `oldString` was absent, matched non-uniquely without `replaceAll`,\n * or the file's hash no longer matched the supplied `expectHash`.\n *\n * **Surface.** Like {@link WorkspacePolicyError}, returned to the agent\n * as tool-error *data* so it can re-read and retry. Extends `AIError`\n * (category `\"tool\"`, code `TOOL_EXEC_FAILED`); branch on `error.type`.\n *\n * @example\n * if (error instanceof WorkspaceEditError && error.type === \"stale-hash\") {\n *   // re-read the file and retry the edit with the fresh hash\n * }\n */\nexport class WorkspaceEditError extends AIError {\n  /** Why the edit was rejected. */\n  public readonly type: WorkspaceEditFailure;\n  /** The edited file's workspace-relative path. */\n  public readonly path: string;\n  /** How many times `oldString` matched, for the `\"not-unique\"` case. */\n  public readonly matches?: number;\n  /** The hash the caller expected, for the `\"stale-hash\"` case. */\n  public readonly expectedHash?: string;\n  /** The file's actual current hash, for the `\"stale-hash\"` case. */\n  public readonly actualHash?: string;\n  /**\n   * For a `multiEdit` rejection, the 0-based index of the edit that failed.\n   * Nothing was written: a multi-edit applies all of its edits or none.\n   */\n  public readonly editIndex?: number;\n\n  public constructor(message: string, options: WorkspaceEditErrorOptions) {\n    super(\"TOOL_EXEC_FAILED\", message, options);\n\n    this.name = \"WorkspaceEditError\";\n    this.type = options.type;\n    this.path = options.path;\n    this.matches = options.matches;\n    this.expectedHash = options.expectedHash;\n    this.actualHash = options.actualHash;\n    this.editIndex = options.editIndex;\n  }\n}\n\n/**\n * Why a background-command operation failed.\n *\n * - `\"not-found\"` — no background command with that id exists in this\n *   workspace (it never existed, or it finished long enough ago to be\n *   pruned).\n */\nexport type WorkspaceJobFailure = \"not-found\";\n\n/** Options for {@link WorkspaceJobError}. */\nexport type WorkspaceJobErrorOptions = AIErrorOptions & {\n  /** Why the operation failed. */\n  type: WorkspaceJobFailure;\n  /** The background command id the caller asked for. */\n  jobId: string;\n};\n\n/**\n * A `shell_output` / `shell_kill` call (or `shellOutput()` / `shellKill()`)\n * named a background command this workspace does not know. Returned to the\n * agent as tool-error data like the other workspace errors.\n *\n * @example\n * if (error instanceof WorkspaceJobError && error.type === \"not-found\") {\n *   console.warn(`No background command ${error.jobId}`);\n * }\n */\nexport class WorkspaceJobError extends AIError {\n  /** Why the operation failed. */\n  public readonly type: WorkspaceJobFailure;\n  /** The background command id the caller asked for. */\n  public readonly jobId: string;\n\n  public constructor(message: string, options: WorkspaceJobErrorOptions) {\n    super(\"TOOL_EXEC_FAILED\", message, options);\n\n    this.name = \"WorkspaceJobError\";\n    this.type = options.type;\n    this.jobId = options.jobId;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAyFA,IAAa,uBAAb,cAA0C,QAAQ;CAkBhD,AAAO,YAAY,SAAiB,SAAsC;EACxE,MAAM,oBAAoB,SAAS,OAAO;EAE1C,KAAK,OAAO;EACZ,KAAK,OAAO,QAAQ;EACpB,KAAK,OAAO,QAAQ;EACpB,KAAK,UAAU,QAAQ;EACvB,KAAK,UAAU,QAAQ;EACvB,KAAK,SAAS,QAAQ;EACtB,KAAK,aAAa,QAAQ;CAC5B;AACF;;;;;;;;;;;;;;;AA+CA,IAAa,qBAAb,cAAwC,QAAQ;CAiB9C,AAAO,YAAY,SAAiB,SAAoC;EACtE,MAAM,oBAAoB,SAAS,OAAO;EAE1C,KAAK,OAAO;EACZ,KAAK,OAAO,QAAQ;EACpB,KAAK,OAAO,QAAQ;EACpB,KAAK,UAAU,QAAQ;EACvB,KAAK,eAAe,QAAQ;EAC5B,KAAK,aAAa,QAAQ;EAC1B,KAAK,YAAY,QAAQ;CAC3B;AACF;;;;;;;;;;;AA6BA,IAAa,oBAAb,cAAuC,QAAQ;CAM7C,AAAO,YAAY,SAAiB,SAAmC;EACrE,MAAM,oBAAoB,SAAS,OAAO;EAE1C,KAAK,OAAO;EACZ,KAAK,OAAO,QAAQ;EACpB,KAAK,QAAQ,QAAQ;CACvB;AACF"}