@warlock.js/ai-workspace 5.30.0 → 5.31.0

package/esm/tools/json-schemas.mjs

@@ -0,0 +1,175 @@
+//#region ../../packages/ai-workspace/src/tools/json-schemas.ts
+/**
+* The JSON Schemas the workspace tools publish for their input (read by
+* `extractJsonSchema` and sent to the provider with each tool), kept short
+* because they ride along on every model call. They describe what the
+* hand-rolled validators accept; the validators remain the authority.
+*/
+const string = (description) => ({
+	type: "string",
+	description
+});
+const integer = (description) => ({
+	type: "integer",
+	description
+});
+const boolean = (description) => ({
+	type: "boolean",
+	description
+});
+/** `read_file`. */
+const READ_FILE_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		startLine: integer("1-based first line to return."),
+		limit: integer("Most lines to return.")
+	},
+	required: ["path"]
+};
+/** `edit_file`. */
+const EDIT_FILE_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		oldString: string("Exact text to replace; must be unique unless replaceAll."),
+		newString: string("Replacement text."),
+		replaceAll: boolean("Replace every occurrence."),
+		expectHash: string("Hash from read_file; rejects the edit if the file changed.")
+	},
+	required: [
+		"path",
+		"oldString",
+		"newString"
+	]
+};
+/** `multi_edit`. */
+const MULTI_EDIT_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		edits: {
+			type: "array",
+			description: "Replacements applied in order, each to the result of the previous; all or none.",
+			minItems: 1,
+			maxItems: 100,
+			items: {
+				type: "object",
+				properties: {
+					oldString: string("Exact text to replace; must be unique unless replaceAll."),
+					newString: string("Replacement text."),
+					replaceAll: boolean("Replace every occurrence.")
+				},
+				required: ["oldString", "newString"]
+			}
+		},
+		expectHash: string("Hash from read_file; rejects every edit if the file changed.")
+	},
+	required: ["path", "edits"]
+};
+/** `write_file`. */
+const WRITE_FILE_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative file path."),
+		content: string("Full file content.")
+	},
+	required: ["path", "content"]
+};
+/** `list_dir`. */
+const LIST_DIR_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		path: string("Workspace-relative directory (default \".\")."),
+		depth: integer("Levels to list; 1 = direct children (default)."),
+		ignore: {
+			type: "array",
+			items: { type: "string" },
+			description: "Extra globs to leave out."
+		}
+	}
+};
+/** `run_shell` (the `background` property is only listed when background commands are enabled). */
+function runShellJsonSchema(background) {
+	return {
+		type: "object",
+		properties: {
+			command: string("The command line to run."),
+			timeoutMs: integer("Wall-clock cap in ms (can only lower the workspace limit)."),
+			...background ? { background: boolean("Start it in the background and return its id at once (dev servers, watchers).") } : {}
+		},
+		required: ["command"]
+	};
+}
+/** `shell_output`. */
+const SHELL_OUTPUT_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		id: string("Background command id from run_shell."),
+		since: integer("A cursor from an earlier result; omit for output since the last read."),
+		waitMs: integer("Wait up to this long (max 30000) for new output.")
+	},
+	required: ["id"]
+};
+/** `shell_kill`. */
+const SHELL_KILL_JSON_SCHEMA = {
+	type: "object",
+	properties: { id: string("Background command id from run_shell.") },
+	required: ["id"]
+};
+/** `run_tests`. */
+const RUN_TESTS_JSON_SCHEMA = {
+	type: "object",
+	properties: { pattern: string("Optional test path or name filter.") }
+};
+/** `grep`. */
+const GREP_JSON_SCHEMA = {
+	type: "object",
+	properties: {
+		pattern: string("Regular expression to search for."),
+		glob: string("Only search files matching this glob (e.g. \"src/**/*.ts\")."),
+		ignoreCase: boolean("Case-insensitive match.")
+	},
+	required: ["pattern"]
+};
+/** `glob`. */
+const GLOB_JSON_SCHEMA = {
+	type: "object",
+	properties: { pattern: string("Glob such as \"src/**/*.ts\".") },
+	required: ["pattern"]
+};
+/** `todo_write`. */
+const TODO_WRITE_JSON_SCHEMA = {
+	type: "object",
+	properties: { todos: {
+		type: "array",
+		description: "The complete updated list (replaces the old one).",
+		maxItems: 100,
+		items: {
+			type: "object",
+			properties: {
+				id: string("Stable id; omit to number items by position."),
+				content: string("The step."),
+				status: {
+					type: "string",
+					enum: [
+						"pending",
+						"in_progress",
+						"completed"
+					]
+				}
+			},
+			required: ["content", "status"]
+		}
+	} },
+	required: ["todos"]
+};
+/** `todo_read`. */
+const TODO_READ_JSON_SCHEMA = {
+	type: "object",
+	properties: {}
+};
+
+//#endregion
+export { EDIT_FILE_JSON_SCHEMA, GLOB_JSON_SCHEMA, GREP_JSON_SCHEMA, LIST_DIR_JSON_SCHEMA, MULTI_EDIT_JSON_SCHEMA, READ_FILE_JSON_SCHEMA, RUN_TESTS_JSON_SCHEMA, SHELL_KILL_JSON_SCHEMA, SHELL_OUTPUT_JSON_SCHEMA, TODO_READ_JSON_SCHEMA, TODO_WRITE_JSON_SCHEMA, WRITE_FILE_JSON_SCHEMA, runShellJsonSchema };
+//# sourceMappingURL=json-schemas.mjs.map

