@warlock.js/ai-workspace 4.5.0

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

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

package/esm/tools/edit-file.mjs

@@ -0,0 +1,57 @@
+import { objectSchema, optionalBooleanField, optionalStringField, stringField } from "./schema.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/edit-file.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "edit_file";
+/** Input schema for the `edit_file` tool. */
+const inputSchema = objectSchema({
+	path: stringField(),
+	oldString: stringField(),
+	newString: stringField(),
+	replaceAll: optionalBooleanField(),
+	expectHash: optionalStringField()
+});
+/**
+* Build the agent-facing `edit_file` tool over a workspace's policy-
+* enforced {@link WorkspaceOps}.
+*
+* The tool validates `{ path, oldString, newString, replaceAll?,
+* expectHash? }` against a Standard Schema, then delegates to
+* `ops.editFile`, which applies the exact-string replacement under the
+* read-before-edit guard and returns the replacement count plus the
+* post-edit `hash`.
+*
+* **Errors flow as data.** A non-unique `oldString` (without
+* `replaceAll`), a missing `oldString`, or a stale `expectHash` cause
+* `ops` to throw a `WorkspaceEditError`; the `tool()` wrapper catches it
+* and surfaces it in the returned `{ error }` field — `invoke()` never
+* throws — so the agent can re-read and retry.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const editTool = makeEditFileTool(ops);
+* const { data, error } = await editTool.invoke({
+*   path: "src/index.ts",
+*   oldString: "const a = 1;",
+*   newString: "const a = 2;",
+*   expectHash,
+* });
+* if (error) console.warn(error.message); // e.g. stale-hash → re-read
+*/
+function makeEditFileTool(ops, options) {
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Replace an exact substring in a workspace file. oldString must match uniquely unless replaceAll is set. Pass expectHash (from read_file) to reject the edit if the file changed since you read it. Returns the number of replacements and the new content hash.",
+		input: inputSchema,
+		async execute(input) {
+			return ops.editFile(input);
+		}
+	});
+}
+
+//#endregion
+export { makeEditFileTool };
+//# sourceMappingURL=edit-file.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"edit-file.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/edit-file.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport {\n  objectSchema,\n  optionalBooleanField,\n  optionalStringField,\n  stringField,\n} from \"./schema\";\nimport type { EditFileInput, EditFileResult, WorkspaceOps } from \"../contracts\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"edit_file\";\n\n/** Input schema for the `edit_file` tool. */\nconst inputSchema = objectSchema<EditFileInput>({\n  path: stringField(),\n  oldString: stringField(),\n  newString: stringField(),\n  replaceAll: optionalBooleanField(),\n  expectHash: optionalStringField(),\n});\n\n/**\n * Build the agent-facing `edit_file` tool over a workspace's policy-\n * enforced {@link WorkspaceOps}.\n *\n * The tool validates `{ path, oldString, newString, replaceAll?,\n * expectHash? }` against a Standard Schema, then delegates to\n * `ops.editFile`, which applies the exact-string replacement under the\n * read-before-edit guard and returns the replacement count plus the\n * post-edit `hash`.\n *\n * **Errors flow as data.** A non-unique `oldString` (without\n * `replaceAll`), a missing `oldString`, or a stale `expectHash` cause\n * `ops` to throw a `WorkspaceEditError`; the `tool()` wrapper catches it\n * and surfaces it in the returned `{ error }` field — `invoke()` never\n * throws — so the agent can re-read and retry.\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 editTool = makeEditFileTool(ops);\n * const { data, error } = await editTool.invoke({\n *   path: \"src/index.ts\",\n *   oldString: \"const a = 1;\",\n *   newString: \"const a = 2;\",\n *   expectHash,\n * });\n * if (error) console.warn(error.message); // e.g. stale-hash → re-read\n */\nexport function makeEditFileTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<EditFileInput, EditFileResult> {\n  return tool<EditFileInput, EditFileResult>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Replace an exact substring in a workspace file. oldString must match \" +\n      \"uniquely unless replaceAll is set. Pass expectHash (from read_file) to \" +\n      \"reject the edit if the file changed since you read it. Returns the \" +\n      \"number of replacements and the new content hash.\",\n    input: inputSchema,\n    async execute(input) {\n      return ops.editFile(input);\n    },\n  });\n}\n"],"mappings":";;;;;AAUA,MAAM,eAAe;;AAGrB,MAAM,cAAc,aAA4B;CAC9C,MAAM,YAAY;CAClB,WAAW,YAAY;CACvB,WAAW,YAAY;CACvB,YAAY,qBAAqB;CACjC,YAAY,oBAAoB;AAClC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BD,SAAgB,iBACd,KACA,SAC6C;CAC7C,OAAO,KAAoC;EACzC,MAAM,SAAS,QAAQ;EACvB,aACE;EAIF,OAAO;EACP,MAAM,QAAQ,OAAO;GACnB,OAAO,IAAI,SAAS,KAAK;EAC3B;CACF,CAAC;AACH"}

package/esm/tools/glob.d.mts

