@warlock.js/ai-workspace 4.5.0

package/esm/backends/mock.mjs

@@ -0,0 +1,167 @@
+//#region ../@warlock.js/ai-workspace/src/backends/mock.ts
+/**
+* Normalize an absolute path to a stable in-memory key: forward slashes,
+* collapsed duplicate separators, and resolved `.` / `..` segments. There
+* are no symlinks in memory, so this is a pure lexical canonicalization —
+* exactly what the backend's `realpath` promises.
+*/
+function canonicalize(absPath) {
+	const unified = absPath.replace(/\\/g, "/");
+	const driveMatch = unified.match(/^([a-zA-Z]:)?\/?/);
+	const prefix = driveMatch ? driveMatch[0] : "";
+	const rest = unified.slice(prefix.length);
+	const resolved = [];
+	for (const segment of rest.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			resolved.pop();
+			continue;
+		}
+		resolved.push(segment);
+	}
+	const joined = resolved.join("/");
+	const normalizedPrefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
+	return joined.length > 0 ? `${normalizedPrefix}${joined}` : normalizedPrefix;
+}
+/** All ancestor directory keys of a canonical path, root-first. */
+function ancestorsOf(canonicalPath) {
+	const lastSlash = canonicalPath.lastIndexOf("/");
+	if (lastSlash <= 0) return [];
+	const parent = canonicalPath.slice(0, lastSlash);
+	const result = ancestorsOf(parent);
+	result.push(parent);
+	return result;
+}
+/**
+* The in-memory executor behind {@link createMockBackend}. Holds the file
+* tree in a `Map`, the directory set in a `Set`, and the scripted command
+* table in a second `Map` — no disk, no child processes, fully
+* deterministic. Construct it via the factory, never directly.
+*/
+var MockBackend = class {
+	constructor(seed) {
+		this.files = /* @__PURE__ */ new Map();
+		this.directories = /* @__PURE__ */ new Set();
+		this.commands = /* @__PURE__ */ new Map();
+		for (const [path, content] of Object.entries(seed?.files ?? {})) {
+			const canonical = canonicalize(path);
+			this.files.set(canonical, content);
+			this.registerAncestorDirectories(canonical);
+		}
+		for (const [command, result] of Object.entries(seed?.commands ?? {})) this.commands.set(command, result);
+	}
+	/** Record every ancestor directory of a path as existing. */
+	registerAncestorDirectories(canonicalPath) {
+		for (const ancestor of ancestorsOf(canonicalPath)) this.directories.add(ancestor);
+	}
+	async readFile(absPath) {
+		const canonical = canonicalize(absPath);
+		const content = this.files.get(canonical);
+		if (content === void 0) throw new Error(`Mock backend: no such file: ${canonical}`);
+		return content;
+	}
+	async writeFile(absPath, content) {
+		const canonical = canonicalize(absPath);
+		this.files.set(canonical, content);
+		this.registerAncestorDirectories(canonical);
+	}
+	async exists(absPath) {
+		const canonical = canonicalize(absPath);
+		return this.files.has(canonical) || this.directories.has(canonical);
+	}
+	async mkdir(absPath) {
+		const canonical = canonicalize(absPath);
+		this.directories.add(canonical);
+		this.registerAncestorDirectories(canonical);
+	}
+	async remove(absPath) {
+		const canonical = canonicalize(absPath);
+		const prefix = `${canonical}/`;
+		for (const file of [...this.files.keys()]) if (file === canonical || file.startsWith(prefix)) this.files.delete(file);
+		for (const directory of [...this.directories]) if (directory === canonical || directory.startsWith(prefix)) this.directories.delete(directory);
+	}
+	async list(absDir) {
+		const canonical = canonicalize(absDir);
+		const prefix = canonical === "/" ? "/" : `${canonical}/`;
+		const children = /* @__PURE__ */ new Set();
+		const collect = (key) => {
+			if (!key.startsWith(prefix) || key === canonical) return;
+			const remainder = key.slice(prefix.length);
+			const nextSlash = remainder.indexOf("/");
+			const childName = nextSlash === -1 ? remainder : remainder.slice(0, nextSlash);
+			if (childName.length > 0) children.add(`${prefix}${childName}`);
+		};
+		for (const file of this.files.keys()) collect(file);
+		for (const directory of this.directories) collect(directory);
+		return [...children].sort();
+	}
+	async realpath(absPath) {
+		return canonicalize(absPath);
+	}
+	async exec(command, _opts) {
+		const scripted = this.commands.get(command);
+		return {
+			exitCode: scripted?.exitCode ?? 0,
+			stdout: scripted?.stdout ?? "",
+			stderr: scripted?.stderr ?? "",
+			timedOut: scripted?.timedOut ?? false
+		};
+	}
+};
+/**
+* Create an in-memory {@link WorkspaceBackend} for fast, disk-free tests.
+*
+* Every IO method operates on a `Map` of `absolutePath -> content` (with a
+* companion directory set), so reads, writes, existence checks, `mkdir`,
+* recursive `remove`, `list`, and `realpath` all run synchronously in
+* memory with no filesystem access. `exec` is **scripted**: a registered
+* `command -> result` table is consulted by exact command line, and any
+* unregistered command resolves to a successful `0`-exit no-op with empty
+* output.
+*
+* `realpath` is a pure lexical canonicalization (forward slashes,
+* collapsed separators, resolved `.`/`..`) — there are no symlinks in
+* memory — which is exactly what the jail resolver expects.
+*
+* The single positional `seed` accepts either the shorthand
+* `Record<string, string>` of file contents (matching the design's
+* `ai.workspace.mock(seed)` signature) or the richer {@link MockBackendSeed}
+* with both `files` and scripted `commands`.
+*
+* @example
+* // Shorthand: seed files only.
+* const backend = createMockBackend({ "/srv/app/src/index.ts": "export const x = 1;" });
+* await backend.readFile("/srv/app/src/index.ts"); // "export const x = 1;"
+*
+* @example
+* // Full seed: files plus a scripted command.
+* const backend = createMockBackend({
+*   files: { "/srv/app/package.json": "{}" },
+*   commands: { "npm test": { exitCode: 1, stderr: "1 failing" } },
+* });
+* await backend.exec("npm test");   // { exitCode: 1, stderr: "1 failing", ... }
+* await backend.exec("echo hi");    // { exitCode: 0, stdout: "", ... } (no-op)
+*/
+function createMockBackend(seed) {
+	return new MockBackend(normalizeSeed(seed));
+}
+/** Coerce the dual-shaped `seed` argument into a {@link MockBackendSeed}. */
+function normalizeSeed(seed) {
+	if (seed === void 0) return;
+	if (isMockBackendSeed(seed)) return seed;
+	return { files: seed };
+}
+/**
+* Whether `seed` is the structured {@link MockBackendSeed} (has a `files`
+* or `commands` key) rather than the flat `path -> content` shorthand. A
+* plain shorthand map whose only key happens to be named `files` is
+* treated as structured — callers wanting that literal path should use the
+* explicit `{ files: { files: "..." } }` form.
+*/
+function isMockBackendSeed(seed) {
+	return typeof seed.files === "object" || typeof seed.commands === "object";
+}
+
+//#endregion
+export { createMockBackend };
+//# sourceMappingURL=mock.mjs.map

