@warlock.js/ai-workspace 5.30.0 → 5.31.0

package/esm/contracts/tool-io.type.d.mts

@@ -1,6 +1,6 @@
 //#region ../../packages/ai-workspace/src/contracts/tool-io.type.d.ts
 /**
- * Input/output shapes for the seven workspace tools and the direct
+ * Input/output shapes for the workspace tools and the direct
  * methods that back them. These are the wire contracts the agent sees
  * (via each tool's schema) and the values the policy-enforced ops layer
  * returns. Paths in every `*Input` are workspace-relative; the policy
@@ -10,7 +10,7 @@
  * The discriminating set of tool names a workspace can vend, used by
  * `tools.pick(...)` to select a least-privilege subset.
  */
-type WorkspaceToolName = "readFile" | "editFile" | "writeFile" | "runShell" | "runTests" | "grep" | "glob";
+type WorkspaceToolName = "readFile" | "editFile" | "multiEdit" | "writeFile" | "listDir" | "runShell" | "shellOutput" | "shellKill" | "runTests" | "grep" | "glob" | "todoWrite" | "todoRead";
 /** Input to the `read_file` tool / `readFile()` direct method. */
 interface ReadFileInput {
   /** Workspace-relative path to read. */
@@ -86,6 +86,40 @@ interface EditFileResult {
   /** SHA-256 of the file content after the edit. */
   hash: string;
 }
+/** One replacement inside a {@link MultiEditInput}. */
+interface MultiEditOperation {
+  /** Exact substring to replace; must be unique unless `replaceAll`. */
+  oldString: string;
+  /** Replacement text. */
+  newString: string;
+  /** Replace every occurrence instead of requiring a single unique match. */
+  replaceAll?: boolean;
+}
+/**
+ * Input to the `multi_edit` tool / `multiEdit()` direct method — several
+ * exact-string replacements in one file, applied in order (each edit sees
+ * the result of the previous ones) and written once. All of them apply or
+ * none do.
+ */
+interface MultiEditInput {
+  /** Workspace-relative path to edit. */
+  path: string;
+  /** The replacements, applied in order. At least one. */
+  edits: MultiEditOperation[];
+  /** Expected current SHA-256 of the file; a mismatch rejects every edit as stale. */
+  expectHash?: string;
+}
+/** Result of a successful multi-edit. */
+interface MultiEditResult {
+  /** Workspace-relative path that was edited. */
+  path: string;
+  /** Number of edits applied (always `edits.length`). */
+  edits: number;
+  /** Total occurrences replaced across every edit. */
+  replacements: number;
+  /** SHA-256 of the file content after all edits. */
+  hash: string;
+}
 /** Input to the `write_file` tool / `writeFile()` direct method. */
 interface WriteFileInput {
   /** Workspace-relative path to write (created if absent). */
@@ -115,10 +149,104 @@ interface ExecOptions {
 }
 /** Input to the `run_shell` tool / `exec()` direct method. */
 interface RunShellInput {
-  /** The command line to run; its leading basename is policy-checked. */
+  /** The command line to run; every command in it is policy-checked. */
   command: string;
   /** Per-call wall-clock cap (overrides the policy default if lower). */
   timeoutMs?: number;
+  /**
+   * Start the command as a background job and return its id at once,
+   * instead of waiting for it. Needs `shell.background` in the policy.
+   */
+  background?: boolean;
+}
+/**
+ * Lifecycle state of a background command.
+ *
+ * - `"running"` — still running.
+ * - `"exited"` — finished on its own; `exitCode` holds its exit code.
+ * - `"killed"` — stopped by `shell_kill` / `shellKill()` or `dispose()`.
+ * - `"timed-out"` — killed for exceeding `shell.background.timeoutMs` (or
+ *   the per-call `timeoutMs`).
+ */
+type ShellJobStatus = "running" | "exited" | "killed" | "timed-out";
+/** A background command owned by the workspace. */
+interface ShellJobInfo {
+  /** Workspace-unique id (`"job-1"`, `"job-2"`, …) for `shell_output` / `shell_kill`. */
+  id: string;
+  /** The command line it runs. */
+  command: string;
+  /** Lifecycle state. */
+  status: ShellJobStatus;
+  /** Exit code once it has stopped; `null` while running. */
+  exitCode: number | null;
+  /** OS process id of the direct child, when the backend has one. */
+  pid?: number;
+  /** ISO timestamp it was started. */
+  startedAt: string;
+  /** ISO timestamp it stopped, once it has. */
+  endedAt?: string;
+}
+/** What `run_shell` returns when called with `background: true`. */
+interface RunShellBackgroundResult extends ShellJobInfo {
+  /** Always `true` — tells this result apart from a foreground {@link RunShellResult}. */
+  background: true;
+}
+/** Options for `startShell()`. */
+interface StartShellOptions {
+  /**
+   * Wall-clock cap for this background command, in ms. Lowers
+   * `shell.background.timeoutMs` (never raises it); absent ⇒ the policy
+   * value, or no cap.
+   */
+  timeoutMs?: number;
+}
+/** Input to the `shell_output` tool. */
+interface ShellOutputInput {
+  /** The background command id `run_shell` returned. */
+  id: string;
+  /**
+   * Return only output produced after this `cursor` (from an earlier
+   * result). Omit to get everything since the previous read.
+   */
+  since?: number;
+  /**
+   * Wait up to this many ms (capped at 30 000) for new output or for the
+   * command to stop, when there is nothing new yet.
+   */
+  waitMs?: number;
+}
+/** Options for `shellOutput()`. */
+interface ShellOutputOptions {
+  /** See {@link ShellOutputInput.since}. */
+  since?: number;
+  /** See {@link ShellOutputInput.waitMs}. */
+  waitMs?: number;
+  /** Stops a `waitMs` wait early. */
+  signal?: AbortSignal;
+}
+/** New output of a background command plus its current state. */
+interface ShellOutputResult extends ShellJobInfo {
+  /** Standard output produced after `since`. */
+  stdout: string;
+  /** Standard error produced after `since`. */
+  stderr: string;
+  /**
+   * Total bytes the command has produced so far (both streams). Pass it as
+   * `since` to read only what comes next.
+   */
+  cursor: number;
+  /**
+   * Bytes produced after `since` that are no longer kept (the per-command
+   * buffer holds the newest `shell.maxOutputBytes`).
+   */
+  droppedBytes: number;
+  /** True when `droppedBytes > 0`. */
+  truncated: boolean;
+}
+/** Input to the `shell_kill` tool. */
+interface ShellKillInput {
+  /** The background command id to stop. */
+  id: string;
 }
 /** Result of a shell command — captured streams plus how it terminated. */
 interface RunShellResult {
@@ -173,6 +301,44 @@ interface GrepResult {
   /** Total number of matches (== `matches.length` unless capped). */
   total: number;
 }
+/** Input to the `list_dir` tool. */
+interface ListDirInput {
+  /** Workspace-relative directory to list. Default `"."` (the root). */
+  path?: string;
+  /** How many levels deep to list (1 = direct children). Default `1`. */
+  depth?: number;
+  /** Extra globs to leave out, on top of `list.ignore` and `denyPaths`. */
+  ignore?: string[];
+}
+/** Options for `listDir()`. */
+interface ListDirOptions {
+  /** See {@link ListDirInput.depth}. */
+  depth?: number;
+  /** See {@link ListDirInput.ignore}. */
+  ignore?: string[];
+}
+/** Kind of a listed entry. A symlink is reported, never followed. */
+type ListDirEntryType = "file" | "directory" | "symlink" | "other";
+/** One entry of a directory listing. */
+interface ListDirEntry {
+  /** Workspace-relative path (absolute for a directory outside `cwd` in `allowPaths`). */
+  path: string;
+  /** Entry kind. */
+  type: ListDirEntryType;
+  /** Size in bytes, for files (when the backend reports it). */
+  size?: number;
+  /** 1 for a direct child of the listed directory, 2 for a grandchild, … */
+  depth: number;
+}
+/** Result of a directory listing. */
+interface ListDirResult {
+  /** The listed directory, workspace-relative (`"."` for the root). */
+  path: string;
+  /** Entries, breadth-first, each level sorted by name. */
+  entries: ListDirEntry[];
+  /** True when `list.maxEntries` cut the listing short. */
+  truncated: boolean;
+}
 /** Input to the `glob` tool / `glob()` direct method. */
 interface GlobInput {
   /** Glob pattern resolved relative to `cwd` (e.g. `"src/api/*.ts"`). */
@@ -183,6 +349,38 @@ interface GlobResult {
   /** Workspace-relative paths matching the pattern, sorted. */
   paths: string[];
 }
+/** State of one todo item. */
+type WorkspaceTodoStatus = "pending" | "in_progress" | "completed";
+/** One item of the workspace's todo list. */
+interface WorkspaceTodo {
+  /** Stable id (assigned `"1"`, `"2"`, … when the writer omits it). */
+  id: string;
+  /** What the step is. */
+  content: string;
+  /** Its state. */
+  status: WorkspaceTodoStatus;
+}
+/** One item as written by `todo_write` / `writeTodos()` — `id` is optional. */
+interface WorkspaceTodoInput {
+  /** Stable id; omit to have one assigned from the item's position. */
+  id?: string;
+  /** What the step is (non-empty, at most 1 000 characters). */
+  content: string;
+  /** Its state. */
+  status: WorkspaceTodoStatus;
+}
+/** Input to the `todo_write` tool — the whole new list, replacing the old one. */
+interface TodoWriteInput {
+  /** The complete list (at most 100 items). An empty list clears it. */
+  todos: WorkspaceTodoInput[];
+}
+/** The todo list plus a count per status. */
+interface TodoListResult {
+  /** Every item, in order. */
+  todos: WorkspaceTodo[];
+  /** How many items are in each status. */
+  counts: Record<WorkspaceTodoStatus, number>;
+}
 //#endregion
-export { EditFileInput, EditFileResult, ExecOptions, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ReadFileInput, ReadFileResult, RunShellInput, RunShellResult, RunTestsInput, WorkspaceToolName, WriteFileInput, WriteFileResult };
+export { 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 };
 //# sourceMappingURL=tool-io.type.d.mts.map

package/esm/contracts/tool-io.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-io.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/tool-io.type.ts"],"mappings":";;AAYA;;;;AAA6B;AAU7B;;;;;KAVY,iBAAA;;UAUK,aAAA;EAMV;EAJL,IAAA;EAmB6B;EAjB7B,SAAA;EAiB6B;EAf7B,KAAA;AAAA;;;;;;;;AA0CI;AAON;;;;UAlCiB,cAAA;EAsCf;EApCA,OAAA;EAwCA;EAtCA,SAAA;EAwCU;AAAA;AAIZ;;EAvCE,OAAA;EAuC6B;EArC7B,UAAA;EAyCA;;;AAEI;AAIN;EAzCE,SAAA;;EAEA,WAAA;EA2CO;EAzCP,UAAA;EA6C8B;;;;;EAvC9B,IAAA;AAAA;AA6CI;AAIN;;;AAJM,UAtCW,aAAA;EA4Cf;EA1CA,IAAA;EAgDS;EA9CT,SAAA;EA8CoB;EA5CpB,SAAA;EAgD4B;EA9C5B,UAAA;EAgDA;EA9CA,UAAA;AAAA;;UAIe,cAAA;EAgDc;EA9C7B,IAAA;EAkDA;EAhDA,YAAA;EAoDA;EAlDA,IAAA;AAAA;;UAIe,cAAA;EA8DA;EA5Df,IAAA;;EAEA,OAAO;AAAA;AAgET;AAAA,UA5DiB,eAAA;;EAEf,IAAA;EA4DA;EA1DA,YAAA;EA8DA;EA5DA,IAAA;AAAA;AAgEF;AAAA,UA5DiB,WAAA;;EAEf,SAAA;EA4DA;;;;AAII;EA1DJ,MAAA,GAAS,WAAW;AAAA;;UAIL,aAAA;EA4Df;EA1DA,OAAA;EA4DA;EA1DA,SAAS;AAAA;AA8DX;AAAA,UA1DiB,cAAA;;EAEf,QAAA;EA0DO;EAxDP,MAAA;EA4DyB;EA1DzB,MAAA;EA4DK;EA1DL,SAAA;;EAEA,QAAA;;;;;;EAMA,SAAA;AAAA;;;;;;UAQe,aAAA;;EAEf,OAAO;AAAA;;UAIQ,SAAA;;EAEf,OAAA;;EAEA,IAAA;;EAEA,UAAA;AAAA;;UAIe,SAAA;;EAEf,IAAA;;EAEA,IAAA;;EAEA,IAAA;AAAA;;UAIe,UAAA;;EAEf,OAAA,EAAS,SAAS;;EAElB,KAAA;AAAA;;UAIe,SAAA;;EAEf,OAAO;AAAA;;UAIQ,UAAA;;EAEf,KAAK;AAAA"}
+{"version":3,"file":"tool-io.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/tool-io.type.ts"],"mappings":"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"}

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

@@ -1,3 +1,5 @@
+import { WorkspaceShellInterpreter } from "./workspace-policy.type.mjs";
+
 //#region ../../packages/ai-workspace/src/contracts/workspace-backend.contract.d.ts
 /**
  * Low-level result of a backend command execution. Mirrors the shape the
@@ -43,6 +45,52 @@ interface WorkspaceBackendExecOptions {
    * backend.
    */
   signal?: AbortSignal;
+  /**
+   * How to run `command`: `"none"` (default) tokenizes it into an argv and
+   * spawns it without a shell; `"sh"` hands the whole line to `/bin/sh -c`
+   * (`cmd.exe /d /v:off /s /c` on Windows). The ops layer has already
+   * checked every command in the line against the policy; a backend that
+   * does not support `"sh"` must refuse the command rather than run it
+   * another way.
+   */
+  interpreter?: WorkspaceShellInterpreter;
+}
+/** Which stream a background command's output chunk came from. */
+type WorkspaceOutputStream = "stdout" | "stderr";
+/** Options for {@link WorkspaceBackend.start}. */
+interface WorkspaceBackendStartOptions {
+  /** Working directory for the spawned process (already jail-resolved). */
+  cwd?: string;
+  /** Exact environment for the spawned process (NOT merged with process.env). */
+  env?: Record<string, string>;
+  /** See {@link WorkspaceBackendExecOptions.interpreter}. */
+  interpreter?: WorkspaceShellInterpreter;
+  /**
+   * Receives output as it arrives, decoded as UTF-8 and never split inside a
+   * character. Called synchronously or later — never after `done` settles.
+   */
+  onOutput(stream: WorkspaceOutputStream, chunk: string): void;
+}
+/** A running background command, as a backend hands it to the ops layer. */
+interface WorkspaceBackendProcess {
+  /** OS process id of the direct child, when there is one. */
+  readonly pid?: number;
+  /**
+   * Settles once the process has exited and its output has been delivered.
+   * Never rejects: a spawn failure resolves with exit code `127`.
+   */
+  readonly done: Promise<{
+    exitCode: number;
+  }>;
+  /** Kill the whole process tree. Idempotent; safe after it has exited. */
+  kill(): void;
+}
+/** What {@link WorkspaceBackend.stat} reports about a path (symlinks are not followed). */
+interface WorkspaceBackendStat {
+  /** Entry kind. */
+  type: "file" | "directory" | "symlink" | "other";
+  /** Size in bytes. */
+  size: number;
 }
 /**
  * The swappable executor a workspace runs on — the thin, **policy-agnostic**
@@ -79,7 +127,19 @@ interface WorkspaceBackend {
   realpath(absPath: string): Promise<string>;
   /** Run a command and capture its outcome. */
   exec(command: string, opts?: WorkspaceBackendExecOptions): Promise<WorkspaceBackendExecResult>;
+  /**
+   * Describe an absolute path without following a final symlink. Optional:
+   * without it, `list_dir` tells files from directories by trying to list
+   * them and reports no sizes.
+   */
+  stat?(absPath: string): Promise<WorkspaceBackendStat>;
+  /**
+   * Start a long-running command and return at once. Optional: without it,
+   * background commands are refused. The process must be its own process
+   * group (or equivalent) so `kill()` reaches every descendant.
+   */
+  start?(command: string, opts: WorkspaceBackendStartOptions): WorkspaceBackendProcess;
 }
 //#endregion
-export { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult };
+export { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult, WorkspaceBackendProcess, WorkspaceBackendStartOptions, WorkspaceBackendStat, WorkspaceOutputStream };
 //# sourceMappingURL=workspace-backend.contract.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"workspace-backend.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-backend.contract.ts"],"mappings":";;AAMA;;;;;UAAiB,0BAAA;EAMf;EAJA,QAAA;EAaA;EAXA,MAAA;EAWS;EATT,MAAA;EAiB0C;EAf1C,QAAA;EA8BoB;;;;;;EAvBpB,SAAA;AAAA;AAuBoB;AAqBtB;;;;AArBsB,UAfL,2BAAA;EA0CU;EAxCzB,GAAA;EA4CyB;EA1CzB,SAAA;EA8C2B;EA5C3B,GAAA,GAAM,MAAA;EAiDK;;;;;;;;EAxCX,MAAA,GAAS,WAAW;AAAA;;;;;;;;;;;;;;;;;;;UAqBL,gBAAA;EAkBb;EAhBF,QAAA,CAAS,OAAA,WAAkB,OAAA;EAiBhB;EAfX,SAAA,CAAU,OAAA,UAAiB,OAAA,WAAkB,OAAA;EAeR;EAbrC,MAAA,CAAO,OAAA,WAAkB,OAAA;;EAEzB,KAAA,CAAM,OAAA,WAAkB,OAAA;;EAExB,MAAA,CAAO,OAAA,WAAkB,OAAA;;EAEzB,IAAA,CAAK,MAAA,WAAiB,OAAA;;EAEtB,QAAA,CAAS,OAAA,WAAkB,OAAA;;EAE3B,IAAA,CACE,OAAA,UACA,IAAA,GAAO,2BAAA,GACN,OAAA,CAAQ,0BAAA;AAAA"}
+{"version":3,"file":"workspace-backend.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-backend.contract.ts"],"mappings":";;;;;AAQA;;;;UAAiB,0BAAA;EAIf;EAFA,QAAA;EAMA;EAJA,MAAA;EAWS;EATT,MAAA;EAiBe;EAff,QAAA;;;;;;;EAOA,SAAA;AAAA;;;;;;UAQe,2BAAA;EAwBwB;EAtBvC,GAAA;EA0BU;EAxBV,SAAA;;EAEA,GAAA,GAAM,MAAA;EAsByB;AAGjC;;;;;;;EAhBE,MAAA,GAAS,WAAA;EAkBT;;;;;;;;EATA,WAAA,GAAc,yBAAA;AAAA;AAkBuC;AAAA,KAd3C,qBAAA;;UAGK,4BAAA;EAsBO;EApBtB,GAAA;EAoBS;EAlBT,GAAA,GAAM,MAAA;EAkBmB;EAhBzB,WAAA,GAAc,yBAAA;EAkBV;AAAA;AAIN;;EAjBE,QAAA,CAAS,MAAA,EAAQ,qBAAA,EAAuB,KAAA;AAAA;AAqBpC;AAAA,UAjBW,uBAAA;EAsCgB;EAAA,SApCtB,GAAA;EAsCkB;;;;EAAA,SAjClB,IAAA,EAAM,OAAO;IAAG,QAAA;EAAA;EA+CI;EA7C7B,IAAA;AAAA;;UAIe,oBAAA;EAqDe;EAnD9B,IAAA;EAmDoF;EAjDpF,IAAI;AAAA;;;;;;;;;;;;;;;;;;;UAqBW,gBAAA;EAcN;EAZT,QAAA,CAAS,OAAA,WAAkB,OAAA;EAc3B;EAZA,SAAA,CAAU,OAAA,UAAiB,OAAA,WAAkB,OAAA;EAYhB;EAV7B,MAAA,CAAO,OAAA,WAAkB,OAAA;EAUkC;EAR3D,KAAA,CAAM,OAAA,WAAkB,OAAA;EAcxB;EAZA,MAAA,CAAO,OAAA,WAAkB,OAAA;EAYD;EAVxB,IAAA,CAAK,MAAA,WAAiB,OAAA;EAgBtB;EAdA,QAAA,CAAS,OAAA,WAAkB,OAAA;EAcG;EAZ9B,IAAA,CAAK,OAAA,UAAiB,IAAA,GAAO,2BAAA,GAA8B,OAAA,CAAQ,0BAAA;EAYN;;AAAuB;;;EANpF,IAAA,EAAM,OAAA,WAAkB,OAAA,CAAQ,oBAAA;;;;;;EAMhC,KAAA,EAAO,OAAA,UAAiB,IAAA,EAAM,4BAAA,GAA+B,uBAAA;AAAA"}

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