@@ -0,0 +1,37 @@
+import { GlobInput, GlobResult } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/glob.d.ts
+/** Options accepted by {@link makeGlobTool} to customize the vended tool. */
+interface MakeGlobToolOptions {
+  /**
+   * Override the tool name the LLM sees. Defaults to `"glob"`. Use a
+   * custom name when wiring several workspaces into one agent so each
+   * path-match surface is addressable.
+   */
+  name?: string;
+}
+/**
+ * Build the agent-facing `glob` tool — resolve a glob pattern to the
+ * matching workspace-relative paths within the jail. The returned
+ * {@link ToolContract} validates the LLM's arguments, delegates to
+ * {@link WorkspaceOps.glob} (which returns a bare sorted `string[]`), and
+ * wraps the result in a {@link GlobResult} so the agent always reads a
+ * stable `{ paths }` envelope. The jail and `denyPaths` filtering are
+ * enforced in the shared ops layer; a policy violation surfaces as typed
+ * tool-error *data* via the runtime's `invoke()` wrapper.
+ *
+ * @param ops - The policy-enforced operation layer to delegate to.
+ * @param options - Optional `{ name }` override for the vended tool name.
+ * @returns A {@link ToolContract} the agent can call as `glob`.
+ *
+ * @example
+ * const glob = makeGlobTool(ops);
+ * const { data } = await glob.invoke({ pattern: "src/models/**\/*.ts" });
+ * console.log(data?.paths);
+ */
+declare function makeGlobTool(ops: WorkspaceOps, options?: MakeGlobToolOptions): ToolContract<GlobInput, GlobResult>;
+//#endregion
+export { MakeGlobToolOptions, makeGlobTool };
+//# sourceMappingURL=glob.d.mts.map

package/esm/tools/glob.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/glob.ts"],"mappings":";;;;;;UAKiB,mBAAA;;;AAAjB;;;EAME,IAAI;AAAA;AAgCN;;;;;;;;;;;;;;;;;;AAGqC;AAHrC,iBAAgB,YAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,mBAAA,GACT,YAAA,CAAa,SAAA,EAAW,UAAA"}

package/esm/tools/glob.mjs

@@ -0,0 +1,45 @@
+import { objectSchema, stringField } from "./schema.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/glob.ts
+/**
+* Standard Schema for {@link GlobInput} — a single required `pattern`
+* string. Built on the package's shared, dependency-free schema builders
+* (no schema library, matching the validator idiom the `@warlock.js/ai`
+* tool runtime expects).
+*/
+const globInputSchema = objectSchema({ pattern: stringField() });
+/**
+* Build the agent-facing `glob` tool — resolve a glob pattern to the
+* matching workspace-relative paths within the jail. The returned
+* {@link ToolContract} validates the LLM's arguments, delegates to
+* {@link WorkspaceOps.glob} (which returns a bare sorted `string[]`), and
+* wraps the result in a {@link GlobResult} so the agent always reads a
+* stable `{ paths }` envelope. The jail and `denyPaths` filtering are
+* enforced in the shared ops layer; a policy violation surfaces as typed
+* tool-error *data* via the runtime's `invoke()` wrapper.
+*
+* @param ops - The policy-enforced operation layer to delegate to.
+* @param options - Optional `{ name }` override for the vended tool name.
+* @returns A {@link ToolContract} the agent can call as `glob`.
+*
+* @example
+* const glob = makeGlobTool(ops);
+* const { data } = await glob.invoke({ pattern: "src/models/**\/*.ts" });
+* console.log(data?.paths);
+*/
+function makeGlobTool(ops, options) {
+	return tool({
+		name: options?.name ?? "glob",
+		description: "Find files in the workspace whose path matches a glob pattern (supports `*`, `**`, and `?`). Returns the matching workspace-relative paths, sorted.",
+		action: (input) => `Finding files matching ${input.pattern}`,
+		input: globInputSchema,
+		async execute(input) {
+			return { paths: await ops.glob(input.pattern) };
+		}
+	});
+}
+
+//#endregion
+export { makeGlobTool };
+//# sourceMappingURL=glob.mjs.map