package/esm/tools/json-schemas.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schemas.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/json-schemas.ts"],"sourcesContent":["import type { JsonSchemaObject } from \"./schema\";\n\n/**\n * The JSON Schemas the workspace tools publish for their input (read by\n * `extractJsonSchema` and sent to the provider with each tool), kept short\n * because they ride along on every model call. They describe what the\n * hand-rolled validators accept; the validators remain the authority.\n */\n\nconst string = (description: string): JsonSchemaObject => ({ type: \"string\", description });\nconst integer = (description: string): JsonSchemaObject => ({ type: \"integer\", description });\nconst boolean = (description: string): JsonSchemaObject => ({ type: \"boolean\", description });\n\n/** `read_file`. */\nexport const READ_FILE_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    path: string(\"Workspace-relative file path.\"),\n    startLine: integer(\"1-based first line to return.\"),\n    limit: integer(\"Most lines to return.\"),\n  },\n  required: [\"path\"],\n};\n\n/** `edit_file`. */\nexport const EDIT_FILE_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    path: string(\"Workspace-relative file path.\"),\n    oldString: string(\"Exact text to replace; must be unique unless replaceAll.\"),\n    newString: string(\"Replacement text.\"),\n    replaceAll: boolean(\"Replace every occurrence.\"),\n    expectHash: string(\"Hash from read_file; rejects the edit if the file changed.\"),\n  },\n  required: [\"path\", \"oldString\", \"newString\"],\n};\n\n/** `multi_edit`. */\nexport const MULTI_EDIT_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    path: string(\"Workspace-relative file path.\"),\n    edits: {\n      type: \"array\",\n      description:\n        \"Replacements applied in order, each to the result of the previous; all or none.\",\n      minItems: 1,\n      maxItems: 100,\n      items: {\n        type: \"object\",\n        properties: {\n          oldString: string(\"Exact text to replace; must be unique unless replaceAll.\"),\n          newString: string(\"Replacement text.\"),\n          replaceAll: boolean(\"Replace every occurrence.\"),\n        },\n        required: [\"oldString\", \"newString\"],\n      },\n    },\n    expectHash: string(\"Hash from read_file; rejects every edit if the file changed.\"),\n  },\n  required: [\"path\", \"edits\"],\n};\n\n/** `write_file`. */\nexport const WRITE_FILE_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    path: string(\"Workspace-relative file path.\"),\n    content: string(\"Full file content.\"),\n  },\n  required: [\"path\", \"content\"],\n};\n\n/** `list_dir`. */\nexport const LIST_DIR_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    path: string('Workspace-relative directory (default \".\").'),\n    depth: integer(\"Levels to list; 1 = direct children (default).\"),\n    ignore: { type: \"array\", items: { type: \"string\" }, description: \"Extra globs to leave out.\" },\n  },\n};\n\n/** `run_shell` (the `background` property is only listed when background commands are enabled). */\nexport function runShellJsonSchema(background: boolean): JsonSchemaObject {\n  return {\n    type: \"object\",\n    properties: {\n      command: string(\"The command line to run.\"),\n      timeoutMs: integer(\"Wall-clock cap in ms (can only lower the workspace limit).\"),\n      ...(background\n        ? {\n            background: boolean(\n              \"Start it in the background and return its id at once (dev servers, watchers).\",\n            ),\n          }\n        : {}),\n    },\n    required: [\"command\"],\n  };\n}\n\n/** `shell_output`. */\nexport const SHELL_OUTPUT_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    id: string(\"Background command id from run_shell.\"),\n    since: integer(\"A cursor from an earlier result; omit for output since the last read.\"),\n    waitMs: integer(\"Wait up to this long (max 30000) for new output.\"),\n  },\n  required: [\"id\"],\n};\n\n/** `shell_kill`. */\nexport const SHELL_KILL_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: { id: string(\"Background command id from run_shell.\") },\n  required: [\"id\"],\n};\n\n/** `run_tests`. */\nexport const RUN_TESTS_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: { pattern: string(\"Optional test path or name filter.\") },\n};\n\n/** `grep`. */\nexport const GREP_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    pattern: string(\"Regular expression to search for.\"),\n    glob: string('Only search files matching this glob (e.g. \"src/**/*.ts\").'),\n    ignoreCase: boolean(\"Case-insensitive match.\"),\n  },\n  required: [\"pattern\"],\n};\n\n/** `glob`. */\nexport const GLOB_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: { pattern: string('Glob such as \"src/**/*.ts\".') },\n  required: [\"pattern\"],\n};\n\n/** `todo_write`. */\nexport const TODO_WRITE_JSON_SCHEMA: JsonSchemaObject = {\n  type: \"object\",\n  properties: {\n    todos: {\n      type: \"array\",\n      description: \"The complete updated list (replaces the old one).\",\n      maxItems: 100,\n      items: {\n        type: \"object\",\n        properties: {\n          id: string(\"Stable id; omit to number items by position.\"),\n          content: string(\"The step.\"),\n          status: { type: \"string\", enum: [\"pending\", \"in_progress\", \"completed\"] },\n        },\n        required: [\"content\", \"status\"],\n      },\n    },\n  },\n  required: [\"todos\"],\n};\n\n/** `todo_read`. */\nexport const TODO_READ_JSON_SCHEMA: JsonSchemaObject = { type: \"object\", properties: {} };\n"],"mappings":"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"}

package/esm/tools/list-dir.d.mts

@@ -0,0 +1,32 @@
+import { ListDirInput, ListDirResult } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../../packages/ai-workspace/src/tools/list-dir.d.ts
+/**
+ * Build the agent-facing `list_dir` tool over a workspace's policy-enforced
+ * {@link WorkspaceOps}: a bounded, jailed listing of one directory.
+ *
+ * Entries come back breadth-first (each level sorted by name) with their
+ * type and — for files — size, down to `depth` levels (capped by
+ * `list.maxDepth`) and at most `list.maxEntries` entries (`truncated` says
+ * when the cap hit). `denyPaths` are always left out, as are the
+ * `list.ignore` globs (default `node_modules`, `.git`) and any `ignore`
+ * globs the model passes. Symlinks are reported as `"symlink"` and never
+ * followed. A path outside the jail surfaces as a `WorkspacePolicyError` in
+ * the result's `error` field.
+ *
+ * @param ops - The shared, policy-enforced operation layer.
+ * @param options - Optional overrides; `name` renames the LLM-visible tool.
+ *
+ * @example
+ * const listDir = makeListDirTool(ops);
+ * const { data } = await listDir.invoke({ path: "src", depth: 2 });
+ * for (const entry of data?.entries ?? []) console.log(entry.type, entry.path, entry.size);
+ */
+declare function makeListDirTool(ops: WorkspaceOps, options?: {
+  name?: string;
+}): ToolContract<ListDirInput, ListDirResult>;
+//#endregion
+export { makeListDirTool };
+//# sourceMappingURL=list-dir.d.mts.map

