@warlock.js/ai-workspace 5.44.0 → 5.46.0

package/esm/tools/run-tests.mjs

@@ -38,7 +38,7 @@ const runTestsInputSchema = withJsonSchema({ "~standard": {
 } }, RUN_TESTS_JSON_SCHEMA);
 /** Quote the test pattern as one literal argument for the line's interpreter. */
 function quotePattern(pattern, interpreter, dialect, platform = process.platform) {
-	if (dialect === "powershell" || interpreter === "powershell") return `'${pattern.replace(/['\u2018\u2019\u201A\u201B]/g, "$&$&")}'`;
+	if (dialect === "powershell" || dialect === "powershell5" || interpreter === "powershell") return `'${pattern.replace(/['\u2018\u2019\u201A\u201B]/g, "$&$&")}'`;
 	if (interpreter === "bash" || interpreter === "sh" && platform !== "win32") return `'${pattern.replace(/'/g, "'\\''")}'`;
 	return `"${pattern}"`;
 }

package/esm/tools/run-tests.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"run-tests.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-tests.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  RunShellResult,\n  RunTestsInput,\n  WorkspaceOps,\n  WorkspaceShellInterpreter,\n} from \"../contracts\";\nimport { RUN_TESTS_JSON_SCHEMA } from \"./json-schemas\";\nimport { withJsonSchema } from \"./schema\";\n\n/** The default tool name `run_tests` is exposed to the LLM under. */\nconst DEFAULT_RUN_TESTS_TOOL_NAME = \"run_tests\";\n\n/** The default command run when no `command` override is configured. */\nconst DEFAULT_TEST_COMMAND = \"npm test\";\n\n/**\n * Hand-rolled Standard Schema for {@link RunTestsInput}. `pattern` is the\n * only field and is optional; when present it must be a string without\n * double quotes or newlines — the pattern is forwarded to the runner as a\n * single double-quoted argument, and those characters would break out of\n * the quoting (i.e. inject extra arguments or commands). Validation\n * happens without a runtime schema dependency, mirroring the wider tool\n * layer.\n */\nconst runTestsInputSchema: StandardSchemaV1<RunTestsInput> = withJsonSchema<RunTestsInput>(\n  {\n    \"~standard\": {\n      version: 1,\n      vendor: \"@warlock.js/ai-workspace\",\n      validate: (value) => {\n        // A no-argument call (the common case) is valid and runs the bare\n        // test command.\n        if (value === undefined || value === null) {\n          return { value: {} };\n        }\n\n        if (typeof value !== \"object\") {\n          return { issues: [{ message: \"expected an object\" }] };\n        }\n\n        const candidate = value as Record<string, unknown>;\n\n        if (candidate.pattern !== undefined && typeof candidate.pattern !== \"string\") {\n          return { issues: [{ message: \"pattern must be a string\", path: [\"pattern\"] }] };\n        }\n\n        if (typeof candidate.pattern === \"string\" && /[\"\\r\\n]/.test(candidate.pattern)) {\n          return {\n            issues: [\n              {\n                message: \"pattern must not contain double quotes or newlines\",\n                path: [\"pattern\"],\n              },\n            ],\n          };\n        }\n\n        const result: RunTestsInput = {};\n\n        if (candidate.pattern !== undefined) {\n          result.pattern = candidate.pattern as string;\n        }\n\n        return { value: result };\n      },\n    },\n  },\n  RUN_TESTS_JSON_SCHEMA,\n);\n\n/** Options for {@link makeRunTestsTool}. */\nexport interface MakeRunTestsToolOptions {\n  /** Override the tool name exposed to the LLM (default `\"run_tests\"`). */\n  name?: string;\n  /**\n   * The base test command to run (default `\"npm test\"`). When the model\n   * supplies a `pattern`, it is appended to this command as a single\n   * quoted argument.\n   */\n  command?: string;\n  /**\n   * The workspace's `shell.interpreter`, so the pattern is quoted for the\n   * way the line runs: double quotes in argv mode (the default), single\n   * quotes for `/bin/sh` (so `$` and backticks in a pattern stay literal),\n   * double quotes for cmd.exe.\n   */\n  interpreter?: WorkspaceShellInterpreter;\n  /**\n   * The grammar of the shell the line runs in; with `interpreter` it picks\n   * the quoting: single quotes (doubled inside) for PowerShell.\n   */\n  dialect?: \"posix\" | \"cmd\" | \"powershell\";\n  /** The platform quoting is chosen for. Default: the running one. */\n  platform?: NodeJS.Platform;\n}\n\n/** Quote the test pattern as one literal argument for the line's interpreter. */\nexport function quotePattern(\n  pattern: string,\n  interpreter: WorkspaceShellInterpreter,\n  dialect?: \"posix\" | \"cmd\" | \"powershell\",\n  platform: NodeJS.Platform = process.platform,\n): string {\n  if (dialect === \"powershell\" || interpreter === \"powershell\") {\n    // PowerShell also reads the typographic single quotes as quotes; each is\n    // doubled to stay literal.\n    return `'${pattern.replace(/['\\u2018\\u2019\\u201A\\u201B]/g, \"$&$&\")}'`;\n  }\n\n  if (interpreter === \"bash\" || (interpreter === \"sh\" && platform !== \"win32\")) {\n    return `'${pattern.replace(/'/g, \"'\\\\''\")}'`;\n  }\n\n  return `\"${pattern}\"`;\n}\n\n/**\n * Build the `run_tests` tool — a {@link ToolContract} convenience over\n * `run_shell` that runs the workspace's configured test command through\n * the policy-enforced {@link WorkspaceOps} layer.\n *\n * The base command defaults to `\"npm test\"` and can be overridden via\n * `options.command`. When the model passes a `pattern`, it is appended to\n * the command as a **single quoted argument** — a path/suite filter the\n * tokenizer hands to the runner as one argv element (e.g.\n * `npm test \"src/cart\"`), so shell metacharacters inside it are literal\n * data, never a second command. Like `run_shell`, the resolved command's\n * executable is gated by the shell policy — a denial surfaces in the\n * result's `error` field — and a non-zero exit (failing tests) comes back\n * as `data` for the agent to read and fix. The agent run's cancellation\n * `signal` is threaded per invocation, exactly as for `run_shell`.\n *\n * @param ops - The policy-enforced operation layer to delegate `exec` to.\n * @param options - Optional tool-name and base-command overrides.\n *\n * @example\n * const runTests = makeRunTestsTool(ops, { command: \"pnpm test\" });\n * const { data } = await runTests.invoke({ pattern: \"cart-total\" });\n * if (data.exitCode !== 0) inspect(data.stderr);\n */\nexport function makeRunTestsTool(\n  ops: WorkspaceOps,\n  options?: MakeRunTestsToolOptions,\n): ToolContract<RunTestsInput, RunShellResult> {\n  const baseCommand = options?.command ?? DEFAULT_TEST_COMMAND;\n\n  return tool<RunTestsInput, RunShellResult>({\n    name: options?.name ?? DEFAULT_RUN_TESTS_TOOL_NAME,\n    description:\n      \"Run the workspace's test suite, optionally narrowed to a path or \" +\n      \"name pattern forwarded to the test runner. Failing tests return a \" +\n      \"non-zero exit code as data, not an error.\",\n    action: (input) =>\n      input.pattern ? `Running tests matching \"${input.pattern}\"` : \"Running tests\",\n    input: runTestsInputSchema,\n    execute: (input, ctx) => {\n      // The pattern rides as ONE quoted token (double quotes and newlines are\n      // rejected by the schema; under /bin/sh it is single-quoted, so `$` and\n      // backticks stay literal), so it reaches the runner as a single argv\n      // element and can never smuggle in additional commands or arguments.\n      const command = input.pattern\n        ? `${baseCommand} ${quotePattern(input.pattern, options?.interpreter ?? \"none\", options?.dialect, options?.platform)}`\n        : baseCommand;\n\n      return ops.exec(command, ctx?.signal ? { signal: ctx.signal } : undefined);\n    },\n  });\n}\n"],"mappings":";;;;;;AAYA,MAAM,8BAA8B;;AAGpC,MAAM,uBAAuB;;;;;;;;;;AAW7B,MAAM,sBAAuD,eAC3D,EACE,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UAAU;EAGnB,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO,EAAE,OAAO,CAAC,EAAE;EAGrB,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,qBAAqB,CAAC,EAAE;EAGvD,MAAM,YAAY;EAElB,IAAI,UAAU,YAAY,UAAa,OAAO,UAAU,YAAY,UAClE,OAAO,EAAE,QAAQ,CAAC;GAAE,SAAS;GAA4B,MAAM,CAAC,SAAS;EAAE,CAAC,EAAE;EAGhF,IAAI,OAAO,UAAU,YAAY,YAAY,UAAU,KAAK,UAAU,OAAO,GAC3E,OAAO,EACL,QAAQ,CACN;GACE,SAAS;GACT,MAAM,CAAC,SAAS;EAClB,CACF,EACF;EAGF,MAAM,SAAwB,CAAC;EAE/B,IAAI,UAAU,YAAY,QACxB,OAAO,UAAU,UAAU;EAG7B,OAAO,EAAE,OAAO,OAAO;CACzB;AACF,EACF,GACA,qBACF;;AA6BA,SAAgB,aACd,SACA,aACA,SACA,WAA4B,QAAQ,UAC5B;CACR,IAAI,YAAY,gBAAgB,gBAAgB,cAG9C,OAAO,IAAI,QAAQ,QAAQ,gCAAgC,MAAM,EAAE;CAGrE,IAAI,gBAAgB,UAAW,gBAAgB,QAAQ,aAAa,SAClE,OAAO,IAAI,QAAQ,QAAQ,MAAM,OAAO,EAAE;CAG5C,OAAO,IAAI,QAAQ;AACrB;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,iBACd,KACA,SAC6C;CAC7C,MAAM,cAAc,SAAS,WAAW;CAExC,OAAO,KAAoC;EACzC,MAAM,SAAS,QAAQ;EACvB,aACE;EAGF,SAAS,UACP,MAAM,UAAU,2BAA2B,MAAM,QAAQ,KAAK;EAChE,OAAO;EACP,UAAU,OAAO,QAAQ;GAKvB,MAAM,UAAU,MAAM,UAClB,GAAG,YAAY,GAAG,aAAa,MAAM,SAAS,SAAS,eAAe,QAAQ,SAAS,SAAS,SAAS,QAAQ,MACjH;GAEJ,OAAO,IAAI,KAAK,SAAS,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MAAS;EAC3E;CACF,CAAC;AACH"}
+{"version":3,"file":"run-tests.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-tests.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  RunShellResult,\n  RunTestsInput,\n  WorkspaceOps,\n  WorkspaceShellInterpreter,\n} from \"../contracts\";\nimport { RUN_TESTS_JSON_SCHEMA } from \"./json-schemas\";\nimport { withJsonSchema } from \"./schema\";\n\n/** The default tool name `run_tests` is exposed to the LLM under. */\nconst DEFAULT_RUN_TESTS_TOOL_NAME = \"run_tests\";\n\n/** The default command run when no `command` override is configured. */\nconst DEFAULT_TEST_COMMAND = \"npm test\";\n\n/**\n * Hand-rolled Standard Schema for {@link RunTestsInput}. `pattern` is the\n * only field and is optional; when present it must be a string without\n * double quotes or newlines — the pattern is forwarded to the runner as a\n * single double-quoted argument, and those characters would break out of\n * the quoting (i.e. inject extra arguments or commands). Validation\n * happens without a runtime schema dependency, mirroring the wider tool\n * layer.\n */\nconst runTestsInputSchema: StandardSchemaV1<RunTestsInput> = withJsonSchema<RunTestsInput>(\n  {\n    \"~standard\": {\n      version: 1,\n      vendor: \"@warlock.js/ai-workspace\",\n      validate: (value) => {\n        // A no-argument call (the common case) is valid and runs the bare\n        // test command.\n        if (value === undefined || value === null) {\n          return { value: {} };\n        }\n\n        if (typeof value !== \"object\") {\n          return { issues: [{ message: \"expected an object\" }] };\n        }\n\n        const candidate = value as Record<string, unknown>;\n\n        if (candidate.pattern !== undefined && typeof candidate.pattern !== \"string\") {\n          return { issues: [{ message: \"pattern must be a string\", path: [\"pattern\"] }] };\n        }\n\n        if (typeof candidate.pattern === \"string\" && /[\"\\r\\n]/.test(candidate.pattern)) {\n          return {\n            issues: [\n              {\n                message: \"pattern must not contain double quotes or newlines\",\n                path: [\"pattern\"],\n              },\n            ],\n          };\n        }\n\n        const result: RunTestsInput = {};\n\n        if (candidate.pattern !== undefined) {\n          result.pattern = candidate.pattern as string;\n        }\n\n        return { value: result };\n      },\n    },\n  },\n  RUN_TESTS_JSON_SCHEMA,\n);\n\n/** Options for {@link makeRunTestsTool}. */\nexport interface MakeRunTestsToolOptions {\n  /** Override the tool name exposed to the LLM (default `\"run_tests\"`). */\n  name?: string;\n  /**\n   * The base test command to run (default `\"npm test\"`). When the model\n   * supplies a `pattern`, it is appended to this command as a single\n   * quoted argument.\n   */\n  command?: string;\n  /**\n   * The workspace's `shell.interpreter`, so the pattern is quoted for the\n   * way the line runs: double quotes in argv mode (the default), single\n   * quotes for `/bin/sh` (so `$` and backticks in a pattern stay literal),\n   * double quotes for cmd.exe.\n   */\n  interpreter?: WorkspaceShellInterpreter;\n  /**\n   * The grammar of the shell the line runs in; with `interpreter` it picks\n   * the quoting: single quotes (doubled inside) for PowerShell.\n   */\n  dialect?: \"posix\" | \"cmd\" | \"powershell\" | \"powershell5\";\n  /** The platform quoting is chosen for. Default: the running one. */\n  platform?: NodeJS.Platform;\n}\n\n/** Quote the test pattern as one literal argument for the line's interpreter. */\nexport function quotePattern(\n  pattern: string,\n  interpreter: WorkspaceShellInterpreter,\n  dialect?: \"posix\" | \"cmd\" | \"powershell\" | \"powershell5\",\n  platform: NodeJS.Platform = process.platform,\n): string {\n  if (dialect === \"powershell\" || dialect === \"powershell5\" || interpreter === \"powershell\") {\n    // PowerShell also reads the typographic single quotes as quotes; each is\n    // doubled to stay literal.\n    return `'${pattern.replace(/['\\u2018\\u2019\\u201A\\u201B]/g, \"$&$&\")}'`;\n  }\n\n  if (interpreter === \"bash\" || (interpreter === \"sh\" && platform !== \"win32\")) {\n    return `'${pattern.replace(/'/g, \"'\\\\''\")}'`;\n  }\n\n  return `\"${pattern}\"`;\n}\n\n/**\n * Build the `run_tests` tool — a {@link ToolContract} convenience over\n * `run_shell` that runs the workspace's configured test command through\n * the policy-enforced {@link WorkspaceOps} layer.\n *\n * The base command defaults to `\"npm test\"` and can be overridden via\n * `options.command`. When the model passes a `pattern`, it is appended to\n * the command as a **single quoted argument** — a path/suite filter the\n * tokenizer hands to the runner as one argv element (e.g.\n * `npm test \"src/cart\"`), so shell metacharacters inside it are literal\n * data, never a second command. Like `run_shell`, the resolved command's\n * executable is gated by the shell policy — a denial surfaces in the\n * result's `error` field — and a non-zero exit (failing tests) comes back\n * as `data` for the agent to read and fix. The agent run's cancellation\n * `signal` is threaded per invocation, exactly as for `run_shell`.\n *\n * @param ops - The policy-enforced operation layer to delegate `exec` to.\n * @param options - Optional tool-name and base-command overrides.\n *\n * @example\n * const runTests = makeRunTestsTool(ops, { command: \"pnpm test\" });\n * const { data } = await runTests.invoke({ pattern: \"cart-total\" });\n * if (data.exitCode !== 0) inspect(data.stderr);\n */\nexport function makeRunTestsTool(\n  ops: WorkspaceOps,\n  options?: MakeRunTestsToolOptions,\n): ToolContract<RunTestsInput, RunShellResult> {\n  const baseCommand = options?.command ?? DEFAULT_TEST_COMMAND;\n\n  return tool<RunTestsInput, RunShellResult>({\n    name: options?.name ?? DEFAULT_RUN_TESTS_TOOL_NAME,\n    description:\n      \"Run the workspace's test suite, optionally narrowed to a path or \" +\n      \"name pattern forwarded to the test runner. Failing tests return a \" +\n      \"non-zero exit code as data, not an error.\",\n    action: (input) =>\n      input.pattern ? `Running tests matching \"${input.pattern}\"` : \"Running tests\",\n    input: runTestsInputSchema,\n    execute: (input, ctx) => {\n      // The pattern rides as ONE quoted token (double quotes and newlines are\n      // rejected by the schema; under /bin/sh it is single-quoted, so `$` and\n      // backticks stay literal), so it reaches the runner as a single argv\n      // element and can never smuggle in additional commands or arguments.\n      const command = input.pattern\n        ? `${baseCommand} ${quotePattern(input.pattern, options?.interpreter ?? \"none\", options?.dialect, options?.platform)}`\n        : baseCommand;\n\n      return ops.exec(command, ctx?.signal ? { signal: ctx.signal } : undefined);\n    },\n  });\n}\n"],"mappings":";;;;;;AAYA,MAAM,8BAA8B;;AAGpC,MAAM,uBAAuB;;;;;;;;;;AAW7B,MAAM,sBAAuD,eAC3D,EACE,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UAAU;EAGnB,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO,EAAE,OAAO,CAAC,EAAE;EAGrB,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,qBAAqB,CAAC,EAAE;EAGvD,MAAM,YAAY;EAElB,IAAI,UAAU,YAAY,UAAa,OAAO,UAAU,YAAY,UAClE,OAAO,EAAE,QAAQ,CAAC;GAAE,SAAS;GAA4B,MAAM,CAAC,SAAS;EAAE,CAAC,EAAE;EAGhF,IAAI,OAAO,UAAU,YAAY,YAAY,UAAU,KAAK,UAAU,OAAO,GAC3E,OAAO,EACL,QAAQ,CACN;GACE,SAAS;GACT,MAAM,CAAC,SAAS;EAClB,CACF,EACF;EAGF,MAAM,SAAwB,CAAC;EAE/B,IAAI,UAAU,YAAY,QACxB,OAAO,UAAU,UAAU;EAG7B,OAAO,EAAE,OAAO,OAAO;CACzB;AACF,EACF,GACA,qBACF;;AA6BA,SAAgB,aACd,SACA,aACA,SACA,WAA4B,QAAQ,UAC5B;CACR,IAAI,YAAY,gBAAgB,YAAY,iBAAiB,gBAAgB,cAG3E,OAAO,IAAI,QAAQ,QAAQ,gCAAgC,MAAM,EAAE;CAGrE,IAAI,gBAAgB,UAAW,gBAAgB,QAAQ,aAAa,SAClE,OAAO,IAAI,QAAQ,QAAQ,MAAM,OAAO,EAAE;CAG5C,OAAO,IAAI,QAAQ;AACrB;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,iBACd,KACA,SAC6C;CAC7C,MAAM,cAAc,SAAS,WAAW;CAExC,OAAO,KAAoC;EACzC,MAAM,SAAS,QAAQ;EACvB,aACE;EAGF,SAAS,UACP,MAAM,UAAU,2BAA2B,MAAM,QAAQ,KAAK;EAChE,OAAO;EACP,UAAU,OAAO,QAAQ;GAKvB,MAAM,UAAU,MAAM,UAClB,GAAG,YAAY,GAAG,aAAa,MAAM,SAAS,SAAS,eAAe,QAAQ,SAAS,SAAS,SAAS,QAAQ,MACjH;GAEJ,OAAO,IAAI,KAAK,SAAS,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,MAAS;EAC3E;CACF,CAAC;AACH"}

