@warlock.js/ai-workspace 5.29.0 → 5.31.0

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

@@ -1,4 +1,4 @@
-//#region ../ai-workspace/src/contracts/workspace-policy.type.d.ts
+//#region ../../packages/ai-workspace/src/contracts/workspace-policy.type.d.ts
 /**
  * The executor a workspace runs on. `"local"` uses `@warlock.js/fs` +
  * `node:child_process` against the real filesystem under `cwd`;
@@ -8,33 +8,130 @@
  * past the W1 surface and intentionally absent from this union.
  */
 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.
+ */
+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.
+ */
+type WorkspaceCommandPattern = string | RegExp;
+/** What {@link WorkspaceAllowCommand} is told about the command it checks. */
+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
+ */
+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.
+ */
+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 {
   /** 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,16 +140,45 @@ 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 {
-  /** Hard cap on bytes returned by a single read; larger reads truncate. */
+  /**
+   * 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
+   * it is cut — mid-line if needed, always on a character boundary — and
+   * the result reports `bytesCapped: true`. Absent ⇒ no byte cap. The
+   * whole file is still read and hashed; this bounds what is returned.
+   */
   maxBytes?: number;
   /** 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).
+ */
+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.
@@ -83,9 +209,11 @@ 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 };
+export { WorkspaceAllowCommand, WorkspaceBackendType, WorkspaceBackgroundPolicy, WorkspaceCommandCheckContext, WorkspaceCommandPattern, WorkspaceListPolicy, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellInterpreter, 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":["../../../../../../../ai-workspace/src/contracts/workspace-policy.type.ts"],"mappings":";;AAQA;;;;AAAgC;AAqBhC;;KArBY,oBAAA;;;;;;;;;;AAoCA;AAMZ;;;;AAIc;AAsBd;;;;UA/CiB,oBAAA;EA2DL;EAzDV,KAAA;EAyD8B;EAvD9B,IAAA;EA+CA;EA7CA,SAAA;EAiDA;EA/CA,cAAA;EAiDA;EA/CA,GAAA,GAAM,MAAM;EAiDZ;;;AAA8B;EA5C9B,UAAA;AAAA;;;;UAMe,mBAAA;;EAEf,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":";;AAQA;;;;AAAgC;AAiBhC;;KAjBY,oBAAA;;AAiByB;AAcrC;;;;AAAqD;AAGrD;;;;;;;;KAjBY,yBAAA;AA2BJ;AAcR;;;;;;;;AAEuC;AAUvC;;AA1BQ,KAbI,uBAAA,YAAmC,MAAM;;UAGpC,4BAAA;EAuEA;EArEf,OAAA;;EAEA,WAAA,EAAa,yBAAyB;EAiFvB;;;;;EA3Ef,MAAA;AAAA;;;;;;;;;;;;KAcU,qBAAA,IACV,IAAA,qBACA,OAAA,EAAS,4BAA4B;;;;AAsFC;AAOxC;;;UAnFiB,yBAAA;EA6FH;EA3FZ,OAAA;EAmGkC;;;;;EA7FlC,SAAS;AAAA;AAuGC;AAsBZ;;;;;;;;;;;;;;;;;;;;;AAcgC;;AApCpB,UA5EK,oBAAA;;EAEf,KAAA;;EAEA,IAAA;;;;;EAKA,YAAA,GAAe,uBAAA;;;;;EAKf,YAAA,GAAe,qBAAA;;;;;;;EAOf,WAAA,GAAc,yBAAA;;EAEd,SAAA;;;;;;EAMA,cAAA;;EAEA,GAAA,GAAM,MAAA;;;;;EAKN,UAAA;;;;;EAKA,UAAA,GAAa,yBAAA;AAAA;;;;;UAOE,mBAAA;;;;;;;;EAQf,QAAA;;EAEA,YAAY;AAAA;;;;;;UAQG,mBAAA;;;;;;EAMf,MAAA;;EAEA,QAAA;;EAEA,UAAA;AAAA;;;;;;;;;;;;;;;;;;;;UAsBe,eAAA;;EAEf,GAAA;;EAEA,UAAA;;EAEA,SAAA;;EAEA,KAAA,GAAQ,oBAAA;;EAER,IAAA,GAAO,mBAAA;;EAEP,IAAA,GAAO,mBAAA;;EAEP,OAAA,GAAU,oBAAA;AAAA"}

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

@@ -1,8 +1,8 @@
-import { EditFileInput, EditFileResult, GrepResult, 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 ../ai-workspace/src/contracts/workspace.contract.d.ts
+//#region ../../packages/ai-workspace/src/contracts/workspace.contract.d.ts
 /**
  * The agent-facing tool surface of a workspace. Each factory returns a
  * {@link ToolContract} ready to hand to `ai.agent({ tools })`. `all()`
@@ -14,7 +14,11 @@ import { ToolContract } from "@warlock.js/ai";
  * multiple agents.
  */
 interface WorkspaceTools {
-  /** All seven tools as `ToolContract[]`, ready for `ai.agent({ tools })`. */
+  /**
+   * 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 +30,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 +67,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 +82,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"] } });
@@ -77,18 +104,15 @@ interface Workspace {
   /** Agent-facing tool factories. */
   readonly tools: WorkspaceTools;
   /**
-   * Read a jailed file. `offset`/`limit` select a 1-based line window;
-   * returns the content, its SHA-256 `hash`, and the file's total line
-   * count (for read-before-edit).
+   * Read a jailed file. `offset`/`limit` select a 1-based line window and
+   * `read.maxBytes` bounds the returned bytes; returns the numbered content,
+   * the full file's SHA-256 `hash` (for read-before-edit), and the window
+   * metadata — the same shape the `read_file` tool returns.
    */
   readFile(path: string, opts?: {
     offset?: number;
     limit?: number;
-  }): Promise<{
-    content: string;
-    hash: string;
-    totalLines: number;
-  }>;
+  }): Promise<ReadFileResult>;
   /** Atomically write full content to a jailed path. */
   writeFile(path: string, content: string): Promise<{
     hash: string;
@@ -96,10 +120,39 @@ interface Workspace {
   }>;
   /** Apply an exact-string edit under the read-before-edit stale guard. */
   editFile(input: EditFileInput): Promise<EditFileResult>;
-  /** Run a policy-gated shell command and capture its outcome. */
-  exec(command: string, opts?: {
-    timeoutMs?: number;
-  }): Promise<RunShellResult>;
+  /** 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;

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

@@ -1 +1 @@
-{"version":3,"file":"workspace.contract.d.mts","names":[],"sources":["../../../../../../../ai-workspace/src/contracts/workspace.contract.ts"],"mappings":";;;;;;;AAoBA;;;;;;;;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;EAuCO;EAAA,SArCb,MAAA,EAAQ,eAAA;EA2CK;EAAA,SAxCb,KAAA,EAAO,cAAA;EAsDO;;;;;EA/CvB,QAAA,CACE,IAAA,UACA,IAAA;IAAS,MAAA;IAAiB,KAAA;EAAA,IACzB,OAAA;IAAU,OAAA;IAAiB,IAAA;IAAc,UAAA;EAAA;EAA/B;EAGb,SAAA,CACE,IAAA,UACA,OAAA,WACC,OAAA;IAAU,IAAA;IAAc,YAAA;EAAA;EADzB;EAIF,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,cAAA;EAH3B;EAMb,IAAA,CAAK,OAAA,UAAiB,IAAA;IAAS,SAAA;EAAA,IAAuB,OAAA,CAAQ,cAAA;EAHrD;EAMT,IAAA,CACE,OAAA,UACA,IAAA;IAAS,IAAA;IAAe,UAAA;EAAA,IACvB,OAAA,CAAQ,UAAA;EANoB;EAS/B,IAAA,CAAK,OAAA,WAAkB,OAAA;EAT+B;EAYtD,MAAA,CAAO,IAAA,WAAe,OAAA;EATtB;EAYA,KAAA,CAAM,IAAA,WAAe,OAAA;EAVV;EAaX,MAAA,CAAO,IAAA,WAAe,OAAA;EAbpB;;;;;EAoBF,QAAA,IAAY,SAAA;EAbZ;;;;;EAoBA,KAAA,CAAM,MAAA,WAAiB,SAAA;AAAA"}
+{"version":3,"file":"workspace.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace.contract.ts"],"mappings":";;;;;;;AAgCA;;;;;;;;UAAiB,cAAA;EAgBsB;;;;;EAVrC,GAAA,IAAO,YAAA;EAsByB;EApBhC,IAAA,IAAQ,KAAA,EAAO,iBAAA,KAAsB,YAAA;EAwBA;EAtBrC,QAAA,CAAS,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJpC;EAMA,QAAA,CAAS,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJrB;EAMf,SAAA,CAAU,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJ5B;EAMT,SAAA,CAAU,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJ5B;EAMT,OAAA,CAAQ,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJzB;EAMV,QAAA,CAAS,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJ1B;EAMV,WAAA,CAAY,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJ/B;EAMR,SAAA,CAAU,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJ5B;EAMT,QAAA,CAAS,IAAA;IAAS,IAAA;IAAe,OAAA;EAAA,IAAqB,YAAA;EAJf;EAMvC,IAAA,CAAK,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJK;EAMrC,IAAA,CAAK,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJvB;EAMT,SAAA,CAAU,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;EAJhC;EAML,QAAA,CAAS,IAAA;IAAS,IAAA;EAAA,IAAkB,YAAA;AAAA;;;;;;;;;;;AAAY;AAyBlD;;;;;;;;;;;UAAiB,SAAA;EAsB2B;EAAA,SApBjC,MAAA,EAAQ,eAAA;EAuBa;EAAA,SApBrB,KAAA,EAAO,cAAA;EAoB+B;;;;;;EAZ/C,QAAA,CAAS,IAAA,UAAc,IAAA;IAAS,MAAA;IAAiB,KAAA;EAAA,IAAmB,OAAA,CAAQ,cAAA;EAgC7C;EA7B/B,SAAA,CAAU,IAAA,UAAc,OAAA,WAAkB,OAAA;IAAU,IAAA;IAAc,YAAA;EAAA;EAsCzB;EAnCzC,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,cAAA;EA8CuC;EA3C/E,SAAA,CAAU,KAAA,EAAO,cAAA,GAAiB,OAAA,CAAQ,eAAA;EA8CnB;EA3CvB,OAAA,CAAQ,IAAA,WAAe,IAAA,GAAO,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAiDlC;;;;;EA1CrB,IAAA,CAAK,OAAA,UAAiB,IAAA,GAAO,WAAA,GAAc,OAAA,CAAQ,cAAA;EA9B1C;;;;;EAqCT,UAAA,CAAW,OAAA,UAAiB,IAAA,GAAO,iBAAA,GAAoB,OAAA,CAAQ,YAAA;EA1B/B;EA6BhC,WAAA,CAAY,EAAA,UAAY,IAAA,GAAO,kBAAA,GAAqB,OAAA,CAAQ,iBAAA;EA7BrC;EAgCvB,SAAA,CAAU,EAAA,WAAa,OAAA,CAAQ,YAAA;EAhC6C;EAmC5E,UAAA,IAAc,YAAA;EAhCJ;EAmCV,SAAA,IAAa,cAAA;EAnC6B;EAsC1C,UAAA,CAAW,KAAA,EAAO,kBAAA,KAAuB,cAAA;EAtCyB;;;;;;EA8ClE,OAAA,IAAW,OAAA;EAxCM;EA2CjB,IAAA,CAAK,OAAA,UAAiB,IAAA;IAAS,IAAA;IAAe,UAAA;EAAA,IAAyB,OAAA,CAAQ,UAAA;EAxCvE;EA2CR,IAAA,CAAK,OAAA,WAAkB,OAAA;EA3CA;EA8CvB,MAAA,CAAO,IAAA,WAAe,OAAA;EA9CiC;EAiDvD,KAAA,CAAM,IAAA,WAAe,OAAA;EA1ChB;EA6CL,MAAA,CAAO,IAAA,WAAe,OAAA;EA7CA;;;;;EAoDtB,QAAA,IAAY,SAAA;EA7CgB;;;;;EAoD5B,KAAA,CAAM,MAAA,WAAiB,SAAA;AAAA"}

package/esm/errors.d.mts

@@ -1,18 +1,46 @@
 import { AIError, AIErrorOptions } from "@warlock.js/ai";
 
-//#region ../ai-workspace/src/errors.d.ts
+//#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";
+/**
+ * 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`.
+ */
+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
@@ -22,7 +50,9 @@ 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;
+  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
@@ -50,6 +80,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);
 }
 /**
@@ -72,7 +110,8 @@ type WorkspaceEditErrorOptions = AIErrorOptions & {
   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;
+  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:
@@ -99,8 +138,43 @@ 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).
+ */
+type WorkspaceJobFailure = "not-found";
+/** Options for {@link WorkspaceJobError}. */
+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}`);
+ * }
+ */
+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 };
+export { WorkspaceEditError, WorkspaceEditErrorOptions, WorkspaceEditFailure, WorkspaceJobError, WorkspaceJobErrorOptions, WorkspaceJobFailure, WorkspacePolicyError, WorkspacePolicyErrorOptions, WorkspacePolicyViolation, WorkspaceShellRefusalReason };
 //# sourceMappingURL=errors.d.mts.map

package/esm/errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../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":";;;;;AAeA;;;;AAAoC;AA2BpC;;;;AAAuC;AAevC;KA1CY,wBAAA;;;;;;;;;;;;;;;;;AAsDA;AAoBZ;;;;;;;;KA/CY,2BAAA;;;;;;KAeA,2BAAA,GAA8B,cAAA;EA8CxB,sCA5ChB,IAAA,EAAM,wBAAA,EA8CU;EA5ChB,IAAA,WA8CmB;EA5CnB,OAAA,WA4CoC;EA1CpC,OAAA,WA0CwE;EAxCxE,MAAA,GAAS,2BAAA,EA8DqB;EA5D9B,UAAA;AAAA;AA4D8B;AAOhC;;;;;;;;;;;;;AAYW;AAiBX;;AApCgC,cAxCnB,oBAAA,SAA6B,OAAA;EA8ElB;EAAA,SA5EN,IAAA,EAAM,wBAAA;EA0EgB;EAAA,SAxEtB,IAAA;EAwE6B;EAAA,SAtE7B,OAAA;EAwEA;EAAA,SAtEA,OAAA;EAwEA;;;;;EAAA,SAlEA,MAAA,GAAS,2BAAA;EA+EN;EAAA,SA7EH,UAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,2BAAA;AAAA;AA2EyB;AAoBxE;;;;AAA+B;AAG/B;;;AAvBwE,KArD5D,oBAAA;;;;;;KAOA,yBAAA,GAA4B,cAAA;EAsF3B,iCApFX,IAAA,EAAM,oBAAoB;EAE1B,IAAA,UAwF6C;EAtF7C,OAAA,WAgF4C;EA9E5C,YAAA,WA8EqC;EA5ErC,UAAA,WA8EsB;EA5EtB,SAAA;AAAA;;;;;AAgFqE;;;;;;;;;;cA/D1D,kBAAA,SAA2B,OAAA;;WAEtB,IAAA,EAAM,oBAAA;;WAEN,IAAA;;WAEA,OAAA;;WAEA,YAAA;;WAEA,UAAA;;;;;WAKA,SAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,yBAAA;AAAA;;;;;;;;KAoBnC,mBAAA;;KAGA,wBAAA,GAA2B,cAAA;kCAErC,IAAA,EAAM,mBAAmB;EAEzB,KAAA;AAAA;;;;;;;;;;;cAaW,iBAAA,SAA0B,OAAA;;WAErB,IAAA,EAAM,mBAAA;;WAEN,KAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,wBAAA;AAAA"}

package/esm/errors.mjs

@@ -1,6 +1,6 @@
 import { AIError } from "@warlock.js/ai";
 
-//#region ../ai-workspace/src/errors.ts
+//#region ../../packages/ai-workspace/src/errors.ts
 /**
 * The workspace policy engine refused an operation — a path escaped the
 * jail (or hit a deny glob), or a shell command's executable was not
@@ -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":["../../../../../../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"}