package/esm/tools/list-dir.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-dir.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/list-dir.ts"],"mappings":";;;;;;;;;AA4CA;;;;;;;;;;;;;;;;;iBAAgB,eAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA;EAAY,IAAA;AAAA,IACX,YAAA,CAAa,YAAA,EAAc,aAAA"}

package/esm/tools/list-dir.mjs

@@ -0,0 +1,50 @@
+import { objectSchema, optionalNumberField, optionalStringArrayField, optionalStringField } from "./schema.mjs";
+import { LIST_DIR_JSON_SCHEMA } from "./json-schemas.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../../packages/ai-workspace/src/tools/list-dir.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "list_dir";
+/** Input schema for the `list_dir` tool. */
+const inputSchema = objectSchema({
+	path: optionalStringField(),
+	depth: optionalNumberField(),
+	ignore: optionalStringArrayField()
+}, LIST_DIR_JSON_SCHEMA);
+/**
+* Build the agent-facing `list_dir` tool over a workspace's policy-enforced
+* {@link WorkspaceOps}: a bounded, jailed listing of one directory.
+*
+* Entries come back breadth-first (each level sorted by name) with their
+* type and — for files — size, down to `depth` levels (capped by
+* `list.maxDepth`) and at most `list.maxEntries` entries (`truncated` says
+* when the cap hit). `denyPaths` are always left out, as are the
+* `list.ignore` globs (default `node_modules`, `.git`) and any `ignore`
+* globs the model passes. Symlinks are reported as `"symlink"` and never
+* followed. A path outside the jail surfaces as a `WorkspacePolicyError` in
+* the result's `error` field.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const listDir = makeListDirTool(ops);
+* const { data } = await listDir.invoke({ path: "src", depth: 2 });
+* for (const entry of data?.entries ?? []) console.log(entry.type, entry.path, entry.size);
+*/
+function makeListDirTool(ops, options) {
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "List a workspace directory: entries with their type and file size, breadth-first, `depth` levels deep (default 1). Dependency and VCS folders are left out unless you list them directly.",
+		action: (input) => `Listing ${typeof input.path === "string" ? input.path : "."}`,
+		input: inputSchema,
+		execute: (input) => ops.listDir(input.path ?? ".", {
+			...input.depth !== void 0 ? { depth: input.depth } : {},
+			...input.ignore !== void 0 ? { ignore: input.ignore } : {}
+		})
+	});
+}
+
+//#endregion
+export { makeListDirTool };
+//# sourceMappingURL=list-dir.mjs.map

package/esm/tools/list-dir.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-dir.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/list-dir.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type { ListDirInput, ListDirResult, WorkspaceOps } from \"../contracts\";\nimport { LIST_DIR_JSON_SCHEMA } from \"./json-schemas\";\nimport {\n  objectSchema,\n  optionalNumberField,\n  optionalStringArrayField,\n  optionalStringField,\n} from \"./schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"list_dir\";\n\n/** Input schema for the `list_dir` tool. */\nconst inputSchema = objectSchema<ListDirInput>(\n  {\n    path: optionalStringField(),\n    depth: optionalNumberField(),\n    ignore: optionalStringArrayField(),\n  },\n  LIST_DIR_JSON_SCHEMA,\n);\n\n/**\n * Build the agent-facing `list_dir` tool over a workspace's policy-enforced\n * {@link WorkspaceOps}: a bounded, jailed listing of one directory.\n *\n * Entries come back breadth-first (each level sorted by name) with their\n * type and — for files — size, down to `depth` levels (capped by\n * `list.maxDepth`) and at most `list.maxEntries` entries (`truncated` says\n * when the cap hit). `denyPaths` are always left out, as are the\n * `list.ignore` globs (default `node_modules`, `.git`) and any `ignore`\n * globs the model passes. Symlinks are reported as `\"symlink\"` and never\n * followed. A path outside the jail surfaces as a `WorkspacePolicyError` in\n * the result's `error` field.\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 listDir = makeListDirTool(ops);\n * const { data } = await listDir.invoke({ path: \"src\", depth: 2 });\n * for (const entry of data?.entries ?? []) console.log(entry.type, entry.path, entry.size);\n */\nexport function makeListDirTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<ListDirInput, ListDirResult> {\n  return tool<ListDirInput, ListDirResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"List a workspace directory: entries with their type and file size, \" +\n      \"breadth-first, `depth` levels deep (default 1). Dependency and VCS \" +\n      \"folders are left out unless you list them directly.\",\n    action: (input) => `Listing ${typeof input.path === \"string\" ? input.path : \".\"}`,\n    input: inputSchema,\n    execute: (input) =>\n      ops.listDir(input.path ?? \".\", {\n        ...(input.depth !== undefined ? { depth: input.depth } : {}),\n        ...(input.ignore !== undefined ? { ignore: input.ignore } : {}),\n      }),\n  });\n}\n"],"mappings":";;;;;;AAWA,MAAM,eAAe;;AAGrB,MAAM,cAAc,aAClB;CACE,MAAM,oBAAoB;CAC1B,OAAO,oBAAoB;CAC3B,QAAQ,yBAAyB;AACnC,GACA,oBACF;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,gBACd,KACA,SAC2C;CAC3C,OAAO,KAAkC;EACvC,MAAM,SAAS,QAAQ;EACvB,aACE;EAGF,SAAS,UAAU,WAAW,OAAO,MAAM,SAAS,WAAW,MAAM,OAAO;EAC5E,OAAO;EACP,UAAU,UACR,IAAI,QAAQ,MAAM,QAAQ,KAAK;GAC7B,GAAI,MAAM,UAAU,SAAY,EAAE,OAAO,MAAM,MAAM,IAAI,CAAC;GAC1D,GAAI,MAAM,WAAW,SAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;EAC/D,CAAC;CACL,CAAC;AACH"}

