@warlock.js/ai-workspace 5.30.0 → 5.32.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,9 +10,9 @@
  * 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";
+export 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 {
+export interface ReadFileInput {
   /** Workspace-relative path to read. */
   path: string;
   /** 1-based line to start from. Omit to start at the top. */
@@ -32,7 +32,7 @@ interface ReadFileInput {
  * returned line may be partial — clipped on a character boundary, never
  * mid-character — and `bytesCapped` is `true`.
  */
-interface ReadFileResult {
+export interface ReadFileResult {
   /** The returned, line-numbered file content for the requested window. */
   content: string;
   /** 1-based first line requested. */
@@ -65,7 +65,7 @@ interface ReadFileResult {
  * Input to the `edit_file` tool / `editFile()` direct method — an
  * exact-string replacement with a read-before-edit stale guard.
  */
-interface EditFileInput {
+export interface EditFileInput {
   /** Workspace-relative path to edit. */
   path: string;
   /** Exact substring to replace; must be unique unless `replaceAll`. */
@@ -78,7 +78,7 @@ interface EditFileInput {
   expectHash?: string;
 }
 /** Result of a successful edit. */
-interface EditFileResult {
+export interface EditFileResult {
   /** Workspace-relative path that was edited. */
   path: string;
   /** Number of occurrences replaced. */
@@ -86,15 +86,49 @@ interface EditFileResult {
   /** SHA-256 of the file content after the edit. */
   hash: string;
 }
+/** One replacement inside a {@link MultiEditInput}. */
+export 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.
+ */
+export 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. */
+export 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 {
+export interface WriteFileInput {
   /** Workspace-relative path to write (created if absent). */
   path: string;
   /** Full file content to write atomically. */
   content: string;
 }
 /** Result of a write. */
-interface WriteFileResult {
+export interface WriteFileResult {
   /** Workspace-relative path that was written. */
   path: string;
   /** Number of bytes written. */
@@ -103,7 +137,7 @@ interface WriteFileResult {
   hash: string;
 }
 /** Options for the `exec()` direct method. */
-interface ExecOptions {
+export interface ExecOptions {
   /** Per-call wall-clock cap in ms; overrides the policy `shell.timeoutMs`. */
   timeoutMs?: number;
   /**
@@ -114,14 +148,108 @@ interface ExecOptions {
   signal?: AbortSignal;
 }
 /** Input to the `run_shell` tool / `exec()` direct method. */
-interface RunShellInput {
-  /** The command line to run; its leading basename is policy-checked. */
+export interface RunShellInput {
+  /** 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`).
+ */
+export type ShellJobStatus = "running" | "exited" | "killed" | "timed-out";
+/** A background command owned by the workspace. */
+export 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`. */
+export interface RunShellBackgroundResult extends ShellJobInfo {
+  /** Always `true` — tells this result apart from a foreground {@link RunShellResult}. */
+  background: true;
+}
+/** Options for `startShell()`. */
+export 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. */
+export 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()`. */
+export 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. */
+export 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. */
+export interface ShellKillInput {
+  /** The background command id to stop. */
+  id: string;
 }
 /** Result of a shell command — captured streams plus how it terminated. */
-interface RunShellResult {
+export interface RunShellResult {
   /** Process exit code (non-zero ⇒ the command failed, not the tool). */
   exitCode: number;
   /** Captured standard output (byte-capped per policy). */
@@ -144,12 +272,12 @@ interface RunShellResult {
  * the workspace's configured test command, optionally narrowed to a
  * pattern (a path/suite filter passed through to the runner).
  */
-interface RunTestsInput {
+export interface RunTestsInput {
   /** Optional path/name filter forwarded to the test runner. */
   pattern?: string;
 }
 /** Input to the `grep` tool / `grep()` direct method. */
-interface GrepInput {
+export interface GrepInput {
   /** Regular-expression pattern to search file contents for. */
   pattern: string;
   /** Glob narrowing which files are scanned (e.g. `"src/api/*.ts"`). */
@@ -158,7 +286,7 @@ interface GrepInput {
   ignoreCase?: boolean;
 }
 /** A single matched line within a file. */
-interface GrepMatch {
+export interface GrepMatch {
   /** Workspace-relative path of the file containing the match. */
   path: string;
   /** 1-based line number of the match. */
@@ -167,22 +295,91 @@ interface GrepMatch {
   text: string;
 }
 /** Result of a content search across the jailed file set. */
-interface GrepResult {
+export interface GrepResult {
   /** Every matching line found, in file/line order. */
   matches: GrepMatch[];
   /** Total number of matches (== `matches.length` unless capped). */
   total: number;
 }
+/** Input to the `list_dir` tool. */
+export 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()`. */
+export 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. */
+export type ListDirEntryType = "file" | "directory" | "symlink" | "other";
+/** One entry of a directory listing. */
+export 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. */
+export 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 {
+export interface GlobInput {
   /** Glob pattern resolved relative to `cwd` (e.g. `"src/api/*.ts"`). */
   pattern: string;
 }
 /** Result of a glob — the matched workspace-relative paths. */
-interface GlobResult {
+export interface GlobResult {
   /** Workspace-relative paths matching the pattern, sorted. */
   paths: string[];
 }
+/** State of one todo item. */
+export type WorkspaceTodoStatus = "pending" | "in_progress" | "completed";
+/** One item of the workspace's todo list. */
+export 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. */
+export 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. */
+export interface TodoWriteInput {
+  /** The complete list (at most 100 items). An empty list clears it. */
+  todos: WorkspaceTodoInput[];
+}
+/** The todo list plus a count per status. */
+export 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 };
 //# 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":";;;;;;;;;;;;YAYY;;iBAgBK;;EAEf;;EAEA;;EAEA;;;;;;;;;;;;;;iBAee;;EAEf;;EAEA;;;;;EAKA;;EAEA;;;;;;EAMA;;EAEA;;EAEA;;;;;;EAMA;;;;;;iBAOe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;iBAIe;;EAEf;;EAEA;;EAEA;;;iBAIe;;EAEf;;EAEA;;EAEA;;;;;;;;iBASe;;EAEf;;EAEA,OAAO;;EAEP;;;iBAIe;;EAEf;;EAEA;;EAEA;;EAEA;;;iBAIe;;EAEf;;EAEA;;;iBAIe;;EAEf;;EAEA;;EAEA;;;iBAIe;;EAEf;;;;;;EAMA,SAAS;;;iBAIM;;EAEf;;EAEA;;;;;EAKA;;;;;;;;;;;YAYU;;iBAGK;;EAEf;;EAEA;;EAEA,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;;iBAIe,iCAAiC;;EAEhD;;;iBAIe;;;;;;EAMf;;;iBAIe;;EAEf;;;;;EAKA;;;;;EAKA;;;iBAIe;;EAEf;;EAEA;;EAEA,SAAS;;;iBAIM,0BAA0B;;EAEzC;;EAEA;;;;;EAKA;;;;;EAKA;;EAEA;;;iBAIe;;EAEf;;;iBAIe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;EAMA;;;;;;;iBAQe;;EAEf;;;iBAIe;;EAEf;;EAEA;;EAEA;;;iBAIe;;EAEf;;EAEA;;EAEA;;;iBAIe;;EAEf,SAAS;;EAET;;;iBAIe;;EAEf;;EAEA;;EAEA;;;iBAIe;;EAEf;;EAEA;;;YAIU;;iBAGK;;EAEf;;EAEA,MAAM;;EAEN;;EAEA;;;iBAIe;;EAEf;;EAEA,SAAS;;EAET;;;iBAIe;;EAEf;;;iBAIe;;EAEf;;;YAIU;;iBAGK;;EAEf;;EAEA;;EAEA,QAAQ;;;iBAIO;;EAEf;;EAEA;;EAEA,QAAQ;;;iBAIO;;EAEf,OAAO;;;iBAIQ;;EAEf,OAAO;;EAEP,QAAQ,OAAO"}

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

@@ -1,3 +1,4 @@
+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
@@ -5,7 +6,7 @@
  * byte-cap `truncated` flag (capping is an ops-layer concern, not the
  * raw executor's).
  */
-interface WorkspaceBackendExecResult {
+export interface WorkspaceBackendExecResult {
   /** Process exit code. */
   exitCode: number;
   /** Captured standard output. */
@@ -27,7 +28,7 @@ interface WorkspaceBackendExecResult {
  * the effective environment and timeout from policy before handing them
  * down — the backend just runs what it is told.
  */
-interface WorkspaceBackendExecOptions {
+export interface WorkspaceBackendExecOptions {
   /** Working directory for the spawned process (already jail-resolved). */
   cwd?: string;
   /** Wall-clock cap in ms; on expiry the process is SIGKILLed. */
@@ -43,6 +44,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. */
+export type WorkspaceOutputStream = "stdout" | "stderr";
+/** Options for {@link WorkspaceBackend.start}. */
+export 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. */
+export 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). */
+export 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**
@@ -62,7 +109,7 @@ interface WorkspaceBackendExecOptions {
  * const out = await backend.readFile("/srv/acme-api/src/index.ts");
  * const { exitCode } = await backend.exec("npm test", { cwd: "/srv/acme-api" });
  */
-interface WorkspaceBackend {
+export interface WorkspaceBackend {
   /** Read a file's full UTF-8 content at an absolute path. */
   readFile(absPath: string): Promise<string>;
   /** Write full content to an absolute path (atomically where supported). */
@@ -79,7 +126,18 @@ 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 };
 //# 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":";;;;;;;;iBAQiB;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;;;;;;;iBAQe;;EAEf;;EAEA;;EAEA,MAAM;;;;;;;;;EASN,SAAS;;;;;;;;;EAST,cAAc;;;YAIJ;;iBAGK;;EAEf;;EAEA,MAAM;;EAEN,cAAc;;;;;EAKd,SAAS,QAAQ,uBAAuB;;;iBAIzB;;WAEN;;;;;WAKA,MAAM;IAAU;;;EAEzB;;;iBAIe;;EAEf;;EAEA;;;;;;;;;;;;;;;;;;;;iBAqBe;;EAEf,SAAS,kBAAkB;;EAE3B,UAAU,iBAAiB,kBAAkB;;EAE7C,OAAO,kBAAkB;;EAEzB,MAAM,kBAAkB;;EAExB,OAAO,kBAAkB;;EAEzB,KAAK,iBAAiB;;EAEtB,SAAS,kBAAkB;;EAE3B,KAAK,iBAAiB,OAAO,8BAA8B,QAAQ;;;;;;EAMnE,MAAM,kBAAkB,QAAQ;;;;;;EAMhC,OAAO,iBAAiB,MAAM,+BAA+B"}

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

@@ -1,5 +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
 /**
  * The **policy-enforced** operation layer that sits between the dumb
@@ -20,7 +19,7 @@ import { EditFileInput, EditFileResult, ExecOptions, GrepResult, ReadFileResult,
  * const { content, hash } = await ops.readFile("src/index.ts");
  * await ops.editFile({ path: "src/index.ts", oldString: "x", newString: "y", expectHash: hash });
  */
-interface WorkspaceOps {
+export interface WorkspaceOps {
   /**
    * Read a jailed file, returning a numbered line window, the full file's
    * hash and the window metadata. `offset`/`limit` select a 1-based line
@@ -43,12 +42,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,7 +84,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 };
 //# sourceMappingURL=workspace-ops.contract.d.mts.map

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":";;;;;;;;;;;;;;;;;;;;;iBAoCiB;;;;;;;EAOf,SAAS,cAAc;IAAS;IAAiB;MAAmB,QAAQ;;EAG5E,UAAU,cAAc,kBAAkB;IAAU;IAAc;;;;;;;EAOlE,SAAS,OAAO,gBAAgB,QAAQ;;;;;;;EAQxC,UAAU,OAAO,iBAAiB,QAAQ;;;;;;;EAQ1C,KAAK,iBAAiB,OAAO,cAAc,QAAQ;;;;;EAMnD,WAAW,iBAAiB,OAAO,oBAAoB,QAAQ;;EAG/D,YAAY,YAAY,OAAO,qBAAqB,QAAQ;;EAG5D,UAAU,aAAa,QAAQ;;EAG/B,cAAc;;;;;EAMd,QAAQ,eAAe,OAAO,iBAAiB,QAAQ;;EAGvD,KAAK,iBAAiB;IAAS;IAAe;MAAyB,QAAQ;;EAG/E,KAAK,kBAAkB;;EAGvB,OAAO,eAAe;;EAGtB,MAAM,eAAe;;EAGrB,OAAO,eAAe;;;;;;EAOtB,WAAW"}