@warlock.js/ai-workspace 5.43.0 → 5.45.0

package/esm/tools/run-shell.mjs

@@ -40,6 +40,24 @@ function runShellInputSchema(background) {
 		}
 	} }, runShellJsonSchema(background));
 }
+const DIALECT_RULES = {
+	posix: "Use POSIX shell syntax: `;`, `&&`, `||`, pipes, quotes, `$( )` and redirections are supported, and every command in the line is checked. Compound statements (`if`, `for`), brace expansion, arithmetic and `&` are not.",
+	cmd: "Use cmd.exe syntax: `&&`, `||`, `&`, `|` and simple redirections are supported, and every command in the line is checked. `%` and `!` expansion, `^`, parentheses and `if` / `for` are not.",
+	powershell: "Use PowerShell syntax: `;`, `&&`, `||`, pipes, `$( )`, the call operator `&` and the redirections `>`, `>>`, `2>` and `2>&1` are supported, and every command in the line is checked (aliases such as `rm` and `Remove-Item` are treated alike). Script blocks, `Invoke-Expression`, here-strings, splatting and `if` / `foreach` are not.",
+	powershell5: "Use Windows PowerShell 5.1 syntax: `;`, pipes, `$( )`, the call operator `&` and the redirections `>`, `>>`, `2>` and `2>&1` are supported, and every command in the line is checked (aliases such as `rm` and `Remove-Item` are treated alike). This version cannot chain with `&&` or `||`: put one command per call, or join with `;` (which runs the next command whatever the exit code). Script blocks, `Invoke-Expression`, here-strings, splatting and `if` / `foreach` are not supported."
+};
+const PLATFORM_NAMES = {
+	win32: "Windows",
+	darwin: "macOS",
+	linux: "Linux"
+};
+/** The sentence that names the shell and its syntax, or `""` in argv mode. */
+function shellSentence(options) {
+	const dialect = options?.shellDialect;
+	if (options?.shellLabel === void 0 || dialect === void 0 || dialect === "none") return "";
+	const platform = options.platform ?? process.platform;
+	return ` Commands run on ${PLATFORM_NAMES[platform] ?? platform} using ${options.shellLabel}. ` + DIALECT_RULES[dialect];
+}
 /** The lower of the model's timeout and the cap (either may be absent). */
 function cappedTimeout(requested, cap) {
 	if (requested === void 0) return cap;
@@ -49,7 +67,7 @@ function makeRunShellTool(ops, options) {
 	const background = options?.background === true;
 	return tool({
 		name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,
-		description: "Run a shell command inside the workspace. Every command in it must be permitted by the shell policy; a refusal explains how to fix the command. Output is byte-capped and the run is time-limited. A non-zero exit code is returned as data, not an error." + (background ? " Pass background: true for a long-running command (dev server, watcher): it returns an id at once; read its output with shell_output and stop it with shell_kill." : ""),
+		description: "Run a shell command inside the workspace. Every command in it must be permitted by the shell policy; a refusal explains how to fix the command. Output is byte-capped and the run is time-limited. A non-zero exit code is returned as data, not an error." + shellSentence(options) + (background ? " Pass background: true for a long-running command (dev server, watcher): it returns an id at once; read its output with shell_output and stop it with shell_kill." : ""),
 		action: (input) => `Running \`${input.command}\``,
 		input: runShellInputSchema(background),
 		execute: async (input, ctx) => {

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

@@ -1 +1 @@
-{"version":3,"file":"run-shell.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-shell.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { WorkspacePolicyError } from \"../errors\";\nimport type {\n  RunShellBackgroundResult,\n  RunShellInput,\n  RunShellResult,\n  WorkspaceOps,\n} from \"../contracts\";\nimport { runShellJsonSchema } from \"./json-schemas\";\nimport { withJsonSchema } from \"./schema\";\n\n/** The default tool name `run_shell` is exposed to the LLM under. */\nconst DEFAULT_RUN_SHELL_TOOL_NAME = \"run_shell\";\n\n/**\n * Hand-rolled Standard Schema for {@link RunShellInput}. We validate the\n * model's arguments without a runtime schema dependency: `command` must be\n * a non-empty string, `timeoutMs` (when present) a positive number and\n * `background` (when present) a boolean. Invalid args surface as a\n * `SchemaValidationError` in the tool result's `error` field rather than\n * reaching `ops.exec`.\n */\nfunction runShellInputSchema(background: boolean): StandardSchemaV1<RunShellInput> {\n  const schema: StandardSchemaV1<RunShellInput> = {\n    \"~standard\": {\n      version: 1,\n      vendor: \"@warlock.js/ai-workspace\",\n      validate: (value) => {\n        if (typeof value !== \"object\" || value === null) {\n          return { issues: [{ message: \"expected an object\" }] };\n        }\n\n        const candidate = value as Record<string, unknown>;\n\n        if (typeof candidate.command !== \"string\" || candidate.command.length === 0) {\n          return {\n            issues: [{ message: \"command must be a non-empty string\", path: [\"command\"] }],\n          };\n        }\n\n        if (\n          candidate.timeoutMs !== undefined &&\n          (typeof candidate.timeoutMs !== \"number\" || candidate.timeoutMs <= 0)\n        ) {\n          return {\n            issues: [{ message: \"timeoutMs must be a positive number\", path: [\"timeoutMs\"] }],\n          };\n        }\n\n        if (candidate.background !== undefined && typeof candidate.background !== \"boolean\") {\n          return {\n            issues: [{ message: \"background must be a boolean\", path: [\"background\"] }],\n          };\n        }\n\n        const result: RunShellInput = { command: candidate.command };\n\n        if (typeof candidate.timeoutMs === \"number\") {\n          result.timeoutMs = candidate.timeoutMs;\n        }\n\n        if (candidate.background === true) {\n          result.background = true;\n        }\n\n        return { value: result };\n      },\n    },\n  };\n\n  return withJsonSchema(schema, runShellJsonSchema(background));\n}\n\n/** Options for {@link makeRunShellTool}. */\nexport interface MakeRunShellToolOptions {\n  /** Override the tool name exposed to the LLM (default `\"run_shell\"`). */\n  name?: string;\n  /**\n   * Upper bound for a model-supplied `timeoutMs` on a foreground command —\n   * the model can lower the timeout, never raise it past this. The\n   * workspace passes its `shell.timeoutMs`.\n   */\n  maxTimeoutMs?: number;\n  /**\n   * Accept `background: true` and start the command as a background job\n   * (`ops.startShell`), returning a {@link RunShellBackgroundResult}. The\n   * workspace sets it when the policy has `shell.background`. Default\n   * `false`: a background request is refused.\n   */\n  background?: boolean;\n}\n\n/** The lower of the model's timeout and the cap (either may be absent). */\nfunction cappedTimeout(requested: number | undefined, cap: number | undefined): number | undefined {\n  if (requested === undefined) {\n    return cap;\n  }\n\n  return cap === undefined ? requested : Math.min(requested, cap);\n}\n\n/**\n * Build the `run_shell` tool — a {@link ToolContract} that runs a command\n * line through the policy-enforced {@link WorkspaceOps} layer.\n *\n * Every command in the line is checked against the shell policy by\n * `ops.exec`; a refused line throws a `WorkspacePolicyError` (with a\n * `reason` and a message that says how to fix the command) which the\n * `tool()` runtime catches and surfaces in the result's `error` field\n * (never a thrown run-killer), so the agent reads the refusal as tool data\n * and self-corrects. A command that runs but exits non-zero is *not* an\n * error — its `exitCode`/`stderr` come back in `data` for the agent to\n * inspect.\n *\n * The agent run's cancellation `signal` (from the dispatch `ctx`) is passed\n * to `ops.exec` per invocation: a cancelled run never starts the command,\n * and one cancelled mid-command kills its process tree (`cancelled: true`).\n * A background command (`background: true`, when enabled) belongs to the\n * workspace instead and keeps running after the call returns.\n *\n * @param ops - The policy-enforced operation layer to delegate `exec` to.\n * @param options - Tool-name override, timeout cap and background support.\n *\n * @example\n * const runShell = makeRunShellTool(ops);\n * const { data, error } = await runShell.invoke({ command: \"npm run build\" });\n * if (error) handleDenied(error);\n * else console.log(data.exitCode, data.stdout);\n */\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions & { background?: false },\n): ToolContract<RunShellInput, RunShellResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options: MakeRunShellToolOptions & { background: true },\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions,\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions,\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult> {\n  const background = options?.background === true;\n\n  return tool<RunShellInput, RunShellResult | RunShellBackgroundResult>({\n    name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,\n    description:\n      \"Run a shell command inside the workspace. Every command in it must be \" +\n      \"permitted by the shell policy; a refusal explains how to fix the \" +\n      \"command. Output is byte-capped and the run is time-limited. A \" +\n      \"non-zero exit code is returned as data, not an error.\" +\n      (background\n        ? \" Pass background: true for a long-running command (dev server, \" +\n          \"watcher): it returns an id at once; read its output with \" +\n          \"shell_output and stop it with shell_kill.\"\n        : \"\"),\n    action: (input) => `Running \\`${input.command}\\``,\n    input: runShellInputSchema(background),\n    // The run's signal belongs to this one invocation: it is read from the\n    // dispatch ctx on every call and never stored on the tool or workspace.\n    execute: async (input, ctx) => {\n      if (input.background === true) {\n        if (!background) {\n          throw new WorkspacePolicyError(\n            \"Background commands are not enabled for this workspace; run the command without background.\",\n            { type: \"denied-command\", reason: \"not-allowed\", command: input.command },\n          );\n        }\n\n        const job = await ops.startShell(\n          input.command,\n          input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : undefined,\n        );\n\n        return { ...job, background: true };\n      }\n\n      const timeoutMs = cappedTimeout(input.timeoutMs, options?.maxTimeoutMs);\n\n      return ops.exec(input.command, {\n        ...(timeoutMs !== undefined ? { timeoutMs } : {}),\n        ...(ctx?.signal ? { signal: ctx.signal } : {}),\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;AAaA,MAAM,8BAA8B;;;;;;;;;AAUpC,SAAS,oBAAoB,YAAsD;CAgDjF,OAAO,eAAe,EA9CpB,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,UAAU;GACnB,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,qBAAqB,CAAC,EAAE;GAGvD,MAAM,YAAY;GAElB,IAAI,OAAO,UAAU,YAAY,YAAY,UAAU,QAAQ,WAAW,GACxE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAsC,MAAM,CAAC,SAAS;GAAE,CAAC,EAC/E;GAGF,IACE,UAAU,cAAc,WACvB,OAAO,UAAU,cAAc,YAAY,UAAU,aAAa,IAEnE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAuC,MAAM,CAAC,WAAW;GAAE,CAAC,EAClF;GAGF,IAAI,UAAU,eAAe,UAAa,OAAO,UAAU,eAAe,WACxE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAgC,MAAM,CAAC,YAAY;GAAE,CAAC,EAC5E;GAGF,MAAM,SAAwB,EAAE,SAAS,UAAU,QAAQ;GAE3D,IAAI,OAAO,UAAU,cAAc,UACjC,OAAO,YAAY,UAAU;GAG/B,IAAI,UAAU,eAAe,MAC3B,OAAO,aAAa;GAGtB,OAAO,EAAE,OAAO,OAAO;EACzB;CACF,EAGyB,GAAG,mBAAmB,UAAU,CAAC;AAC9D;;AAsBA,SAAS,cAAc,WAA+B,KAA6C;CACjG,IAAI,cAAc,QAChB,OAAO;CAGT,OAAO,QAAQ,SAAY,YAAY,KAAK,IAAI,WAAW,GAAG;AAChE;AA0CA,SAAgB,iBACd,KACA,SACwE;CACxE,MAAM,aAAa,SAAS,eAAe;CAE3C,OAAO,KAA+D;EACpE,MAAM,SAAS,QAAQ;EACvB,aACE,gQAIC,aACG,sKAGA;EACN,SAAS,UAAU,aAAa,MAAM,QAAQ;EAC9C,OAAO,oBAAoB,UAAU;EAGrC,SAAS,OAAO,OAAO,QAAQ;GAC7B,IAAI,MAAM,eAAe,MAAM;IAC7B,IAAI,CAAC,YACH,MAAM,IAAI,qBACR,+FACA;KAAE,MAAM;KAAkB,QAAQ;KAAe,SAAS,MAAM;IAAQ,CAC1E;IAQF,OAAO;KAAE,GAAG,MALM,IAAI,WACpB,MAAM,SACN,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,UAAU,IAAI,MACnE;KAEiB,YAAY;IAAK;GACpC;GAEA,MAAM,YAAY,cAAc,MAAM,WAAW,SAAS,YAAY;GAEtE,OAAO,IAAI,KAAK,MAAM,SAAS;IAC7B,GAAI,cAAc,SAAY,EAAE,UAAU,IAAI,CAAC;IAC/C,GAAI,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,CAAC;GAC9C,CAAC;EACH;CACF,CAAC;AACH"}
+{"version":3,"file":"run-shell.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-shell.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { WorkspacePolicyError } from \"../errors\";\nimport type {\n  RunShellBackgroundResult,\n  RunShellInput,\n  RunShellResult,\n  WorkspaceOps,\n} from \"../contracts\";\nimport { runShellJsonSchema } from \"./json-schemas\";\nimport { withJsonSchema } from \"./schema\";\n\n/** The default tool name `run_shell` is exposed to the LLM under. */\nconst DEFAULT_RUN_SHELL_TOOL_NAME = \"run_shell\";\n\n/**\n * Hand-rolled Standard Schema for {@link RunShellInput}. We validate the\n * model's arguments without a runtime schema dependency: `command` must be\n * a non-empty string, `timeoutMs` (when present) a positive number and\n * `background` (when present) a boolean. Invalid args surface as a\n * `SchemaValidationError` in the tool result's `error` field rather than\n * reaching `ops.exec`.\n */\nfunction runShellInputSchema(background: boolean): StandardSchemaV1<RunShellInput> {\n  const schema: StandardSchemaV1<RunShellInput> = {\n    \"~standard\": {\n      version: 1,\n      vendor: \"@warlock.js/ai-workspace\",\n      validate: (value) => {\n        if (typeof value !== \"object\" || value === null) {\n          return { issues: [{ message: \"expected an object\" }] };\n        }\n\n        const candidate = value as Record<string, unknown>;\n\n        if (typeof candidate.command !== \"string\" || candidate.command.length === 0) {\n          return {\n            issues: [{ message: \"command must be a non-empty string\", path: [\"command\"] }],\n          };\n        }\n\n        if (\n          candidate.timeoutMs !== undefined &&\n          (typeof candidate.timeoutMs !== \"number\" || candidate.timeoutMs <= 0)\n        ) {\n          return {\n            issues: [{ message: \"timeoutMs must be a positive number\", path: [\"timeoutMs\"] }],\n          };\n        }\n\n        if (candidate.background !== undefined && typeof candidate.background !== \"boolean\") {\n          return {\n            issues: [{ message: \"background must be a boolean\", path: [\"background\"] }],\n          };\n        }\n\n        const result: RunShellInput = { command: candidate.command };\n\n        if (typeof candidate.timeoutMs === \"number\") {\n          result.timeoutMs = candidate.timeoutMs;\n        }\n\n        if (candidate.background === true) {\n          result.background = true;\n        }\n\n        return { value: result };\n      },\n    },\n  };\n\n  return withJsonSchema(schema, runShellJsonSchema(background));\n}\n\n/** Options for {@link makeRunShellTool}. */\nexport interface MakeRunShellToolOptions {\n  /** Override the tool name exposed to the LLM (default `\"run_shell\"`). */\n  name?: string;\n  /**\n   * Upper bound for a model-supplied `timeoutMs` on a foreground command —\n   * the model can lower the timeout, never raise it past this. The\n   * workspace passes its `shell.timeoutMs`.\n   */\n  maxTimeoutMs?: number;\n  /**\n   * Accept `background: true` and start the command as a background job\n   * (`ops.startShell`), returning a {@link RunShellBackgroundResult}. The\n   * workspace sets it when the policy has `shell.background`. Default\n   * `false`: a background request is refused.\n   */\n  background?: boolean;\n  /**\n   * The name of the shell lines run in (for example `bash` or\n   * `PowerShell 7 (pwsh)`). When set, the description tells the model which\n   * shell and syntax rules apply. Absent ⇒ argv mode, no shell.\n   */\n  shellLabel?: string;\n  /** The grammar of that shell; selects the syntax rules in the description. */\n  shellDialect?: \"posix\" | \"cmd\" | \"powershell\" | \"powershell5\" | \"none\";\n  /** The operating system named in the description. Default: the running one. */\n  platform?: NodeJS.Platform;\n}\n\nconst DIALECT_RULES: Record<\"posix\" | \"cmd\" | \"powershell\" | \"powershell5\", string> = {\n  posix:\n    \"Use POSIX shell syntax: `;`, `&&`, `||`, pipes, quotes, `$( )` and redirections are supported, \" +\n    \"and every command in the line is checked. Compound statements (`if`, `for`), brace expansion, \" +\n    \"arithmetic and `&` are not.\",\n  cmd:\n    \"Use cmd.exe syntax: `&&`, `||`, `&`, `|` and simple redirections are supported, and every command \" +\n    \"in the line is checked. `%` and `!` expansion, `^`, parentheses and `if` / `for` are not.\",\n  powershell:\n    \"Use PowerShell syntax: `;`, `&&`, `||`, pipes, `$( )`, the call operator `&` and the redirections \" +\n    \"`>`, `>>`, `2>` and `2>&1` are supported, and every command in the line is checked (aliases such as \" +\n    \"`rm` and `Remove-Item` are treated alike). Script blocks, `Invoke-Expression`, here-strings, \" +\n    \"splatting and `if` / `foreach` are not.\",\n  powershell5:\n    \"Use Windows PowerShell 5.1 syntax: `;`, pipes, `$( )`, the call operator `&` and the redirections \" +\n    \"`>`, `>>`, `2>` and `2>&1` are supported, and every command in the line is checked (aliases such as \" +\n    \"`rm` and `Remove-Item` are treated alike). This version cannot chain with `&&` or `||`: put one \" +\n    \"command per call, or join with `;` (which runs the next command whatever the exit code). Script \" +\n    \"blocks, `Invoke-Expression`, here-strings, splatting and `if` / `foreach` are not supported.\",\n};\n\nconst PLATFORM_NAMES: Partial<Record<NodeJS.Platform, string>> = {\n  win32: \"Windows\",\n  darwin: \"macOS\",\n  linux: \"Linux\",\n};\n\n/** The sentence that names the shell and its syntax, or `\"\"` in argv mode. */\nfunction shellSentence(options: MakeRunShellToolOptions | undefined): string {\n  const dialect = options?.shellDialect;\n\n  if (options?.shellLabel === undefined || dialect === undefined || dialect === \"none\") {\n    return \"\";\n  }\n\n  const platform = options.platform ?? process.platform;\n\n  return (\n    ` Commands run on ${PLATFORM_NAMES[platform] ?? platform} using ${options.shellLabel}. ` +\n    DIALECT_RULES[dialect]\n  );\n}\n\n/** The lower of the model's timeout and the cap (either may be absent). */\nfunction cappedTimeout(requested: number | undefined, cap: number | undefined): number | undefined {\n  if (requested === undefined) {\n    return cap;\n  }\n\n  return cap === undefined ? requested : Math.min(requested, cap);\n}\n\n/**\n * Build the `run_shell` tool — a {@link ToolContract} that runs a command\n * line through the policy-enforced {@link WorkspaceOps} layer.\n *\n * Every command in the line is checked against the shell policy by\n * `ops.exec`; a refused line throws a `WorkspacePolicyError` (with a\n * `reason` and a message that says how to fix the command) which the\n * `tool()` runtime catches and surfaces in the result's `error` field\n * (never a thrown run-killer), so the agent reads the refusal as tool data\n * and self-corrects. A command that runs but exits non-zero is *not* an\n * error — its `exitCode`/`stderr` come back in `data` for the agent to\n * inspect.\n *\n * The agent run's cancellation `signal` (from the dispatch `ctx`) is passed\n * to `ops.exec` per invocation: a cancelled run never starts the command,\n * and one cancelled mid-command kills its process tree (`cancelled: true`).\n * A background command (`background: true`, when enabled) belongs to the\n * workspace instead and keeps running after the call returns.\n *\n * @param ops - The policy-enforced operation layer to delegate `exec` to.\n * @param options - Tool-name override, timeout cap and background support.\n *\n * @example\n * const runShell = makeRunShellTool(ops);\n * const { data, error } = await runShell.invoke({ command: \"npm run build\" });\n * if (error) handleDenied(error);\n * else console.log(data.exitCode, data.stdout);\n */\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions & { background?: false },\n): ToolContract<RunShellInput, RunShellResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options: MakeRunShellToolOptions & { background: true },\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions,\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions,\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult> {\n  const background = options?.background === true;\n\n  return tool<RunShellInput, RunShellResult | RunShellBackgroundResult>({\n    name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,\n    description:\n      \"Run a shell command inside the workspace. Every command in it must be \" +\n      \"permitted by the shell policy; a refusal explains how to fix the \" +\n      \"command. Output is byte-capped and the run is time-limited. A \" +\n      \"non-zero exit code is returned as data, not an error.\" +\n      shellSentence(options) +\n      (background\n        ? \" Pass background: true for a long-running command (dev server, \" +\n          \"watcher): it returns an id at once; read its output with \" +\n          \"shell_output and stop it with shell_kill.\"\n        : \"\"),\n    action: (input) => `Running \\`${input.command}\\``,\n    input: runShellInputSchema(background),\n    // The run's signal belongs to this one invocation: it is read from the\n    // dispatch ctx on every call and never stored on the tool or workspace.\n    execute: async (input, ctx) => {\n      if (input.background === true) {\n        if (!background) {\n          throw new WorkspacePolicyError(\n            \"Background commands are not enabled for this workspace; run the command without background.\",\n            { type: \"denied-command\", reason: \"not-allowed\", command: input.command },\n          );\n        }\n\n        const job = await ops.startShell(\n          input.command,\n          input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : undefined,\n        );\n\n        return { ...job, background: true };\n      }\n\n      const timeoutMs = cappedTimeout(input.timeoutMs, options?.maxTimeoutMs);\n\n      return ops.exec(input.command, {\n        ...(timeoutMs !== undefined ? { timeoutMs } : {}),\n        ...(ctx?.signal ? { signal: ctx.signal } : {}),\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;AAaA,MAAM,8BAA8B;;;;;;;;;AAUpC,SAAS,oBAAoB,YAAsD;CAgDjF,OAAO,eAAe,EA9CpB,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,UAAU;GACnB,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,qBAAqB,CAAC,EAAE;GAGvD,MAAM,YAAY;GAElB,IAAI,OAAO,UAAU,YAAY,YAAY,UAAU,QAAQ,WAAW,GACxE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAsC,MAAM,CAAC,SAAS;GAAE,CAAC,EAC/E;GAGF,IACE,UAAU,cAAc,WACvB,OAAO,UAAU,cAAc,YAAY,UAAU,aAAa,IAEnE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAuC,MAAM,CAAC,WAAW;GAAE,CAAC,EAClF;GAGF,IAAI,UAAU,eAAe,UAAa,OAAO,UAAU,eAAe,WACxE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAgC,MAAM,CAAC,YAAY;GAAE,CAAC,EAC5E;GAGF,MAAM,SAAwB,EAAE,SAAS,UAAU,QAAQ;GAE3D,IAAI,OAAO,UAAU,cAAc,UACjC,OAAO,YAAY,UAAU;GAG/B,IAAI,UAAU,eAAe,MAC3B,OAAO,aAAa;GAGtB,OAAO,EAAE,OAAO,OAAO;EACzB;CACF,EAGyB,GAAG,mBAAmB,UAAU,CAAC;AAC9D;AA+BA,MAAM,gBAAgF;CACpF,OACE;CAGF,KACE;CAEF,YACE;CAIF,aACE;AAKJ;AAEA,MAAM,iBAA2D;CAC/D,OAAO;CACP,QAAQ;CACR,OAAO;AACT;;AAGA,SAAS,cAAc,SAAsD;CAC3E,MAAM,UAAU,SAAS;CAEzB,IAAI,SAAS,eAAe,UAAa,YAAY,UAAa,YAAY,QAC5E,OAAO;CAGT,MAAM,WAAW,QAAQ,YAAY,QAAQ;CAE7C,OACE,oBAAoB,eAAe,aAAa,SAAS,SAAS,QAAQ,WAAW,MACrF,cAAc;AAElB;;AAGA,SAAS,cAAc,WAA+B,KAA6C;CACjG,IAAI,cAAc,QAChB,OAAO;CAGT,OAAO,QAAQ,SAAY,YAAY,KAAK,IAAI,WAAW,GAAG;AAChE;AA0CA,SAAgB,iBACd,KACA,SACwE;CACxE,MAAM,aAAa,SAAS,eAAe;CAE3C,OAAO,KAA+D;EACpE,MAAM,SAAS,QAAQ;EACvB,aACE,+PAIA,cAAc,OAAO,KACpB,aACG,sKAGA;EACN,SAAS,UAAU,aAAa,MAAM,QAAQ;EAC9C,OAAO,oBAAoB,UAAU;EAGrC,SAAS,OAAO,OAAO,QAAQ;GAC7B,IAAI,MAAM,eAAe,MAAM;IAC7B,IAAI,CAAC,YACH,MAAM,IAAI,qBACR,+FACA;KAAE,MAAM;KAAkB,QAAQ;KAAe,SAAS,MAAM;IAAQ,CAC1E;IAQF,OAAO;KAAE,GAAG,MALM,IAAI,WACpB,MAAM,SACN,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,UAAU,IAAI,MACnE;KAEiB,YAAY;IAAK;GACpC;GAEA,MAAM,YAAY,cAAc,MAAM,WAAW,SAAS,YAAY;GAEtE,OAAO,IAAI,KAAK,MAAM,SAAS;IAC7B,GAAI,cAAc,SAAY,EAAE,UAAU,IAAI,CAAC;IAC/C,GAAI,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,CAAC;GAC9C,CAAC;EACH;CACF,CAAC;AACH"}

package/esm/tools/run-tests.d.mts

@@ -21,6 +21,13 @@ export interface MakeRunTestsToolOptions {
    * double quotes for cmd.exe.
    */
   interpreter?: WorkspaceShellInterpreter;
+  /**
+   * The grammar of the shell the line runs in; with `interpreter` it picks
+   * the quoting: single quotes (doubled inside) for PowerShell.
+   */
+  dialect?: "posix" | "cmd" | "powershell" | "powershell5";
+  /** The platform quoting is chosen for. Default: the running one. */
+  platform?: NodeJS.Platform;
 }
 /**
  * Build the `run_tests` tool — a {@link ToolContract} convenience over

package/esm/tools/run-tests.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"run-tests.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-tests.ts"],"mappings":";;;;;;;iBAyEiB;;EAEf;;;;;;EAMA;;;;;;;EAOA,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoCA,iBACd,KAAK,cACL,UAAU,0BACT,aAAa,eAAe"}
+{"version":3,"file":"run-tests.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-tests.ts"],"mappings":";;;;;;;iBAyEiB;;EAEf;;;;;;EAMA;;;;;;;EAOA,cAAc;;;;;EAKd;;EAEA,WAAW,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;wBA+CJ,iBACd,KAAK,cACL,UAAU,0BACT,aAAa,eAAe"}

package/esm/tools/run-tests.mjs

@@ -37,8 +37,9 @@ 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) {
-	if (interpreter === "sh" && process.platform !== "win32") return `'${pattern.replace(/'/g, "'\\''")}'`;
+function quotePattern(pattern, interpreter, dialect, platform = process.platform) {
+	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}"`;
 }
 /**
@@ -73,12 +74,12 @@ function makeRunTestsTool(ops, options) {
 		action: (input) => input.pattern ? `Running tests matching "${input.pattern}"` : "Running tests",
 		input: runTestsInputSchema,
 		execute: (input, ctx) => {
-			const command = input.pattern ? `${baseCommand} ${quotePattern(input.pattern, options?.interpreter ?? "none")}` : baseCommand;
+			const command = input.pattern ? `${baseCommand} ${quotePattern(input.pattern, options?.interpreter ?? "none", options?.dialect, options?.platform)}` : baseCommand;
 			return ops.exec(command, ctx?.signal ? { signal: ctx.signal } : void 0);
 		}
 	});
 }
 
 //#endregion
-export { makeRunTestsTool };
+export { makeRunTestsTool, quotePattern };
 //# sourceMappingURL=run-tests.mjs.map

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\n/** Quote the test pattern as one literal argument for the line's interpreter. */\nfunction quotePattern(pattern: string, interpreter: WorkspaceShellInterpreter): string {\n  if (interpreter === \"sh\" && process.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\")}`\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;;AAsBA,SAAS,aAAa,SAAiB,aAAgD;CACrF,IAAI,gBAAgB,QAAQ,QAAQ,aAAa,SAC/C,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,MAAM,MAC5E;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/tools/write-file.mjs

@@ -38,11 +38,12 @@ function makeWriteFileTool(ops, options) {
 		description: "Write full content to a workspace file, creating it (and any parent directories) if absent and overwriting it otherwise. The write is atomic. Returns the bytes written and the new content hash.",
 		input: inputSchema,
 		async execute(input) {
-			const { hash, bytesWritten } = await ops.writeFile(input.path, input.content);
+			const { hash, bytesWritten, diagnostics } = await ops.writeFile(input.path, input.content);
 			return {
 				path: input.path,
 				bytesWritten,
-				hash
+				hash,
+				...diagnostics !== void 0 ? { diagnostics } : {}
 			};
 		}
 	});

package/esm/tools/write-file.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"write-file.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/write-file.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { objectSchema, stringField } from \"./schema\";\nimport { WRITE_FILE_JSON_SCHEMA } from \"./json-schemas\";\nimport type { WorkspaceOps, WriteFileInput, WriteFileResult } from \"../contracts\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"write_file\";\n\n/** Input schema for the `write_file` tool. */\nconst inputSchema = objectSchema<WriteFileInput>(\n  {\n    path: stringField(),\n    content: stringField(),\n  },\n  WRITE_FILE_JSON_SCHEMA,\n);\n\n/**\n * Build the agent-facing `write_file` tool over a workspace's policy-\n * enforced {@link WorkspaceOps}.\n *\n * The tool validates `{ path, content }` against a Standard Schema, then\n * delegates to `ops.writeFile`, which atomically writes the full content\n * (creating parent directories) and returns the byte count and content\n * `hash`. The tool re-attaches the workspace-relative `path` so the\n * result matches the {@link WriteFileResult} wire shape.\n *\n * **Errors flow as data.** A jail escape is thrown by `ops`; the\n * `tool()` wrapper catches it and surfaces it in the returned `{ error }`\n * field — `invoke()` never throws.\n *\n * @param ops - The shared, policy-enforced operation layer.\n * @param options - Optional overrides; `name` renames the LLM-visible tool.\n *\n * @example\n * const writeTool = makeWriteFileTool(ops);\n * const { data } = await writeTool.invoke({ path: \"src/new.ts\", content: \"export {};\" });\n * console.log(data.bytesWritten, data.hash);\n */\nexport function makeWriteFileTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<WriteFileInput, WriteFileResult> {\n  return tool<WriteFileInput, WriteFileResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Write full content to a workspace file, creating it (and any parent \" +\n      \"directories) if absent and overwriting it otherwise. The write is \" +\n      \"atomic. Returns the bytes written and the new content hash.\",\n    input: inputSchema,\n    async execute(input) {\n      const { hash, bytesWritten } = await ops.writeFile(input.path, input.content);\n\n      return { path: input.path, bytesWritten, hash };\n    },\n  });\n}\n"],"mappings":";;;;;;AAMA,MAAM,eAAe;;AAGrB,MAAM,cAAc,aAClB;CACE,MAAM,YAAY;CAClB,SAAS,YAAY;AACvB,GACA,sBACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,kBACd,KACA,SAC+C;CAC/C,OAAO,KAAsC;EAC3C,MAAM,SAAS,QAAQ;EACvB,aACE;EAGF,OAAO;EACP,MAAM,QAAQ,OAAO;GACnB,MAAM,EAAE,MAAM,iBAAiB,MAAM,IAAI,UAAU,MAAM,MAAM,MAAM,OAAO;GAE5E,OAAO;IAAE,MAAM,MAAM;IAAM;IAAc;GAAK;EAChD;CACF,CAAC;AACH"}
+{"version":3,"file":"write-file.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/write-file.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { objectSchema, stringField } from \"./schema\";\nimport { WRITE_FILE_JSON_SCHEMA } from \"./json-schemas\";\nimport type { WorkspaceOps, WriteFileInput, WriteFileResult } from \"../contracts\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"write_file\";\n\n/** Input schema for the `write_file` tool. */\nconst inputSchema = objectSchema<WriteFileInput>(\n  {\n    path: stringField(),\n    content: stringField(),\n  },\n  WRITE_FILE_JSON_SCHEMA,\n);\n\n/**\n * Build the agent-facing `write_file` tool over a workspace's policy-\n * enforced {@link WorkspaceOps}.\n *\n * The tool validates `{ path, content }` against a Standard Schema, then\n * delegates to `ops.writeFile`, which atomically writes the full content\n * (creating parent directories) and returns the byte count and content\n * `hash`. The tool re-attaches the workspace-relative `path` so the\n * result matches the {@link WriteFileResult} wire shape.\n *\n * **Errors flow as data.** A jail escape is thrown by `ops`; the\n * `tool()` wrapper catches it and surfaces it in the returned `{ error }`\n * field — `invoke()` never throws.\n *\n * @param ops - The shared, policy-enforced operation layer.\n * @param options - Optional overrides; `name` renames the LLM-visible tool.\n *\n * @example\n * const writeTool = makeWriteFileTool(ops);\n * const { data } = await writeTool.invoke({ path: \"src/new.ts\", content: \"export {};\" });\n * console.log(data.bytesWritten, data.hash);\n */\nexport function makeWriteFileTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<WriteFileInput, WriteFileResult> {\n  return tool<WriteFileInput, WriteFileResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Write full content to a workspace file, creating it (and any parent \" +\n      \"directories) if absent and overwriting it otherwise. The write is \" +\n      \"atomic. Returns the bytes written and the new content hash.\",\n    input: inputSchema,\n    async execute(input) {\n      const { hash, bytesWritten, diagnostics } = await ops.writeFile(input.path, input.content);\n\n      return {\n        path: input.path,\n        bytesWritten,\n        hash,\n        ...(diagnostics !== undefined ? { diagnostics } : {}),\n      };\n    },\n  });\n}\n"],"mappings":";;;;;;AAMA,MAAM,eAAe;;AAGrB,MAAM,cAAc,aAClB;CACE,MAAM,YAAY;CAClB,SAAS,YAAY;AACvB,GACA,sBACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,kBACd,KACA,SAC+C;CAC/C,OAAO,KAAsC;EAC3C,MAAM,SAAS,QAAQ;EACvB,aACE;EAGF,OAAO;EACP,MAAM,QAAQ,OAAO;GACnB,MAAM,EAAE,MAAM,cAAc,gBAAgB,MAAM,IAAI,UAAU,MAAM,MAAM,MAAM,OAAO;GAEzF,OAAO;IACL,MAAM,MAAM;IACZ;IACA;IACA,GAAI,gBAAgB,SAAY,EAAE,YAAY,IAAI,CAAC;GACrD;EACF;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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoagB,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

@@ -1,5 +1,8 @@
 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";
@@ -88,10 +91,26 @@ var WorkspaceImpl = class WorkspaceImpl {
 		this.allowedTools = new Set(allowedTools);
 		this.state = state ?? {
 			jobs: new ShellJobs(),
-			todos: new TodoStore()
+			todos: new TodoStore(),
+			approvals: []
+		};
+		this.resolvedShell = resolveShell(policy.shell);
+		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 });
+		this.ops = createOps(backend, policy, {
+			jobs: this.state.jobs,
+			approvals: this.state.approvals
+		});
 		this.tools = this.buildTools();
 	}
 	/**
@@ -105,7 +124,7 @@ var WorkspaceImpl = class WorkspaceImpl {
 		const erase = (contract) => contract;
 		const shell = this.policy.shell;
 		const background = shell?.background !== void 0;
-		const interpreter = shell?.interpreter ?? "none";
+		const resolvedShell = this.resolvedShell;
 		const factories = {
 			readFile: (opts) => erase(makeReadFileTool(this.ops, opts)),
 			editFile: (opts) => erase(makeEditFileTool(this.ops, opts)),
@@ -116,13 +135,16 @@ var WorkspaceImpl = class WorkspaceImpl {
 			runShell: (opts) => erase(makeRunShellTool(this.ops, {
 				...opts?.name !== void 0 ? { name: opts.name } : {},
 				...shell?.timeoutMs !== void 0 ? { maxTimeoutMs: shell.timeoutMs } : {},
-				background
+				background,
+				...resolvedShell.interpreter !== "none" ? { shellLabel: resolvedShell.label } : {},
+				shellDialect: resolvedShell.interpreter === "none" ? "none" : resolvedShell.dialect
 			})),
 			shellOutput: (opts) => erase(makeShellOutputTool(this.ops, opts)),
 			shellKill: (opts) => erase(makeShellKillTool(this.ops, opts)),
 			runTests: (opts) => erase(makeRunTestsTool(this.ops, {
 				...opts,
-				interpreter
+				interpreter: resolvedShell.interpreter,
+				dialect: resolvedShell.dialect
 			})),
 			grep: (opts) => erase(makeGrepTool(this.ops, opts)),
 			glob: (opts) => erase(makeGlobTool(this.ops, opts)),

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 { 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  WorkspaceOps,\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}\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  /** 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() };\n\n    const backend = selectBackend(policy);\n    this.ops = createOps(backend, policy, { jobs: this.state.jobs });\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 interpreter = shell?.interpreter ?? \"none\";\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          }),\n        ),\n      shellOutput: (opts) => erase(makeShellOutputTool(this.ops, opts)),\n      shellKill: (opts) => erase(makeShellKillTool(this.ops, opts)),\n      runTests: (opts) => erase(makeRunTestsTool(this.ops, { ...opts, interpreter })),\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,21 +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) or `"sh"` (opt-in shell syntax, every command checked).                                                                                                                                         |
-| `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"] }`.
 
@@ -235,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.
+- `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
@@ -309,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.
@@ -356,10 +363,56 @@ A custom `WorkspaceBackend` receives the signal as `exec(command, { signal })` a
 
 ## Read-before-edit (the stale-hash guard)
 
-`readFile` returns a SHA-256 `hash` of the full file. Pass it to `editFile`'s `expectHash`; if the file changed since you read it, the edit is rejected as stale so you re-read before clobbering. `editFile` also requires the `oldString` to be **exact and unique** — pass `replaceAll: true` to replace every occurrence, or include more surrounding context to disambiguate.
+`readFile` returns a SHA-256 `hash` of the full file. Pass it to `editFile`'s `expectHash`; if the file changed since you read it, the edit is rejected as stale so you re-read before clobbering. `editFile` also requires the `oldString` to be **found uniquely** (see "Finding the text to edit") — pass `replaceAll: true` to replace every occurrence, or include more surrounding context to disambiguate.
 
 Writes, edits and removes of the same path run one after another, even when the agent dispatches tool calls concurrently: of two edits pinned to the same `expectHash`, the second is rejected as stale instead of silently overwriting the first. `read.maxBytes` bounds what a read returns, not memory — the whole file is still read and hashed.
 
+## Finding the text to edit — `edit.matching`
+
+By default an edit looks for `oldString` in tiers and uses the first tier that finds it: the exact text, then the text with line endings normalised (an LF `oldString` finds CRLF lines), then with look-alike punctuation folded (curly quotes, en/em dashes and non-breaking spaces match their plain forms), then line by line ignoring trailing whitespace. A result found by one of the last two tiers reports `matchTier: "unicode"` or `"whitespace"`; an exact find leaves it out. A loose find must be unique: with two candidates the edit fails with `not-unique` and writes nothing, even with `replaceAll`. Replacement text takes the file's dominant line ending, so a CRLF file stays CRLF.
+
+```ts
+ai.workspace({
+  cwd,
+  edit: { matching: "tiered", missHintLines: 12, lineEndings: "preserve" },
+});
+```
+
+- `matching: "exact"` accepts only the text byte for byte.
+- `lineEndings: "lf" | "crlf"` forces the ending of replacement text.
+- When the text is not found, the `WorkspaceEditError` (`type: "not-found"`) carries a `hint`: the closest file text (at most `missHintLines` lines, 12 by default, each at most 200 characters; `0` turns it off, and it never exceeds `read.maxBytes`) or a note that `newString` is already present. A file the jail refuses never gets a hint.
+
+## Diagnostics after an edit — `hooks.afterEdit`
+
+```ts
+ai.workspace({
+  cwd,
+  hooks: {
+    afterEdit: async ({ paths, tool }) => await typecheck(paths), // returns text or nothing
+    afterEditMaxChars: 4_000,
+    afterEditTimeoutMs: 10_000,
+  },
+});
+```
+
+After `write_file`, `edit_file`, `multi_edit` or `apply_patch` writes files, the hook runs once per call with the written paths (not on a patch `dryRun`, not for deleted files). Text it returns comes back on the result as `diagnostics`, between `[diagnostics]` and `[/diagnostics]` lines; output over `afterEditMaxChars` is cut with a marker. A hook that throws or does not answer within `afterEditTimeoutMs` yields `diagnostics unavailable` and never fails the edit.
+
+## Oversized output — `output`
+
+```ts
+ai.workspace({
+  cwd,
+  output: {
+    spillDir: ".warlock/spill",
+    maxLines: 2_000,
+    maxBytes: 51_200,
+    retentionMs: 604_800_000,
+  },
+});
+```
+
+With `output.spillDir` set, output too large to return whole (`run_shell`, `shell_output`, `grep`, `glob`, and `read_file` when `read.maxBytes` cut the window) is saved in full to `spill-<time>-<random>-<label>.txt` there. The result keeps the start and end (`keep: "head+tail"`, the default for shell output; `"head"` for the rest, or set `keep` yourself) and carries a marker such as `[showing lines 1-25 and 99976-100000 of 100000; full output saved to FILE]`. The boolean `truncated` stays; `truncation` adds `{ shown: { lines }, total: { lines, bytes }, path? }` (per stream, `truncation.stdout` / `truncation.stderr`, for commands). `read_file` may open the spill directory even when it is outside the jail, so the model can page through the file with `startLine` / `limit`; nothing else outside the jail opens, and writes never reach it. Files older than `retentionMs` (7 days by default) are removed when a workspace is created, when a new file is written and on `dispose()`; `retentionMs: 0` removes the files this workspace wrote on `dispose()`. Only files named like spill files are ever removed. Without `spillDir`, output is cut at `shell.maxOutputBytes` / `read.maxBytes` as before, and `run_shell` results still report the sizes in `truncation`.
+
 ## Errors flow as data, not throws
 
 Policy and edit failures are typed errors extending the `@warlock.js/ai` `AIError` base. Inside a tool the `tool()` wrapper catches them and surfaces them in `{ error }`, so the agent reads the failure and self-corrects. Branch on `.type`:

package/package.json

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