package/esm/tools/multi-edit.d.mts

@@ -0,0 +1,38 @@
+import { MultiEditInput, MultiEditResult } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../../packages/ai-workspace/src/tools/multi-edit.d.ts
+/**
+ * Build the agent-facing `multi_edit` tool over a workspace's policy-
+ * enforced {@link WorkspaceOps}: several exact-string replacements in one
+ * file, **atomic** — every edit applies, in order (each against the result
+ * of the previous ones), and the file is written once; or one edit fails
+ * and nothing is written.
+ *
+ * Each edit follows the `edit_file` rules: `oldString` must be found, and
+ * found exactly once unless `replaceAll`. An optional `expectHash` (from
+ * `read_file`) rejects the whole call when the file changed since it was
+ * read. A failure surfaces as a `WorkspaceEditError` in the result's
+ * `error` field, with `editIndex` naming the failing edit.
+ *
+ * @param ops - The shared, policy-enforced operation layer.
+ * @param options - Optional overrides; `name` renames the LLM-visible tool.
+ *
+ * @example
+ * const multiEdit = makeMultiEditTool(ops);
+ * const { data, error } = await multiEdit.invoke({
+ *   path: "src/cart.ts",
+ *   expectHash,
+ *   edits: [
+ *     { oldString: "let total = 0;", newString: "let total = 0n;" },
+ *     { oldString: "total += price;", newString: "total += BigInt(price);" },
+ *   ],
+ * });
+ */
+declare function makeMultiEditTool(ops: WorkspaceOps, options?: {
+  name?: string;
+}): ToolContract<MultiEditInput, MultiEditResult>;
+//#endregion
+export { makeMultiEditTool };
+//# sourceMappingURL=multi-edit.d.mts.map

package/esm/tools/multi-edit.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-edit.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/multi-edit.ts"],"mappings":";;;;;;;;;AA8JA;;;;;;;;;;;;;;;;;AAG+C;;;;;;iBAH/B,iBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA;EAAY,IAAA;AAAA,IACX,YAAA,CAAa,cAAA,EAAgB,eAAA"}

package/esm/tools/multi-edit.mjs

@@ -0,0 +1,121 @@
+import "../ops.mjs";
+import { withJsonSchema } from "./schema.mjs";
+import { MULTI_EDIT_JSON_SCHEMA } from "./json-schemas.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../../packages/ai-workspace/src/tools/multi-edit.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "multi_edit";
+/** Validate one element of `edits`. */
+function validateEdit(value, index) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return { issues: [{
+		message: `edits[${index}] must be an object`,
+		path: ["edits", index]
+	}] };
+	const candidate = value;
+	const issues = [];
+	if (typeof candidate.oldString !== "string" || candidate.oldString === "") issues.push({
+		message: `edits[${index}].oldString must be a non-empty string`,
+		path: [
+			"edits",
+			index,
+			"oldString"
+		]
+	});
+	if (typeof candidate.newString !== "string") issues.push({
+		message: `edits[${index}].newString must be a string`,
+		path: [
+			"edits",
+			index,
+			"newString"
+		]
+	});
+	if (candidate.replaceAll !== void 0 && typeof candidate.replaceAll !== "boolean") issues.push({
+		message: `edits[${index}].replaceAll must be a boolean when provided`,
+		path: [
+			"edits",
+			index,
+			"replaceAll"
+		]
+	});
+	if (issues.length > 0 || typeof candidate.oldString !== "string" || typeof candidate.newString !== "string") return { issues };
+	return { edit: {
+		oldString: candidate.oldString,
+		newString: candidate.newString,
+		...candidate.replaceAll === true ? { replaceAll: true } : {}
+	} };
+}
+/** Input schema for the `multi_edit` tool. */
+const inputSchema = withJsonSchema({ "~standard": {
+	version: 1,
+	vendor: "ai-workspace",
+	validate(value) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) return { issues: [{ message: "input must be an object" }] };
+		const candidate = value;
+		const issues = [];
+		const edits = [];
+		if (typeof candidate.path !== "string" || candidate.path === "") issues.push({
+			message: "\"path\" must be a non-empty string",
+			path: ["path"]
+		});
+		if (candidate.expectHash !== void 0 && typeof candidate.expectHash !== "string") issues.push({
+			message: "\"expectHash\" must be a string when provided",
+			path: ["expectHash"]
+		});
+		if (!Array.isArray(candidate.edits) || candidate.edits.length === 0 || candidate.edits.length > 100) issues.push({
+			message: `"edits" must be an array of 1 to ${100} edits`,
+			path: ["edits"]
+		});
+		else candidate.edits.forEach((item, index) => {
+			const outcome = validateEdit(item, index);
+			if ("issues" in outcome) issues.push(...outcome.issues);
+			else edits.push(outcome.edit);
+		});
+		if (issues.length > 0 || typeof candidate.path !== "string") return { issues };
+		return { value: {
+			path: candidate.path,
+			edits,
+			...typeof candidate.expectHash === "string" ? { expectHash: candidate.expectHash } : {}
+		} };
+	}
+} }, MULTI_EDIT_JSON_SCHEMA);
+/**
+* Build the agent-facing `multi_edit` tool over a workspace's policy-
+* enforced {@link WorkspaceOps}: several exact-string replacements in one
+* file, **atomic** — every edit applies, in order (each against the result
+* of the previous ones), and the file is written once; or one edit fails
+* and nothing is written.
+*
+* Each edit follows the `edit_file` rules: `oldString` must be found, and
+* found exactly once unless `replaceAll`. An optional `expectHash` (from
+* `read_file`) rejects the whole call when the file changed since it was
+* read. A failure surfaces as a `WorkspaceEditError` in the result's
+* `error` field, with `editIndex` naming the failing edit.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const multiEdit = makeMultiEditTool(ops);
+* const { data, error } = await multiEdit.invoke({
+*   path: "src/cart.ts",
+*   expectHash,
+*   edits: [
+*     { oldString: "let total = 0;", newString: "let total = 0n;" },
+*     { oldString: "total += price;", newString: "total += BigInt(price);" },
+*   ],
+* });
+*/
+function makeMultiEditTool(ops, options) {
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Make several exact-string replacements in one workspace file at once. Edits apply in order, each to the result of the previous; if any edit fails (text not found, or not unique without replaceAll) none are applied. Pass expectHash (from read_file) to reject the call if the file changed since you read it.",
+		action: (input) => `Editing ${typeof input.path === "string" ? input.path : "a file"}`,
+		input: inputSchema,
+		execute: (input) => ops.multiEdit(input)
+	});
+}
+
+//#endregion
+export { makeMultiEditTool };
+//# sourceMappingURL=multi-edit.mjs.map