package/esm/tools/glob.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/glob.ts"],"sourcesContent":["import { type ToolContract, tool } from \"@warlock.js/ai\";\nimport { objectSchema, stringField } from \"./schema\";\nimport type { GlobInput, GlobResult, WorkspaceOps } from \"../contracts\";\n\n/** Options accepted by {@link makeGlobTool} to customize the vended tool. */\nexport interface MakeGlobToolOptions {\n  /**\n   * Override the tool name the LLM sees. Defaults to `\"glob\"`. Use a\n   * custom name when wiring several workspaces into one agent so each\n   * path-match surface is addressable.\n   */\n  name?: string;\n}\n\n/**\n * Standard Schema for {@link GlobInput} — a single required `pattern`\n * string. Built on the package's shared, dependency-free schema builders\n * (no schema library, matching the validator idiom the `@warlock.js/ai`\n * tool runtime expects).\n */\nconst globInputSchema = objectSchema<GlobInput>({\n  pattern: stringField(),\n});\n\n/**\n * Build the agent-facing `glob` tool — resolve a glob pattern to the\n * matching workspace-relative paths within the jail. The returned\n * {@link ToolContract} validates the LLM's arguments, delegates to\n * {@link WorkspaceOps.glob} (which returns a bare sorted `string[]`), and\n * wraps the result in a {@link GlobResult} so the agent always reads a\n * stable `{ paths }` envelope. The jail and `denyPaths` filtering are\n * enforced in the shared ops layer; a policy violation surfaces as typed\n * tool-error *data* via the runtime's `invoke()` wrapper.\n *\n * @param ops - The policy-enforced operation layer to delegate to.\n * @param options - Optional `{ name }` override for the vended tool name.\n * @returns A {@link ToolContract} the agent can call as `glob`.\n *\n * @example\n * const glob = makeGlobTool(ops);\n * const { data } = await glob.invoke({ pattern: \"src/models/**\\/*.ts\" });\n * console.log(data?.paths);\n */\nexport function makeGlobTool(\n  ops: WorkspaceOps,\n  options?: MakeGlobToolOptions,\n): ToolContract<GlobInput, GlobResult> {\n  return tool<GlobInput, GlobResult>({\n    name: options?.name ?? \"glob\",\n    description:\n      \"Find files in the workspace whose path matches a glob pattern \" +\n      \"(supports `*`, `**`, and `?`). Returns the matching \" +\n      \"workspace-relative paths, sorted.\",\n    action: (input) => `Finding files matching ${input.pattern}`,\n    input: globInputSchema,\n    async execute(input) {\n      const paths = await ops.glob(input.pattern);\n\n      return { paths };\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;AAoBA,MAAM,kBAAkB,aAAwB,EAC9C,SAAS,YAAY,EACvB,CAAC;;;;;;;;;;;;;;;;;;;;AAqBD,SAAgB,aACd,KACA,SACqC;CACrC,OAAO,KAA4B;EACjC,MAAM,SAAS,QAAQ;EACvB,aACE;EAGF,SAAS,UAAU,0BAA0B,MAAM;EACnD,OAAO;EACP,MAAM,QAAQ,OAAO;GAGnB,OAAO,EAAE,aAFW,IAAI,KAAK,MAAM,OAAO,EAE3B;EACjB;CACF,CAAC;AACH"}

package/esm/tools/grep.d.mts

@@ -0,0 +1,36 @@
+import { GrepInput, GrepResult } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/grep.d.ts
+/** Options accepted by {@link makeGrepTool} to customize the vended tool. */
+interface MakeGrepToolOptions {
+  /**
+   * Override the tool name the LLM sees. Defaults to `"grep"`. Use a
+   * custom name when wiring several workspaces into one agent so each
+   * search surface is addressable.
+   */
+  name?: string;
+}
+/**
+ * Build the agent-facing `grep` tool — a regex content search across the
+ * jailed file set. The returned {@link ToolContract} validates the LLM's
+ * arguments, then delegates verbatim to {@link WorkspaceOps.grep}, so the
+ * policy jail, `denyPaths` filtering, and match cap are enforced in the
+ * single shared ops layer rather than duplicated here. A policy violation
+ * (e.g. a jail-resolution failure) surfaces as typed tool-error *data*
+ * via the runtime's `invoke()` wrapper, never as a thrown run-killer.
+ *
+ * @param ops - The policy-enforced operation layer to delegate to.
+ * @param options - Optional `{ name }` override for the vended tool name.
+ * @returns A {@link ToolContract} the agent can call as `grep`.
+ *
+ * @example
+ * const grep = makeGrepTool(ops);
+ * const { data } = await grep.invoke({ pattern: "TODO", glob: "src/*.ts" });
+ * console.log(data?.total, data?.matches);
+ */
+declare function makeGrepTool(ops: WorkspaceOps, options?: MakeGrepToolOptions): ToolContract<GrepInput, GrepResult>;
+//#endregion
+export { MakeGrepToolOptions, makeGrepTool };
+//# sourceMappingURL=grep.d.mts.map

package/esm/tools/grep.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grep.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/grep.ts"],"mappings":";;;;;;UAUiB,mBAAA;;;AAAjB;;;EAME,IAAI;AAAA;AAiCN;;;;;;;;;;;;;;;;;;AAAA,iBAAgB,YAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,mBAAA,GACT,YAAA,CAAa,SAAA,EAAW,UAAA"}

package/esm/tools/grep.mjs

