@warlock.js/ai-workspace 5.29.0 → 5.31.0

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

@@ -1,6 +1,6 @@
-//#region ../ai-workspace/src/contracts/tool-io.type.d.ts
+//#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. */
@@ -23,20 +23,42 @@ interface ReadFileInput {
 /**
  * Result of a read — the requested line window plus the metadata an
  * agent needs to read-before-edit (the `hash` feeds `editFile`'s
- * `expectHash` stale-guard).
+ * `expectHash` stale-guard). The `read_file` tool and the `readFile()`
+ * direct method return the same shape for the same arguments.
+ *
+ * `content` is `cat -n` numbered and is bounded by the policy's
+ * `read.maxBytes`, measured in UTF-8 bytes of `content` itself (line-number
+ * prefixes and newlines included). When the cap cuts the window, the last
+ * returned line may be partial — clipped on a character boundary, never
+ * mid-character — and `bytesCapped` is `true`.
  */
 interface ReadFileResult {
-  /** The returned file content for the requested window. */
+  /** The returned, line-numbered file content for the requested window. */
   content: string;
-  /** 1-based first line included in `content`. */
+  /** 1-based first line requested. */
   startLine: number;
-  /** 1-based last line included in `content`. */
+  /**
+   * 1-based last line included in `content` (possibly partially, when
+   * `bytesCapped`). Below `startLine` when the window is empty.
+   */
   endLine: number;
   /** Total line count of the underlying file. */
   totalLines: number;
-  /** True when the window stopped short of the file end (policy cap or `limit`). */
+  /**
+   * True when anything after `content` was withheld: lines past `endLine`
+   * (line `limit`, policy default window or byte cap) or the tail of
+   * `endLine` itself (byte cap).
+   */
   truncated: boolean;
-  /** SHA-256 of the full file content at read time (stale-edit guard). */
+  /** True when `read.maxBytes` cut the window short. */
+  bytesCapped: boolean;
+  /** UTF-8 byte length of the full file. */
+  totalBytes: number;
+  /**
+   * SHA-256 of the **full** file content at read time — not of the returned
+   * window — so it stays valid as an `editFile` `expectHash` whatever window
+   * or byte cap was applied.
+   */
   hash: string;
 }
 /**
@@ -64,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). */
@@ -80,12 +136,117 @@ interface WriteFileResult {
   /** SHA-256 of the written content. */
   hash: string;
 }
+/** Options for the `exec()` direct method. */
+interface ExecOptions {
+  /** Per-call wall-clock cap in ms; overrides the policy `shell.timeoutMs`. */
+  timeoutMs?: number;
+  /**
+   * Cancels this one command. Already aborted: the command is not started.
+   * Aborted mid-run: its process tree is killed. Either way the result has
+   * `cancelled: true`. The tools pass the agent run's signal here.
+   */
+  signal?: AbortSignal;
+}
 /** 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 {
@@ -99,6 +260,12 @@ interface RunShellResult {
   truncated: boolean;
   /** True when the command was SIGKILLed for exceeding its timeout. */
   timedOut: boolean;
+  /**
+   * True when the invocation's `signal` aborted: before start (nothing ran)
+   * or mid-run (the process tree was killed). Never true together with
+   * `timedOut`.
+   */
+  cancelled: boolean;
 }
 /**
  * Input to the `run_tests` tool. Convenience over `run_shell` that runs
@@ -134,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"`). */
@@ -144,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, 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":["../../../../../../../ai-workspace/src/contracts/tool-io.type.ts"],"mappings":";;AAYA;;;;AAA6B;AAU7B;;;;;KAVY,iBAAA;;UAUK,aAAA;EAMV;EAJL,IAAA;EAY6B;EAV7B,SAAA;EAU6B;EAR7B,KAAA;AAAA;;;;;;UAQe,cAAA;EAmBA;EAjBf,OAAA;;EAEA,SAAA;EAiBA;EAfA,OAAA;EAmBA;EAjBA,UAAA;EAqBA;EAnBA,SAAA;EAmBU;EAjBV,IAAA;AAAA;;;;;UAOe,aAAA;EAoBX;EAlBJ,IAAA;EAsBe;EApBf,SAAA;;EAEA,SAAA;EAsBO;EApBP,UAAA;EAwB8B;EAtB9B,UAAA;AAAA;;UAIe,cAAA;EAwBf;EAtBA,IAAA;EAsBI;EApBJ,YAAA;EAwB4B;EAtB5B,IAAA;AAAA;AA0BS;AAAA,UAtBM,cAAA;EA0Bc;EAxB7B,IAAA;EAwB6B;EAtB7B,OAAO;AAAA;;UAIQ,eAAA;EA4Bf;EA1BA,IAAA;EA0BQ;EAxBR,YAAA;EAgC4B;EA9B5B,IAAA;AAAA;AAgCO;AAAA,UA5BQ,aAAA;EAgCS;EA9BxB,OAAA;EA8BwB;EA5BxB,SAAS;AAAA;;UAIM,cAAA;EA8BL;EA5BV,QAAA;EAgCwB;EA9BxB,MAAA;EA8BwB;EA5BxB,MAAA;EAgCA;EA9BA,SAAA;EAgCI;EA9BJ,QAAA;AAAA;;;;;;UAQe,aAAA;EA8BV;EA5BL,OAAO;AAAA;;UAIQ,SAAA;EA8BR;EA5BP,OAAA;EAgCe;EA9Bf,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,4 +1,6 @@
-//#region ../ai-workspace/src/contracts/workspace-backend.contract.d.ts
+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
  * policy-enforced ops layer surfaces as `RunShellResult`, minus the