package/esm/tools/multi-edit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-edit.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/multi-edit.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { MAX_MULTI_EDITS } from \"../ops\";\nimport type {\n  MultiEditInput,\n  MultiEditOperation,\n  MultiEditResult,\n  WorkspaceOps,\n} from \"../contracts\";\nimport { MULTI_EDIT_JSON_SCHEMA } from \"./json-schemas\";\nimport { withJsonSchema } from \"./schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"multi_edit\";\n\n/** Validate one element of `edits`. */\nfunction validateEdit(\n  value: unknown,\n  index: number,\n): { edit: MultiEditOperation } | { issues: StandardSchemaV1.Issue[] } {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    return { issues: [{ message: `edits[${index}] must be an object`, path: [\"edits\", index] }] };\n  }\n\n  const candidate = value as Record<string, unknown>;\n  const issues: StandardSchemaV1.Issue[] = [];\n\n  if (typeof candidate.oldString !== \"string\" || candidate.oldString === \"\") {\n    issues.push({\n      message: `edits[${index}].oldString must be a non-empty string`,\n      path: [\"edits\", index, \"oldString\"],\n    });\n  }\n\n  if (typeof candidate.newString !== \"string\") {\n    issues.push({\n      message: `edits[${index}].newString must be a string`,\n      path: [\"edits\", index, \"newString\"],\n    });\n  }\n\n  if (candidate.replaceAll !== undefined && typeof candidate.replaceAll !== \"boolean\") {\n    issues.push({\n      message: `edits[${index}].replaceAll must be a boolean when provided`,\n      path: [\"edits\", index, \"replaceAll\"],\n    });\n  }\n\n  if (\n    issues.length > 0 ||\n    typeof candidate.oldString !== \"string\" ||\n    typeof candidate.newString !== \"string\"\n  ) {\n    return { issues };\n  }\n\n  return {\n    edit: {\n      oldString: candidate.oldString,\n      newString: candidate.newString,\n      ...(candidate.replaceAll === true ? { replaceAll: true } : {}),\n    },\n  };\n}\n\n/** Input schema for the `multi_edit` tool. */\nconst inputSchema = withJsonSchema<MultiEditInput>(\n  {\n    \"~standard\": {\n      version: 1,\n      vendor: \"ai-workspace\",\n      validate(value) {\n        if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n          return { issues: [{ message: \"input must be an object\" }] };\n        }\n\n        const candidate = value as Record<string, unknown>;\n        const issues: StandardSchemaV1.Issue[] = [];\n        const edits: MultiEditOperation[] = [];\n\n        if (typeof candidate.path !== \"string\" || candidate.path === \"\") {\n          issues.push({ message: '\"path\" must be a non-empty string', path: [\"path\"] });\n        }\n\n        if (candidate.expectHash !== undefined && typeof candidate.expectHash !== \"string\") {\n          issues.push({\n            message: '\"expectHash\" must be a string when provided',\n            path: [\"expectHash\"],\n          });\n        }\n\n        if (\n          !Array.isArray(candidate.edits) ||\n          candidate.edits.length === 0 ||\n          candidate.edits.length > MAX_MULTI_EDITS\n        ) {\n          issues.push({\n            message: `\"edits\" must be an array of 1 to ${MAX_MULTI_EDITS} edits`,\n            path: [\"edits\"],\n          });\n        } else {\n          candidate.edits.forEach((item: unknown, index: number) => {\n            const outcome = validateEdit(item, index);\n\n            if (\"issues\" in outcome) {\n              issues.push(...outcome.issues);\n            } else {\n              edits.push(outcome.edit);\n            }\n          });\n        }\n\n        if (issues.length > 0 || typeof candidate.path !== \"string\") {\n          return { issues };\n        }\n\n        return {\n          value: {\n            path: candidate.path,\n            edits,\n            ...(typeof candidate.expectHash === \"string\"\n              ? { expectHash: candidate.expectHash }\n              : {}),\n          },\n        };\n      },\n    },\n  },\n  MULTI_EDIT_JSON_SCHEMA,\n);\n\n/**\n * Build the agent-facing `multi_edit` tool over a workspace's policy-\n * enforced {@link WorkspaceOps}: several exact-string replacements in one\n * file, **atomic** — every edit applies, in order (each against the result\n * of the previous ones), and the file is written once; or one edit fails\n * and nothing is written.\n *\n * Each edit follows the `edit_file` rules: `oldString` must be found, and\n * found exactly once unless `replaceAll`. An optional `expectHash` (from\n * `read_file`) rejects the whole call when the file changed since it was\n * read. A failure surfaces as a `WorkspaceEditError` in the result's\n * `error` field, with `editIndex` naming the failing edit.\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 multiEdit = makeMultiEditTool(ops);\n * const { data, error } = await multiEdit.invoke({\n *   path: \"src/cart.ts\",\n *   expectHash,\n *   edits: [\n *     { oldString: \"let total = 0;\", newString: \"let total = 0n;\" },\n *     { oldString: \"total += price;\", newString: \"total += BigInt(price);\" },\n *   ],\n * });\n */\nexport function makeMultiEditTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<MultiEditInput, MultiEditResult> {\n  return tool<MultiEditInput, MultiEditResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Make several exact-string replacements in one workspace file at once. \" +\n      \"Edits apply in order, each to the result of the previous; if any \" +\n      \"edit fails (text not found, or not unique without replaceAll) none \" +\n      \"are applied. Pass expectHash (from read_file) to reject the call if \" +\n      \"the file changed since you read it.\",\n    action: (input) => `Editing ${typeof input.path === \"string\" ? input.path : \"a file\"}`,\n    input: inputSchema,\n    execute: (input) => ops.multiEdit(input),\n  });\n}\n"],"mappings":";;;;;;;AAaA,MAAM,eAAe;;AAGrB,SAAS,aACP,OACA,OACqE;CACrE,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO,EAAE,QAAQ,CAAC;EAAE,SAAS,SAAS,MAAM;EAAsB,MAAM,CAAC,SAAS,KAAK;CAAE,CAAC,EAAE;CAG9F,MAAM,YAAY;CAClB,MAAM,SAAmC,CAAC;CAE1C,IAAI,OAAO,UAAU,cAAc,YAAY,UAAU,cAAc,IACrE,OAAO,KAAK;EACV,SAAS,SAAS,MAAM;EACxB,MAAM;GAAC;GAAS;GAAO;EAAW;CACpC,CAAC;CAGH,IAAI,OAAO,UAAU,cAAc,UACjC,OAAO,KAAK;EACV,SAAS,SAAS,MAAM;EACxB,MAAM;GAAC;GAAS;GAAO;EAAW;CACpC,CAAC;CAGH,IAAI,UAAU,eAAe,UAAa,OAAO,UAAU,eAAe,WACxE,OAAO,KAAK;EACV,SAAS,SAAS,MAAM;EACxB,MAAM;GAAC;GAAS;GAAO;EAAY;CACrC,CAAC;CAGH,IACE,OAAO,SAAS,KAChB,OAAO,UAAU,cAAc,YAC/B,OAAO,UAAU,cAAc,UAE/B,OAAO,EAAE,OAAO;CAGlB,OAAO,EACL,MAAM;EACJ,WAAW,UAAU;EACrB,WAAW,UAAU;EACrB,GAAI,UAAU,eAAe,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;CAC9D,EACF;AACF;;AAGA,MAAM,cAAc,eAClB,EACE,aAAa;CACX,SAAS;CACT,QAAQ;CACR,SAAS,OAAO;EACd,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,0BAA0B,CAAC,EAAE;EAG5D,MAAM,YAAY;EAClB,MAAM,SAAmC,CAAC;EAC1C,MAAM,QAA8B,CAAC;EAErC,IAAI,OAAO,UAAU,SAAS,YAAY,UAAU,SAAS,IAC3D,OAAO,KAAK;GAAE,SAAS;GAAqC,MAAM,CAAC,MAAM;EAAE,CAAC;EAG9E,IAAI,UAAU,eAAe,UAAa,OAAO,UAAU,eAAe,UACxE,OAAO,KAAK;GACV,SAAS;GACT,MAAM,CAAC,YAAY;EACrB,CAAC;EAGH,IACE,CAAC,MAAM,QAAQ,UAAU,KAAK,KAC9B,UAAU,MAAM,WAAW,KAC3B,UAAU,MAAM,cAEhB,OAAO,KAAK;GACV,SAAS,wCAAoD;GAC7D,MAAM,CAAC,OAAO;EAChB,CAAC;OAED,UAAU,MAAM,SAAS,MAAe,UAAkB;GACxD,MAAM,UAAU,aAAa,MAAM,KAAK;GAExC,IAAI,YAAY,SACd,OAAO,KAAK,GAAG,QAAQ,MAAM;QAE7B,MAAM,KAAK,QAAQ,IAAI;EAE3B,CAAC;EAGH,IAAI,OAAO,SAAS,KAAK,OAAO,UAAU,SAAS,UACjD,OAAO,EAAE,OAAO;EAGlB,OAAO,EACL,OAAO;GACL,MAAM,UAAU;GAChB;GACA,GAAI,OAAO,UAAU,eAAe,WAChC,EAAE,YAAY,UAAU,WAAW,IACnC,CAAC;EACP,EACF;CACF;AACF,EACF,GACA,sBACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,kBACd,KACA,SAC+C;CAC/C,OAAO,KAAsC;EAC3C,MAAM,SAAS,QAAQ;EACvB,aACE;EAKF,SAAS,UAAU,WAAW,OAAO,MAAM,SAAS,WAAW,MAAM,OAAO;EAC5E,OAAO;EACP,UAAU,UAAU,IAAI,UAAU,KAAK;CACzC,CAAC;AACH"}