@@ -0,0 +1,51 @@
+import { objectSchema, optionalBooleanField, optionalStringField, stringField } from "./schema.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/grep.ts
+/**
+* Standard Schema for {@link GrepInput} — `pattern` is a required string;
+* `glob` and `ignoreCase` are optional. Built on the package's shared,
+* dependency-free schema builders (no schema library, matching the
+* validator idiom the `@warlock.js/ai` tool runtime expects).
+*/
+const grepInputSchema = objectSchema({
+	pattern: stringField(),
+	glob: optionalStringField(),
+	ignoreCase: optionalBooleanField()
+});
+/**
+* Build the agent-facing `grep` tool — a regex content search across the
+* jailed file set. The returned {@link ToolContract} validates the LLM's
+* arguments, then delegates verbatim to {@link WorkspaceOps.grep}, so the
+* policy jail, `denyPaths` filtering, and match cap are enforced in the
+* single shared ops layer rather than duplicated here. A policy violation
+* (e.g. a jail-resolution failure) surfaces as typed tool-error *data*
+* via the runtime's `invoke()` wrapper, never as a thrown run-killer.
+*
+* @param ops - The policy-enforced operation layer to delegate to.
+* @param options - Optional `{ name }` override for the vended tool name.
+* @returns A {@link ToolContract} the agent can call as `grep`.
+*
+* @example
+* const grep = makeGrepTool(ops);
+* const { data } = await grep.invoke({ pattern: "TODO", glob: "src/*.ts" });
+* console.log(data?.total, data?.matches);
+*/
+function makeGrepTool(ops, options) {
+	return tool({
+		name: options?.name ?? "grep",
+		description: "Search file contents across the workspace for a regular-expression pattern. Optionally narrow the scanned files with a glob and match case-insensitively. Returns every matching line with its file path and 1-based line number.",
+		action: (input) => `Searching for /${input.pattern}/`,
+		input: grepInputSchema,
+		async execute(input) {
+			return ops.grep(input.pattern, {
+				glob: input.glob,
+				ignoreCase: input.ignoreCase
+			});
+		}
+	});
+}
+
+//#endregion
+export { makeGrepTool };
+//# sourceMappingURL=grep.mjs.map

package/esm/tools/grep.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"grep.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/grep.ts"],"sourcesContent":["import { type ToolContract, tool } from \"@warlock.js/ai\";\nimport {\n  objectSchema,\n  optionalBooleanField,\n  optionalStringField,\n  stringField,\n} from \"./schema\";\nimport type { GrepInput, GrepResult, WorkspaceOps } from \"../contracts\";\n\n/** Options accepted by {@link makeGrepTool} to customize the vended tool. */\nexport interface MakeGrepToolOptions {\n  /**\n   * Override the tool name the LLM sees. Defaults to `\"grep\"`. Use a\n   * custom name when wiring several workspaces into one agent so each\n   * search surface is addressable.\n   */\n  name?: string;\n}\n\n/**\n * Standard Schema for {@link GrepInput} — `pattern` is a required string;\n * `glob` and `ignoreCase` are optional. Built on the package's shared,\n * dependency-free schema builders (no schema library, matching the\n * validator idiom the `@warlock.js/ai` tool runtime expects).\n */\nconst grepInputSchema = objectSchema<GrepInput>({\n  pattern: stringField(),\n  glob: optionalStringField(),\n  ignoreCase: optionalBooleanField(),\n});\n\n/**\n * Build the agent-facing `grep` tool — a regex content search across the\n * jailed file set. The returned {@link ToolContract} validates the LLM's\n * arguments, then delegates verbatim to {@link WorkspaceOps.grep}, so the\n * policy jail, `denyPaths` filtering, and match cap are enforced in the\n * single shared ops layer rather than duplicated here. A policy violation\n * (e.g. a jail-resolution failure) surfaces as typed tool-error *data*\n * via the runtime's `invoke()` wrapper, never as a thrown run-killer.\n *\n * @param ops - The policy-enforced operation layer to delegate to.\n * @param options - Optional `{ name }` override for the vended tool name.\n * @returns A {@link ToolContract} the agent can call as `grep`.\n *\n * @example\n * const grep = makeGrepTool(ops);\n * const { data } = await grep.invoke({ pattern: \"TODO\", glob: \"src/*.ts\" });\n * console.log(data?.total, data?.matches);\n */\nexport function makeGrepTool(\n  ops: WorkspaceOps,\n  options?: MakeGrepToolOptions,\n): ToolContract<GrepInput, GrepResult> {\n  return tool<GrepInput, GrepResult>({\n    name: options?.name ?? \"grep\",\n    description:\n      \"Search file contents across the workspace for a regular-expression \" +\n      \"pattern. Optionally narrow the scanned files with a glob and match \" +\n      \"case-insensitively. Returns every matching line with its file path \" +\n      \"and 1-based line number.\",\n    action: (input) => `Searching for /${input.pattern}/`,\n    input: grepInputSchema,\n    async execute(input) {\n      return ops.grep(input.pattern, {\n        glob: input.glob,\n        ignoreCase: input.ignoreCase,\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;AAyBA,MAAM,kBAAkB,aAAwB;CAC9C,SAAS,YAAY;CACrB,MAAM,oBAAoB;CAC1B,YAAY,qBAAqB;AACnC,CAAC;;;;;;;;;;;;;;;;;;;AAoBD,SAAgB,aACd,KACA,SACqC;CACrC,OAAO,KAA4B;EACjC,MAAM,SAAS,QAAQ;EACvB,aACE;EAIF,SAAS,UAAU,kBAAkB,MAAM,QAAQ;EACnD,OAAO;EACP,MAAM,QAAQ,OAAO;GACnB,OAAO,IAAI,KAAK,MAAM,SAAS;IAC7B,MAAM,MAAM;IACZ,YAAY,MAAM;GACpB,CAAC;EACH;CACF,CAAC;AACH"}

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

