@warlock.js/ai-workspace 5.29.0 → 5.31.0

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

@@ -1,27 +1,47 @@
-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";
 
-//#region ../ai-workspace/src/tools/run-shell.d.ts
+//#region ../../packages/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;
+  /**
+   * 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);
@@ -29,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":["../../../../../../../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"}
+{"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"}

package/esm/tools/run-shell.mjs

@@ -1,62 +1,75 @@
+import { WorkspacePolicyError } from "../errors.mjs";
+import { withJsonSchema } from "./schema.mjs";
+import { runShellJsonSchema } from "./json-schemas.mjs";
 import { tool } from "@warlock.js/ai";
 
-//#region ../ai-workspace/src/tools/run-shell.ts
+//#region ../../packages/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);
+* a non-empty string, `timeoutMs` (when present) a positive number and
+* `background` (when present) a boolean. Invalid args surface as a
+* `SchemaValidationError` in the tool result's `error` field rather than
+* reaching `ops.exec`.
 */
+function runShellInputSchema(background) {
+	return withJsonSchema({ "~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"]
+			}] };
+			if (candidate.background !== void 0 && typeof candidate.background !== "boolean") return { issues: [{
+				message: "background must be a boolean",
+				path: ["background"]
+			}] };
+			const result = { command: candidate.command };
+			if (typeof candidate.timeoutMs === "number") result.timeoutMs = candidate.timeoutMs;
+			if (candidate.background === true) result.background = true;
+			return { value: result };
+		}
+	} }, runShellJsonSchema(background));
+}
+/** The lower of the model's timeout and the cap (either may be absent). */
+function cappedTimeout(requested, cap) {
+	if (requested === void 0) return cap;
+	return cap === void 0 ? requested : Math.min(requested, cap);
+}
 function makeRunShellTool(ops, options) {
+	const background = options?.background === true;
 	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.",
+		description: "Run a shell command inside the workspace. Every command in it must be permitted by the shell policy; a refusal explains how to fix the command. Output is byte-capped and the run is time-limited. A non-zero exit code is returned as data, not an error." + (background ? " Pass background: true for a long-running command (dev server, watcher): it returns an id at once; read its output with shell_output and stop it with shell_kill." : ""),
 		action: (input) => `Running \`${input.command}\``,
-		input: runShellInputSchema,
-		execute: (input) => ops.exec(input.command, { timeoutMs: input.timeoutMs })
+		input: runShellInputSchema(background),
+		execute: async (input, ctx) => {
+			if (input.background === true) {
+				if (!background) throw new WorkspacePolicyError("Background commands are not enabled for this workspace; run the command without background.", {
+					type: "denied-command",
+					reason: "not-allowed",
+					command: input.command
+				});
+				return {
+					...await ops.startShell(input.command, input.timeoutMs !== void 0 ? { timeoutMs: input.timeoutMs } : void 0),
+					background: true
+				};
+			}
+			const timeoutMs = cappedTimeout(input.timeoutMs, options?.maxTimeoutMs);
+			return ops.exec(input.command, {
+				...timeoutMs !== void 0 ? { timeoutMs } : {},
+				...ctx?.signal ? { signal: ctx.signal } : {}
+			});
+		}
 	});
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"run-shell.mjs","names":[],"sources":["../../../../../../../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"}
+{"version":3,"file":"run-shell.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-shell.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { tool, type ToolContract } from \"@warlock.js/ai\";\nimport { WorkspacePolicyError } from \"../errors\";\nimport type {\n  RunShellBackgroundResult,\n  RunShellInput,\n  RunShellResult,\n  WorkspaceOps,\n} from \"../contracts\";\nimport { runShellJsonSchema } from \"./json-schemas\";\nimport { withJsonSchema } from \"./schema\";\n\n/** The default tool name `run_shell` is exposed to the LLM under. */\nconst DEFAULT_RUN_SHELL_TOOL_NAME = \"run_shell\";\n\n/**\n * Hand-rolled Standard Schema for {@link RunShellInput}. We validate the\n * model's arguments without a runtime schema dependency: `command` must be\n * a non-empty string, `timeoutMs` (when present) a positive number and\n * `background` (when present) a boolean. Invalid args surface as a\n * `SchemaValidationError` in the tool result's `error` field rather than\n * reaching `ops.exec`.\n */\nfunction runShellInputSchema(background: boolean): StandardSchemaV1<RunShellInput> {\n  const schema: StandardSchemaV1<RunShellInput> = {\n    \"~standard\": {\n      version: 1,\n      vendor: \"@warlock.js/ai-workspace\",\n      validate: (value) => {\n        if (typeof value !== \"object\" || value === null) {\n          return { issues: [{ message: \"expected an object\" }] };\n        }\n\n        const candidate = value as Record<string, unknown>;\n\n        if (typeof candidate.command !== \"string\" || candidate.command.length === 0) {\n          return {\n            issues: [{ message: \"command must be a non-empty string\", path: [\"command\"] }],\n          };\n        }\n\n        if (\n          candidate.timeoutMs !== undefined &&\n          (typeof candidate.timeoutMs !== \"number\" || candidate.timeoutMs <= 0)\n        ) {\n          return {\n            issues: [{ message: \"timeoutMs must be a positive number\", path: [\"timeoutMs\"] }],\n          };\n        }\n\n        if (candidate.background !== undefined && typeof candidate.background !== \"boolean\") {\n          return {\n            issues: [{ message: \"background must be a boolean\", path: [\"background\"] }],\n          };\n        }\n\n        const result: RunShellInput = { command: candidate.command };\n\n        if (typeof candidate.timeoutMs === \"number\") {\n          result.timeoutMs = candidate.timeoutMs;\n        }\n\n        if (candidate.background === true) {\n          result.background = true;\n        }\n\n        return { value: result };\n      },\n    },\n  };\n\n  return withJsonSchema(schema, runShellJsonSchema(background));\n}\n\n/** Options for {@link makeRunShellTool}. */\nexport interface MakeRunShellToolOptions {\n  /** Override the tool name exposed to the LLM (default `\"run_shell\"`). */\n  name?: string;\n  /**\n   * Upper bound for a model-supplied `timeoutMs` on a foreground command —\n   * the model can lower the timeout, never raise it past this. The\n   * workspace passes its `shell.timeoutMs`.\n   */\n  maxTimeoutMs?: number;\n  /**\n   * Accept `background: true` and start the command as a background job\n   * (`ops.startShell`), returning a {@link RunShellBackgroundResult}. The\n   * workspace sets it when the policy has `shell.background`. Default\n   * `false`: a background request is refused.\n   */\n  background?: boolean;\n}\n\n/** The lower of the model's timeout and the cap (either may be absent). */\nfunction cappedTimeout(requested: number | undefined, cap: number | undefined): number | undefined {\n  if (requested === undefined) {\n    return cap;\n  }\n\n  return cap === undefined ? requested : Math.min(requested, cap);\n}\n\n/**\n * Build the `run_shell` tool — a {@link ToolContract} that runs a command\n * line through the policy-enforced {@link WorkspaceOps} layer.\n *\n * Every command in the line is checked against the shell policy by\n * `ops.exec`; a refused line throws a `WorkspacePolicyError` (with a\n * `reason` and a message that says how to fix the command) which the\n * `tool()` runtime catches and surfaces in the result's `error` field\n * (never a thrown run-killer), so the agent reads the refusal as tool data\n * and self-corrects. A command that runs but exits non-zero is *not* an\n * error — its `exitCode`/`stderr` come back in `data` for the agent to\n * inspect.\n *\n * The agent run's cancellation `signal` (from the dispatch `ctx`) is passed\n * to `ops.exec` per invocation: a cancelled run never starts the command,\n * and one cancelled mid-command kills its process tree (`cancelled: true`).\n * A background command (`background: true`, when enabled) belongs to the\n * workspace instead and keeps running after the call returns.\n *\n * @param ops - The policy-enforced operation layer to delegate `exec` to.\n * @param options - Tool-name override, timeout cap and background support.\n *\n * @example\n * const runShell = makeRunShellTool(ops);\n * const { data, error } = await runShell.invoke({ command: \"npm run build\" });\n * if (error) handleDenied(error);\n * else console.log(data.exitCode, data.stdout);\n */\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions & { background?: false },\n): ToolContract<RunShellInput, RunShellResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options: MakeRunShellToolOptions & { background: true },\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions,\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult>;\nexport function makeRunShellTool(\n  ops: WorkspaceOps,\n  options?: MakeRunShellToolOptions,\n): ToolContract<RunShellInput, RunShellResult | RunShellBackgroundResult> {\n  const background = options?.background === true;\n\n  return tool<RunShellInput, RunShellResult | RunShellBackgroundResult>({\n    name: options?.name ?? DEFAULT_RUN_SHELL_TOOL_NAME,\n    description:\n      \"Run a shell command inside the workspace. Every command in it must be \" +\n      \"permitted by the shell policy; a refusal explains how to fix the \" +\n      \"command. Output is byte-capped and the run is time-limited. A \" +\n      \"non-zero exit code is returned as data, not an error.\" +\n      (background\n        ? \" Pass background: true for a long-running command (dev server, \" +\n          \"watcher): it returns an id at once; read its output with \" +\n          \"shell_output and stop it with shell_kill.\"\n        : \"\"),\n    action: (input) => `Running \\`${input.command}\\``,\n    input: runShellInputSchema(background),\n    // The run's signal belongs to this one invocation: it is read from the\n    // dispatch ctx on every call and never stored on the tool or workspace.\n    execute: async (input, ctx) => {\n      if (input.background === true) {\n        if (!background) {\n          throw new WorkspacePolicyError(\n            \"Background commands are not enabled for this workspace; run the command without background.\",\n            { type: \"denied-command\", reason: \"not-allowed\", command: input.command },\n          );\n        }\n\n        const job = await ops.startShell(\n          input.command,\n          input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : undefined,\n        );\n\n        return { ...job, background: true };\n      }\n\n      const timeoutMs = cappedTimeout(input.timeoutMs, options?.maxTimeoutMs);\n\n      return ops.exec(input.command, {\n        ...(timeoutMs !== undefined ? { timeoutMs } : {}),\n        ...(ctx?.signal ? { signal: ctx.signal } : {}),\n      });\n    },\n  });\n}\n"],"mappings":";;;;;;;AAaA,MAAM,8BAA8B;;;;;;;;;AAUpC,SAAS,oBAAoB,YAAsD;CAgDjF,OAAO,eAAe,EA9CpB,aAAa;EACX,SAAS;EACT,QAAQ;EACR,WAAW,UAAU;GACnB,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,qBAAqB,CAAC,EAAE;GAGvD,MAAM,YAAY;GAElB,IAAI,OAAO,UAAU,YAAY,YAAY,UAAU,QAAQ,WAAW,GACxE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAsC,MAAM,CAAC,SAAS;GAAE,CAAC,EAC/E;GAGF,IACE,UAAU,cAAc,WACvB,OAAO,UAAU,cAAc,YAAY,UAAU,aAAa,IAEnE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAuC,MAAM,CAAC,WAAW;GAAE,CAAC,EAClF;GAGF,IAAI,UAAU,eAAe,UAAa,OAAO,UAAU,eAAe,WACxE,OAAO,EACL,QAAQ,CAAC;IAAE,SAAS;IAAgC,MAAM,CAAC,YAAY;GAAE,CAAC,EAC5E;GAGF,MAAM,SAAwB,EAAE,SAAS,UAAU,QAAQ;GAE3D,IAAI,OAAO,UAAU,cAAc,UACjC,OAAO,YAAY,UAAU;GAG/B,IAAI,UAAU,eAAe,MAC3B,OAAO,aAAa;GAGtB,OAAO,EAAE,OAAO,OAAO;EACzB;CACF,EAGyB,GAAG,mBAAmB,UAAU,CAAC;AAC9D;;AAsBA,SAAS,cAAc,WAA+B,KAA6C;CACjG,IAAI,cAAc,QAChB,OAAO;CAGT,OAAO,QAAQ,SAAY,YAAY,KAAK,IAAI,WAAW,GAAG;AAChE;AA0CA,SAAgB,iBACd,KACA,SACwE;CACxE,MAAM,aAAa,SAAS,eAAe;CAE3C,OAAO,KAA+D;EACpE,MAAM,SAAS,QAAQ;EACvB,aACE,gQAIC,aACG,sKAGA;EACN,SAAS,UAAU,aAAa,MAAM,QAAQ;EAC9C,OAAO,oBAAoB,UAAU;EAGrC,SAAS,OAAO,OAAO,QAAQ;GAC7B,IAAI,MAAM,eAAe,MAAM;IAC7B,IAAI,CAAC,YACH,MAAM,IAAI,qBACR,+FACA;KAAE,MAAM;KAAkB,QAAQ;KAAe,SAAS,MAAM;IAAQ,CAC1E;IAQF,OAAO;KAAE,GAAG,MALM,IAAI,WACpB,MAAM,SACN,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,UAAU,IAAI,MACnE;KAEiB,YAAY;IAAK;GACpC;GAEA,MAAM,YAAY,cAAc,MAAM,WAAW,SAAS,YAAY;GAEtE,OAAO,IAAI,KAAK,MAAM,SAAS;IAC7B,GAAI,cAAc,SAAY,EAAE,UAAU,IAAI,CAAC;IAC/C,GAAI,KAAK,SAAS,EAAE,QAAQ,IAAI,OAAO,IAAI,CAAC;GAC9C,CAAC;EACH;CACF,CAAC;AACH"}

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