@@ -1,4 +1,4 @@
-import { EditFileInput, EditFileResult, ExecOptions, GrepResult, ReadFileResult, RunShellResult } from "./tool-io.type.mjs";
+import { EditFileInput, EditFileResult, ExecOptions, GrepResult, ListDirOptions, ListDirResult, MultiEditInput, MultiEditResult, ReadFileResult, RunShellResult, ShellJobInfo, ShellOutputOptions, ShellOutputResult, StartShellOptions } from "./tool-io.type.mjs";
 
 //#region ../../packages/ai-workspace/src/contracts/workspace-ops.contract.d.ts
 /**
@@ -43,12 +43,35 @@ interface WorkspaceOps {
    */
   editFile(input: EditFileInput): Promise<EditFileResult>;
   /**
-   * Run a shell command after gating its leading executable basename
-   * against the shell allow/deny policy, with the policy environment,
+   * Apply several exact-string edits to one file atomically: each edit runs
+   * against the result of the previous ones, under the same uniqueness rules
+   * as `editFile`, and the file is written once — or, when any edit fails,
+   * not at all (`WorkspaceEditError` with `editIndex`).
+   */
+  multiEdit(input: MultiEditInput): Promise<MultiEditResult>;
+  /**
+   * Run a command line after checking every command in it against the
+   * shell policy (see `WorkspaceShellPolicy`), with the policy environment,
    * timeout, and output byte cap applied. `signal` cancels this one call
    * (see {@link ExecOptions}).
    */
   exec(command: string, opts?: ExecOptions): Promise<RunShellResult>;