package/esm/tools/read-file.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"read-file.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/read-file.ts"],"mappings":";;;;;;;;;AAsCA;;;;;;;;;;;;;;;;;AAG6C;;;iBAH7B,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA;EAAY,IAAA;AAAA,IACX,YAAA,CAAa,aAAA,EAAe,cAAA"}
+{"version":3,"file":"read-file.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/read-file.ts"],"mappings":";;;;;;;;;AA0CA;;;;;;;;;;;;;;;;;AAG6C;;;iBAH7B,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA;EAAY,IAAA;AAAA,IACX,YAAA,CAAa,aAAA,EAAe,cAAA"}

package/esm/tools/read-file.mjs

@@ -1,4 +1,5 @@
 import { objectSchema, optionalNumberField, stringField } from "./schema.mjs";
+import { READ_FILE_JSON_SCHEMA } from "./json-schemas.mjs";
 import { tool } from "@warlock.js/ai";
 
 //#region ../../packages/ai-workspace/src/tools/read-file.ts
@@ -9,7 +10,7 @@ const inputSchema = objectSchema({
 	path: stringField(),
 	startLine: optionalNumberField(),
 	limit: optionalNumberField()
-});
+}, READ_FILE_JSON_SCHEMA);
 /**
 * Build the agent-facing `read_file` tool over a workspace's policy-
 * enforced {@link WorkspaceOps}.

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

@@ -1 +1 @@
-{"version":3,"file":"read-file.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/read-file.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { objectSchema, optionalNumberField, stringField } from \"./schema\";\nimport type { ReadFileInput, ReadFileResult, WorkspaceOps } from \"../contracts\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"read_file\";\n\n/** Input schema for the `read_file` tool. */\nconst inputSchema = objectSchema<ReadFileInput>({\n  path: stringField(),\n  startLine: optionalNumberField(),\n  limit: optionalNumberField(),\n});\n\n/**\n * Build the agent-facing `read_file` tool over a workspace's policy-\n * enforced {@link WorkspaceOps}.\n *\n * The tool validates `{ path, startLine?, limit? }` against a Standard\n * Schema, then delegates to `ops.readFile`, mapping the result into the\n * agent wire shape {@link ReadFileResult} — the full file's `hash` an\n * agent must carry into a later `edit_file` (read-before-edit), plus the\n * `startLine` / `endLine` / `truncated` / `bytesCapped` window metadata.\n * The returned `content` never exceeds the policy's `read.maxBytes`.\n *\n * **Errors flow as data.** Policy violations (a jail escape) are thrown\n * by `ops`; the `tool()` wrapper catches them and surfaces them in the\n * returned `{ error }` field — `invoke()` never throws — so the agent can\n * read the failure and self-correct.\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 readTool = makeReadFileTool(ops);\n * const { data, error } = await readTool.invoke({ path: \"src/index.ts\" });\n * if (!error) console.log(data.hash); // feed into edit_file's expectHash\n */\nexport function makeReadFileTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<ReadFileInput, ReadFileResult> {\n  return tool<ReadFileInput, ReadFileResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Read a file from the workspace, returning a numbered line window plus \" +\n      \"the file's content hash. Pass the hash to edit_file's expectHash to \" +\n      \"guard against editing a stale version. Use startLine/limit to page \" +\n      \"through large files. Output is byte-capped by the workspace policy; \" +\n      \"when bytesCapped is true the last returned line may be cut short.\",\n    input: inputSchema,\n    async execute(input) {\n      // The ops layer owns the window and byte-cap arithmetic, so the tool\n      // and the direct `readFile()` return identical results for the same\n      // arguments.\n      return ops.readFile(input.path, {\n        offset: input.startLine !== undefined ? Math.max(1, input.startLine) : 1,\n        limit: input.limit,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;AAKA,MAAM,eAAe;;AAGrB,MAAM,cAAc,aAA4B;CAC9C,MAAM,YAAY;CAClB,WAAW,oBAAoB;CAC/B,OAAO,oBAAoB;AAC7B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA0BD,SAAgB,iBACd,KACA,SAC6C;CAC7C,OAAO,KAAoC;EACzC,MAAM,SAAS,QAAQ;EACvB,aACE;EAKF,OAAO;EACP,MAAM,QAAQ,OAAO;GAInB,OAAO,IAAI,SAAS,MAAM,MAAM;IAC9B,QAAQ,MAAM,cAAc,SAAY,KAAK,IAAI,GAAG,MAAM,SAAS,IAAI;IACvE,OAAO,MAAM;GACf,CAAC;EACH;CACF,CAAC;AACH"}
+{"version":3,"file":"read-file.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/read-file.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { objectSchema, optionalNumberField, stringField } from \"./schema\";\nimport { READ_FILE_JSON_SCHEMA } from \"./json-schemas\";\nimport type { ReadFileInput, ReadFileResult, WorkspaceOps } from \"../contracts\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"read_file\";\n\n/** Input schema for the `read_file` tool. */\nconst inputSchema = objectSchema<ReadFileInput>(\n  {\n    path: stringField(),\n    startLine: optionalNumberField(),\n    limit: optionalNumberField(),\n  },\n  READ_FILE_JSON_SCHEMA,\n);\n\n/**\n * Build the agent-facing `read_file` tool over a workspace's policy-\n * enforced {@link WorkspaceOps}.\n *\n * The tool validates `{ path, startLine?, limit? }` against a Standard\n * Schema, then delegates to `ops.readFile`, mapping the result into the\n * agent wire shape {@link ReadFileResult} — the full file's `hash` an\n * agent must carry into a later `edit_file` (read-before-edit), plus the\n * `startLine` / `endLine` / `truncated` / `bytesCapped` window metadata.\n * The returned `content` never exceeds the policy's `read.maxBytes`.\n *\n * **Errors flow as data.** Policy violations (a jail escape) are thrown\n * by `ops`; the `tool()` wrapper catches them and surfaces them in the\n * returned `{ error }` field — `invoke()` never throws — so the agent can\n * read the failure and self-correct.\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 readTool = makeReadFileTool(ops);\n * const { data, error } = await readTool.invoke({ path: \"src/index.ts\" });\n * if (!error) console.log(data.hash); // feed into edit_file's expectHash\n */\nexport function makeReadFileTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<ReadFileInput, ReadFileResult> {\n  return tool<ReadFileInput, ReadFileResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Read a file from the workspace, returning a numbered line window plus \" +\n      \"the file's content hash. Pass the hash to edit_file's expectHash to \" +\n      \"guard against editing a stale version. Use startLine/limit to page \" +\n      \"through large files. Output is byte-capped by the workspace policy; \" +\n      \"when bytesCapped is true the last returned line may be cut short.\",\n    input: inputSchema,\n    async execute(input) {\n      // The ops layer owns the window and byte-cap arithmetic, so the tool\n      // and the direct `readFile()` return identical results for the same\n      // arguments.\n      return ops.readFile(input.path, {\n        offset: input.startLine !== undefined ? Math.max(1, input.startLine) : 1,\n        limit: input.limit,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;AAMA,MAAM,eAAe;;AAGrB,MAAM,cAAc,aAClB;CACE,MAAM,YAAY;CAClB,WAAW,oBAAoB;CAC/B,OAAO,oBAAoB;AAC7B,GACA,qBACF;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,iBACd,KACA,SAC6C;CAC7C,OAAO,KAAoC;EACzC,MAAM,SAAS,QAAQ;EACvB,aACE;EAKF,OAAO;EACP,MAAM,QAAQ,OAAO;GAInB,OAAO,IAAI,SAAS,MAAM,MAAM;IAC9B,QAAQ,MAAM,cAAc,SAAY,KAAK,IAAI,GAAG,MAAM,SAAS,IAAI;IACvE,OAAO,MAAM;GACf,CAAC;EACH;CACF,CAAC;AACH"}

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