@@ -0,0 +1,35 @@
+import { ReadFileInput, ReadFileResult } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/read-file.d.ts
+/**
+ * Build the agent-facing `read_file` tool over a workspace's policy-
+ * enforced {@link WorkspaceOps}.
+ *
+ * The tool validates `{ path, startLine?, limit? }` against a Standard
+ * Schema, then delegates to `ops.readFile`, mapping the result into the
+ * agent wire shape {@link ReadFileResult} — the `hash` an agent must
+ * carry into a later `edit_file` (read-before-edit), plus the `startLine`
+ * / `endLine` / `truncated` window metadata derived from the requested
+ * range and the file's `totalLines`.
+ *
+ * **Errors flow as data.** Policy violations (a jail escape) are thrown
+ * by `ops`; the `tool()` wrapper catches them and surfaces them in the
+ * returned `{ error }` field — `invoke()` never throws — so the agent can
+ * read the failure and self-correct.
+ *
+ * @param ops - The shared, policy-enforced operation layer.
+ * @param options - Optional overrides; `name` renames the LLM-visible tool.
+ *
+ * @example
+ * const readTool = makeReadFileTool(ops);
+ * const { data, error } = await readTool.invoke({ path: "src/index.ts" });
+ * if (!error) console.log(data.hash); // feed into edit_file's expectHash
+ */
+declare function makeReadFileTool(ops: WorkspaceOps, options?: {
+  name?: string;
+}): ToolContract<ReadFileInput, ReadFileResult>;
+//#endregion
+export { makeReadFileTool };
+//# sourceMappingURL=read-file.d.mts.map

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

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

package/esm/tools/read-file.mjs

@@ -0,0 +1,64 @@
+import { objectSchema, optionalNumberField, stringField } from "./schema.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/read-file.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "read_file";
+/** Input schema for the `read_file` tool. */
+const inputSchema = objectSchema({
+	path: stringField(),
+	startLine: optionalNumberField(),
+	limit: optionalNumberField()
+});
+/**
+* Build the agent-facing `read_file` tool over a workspace's policy-
+* enforced {@link WorkspaceOps}.
+*
+* The tool validates `{ path, startLine?, limit? }` against a Standard
+* Schema, then delegates to `ops.readFile`, mapping the result into the
+* agent wire shape {@link ReadFileResult} — the `hash` an agent must
+* carry into a later `edit_file` (read-before-edit), plus the `startLine`
+* / `endLine` / `truncated` window metadata derived from the requested
+* range and the file's `totalLines`.
+*
+* **Errors flow as data.** Policy violations (a jail escape) are thrown
+* by `ops`; the `tool()` wrapper catches them and surfaces them in the
+* returned `{ error }` field — `invoke()` never throws — so the agent can
+* read the failure and self-correct.
+*
+* @param ops - The shared, policy-enforced operation layer.
+* @param options - Optional overrides; `name` renames the LLM-visible tool.
+*
+* @example
+* const readTool = makeReadFileTool(ops);
+* const { data, error } = await readTool.invoke({ path: "src/index.ts" });
+* if (!error) console.log(data.hash); // feed into edit_file's expectHash
+*/
+function makeReadFileTool(ops, options) {
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Read a file from the workspace, returning a numbered line window plus the file's content hash. Pass the hash to edit_file's expectHash to guard against editing a stale version. Use startLine/limit to page through large files.",
+		input: inputSchema,
+		async execute(input) {
+			const startLine = input.startLine !== void 0 ? Math.max(1, input.startLine) : 1;
+			const { content, hash, totalLines } = await ops.readFile(input.path, {
+				offset: startLine,
+				limit: input.limit
+			});
+			const returnedLines = content.length === 0 ? 0 : content.split("\n").length;
+			const endLine = Math.min(totalLines, startLine + Math.max(returnedLines, 1) - 1);
+			return {
+				content,
+				startLine,
+				endLine,
+				totalLines,
+				truncated: endLine < totalLines,
+				hash
+			};
+		}
+	});
+}
+
+//#endregion
+export { makeReadFileTool };
+//# sourceMappingURL=read-file.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read-file.mjs","names":[],"sources":["../../../../../../../@warlock.js/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 `hash` an agent must\n * carry into a later `edit_file` (read-before-edit), plus the `startLine`\n * / `endLine` / `truncated` window metadata derived from the requested\n * range and the file's `totalLines`.\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.\",\n    input: inputSchema,\n    async execute(input) {\n      const startLine = input.startLine !== undefined ? Math.max(1, input.startLine) : 1;\n      const { content, hash, totalLines } = await ops.readFile(input.path, {\n        offset: startLine,\n        limit: input.limit,\n      });\n\n      // The window's last line is the start plus however many lines the\n      // ops layer actually returned (it caps at `limit` / the policy\n      // default), bounded by the file's end.\n      const returnedLines = content.length === 0 ? 0 : content.split(\"\\n\").length;\n      const endLine = Math.min(totalLines, startLine + Math.max(returnedLines, 1) - 1);\n      const truncated = endLine < totalLines;\n\n      return { content, startLine, endLine, totalLines, truncated, hash };\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;EAIF,OAAO;EACP,MAAM,QAAQ,OAAO;GACnB,MAAM,YAAY,MAAM,cAAc,SAAY,KAAK,IAAI,GAAG,MAAM,SAAS,IAAI;GACjF,MAAM,EAAE,SAAS,MAAM,eAAe,MAAM,IAAI,SAAS,MAAM,MAAM;IACnE,QAAQ;IACR,OAAO,MAAM;GACf,CAAC;GAKD,MAAM,gBAAgB,QAAQ,WAAW,IAAI,IAAI,QAAQ,MAAM,IAAI,CAAC,CAAC;GACrE,MAAM,UAAU,KAAK,IAAI,YAAY,YAAY,KAAK,IAAI,eAAe,CAAC,IAAI,CAAC;GAG/E,OAAO;IAAE;IAAS;IAAW;IAAS;IAAY,WAFhC,UAAU;IAEiC;GAAK;EACpE;CACF,CAAC;AACH"}

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