package/esm/backends/mock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/backends/mock.ts"],"sourcesContent":["import type {\n  WorkspaceBackend,\n  WorkspaceBackendExecOptions,\n  WorkspaceBackendExecResult,\n} from \"../contracts/workspace-backend.contract\";\n\n/**\n * A scripted outcome for the mock backend's `exec`. Mirrors\n * {@link WorkspaceBackendExecResult} but every field is optional so a\n * registration can specify only what it cares about — the rest fall back\n * to a successful, empty-output, non-timed-out run.\n */\nexport type MockExecResult = Partial<WorkspaceBackendExecResult>;\n\n/**\n * The two seedable inputs of a mock backend:\n *\n * - `files` — initial file tree as `absolutePath -> content`. Parent\n *   directories of each seeded file are implicitly created.\n * - `commands` — scripted `exec` outcomes keyed on the **exact** command\n *   line. Any command not registered here resolves to a `0`-exit no-op.\n */\nexport interface MockBackendSeed {\n  /** Initial file contents, keyed by absolute path. */\n  files?: Record<string, string>;\n  /** Scripted `exec` results, keyed by exact command line. */\n  commands?: Record<string, MockExecResult>;\n}\n\n/**\n * Normalize an absolute path to a stable in-memory key: forward slashes,\n * collapsed duplicate separators, and resolved `.` / `..` segments. There\n * are no symlinks in memory, so this is a pure lexical canonicalization —\n * exactly what the backend's `realpath` promises.\n */\nfunction canonicalize(absPath: string): string {\n  const unified = absPath.replace(/\\\\/g, \"/\");\n  // Preserve a leading slash (POSIX root) or a `C:`-style Windows drive\n  // prefix; everything else is a normal segment.\n  const driveMatch = unified.match(/^([a-zA-Z]:)?\\/?/);\n  const prefix = driveMatch ? driveMatch[0] : \"\";\n  const rest = unified.slice(prefix.length);\n\n  const resolved: string[] = [];\n\n  for (const segment of rest.split(\"/\")) {\n    if (segment === \"\" || segment === \".\") {\n      continue;\n    }\n\n    if (segment === \"..\") {\n      resolved.pop();\n\n      continue;\n    }\n\n    resolved.push(segment);\n  }\n\n  const joined = resolved.join(\"/\");\n\n  // A trailing slash on the prefix means it was absolute; keep it so the\n  // result stays absolute even when the body is empty (the root itself).\n  const normalizedPrefix = prefix.endsWith(\"/\") ? prefix : `${prefix}/`;\n\n  return joined.length > 0 ? `${normalizedPrefix}${joined}` : normalizedPrefix;\n}\n\n/** All ancestor directory keys of a canonical path, root-first. */\nfunction ancestorsOf(canonicalPath: string): string[] {\n  const lastSlash = canonicalPath.lastIndexOf(\"/\");\n\n  if (lastSlash <= 0) {\n    return [];\n  }\n\n  const parent = canonicalPath.slice(0, lastSlash);\n  const result = ancestorsOf(parent);\n\n  result.push(parent);\n\n  return result;\n}\n\n/**\n * The in-memory executor behind {@link createMockBackend}. Holds the file\n * tree in a `Map`, the directory set in a `Set`, and the scripted command\n * table in a second `Map` — no disk, no child processes, fully\n * deterministic. Construct it via the factory, never directly.\n */\nclass MockBackend implements WorkspaceBackend {\n  /** Canonical file path -> content. */\n  private readonly files = new Map<string, string>();\n\n  /** Canonical directory paths that exist (including implicit parents). */\n  private readonly directories = new Set<string>();\n\n  /** Exact command line -> scripted outcome. */\n  private readonly commands = new Map<string, MockExecResult>();\n\n  public constructor(seed?: MockBackendSeed) {\n    for (const [path, content] of Object.entries(seed?.files ?? {})) {\n      const canonical = canonicalize(path);\n\n      this.files.set(canonical, content);\n      this.registerAncestorDirectories(canonical);\n    }\n\n    for (const [command, result] of Object.entries(seed?.commands ?? {})) {\n      this.commands.set(command, result);\n    }\n  }\n\n  /** Record every ancestor directory of a path as existing. */\n  private registerAncestorDirectories(canonicalPath: string): void {\n    for (const ancestor of ancestorsOf(canonicalPath)) {\n      this.directories.add(ancestor);\n    }\n  }\n\n  public async readFile(absPath: string): Promise<string> {\n    const canonical = canonicalize(absPath);\n    const content = this.files.get(canonical);\n\n    if (content === undefined) {\n      throw new Error(`Mock backend: no such file: ${canonical}`);\n    }\n\n    return content;\n  }\n\n  public async writeFile(absPath: string, content: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n\n    this.files.set(canonical, content);\n    this.registerAncestorDirectories(canonical);\n  }\n\n  public async exists(absPath: string): Promise<boolean> {\n    const canonical = canonicalize(absPath);\n\n    return this.files.has(canonical) || this.directories.has(canonical);\n  }\n\n  public async mkdir(absPath: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n\n    this.directories.add(canonical);\n    this.registerAncestorDirectories(canonical);\n  }\n\n  public async remove(absPath: string): Promise<void> {\n    const canonical = canonicalize(absPath);\n    const prefix = `${canonical}/`;\n\n    // Drop the entry itself and any descendant files/directories — a\n    // recursive tree removal, matching the contract's \"file or directory\n    // tree\" wording.\n    for (const file of [...this.files.keys()]) {\n      if (file === canonical || file.startsWith(prefix)) {\n        this.files.delete(file);\n      }\n    }\n\n    for (const directory of [...this.directories]) {\n      if (directory === canonical || directory.startsWith(prefix)) {\n        this.directories.delete(directory);\n      }\n    }\n  }\n\n  public async list(absDir: string): Promise<string[]> {\n    const canonical = canonicalize(absDir);\n    const prefix = canonical === \"/\" ? \"/\" : `${canonical}/`;\n    const children = new Set<string>();\n\n    const collect = (key: string): void => {\n      if (!key.startsWith(prefix) || key === canonical) {\n        return;\n      }\n\n      const remainder = key.slice(prefix.length);\n      const nextSlash = remainder.indexOf(\"/\");\n      const childName =\n        nextSlash === -1 ? remainder : remainder.slice(0, nextSlash);\n\n      if (childName.length > 0) {\n        children.add(`${prefix}${childName}`);\n      }\n    };\n\n    for (const file of this.files.keys()) {\n      collect(file);\n    }\n\n    for (const directory of this.directories) {\n      collect(directory);\n    }\n\n    return [...children].sort();\n  }\n\n  public async realpath(absPath: string): Promise<string> {\n    return canonicalize(absPath);\n  }\n\n  public async exec(\n    command: string,\n    _opts?: WorkspaceBackendExecOptions,\n  ): Promise<WorkspaceBackendExecResult> {\n    const scripted = this.commands.get(command);\n\n    return {\n      exitCode: scripted?.exitCode ?? 0,\n      stdout: scripted?.stdout ?? \"\",\n      stderr: scripted?.stderr ?? \"\",\n      timedOut: scripted?.timedOut ?? false,\n    };\n  }\n}\n\n/**\n * Create an in-memory {@link WorkspaceBackend} for fast, disk-free tests.\n *\n * Every IO method operates on a `Map` of `absolutePath -> content` (with a\n * companion directory set), so reads, writes, existence checks, `mkdir`,\n * recursive `remove`, `list`, and `realpath` all run synchronously in\n * memory with no filesystem access. `exec` is **scripted**: a registered\n * `command -> result` table is consulted by exact command line, and any\n * unregistered command resolves to a successful `0`-exit no-op with empty\n * output.\n *\n * `realpath` is a pure lexical canonicalization (forward slashes,\n * collapsed separators, resolved `.`/`..`) — there are no symlinks in\n * memory — which is exactly what the jail resolver expects.\n *\n * The single positional `seed` accepts either the shorthand\n * `Record<string, string>` of file contents (matching the design's\n * `ai.workspace.mock(seed)` signature) or the richer {@link MockBackendSeed}\n * with both `files` and scripted `commands`.\n *\n * @example\n * // Shorthand: seed files only.\n * const backend = createMockBackend({ \"/srv/app/src/index.ts\": \"export const x = 1;\" });\n * await backend.readFile(\"/srv/app/src/index.ts\"); // \"export const x = 1;\"\n *\n * @example\n * // Full seed: files plus a scripted command.\n * const backend = createMockBackend({\n *   files: { \"/srv/app/package.json\": \"{}\" },\n *   commands: { \"npm test\": { exitCode: 1, stderr: \"1 failing\" } },\n * });\n * await backend.exec(\"npm test\");   // { exitCode: 1, stderr: \"1 failing\", ... }\n * await backend.exec(\"echo hi\");    // { exitCode: 0, stdout: \"\", ... } (no-op)\n */\nexport function createMockBackend(\n  seed?: Record<string, string> | MockBackendSeed,\n): WorkspaceBackend {\n  return new MockBackend(normalizeSeed(seed));\n}\n\n/** Coerce the dual-shaped `seed` argument into a {@link MockBackendSeed}. */\nfunction normalizeSeed(\n  seed?: Record<string, string> | MockBackendSeed,\n): MockBackendSeed | undefined {\n  if (seed === undefined) {\n    return undefined;\n  }\n\n  if (isMockBackendSeed(seed)) {\n    return seed;\n  }\n\n  return { files: seed };\n}\n\n/**\n * Whether `seed` is the structured {@link MockBackendSeed} (has a `files`\n * or `commands` key) rather than the flat `path -> content` shorthand. A\n * plain shorthand map whose only key happens to be named `files` is\n * treated as structured — callers wanting that literal path should use the\n * explicit `{ files: { files: \"...\" } }` form.\n */\nfunction isMockBackendSeed(\n  seed: Record<string, string> | MockBackendSeed,\n): seed is MockBackendSeed {\n  return (\n    typeof (seed as MockBackendSeed).files === \"object\" ||\n    typeof (seed as MockBackendSeed).commands === \"object\"\n  );\n}\n"],"mappings":"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"}