@@ -1,4 +1,4 @@
-import { RunShellInput, RunShellResult } from "../contracts/tool-io.type.mjs";
+import { RunShellBackgroundResult, RunShellInput, RunShellResult } from "../contracts/tool-io.type.mjs";
 import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
 import { ToolContract } from "@warlock.js/ai";
 
@@ -7,25 +7,41 @@ import { ToolContract } from "@warlock.js/ai";
 interface MakeRunShellToolOptions {
   /** Override the tool name exposed to the LLM (default `"run_shell"`). */
   name?: string;
+  /**
+   * Upper bound for a model-supplied `timeoutMs` on a foreground command —
+   * the model can lower the timeout, never raise it past this. The
+   * workspace passes its `shell.timeoutMs`.
+   */
+  maxTimeoutMs?: number;
+  /**
+   * Accept `background: true` and start the command as a background job
+   * (`ops.startShell`), returning a {@link RunShellBackgroundResult}. The
+   * workspace sets it when the policy has `shell.background`. Default
+   * `false`: a background request is refused.
+   */
+  background?: boolean;
 }
 /**
- * Build the `run_shell` tool — a {@link ToolContract} that runs a single
- * shell command through the policy-enforced {@link WorkspaceOps} layer.
+ * Build the `run_shell` tool — a {@link ToolContract} that runs a command
+ * line through the policy-enforced {@link WorkspaceOps} layer.
  *
- * The command's leading executable basename is gated against the shell
- * allow/deny policy by `ops.exec`; a blocked command throws a
- * `WorkspacePolicyError` which the `tool()` runtime catches and surfaces
- * in the result's `error` field (never a thrown run-killer), so the agent
- * reads the refusal as tool data and self-corrects. A command that runs
- * but exits non-zero is *not* an error — its `exitCode`/`stderr` come back
- * in `data` for the agent to inspect.
+ * Every command in the line is checked against the shell policy by
+ * `ops.exec`; a refused line throws a `WorkspacePolicyError` (with a
+ * `reason` and a message that says how to fix the command) which the
+ * `tool()` runtime catches and surfaces in the result's `error` field
+ * (never a thrown run-killer), so the agent reads the refusal as tool data
+ * and self-corrects. A command that runs but exits non-zero is *not* an
+ * error — its `exitCode`/`stderr` come back in `data` for the agent to
+ * inspect.
  *
  * The agent run's cancellation `signal` (from the dispatch `ctx`) is passed
  * to `ops.exec` per invocation: a cancelled run never starts the command,
  * and one cancelled mid-command kills its process tree (`cancelled: true`).
+ * A background command (`background: true`, when enabled) belongs to the
+ * workspace instead and keeps running after the call returns.
  *
  * @param ops - The policy-enforced operation layer to delegate `exec` to.
- * @param options - Optional tool-name override.
+ * @param options - Tool-name override, timeout cap and background support.
  *
  * @example
  * const runShell = makeRunShellTool(ops);
@@ -33,7 +49,13 @@ interface MakeRunShellToolOptions {
  * if (error) handleDenied(error);
  * else console.log(data.exitCode, data.stdout);
  */