package/esm/workspace.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/workspace.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA6bgB,UAAU,QAAQ,kBAAkB;;;;;;;;YAWxC;;IAER,UAAU,QAAQ,kBAAkB"}
+{"version":3,"file":"workspace.d.mts","names":[],"sources":["../../../../../../../packages/ai-workspace/src/workspace.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAkdgB,UAAU,QAAQ,kBAAkB;;;;;;;;YAWxC;;IAER,UAAU,QAAQ,kBAAkB"}

package/esm/workspace.mjs

@@ -2,6 +2,7 @@ import { WorkspacePolicyError } from "./errors.mjs";
 import { resolveShell } from "./policy/shell-interpreter.mjs";
 import { classifyShellCommand } from "./policy/shell-check.mjs";
 import { applyPatchWithOps } from "./patch/apply-patch-generic.mjs";
+import { samePattern } from "./policy/approval-helpers.mjs";
 import { ShellJobs } from "./shell-jobs.mjs";
 import { createOps } from "./ops.mjs";
 import { createLocalBackend } from "./backends/local.mjs";
@@ -94,7 +95,17 @@ var WorkspaceImpl = class WorkspaceImpl {
 			approvals: []
 		};
 		this.resolvedShell = resolveShell(policy.shell);
-		this.shell = { classify: (line) => classifyShellCommand(line, policy) };
+		const approvals = this.state.approvals;
+		this.shell = {
+			classify: (line) => classifyShellCommand(line, policy),
+			remembered: () => [...approvals],
+			forget: (pattern) => {
+				const index = approvals.findIndex((entry) => samePattern(entry, pattern));
+				if (index === -1) return false;
+				approvals.splice(index, 1);
+				return true;
+			}
+		};
 		const backend = selectBackend(policy);
 		this.ops = createOps(backend, policy, {
 			jobs: this.state.jobs,

package/esm/workspace.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.mjs","names":[],"sources":["../../../../../../../packages/ai-workspace/src/workspace.ts"],"sourcesContent":["import path from \"node:path\";\nimport { ai, type ToolContract } from \"@warlock.js/ai\";\nimport { createLocalBackend } from \"./backends/local\";\nimport { createMockBackend } from \"./backends/mock\";\nimport { WorkspacePolicyError } from \"./errors\";\nimport { createOps } from \"./ops\";\nimport { classifyShellCommand } from \"./policy/shell-check\";\nimport { resolveShell, type ResolvedShell } from \"./policy/shell-interpreter\";\nimport { ShellJobs } from \"./shell-jobs\";\nimport { TodoStore } from \"./todos\";\nimport { applyPatchWithOps } from \"./patch/apply-patch-generic\";\nimport { makeApplyPatchTool } from \"./tools/apply-patch\";\nimport { makeEditFileTool } from \"./tools/edit-file\";\nimport { makeGlobTool } from \"./tools/glob\";\nimport { makeGrepTool } from \"./tools/grep\";\nimport { makeListDirTool } from \"./tools/list-dir\";\nimport { makeMultiEditTool } from \"./tools/multi-edit\";\nimport { makeReadFileTool } from \"./tools/read-file\";\nimport { makeRunShellTool } from \"./tools/run-shell\";\nimport { makeRunTestsTool } from \"./tools/run-tests\";\nimport { makeShellKillTool } from \"./tools/shell-kill\";\nimport { makeShellOutputTool } from \"./tools/shell-output\";\nimport { makeTodoReadTool, makeTodoWriteTool } from \"./tools/todo\";\nimport { makeWriteFileTool } from \"./tools/write-file\";\nimport type {\n  ApplyPatchInput,\n  ApplyPatchResult,\n  EditFileInput,\n  EditFileResult,\n  ExecOptions,\n  GrepResult,\n  ListDirOptions,\n  ListDirResult,\n  MultiEditInput,\n  MultiEditResult,\n  ReadFileResult,\n  RunShellResult,\n  ShellJobInfo,\n  ShellOutputOptions,\n  ShellOutputResult,\n  StartShellOptions,\n  TodoListResult,\n  Workspace,\n  WorkspaceBackend,\n  WorkspaceCommandPattern,\n  WorkspaceOps,\n  WorkspaceShellClassification,\n  WorkspacePolicy,\n  WorkspaceTodoInput,\n  WorkspaceToolName,\n  WorkspaceTools,\n} from \"./contracts\";\n\n/**\n * The full set of tool names a writable workspace vends, in a stable\n * canonical order so `tools.all()` is deterministic.\n */\nconst ALL_TOOL_NAMES: readonly WorkspaceToolName[] = [\n  \"readFile\",\n  \"editFile\",\n  \"multiEdit\",\n  \"applyPatch\",\n  \"writeFile\",\n  \"listDir\",\n  \"runShell\",\n  \"shellOutput\",\n  \"shellKill\",\n  \"runTests\",\n  \"grep\",\n  \"glob\",\n  \"todoWrite\",\n  \"todoRead\",\n];\n\n/**\n * The subset a {@link Workspace.readonly} projection exposes — the\n * tools that cannot change the tree. `editFile` / `multiEdit` /\n * `writeFile` / the shell tools / `runTests` are deliberately omitted so a\n * reviewer agent has no path to change it. The todo tools stay: they only\n * touch the in-memory plan.\n */\nconst READONLY_TOOL_NAMES: readonly WorkspaceToolName[] = [\n  \"readFile\",\n  \"listDir\",\n  \"grep\",\n  \"glob\",\n  \"todoWrite\",\n  \"todoRead\",\n];\n\n/** Tools vended only when the policy enables background commands. */\nconst BACKGROUND_TOOL_NAMES: ReadonlySet<WorkspaceToolName> = new Set([\"shellOutput\", \"shellKill\"]);\n\n/**\n * State one workspace shares with every projection made from it: its\n * background commands and its todo list.\n */\ninterface WorkspaceState {\n  jobs: ShellJobs;\n  todos: TodoStore;\n  /** Command patterns the host approved with `remember`. */\n  approvals: WorkspaceCommandPattern[];\n}\n\n/**\n * Choose the dumb IO executor for a policy. `\"mock\"` selects the\n * in-memory backend (hermetic tests); anything else — including the\n * `\"local\"` default and an absent `backend` — selects the real-disk\n * local backend.\n */\nfunction selectBackend(policy: WorkspacePolicy): WorkspaceBackend {\n  if (policy.backend === \"mock\") {\n    return createMockBackend();\n  }\n\n  return createLocalBackend();\n}\n\n/**\n * The internal {@link Workspace} implementation. Holds the resolved\n * backend, the policy, and the single shared {@link WorkspaceOps} seam\n * that both the agent-facing `.tools.*` factories and the human-facing\n * direct methods funnel through — one jail, one rule set, two callers.\n *\n * The `allowedTools` set narrows what `tools.*` will vend and which\n * mutating direct methods are permitted: a full workspace allows every\n * name; a {@link WorkspaceImpl.readonly} projection allows only the\n * read/grep/glob subset and rejects writes/edits/shell/mkdir/remove.\n *\n * Constructed via {@link workspace}; the class itself is internal.\n */\nclass WorkspaceImpl implements Workspace {\n  /** The shared, policy-enforced operation layer (jail + guards). */\n  private readonly ops: WorkspaceOps;\n\n  /** Tool names this projection is permitted to vend / mutate through. */\n  private readonly allowedTools: ReadonlySet<WorkspaceToolName>;\n\n  public readonly policy: WorkspacePolicy;\n\n  public readonly tools: WorkspaceTools;\n\n  public readonly shell: { classify(line: string): WorkspaceShellClassification };\n\n  /** The shell the policy's interpreter resolves to on this host. */\n  private readonly resolvedShell: ResolvedShell;\n\n  /** Background commands + todo list, shared with projections. */\n  private readonly state: WorkspaceState;\n\n  public constructor(\n    policy: WorkspacePolicy,\n    allowedTools: readonly WorkspaceToolName[] = ALL_TOOL_NAMES,\n    state?: WorkspaceState,\n  ) {\n    this.policy = policy;\n    this.allowedTools = new Set(allowedTools);\n    this.state = state ?? { jobs: new ShellJobs(), todos: new TodoStore(), approvals: [] };\n    this.resolvedShell = resolveShell(policy.shell);\n    this.shell = { classify: (line) => classifyShellCommand(line, policy) };\n\n    const backend = selectBackend(policy);\n    this.ops = createOps(backend, policy, {\n      jobs: this.state.jobs,\n      approvals: this.state.approvals,\n    });\n    this.tools = this.buildTools();\n  }\n\n  /**\n   * Assemble the agent-facing tool namespace. Each factory builds its\n   * tool over the shared `ops`; `all()` returns every *allowed* tool in\n   * canonical order and `pick(...)` returns the named subset (silently\n   * dropping any name this projection does not allow, so a `readonly()`\n   * workspace can never be coaxed into vending a mutating tool).\n   */\n  private buildTools(): WorkspaceTools {\n    // Each `make*Tool` returns a precisely-typed\n    // `ToolContract<SpecificInput, SpecificOutput>`, but the agent-facing\n    // `WorkspaceTools` surface vends the type-erased `ToolContract`\n    // (`ToolContract<unknown, unknown>`). Because `ToolContract` puts its\n    // input in a contravariant position (`execute(input)` / `action(input)`),\n    // a specific contract is not assignable to the erased one — so erase it\n    // once, here, through `unknown`. The runtime object is identical; only\n    // the static input type is widened for the shared surface.\n    const erase = <TInput, TOutput>(contract: ToolContract<TInput, TOutput>): ToolContract =>\n      contract as unknown as ToolContract;\n\n    const shell = this.policy.shell;\n    const background = shell?.background !== undefined;\n    const resolvedShell = this.resolvedShell;\n\n    const factories: Record<\n      WorkspaceToolName,\n      (opts?: { name?: string; command?: string }) => ToolContract\n    > = {\n      readFile: (opts) => erase(makeReadFileTool(this.ops, opts)),\n      editFile: (opts) => erase(makeEditFileTool(this.ops, opts)),\n      multiEdit: (opts) => erase(makeMultiEditTool(this.ops, opts)),\n      applyPatch: (opts) => erase(makeApplyPatchTool(this.ops, opts)),\n      writeFile: (opts) => erase(makeWriteFileTool(this.ops, opts)),\n      listDir: (opts) => erase(makeListDirTool(this.ops, opts)),\n      runShell: (opts) =>\n        erase(\n          makeRunShellTool(this.ops, {\n            ...(opts?.name !== undefined ? { name: opts.name } : {}),\n            ...(shell?.timeoutMs !== undefined ? { maxTimeoutMs: shell.timeoutMs } : {}),\n            background,\n            ...(resolvedShell.interpreter !== \"none\" ? { shellLabel: resolvedShell.label } : {}),\n            shellDialect: resolvedShell.interpreter === \"none\" ? \"none\" : resolvedShell.dialect,\n          }),\n        ),\n      shellOutput: (opts) => erase(makeShellOutputTool(this.ops, opts)),\n      shellKill: (opts) => erase(makeShellKillTool(this.ops, opts)),\n      runTests: (opts) =>\n        erase(\n          makeRunTestsTool(this.ops, {\n            ...opts,\n            interpreter: resolvedShell.interpreter,\n            dialect: resolvedShell.dialect,\n          }),\n        ),\n      grep: (opts) => erase(makeGrepTool(this.ops, opts)),\n      glob: (opts) => erase(makeGlobTool(this.ops, opts)),\n      todoWrite: (opts) => erase(makeTodoWriteTool(this.state.todos, opts)),\n      todoRead: (opts) => erase(makeTodoReadTool(this.state.todos, opts)),\n    };\n\n    const build = (name: WorkspaceToolName, opts?: { name?: string; command?: string }) =>\n      factories[name](opts);\n\n    // `shell_output` / `shell_kill` only mean something when background\n    // commands can be started, so `all()` leaves them out otherwise.\n    const vendedByAll = (name: WorkspaceToolName): boolean =>\n      this.allowedTools.has(name) && (background || !BACKGROUND_TOOL_NAMES.has(name));\n\n    return {\n      all: () => ALL_TOOL_NAMES.filter(vendedByAll).map((name) => build(name)),\n      pick: (...names: WorkspaceToolName[]) =>\n        names.filter((name) => this.allowedTools.has(name)).map((name) => build(name)),\n      readFile: (opts) => build(\"readFile\", opts),\n      editFile: (opts) => build(\"editFile\", opts),\n      multiEdit: (opts) => build(\"multiEdit\", opts),\n      applyPatch: (opts) => build(\"applyPatch\", opts),\n      writeFile: (opts) => build(\"writeFile\", opts),\n      listDir: (opts) => build(\"listDir\", opts),\n      runShell: (opts) => build(\"runShell\", opts),\n      shellOutput: (opts) => build(\"shellOutput\", opts),\n      shellKill: (opts) => build(\"shellKill\", opts),\n      runTests: (opts) => build(\"runTests\", opts),\n      grep: (opts) => build(\"grep\", opts),\n      glob: (opts) => build(\"glob\", opts),\n      todoWrite: (opts) => build(\"todoWrite\", opts),\n      todoRead: (opts) => build(\"todoRead\", opts),\n    };\n  }\n\n  /**\n   * Reject a mutating direct method on a read-only projection — surfaced\n   * as a {@link WorkspacePolicyError} (the same typed error a denied\n   * command produces) so a caller branches on `error.type`.\n   */\n  private assertWritable(operation: string): void {\n    if (this.allowedTools.has(\"writeFile\")) {\n      return;\n    }\n\n    throw new WorkspacePolicyError(\n      `Operation \"${operation}\" is not permitted on a read-only workspace.`,\n      { type: \"denied-command\", command: operation },\n    );\n  }\n\n  public readFile(\n    filePath: string,\n    opts?: { offset?: number; limit?: number },\n  ): Promise<ReadFileResult> {\n    return this.ops.readFile(filePath, opts);\n  }\n\n  public async writeFile(\n    filePath: string,\n    content: string,\n  ): Promise<{ hash: string; bytesWritten: number }> {\n    this.assertWritable(\"writeFile\");\n\n    return this.ops.writeFile(filePath, content);\n  }\n\n  public async editFile(input: EditFileInput): Promise<EditFileResult> {\n    this.assertWritable(\"editFile\");\n\n    return this.ops.editFile(input);\n  }\n\n  public async multiEdit(input: MultiEditInput): Promise<MultiEditResult> {\n    this.assertWritable(\"multiEdit\");\n\n    return this.ops.multiEdit(input);\n  }\n\n  public async applyPatch(input: ApplyPatchInput): Promise<ApplyPatchResult> {\n    this.assertWritable(\"applyPatch\");\n\n    return this.ops.applyPatch ? this.ops.applyPatch(input) : applyPatchWithOps(this.ops, input);\n  }\n\n  public listDir(dirPath?: string, opts?: ListDirOptions): Promise<ListDirResult> {\n    return this.ops.listDir(dirPath, opts);\n  }\n\n  public async exec(command: string, opts?: ExecOptions): Promise<RunShellResult> {\n    this.assertWritable(\"exec\");\n\n    return this.ops.exec(command, opts);\n  }\n\n  public async startShell(command: string, opts?: StartShellOptions): Promise<ShellJobInfo> {\n    this.assertWritable(\"startShell\");\n\n    return this.ops.startShell(command, opts);\n  }\n\n  public shellOutput(id: string, opts?: ShellOutputOptions): Promise<ShellOutputResult> {\n    return this.ops.shellOutput(id, opts);\n  }\n\n  public async shellKill(id: string): Promise<ShellJobInfo> {\n    this.assertWritable(\"shellKill\");\n\n    return this.ops.shellKill(id);\n  }\n\n  public listShells(): ShellJobInfo[] {\n    return this.ops.listShells();\n  }\n\n  public readTodos(): TodoListResult {\n    return this.state.todos.read();\n  }\n\n  public writeTodos(todos: WorkspaceTodoInput[]): TodoListResult {\n    return this.state.todos.write(todos);\n  }\n\n  public dispose(): Promise<void> {\n    return this.ops.dispose();\n  }\n\n  public grep(\n    pattern: string,\n    opts?: { glob?: string; ignoreCase?: boolean },\n  ): Promise<GrepResult> {\n    return this.ops.grep(pattern, opts);\n  }\n\n  public glob(pattern: string): Promise<string[]> {\n    return this.ops.glob(pattern);\n  }\n\n  public exists(filePath: string): Promise<boolean> {\n    return this.ops.exists(filePath);\n  }\n\n  public async mkdir(filePath: string): Promise<void> {\n    this.assertWritable(\"mkdir\");\n\n    return this.ops.mkdir(filePath);\n  }\n\n  public async remove(filePath: string): Promise<void> {\n    this.assertWritable(\"remove\");\n\n    return this.ops.remove(filePath);\n  }\n\n  /**\n   * A read-only projection over the SAME policy — only the read / list /\n   * grep / glob / todo tools are vended and every mutating direct method\n   * rejects with a {@link WorkspacePolicyError}. A fresh ops/backend is\n   * built from the identical policy, so the projection sees the same jailed\n   * tree; it shares this workspace's background commands and todo list.\n   */\n  public readonly(): Workspace {\n    return new WorkspaceImpl(\n      this.policy,\n      READONLY_TOOL_NAMES.filter((name) => this.allowedTools.has(name)),\n      this.state,\n    );\n  }\n\n  /**\n   * A sub-jailed view rooted at `subdir` (relative to this workspace's\n   * `cwd`). Returns a brand-new workspace whose policy is this policy\n   * with `cwd` narrowed to `join(cwd, subdir)` — same backend selection,\n   * same allow/deny/shell/read sub-policies, but a tighter jail root. It\n   * shares this workspace's background commands and todo list.\n   */\n  public scope(subdir: string): Workspace {\n    return new WorkspaceImpl(\n      { ...this.policy, cwd: path.join(this.policy.cwd, subdir) },\n      [...this.allowedTools],\n      this.state,\n    );\n  }\n}\n\n/**\n * Build a {@link Workspace} — the integrator that wires a\n * {@link WorkspacePolicy} to a backend, the shared policy-enforced ops\n * layer, and the agent-facing tool factories.\n *\n * The backend is chosen from `policy.backend`: `\"mock\"` runs in memory\n * (hermetic tests); the `\"local\"` default (and any absent value) runs\n * over the real disk via `@warlock.js/fs` + `node:child_process`. The\n * returned workspace exposes:\n *\n * - **`tools.*`** — `readFile` / `editFile` / `multiEdit` / `writeFile` /\n *   `listDir` / `runShell` / `shellOutput` / `shellKill` / `runTests` /\n *   `grep` / `glob` / `todoWrite` / `todoRead`, plus `all()` (every tool)\n *   and `pick(...)` (a least-privilege subset).\n * - **direct methods** — `readFile` / `writeFile` / `editFile` /\n *   `multiEdit` / `listDir` / `exec` / `startShell` / `shellOutput` /\n *   `shellKill` / `listShells` / `grep` / `glob` / `exists` / `mkdir` /\n *   `remove` / `readTodos` / `writeTodos`, each delegating to the shared\n *   ops layer, and `dispose()`.\n * - **`readonly()`** — a projection that vends only the read-side tools and\n *   rejects every mutating direct method.\n * - **`scope(subdir)`** — a sub-jailed workspace rooted at `subdir`.\n *\n * Available at runtime as `ai.workspace(policy)` once this module is\n * imported (it registers the verb on the shared `ai` object).\n *\n * @param policy - The policy bounding the workspace (its `cwd` is the jail root).\n * @returns A fully-wired {@link Workspace}.\n *\n * @example\n * const ws = workspace({ cwd: \"/srv/acme-api\", shell: { allow: [\"npm\"], inheritEnv: [\"PATH\"] } });\n * const dev = ai.agent({ model, tools: ws.tools.all() });\n * await dev.execute(\"Make the failing cart-total suite green.\");\n *\n * @example\n * // Least-privilege reviewer — no write, no shell.\n * const reviewer = ai.agent({ model, tools: ws.readonly().tools.all() });\n */\nexport function workspace(policy: WorkspacePolicy): Workspace {\n  return new WorkspaceImpl(policy);\n}\n\n/**\n * Attach the `workspace` verb to the `ai` namespace via module augmentation,\n * per the `ai.`-namespace convention. `@warlock.js/ai` now exposes a named `Ai`\n * interface for exactly this, so after a bare `import \"@warlock.js/ai-workspace\"`,\n * `ai.workspace(...)` is globally typed — no view/cast needed.\n */\ndeclare module \"@warlock.js/ai\" {\n  interface Ai {\n    /** Build a policy-jailed filesystem + shell {@link Workspace}. */\n    workspace(policy: WorkspacePolicy): Workspace;\n  }\n}\n\n// Runtime registration: attach `workspace` onto the shared `ai` object the\n// moment this package is imported (the augmentation above types it).\nai.workspace = workspace;\n"],"mappings":"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"}
+{"version":3,"file":"workspace.mjs","names":[],"sources":["../../../../../../../packages/ai-workspace/src/workspace.ts"],"sourcesContent":["import path from \"node:path\";\nimport { ai, type ToolContract } from \"@warlock.js/ai\";\nimport { createLocalBackend } from \"./backends/local\";\nimport { createMockBackend } from \"./backends/mock\";\nimport { WorkspacePolicyError } from \"./errors\";\nimport { createOps } from \"./ops\";\nimport { samePattern } from \"./policy/approval-helpers\";\nimport { classifyShellCommand } from \"./policy/shell-check\";\nimport { resolveShell, type ResolvedShell } from \"./policy/shell-interpreter\";\nimport { ShellJobs } from \"./shell-jobs\";\nimport { TodoStore } from \"./todos\";\nimport { applyPatchWithOps } from \"./patch/apply-patch-generic\";\nimport { makeApplyPatchTool } from \"./tools/apply-patch\";\nimport { makeEditFileTool } from \"./tools/edit-file\";\nimport { makeGlobTool } from \"./tools/glob\";\nimport { makeGrepTool } from \"./tools/grep\";\nimport { makeListDirTool } from \"./tools/list-dir\";\nimport { makeMultiEditTool } from \"./tools/multi-edit\";\nimport { makeReadFileTool } from \"./tools/read-file\";\nimport { makeRunShellTool } from \"./tools/run-shell\";\nimport { makeRunTestsTool } from \"./tools/run-tests\";\nimport { makeShellKillTool } from \"./tools/shell-kill\";\nimport { makeShellOutputTool } from \"./tools/shell-output\";\nimport { makeTodoReadTool, makeTodoWriteTool } from \"./tools/todo\";\nimport { makeWriteFileTool } from \"./tools/write-file\";\nimport type {\n  ApplyPatchInput,\n  ApplyPatchResult,\n  EditFileInput,\n  EditFileResult,\n  ExecOptions,\n  GrepResult,\n  ListDirOptions,\n  ListDirResult,\n  MultiEditInput,\n  MultiEditResult,\n  ReadFileResult,\n  RunShellResult,\n  ShellJobInfo,\n  ShellOutputOptions,\n  ShellOutputResult,\n  StartShellOptions,\n  TodoListResult,\n  Workspace,\n  WorkspaceBackend,\n  WorkspaceCommandPattern,\n  WorkspaceOps,\n  WorkspaceShellClassification,\n  WorkspacePolicy,\n  WorkspaceTodoInput,\n  WorkspaceToolName,\n  WorkspaceTools,\n} from \"./contracts\";\n\n/**\n * The full set of tool names a writable workspace vends, in a stable\n * canonical order so `tools.all()` is deterministic.\n */\nconst ALL_TOOL_NAMES: readonly WorkspaceToolName[] = [\n  \"readFile\",\n  \"editFile\",\n  \"multiEdit\",\n  \"applyPatch\",\n  \"writeFile\",\n  \"listDir\",\n  \"runShell\",\n  \"shellOutput\",\n  \"shellKill\",\n  \"runTests\",\n  \"grep\",\n  \"glob\",\n  \"todoWrite\",\n  \"todoRead\",\n];\n\n/**\n * The subset a {@link Workspace.readonly} projection exposes — the\n * tools that cannot change the tree. `editFile` / `multiEdit` /\n * `writeFile` / the shell tools / `runTests` are deliberately omitted so a\n * reviewer agent has no path to change it. The todo tools stay: they only\n * touch the in-memory plan.\n */\nconst READONLY_TOOL_NAMES: readonly WorkspaceToolName[] = [\n  \"readFile\",\n  \"listDir\",\n  \"grep\",\n  \"glob\",\n  \"todoWrite\",\n  \"todoRead\",\n];\n\n/** Tools vended only when the policy enables background commands. */\nconst BACKGROUND_TOOL_NAMES: ReadonlySet<WorkspaceToolName> = new Set([\"shellOutput\", \"shellKill\"]);\n\n/**\n * State one workspace shares with every projection made from it: its\n * background commands and its todo list.\n */\ninterface WorkspaceState {\n  jobs: ShellJobs;\n  todos: TodoStore;\n  /** Command patterns the host approved with `remember`. */\n  approvals: WorkspaceCommandPattern[];\n}\n\n/**\n * Choose the dumb IO executor for a policy. `\"mock\"` selects the\n * in-memory backend (hermetic tests); anything else — including the\n * `\"local\"` default and an absent `backend` — selects the real-disk\n * local backend.\n */\nfunction selectBackend(policy: WorkspacePolicy): WorkspaceBackend {\n  if (policy.backend === \"mock\") {\n    return createMockBackend();\n  }\n\n  return createLocalBackend();\n}\n\n/**\n * The internal {@link Workspace} implementation. Holds the resolved\n * backend, the policy, and the single shared {@link WorkspaceOps} seam\n * that both the agent-facing `.tools.*` factories and the human-facing\n * direct methods funnel through — one jail, one rule set, two callers.\n *\n * The `allowedTools` set narrows what `tools.*` will vend and which\n * mutating direct methods are permitted: a full workspace allows every\n * name; a {@link WorkspaceImpl.readonly} projection allows only the\n * read/grep/glob subset and rejects writes/edits/shell/mkdir/remove.\n *\n * Constructed via {@link workspace}; the class itself is internal.\n */\nclass WorkspaceImpl implements Workspace {\n  /** The shared, policy-enforced operation layer (jail + guards). */\n  private readonly ops: WorkspaceOps;\n\n  /** Tool names this projection is permitted to vend / mutate through. */\n  private readonly allowedTools: ReadonlySet<WorkspaceToolName>;\n\n  public readonly policy: WorkspacePolicy;\n\n  public readonly tools: WorkspaceTools;\n\n  public readonly shell: {\n    classify(line: string): WorkspaceShellClassification;\n    remembered(): readonly WorkspaceCommandPattern[];\n    forget(pattern: WorkspaceCommandPattern): boolean;\n  };\n\n  /** The shell the policy's interpreter resolves to on this host. */\n  private readonly resolvedShell: ResolvedShell;\n\n  /** Background commands + todo list, shared with projections. */\n  private readonly state: WorkspaceState;\n\n  public constructor(\n    policy: WorkspacePolicy,\n    allowedTools: readonly WorkspaceToolName[] = ALL_TOOL_NAMES,\n    state?: WorkspaceState,\n  ) {\n    this.policy = policy;\n    this.allowedTools = new Set(allowedTools);\n    this.state = state ?? { jobs: new ShellJobs(), todos: new TodoStore(), approvals: [] };\n    this.resolvedShell = resolveShell(policy.shell);\n    const approvals = this.state.approvals;\n\n    this.shell = {\n      classify: (line) => classifyShellCommand(line, policy),\n      remembered: () => [...approvals],\n      forget: (pattern) => {\n        const index = approvals.findIndex((entry) => samePattern(entry, pattern));\n\n        if (index === -1) {\n          return false;\n        }\n\n        approvals.splice(index, 1);\n\n        return true;\n      },\n    };\n\n    const backend = selectBackend(policy);\n    this.ops = createOps(backend, policy, {\n      jobs: this.state.jobs,\n      approvals: this.state.approvals,\n    });\n    this.tools = this.buildTools();\n  }\n\n  /**\n   * Assemble the agent-facing tool namespace. Each factory builds its\n   * tool over the shared `ops`; `all()` returns every *allowed* tool in\n   * canonical order and `pick(...)` returns the named subset (silently\n   * dropping any name this projection does not allow, so a `readonly()`\n   * workspace can never be coaxed into vending a mutating tool).\n   */\n  private buildTools(): WorkspaceTools {\n    // Each `make*Tool` returns a precisely-typed\n    // `ToolContract<SpecificInput, SpecificOutput>`, but the agent-facing\n    // `WorkspaceTools` surface vends the type-erased `ToolContract`\n    // (`ToolContract<unknown, unknown>`). Because `ToolContract` puts its\n    // input in a contravariant position (`execute(input)` / `action(input)`),\n    // a specific contract is not assignable to the erased one — so erase it\n    // once, here, through `unknown`. The runtime object is identical; only\n    // the static input type is widened for the shared surface.\n    const erase = <TInput, TOutput>(contract: ToolContract<TInput, TOutput>): ToolContract =>\n      contract as unknown as ToolContract;\n\n    const shell = this.policy.shell;\n    const background = shell?.background !== undefined;\n    const resolvedShell = this.resolvedShell;\n\n    const factories: Record<\n      WorkspaceToolName,\n      (opts?: { name?: string; command?: string }) => ToolContract\n    > = {\n      readFile: (opts) => erase(makeReadFileTool(this.ops, opts)),\n      editFile: (opts) => erase(makeEditFileTool(this.ops, opts)),\n      multiEdit: (opts) => erase(makeMultiEditTool(this.ops, opts)),\n      applyPatch: (opts) => erase(makeApplyPatchTool(this.ops, opts)),\n      writeFile: (opts) => erase(makeWriteFileTool(this.ops, opts)),\n      listDir: (opts) => erase(makeListDirTool(this.ops, opts)),\n      runShell: (opts) =>\n        erase(\n          makeRunShellTool(this.ops, {\n            ...(opts?.name !== undefined ? { name: opts.name } : {}),\n            ...(shell?.timeoutMs !== undefined ? { maxTimeoutMs: shell.timeoutMs } : {}),\n            background,\n            ...(resolvedShell.interpreter !== \"none\" ? { shellLabel: resolvedShell.label } : {}),\n            shellDialect: resolvedShell.interpreter === \"none\" ? \"none\" : resolvedShell.dialect,\n          }),\n        ),\n      shellOutput: (opts) => erase(makeShellOutputTool(this.ops, opts)),\n      shellKill: (opts) => erase(makeShellKillTool(this.ops, opts)),\n      runTests: (opts) =>\n        erase(\n          makeRunTestsTool(this.ops, {\n            ...opts,\n            interpreter: resolvedShell.interpreter,\n            dialect: resolvedShell.dialect,\n          }),\n        ),\n      grep: (opts) => erase(makeGrepTool(this.ops, opts)),\n      glob: (opts) => erase(makeGlobTool(this.ops, opts)),\n      todoWrite: (opts) => erase(makeTodoWriteTool(this.state.todos, opts)),\n      todoRead: (opts) => erase(makeTodoReadTool(this.state.todos, opts)),\n    };\n\n    const build = (name: WorkspaceToolName, opts?: { name?: string; command?: string }) =>\n      factories[name](opts);\n\n    // `shell_output` / `shell_kill` only mean something when background\n    // commands can be started, so `all()` leaves them out otherwise.\n    const vendedByAll = (name: WorkspaceToolName): boolean =>\n      this.allowedTools.has(name) && (background || !BACKGROUND_TOOL_NAMES.has(name));\n\n    return {\n      all: () => ALL_TOOL_NAMES.filter(vendedByAll).map((name) => build(name)),\n      pick: (...names: WorkspaceToolName[]) =>\n        names.filter((name) => this.allowedTools.has(name)).map((name) => build(name)),\n      readFile: (opts) => build(\"readFile\", opts),\n      editFile: (opts) => build(\"editFile\", opts),\n      multiEdit: (opts) => build(\"multiEdit\", opts),\n      applyPatch: (opts) => build(\"applyPatch\", opts),\n      writeFile: (opts) => build(\"writeFile\", opts),\n      listDir: (opts) => build(\"listDir\", opts),\n      runShell: (opts) => build(\"runShell\", opts),\n      shellOutput: (opts) => build(\"shellOutput\", opts),\n      shellKill: (opts) => build(\"shellKill\", opts),\n      runTests: (opts) => build(\"runTests\", opts),\n      grep: (opts) => build(\"grep\", opts),\n      glob: (opts) => build(\"glob\", opts),\n      todoWrite: (opts) => build(\"todoWrite\", opts),\n      todoRead: (opts) => build(\"todoRead\", opts),\n    };\n  }\n\n  /**\n   * Reject a mutating direct method on a read-only projection — surfaced\n   * as a {@link WorkspacePolicyError} (the same typed error a denied\n   * command produces) so a caller branches on `error.type`.\n   */\n  private assertWritable(operation: string): void {\n    if (this.allowedTools.has(\"writeFile\")) {\n      return;\n    }\n\n    throw new WorkspacePolicyError(\n      `Operation \"${operation}\" is not permitted on a read-only workspace.`,\n      { type: \"denied-command\", command: operation },\n    );\n  }\n\n  public readFile(\n    filePath: string,\n    opts?: { offset?: number; limit?: number },\n  ): Promise<ReadFileResult> {\n    return this.ops.readFile(filePath, opts);\n  }\n\n  public async writeFile(\n    filePath: string,\n    content: string,\n  ): Promise<{ hash: string; bytesWritten: number }> {\n    this.assertWritable(\"writeFile\");\n\n    return this.ops.writeFile(filePath, content);\n  }\n\n  public async editFile(input: EditFileInput): Promise<EditFileResult> {\n    this.assertWritable(\"editFile\");\n\n    return this.ops.editFile(input);\n  }\n\n  public async multiEdit(input: MultiEditInput): Promise<MultiEditResult> {\n    this.assertWritable(\"multiEdit\");\n\n    return this.ops.multiEdit(input);\n  }\n\n  public async applyPatch(input: ApplyPatchInput): Promise<ApplyPatchResult> {\n    this.assertWritable(\"applyPatch\");\n\n    return this.ops.applyPatch ? this.ops.applyPatch(input) : applyPatchWithOps(this.ops, input);\n  }\n\n  public listDir(dirPath?: string, opts?: ListDirOptions): Promise<ListDirResult> {\n    return this.ops.listDir(dirPath, opts);\n  }\n\n  public async exec(command: string, opts?: ExecOptions): Promise<RunShellResult> {\n    this.assertWritable(\"exec\");\n\n    return this.ops.exec(command, opts);\n  }\n\n  public async startShell(command: string, opts?: StartShellOptions): Promise<ShellJobInfo> {\n    this.assertWritable(\"startShell\");\n\n    return this.ops.startShell(command, opts);\n  }\n\n  public shellOutput(id: string, opts?: ShellOutputOptions): Promise<ShellOutputResult> {\n    return this.ops.shellOutput(id, opts);\n  }\n\n  public async shellKill(id: string): Promise<ShellJobInfo> {\n    this.assertWritable(\"shellKill\");\n\n    return this.ops.shellKill(id);\n  }\n\n  public listShells(): ShellJobInfo[] {\n    return this.ops.listShells();\n  }\n\n  public readTodos(): TodoListResult {\n    return this.state.todos.read();\n  }\n\n  public writeTodos(todos: WorkspaceTodoInput[]): TodoListResult {\n    return this.state.todos.write(todos);\n  }\n\n  public dispose(): Promise<void> {\n    return this.ops.dispose();\n  }\n\n  public grep(\n    pattern: string,\n    opts?: { glob?: string; ignoreCase?: boolean },\n  ): Promise<GrepResult> {\n    return this.ops.grep(pattern, opts);\n  }\n\n  public glob(pattern: string): Promise<string[]> {\n    return this.ops.glob(pattern);\n  }\n\n  public exists(filePath: string): Promise<boolean> {\n    return this.ops.exists(filePath);\n  }\n\n  public async mkdir(filePath: string): Promise<void> {\n    this.assertWritable(\"mkdir\");\n\n    return this.ops.mkdir(filePath);\n  }\n\n  public async remove(filePath: string): Promise<void> {\n    this.assertWritable(\"remove\");\n\n    return this.ops.remove(filePath);\n  }\n\n  /**\n   * A read-only projection over the SAME policy — only the read / list /\n   * grep / glob / todo tools are vended and every mutating direct method\n   * rejects with a {@link WorkspacePolicyError}. A fresh ops/backend is\n   * built from the identical policy, so the projection sees the same jailed\n   * tree; it shares this workspace's background commands and todo list.\n   */\n  public readonly(): Workspace {\n    return new WorkspaceImpl(\n      this.policy,\n      READONLY_TOOL_NAMES.filter((name) => this.allowedTools.has(name)),\n      this.state,\n    );\n  }\n\n  /**\n   * A sub-jailed view rooted at `subdir` (relative to this workspace's\n   * `cwd`). Returns a brand-new workspace whose policy is this policy\n   * with `cwd` narrowed to `join(cwd, subdir)` — same backend selection,\n   * same allow/deny/shell/read sub-policies, but a tighter jail root. It\n   * shares this workspace's background commands and todo list.\n   */\n  public scope(subdir: string): Workspace {\n    return new WorkspaceImpl(\n      { ...this.policy, cwd: path.join(this.policy.cwd, subdir) },\n      [...this.allowedTools],\n      this.state,\n    );\n  }\n}\n\n/**\n * Build a {@link Workspace} — the integrator that wires a\n * {@link WorkspacePolicy} to a backend, the shared policy-enforced ops\n * layer, and the agent-facing tool factories.\n *\n * The backend is chosen from `policy.backend`: `\"mock\"` runs in memory\n * (hermetic tests); the `\"local\"` default (and any absent value) runs\n * over the real disk via `@warlock.js/fs` + `node:child_process`. The\n * returned workspace exposes:\n *\n * - **`tools.*`** — `readFile` / `editFile` / `multiEdit` / `writeFile` /\n *   `listDir` / `runShell` / `shellOutput` / `shellKill` / `runTests` /\n *   `grep` / `glob` / `todoWrite` / `todoRead`, plus `all()` (every tool)\n *   and `pick(...)` (a least-privilege subset).\n * - **direct methods** — `readFile` / `writeFile` / `editFile` /\n *   `multiEdit` / `listDir` / `exec` / `startShell` / `shellOutput` /\n *   `shellKill` / `listShells` / `grep` / `glob` / `exists` / `mkdir` /\n *   `remove` / `readTodos` / `writeTodos`, each delegating to the shared\n *   ops layer, and `dispose()`.\n * - **`readonly()`** — a projection that vends only the read-side tools and\n *   rejects every mutating direct method.\n * - **`scope(subdir)`** — a sub-jailed workspace rooted at `subdir`.\n *\n * Available at runtime as `ai.workspace(policy)` once this module is\n * imported (it registers the verb on the shared `ai` object).\n *\n * @param policy - The policy bounding the workspace (its `cwd` is the jail root).\n * @returns A fully-wired {@link Workspace}.\n *\n * @example\n * const ws = workspace({ cwd: \"/srv/acme-api\", shell: { allow: [\"npm\"], inheritEnv: [\"PATH\"] } });\n * const dev = ai.agent({ model, tools: ws.tools.all() });\n * await dev.execute(\"Make the failing cart-total suite green.\");\n *\n * @example\n * // Least-privilege reviewer — no write, no shell.\n * const reviewer = ai.agent({ model, tools: ws.readonly().tools.all() });\n */\nexport function workspace(policy: WorkspacePolicy): Workspace {\n  return new WorkspaceImpl(policy);\n}\n\n/**\n * Attach the `workspace` verb to the `ai` namespace via module augmentation,\n * per the `ai.`-namespace convention. `@warlock.js/ai` now exposes a named `Ai`\n * interface for exactly this, so after a bare `import \"@warlock.js/ai-workspace\"`,\n * `ai.workspace(...)` is globally typed — no view/cast needed.\n */\ndeclare module \"@warlock.js/ai\" {\n  interface Ai {\n    /** Build a policy-jailed filesystem + shell {@link Workspace}. */\n    workspace(policy: WorkspacePolicy): Workspace;\n  }\n}\n\n// Runtime registration: attach `workspace` onto the shared `ai` object the\n// moment this package is imported (the augmentation above types it).\nai.workspace = workspace;\n"],"mappings":"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"}

package/llms-full.txt

@@ -168,22 +168,22 @@ Paths are resolved against `cwd` with symlinks collapsed and accepted inside `cw
 
 ## The policy surface
 
-| Field                                               | What it does                                                                                                                                                                                                                                                                                            |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cwd`                                               | **Absolute** jail root. Every path resolves against it and must stay inside.                                                                                                                                                                                                                            |
-| `allowPaths`                                        | Extra readable roots outside `cwd`.                                                                                                                                                                                                                                                                     |
-| `denyPaths`                                         | Globs (`*`, `**`, `?`) blocked **even inside `cwd`** — e.g. `[".git/**", ".env*"]`. A bare dir name (`"node_modules"`) also blocks its contents.                                                                                                                                                        |
-| `shell.allow` / `shell.deny`                        | Executable **basenames** matched against every command's argv (after tokenizing — see below). **Deny wins**, case-insensitively. An `allow` list is exhaustive (fail-closed); no `shell` block at all ⇒ nothing may run.                                                                                |
-| `shell.denyPatterns` / `shell.allowCommand`         | Argument rules on every command: string prefix patterns (`"git push --force"`) or RegExps, and a predicate `(argv, ctx) => true \| false \| "why"`.                                                                                                                                                     |
-| `shell.interpreter`                                 | `"none"` (default, argv), `"sh"`, `"bash"`, `"powershell"`, `"cmd"` or `"auto"` (opt-in shell syntax, every command checked); `shell.interpreterPath` sets the shell executable.                                                                                                                        |
-| `shell.rules` / `shell.onAsk`                       | Ordered `{ match, effect: "allow" \| "ask" \| "deny", reason? }` rules (last match wins, a deny anywhere refuses the line); `onAsk({ command, asks, signal })` returns `{ allow, remember? }`. Refusals: `"approval-required"`, `"approval-denied"`. `ws.shell.classify(line)` lists a line's commands. |
-| `shell.background`                                  | `{ maxJobs?, timeoutMs? }` — enables background commands. Absent ⇒ refused.                                                                                                                                                                                                                             |
-| `list.ignore` / `list.maxDepth` / `list.maxEntries` | `list_dir` bounds: hidden globs (default `node_modules`, `.git`), depth cap (5), entry cap (500).                                                                                                                                                                                                       |
-| `shell.inheritEnv`                                  | Opt-in `process.env` keys to pass through (e.g. `["PATH"]`). **Nothing leaks in otherwise** — a command can't find `node`/`npm` without `PATH`.                                                                                                                                                         |
-| `shell.env`                                         | Explicit env vars injected into every spawned process (override inherited on collision).                                                                                                                                                                                                                |
-| `shell.timeoutMs` / `shell.maxOutputBytes`          | Per-command wall-clock cap (process tree SIGKILLed on expiry) and stdout/stderr byte cap (clipped on a character boundary).                                                                                                                                                                             |
-| `read.defaultLines` / `read.maxBytes`               | Default read window + a ceiling on the UTF-8 bytes of the returned `content` (line numbers included). See [Read windows and the byte ceiling](#read-windows-and-the-byte-ceiling).                                                                                                                      |
-| `backend`                                           | `"local"` (default — real disk) or `"mock"` (in-memory, for tests).                                                                                                                                                                                                                                     |
+| Field                                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`                                               | **Absolute** jail root. Every path resolves against it and must stay inside.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `allowPaths`                                        | Extra readable roots outside `cwd`.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `denyPaths`                                         | Globs (`*`, `**`, `?`) blocked **even inside `cwd`** — e.g. `[".git/**", ".env*"]`. A bare dir name (`"node_modules"`) also blocks its contents.                                                                                                                                                                                                                                                                                                                                               |
+| `shell.allow` / `shell.deny`                        | Executable **basenames** matched against every command's argv (after tokenizing — see below). **Deny wins**, case-insensitively. An `allow` list is exhaustive (fail-closed); no `shell` block at all ⇒ nothing may run.                                                                                                                                                                                                                                                                       |
+| `shell.denyPatterns` / `shell.allowCommand`         | Argument rules on every command: string prefix patterns (`"git push --force"`) or RegExps, and a predicate `(argv, ctx) => true \| false \| "why"`.                                                                                                                                                                                                                                                                                                                                            |
+| `shell.interpreter`                                 | `"none"` (default, argv), `"sh"`, `"bash"`, `"powershell"`, `"cmd"` or `"auto"` (opt-in shell syntax, every command checked); `shell.interpreterPath` sets the shell executable.                                                                                                                                                                                                                                                                                                               |
+| `shell.rules` / `shell.onAsk`                       | Ordered `{ match, effect: "allow" \| "ask" \| "deny", reason? }` rules (last match wins, a deny anywhere refuses the line); `onAsk({ command, asks, signal })` returns `{ allow, remember? }`. Refusals: `"approval-required"`, `"approval-denied"`. `ws.shell.classify(line)` lists a line's commands. `remember` takes one pattern or an array and `reason` (≤ 500 chars) reaches the model in the refusal; `ws.shell.remembered()` / `forget(pattern)` list and remove remembered patterns. |
+| `shell.background`                                  | `{ maxJobs?, timeoutMs? }` — enables background commands. Absent ⇒ refused.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `list.ignore` / `list.maxDepth` / `list.maxEntries` | `list_dir` bounds: hidden globs (default `node_modules`, `.git`), depth cap (5), entry cap (500).                                                                                                                                                                                                                                                                                                                                                                                              |
+| `shell.inheritEnv`                                  | Opt-in `process.env` keys to pass through (e.g. `["PATH"]`). **Nothing leaks in otherwise** — a command can't find `node`/`npm` without `PATH`.                                                                                                                                                                                                                                                                                                                                                |
+| `shell.env`                                         | Explicit env vars injected into every spawned process (override inherited on collision).                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `shell.timeoutMs` / `shell.maxOutputBytes`          | Per-command wall-clock cap (process tree SIGKILLed on expiry) and stdout/stderr byte cap (clipped on a character boundary).                                                                                                                                                                                                                                                                                                                                                                    |
+| `read.defaultLines` / `read.maxBytes`               | Default read window + a ceiling on the UTF-8 bytes of the returned `content` (line numbers included). See [Read windows and the byte ceiling](#read-windows-and-the-byte-ceiling).                                                                                                                                                                                                                                                                                                             |
+| `backend`                                           | `"local"` (default — real disk) or `"mock"` (in-memory, for tests).                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 > **The most common gotcha:** `run_shell` fails to find `node`/`npm` because the env is empty. Add `shell: { allow: ["npm", "node"], inheritEnv: ["PATH"] }`.
 
@@ -236,7 +236,7 @@ export async function commitWork(cwd: string) {
 
 - Shell mode parses the line and checks every simple command — inside `;`, `&&`, `||`, pipes, `( )`, `$( )`, backticks, here-documents and `NAME=value cmd` prefixes. Redirection targets and `cd` directories must be literal paths inside the jail (`/dev/null` is fine), re-checked with symlinks resolved.
 - It refuses what it can't parse with confidence (`reason: "unsupported-syntax"`): compound commands, arithmetic, brace expansion, unusual `${…}` forms, bash-only redirections, a command name decided at run time, `&` in a line (use `background: true`), assignments to `IFS`/`PS4`/`CDPATH`/`BASH_ENV`…; it drops shell start-up variables (`ENV`, `BASH_ENV`, `SHELLOPTS`, `BASH_FUNC_*`, …) from the environment.
-- `reason` values: `"metacharacter"`, `"unbalanced-quotes"`, `"denied-executable"`, `"not-allowed"`, `"denied-pattern"`, `"nested-command"`, `"unsupported-syntax"`, `"path-escape"`. `checkShellCommand(policy, line)` returns the verdict without running anything; `classifyShellCommand(line, policy?)` returns `{ commands, opaque? }` with the same parser a host approval gate can reuse; `resolveShell(policy.shell)` reports which interpreter and executable `"auto"` (or a named interpreter) resolves to on this host.
+- `reason` values: `"metacharacter"`, `"unbalanced-quotes"`, `"denied-executable"`, `"not-allowed"`, `"denied-pattern"`, `"nested-command"`, `"unsupported-syntax"`, `"path-escape"`. `checkShellCommand(policy, line)` returns the verdict without running anything; `classifyShellCommand(line, policy?)` returns `{ commands, opaque? }` with the same parser a host approval gate can reuse; `resolveShell(policy.shell)` reports which interpreter and executable `"auto"` (or a named interpreter) resolves to on this host, plus the PowerShell `edition` (`"desktop"` = Windows PowerShell 5.1, `"core"` = 7+) and `version`; the 5.1 dialect (`"powershell5"`) refuses `&&` / `||`, and on Windows `"auto"` prefers `pwsh`, then Git Bash, then 5.1, then `cmd`. The `PowerShellEdition` type is exported.
 - Pair shell mode with an exhaustive `allow`: `deny` alone is a best-effort filter.
 
 ## Two callers, one jail
@@ -310,6 +310,12 @@ export async function devLoop(cwd: string) {
 }
 ```
 
+- Result shapes when output is cut or spilled (`output.spillDir`): every result that spilled carries a flat `spilledTo?: string[]` (absolute paths) beside `truncated` and `truncation`, and its text ends with the marker line naming the file.
+  - `run_shell` → `{ exitCode, stdout, stderr, truncated, timedOut, cancelled, truncation?: { stdout?, stderr? }, spilledTo? }`; one path per spilled stream.
+  - `shell_output` → the fields above under Background, plus `truncation?: { stdout?, stderr? }` and `spilledTo?`.
+  - `read_file` → `{ content, ..., truncated, bytesCapped, truncation?, spilledTo? }`; spills only when `read.maxBytes` cut the window.
+  - `grep` → `{ matches, total, truncated?, truncation?, spilledTo? }`; `glob` → `{ paths, truncated?, truncation?, spilledTo? }`.
+  - `truncation` is `{ shown: { lines }, total: { lines, bytes }, path? }`; without `spillDir` there is no `path` and no `spilledTo`.
 - `list_dir({ path?, depth?, ignore? })` → `{ path, entries: [{ path, type, size?, depth }], truncated }`; `denyPaths` always hidden, `list.ignore` (default `node_modules`, `.git`) hidden from listings, symlinks reported but never followed.
 - `apply_patch({ patch, dryRun? })` → `{ files: [{ path, action, oldPath?, hunks, hash? }], dryRun }`; a unified diff that modifies, creates, deletes and renames files, all or none; paths jailed, hunks matched by context, line endings kept, binary files refused (`binary-file`); `dryRun` checks only. Not in `readonly()`.
 - `multi_edit({ path, edits, expectHash? })` → `{ path, edits, replacements, hash }`; same uniqueness rules as `edit_file`, at most 100 edits.

package/package.json

@@ -19,13 +19,13 @@
     "directory": "packages/ai-workspace"
   },
   "peerDependencies": {
-    "@warlock.js/ai": "5.44.0"
+    "@warlock.js/ai": "5.46.0"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@warlock.js/fs": "5.44.0"
+    "@warlock.js/fs": "5.46.0"
   },
-  "version": "5.44.0",
+  "version": "5.46.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/use-a-workspace/SKILL.md

@@ -30,22 +30,22 @@ Paths are resolved against `cwd` with symlinks collapsed and accepted inside `cw
 
 ## The policy surface
 
-| Field                                               | What it does                                                                                                                                                                                                                                                                                            |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cwd`                                               | **Absolute** jail root. Every path resolves against it and must stay inside.                                                                                                                                                                                                                            |
-| `allowPaths`                                        | Extra readable roots outside `cwd`.                                                                                                                                                                                                                                                                     |
-| `denyPaths`                                         | Globs (`*`, `**`, `?`) blocked **even inside `cwd`** — e.g. `[".git/**", ".env*"]`. A bare dir name (`"node_modules"`) also blocks its contents.                                                                                                                                                        |
-| `shell.allow` / `shell.deny`                        | Executable **basenames** matched against every command's argv (after tokenizing — see below). **Deny wins**, case-insensitively. An `allow` list is exhaustive (fail-closed); no `shell` block at all ⇒ nothing may run.                                                                                |
-| `shell.denyPatterns` / `shell.allowCommand`         | Argument rules on every command: string prefix patterns (`"git push --force"`) or RegExps, and a predicate `(argv, ctx) => true \| false \| "why"`.                                                                                                                                                     |
-| `shell.interpreter`                                 | `"none"` (default, argv), `"sh"`, `"bash"`, `"powershell"`, `"cmd"` or `"auto"` (opt-in shell syntax, every command checked); `shell.interpreterPath` sets the shell executable.                                                                                                                        |
-| `shell.rules` / `shell.onAsk`                       | Ordered `{ match, effect: "allow" \| "ask" \| "deny", reason? }` rules (last match wins, a deny anywhere refuses the line); `onAsk({ command, asks, signal })` returns `{ allow, remember? }`. Refusals: `"approval-required"`, `"approval-denied"`. `ws.shell.classify(line)` lists a line's commands. |
-| `shell.background`                                  | `{ maxJobs?, timeoutMs? }` — enables background commands. Absent ⇒ refused.                                                                                                                                                                                                                             |
-| `list.ignore` / `list.maxDepth` / `list.maxEntries` | `list_dir` bounds: hidden globs (default `node_modules`, `.git`), depth cap (5), entry cap (500).                                                                                                                                                                                                       |
-| `shell.inheritEnv`                                  | Opt-in `process.env` keys to pass through (e.g. `["PATH"]`). **Nothing leaks in otherwise** — a command can't find `node`/`npm` without `PATH`.                                                                                                                                                         |
-| `shell.env`                                         | Explicit env vars injected into every spawned process (override inherited on collision).                                                                                                                                                                                                                |
-| `shell.timeoutMs` / `shell.maxOutputBytes`          | Per-command wall-clock cap (process tree SIGKILLed on expiry) and stdout/stderr byte cap (clipped on a character boundary).                                                                                                                                                                             |
-| `read.defaultLines` / `read.maxBytes`               | Default read window + a ceiling on the UTF-8 bytes of the returned `content` (line numbers included). See [Read windows and the byte ceiling](#read-windows-and-the-byte-ceiling).                                                                                                                      |
-| `backend`                                           | `"local"` (default — real disk) or `"mock"` (in-memory, for tests).                                                                                                                                                                                                                                     |
+| Field                                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`                                               | **Absolute** jail root. Every path resolves against it and must stay inside.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `allowPaths`                                        | Extra readable roots outside `cwd`.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `denyPaths`                                         | Globs (`*`, `**`, `?`) blocked **even inside `cwd`** — e.g. `[".git/**", ".env*"]`. A bare dir name (`"node_modules"`) also blocks its contents.                                                                                                                                                                                                                                                                                                                                               |
+| `shell.allow` / `shell.deny`                        | Executable **basenames** matched against every command's argv (after tokenizing — see below). **Deny wins**, case-insensitively. An `allow` list is exhaustive (fail-closed); no `shell` block at all ⇒ nothing may run.                                                                                                                                                                                                                                                                       |
+| `shell.denyPatterns` / `shell.allowCommand`         | Argument rules on every command: string prefix patterns (`"git push --force"`) or RegExps, and a predicate `(argv, ctx) => true \| false \| "why"`.                                                                                                                                                                                                                                                                                                                                            |
+| `shell.interpreter`                                 | `"none"` (default, argv), `"sh"`, `"bash"`, `"powershell"`, `"cmd"` or `"auto"` (opt-in shell syntax, every command checked); `shell.interpreterPath` sets the shell executable.                                                                                                                                                                                                                                                                                                               |
+| `shell.rules` / `shell.onAsk`                       | Ordered `{ match, effect: "allow" \| "ask" \| "deny", reason? }` rules (last match wins, a deny anywhere refuses the line); `onAsk({ command, asks, signal })` returns `{ allow, remember? }`. Refusals: `"approval-required"`, `"approval-denied"`. `ws.shell.classify(line)` lists a line's commands. `remember` takes one pattern or an array and `reason` (≤ 500 chars) reaches the model in the refusal; `ws.shell.remembered()` / `forget(pattern)` list and remove remembered patterns. |
+| `shell.background`                                  | `{ maxJobs?, timeoutMs? }` — enables background commands. Absent ⇒ refused.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `list.ignore` / `list.maxDepth` / `list.maxEntries` | `list_dir` bounds: hidden globs (default `node_modules`, `.git`), depth cap (5), entry cap (500).                                                                                                                                                                                                                                                                                                                                                                                              |
+| `shell.inheritEnv`                                  | Opt-in `process.env` keys to pass through (e.g. `["PATH"]`). **Nothing leaks in otherwise** — a command can't find `node`/`npm` without `PATH`.                                                                                                                                                                                                                                                                                                                                                |
+| `shell.env`                                         | Explicit env vars injected into every spawned process (override inherited on collision).                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `shell.timeoutMs` / `shell.maxOutputBytes`          | Per-command wall-clock cap (process tree SIGKILLed on expiry) and stdout/stderr byte cap (clipped on a character boundary).                                                                                                                                                                                                                                                                                                                                                                    |
+| `read.defaultLines` / `read.maxBytes`               | Default read window + a ceiling on the UTF-8 bytes of the returned `content` (line numbers included). See [Read windows and the byte ceiling](#read-windows-and-the-byte-ceiling).                                                                                                                                                                                                                                                                                                             |
+| `backend`                                           | `"local"` (default — real disk) or `"mock"` (in-memory, for tests).                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 > **The most common gotcha:** `run_shell` fails to find `node`/`npm` because the env is empty. Add `shell: { allow: ["npm", "node"], inheritEnv: ["PATH"] }`.
 
@@ -98,7 +98,7 @@ export async function commitWork(cwd: string) {
 
 - Shell mode parses the line and checks every simple command — inside `;`, `&&`, `||`, pipes, `( )`, `$( )`, backticks, here-documents and `NAME=value cmd` prefixes. Redirection targets and `cd` directories must be literal paths inside the jail (`/dev/null` is fine), re-checked with symlinks resolved.
 - It refuses what it can't parse with confidence (`reason: "unsupported-syntax"`): compound commands, arithmetic, brace expansion, unusual `${…}` forms, bash-only redirections, a command name decided at run time, `&` in a line (use `background: true`), assignments to `IFS`/`PS4`/`CDPATH`/`BASH_ENV`…; it drops shell start-up variables (`ENV`, `BASH_ENV`, `SHELLOPTS`, `BASH_FUNC_*`, …) from the environment.
-- `reason` values: `"metacharacter"`, `"unbalanced-quotes"`, `"denied-executable"`, `"not-allowed"`, `"denied-pattern"`, `"nested-command"`, `"unsupported-syntax"`, `"path-escape"`. `checkShellCommand(policy, line)` returns the verdict without running anything; `classifyShellCommand(line, policy?)` returns `{ commands, opaque? }` with the same parser a host approval gate can reuse; `resolveShell(policy.shell)` reports which interpreter and executable `"auto"` (or a named interpreter) resolves to on this host.
+- `reason` values: `"metacharacter"`, `"unbalanced-quotes"`, `"denied-executable"`, `"not-allowed"`, `"denied-pattern"`, `"nested-command"`, `"unsupported-syntax"`, `"path-escape"`. `checkShellCommand(policy, line)` returns the verdict without running anything; `classifyShellCommand(line, policy?)` returns `{ commands, opaque? }` with the same parser a host approval gate can reuse; `resolveShell(policy.shell)` reports which interpreter and executable `"auto"` (or a named interpreter) resolves to on this host, plus the PowerShell `edition` (`"desktop"` = Windows PowerShell 5.1, `"core"` = 7+) and `version`; the 5.1 dialect (`"powershell5"`) refuses `&&` / `||`, and on Windows `"auto"` prefers `pwsh`, then Git Bash, then 5.1, then `cmd`. The `PowerShellEdition` type is exported.
 - Pair shell mode with an exhaustive `allow`: `deny` alone is a best-effort filter.
 
 ## Two callers, one jail
@@ -172,6 +172,12 @@ export async function devLoop(cwd: string) {
 }
 ```
 
+- Result shapes when output is cut or spilled (`output.spillDir`): every result that spilled carries a flat `spilledTo?: string[]` (absolute paths) beside `truncated` and `truncation`, and its text ends with the marker line naming the file.
+  - `run_shell` → `{ exitCode, stdout, stderr, truncated, timedOut, cancelled, truncation?: { stdout?, stderr? }, spilledTo? }`; one path per spilled stream.
+  - `shell_output` → the fields above under Background, plus `truncation?: { stdout?, stderr? }` and `spilledTo?`.
+  - `read_file` → `{ content, ..., truncated, bytesCapped, truncation?, spilledTo? }`; spills only when `read.maxBytes` cut the window.
+  - `grep` → `{ matches, total, truncated?, truncation?, spilledTo? }`; `glob` → `{ paths, truncated?, truncation?, spilledTo? }`.
+  - `truncation` is `{ shown: { lines }, total: { lines, bytes }, path? }`; without `spillDir` there is no `path` and no `spilledTo`.
 - `list_dir({ path?, depth?, ignore? })` → `{ path, entries: [{ path, type, size?, depth }], truncated }`; `denyPaths` always hidden, `list.ignore` (default `node_modules`, `.git`) hidden from listings, symlinks reported but never followed.
 - `apply_patch({ patch, dryRun? })` → `{ files: [{ path, action, oldPath?, hunks, hash? }], dryRun }`; a unified diff that modifies, creates, deletes and renames files, all or none; paths jailed, hunks matched by context, line endings kept, binary files refused (`binary-file`); `dryRun` checks only. Not in `readonly()`.
 - `multi_edit({ path, edits, expectHash? })` → `{ path, edits, replacements, hash }`; same uniqueness rules as `edit_file`, at most 100 edits.