@@ -0,0 +1,35 @@
+import { RunShellInput, RunShellResult } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/run-shell.d.ts
+/** Options for {@link makeRunShellTool}. */
+interface MakeRunShellToolOptions {
+  /** Override the tool name exposed to the LLM (default `"run_shell"`). */
+  name?: string;
+}
+/**
+ * Build the `run_shell` tool — a {@link ToolContract} that runs a single
+ * shell command 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.
+ *
+ * @param ops - The policy-enforced operation layer to delegate `exec` to.
+ * @param options - Optional tool-name override.
+ *
+ * @example
+ * const runShell = makeRunShellTool(ops);
+ * const { data, error } = await runShell.invoke({ command: "npm run build" });
+ * if (error) handleDenied(error);
+ * else console.log(data.exitCode, data.stdout);
+ */
+declare function makeRunShellTool(ops: WorkspaceOps, options?: MakeRunShellToolOptions): ToolContract<RunShellInput, RunShellResult>;
+//#endregion
+export { MakeRunShellToolOptions, makeRunShellTool };
+//# sourceMappingURL=run-shell.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-shell.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/run-shell.ts"],"mappings":";;;;;;UAsDiB,uBAAA;;EAEf,IAAI;AAAA;;;;AAAA;AAwBN;;;;;;;;;;;;;;;;;iBAAgB,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,uBAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA"}

package/esm/tools/run-shell.mjs