-declare function makeRunShellTool(ops: WorkspaceOps, options?: MakeRunShellToolOptions): ToolContract<RunShellInput, RunShellResult>;
+declare function makeRunShellTool(ops: WorkspaceOps, options?: MakeRunShellToolOptions & {
+  background?: false;
+}): ToolContract<RunShellInput, RunShellResult>;
+declare function makeRunShellTool(ops: WorkspaceOps, options: MakeRunShellToolOptions & {
+  background: true;
+}): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;
+declare function makeRunShellTool(ops: WorkspaceOps, options?: MakeRunShellToolOptions): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;
 //#endregion
 export { MakeRunShellToolOptions, makeRunShellTool };
 //# sourceMappingURL=run-shell.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"run-shell.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-shell.ts"],"mappings":";;;;;;UAsDiB,uBAAA;;EAEf,IAAI;AAAA;;;;AAAA;AA4BN;;;;;;;;;;;;;;;;;;AAG6C;;;iBAH7B,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,uBAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA"}
+{"version":3,"file":"run-shell.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-shell.ts"],"mappings":";;;;;;UA2EiB,uBAAA;;EAEf,IAAA;EAFe;;;;;EAQf,YAAA;EAOA;;AAAU;AAwCZ;;;EAxCE,UAAA;AAAA;;;;;;;;;;;;;;;AA2C2C;AAC7C;;;;;;;;;;;;;iBAJgB,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,uBAAA;EAA4B,UAAA;AAAA,IACrC,YAAA,CAAa,aAAA,EAAe,cAAA;AAAA,iBACf,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,EAAS,uBAAA;EAA4B,UAAA;AAAA,IACpC,YAAA,CAAa,aAAA,EAAe,cAAA,GAAiB,wBAAA;AAAA,iBAChC,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,uBAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA,GAAiB,wBAAA"}