@@ -1,8 +1,9 @@
 import { RunShellResult, RunTestsInput } from "../contracts/tool-io.type.mjs";
+import { WorkspaceShellInterpreter } from "../contracts/workspace-policy.type.mjs";
 import { WorkspaceOps } from "../contracts/workspace-ops.contract.mjs";
 import { ToolContract } from "@warlock.js/ai";
 
-//#region ../ai-workspace/src/tools/run-tests.d.ts
+//#region ../../packages/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"`). */
@@ -13,6 +14,13 @@ interface MakeRunTestsToolOptions {
    * quoted argument.
    */
   command?: string;
+  /**
+   * The workspace's `shell.interpreter`, so the pattern is quoted for the
+   * way the line runs: double quotes in argv mode (the default), single
+   * quotes for `/bin/sh` (so `$` and backticks in a pattern stay literal),
+   * double quotes for cmd.exe.
+   */
+  interpreter?: WorkspaceShellInterpreter;
 }
 /**
  * Build the `run_tests` tool — a {@link ToolContract} convenience over
@@ -27,7 +35,8 @@ interface MakeRunTestsToolOptions {
  * data, never a second command. 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.
+ * as `data` for the agent to read and fix. The agent run's cancellation
+ * `signal` is threaded per invocation, exactly as for `run_shell`.
  *
  * @param ops - The policy-enforced operation layer to delegate `exec` to.
  * @param options - Optional tool-name and base-command overrides.

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

@@ -1 +1 @@
-{"version":3,"file":"run-tests.d.mts","names":[],"sources":["../../../../../../../ai-workspace/src/tools/run-tests.ts"],"mappings":";;;;;;UAmEiB,uBAAA;;EAEf,IAAA;EAFe;;;;AAQR;EAAP,OAAO;AAAA;;;;;;;;;;;;;;;;;AA6BoC;;;;;;;iBAH7B,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,uBAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA"}
+{"version":3,"file":"run-tests.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/run-tests.ts"],"mappings":";;;;;;;UAyEiB,uBAAA;;EAEf,IAAA;;AAFF;;;;EAQE,OAAA;EAAA;;;;AAOuC;AAoCzC;EApCE,WAAA,GAAc,yBAAyB;AAAA;;;;;;;;;;;;;;;;AAuCI;;;;;;;;;iBAH7B,gBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA,GAAU,uBAAA,GACT,YAAA,CAAa,aAAA,EAAe,cAAA"}

package/esm/tools/run-tests.mjs

@@ -1,6 +1,8 @@
+import { withJsonSchema } from "./schema.mjs";
+import { RUN_TESTS_JSON_SCHEMA } from "./json-schemas.mjs";
 import { tool } from "@warlock.js/ai";
 
-//#region ../ai-workspace/src/tools/run-tests.ts
+//#region ../../packages/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. */
@@ -14,7 +16,7 @@ const DEFAULT_TEST_COMMAND = "npm test";
 * happens without a runtime schema dependency, mirroring the wider tool
 * layer.
 */
