@warlock.js/ai-workspace 5.30.0 → 5.31.0

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

@@ -1,4 +1,4 @@
-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";
 
@@ -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"] } });
@@ -93,12 +120,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;

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":"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"}

package/esm/errors.d.mts

@@ -6,13 +6,41 @@ import { AIError, AIErrorOptions } from "@warlock.js/ai";
  *
  * - `"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":["../../../../../../../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":";;;;;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

@@ -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"}

package/esm/index.d.mts

@@ -1,20 +1,28 @@
-import { EditFileInput, EditFileResult, ExecOptions, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ReadFileInput, ReadFileResult, RunShellInput, RunShellResult, RunTestsInput, WorkspaceToolName, WriteFileInput, WriteFileResult } from "./contracts/tool-io.type.mjs";
-import { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult } from "./contracts/workspace-backend.contract.mjs";
+import { EditFileInput, EditFileResult, ExecOptions, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ListDirEntry, ListDirEntryType, ListDirInput, ListDirOptions, ListDirResult, MultiEditInput, MultiEditOperation, MultiEditResult, ReadFileInput, ReadFileResult, RunShellBackgroundResult, RunShellInput, RunShellResult, RunTestsInput, ShellJobInfo, ShellJobStatus, ShellKillInput, ShellOutputInput, ShellOutputOptions, ShellOutputResult, StartShellOptions, TodoListResult, TodoWriteInput, WorkspaceTodo, WorkspaceTodoInput, WorkspaceTodoStatus, WorkspaceToolName, WriteFileInput, WriteFileResult } from "./contracts/tool-io.type.mjs";
+import { WorkspaceAllowCommand, WorkspaceBackendType, WorkspaceBackgroundPolicy, WorkspaceCommandCheckContext, WorkspaceCommandPattern, WorkspaceListPolicy, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellInterpreter, WorkspaceShellPolicy } from "./contracts/workspace-policy.type.mjs";
+import { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult, WorkspaceBackendProcess, WorkspaceBackendStartOptions, WorkspaceBackendStat, WorkspaceOutputStream } from "./contracts/workspace-backend.contract.mjs";
 import { WorkspaceOps } from "./contracts/workspace-ops.contract.mjs";
-import { WorkspaceBackendType, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellPolicy } from "./contracts/workspace-policy.type.mjs";
 import { Workspace, WorkspaceTools } from "./contracts/workspace.contract.mjs";
-import { WorkspaceEditError, WorkspaceEditErrorOptions, WorkspaceEditFailure, WorkspacePolicyError, WorkspacePolicyErrorOptions, WorkspacePolicyViolation } from "./errors.mjs";
+import { WorkspaceEditError, WorkspaceEditErrorOptions, WorkspaceEditFailure, WorkspaceJobError, WorkspaceJobErrorOptions, WorkspaceJobFailure, WorkspacePolicyError, WorkspacePolicyErrorOptions, WorkspacePolicyViolation, WorkspaceShellRefusalReason } from "./errors.mjs";
 import { ResolvedPath, buildEnv, isCommandAllowed, resolveInJail } from "./policy/policy.mjs";
+import { WorkspaceShellCheck, WorkspaceShellPath, WorkspaceShellPathAccess, checkShellCommand } from "./policy/shell-check.mjs";
+import { ArgvAnalysis, analyzeArgvCommand, tokenizeCommand } from "./policy/tokenize-command.mjs";
 import { createOps } from "./ops.mjs";
 import { createLocalBackend } from "./backends/local.mjs";
 import { MockBackendSeed, MockExecResult, createMockBackend } from "./backends/mock.mjs";
 import { makeEditFileTool } from "./tools/edit-file.mjs";
 import { MakeGlobToolOptions, makeGlobTool } from "./tools/glob.mjs";
 import { MakeGrepToolOptions, makeGrepTool } from "./tools/grep.mjs";
+import { makeListDirTool } from "./tools/list-dir.mjs";
+import { makeMultiEditTool } from "./tools/multi-edit.mjs";
 import { makeReadFileTool } from "./tools/read-file.mjs";
 import { MakeRunShellToolOptions, makeRunShellTool } from "./tools/run-shell.mjs";
 import { MakeRunTestsToolOptions, makeRunTestsTool } from "./tools/run-tests.mjs";
+import { makeShellKillTool } from "./tools/shell-kill.mjs";
+import { makeShellOutputTool } from "./tools/shell-output.mjs";
+import { TodoStore } from "./todos.mjs";
+import { makeTodoReadTool, makeTodoWriteTool } from "./tools/todo.mjs";
 import { makeWriteFileTool } from "./tools/write-file.mjs";
 import { workspace } from "./workspace.mjs";
-export { type EditFileInput, type EditFileResult, type ExecOptions, type GlobInput, type GlobResult, type GrepInput, type GrepMatch, type GrepResult, type MakeGlobToolOptions, type MakeGrepToolOptions, type MakeRunShellToolOptions, type MakeRunTestsToolOptions, type MockBackendSeed, type MockExecResult, type ReadFileInput, type ReadFileResult, type ResolvedPath, type RunShellInput, type RunShellResult, type RunTestsInput, type Workspace, type WorkspaceBackend, type WorkspaceBackendExecOptions, type WorkspaceBackendExecResult, type WorkspaceBackendType, WorkspaceEditError, type WorkspaceEditErrorOptions, type WorkspaceEditFailure, type WorkspaceOps, type WorkspacePolicy, WorkspacePolicyError, type WorkspacePolicyErrorOptions, type WorkspacePolicyViolation, type WorkspaceReadPolicy, type WorkspaceShellPolicy, type WorkspaceToolName, type WorkspaceTools, type WriteFileInput, type WriteFileResult, buildEnv, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeWriteFileTool, resolveInJail, workspace };
+export { type ArgvAnalysis, type EditFileInput, type EditFileResult, type ExecOptions, type GlobInput, type GlobResult, type GrepInput, type GrepMatch, type GrepResult, type ListDirEntry, type ListDirEntryType, type ListDirInput, type ListDirOptions, type ListDirResult, type MakeGlobToolOptions, type MakeGrepToolOptions, type MakeRunShellToolOptions, type MakeRunTestsToolOptions, type MockBackendSeed, type MockExecResult, type MultiEditInput, type MultiEditOperation, type MultiEditResult, type ReadFileInput, type ReadFileResult, type ResolvedPath, type RunShellBackgroundResult, type RunShellInput, type RunShellResult, type RunTestsInput, type ShellJobInfo, type ShellJobStatus, type ShellKillInput, type ShellOutputInput, type ShellOutputOptions, type ShellOutputResult, type StartShellOptions, type TodoListResult, TodoStore, type TodoWriteInput, type Workspace, type WorkspaceAllowCommand, type WorkspaceBackend, type WorkspaceBackendExecOptions, type WorkspaceBackendExecResult, type WorkspaceBackendProcess, type WorkspaceBackendStartOptions, type WorkspaceBackendStat, type WorkspaceBackendType, type WorkspaceBackgroundPolicy, type WorkspaceCommandCheckContext, type WorkspaceCommandPattern, WorkspaceEditError, type WorkspaceEditErrorOptions, type WorkspaceEditFailure, WorkspaceJobError, type WorkspaceJobErrorOptions, type WorkspaceJobFailure, type WorkspaceListPolicy, type WorkspaceOps, type WorkspaceOutputStream, type WorkspacePolicy, WorkspacePolicyError, type WorkspacePolicyErrorOptions, type WorkspacePolicyViolation, type WorkspaceReadPolicy, type WorkspaceShellCheck, type WorkspaceShellInterpreter, type WorkspaceShellPath, type WorkspaceShellPathAccess, type WorkspaceShellPolicy, type WorkspaceShellRefusalReason, type WorkspaceTodo, type WorkspaceTodoInput, type WorkspaceTodoStatus, type WorkspaceToolName, type WorkspaceTools, type WriteFileInput, type WriteFileResult, analyzeArgvCommand, buildEnv, checkShellCommand, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeListDirTool, makeMultiEditTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeShellKillTool, makeShellOutputTool, makeTodoReadTool, makeTodoWriteTool, makeWriteFileTool, resolveInJail, tokenizeCommand, workspace };
 import "./workspace.mjs";

package/esm/index.mjs

@@ -1,4 +1,6 @@
-import { WorkspaceEditError, WorkspacePolicyError } from "./errors.mjs";
+import { WorkspaceEditError, WorkspaceJobError, WorkspacePolicyError } from "./errors.mjs";
+import { analyzeArgvCommand, tokenizeCommand } from "./policy/tokenize-command.mjs";
+import { checkShellCommand } from "./policy/shell-check.mjs";
 import { buildEnv, isCommandAllowed, resolveInJail } from "./policy/policy.mjs";
 import { createOps } from "./ops.mjs";
 import { createLocalBackend } from "./backends/local.mjs";
@@ -6,10 +8,16 @@ import { createMockBackend } from "./backends/mock.mjs";
 import { makeEditFileTool } from "./tools/edit-file.mjs";
 import { makeGlobTool } from "./tools/glob.mjs";
 import { makeGrepTool } from "./tools/grep.mjs";
+import { makeListDirTool } from "./tools/list-dir.mjs";
+import { makeMultiEditTool } from "./tools/multi-edit.mjs";
 import { makeReadFileTool } from "./tools/read-file.mjs";
 import { makeRunShellTool } from "./tools/run-shell.mjs";
 import { makeRunTestsTool } from "./tools/run-tests.mjs";
+import { makeShellKillTool } from "./tools/shell-kill.mjs";
+import { makeShellOutputTool } from "./tools/shell-output.mjs";
+import { TodoStore } from "./todos.mjs";
+import { makeTodoReadTool, makeTodoWriteTool } from "./tools/todo.mjs";
 import { makeWriteFileTool } from "./tools/write-file.mjs";
 import { workspace } from "./workspace.mjs";
 
-export { WorkspaceEditError, WorkspacePolicyError, buildEnv, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeWriteFileTool, resolveInJail, workspace };
+export { TodoStore, WorkspaceEditError, WorkspaceJobError, WorkspacePolicyError, analyzeArgvCommand, buildEnv, checkShellCommand, createLocalBackend, createMockBackend, createOps, isCommandAllowed, makeEditFileTool, makeGlobTool, makeGrepTool, makeListDirTool, makeMultiEditTool, makeReadFileTool, makeRunShellTool, makeRunTestsTool, makeShellKillTool, makeShellOutputTool, makeTodoReadTool, makeTodoWriteTool, makeWriteFileTool, resolveInJail, tokenizeCommand, workspace };

package/esm/ops.d.mts

@@ -1,7 +1,24 @@
+import { WorkspacePolicy } from "./contracts/workspace-policy.type.mjs";
 import { WorkspaceBackend } from "./contracts/workspace-backend.contract.mjs";
 import { WorkspaceOps } from "./contracts/workspace-ops.contract.mjs";
-import { WorkspacePolicy } from "./contracts/workspace-policy.type.mjs";
+import { ShellJobs } from "./shell-jobs.mjs";
+
 //#region ../../packages/ai-workspace/src/ops.d.ts
+/**
+ * The internal, single-instance implementation of {@link WorkspaceOps}.
+ * Holds the backend + policy and is the one place the jail, command
+ * gating, read caps, and the read-before-edit guard are enforced — both
+ * the agent-facing tools and the human-facing direct methods funnel
+ * through this object, so there is exactly one set of rules.
+ */
+/**
+ * State an ops layer shares with the other projections of the same
+ * workspace (`readonly()`, `scope()`): the background commands it owns.
+ */
+interface OpsRuntime {
+  /** The workspace's background commands. */
+  jobs: ShellJobs;
+}
 /**
  * Create the policy-enforced operation layer over a backend.
  *
@@ -14,12 +31,14 @@ import { WorkspacePolicy } from "./contracts/workspace-policy.type.mjs";
  *
  * @param backend - The dumb IO executor (local disk or in-memory mock).
  * @param policy - The policy that bounds every operation.
+ * @param runtime - State shared with other views of the same workspace
+ *   (its background commands); a fresh one when omitted.
  *
  * @example
  * const ops = createOps(localBackend, { cwd: "/srv/api", shell: { allow: ["npm"] } });
  * const { content, hash } = await ops.readFile("src/index.ts");
  */
-declare function createOps(backend: WorkspaceBackend, policy: WorkspacePolicy): WorkspaceOps;
+declare function createOps(backend: WorkspaceBackend, policy: WorkspacePolicy, runtime?: OpsRuntime): WorkspaceOps;
 //#endregion
 export { createOps };
 //# sourceMappingURL=ops.d.mts.map

package/esm/ops.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ops.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/ops.ts"],"mappings":";;;;;;;;;AAunBA;;;;;;;;;;;;iBAAgB,SAAA,CACd,OAAA,EAAS,gBAAA,EACT,MAAA,EAAQ,eAAA,GACP,YAAA"}
+{"version":3,"file":"ops.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/ops.ts"],"mappings":";;;;;;;;;AA8LA;;;;AAEiB;AAitBjB;;;AAjtBiB,UAFA,UAAA;EAqtBP;EAntBR,IAAA,EAAM,SAAS;AAAA;;;;;;;;;;;AAqtBF;;;;;;;;;iBAJC,SAAA,CACd,OAAA,EAAS,gBAAA,EACT,MAAA,EAAQ,eAAA,EACR,OAAA,GAAU,UAAA,GACT,YAAA"}