+  /**
+   * Start a policy-checked command as a background job owned by the
+   * workspace and return at once. Needs `shell.background`.
+   */
+  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 and report its final state. */
+  shellKill(id: string): Promise<ShellJobInfo>;
+  /** Every background command this workspace knows, oldest first. */
+  listShells(): ShellJobInfo[];
+  /**
+   * List a jailed directory — bounded by depth and `list.maxEntries`, with
+   * `denyPaths` and `list.ignore` left out and symlinks never followed.
+   */
+  listDir(path?: string, opts?: ListDirOptions): Promise<ListDirResult>;
   /** Search jailed file contents for a regex pattern. */
   grep(pattern: string, opts?: {
     glob?: string;
@@ -62,6 +85,12 @@ interface WorkspaceOps {
   mkdir(path: string): Promise<void>;
   /** Remove a file or directory tree at a jailed path. */
   remove(path: string): Promise<void>;
+  /**
+   * Kill every background command (whole process trees) and refuse new
+   * commands. A foreground command already running finishes on its own (or
+   * by its timeout / signal). Idempotent.
+   */
+  dispose(): Promise<void>;
 }
 //#endregion
 export { WorkspaceOps };

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

@@ -1 +1 @@
-{"version":3,"file":"workspace-ops.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-ops.contract.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;UAAiB,YAAA;EAiDc;;;;;;EA1C7B,QAAA,CACE,IAAA,UACA,IAAA;IAAS,MAAA;IAAiB,KAAA;EAAA,IACzB,OAAA,CAAQ,cAAA;EAIT;EADF,SAAA,CACE,IAAA,UACA,OAAA,WACC,OAAA;IAAU,IAAA;IAAc,YAAA;EAAA;EAO3B;;;;;EAAA,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,cAAA;EAQnC;;;;;;EAAL,IAAA,CAAK,OAAA,UAAiB,IAAA,GAAO,WAAA,GAAc,OAAA,CAAQ,cAAA;EAKxC;EAFX,IAAA,CACE,OAAA,UACA,IAAA;IAAS,IAAA;IAAe,UAAA;EAAA,IACvB,OAAA,CAAQ,UAAA;EAGX;EAAA,IAAA,CAAK,OAAA,WAAkB,OAAA;EAAA;EAGvB,MAAA,CAAO,IAAA,WAAe,OAAA;EAAf;EAGP,KAAA,CAAM,IAAA,WAAe,OAAA;EAArB;EAGA,MAAA,CAAO,IAAA,WAAe,OAAA;AAAA"}
+{"version":3,"file":"workspace-ops.contract.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-ops.contract.ts"],"mappings":";;;;;AAoCA;;;;;;;;;;;;;;;;;UAAiB,YAAA;EA0CgB;;;;;;EAnC/B,QAAA,CAAS,IAAA,UAAc,IAAA;IAAS,MAAA;IAAiB,KAAA;EAAA,IAAmB,OAAA,CAAQ,cAAA;EAkDL;EA/CvE,SAAA,CAAU,IAAA,UAAc,OAAA,WAAkB,OAAA;IAAU,IAAA;IAAc,YAAA;EAAA;EAkEvD;;;;;EA3DX,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,cAAA;EAVS;;;;;;EAkBjD,SAAA,CAAU,KAAA,EAAO,cAAA,GAAiB,OAAA,CAAQ,eAAA;EAfA;;;;;;EAuB1C,IAAA,CAAK,OAAA,UAAiB,IAAA,GAAO,WAAA,GAAc,OAAA,CAAQ,cAAA;EAhBX;;;;EAsBxC,UAAA,CAAW,OAAA,UAAiB,IAAA,GAAO,iBAAA,GAAoB,OAAA,CAAQ,YAAA;EAdrB;EAiB1C,WAAA,CAAY,EAAA,UAAY,IAAA,GAAO,kBAAA,GAAqB,OAAA,CAAQ,iBAAA;EATvD;EAYL,SAAA,CAAU,EAAA,WAAa,OAAA,CAAQ,YAAA;EAZT;EAetB,UAAA,IAAc,YAAA;EAfqC;;;;EAqBnD,OAAA,CAAQ,IAAA,WAAe,IAAA,GAAO,cAAA,GAAiB,OAAA,CAAQ,aAAA;EAfA;EAkBvD,IAAA,CAAK,OAAA,UAAiB,IAAA;IAAS,IAAA;IAAe,UAAA;EAAA,IAAyB,OAAA,CAAQ,UAAA;EAfvD;EAkBxB,IAAA,CAAK,OAAA,WAAkB,OAAA;EAlBqC;EAqB5D,MAAA,CAAO,IAAA,WAAe,OAAA;EAlBZ;EAqBV,KAAA,CAAM,IAAA,WAAe,OAAA;EArBU;EAwB/B,MAAA,CAAO,IAAA,WAAe,OAAA;EArBR;;;;;EA4Bd,OAAA,IAAW,OAAA;AAAA"}

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

@@ -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,6 +140,11 @@ 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.
@@ -60,6 +162,23 @@ interface WorkspaceReadPolicy {
   /** Default number of lines a read returns when no explicit limit is given. */
   defaultLines?: number;
 }
+/**
+ * Directory-listing sub-policy for the `list_dir` tool and `listDir()`.
+ * `denyPaths` are always hidden from listings; `ignore` hides more without
+ * blocking access (an ignored file can still be read).
+ */
+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.
@@ -90,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":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-policy.type.ts"],"mappings":";;AAQA;;;;AAAgC;AAqBhC;;KArBY,oBAAA;;;;;;;;;;AAoCA;AAOZ;;;;AAUc;AAsBd;;;;UAtDiB,oBAAA;EAkEL;EAhEV,KAAA;EAgE8B;EA9D9B,IAAA;EAsDA;EApDA,SAAA;EAwDA;EAtDA,cAAA;EAwDA;EAtDA,GAAA,GAAM,MAAM;EAwDZ;;;AAA8B;EAnD9B,UAAA;AAAA;;;;;UAOe,mBAAA;;;;;;;;EAQf,QAAA;;EAEA,YAAY;AAAA;;;;;;;;;;;;;;;;;;;;UAsBG,eAAA;;EAEf,GAAA;;EAEA,UAAA;;EAEA,SAAA;;EAEA,KAAA,GAAQ,oBAAA;;EAER,IAAA,GAAO,mBAAA;;EAEP,OAAA,GAAU,oBAAA;AAAA"}
+{"version":3,"file":"workspace-policy.type.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/contracts/workspace-policy.type.ts"],"mappings":";;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"}