-const runTestsInputSchema = { "~standard": {
+const runTestsInputSchema = withJsonSchema({ "~standard": {
 	version: 1,
 	vendor: "@warlock.js/ai-workspace",
 	validate: (value) => {
@@ -33,7 +35,12 @@ const runTestsInputSchema = { "~standard": {
 		if (candidate.pattern !== void 0) result.pattern = candidate.pattern;
 		return { value: result };
 	}
-} };
+} }, RUN_TESTS_JSON_SCHEMA);
+/** Quote the test pattern as one literal argument for the line's interpreter. */
+function quotePattern(pattern, interpreter) {
+	if (interpreter === "sh" && process.platform !== "win32") return `'${pattern.replace(/'/g, "'\\''")}'`;
+	return `"${pattern}"`;
+}
 /**
 * Build the `run_tests` tool — a {@link ToolContract} convenience over
 * `run_shell` that runs the workspace's configured test command through
@@ -47,7 +54,8 @@ const runTestsInputSchema = { "~standard": {
 * data, never a second command. 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.
+* as `data` for the agent to read and fix. The agent run's cancellation
+* `signal` is threaded per invocation, exactly as for `run_shell`.
 *
 * @param ops - The policy-enforced operation layer to delegate `exec` to.
 * @param options - Optional tool-name and base-command overrides.
@@ -64,9 +72,9 @@ function makeRunTestsTool(ops, options) {
 		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);
+		execute: (input, ctx) => {
+			const command = input.pattern ? `${baseCommand} ${quotePattern(input.pattern, options?.interpreter ?? "none")}` : baseCommand;
+			return ops.exec(command, ctx?.signal ? { signal: ctx.signal } : void 0);
 		}
 	});
 }

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

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

package/esm/tools/schema.mjs

@@ -1,4 +1,4 @@
-//#region ../ai-workspace/src/tools/schema.ts
+//#region ../../packages/ai-workspace/src/tools/schema.ts
 /**
 * Tiny, dependency-free [Standard Schema](https://standardschema.dev)
 * builders for the workspace tools' input validation. The package pins
@@ -15,6 +15,10 @@
 */
 /** The vendor tag stamped on every issue these builders produce. */
 const VENDOR = "ai-workspace";
+/** Attach a JSON Schema description to a hand-rolled Standard Schema. */
+function withJsonSchema(schema, jsonSchema) {
+	return Object.assign(schema, { jsonSchema });
+}
 /** Required string field — rejects anything that is not a string. */
 function stringField() {
 	return (value, key) => {
@@ -65,24 +69,25 @@ function optionalBooleanField() {
 	};
 }
 /**
-* Build a {@link StandardSchemaV1} for a flat object whose every property
-* is validated by a {@link FieldValidator}. The input must be a non-null
-* object; each declared field is validated and the (possibly coerced)
-* values are collected into the typed result. All field issues are merged
-* so the caller sees every problem at once.
-*
-* `T` is constrained to `object` rather than `Record<string, unknown>` so
-* the tool IO `interface`s (which carry no implicit string index
-* signature) satisfy it directly — only the declared keys in `shape` are
-* ever read, so a string index signature is never required.
-*
-* @example
-* const schema = objectSchema<{ path: string; limit?: number }>({
-*   path: stringField(),
-*   limit: optionalNumberField(),
-* });
+* Optional array-of-strings field — accepts `undefined` or an array whose
+* every element is a string (at most `maxItems` of them).
 */
-function objectSchema(shape) {
+function optionalStringArrayField(maxItems = 50) {
+	return (value, key) => {
+		if (value === void 0) return { value: void 0 };
+		if (Array.isArray(value) && value.length <= maxItems && value.every((item) => typeof item === "string")) return { value };
+		return { issues: [{
+			message: `"${key}" must be an array of at most ${maxItems} strings when provided`,
+			path: [key]
+		}] };
+	};
+}
+function objectSchema(shape, jsonSchema) {
+	const schema = buildObjectSchema(shape);
+	return jsonSchema === void 0 ? schema : withJsonSchema(schema, jsonSchema);
+}
+/** The validator behind {@link objectSchema}. */
+function buildObjectSchema(shape) {
 	return { "~standard": {
 		version: 1,
 		vendor: VENDOR,
@@ -107,5 +112,5 @@ function objectSchema(shape) {
 }
 
 //#endregion
-export { objectSchema, optionalBooleanField, optionalNumberField, optionalStringField, stringField };
+export { objectSchema, optionalBooleanField, optionalNumberField, optionalStringArrayField, optionalStringField, stringField, withJsonSchema };
 //# sourceMappingURL=schema.mjs.map

package/esm/tools/schema.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../../../../ai-workspace/src/tools/schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Tiny, dependency-free [Standard Schema](https://standardschema.dev)\n * builders for the workspace tools' input validation. The package pins\n * only `@warlock.js/ai` and `@warlock.js/fs` as runtime dependencies, so\n * rather than pull in a schema library we hand-roll the few shapes the\n * file tools need — exactly the pattern `@warlock.js/ai`'s own `tool()`\n * tests use. Each builder returns a `StandardSchemaV1`, which is what\n * `tool({ input })` validates against before calling `execute`.\n *\n * These intentionally cover only the primitive cases the FILE tools\n * require (`string`, `optional string`, `optional number`, `optional\n * boolean`, and an `object` of fields). They are not a general-purpose\n * validator.\n */\n\n/** The vendor tag stamped on every issue these builders produce. */\nconst VENDOR = \"ai-workspace\";\n\n/**\n * A single field validator inside {@link objectSchema}: given a value,\n * return either the coerced value or a list of issues. Field validators\n * receive the raw property and the property name (for issue messages).\n */\ntype FieldValidator<T> = (\n  value: unknown,\n  key: string,\n) => { value: T } | { issues: StandardSchemaV1.Issue[] };\n\n/** Required string field — rejects anything that is not a string. */\nexport function stringField(): FieldValidator<string> {\n  return (value, key) => {\n    if (typeof value === \"string\") {\n      return { value };\n    }\n\n    return { issues: [{ message: `\"${key}\" must be a string`, path: [key] }] };\n  };\n}\n\n/**\n * Optional string field — accepts `undefined` (the property absent or\n * explicitly undefined) or a string, and rejects every other type.\n */\nexport function optionalStringField(): FieldValidator<string | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"string\") {\n      return { value };\n    }\n\n    return {\n      issues: [{ message: `\"${key}\" must be a string when provided`, path: [key] }],\n    };\n  };\n}\n\n/**\n * Optional finite-number field — accepts `undefined` or a finite number,\n * rejecting `NaN`/`Infinity` and non-number types.\n */\nexport function optionalNumberField(): FieldValidator<number | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"number\" && Number.isFinite(value)) {\n      return { value };\n    }\n\n    return {\n      issues: [\n        { message: `\"${key}\" must be a finite number when provided`, path: [key] },\n      ],\n    };\n  };\n}\n\n/** Optional boolean field — accepts `undefined` or a boolean. */\nexport function optionalBooleanField(): FieldValidator<boolean | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"boolean\") {\n      return { value };\n    }\n\n    return {\n      issues: [{ message: `\"${key}\" must be a boolean when provided`, path: [key] }],\n    };\n  };\n}\n\n/** The per-key field validator map describing an object schema's shape. */\ntype ObjectShape<T> = {\n  [K in keyof T]-?: FieldValidator<T[K]>;\n};\n\n/**\n * Build a {@link StandardSchemaV1} for a flat object whose every property\n * is validated by a {@link FieldValidator}. The input must be a non-null\n * object; each declared field is validated and the (possibly coerced)\n * values are collected into the typed result. All field issues are merged\n * so the caller sees every problem at once.\n *\n * `T` is constrained to `object` rather than `Record<string, unknown>` so\n * the tool IO `interface`s (which carry no implicit string index\n * signature) satisfy it directly — only the declared keys in `shape` are\n * ever read, so a string index signature is never required.\n *\n * @example\n * const schema = objectSchema<{ path: string; limit?: number }>({\n *   path: stringField(),\n *   limit: optionalNumberField(),\n * });\n */\nexport function objectSchema<T extends object>(\n  shape: ObjectShape<T>,\n): StandardSchemaV1<T> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: VENDOR,\n      validate(input) {\n        if (typeof input !== \"object\" || input === null || Array.isArray(input)) {\n          return { issues: [{ message: \"input must be an object\" }] };\n        }\n\n        const source = input as Record<string, unknown>;\n        const issues: StandardSchemaV1.Issue[] = [];\n        const result: Record<string, unknown> = {};\n\n        for (const key of Object.keys(shape) as (keyof T)[]) {\n          const field = shape[key];\n          const outcome = field(source[key as string], key as string);\n\n          if (\"issues\" in outcome) {\n            issues.push(...outcome.issues);\n\n            continue;\n          }\n\n          // Only carry through keys that resolved to a defined value, so\n          // optional-absent fields stay absent rather than becoming\n          // explicit `undefined` properties.\n          if (outcome.value !== undefined) {\n            result[key as string] = outcome.value;\n          }\n        }\n\n        if (issues.length > 0) {\n          return { issues };\n        }\n\n        return { value: result as T };\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,MAAM,SAAS;;AAaf,SAAgB,cAAsC;CACpD,QAAQ,OAAO,QAAQ;EACrB,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EAAE,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAqB,MAAM,CAAC,GAAG;EAAE,CAAC,EAAE;CAC3E;AACF;;;;;AAMA,SAAgB,sBAA0D;CACxE,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAmC,MAAM,CAAC,GAAG;EAAE,CAAC,EAC9E;CACF;AACF;;;;;AAMA,SAAgB,sBAA0D;CACxE,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,GACpD,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CACN;GAAE,SAAS,IAAI,IAAI;GAA0C,MAAM,CAAC,GAAG;EAAE,CAC3E,EACF;CACF;AACF;;AAGA,SAAgB,uBAA4D;CAC1E,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,WACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAoC,MAAM,CAAC,GAAG;EAAE,CAAC,EAC/E;CACF;AACF;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,aACd,OACqB;CACrB,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,SAAS,OAAO;GACd,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,0BAA0B,CAAC,EAAE;GAG5D,MAAM,SAAS;GACf,MAAM,SAAmC,CAAC;GAC1C,MAAM,SAAkC,CAAC;GAEzC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GAAkB;IACnD,MAAM,QAAQ,MAAM;IACpB,MAAM,UAAU,MAAM,OAAO,MAAgB,GAAa;IAE1D,IAAI,YAAY,SAAS;KACvB,OAAO,KAAK,GAAG,QAAQ,MAAM;KAE7B;IACF;IAKA,IAAI,QAAQ,UAAU,QACpB,OAAO,OAAiB,QAAQ;GAEpC;GAEA,IAAI,OAAO,SAAS,GAClB,OAAO,EAAE,OAAO;GAGlB,OAAO,EAAE,OAAO,OAAY;EAC9B;CACF,EACF;AACF"}
+{"version":3,"file":"schema.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\n/**\n * Tiny, dependency-free [Standard Schema](https://standardschema.dev)\n * builders for the workspace tools' input validation. The package pins\n * only `@warlock.js/ai` and `@warlock.js/fs` as runtime dependencies, so\n * rather than pull in a schema library we hand-roll the few shapes the\n * file tools need — exactly the pattern `@warlock.js/ai`'s own `tool()`\n * tests use. Each builder returns a `StandardSchemaV1`, which is what\n * `tool({ input })` validates against before calling `execute`.\n *\n * These intentionally cover only the primitive cases the FILE tools\n * require (`string`, `optional string`, `optional number`, `optional\n * boolean`, and an `object` of fields). They are not a general-purpose\n * validator.\n */\n\n/** The vendor tag stamped on every issue these builders produce. */\nconst VENDOR = \"ai-workspace\";\n\n/** A JSON Schema object, as providers send it with a tool definition. */\nexport type JsonSchemaObject = Record<string, unknown>;\n\n/**\n * A Standard Schema that also carries the JSON Schema of its input as a\n * top-level `jsonSchema` property — the property `@warlock.js/ai`'s\n * `extractJsonSchema` reads — so providers send the model the real\n * parameter shape instead of a bare `{ type: \"object\" }`.\n */\nexport type JsonStandardSchema<T> = StandardSchemaV1<T> & { jsonSchema: JsonSchemaObject };\n\n/** Attach a JSON Schema description to a hand-rolled Standard Schema. */\nexport function withJsonSchema<T>(\n  schema: StandardSchemaV1<T>,\n  jsonSchema: JsonSchemaObject,\n): JsonStandardSchema<T> {\n  return Object.assign(schema, { jsonSchema });\n}\n\n/**\n * A single field validator inside {@link objectSchema}: given a value,\n * return either the coerced value or a list of issues. Field validators\n * receive the raw property and the property name (for issue messages).\n */\nexport type FieldValidator<T> = (\n  value: unknown,\n  key: string,\n) => { value: T } | { issues: StandardSchemaV1.Issue[] };\n\n/** Required string field — rejects anything that is not a string. */\nexport function stringField(): FieldValidator<string> {\n  return (value, key) => {\n    if (typeof value === \"string\") {\n      return { value };\n    }\n\n    return { issues: [{ message: `\"${key}\" must be a string`, path: [key] }] };\n  };\n}\n\n/**\n * Optional string field — accepts `undefined` (the property absent or\n * explicitly undefined) or a string, and rejects every other type.\n */\nexport function optionalStringField(): FieldValidator<string | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"string\") {\n      return { value };\n    }\n\n    return {\n      issues: [{ message: `\"${key}\" must be a string when provided`, path: [key] }],\n    };\n  };\n}\n\n/**\n * Optional finite-number field — accepts `undefined` or a finite number,\n * rejecting `NaN`/`Infinity` and non-number types.\n */\nexport function optionalNumberField(): FieldValidator<number | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"number\" && Number.isFinite(value)) {\n      return { value };\n    }\n\n    return {\n      issues: [{ message: `\"${key}\" must be a finite number when provided`, path: [key] }],\n    };\n  };\n}\n\n/** Optional boolean field — accepts `undefined` or a boolean. */\nexport function optionalBooleanField(): FieldValidator<boolean | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (typeof value === \"boolean\") {\n      return { value };\n    }\n\n    return {\n      issues: [{ message: `\"${key}\" must be a boolean when provided`, path: [key] }],\n    };\n  };\n}\n\n/**\n * Optional array-of-strings field — accepts `undefined` or an array whose\n * every element is a string (at most `maxItems` of them).\n */\nexport function optionalStringArrayField(maxItems = 50): FieldValidator<string[] | undefined> {\n  return (value, key) => {\n    if (value === undefined) {\n      return { value: undefined };\n    }\n\n    if (\n      Array.isArray(value) &&\n      value.length <= maxItems &&\n      value.every((item) => typeof item === \"string\")\n    ) {\n      return { value: value as string[] };\n    }\n\n    return {\n      issues: [\n        {\n          message: `\"${key}\" must be an array of at most ${maxItems} strings when provided`,\n          path: [key],\n        },\n      ],\n    };\n  };\n}\n\n/** The per-key field validator map describing an object schema's shape. */\ntype ObjectShape<T> = {\n  [K in keyof T]-?: FieldValidator<T[K]>;\n};\n\n/**\n * Build a {@link StandardSchemaV1} for a flat object whose every property\n * is validated by a {@link FieldValidator}. The input must be a non-null\n * object; each declared field is validated and the (possibly coerced)\n * values are collected into the typed result. All field issues are merged\n * so the caller sees every problem at once.\n *\n * `T` is constrained to `object` rather than `Record<string, unknown>` so\n * the tool IO `interface`s (which carry no implicit string index\n * signature) satisfy it directly — only the declared keys in `shape` are\n * ever read, so a string index signature is never required.\n *\n * @example\n * const schema = objectSchema<{ path: string; limit?: number }>({\n *   path: stringField(),\n *   limit: optionalNumberField(),\n * });\n */\nexport function objectSchema<T extends object>(shape: ObjectShape<T>): StandardSchemaV1<T>;\nexport function objectSchema<T extends object>(\n  shape: ObjectShape<T>,\n  jsonSchema: JsonSchemaObject,\n): JsonStandardSchema<T>;\nexport function objectSchema<T extends object>(\n  shape: ObjectShape<T>,\n  jsonSchema?: JsonSchemaObject,\n): StandardSchemaV1<T> {\n  const schema = buildObjectSchema(shape);\n\n  return jsonSchema === undefined ? schema : withJsonSchema(schema, jsonSchema);\n}\n\n/** The validator behind {@link objectSchema}. */\nfunction buildObjectSchema<T extends object>(shape: ObjectShape<T>): StandardSchemaV1<T> {\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: VENDOR,\n      validate(input) {\n        if (typeof input !== \"object\" || input === null || Array.isArray(input)) {\n          return { issues: [{ message: \"input must be an object\" }] };\n        }\n\n        const source = input as Record<string, unknown>;\n        const issues: StandardSchemaV1.Issue[] = [];\n        const result: Record<string, unknown> = {};\n\n        for (const key of Object.keys(shape) as (keyof T)[]) {\n          const field = shape[key];\n          const outcome = field(source[key as string], key as string);\n\n          if (\"issues\" in outcome) {\n            issues.push(...outcome.issues);\n\n            continue;\n          }\n\n          // Only carry through keys that resolved to a defined value, so\n          // optional-absent fields stay absent rather than becoming\n          // explicit `undefined` properties.\n          if (outcome.value !== undefined) {\n            result[key as string] = outcome.value;\n          }\n        }\n\n        if (issues.length > 0) {\n          return { issues };\n        }\n\n        return { value: result as T };\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,MAAM,SAAS;;AAcf,SAAgB,eACd,QACA,YACuB;CACvB,OAAO,OAAO,OAAO,QAAQ,EAAE,WAAW,CAAC;AAC7C;;AAaA,SAAgB,cAAsC;CACpD,QAAQ,OAAO,QAAQ;EACrB,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EAAE,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAqB,MAAM,CAAC,GAAG;EAAE,CAAC,EAAE;CAC3E;AACF;;;;;AAMA,SAAgB,sBAA0D;CACxE,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAmC,MAAM,CAAC,GAAG;EAAE,CAAC,EAC9E;CACF;AACF;;;;;AAMA,SAAgB,sBAA0D;CACxE,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,GACpD,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAA0C,MAAM,CAAC,GAAG;EAAE,CAAC,EACrF;CACF;AACF;;AAGA,SAAgB,uBAA4D;CAC1E,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IAAI,OAAO,UAAU,WACnB,OAAO,EAAE,MAAM;EAGjB,OAAO,EACL,QAAQ,CAAC;GAAE,SAAS,IAAI,IAAI;GAAoC,MAAM,CAAC,GAAG;EAAE,CAAC,EAC/E;CACF;AACF;;;;;AAMA,SAAgB,yBAAyB,WAAW,IAA0C;CAC5F,QAAQ,OAAO,QAAQ;EACrB,IAAI,UAAU,QACZ,OAAO,EAAE,OAAO,OAAU;EAG5B,IACE,MAAM,QAAQ,KAAK,KACnB,MAAM,UAAU,YAChB,MAAM,OAAO,SAAS,OAAO,SAAS,QAAQ,GAE9C,OAAO,EAAS,MAAkB;EAGpC,OAAO,EACL,QAAQ,CACN;GACE,SAAS,IAAI,IAAI,gCAAgC,SAAS;GAC1D,MAAM,CAAC,GAAG;EACZ,CACF,EACF;CACF;AACF;AA8BA,SAAgB,aACd,OACA,YACqB;CACrB,MAAM,SAAS,kBAAkB,KAAK;CAEtC,OAAO,eAAe,SAAY,SAAS,eAAe,QAAQ,UAAU;AAC9E;;AAGA,SAAS,kBAAoC,OAA4C;CACvF,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,SAAS,OAAO;GACd,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,0BAA0B,CAAC,EAAE;GAG5D,MAAM,SAAS;GACf,MAAM,SAAmC,CAAC;GAC1C,MAAM,SAAkC,CAAC;GAEzC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAK,GAAkB;IACnD,MAAM,QAAQ,MAAM;IACpB,MAAM,UAAU,MAAM,OAAO,MAAgB,GAAa;IAE1D,IAAI,YAAY,SAAS;KACvB,OAAO,KAAK,GAAG,QAAQ,MAAM;KAE7B;IACF;IAKA,IAAI,QAAQ,UAAU,QACpB,OAAO,OAAiB,QAAQ;GAEpC;GAEA,IAAI,OAAO,SAAS,GAClB,OAAO,EAAE,OAAO;GAGlB,OAAO,EAAE,OAAO,OAAY;EAC9B;CACF,EACF;AACF"}

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

@@ -0,0 +1,25 @@
+import { ShellJobInfo, ShellKillInput } 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/shell-kill.d.ts
+/**
+ * Build the agent-facing `shell_kill` tool: stop a background command
+ * started with `run_shell({ background: true })`, killing its whole process
+ * tree, and return its final state. Killing a command that already stopped
+ * just reports its state. An unknown id surfaces as a `WorkspaceJobError`
+ * 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 { data } = await makeShellKillTool(ops).invoke({ id: "job-1" });
+ * console.log(data?.status); // "killed"
+ */
+declare function makeShellKillTool(ops: WorkspaceOps, options?: {
+  name?: string;
+}): ToolContract<ShellKillInput, ShellJobInfo>;
+//#endregion
+export { makeShellKillTool };
+//# sourceMappingURL=shell-kill.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shell-kill.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/shell-kill.ts"],"mappings":";;;;;;;;;AAyBA;;;;;;;;;;iBAAgB,iBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA;EAAY,IAAA;AAAA,IACX,YAAA,CAAa,cAAA,EAAgB,YAAA"}

package/esm/tools/shell-kill.mjs

@@ -0,0 +1,36 @@
+import { objectSchema, stringField } from "./schema.mjs";
+import { SHELL_KILL_JSON_SCHEMA } from "./json-schemas.mjs";
+import { tool } from "@warlock.js/ai";
+
+//#region ../../packages/ai-workspace/src/tools/shell-kill.ts
+/** Default tool name exposed to the LLM. */
+const DEFAULT_NAME = "shell_kill";
+/** Input schema for the `shell_kill` tool. */
+const inputSchema = objectSchema({ id: stringField() }, SHELL_KILL_JSON_SCHEMA);
+/**
+* Build the agent-facing `shell_kill` tool: stop a background command
+* started with `run_shell({ background: true })`, killing its whole process
+* tree, and return its final state. Killing a command that already stopped
+* just reports its state. An unknown id surfaces as a `WorkspaceJobError`
+* 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 { data } = await makeShellKillTool(ops).invoke({ id: "job-1" });
+* console.log(data?.status); // "killed"
+*/
+function makeShellKillTool(ops, options) {
+	return tool({
+		name: options?.name ?? DEFAULT_NAME,
+		description: "Stop a background command started with run_shell (background: true), killing it and everything it started. Returns its final state.",
+		action: (input) => `Stopping ${typeof input.id === "string" ? input.id : "a background command"}`,
+		input: inputSchema,
+		execute: (input) => ops.shellKill(input.id)
+	});
+}
+
+//#endregion
+export { makeShellKillTool };
+//# sourceMappingURL=shell-kill.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shell-kill.mjs","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/shell-kill.ts"],"sourcesContent":["import { tool, type ToolContract } from \"@warlock.js/ai\";\nimport type { ShellJobInfo, ShellKillInput, WorkspaceOps } from \"../contracts\";\nimport { SHELL_KILL_JSON_SCHEMA } from \"./json-schemas\";\nimport { objectSchema, stringField } from \"./schema\";\n\n/** Default tool name exposed to the LLM. */\nconst DEFAULT_NAME = \"shell_kill\";\n\n/** Input schema for the `shell_kill` tool. */\nconst inputSchema = objectSchema<ShellKillInput>({ id: stringField() }, SHELL_KILL_JSON_SCHEMA);\n\n/**\n * Build the agent-facing `shell_kill` tool: stop a background command\n * started with `run_shell({ background: true })`, killing its whole process\n * tree, and return its final state. Killing a command that already stopped\n * just reports its state. An unknown id surfaces as a `WorkspaceJobError`\n * in 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 { data } = await makeShellKillTool(ops).invoke({ id: \"job-1\" });\n * console.log(data?.status); // \"killed\"\n */\nexport function makeShellKillTool(\n  ops: WorkspaceOps,\n  options?: { name?: string },\n): ToolContract<ShellKillInput, ShellJobInfo> {\n  return tool<ShellKillInput, ShellJobInfo>({\n    name: options?.name ?? DEFAULT_NAME,\n    description:\n      \"Stop a background command started with run_shell (background: true), \" +\n      \"killing it and everything it started. Returns its final state.\",\n    action: (input) =>\n      `Stopping ${typeof input.id === \"string\" ? input.id : \"a background command\"}`,\n    input: inputSchema,\n    execute: (input) => ops.shellKill(input.id),\n  });\n}\n"],"mappings":";;;;;;AAMA,MAAM,eAAe;;AAGrB,MAAM,cAAc,aAA6B,EAAE,IAAI,YAAY,EAAE,GAAG,sBAAsB;;;;;;;;;;;;;;;AAgB9F,SAAgB,kBACd,KACA,SAC4C;CAC5C,OAAO,KAAmC;EACxC,MAAM,SAAS,QAAQ;EACvB,aACE;EAEF,SAAS,UACP,YAAY,OAAO,MAAM,OAAO,WAAW,MAAM,KAAK;EACxD,OAAO;EACP,UAAU,UAAU,IAAI,UAAU,MAAM,EAAE;CAC5C,CAAC;AACH"}

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

@@ -0,0 +1,30 @@
+import { ShellOutputInput, ShellOutputResult } 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/shell-output.d.ts
+/**
+ * Build the agent-facing `shell_output` tool: the new output of a
+ * background command started with `run_shell({ background: true })`, plus
+ * its state (`running` / `exited` / `killed` / `timed-out`, `exitCode`).
+ *
+ * Without `since` it returns everything produced since the previous read;
+ * `cursor` in the result is the position to pass as `since` next time.
+ * `waitMs` (at most 30 s) waits for new output or for the command to stop
+ * when there is nothing new yet — the agent run's signal ends the wait
+ * early. Only the newest `shell.maxOutputBytes` of a command's output are
+ * kept; `droppedBytes` says how much the reader missed.
+ *
+ * @param ops - The shared, policy-enforced operation layer.
+ * @param options - Optional overrides; `name` renames the LLM-visible tool.
+ *
+ * @example
+ * const { data } = await makeShellOutputTool(ops).invoke({ id: "job-1", waitMs: 2_000 });
+ * if (data?.stdout.includes("ready")) console.log("dev server is up");
+ */
+declare function makeShellOutputTool(ops: WorkspaceOps, options?: {
+  name?: string;
+}): ToolContract<ShellOutputInput, ShellOutputResult>;
+//#endregion
+export { makeShellOutputTool };
+//# sourceMappingURL=shell-output.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shell-output.d.mts","names":[],"sources":["../../../../../../../../packages/ai-workspace/src/tools/shell-output.ts"],"mappings":";;;;;;;;;AAqCA;;;;;;;;;;;;;;;iBAAgB,mBAAA,CACd,GAAA,EAAK,YAAA,EACL,OAAA;EAAY,IAAA;AAAA,IACX,YAAA,CAAa,gBAAA,EAAkB,iBAAA"}