@@ -0,0 +1,65 @@
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/run-shell.ts
+/** The default tool name `run_shell` is exposed to the LLM under. */
+const DEFAULT_RUN_SHELL_TOOL_NAME = "run_shell";
+/**
+* Hand-rolled Standard Schema for {@link RunShellInput}. We validate the
+* model's arguments without a runtime schema dependency: `command` must be
+* a non-empty string, and `timeoutMs` (when present) a positive number.
+* Invalid args surface as a `SchemaValidationError` in the tool result's
+* `error` field rather than reaching `ops.exec`.
+*/
+const runShellInputSchema = { "~standard": {
+	version: 1,
+	vendor: "@warlock.js/ai-workspace",
+	validate: (value) => {
+		if (typeof value !== "object" || value === null) return { issues: [{ message: "expected an object" }] };
+		const candidate = value;
+		if (typeof candidate.command !== "string" || candidate.command.length === 0) return { issues: [{
+			message: "command must be a non-empty string",
+			path: ["command"]
+		}] };
+		if (candidate.timeoutMs !== void 0 && (typeof candidate.timeoutMs !== "number" || candidate.timeoutMs <= 0)) return { issues: [{
+			message: "timeoutMs must be a positive number",
+			path: ["timeoutMs"]
+		}] };
+		const result = { command: candidate.command };
+		if (candidate.timeoutMs !== void 0) result.timeoutMs = candidate.timeoutMs;
+		return { value: result };
+	}
+} };
+/**
+* Build the `run_shell` tool — a {@link ToolContract} that runs a single
+* shell command 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.
+*
+* @param ops - The policy-enforced operation layer to delegate `exec` to.
+* @param options - Optional tool-name override.
+*
+* @example
+* const runShell = makeRunShellTool(ops);
+* const { data, error } = await runShell.invoke({ command: "npm run build" });
+* if (error) handleDenied(error);
+* else console.log(data.exitCode, data.stdout);
+*/
+function makeRunShellTool(ops, options) {
+	return tool({
+		name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,
+		description: "Run a single shell command inside the workspace. The command's executable must be permitted by the shell policy; output is byte-capped and the run is time-limited. A non-zero exit code is returned as data, not an error.",
+		action: (input) => `Running \`${input.command}\``,
+		input: runShellInputSchema,
+		execute: (input) => ops.exec(input.command, { timeoutMs: input.timeoutMs })
+	});
+}
+
+//#endregion
+export { makeRunShellTool };
+//# sourceMappingURL=run-shell.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-shell.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/run-shell.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type {\n  RunShellInput,\n  RunShellResult,\n  WorkspaceOps,\n} from \"../contracts\";\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, and `timeoutMs` (when present) a positive number.\n * Invalid args surface as a `SchemaValidationError` in the tool result's\n * `error` field rather than reaching `ops.exec`.\n */\nconst runShellInputSchema: 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 { issues: [{ message: \"command must be a non-empty string\", path: [\"command\"] }] };\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      const result: RunShellInput = { command: candidate.command };\n\n      if (candidate.timeoutMs !== undefined) {\n        result.timeoutMs = candidate.timeoutMs as number;\n      }\n\n      return { value: result };\n    },\n  },\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\n/**\n * Build the `run_shell` tool — a {@link ToolContract} that runs a single\n * shell command through the policy-enforced {@link WorkspaceOps} layer.\n *\n * The command's leading executable basename is gated against the shell\n * allow/deny policy by `ops.exec`; a blocked command throws a\n * `WorkspacePolicyError` which the `tool()` runtime catches and surfaces\n * in the result's `error` field (never a thrown run-killer), so the agent\n * reads the refusal as tool data and self-corrects. A command that runs\n * but exits non-zero is *not* an error — its `exitCode`/`stderr` come back\n * in `data` for the agent to inspect.\n *\n * @param ops - The policy-enforced operation layer to delegate `exec` to.\n * @param options - Optional tool-name override.\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,\n): ToolContract<RunShellInput, RunShellResult> {\n  return tool<RunShellInput, RunShellResult>({\n    name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,\n    description:\n      \"Run a single shell command inside the workspace. The command's \" +\n      \"executable must be permitted by the shell policy; output is \" +\n      \"byte-capped and the run is time-limited. A non-zero exit code is \" +\n      \"returned as data, not an error.\",\n    action: (input) => `Running \\`${input.command}\\``,\n    input: runShellInputSchema,\n    execute: (input) => ops.exec(input.command, { timeoutMs: input.timeoutMs }),\n  });\n}\n"],"mappings":";;;;AASA,MAAM,8BAA8B;;;;;;;;AASpC,MAAM,sBAAuD,EAC3D,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UAAU;EACnB,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,qBAAqB,CAAC,EAAE;EAGvD,MAAM,YAAY;EAElB,IAAI,OAAO,UAAU,YAAY,YAAY,UAAU,QAAQ,WAAW,GACxE,OAAO,EAAE,QAAQ,CAAC;GAAE,SAAS;GAAsC,MAAM,CAAC,SAAS;EAAE,CAAC,EAAE;EAG1F,IACE,UAAU,cAAc,WACvB,OAAO,UAAU,cAAc,YAAY,UAAU,aAAa,IAEnE,OAAO,EACL,QAAQ,CAAC;GAAE,SAAS;GAAuC,MAAM,CAAC,WAAW;EAAE,CAAC,EAClF;EAGF,MAAM,SAAwB,EAAE,SAAS,UAAU,QAAQ;EAE3D,IAAI,UAAU,cAAc,QAC1B,OAAO,YAAY,UAAU;EAG/B,OAAO,EAAE,OAAO,OAAO;CACzB;AACF,EACF;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,iBACd,KACA,SAC6C;CAC7C,OAAO,KAAoC;EACzC,MAAM,SAAS,QAAQ;EACvB,aACE;EAIF,SAAS,UAAU,aAAa,MAAM,QAAQ;EAC9C,OAAO;EACP,UAAU,UAAU,IAAI,KAAK,MAAM,SAAS,EAAE,WAAW,MAAM,UAAU,CAAC;CAC5E,CAAC;AACH"}

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

@@ -0,0 +1,40 @@
+import { RunShellResult, RunTestsInput } from "../contracts/tool-io.type.mjs";
+import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
+import { ToolContract } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/run-tests.d.ts
+/** Options for {@link makeRunTestsTool}. */
+interface MakeRunTestsToolOptions {
+  /** Override the tool name exposed to the LLM (default `"run_tests"`). */
+  name?: string;
+  /**
+   * The base test command to run (default `"npm test"`). When the model
+   * supplies a `pattern`, it is appended to this command.
+   */
+  command?: string;
+}
+/**
+ * Build the `run_tests` tool — a {@link ToolContract} convenience over
+ * `run_shell` that runs the workspace's configured test command through
+ * the policy-enforced {@link WorkspaceOps} layer.
+ *
+ * The base command defaults to `"npm test"` and can be overridden via
+ * `options.command`. When the model passes a `pattern`, it is appended to
+ * the command as a path/suite filter forwarded to the runner (e.g.
+ * `"npm test src/cart"`). Like `run_shell`, the resolved command's
+ * executable is gated by the shell policy — a denial surfaces in the
+ * result's `error` field — and a non-zero exit (failing tests) comes back
+ * as `data` for the agent to read and fix.
+ *
+ * @param ops - The policy-enforced operation layer to delegate `exec` to.
+ * @param options - Optional tool-name and base-command overrides.
+ *
+ * @example
+ * const runTests = makeRunTestsTool(ops, { command: "pnpm test" });
+ * const { data } = await runTests.invoke({ pattern: "cart-total" });
+ * if (data.exitCode !== 0) inspect(data.stderr);
+ */
+declare function makeRunTestsTool(ops: WorkspaceOps, options?: MakeRunTestsToolOptions): ToolContract<RunTestsInput, RunShellResult>;
+//#endregion
+export { MakeRunTestsToolOptions, makeRunTestsTool };
+//# sourceMappingURL=run-tests.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-tests.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-workspace/src/tools/run-tests.ts"],"mappings":";;;;;;UAqDiB,uBAAA;;EAEf,IAAA;EAFe;;;;EAOf,OAAO;AAAA;;;;;;;;;;;;;;;;;;AA2BoC;;;;iBAH7B,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,uBAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA"}