package/esm/contracts/index.d.mts

@@ -0,0 +1,5 @@
+import { EditFileInput, EditFileResult, GlobInput, GlobResult, GrepInput, GrepMatch, GrepResult, ReadFileInput, ReadFileResult, RunShellInput, RunShellResult, RunTestsInput, WorkspaceToolName, WriteFileInput, WriteFileResult } from "./tool-io.type.mjs";
+import { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult } from "./workspace-backend.contract.mjs";
+import { WorkspaceOps } from "./workspace-ops.contract.mjs";
+import { WorkspaceBackendType, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellPolicy } from "./workspace-policy.type.mjs";
+import { Workspace, WorkspaceTools } from "./workspace.contract.mjs";

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

@@ -0,0 +1,149 @@
+//#region ../@warlock.js/ai-workspace/src/contracts/tool-io.type.d.ts
+/**
+ * Input/output shapes for the seven 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
+ * engine resolves them against `cwd` and rejects escapes.
+ */
+/**
+ * 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";
+/** Input to the `read_file` tool / `readFile()` direct method. */
+interface ReadFileInput {
+  /** Workspace-relative path to read. */
+  path: string;
+  /** 1-based line to start from. Omit to start at the top. */
+  startLine?: number;
+  /** Max lines to return from `startLine`. Omit for the policy default. */
+  limit?: number;
+}
+/**
+ * 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).
+ */
+interface ReadFileResult {
+  /** The returned file content for the requested window. */
+  content: string;
+  /** 1-based first line included in `content`. */
+  startLine: number;
+  /** 1-based last line included in `content`. */
+  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`). */
+  truncated: boolean;
+  /** SHA-256 of the full file content at read time (stale-edit guard). */
+  hash: string;
+}
+/**
+ * Input to the `edit_file` tool / `editFile()` direct method — an
+ * exact-string replacement with a read-before-edit stale guard.
+ */
+interface EditFileInput {
+  /** Workspace-relative path to edit. */
+  path: string;
+  /** 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;
+  /** Expected current SHA-256; a mismatch rejects the edit as stale. */
+  expectHash?: string;
+}
+/** Result of a successful edit. */
+interface EditFileResult {
+  /** Workspace-relative path that was edited. */
+  path: string;
+  /** Number of occurrences replaced. */
+  replacements: number;
+  /** SHA-256 of the file content after the edit. */
+  hash: string;
+}
+/** Input to the `write_file` tool / `writeFile()` direct method. */
+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 {
+  /** Workspace-relative path that was written. */
+  path: string;
+  /** Number of bytes written. */
+  bytesWritten: number;
+  /** SHA-256 of the written content. */
+  hash: string;
+}
+/** Input to the `run_shell` tool / `exec()` direct method. */
+interface RunShellInput {
+  /** The command line to run; its leading basename is policy-checked. */
+  command: string;
+  /** Per-call wall-clock cap (overrides the policy default if lower). */
+  timeoutMs?: number;
+}
+/** Result of a shell command — captured streams plus how it terminated. */
+interface RunShellResult {
+  /** Process exit code (non-zero ⇒ the command failed, not the tool). */
+  exitCode: number;
+  /** Captured standard output (byte-capped per policy). */
+  stdout: string;
+  /** Captured standard error (byte-capped per policy). */
+  stderr: string;
+  /** True when stdout/stderr was clipped at the policy byte cap. */
+  truncated: boolean;
+  /** True when the command was SIGKILLed for exceeding its timeout. */
+  timedOut: boolean;
+}
+/**
+ * Input to the `run_tests` tool. Convenience over `run_shell` that runs
+ * the workspace's configured test command, optionally narrowed to a
+ * pattern (a path/suite filter passed through to the runner).
+ */
+interface RunTestsInput {
+  /** Optional path/name filter forwarded to the test runner. */
+  pattern?: string;
+}
+/** Input to the `grep` tool / `grep()` direct method. */
+interface GrepInput {
+  /** Regular-expression pattern to search file contents for. */
+  pattern: string;
+  /** Glob narrowing which files are scanned (e.g. `"src/api/*.ts"`). */
+  glob?: string;
+  /** Case-insensitive matching when true. */
+  ignoreCase?: boolean;
+}
+/** A single matched line within a file. */
+interface GrepMatch {
+  /** Workspace-relative path of the file containing the match. */
+  path: string;
+  /** 1-based line number of the match. */
+  line: number;
+  /** Full text of the matching line. */
+  text: string;
+}
+/** Result of a content search across the jailed file set. */
+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 `glob` tool / `glob()` direct method. */
+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 {
+  /** Workspace-relative paths matching the pattern, sorted. */
+  paths: string[];
+}
+//#endregion
+export { EditFileInput, EditFileResult, 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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-io.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/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"}

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

@@ -0,0 +1,69 @@
+//#region ../@warlock.js/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
+ * byte-cap `truncated` flag (capping is an ops-layer concern, not the
+ * raw executor's).
+ */
+interface WorkspaceBackendExecResult {
+  /** Process exit code. */
+  exitCode: number;
+  /** Captured standard output. */
+  stdout: string;
+  /** Captured standard error. */
+  stderr: string;
+  /** True when the command was killed for exceeding its timeout. */
+  timedOut: boolean;
+}
+/**
+ * Options threaded into a backend `exec` call. The ops layer resolves
+ * the effective environment and timeout from policy before handing them
+ * down — the backend just runs what it is told.
+ */
+interface WorkspaceBackendExecOptions {
+  /** Working directory for the spawned process (already jail-resolved). */
+  cwd?: string;
+  /** Wall-clock cap in ms; on expiry the process is SIGKILLed. */
+  timeoutMs?: number;
+  /** Exact environment for the spawned process (NOT merged with process.env). */
+  env?: Record<string, string>;
+}
+/**
+ * The swappable executor a workspace runs on — the thin, **policy-agnostic**
+ * IO seam the ops layer calls. A backend takes **already-resolved absolute
+ * paths** and performs the side effect; it does NOT know about `cwd` jails,
+ * allow/deny lists, hashes, or line windows — that enforcement lives one
+ * layer up in {@link WorkspaceOps}.
+ *
+ * Implementations:
+ * - **local** — `@warlock.js/fs` for IO + `node:child_process` for `exec`.
+ * - **mock** — an in-memory `Map` + scripted `exec`, for hermetic tests.
+ *
+ * Keeping the backend dumb is what lets the same ops/policy layer run
+ * unchanged over a real disk, an in-memory fake, or (later) a container.
+ *
+ * @example
+ * const out = await backend.readFile("/srv/acme-api/src/index.ts");
+ * const { exitCode } = await backend.exec("npm test", { cwd: "/srv/acme-api" });
+ */
+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). */
+  writeFile(absPath: string, content: string): Promise<void>;
+  /** Whether anything exists at an absolute path (file or directory). */
+  exists(absPath: string): Promise<boolean>;
+  /** Create a directory (and parents) at an absolute path; idempotent. */
+  mkdir(absPath: string): Promise<void>;
+  /** Remove a file or directory tree at an absolute path. */
+  remove(absPath: string): Promise<void>;
+  /** List immediate children of an absolute directory as absolute paths. */
+  list(absDir: string): Promise<string[]>;
+  /** Resolve symlinks/`..` to a canonical absolute path (jail enforcement). */
+  realpath(absPath: string): Promise<string>;
+  /** Run a command and capture its outcome. */
+  exec(command: string, opts?: WorkspaceBackendExecOptions): Promise<WorkspaceBackendExecResult>;
+}
+//#endregion
+export { WorkspaceBackend, WorkspaceBackendExecOptions, WorkspaceBackendExecResult };
+//# sourceMappingURL=workspace-backend.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-backend.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/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"}

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

@@ -0,0 +1,72 @@
+import { EditFileInput, EditFileResult, GrepResult, RunShellResult } from "./tool-io.type.mjs";
+
+//#region ../@warlock.js/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
+ * `.tools.*` factories and the human-facing direct methods. Both share
+ * this single instance, so there is exactly one jail and one set of
+ * rules regardless of who calls.
+ *
+ * Every method here resolves workspace-relative paths against `cwd`,
+ * applies the path allow/deny jail, gates shell commands, enforces read
+ * caps and the read-before-edit stale-hash guard, then delegates the raw
+ * IO to the backend. Policy violations surface as typed errors
+ * (`WorkspacePolicyError` / `WorkspaceEditError`), which the tool layer
+ * turns into agent-visible tool-error data rather than thrown
+ * run-killers.
+ *
+ * @example
+ * const { content, hash } = await ops.readFile("src/index.ts");
+ * await ops.editFile({ path: "src/index.ts", oldString: "x", newString: "y", expectHash: hash });
+ */
+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.
+   */
+  readFile(path: string, opts?: {
+    offset?: number;
+    limit?: number;
+  }): Promise<{
+    content: string;
+    hash: string;
+    totalLines: number;
+  }>;
+  /** Atomically write full content to a jailed path, returning size + hash. */
+  writeFile(path: string, content: string): Promise<{
+    hash: string;
+    bytesWritten: number;
+  }>;
+  /**
+   * Apply an exact-string edit under the read-before-edit guard:
+   * rejects on a non-unique `oldString` (unless `replaceAll`) or a
+   * stale `expectHash`.
+   */
+  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.
+   */
+  exec(command: string, opts?: {
+    timeoutMs?: number;
+  }): Promise<RunShellResult>;
+  /** Search jailed file contents for a regex pattern. */
+  grep(pattern: string, opts?: {
+    glob?: string;
+    ignoreCase?: boolean;
+  }): Promise<GrepResult>;
+  /** Resolve a glob to matching workspace-relative paths within the jail. */
+  glob(pattern: string): Promise<string[]>;
+  /** Whether a jailed path exists (file or directory). */
+  exists(path: string): Promise<boolean>;
+  /** Create a directory (and parents) at a jailed path; idempotent. */
+  mkdir(path: string): Promise<void>;
+  /** Remove a file or directory tree at a jailed path. */
+  remove(path: string): Promise<void>;
+}
+//#endregion
+export { WorkspaceOps };
+//# sourceMappingURL=workspace-ops.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-ops.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/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"}

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

@@ -0,0 +1,86 @@
+//#region ../@warlock.js/ai-workspace/src/contracts/workspace-policy.type.d.ts
+/**
+ * The executor a workspace runs on. `"local"` uses `@warlock.js/fs` +
+ * `node:child_process` against the real filesystem under `cwd`;
+ * `"mock"` uses an in-memory backend (for hermetic, disk-free tests).
+ *
+ * The worktree and container backends from the design doc are deferred
+ * past the W1 surface and intentionally absent from this union.
+ */
+type WorkspaceBackendType = "local" | "mock";
+/**
+ * Shell-execution sub-policy for `run_shell` / `run_tests` and the
+ * `exec()` direct method.
+ *
+ * **Command gating.** Each command'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.
+ *
+ * **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.
+ */
+interface WorkspaceShellPolicy {
+  /** Allowed executable basenames (e.g. `["npm", "node"]`). */
+  allow?: string[];
+  /** Denied executable basenames — wins over `allow`. */
+  deny?: string[];
+  /** Per-command wall-clock cap; on expiry the process is SIGKILLed. */
+  timeoutMs?: number;
+  /** Max bytes captured from stdout/stderr before output is truncated. */
+  maxOutputBytes?: number;
+  /** Explicit environment variables injected into every spawned process. */
+  env?: Record<string, string>;
+  /**
+   * Opt-in passthrough of named `process.env` keys (e.g. `["PATH"]`).
+   * Nothing from `process.env` leaks in unless listed here.
+   */
+  inheritEnv?: string[];
+}
+/**
+ * Read sub-policy controlling how much of a file a single read returns.
+ */
+interface WorkspaceReadPolicy {
+  /** Hard cap on bytes returned by a single read; larger reads truncate. */
+  maxBytes?: number;
+  /** Default number of lines a read returns when no explicit limit is given. */
+  defaultLines?: number;
+}
+/**
+ * The full policy that bounds a workspace — the single source of truth
+ * the policy engine enforces for both `.tools.*` and the direct methods.
+ *
+ * **Path jail.** Every path is `realpath`-resolved and must sit under
+ * `cwd` (or an `allowPaths` root); `denyPaths` globs are blocked even
+ * inside `cwd` (e.g. `.git/**`, `.env*`). A path that escapes the jail
+ * surfaces as a `WorkspacePolicyError`, returned to the agent as tool
+ * data — never a thrown run-killer.
+ *
+ * @example
+ * const policy: WorkspacePolicy = {
+ *   cwd: "/srv/acme-api",
+ *   denyPaths: [".git/**", ".env*"],
+ *   shell: { allow: ["npm", "node"], inheritEnv: ["PATH"], timeoutMs: 60_000 },
+ *   read: { maxBytes: 256_000, defaultLines: 2_000 },
+ *   backend: "local",
+ * };
+ */
+interface WorkspacePolicy {
+  /** Absolute jail root — the workspace cannot read or write outside it. */
+  cwd: string;
+  /** Extra readable roots outside `cwd` (resolved absolute paths). */
+  allowPaths?: string[];
+  /** Globs blocked even inside `cwd` (deny wins over allow). */
+  denyPaths?: string[];
+  /** Shell-execution sub-policy. Absent ⇒ no command may run. */
+  shell?: WorkspaceShellPolicy;
+  /** Read sub-policy (byte cap + default line window). */
+  read?: WorkspaceReadPolicy;
+  /** Executor the workspace runs on. Defaults to `"local"`. */
+  backend?: WorkspaceBackendType;
+}
+//#endregion
+export { WorkspaceBackendType, WorkspacePolicy, WorkspaceReadPolicy, WorkspaceShellPolicy };
+//# sourceMappingURL=workspace-policy.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-policy.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/contracts/workspace-policy.type.ts"],"mappings":";;AAQA;;;;AAAgC;AAgBhC;;KAhBY,oBAAA;;;;;;;;;;AA+BA;AAMZ;;;;UArBiB,oBAAA;EA+CA;EA7Cf,KAAA;;EAEA,IAAA;EAqDO;EAnDP,SAAA;EAqD8B;EAnD9B,cAAA;EAyCA;EAvCA,GAAA,GAAM,MAAM;EA2CZ;;;;EAtCA,UAAA;AAAA;;;AA4C8B;UAtCf,mBAAA;;EAEf,QAAA;;EAEA,YAAY;AAAA;;;;;;;;;;;;;;;;;;;;UAsBG,eAAA;;EAEf,GAAA;;EAEA,UAAA;;EAEA,SAAA;;EAEA,KAAA,GAAQ,oBAAA;;EAER,IAAA,GAAO,mBAAA;;EAEP,OAAA,GAAU,oBAAA;AAAA"}