@@ -14,6 +16,13 @@ interface WorkspaceBackendExecResult {
   stderr: string;
   /** True when the command was killed for exceeding its timeout. */
   timedOut: boolean;
+  /**
+   * True when the invocation's `signal` aborted — either before the
+   * command started (nothing was spawned) or while it ran (the process
+   * tree was killed). Mutually exclusive with `timedOut`. Optional so
+   * existing custom backends keep compiling; absent reads as `false`.
+   */
+  cancelled?: boolean;
 }
 /**
  * Options threaded into a backend `exec` call. The ops layer resolves
@@ -27,6 +36,61 @@ interface WorkspaceBackendExecOptions {
   timeoutMs?: number;
   /** Exact environment for the spawned process (NOT merged with process.env). */
   env?: Record<string, string>;
+  /**
+   * Per-invocation cancellation. A backend must not start the command when
+   * the signal is already aborted, must tear down the whole process tree
+   * when it aborts mid-run, must remove its abort listener once the command
+   * settles, and reports either case as `cancelled: true` (never a
+   * rejection). The signal belongs to ONE call — never cache it on the
+   * 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**
@@ -63,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":["../../../../../../../ai-workspace/src/contracts/workspace-backend.contract.ts"],"mappings":";;AAMA;;;;;UAAiB,0BAAA;EAMf;EAJA,QAAA;EAMQ;EAJR,MAAA;EAYe;EAVf,MAAA;;EAEA,QAAA;AAAA;;;;;AAcY;UANG,2BAAA;EA2BgB;EAzB/B,GAAA;EA2B2B;EAzB3B,SAAA;EA6ByB;EA3BzB,GAAA,GAAM,MAAM;AAAA;;;;;;;;;;;;;;;;;;;UAqBG,gBAAA;EAQS;EANxB,QAAA,CAAS,OAAA,WAAkB,OAAA;EAQpB;EANP,SAAA,CAAU,OAAA,UAAiB,OAAA,WAAkB,OAAA;EAQ7C;EANA,MAAA,CAAO,OAAA,WAAkB,OAAA;EAMH;EAJtB,KAAA,CAAM,OAAA,WAAkB,OAAA;EAMf;EAJT,MAAA,CAAO,OAAA,WAAkB,OAAA;EAMzB;EAJA,IAAA,CAAK,MAAA,WAAiB,OAAA;EAMb;EAJT,QAAA,CAAS,OAAA,WAAkB,OAAA;EAKxB;EAHH,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,6 +1,6 @@
-import { EditFileInput, EditFileResult, GrepResult, 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 ../ai-workspace/src/contracts/workspace-ops.contract.d.ts
+//#region ../../packages/ai-workspace/src/contracts/workspace-ops.contract.d.ts
 /**
  * The **policy-enforced** operation layer that sits between the dumb
  * {@link WorkspaceBackend} and the two public callers — the agent-facing
@@ -22,18 +22,15 @@ import { EditFileInput, EditFileResult, GrepResult, RunShellResult } from "./too
  */
 interface WorkspaceOps {
   /**
-   * Read a jailed file, returning its content, content hash, and total
-   * line count. `offset`/`limit` select a 1-based line window; the
-   * policy `read` caps still apply.
+   * 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
+   * window; `read.maxBytes` bounds the UTF-8 bytes of the returned
+   * `content` (see {@link ReadFileResult}).
    */
   readFile(path: string, opts?: {
     offset?: number;
     limit?: number;
-  }): Promise<{
-    content: string;
-    hash: string;
-    totalLines: number;
-  }>;
+  }): Promise<ReadFileResult>;
   /** Atomically write full content to a jailed path, returning size + hash. */
   writeFile(path: string, content: string): Promise<{
     hash: string;
@@ -46,13 +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,
-   * timeout, and output byte cap applied.
+   * 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.
    */
-  exec(command: string, opts?: {
-    timeoutMs?: number;
-  }): Promise<RunShellResult>;
+  listDir(path?: string, opts?: ListDirOptions): Promise<ListDirResult>;
   /** Search jailed file contents for a regex pattern. */
   grep(pattern: string, opts?: {
     glob?: string;
@@ -66,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":["../../../../../../../ai-workspace/src/contracts/workspace-ops.contract.ts"],"mappings":";;;;;AA0BA;;;;;;;;;;;;;;;;;UAAiB,YAAA;EAMf;;;;;EAAA,QAAA,CACE,IAAA,UACA,IAAA;IAAS,MAAA;IAAiB,KAAA;EAAA,IACzB,OAAA;IAAU,OAAA;IAAiB,IAAA;IAAc,UAAA;EAAA;EAM/B;EAHb,SAAA,CACE,IAAA,UACA,OAAA,WACC,OAAA;IAAU,IAAA;IAAc,YAAA;EAAA;EAOK;;;;;EAAhC,QAAA,CAAS,KAAA,EAAO,aAAA,GAAgB,OAAA,CAAQ,cAAA;EAUrC;;;;;EAHH,IAAA,CACE,OAAA,UACA,IAAA;IAAS,SAAA;EAAA,IACR,OAAA,CAAQ,cAAA;EAMA;EAHX,IAAA,CACE,OAAA,UACA,IAAA;IAAS,IAAA;IAAe,UAAA;EAAA,IACvB,OAAA,CAAQ,UAAA;EAMJ;EAHP,IAAA,CAAK,OAAA,WAAkB,OAAA;EAMvB;EAHA,MAAA,CAAO,IAAA,WAAe,OAAA;EAGD;EAArB,KAAA,CAAM,IAAA,WAAe,OAAA;EAGd;EAAP,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"}