package/esm/tools/run-tests.mjs

@@ -0,0 +1,67 @@
+import { tool } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-workspace/src/tools/run-tests.ts
+/** The default tool name `run_tests` is exposed to the LLM under. */
+const DEFAULT_RUN_TESTS_TOOL_NAME = "run_tests";
+/** The default command run when no `command` override is configured. */
+const DEFAULT_TEST_COMMAND = "npm test";
+/**
+* Hand-rolled Standard Schema for {@link RunTestsInput}. `pattern` is the
+* only field and is optional; when present it must be a string. Validation
+* happens without a runtime schema dependency, mirroring the wider tool
+* layer.
+*/
+const runTestsInputSchema = { "~standard": {
+	version: 1,
+	vendor: "@warlock.js/ai-workspace",
+	validate: (value) => {
+		if (value === void 0 || value === null) return { value: {} };
+		if (typeof value !== "object") return { issues: [{ message: "expected an object" }] };
+		const candidate = value;
+		if (candidate.pattern !== void 0 && typeof candidate.pattern !== "string") return { issues: [{
+			message: "pattern must be a string",
+			path: ["pattern"]
+		}] };
+		const result = {};
+		if (candidate.pattern !== void 0) result.pattern = candidate.pattern;
+		return { value: result };
+	}
+} };
+/**
+* Build the `run_tests` tool — a {@link ToolContract} convenience over
+* `run_shell` that runs the workspace's configured test command through
+* the policy-enforced {@link WorkspaceOps} layer.
+*
+* The base command defaults to `"npm test"` and can be overridden via
+* `options.command`. When the model passes a `pattern`, it is appended to
+* the command as a path/suite filter forwarded to the runner (e.g.
+* `"npm test src/cart"`). Like `run_shell`, the resolved command's
+* executable is gated by the shell policy — a denial surfaces in the
+* result's `error` field — and a non-zero exit (failing tests) comes back
+* as `data` for the agent to read and fix.
+*
+* @param ops - The policy-enforced operation layer to delegate `exec` to.
+* @param options - Optional tool-name and base-command overrides.
+*
+* @example
+* const runTests = makeRunTestsTool(ops, { command: "pnpm test" });
+* const { data } = await runTests.invoke({ pattern: "cart-total" });
+* if (data.exitCode !== 0) inspect(data.stderr);
+*/
+function makeRunTestsTool(ops, options) {
+	const baseCommand = options?.command ?? DEFAULT_TEST_COMMAND;
+	return tool({
+		name: options?.name ?? DEFAULT_RUN_TESTS_TOOL_NAME,
+		description: "Run the workspace's test suite, optionally narrowed to a path or name pattern forwarded to the test runner. Failing tests return a non-zero exit code as data, not an error.",
+		action: (input) => input.pattern ? `Running tests matching "${input.pattern}"` : "Running tests",
+		input: runTestsInputSchema,
+		execute: (input) => {
+			const command = input.pattern ? `${baseCommand} ${input.pattern}` : baseCommand;
+			return ops.exec(command);
+		}
+	});
+}
+
+//#endregion
+export { makeRunTestsTool };
+//# sourceMappingURL=run-tests.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-tests.mjs","names":[],"sources":["../../../../../../../@warlock.js/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} from \"../contracts\";\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. Validation\n * happens without a runtime schema dependency, mirroring the wider tool\n * layer.\n */\nconst runTestsInputSchema: StandardSchemaV1<RunTestsInput> = {\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      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\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.\n   */\n  command?: string;\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 path/suite filter forwarded to the runner (e.g.\n * `\"npm test src/cart\"`). 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.\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) => {\n      const command = input.pattern ? `${baseCommand} ${input.pattern}` : baseCommand;\n\n      return ops.exec(command);\n    },\n  });\n}\n"],"mappings":";;;;AASA,MAAM,8BAA8B;;AAGpC,MAAM,uBAAuB;;;;;;;AAQ7B,MAAM,sBAAuD,EAC3D,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,MAAM,SAAwB,CAAC;EAE/B,IAAI,UAAU,YAAY,QACxB,OAAO,UAAU,UAAU;EAG7B,OAAO,EAAE,OAAO,OAAO;CACzB;AACF,EACF;;;;;;;;;;;;;;;;;;;;;;AAkCA,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,UAAU;GAClB,MAAM,UAAU,MAAM,UAAU,GAAG,YAAY,GAAG,MAAM,YAAY;GAEpE,OAAO,IAAI,KAAK,OAAO;EACzB;CACF,CAAC;AACH"}