@xopcai/xopc 0.0.123 → 0.0.125

package/dist/src/agent/tools/dreaming-tool.js

@@ -35,16 +35,18 @@ function createDreamingTool(deps) {
 	return {
 		name: "dreaming",
 		label: "💤 Dreaming",
-		description: "Inspect and maintain the dreaming promotion state.\n\nActions:\n- status: show config gates and short-term store stats\n- reset_store: clear short-term recall store (memory/.dreams/short-term-recall.json)\n- clear_lock: remove a stale promotion lock file (memory/.dreams/short-term-promotion.lock)",
+		description: "Inspect and maintain the dreaming promotion state.\n\nActions:\n- status: show config gates and short-term store stats\n- reset_store: clear this agent short-term recall store (.dreams/short-term-recall.json)\n- clear_lock: remove this agent stale promotion lock file (.dreams/short-term-promotion.lock)",
 		parameters: DreamingSchema,
 		async execute(_toolCallId, params) {
 			const action = params.action;
-			const workspaceDir = deps.getWorkspace();
-			const resolved = resolveDreamingConfig(deps.getConfig());
-			const storePath = path.join(workspaceDir, SHORT_TERM_RECALL_STORE_RELATIVE);
-			const lockPath = path.join(workspaceDir, SHORT_TERM_PROMOTION_LOCK_RELATIVE);
+			const dreamingRoot = deps.getDreamingRoot();
+			const cfg = deps.getConfig();
+			const agentId = deps.getAgentId?.();
+			const resolved = resolveDreamingConfig(cfg, agentId);
+			const storePath = path.join(dreamingRoot, SHORT_TERM_RECALL_STORE_RELATIVE);
+			const lockPath = path.join(dreamingRoot, SHORT_TERM_PROMOTION_LOCK_RELATIVE);
 			if (action === "status") {
-				const { store } = await loadDreamingStore({ workspaceDir });
+				const { store } = await loadDreamingStore({ dreamingRoot });
 				const entries = Object.values(store.entries ?? {});
 				const total = entries.length;
 				const promoted = entries.filter((e) => Boolean(e.promotedAt)).length;
@@ -64,7 +66,8 @@ function createDreamingTool(deps) {
 					`deep.minRecallCount: ${resolved.deep.minRecallCount}`,
 					`deep.limit: ${resolved.deep.limit}`,
 					"",
-					`storePath: ${SHORT_TERM_RECALL_STORE_RELATIVE}`,
+					`agentId: ${agentId ?? "(unknown)"}`,
+					`storePath: ${storePath}`,
 					`entryCount: ${total}`,
 					`promotedCount: ${promoted}`,
 					`promotedToday: ${promotedToday}`,
@@ -76,17 +79,17 @@ function createDreamingTool(deps) {
 				].join("\n"));
 			}
 			if (action === "reset_store") {
-				const { store } = await loadDreamingStore({ workspaceDir });
+				const { store } = await loadDreamingStore({ dreamingRoot });
 				const before = Object.keys(store.entries ?? {}).length;
 				const nowIso = (/* @__PURE__ */ new Date()).toISOString();
 				store.entries = {};
 				store.updatedAt = nowIso;
 				await saveDreamingStore({
-					workspaceDir,
+					dreamingRoot,
 					store
 				});
 				log.info({
-					workspaceDir,
+					dreamingRoot,
 					before
 				}, "Dreaming store reset");
 				return textResult(`Reset short-term store. Removed ${before} entr${before === 1 ? "y" : "ies"}. Path: ${storePath}`);

package/dist/src/agent/tools/dreaming-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"dreaming-tool.js","names":[],"sources":["../../../../src/agent/tools/dreaming-tool.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { createLogger } from '../../utils/logger.js';\nimport { resolveDreamingConfig } from '../memory/dreaming/config.js';\nimport {\n  SHORT_TERM_PROMOTION_LOCK_RELATIVE,\n  SHORT_TERM_RECALL_STORE_RELATIVE,\n} from '../memory/dreaming/constants.js';\nimport { loadDreamingStore, saveDreamingStore } from '../memory/dreaming/short-term-store.js';\n\nconst log = createLogger('DreamingTool');\n\nconst DreamingSchema = Type.Object({\n  action: Type.Union([Type.Literal('status'), Type.Literal('reset_store'), Type.Literal('clear_lock')]),\n});\n\ntype DreamingParams = {\n  action: 'status' | 'reset_store' | 'clear_lock';\n};\n\nexport interface DreamingToolDeps {\n  getWorkspace: () => string;\n  getConfig: () => Config | undefined;\n}\n\nfunction textResult(text: string): AgentToolResult<{}> {\n  return { content: [{ type: 'text', text }], details: {} };\n}\n\nfunction safeStatMs(ms: number | undefined): number | null {\n  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) return null;\n  return Math.floor(ms);\n}\n\nfunction isoDay(isoLike: string | undefined): string | null {\n  if (!isoLike) return null;\n  const m = isoLike.match(/^(\\d{4}-\\d{2}-\\d{2})/);\n  return m?.[1] ?? null;\n}\n\nexport function createDreamingTool(deps: DreamingToolDeps): AgentTool {\n  return {\n    name: 'dreaming',\n    label: '💤 Dreaming',\n    description:\n      'Inspect and maintain the dreaming promotion state.\\n\\n' +\n      'Actions:\\n' +\n      '- status: show config gates and short-term store stats\\n' +\n      '- reset_store: clear short-term recall store (memory/.dreams/short-term-recall.json)\\n' +\n      '- clear_lock: remove a stale promotion lock file (memory/.dreams/short-term-promotion.lock)',\n    parameters: DreamingSchema,\n    async execute(_toolCallId, params: any): Promise<AgentToolResult<{}>> {\n      const action = (params as DreamingParams).action;\n      const workspaceDir = deps.getWorkspace();\n      const cfg = deps.getConfig();\n      const resolved = resolveDreamingConfig(cfg);\n\n      const storePath = path.join(workspaceDir, SHORT_TERM_RECALL_STORE_RELATIVE);\n      const lockPath = path.join(workspaceDir, SHORT_TERM_PROMOTION_LOCK_RELATIVE);\n\n      if (action === 'status') {\n        const { store } = await loadDreamingStore({ workspaceDir });\n        const entries = Object.values(store.entries ?? {});\n        const total = entries.length;\n        const promoted = entries.filter((e) => Boolean(e.promotedAt)).length;\n        const today = new Date().toISOString().slice(0, 10);\n        const promotedToday = entries.filter((e) => isoDay(e.promotedAt) === today).length;\n        const lastPromotedAt = entries\n          .map((e) => e.promotedAt)\n          .filter((x): x is string => typeof x === 'string' && x.length > 0)\n          .sort()\n          .at(-1);\n\n        const lockStat = await fs.stat(lockPath).catch(() => null);\n        const lockAgeMs =\n          lockStat && safeStatMs(lockStat.mtimeMs) ? Date.now() - Math.floor(lockStat.mtimeMs) : null;\n\n        const lines = [\n          'Dreaming status',\n          '',\n          `enabled: ${resolved.enabled ? 'true' : 'false'}`,\n          `deep.enabled: ${resolved.deep.enabled ? 'true' : 'false'}`,\n          `cron.frequency: ${resolved.frequency}`,\n          `cron.timezone: ${resolved.timezone ?? '(default)'}`,\n          `deep.minScore: ${resolved.deep.minScore}`,\n          `deep.minRecallCount: ${resolved.deep.minRecallCount}`,\n          `deep.limit: ${resolved.deep.limit}`,\n          '',\n          `storePath: ${SHORT_TERM_RECALL_STORE_RELATIVE}`,\n          `entryCount: ${total}`,\n          `promotedCount: ${promoted}`,\n          `promotedToday: ${promotedToday}`,\n          `lastPromotedAt: ${lastPromotedAt ?? '(none)'}`,\n          '',\n          `lockPath: ${SHORT_TERM_PROMOTION_LOCK_RELATIVE}`,\n          `lockPresent: ${lockStat ? 'true' : 'false'}`,\n          `lockAgeMs: ${lockAgeMs ?? '(n/a)'}`,\n        ];\n        return textResult(lines.join('\\n'));\n      }\n\n      if (action === 'reset_store') {\n        const { store } = await loadDreamingStore({ workspaceDir });\n        const before = Object.keys(store.entries ?? {}).length;\n        const nowIso = new Date().toISOString();\n        store.entries = {};\n        store.updatedAt = nowIso;\n        await saveDreamingStore({ workspaceDir, store });\n        log.info({ workspaceDir, before }, 'Dreaming store reset');\n        return textResult(\n          `Reset short-term store. Removed ${before} entr${before === 1 ? 'y' : 'ies'}. Path: ${storePath}`,\n        );\n      }\n\n      await fs.unlink(lockPath).catch(() => {});\n      return textResult(`Cleared lock (if present). Path: ${lockPath}`);\n    },\n  } as any;\n}\n\n"],"mappings":";;;;;;;;;aAOqD;AAQrD,MAAM,MAAM,aAAa,eAAe;AAExC,MAAM,iBAAiB,KAAK,OAAO,EACjC,QAAQ,KAAK,MAAM;CAAC,KAAK,QAAQ,SAAS;CAAE,KAAK,QAAQ,cAAc;CAAE,KAAK,QAAQ,aAAa;CAAC,CAAC,EACtG,CAAC;AAWF,SAAS,WAAW,MAAmC;AACrD,QAAO;EAAE,SAAS,CAAC;GAAE,MAAM;GAAQ;GAAM,CAAC;EAAE,SAAS,EAAE;EAAE;;AAG3D,SAAS,WAAW,IAAuC;AACzD,KAAI,OAAO,OAAO,YAAY,CAAC,OAAO,SAAS,GAAG,IAAI,MAAM,EAAG,QAAO;AACtE,QAAO,KAAK,MAAM,GAAG;;AAGvB,SAAS,OAAO,SAA4C;AAC1D,KAAI,CAAC,QAAS,QAAO;AAErB,QADU,QAAQ,MAAM,uBAChB,GAAG,MAAM;;AAGnB,SAAgB,mBAAmB,MAAmC;AACpE,QAAO;EACL,MAAM;EACN,OAAO;EACP,aACE;EAKF,YAAY;EACZ,MAAM,QAAQ,aAAa,QAA2C;GACpE,MAAM,SAAU,OAA0B;GAC1C,MAAM,eAAe,KAAK,cAAc;GAExC,MAAM,WAAW,sBADL,KAAK,WACyB,CAAC;GAE3C,MAAM,YAAY,KAAK,KAAK,cAAc,iCAAiC;GAC3E,MAAM,WAAW,KAAK,KAAK,cAAc,mCAAmC;AAE5E,OAAI,WAAW,UAAU;IACvB,MAAM,EAAE,UAAU,MAAM,kBAAkB,EAAE,cAAc,CAAC;IAC3D,MAAM,UAAU,OAAO,OAAO,MAAM,WAAW,EAAE,CAAC;IAClD,MAAM,QAAQ,QAAQ;IACtB,MAAM,WAAW,QAAQ,QAAQ,MAAM,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC9D,MAAM,yBAAQ,IAAI,MAAM,EAAC,aAAa,CAAC,MAAM,GAAG,GAAG;IACnD,MAAM,gBAAgB,QAAQ,QAAQ,MAAM,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IAC5E,MAAM,iBAAiB,QACpB,KAAK,MAAM,EAAE,WAAW,CACxB,QAAQ,MAAmB,OAAO,MAAM,YAAY,EAAE,SAAS,EAAE,CACjE,MAAM,CACN,GAAG,GAAG;IAET,MAAM,WAAW,MAAM,GAAG,KAAK,SAAS,CAAC,YAAY,KAAK;IAC1D,MAAM,YACJ,YAAY,WAAW,SAAS,QAAQ,GAAG,KAAK,KAAK,GAAG,KAAK,MAAM,SAAS,QAAQ,GAAG;AAuBzF,WAAO,WAAW;KApBhB;KACA;KACA,YAAY,SAAS,UAAU,SAAS;KACxC,iBAAiB,SAAS,KAAK,UAAU,SAAS;KAClD,mBAAmB,SAAS;KAC5B,kBAAkB,SAAS,YAAY;KACvC,kBAAkB,SAAS,KAAK;KAChC,wBAAwB,SAAS,KAAK;KACtC,eAAe,SAAS,KAAK;KAC7B;KACA,cAAc;KACd,eAAe;KACf,kBAAkB;KAClB,kBAAkB;KAClB,mBAAmB,kBAAkB;KACrC;KACA,aAAa;KACb,gBAAgB,WAAW,SAAS;KACpC,cAAc,aAAa;KAEN,CAAC,KAAK,KAAK,CAAC;;AAGrC,OAAI,WAAW,eAAe;IAC5B,MAAM,EAAE,UAAU,MAAM,kBAAkB,EAAE,cAAc,CAAC;IAC3D,MAAM,SAAS,OAAO,KAAK,MAAM,WAAW,EAAE,CAAC,CAAC;IAChD,MAAM,0BAAS,IAAI,MAAM,EAAC,aAAa;AACvC,UAAM,UAAU,EAAE;AAClB,UAAM,YAAY;AAClB,UAAM,kBAAkB;KAAE;KAAc;KAAO,CAAC;AAChD,QAAI,KAAK;KAAE;KAAc;KAAQ,EAAE,uBAAuB;AAC1D,WAAO,WACL,mCAAmC,OAAO,OAAO,WAAW,IAAI,MAAM,MAAM,UAAU,YACvF;;AAGH,SAAM,GAAG,OAAO,SAAS,CAAC,YAAY,GAAG;AACzC,UAAO,WAAW,oCAAoC,WAAW;;EAEpE"}
+{"version":3,"file":"dreaming-tool.js","names":[],"sources":["../../../../src/agent/tools/dreaming-tool.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { createLogger } from '../../utils/logger.js';\nimport { resolveDreamingConfig } from '../memory/dreaming/config.js';\nimport {\n  SHORT_TERM_PROMOTION_LOCK_RELATIVE,\n  SHORT_TERM_RECALL_STORE_RELATIVE,\n} from '../memory/dreaming/constants.js';\nimport { loadDreamingStore, saveDreamingStore } from '../memory/dreaming/short-term-store.js';\n\nconst log = createLogger('DreamingTool');\n\nconst DreamingSchema = Type.Object({\n  action: Type.Union([Type.Literal('status'), Type.Literal('reset_store'), Type.Literal('clear_lock')]),\n});\n\ntype DreamingParams = {\n  action: 'status' | 'reset_store' | 'clear_lock';\n};\n\nexport interface DreamingToolDeps {\n  getWorkspace: () => string;\n  getDreamingRoot: () => string;\n  getConfig: () => Config | undefined;\n  getAgentId?: () => string | undefined;\n}\n\nfunction textResult(text: string): AgentToolResult<{}> {\n  return { content: [{ type: 'text', text }], details: {} };\n}\n\nfunction safeStatMs(ms: number | undefined): number | null {\n  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) return null;\n  return Math.floor(ms);\n}\n\nfunction isoDay(isoLike: string | undefined): string | null {\n  if (!isoLike) return null;\n  const m = isoLike.match(/^(\\d{4}-\\d{2}-\\d{2})/);\n  return m?.[1] ?? null;\n}\n\nexport function createDreamingTool(deps: DreamingToolDeps): AgentTool {\n  return {\n    name: 'dreaming',\n    label: '💤 Dreaming',\n    description:\n      'Inspect and maintain the dreaming promotion state.\\n\\n' +\n      'Actions:\\n' +\n      '- status: show config gates and short-term store stats\\n' +\n      '- reset_store: clear this agent short-term recall store (.dreams/short-term-recall.json)\\n' +\n      '- clear_lock: remove this agent stale promotion lock file (.dreams/short-term-promotion.lock)',\n    parameters: DreamingSchema,\n    async execute(_toolCallId, params: any): Promise<AgentToolResult<{}>> {\n      const action = (params as DreamingParams).action;\n      const dreamingRoot = deps.getDreamingRoot();\n      const cfg = deps.getConfig();\n      const agentId = deps.getAgentId?.();\n      const resolved = resolveDreamingConfig(cfg, agentId);\n\n      const storePath = path.join(dreamingRoot, SHORT_TERM_RECALL_STORE_RELATIVE);\n      const lockPath = path.join(dreamingRoot, SHORT_TERM_PROMOTION_LOCK_RELATIVE);\n\n      if (action === 'status') {\n        const { store } = await loadDreamingStore({ dreamingRoot });\n        const entries = Object.values(store.entries ?? {});\n        const total = entries.length;\n        const promoted = entries.filter((e) => Boolean(e.promotedAt)).length;\n        const today = new Date().toISOString().slice(0, 10);\n        const promotedToday = entries.filter((e) => isoDay(e.promotedAt) === today).length;\n        const lastPromotedAt = entries\n          .map((e) => e.promotedAt)\n          .filter((x): x is string => typeof x === 'string' && x.length > 0)\n          .sort()\n          .at(-1);\n\n        const lockStat = await fs.stat(lockPath).catch(() => null);\n        const lockAgeMs =\n          lockStat && safeStatMs(lockStat.mtimeMs) ? Date.now() - Math.floor(lockStat.mtimeMs) : null;\n\n        const lines = [\n          'Dreaming status',\n          '',\n          `enabled: ${resolved.enabled ? 'true' : 'false'}`,\n          `deep.enabled: ${resolved.deep.enabled ? 'true' : 'false'}`,\n          `cron.frequency: ${resolved.frequency}`,\n          `cron.timezone: ${resolved.timezone ?? '(default)'}`,\n          `deep.minScore: ${resolved.deep.minScore}`,\n          `deep.minRecallCount: ${resolved.deep.minRecallCount}`,\n          `deep.limit: ${resolved.deep.limit}`,\n          '',\n          `agentId: ${agentId ?? '(unknown)'}`,\n          `storePath: ${storePath}`,\n          `entryCount: ${total}`,\n          `promotedCount: ${promoted}`,\n          `promotedToday: ${promotedToday}`,\n          `lastPromotedAt: ${lastPromotedAt ?? '(none)'}`,\n          '',\n          `lockPath: ${SHORT_TERM_PROMOTION_LOCK_RELATIVE}`,\n          `lockPresent: ${lockStat ? 'true' : 'false'}`,\n          `lockAgeMs: ${lockAgeMs ?? '(n/a)'}`,\n        ];\n        return textResult(lines.join('\\n'));\n      }\n\n      if (action === 'reset_store') {\n        const { store } = await loadDreamingStore({ dreamingRoot });\n        const before = Object.keys(store.entries ?? {}).length;\n        const nowIso = new Date().toISOString();\n        store.entries = {};\n        store.updatedAt = nowIso;\n        await saveDreamingStore({ dreamingRoot, store });\n        log.info({ dreamingRoot, before }, 'Dreaming store reset');\n        return textResult(\n          `Reset short-term store. Removed ${before} entr${before === 1 ? 'y' : 'ies'}. Path: ${storePath}`,\n        );\n      }\n\n      await fs.unlink(lockPath).catch(() => {});\n      return textResult(`Cleared lock (if present). Path: ${lockPath}`);\n    },\n  } as any;\n}\n"],"mappings":"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"}

package/dist/src/agent/tools/exec-command.d.ts

@@ -0,0 +1,30 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { GoalEvidenceRecordInput } from './goal-evidence-recorder.js';
+export interface ExecCommandDetails {
+    command: string;
+    cwd: string;
+    status: 'success' | 'failed' | 'timed_out' | 'blocked';
+    exitCode: number | null;
+    durationMs: number;
+    timedOut: boolean;
+    truncated: boolean;
+    truncatedBy?: 'lines' | 'bytes' | null;
+    outputBytes: number;
+    stdout: string;
+    stderr: string;
+    aggregatedOutput: string;
+    failureHint?: string;
+}
+export interface ExecCommandUpdateDetails {
+    kind: 'command_output_delta';
+    command: string;
+    cwd: string;
+    stream: 'stdout' | 'stderr';
+    delta: string;
+}
+export interface CreateExecCommandToolOptions {
+    /** Env var names allowed through prepareSafeToolEnv even if they match secret heuristics. */
+    getSkillPassthroughEnvVarNames?: () => string[];
+    recordGoalEvidence?: (input: GoalEvidenceRecordInput) => Promise<void> | void;
+}
+export declare function createExecCommandTool(workspaceCwd: string, options?: CreateExecCommandToolOptions): AgentTool;

package/dist/src/agent/tools/exec-command.js

@@ -0,0 +1,228 @@
+import { formatSize, truncateTail } from "./truncate.js";
+import { evaluateExecPolicy } from "../sandbox/exec-policy.js";
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/exec-command.ts
+const MAX_COMMAND_TIMEOUT_MS = 3e5;
+const DEFAULT_TIMEOUT_MS = 12e4;
+const DEFAULT_MAX_OUTPUT_CHARS = 5e4;
+const STREAM_DELTA_MAX_CHARS = 16e3;
+const ExecCommandSchema = Type.Object({
+	cmd: Type.String({ description: "Shell command to execute." }),
+	cwd: Type.Optional(Type.String({ description: "Working directory. Relative paths are resolved under the agent workspace." })),
+	timeoutMs: Type.Optional(Type.Number({ description: "Command timeout in milliseconds. Defaults to 120000 and is capped at 300000." })),
+	maxOutputChars: Type.Optional(Type.Number({ description: "Maximum characters returned to the model. UI streaming still receives output deltas." }))
+});
+function clampTimeoutMs(raw) {
+	return Math.min(MAX_COMMAND_TIMEOUT_MS, Math.max(1e3, Math.floor(typeof raw === "number" && Number.isFinite(raw) ? raw : DEFAULT_TIMEOUT_MS)));
+}
+function clampMaxOutputChars(raw) {
+	return Math.max(1e3, Math.min(5e5, Math.floor(typeof raw === "number" && Number.isFinite(raw) ? raw : DEFAULT_MAX_OUTPUT_CHARS)));
+}
+function isLikelyTestCommand(command) {
+	return /\b(test|vitest|jest|pytest|go test|cargo test|npm test|pnpm test|yarn test|typecheck|type-check|lint)\b/i.test(command);
+}
+function commandStatus(exitCode, timedOut) {
+	if (timedOut) return "timed_out";
+	if (exitCode === 0) return "success";
+	return "failed";
+}
+function commandFailureHint(details) {
+	if (details.status === "success") return void 0;
+	if (details.status === "timed_out") return "The command timed out. Re-run a narrower command, increase timeoutMs if the long run is expected, or inspect partial output before retrying.";
+	if (details.exitCode !== 0 && details.stderr.trim()) return "The command failed. Inspect stderr first, fix the underlying issue, then re-run the narrowest relevant verification command.";
+	if (details.exitCode !== 0 && details.stdout.trim()) return "The command failed. Inspect stdout for the failure location, then re-run the narrowest relevant verification command.";
+	return "The command failed without output. Verify the command, cwd, and required dependencies before retrying.";
+}
+function formatOutputForModel(details, maxOutputChars) {
+	let prefix = "";
+	if (details.timedOut) prefix += `Command timed out after ${Math.round(details.durationMs / 1e3)}s\n`;
+	if (details.exitCode !== 0 && details.exitCode != null) prefix += `Command exited with code ${details.exitCode}\n`;
+	const truncation = truncateTail(details.aggregatedOutput, { maxBytes: Math.min(maxOutputChars, DEFAULT_MAX_OUTPUT_CHARS) });
+	let text = `${prefix}${truncation.content}`.trimEnd();
+	if (!text) text = "(no output)";
+	if (truncation.truncated) text += `\n\n[Output truncated: ${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}]`;
+	if (details.failureHint) text += `\n\nNext action: ${details.failureHint}`;
+	return {
+		text,
+		truncated: truncation.truncated,
+		truncatedBy: truncation.truncatedBy,
+		outputBytes: truncation.outputBytes
+	};
+}
+function createExecCommandTool(workspaceCwd, options) {
+	return {
+		name: "exec_command",
+		description: [
+			"Run shell commands for code inspection, builds, tests, type checks, and verification.",
+			"Use apply_patch for file edits; do not edit files by shell redirection unless explicitly necessary.",
+			"Relative cwd values resolve under the current agent workspace."
+		].join(" "),
+		parameters: ExecCommandSchema,
+		label: "Run Command",
+		mutationScope: "unknown",
+		supportsParallel: false,
+		idempotent: false,
+		finalGuardRelevant: true,
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const command = (params.cmd ?? params.command ?? "").trim();
+			if (!command) return {
+				content: [{
+					type: "text",
+					text: "Error: cmd is required"
+				}],
+				details: {
+					command,
+					cwd: workspaceCwd,
+					status: "failed",
+					exitCode: null,
+					durationMs: 0,
+					timedOut: false,
+					truncated: false,
+					outputBytes: 0,
+					stdout: "",
+					stderr: "cmd is required",
+					aggregatedOutput: "cmd is required",
+					failureHint: "Provide a non-empty cmd value."
+				}
+			};
+			const requestedCwd = params.cwd?.trim() ? resolve(workspaceCwd, params.cwd.trim()) : workspaceCwd;
+			const policy = evaluateExecPolicy({
+				command,
+				cwd: requestedCwd,
+				allowedEnvVars: options?.getSkillPassthroughEnvVarNames?.() ?? []
+			});
+			if (!policy.allowed) {
+				const text = `Sandbox blocked command: ${policy.reason}`;
+				return {
+					content: [{
+						type: "text",
+						text
+					}],
+					details: {
+						command,
+						cwd: requestedCwd,
+						status: "blocked",
+						exitCode: null,
+						durationMs: 0,
+						timedOut: false,
+						truncated: false,
+						outputBytes: Buffer.byteLength(text),
+						stdout: "",
+						stderr: text,
+						aggregatedOutput: text,
+						failureHint: "Use a narrower workspace-safe command or inspect files with read/search tools instead."
+					}
+				};
+			}
+			const timeoutMs = Math.min(clampTimeoutMs(params.timeoutMs), policy.timeoutMs);
+			const maxOutputChars = clampMaxOutputChars(params.maxOutputChars);
+			const startTime = Date.now();
+			let stdout = "";
+			let stderr = "";
+			let aggregatedOutput = "";
+			let timedOut = false;
+			let settled = false;
+			return new Promise((resolveTool) => {
+				const proc = spawn(command, [], {
+					shell: true,
+					cwd: policy.effectiveCwd,
+					env: {
+						...policy.sanitizedEnv,
+						COLUMNS: "200"
+					}
+				});
+				const publishDelta = (stream, raw) => {
+					const text = raw.toString();
+					if (!text) return;
+					if (stream === "stdout") stdout += text;
+					else stderr += text;
+					aggregatedOutput += text;
+					const delta = text.length > STREAM_DELTA_MAX_CHARS ? `${text.slice(0, STREAM_DELTA_MAX_CHARS)}\n[stream delta truncated]` : text;
+					onUpdate?.({
+						content: [],
+						details: {
+							kind: "command_output_delta",
+							command,
+							cwd: policy.effectiveCwd,
+							stream,
+							delta
+						}
+					});
+				};
+				const finish = (exitCode, errorText) => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timeout);
+					signal?.removeEventListener("abort", abort);
+					if (errorText) {
+						stderr += errorText;
+						aggregatedOutput += errorText;
+					}
+					const durationMs = Date.now() - startTime;
+					const baseDetails = {
+						command,
+						cwd: policy.effectiveCwd,
+						status: commandStatus(exitCode, timedOut),
+						exitCode,
+						durationMs,
+						timedOut,
+						truncated: false,
+						outputBytes: Buffer.byteLength(aggregatedOutput),
+						stdout,
+						stderr,
+						aggregatedOutput
+					};
+					baseDetails.failureHint = commandFailureHint(baseDetails);
+					const formatted = formatOutputForModel(baseDetails, maxOutputChars);
+					const details = {
+						...baseDetails,
+						truncated: formatted.truncated,
+						truncatedBy: formatted.truncatedBy,
+						outputBytes: formatted.outputBytes
+					};
+					const result = {
+						content: [{
+							type: "text",
+							text: formatted.text
+						}],
+						details
+					};
+					Promise.resolve(options?.recordGoalEvidence?.({
+						kind: timedOut || exitCode !== 0 ? "command" : isLikelyTestCommand(command) ? "test" : "command",
+						title: `Command: ${command.slice(0, 120)}`,
+						summary: formatted.text.slice(0, 2e3),
+						data: {
+							command,
+							cwd: policy.effectiveCwd,
+							exitCode,
+							durationMs,
+							timedOut,
+							truncated: details.truncated,
+							outputBytes: details.outputBytes
+						}
+					})).finally(() => resolveTool(result));
+				};
+				const abort = () => {
+					timedOut = true;
+					proc.kill("SIGKILL");
+				};
+				const timeout = setTimeout(() => {
+					timedOut = true;
+					proc.kill("SIGKILL");
+				}, timeoutMs);
+				if (signal?.aborted) abort();
+				else signal?.addEventListener("abort", abort, { once: true });
+				proc.stdout?.on("data", (data) => publishDelta("stdout", data));
+				proc.stderr?.on("data", (data) => publishDelta("stderr", data));
+				proc.on("error", (err) => finish(null, `Error: ${err.message}`));
+				proc.on("close", (code) => finish(code));
+			});
+		}
+	};
+}
+//#endregion
+export { createExecCommandTool };
+
+//# sourceMappingURL=exec-command.js.map

package/dist/src/agent/tools/exec-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-command.js","names":[],"sources":["../../../../src/agent/tools/exec-command.ts"],"sourcesContent":["import { Type } from '@sinclair/typebox';\nimport type {\n  AgentTool,\n  AgentToolResult,\n  AgentToolUpdateCallback,\n} from '@earendil-works/pi-agent-core';\nimport { spawn } from 'node:child_process';\nimport { resolve } from 'node:path';\n\nimport { evaluateExecPolicy } from '../sandbox/exec-policy.js';\nimport { formatSize, truncateTail } from './truncate.js';\nimport type { GoalEvidenceRecordInput } from './goal-evidence-recorder.js';\n\nconst MAX_COMMAND_TIMEOUT_MS = 300_000;\nconst DEFAULT_TIMEOUT_MS = 120_000;\nconst DEFAULT_MAX_OUTPUT_CHARS = 50_000;\nconst STREAM_DELTA_MAX_CHARS = 16_000;\n\nconst ExecCommandSchema = Type.Object({\n  cmd: Type.String({ description: 'Shell command to execute.' }),\n  cwd: Type.Optional(\n    Type.String({\n      description: 'Working directory. Relative paths are resolved under the agent workspace.',\n    }),\n  ),\n  timeoutMs: Type.Optional(\n    Type.Number({\n      description: 'Command timeout in milliseconds. Defaults to 120000 and is capped at 300000.',\n    }),\n  ),\n  maxOutputChars: Type.Optional(\n    Type.Number({\n      description: 'Maximum characters returned to the model. UI streaming still receives output deltas.',\n    }),\n  ),\n});\n\nexport interface ExecCommandDetails {\n  command: string;\n  cwd: string;\n  status: 'success' | 'failed' | 'timed_out' | 'blocked';\n  exitCode: number | null;\n  durationMs: number;\n  timedOut: boolean;\n  truncated: boolean;\n  truncatedBy?: 'lines' | 'bytes' | null;\n  outputBytes: number;\n  stdout: string;\n  stderr: string;\n  aggregatedOutput: string;\n  failureHint?: string;\n}\n\nexport interface ExecCommandUpdateDetails {\n  kind: 'command_output_delta';\n  command: string;\n  cwd: string;\n  stream: 'stdout' | 'stderr';\n  delta: string;\n}\n\nexport interface CreateExecCommandToolOptions {\n  /** Env var names allowed through prepareSafeToolEnv even if they match secret heuristics. */\n  getSkillPassthroughEnvVarNames?: () => string[];\n  recordGoalEvidence?: (input: GoalEvidenceRecordInput) => Promise<void> | void;\n}\n\ntype ExecCommandParams = {\n  cmd?: string;\n  command?: string;\n  cwd?: string;\n  timeoutMs?: number;\n  maxOutputChars?: number;\n};\n\nfunction clampTimeoutMs(raw: unknown): number {\n  const n = typeof raw === 'number' && Number.isFinite(raw) ? raw : DEFAULT_TIMEOUT_MS;\n  return Math.min(MAX_COMMAND_TIMEOUT_MS, Math.max(1_000, Math.floor(n)));\n}\n\nfunction clampMaxOutputChars(raw: unknown): number {\n  const n = typeof raw === 'number' && Number.isFinite(raw) ? raw : DEFAULT_MAX_OUTPUT_CHARS;\n  return Math.max(1_000, Math.min(500_000, Math.floor(n)));\n}\n\nfunction isLikelyTestCommand(command: string): boolean {\n  return /\\b(test|vitest|jest|pytest|go test|cargo test|npm test|pnpm test|yarn test|typecheck|type-check|lint)\\b/i.test(command);\n}\n\nfunction commandStatus(exitCode: number | null, timedOut: boolean): ExecCommandDetails['status'] {\n  if (timedOut) return 'timed_out';\n  if (exitCode === 0) return 'success';\n  return 'failed';\n}\n\nfunction commandFailureHint(details: Pick<ExecCommandDetails, 'status' | 'exitCode' | 'timedOut' | 'stderr' | 'stdout'>): string | undefined {\n  if (details.status === 'success') return undefined;\n  if (details.status === 'timed_out') {\n    return 'The command timed out. Re-run a narrower command, increase timeoutMs if the long run is expected, or inspect partial output before retrying.';\n  }\n  if (details.exitCode !== 0 && details.stderr.trim()) {\n    return 'The command failed. Inspect stderr first, fix the underlying issue, then re-run the narrowest relevant verification command.';\n  }\n  if (details.exitCode !== 0 && details.stdout.trim()) {\n    return 'The command failed. Inspect stdout for the failure location, then re-run the narrowest relevant verification command.';\n  }\n  return 'The command failed without output. Verify the command, cwd, and required dependencies before retrying.';\n}\n\nfunction formatOutputForModel(\n  details: ExecCommandDetails,\n  maxOutputChars: number,\n): { text: string; truncated: boolean; truncatedBy?: 'lines' | 'bytes' | null; outputBytes: number } {\n  let prefix = '';\n  if (details.timedOut) {\n    prefix += `Command timed out after ${Math.round(details.durationMs / 1000)}s\\n`;\n  }\n  if (details.exitCode !== 0 && details.exitCode != null) {\n    prefix += `Command exited with code ${details.exitCode}\\n`;\n  }\n\n  const truncation = truncateTail(details.aggregatedOutput, {\n    maxBytes: Math.min(maxOutputChars, DEFAULT_MAX_OUTPUT_CHARS),\n  });\n  let text = `${prefix}${truncation.content}`.trimEnd();\n  if (!text) text = '(no output)';\n  if (truncation.truncated) {\n    text += `\\n\\n[Output truncated: ${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}]`;\n  }\n  if (details.failureHint) {\n    text += `\\n\\nNext action: ${details.failureHint}`;\n  }\n  return {\n    text,\n    truncated: truncation.truncated,\n    truncatedBy: truncation.truncatedBy,\n    outputBytes: truncation.outputBytes,\n  };\n}\n\nexport function createExecCommandTool(\n  workspaceCwd: string,\n  options?: CreateExecCommandToolOptions,\n): AgentTool {\n  return {\n    name: 'exec_command',\n    description: [\n      'Run shell commands for code inspection, builds, tests, type checks, and verification.',\n      'Use apply_patch for file edits; do not edit files by shell redirection unless explicitly necessary.',\n      'Relative cwd values resolve under the current agent workspace.',\n    ].join(' '),\n    parameters: ExecCommandSchema,\n    label: 'Run Command',\n    mutationScope: 'unknown',\n    supportsParallel: false,\n    idempotent: false,\n    finalGuardRelevant: true,\n\n    async execute(\n      _toolCallId: string,\n      params: ExecCommandParams,\n      signal?: AbortSignal,\n      onUpdate?: AgentToolUpdateCallback<ExecCommandUpdateDetails>,\n    ): Promise<AgentToolResult<ExecCommandDetails>> {\n      const command = (params.cmd ?? params.command ?? '').trim();\n      if (!command) {\n        return {\n          content: [{ type: 'text', text: 'Error: cmd is required' }],\n          details: {\n            command,\n            cwd: workspaceCwd,\n            status: 'failed',\n            exitCode: null,\n            durationMs: 0,\n            timedOut: false,\n            truncated: false,\n            outputBytes: 0,\n            stdout: '',\n            stderr: 'cmd is required',\n            aggregatedOutput: 'cmd is required',\n            failureHint: 'Provide a non-empty cmd value.',\n          },\n        };\n      }\n\n      const requestedCwd = params.cwd?.trim()\n        ? resolve(workspaceCwd, params.cwd.trim())\n        : workspaceCwd;\n      const passthroughNames = options?.getSkillPassthroughEnvVarNames?.() ?? [];\n      const policy = evaluateExecPolicy({\n        command,\n        cwd: requestedCwd,\n        allowedEnvVars: passthroughNames,\n      });\n      if (!policy.allowed) {\n        const text = `Sandbox blocked command: ${policy.reason}`;\n        return {\n          content: [{ type: 'text', text }],\n          details: {\n            command,\n            cwd: requestedCwd,\n            status: 'blocked',\n            exitCode: null,\n            durationMs: 0,\n            timedOut: false,\n            truncated: false,\n            outputBytes: Buffer.byteLength(text),\n            stdout: '',\n            stderr: text,\n            aggregatedOutput: text,\n            failureHint: 'Use a narrower workspace-safe command or inspect files with read/search tools instead.',\n          },\n        };\n      }\n\n      const timeoutMs = Math.min(clampTimeoutMs(params.timeoutMs), policy.timeoutMs);\n      const maxOutputChars = clampMaxOutputChars(params.maxOutputChars);\n      const startTime = Date.now();\n      let stdout = '';\n      let stderr = '';\n      let aggregatedOutput = '';\n      let timedOut = false;\n      let settled = false;\n\n      return new Promise((resolveTool) => {\n        const proc = spawn(command, [], {\n          shell: true,\n          cwd: policy.effectiveCwd,\n          env: {\n            ...policy.sanitizedEnv,\n            COLUMNS: '200',\n          },\n        });\n\n        const publishDelta = (stream: 'stdout' | 'stderr', raw: Buffer | string) => {\n          const text = raw.toString();\n          if (!text) return;\n          if (stream === 'stdout') stdout += text;\n          else stderr += text;\n          aggregatedOutput += text;\n\n          const delta = text.length > STREAM_DELTA_MAX_CHARS\n            ? `${text.slice(0, STREAM_DELTA_MAX_CHARS)}\\n[stream delta truncated]`\n            : text;\n          onUpdate?.({\n            content: [],\n            details: {\n              kind: 'command_output_delta',\n              command,\n              cwd: policy.effectiveCwd,\n              stream,\n              delta,\n            },\n          });\n        };\n\n        const finish = (\n          exitCode: number | null,\n          errorText?: string,\n        ) => {\n          if (settled) return;\n          settled = true;\n          clearTimeout(timeout);\n          signal?.removeEventListener('abort', abort);\n          if (errorText) {\n            stderr += errorText;\n            aggregatedOutput += errorText;\n          }\n\n          const durationMs = Date.now() - startTime;\n          const baseDetails: ExecCommandDetails = {\n            command,\n            cwd: policy.effectiveCwd,\n            status: commandStatus(exitCode, timedOut),\n            exitCode,\n            durationMs,\n            timedOut,\n            truncated: false,\n            outputBytes: Buffer.byteLength(aggregatedOutput),\n            stdout,\n            stderr,\n            aggregatedOutput,\n          };\n          baseDetails.failureHint = commandFailureHint(baseDetails);\n          const formatted = formatOutputForModel(baseDetails, maxOutputChars);\n          const details: ExecCommandDetails = {\n            ...baseDetails,\n            truncated: formatted.truncated,\n            truncatedBy: formatted.truncatedBy,\n            outputBytes: formatted.outputBytes,\n          };\n\n          const result: AgentToolResult<ExecCommandDetails> = {\n            content: [{ type: 'text', text: formatted.text }],\n            details,\n          };\n\n          void Promise.resolve(options?.recordGoalEvidence?.({\n            kind: timedOut || exitCode !== 0 ? 'command' : isLikelyTestCommand(command) ? 'test' : 'command',\n            title: `Command: ${command.slice(0, 120)}`,\n            summary: formatted.text.slice(0, 2000),\n            data: {\n              command,\n              cwd: policy.effectiveCwd,\n              exitCode,\n              durationMs,\n              timedOut,\n              truncated: details.truncated,\n              outputBytes: details.outputBytes,\n            },\n          })).finally(() => resolveTool(result));\n        };\n\n        const abort = () => {\n          timedOut = true;\n          proc.kill('SIGKILL');\n        };\n\n        const timeout = setTimeout(() => {\n          timedOut = true;\n          proc.kill('SIGKILL');\n        }, timeoutMs);\n\n        if (signal?.aborted) {\n          abort();\n        } else {\n          signal?.addEventListener('abort', abort, { once: true });\n        }\n\n        proc.stdout?.on('data', (data) => publishDelta('stdout', data));\n        proc.stderr?.on('data', (data) => publishDelta('stderr', data));\n        proc.on('error', (err) => finish(null, `Error: ${err.message}`));\n        proc.on('close', (code) => finish(code));\n      });\n    },\n  } as any;\n}\n"],"mappings":"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"}

package/dist/src/agent/tools/execute-code-tool.js

@@ -10,7 +10,7 @@ const DEFAULT_TIMEOUT_SEC = 1800;
 /** Hard cap for `timeout` parameter (4 hours). */
 const MAX_TIMEOUT_SEC = 14400;
 const ExecuteCodeSchema = Type.Object({
-	code: Type.String({ description: "JavaScript to run. Exposed as `tools` (async functions) and `console`:\n  await tools.web_search(query, count?)\n  await tools.web_fetch(url, maxChars?)\n  await tools.read_file(path, limit?)\n  await tools.write_file(path, content)\n  await tools.grep(pattern, { path?, glob?, ignoreCase?, literal?, context?, limit? })\n  await tools.find(pattern, { path?, limit? })\n  await tools.shell(command)\n\nUse console.log() for output; combined stdout/stderr is returned." }),
+	code: Type.String({ description: "JavaScript to run. Exposed as `tools` (async functions) and `console`:\n  await tools.web_search(query, count?)\n  await tools.web_fetch(url, maxChars?)\n  await tools.read_file(path, limit?)\n  await tools.write_file(path, content)\n  await tools.grep(pattern, { path?, glob?, ignoreCase?, literal?, context?, limit? })\n  await tools.find(pattern, { path?, limit? })\n  await tools.exec_command(cmd, cwd?)\n\nUse console.log() for output; combined stdout/stderr is returned." }),
 	timeout: Type.Optional(Type.Number({
 		description: "Execution timeout in seconds (default: 3600 = 60m, max: 14400 = 4h)",
 		default: DEFAULT_TIMEOUT_SEC
@@ -23,7 +23,7 @@ const SANDBOX_ALLOWED_TOOLS = new Set([
 	"write_file",
 	"grep",
 	"find",
-	"shell",
+	"exec_command",
 	"skills_list",
 	"skill_view"
 ]);
@@ -99,7 +99,10 @@ function createToolsApi(getMap, signal) {
 				...typeof o.limit === "number" && Number.isFinite(o.limit) ? { limit: o.limit } : {}
 			});
 		},
-		shell: async (command) => run("shell", { command: String(command ?? "") })
+		exec_command: async (cmd, cwd) => run("exec_command", {
+			cmd: String(cmd ?? ""),
+			...typeof cwd === "string" && cwd.trim() ? { cwd } : {}
+		})
 	};
 }
 async function runSandboxedScript(code, sandbox, timeoutMs, signal) {
@@ -128,7 +131,7 @@ function createExecuteCodeTool(deps) {
 	return {
 		name: "execute_code",
 		label: "⚡ Execute Code",
-		description: "Run sandboxed JavaScript that calls a subset of tools via `tools.*` (batch work in one step).\n\nOnly stdout/stderr from `console` plus tool return text (as strings) are visible — not full tool JSON.\n\nWHEN TO USE: loops over files/URLs, simple branching between tool calls.\nWHEN NOT TO USE: single tool calls; tasks needing full tool schemas or disallowed tools.\n\nAPI: `await tools.web_search(q, count?)`, `web_fetch(url, maxChars?)`, `read_file(path, limit?)`, `write_file(path, content)`, `grep(pattern, opts?)`, `find(glob, opts?)`, `shell(command)`. Use `console.log` for output.",
+		description: "Run sandboxed JavaScript that calls a subset of tools via `tools.*` (batch work in one step).\n\nOnly stdout/stderr from `console` plus tool return text (as strings) are visible — not full tool JSON.\n\nWHEN TO USE: loops over files/URLs, simple branching between tool calls.\nWHEN NOT TO USE: single tool calls; tasks needing full tool schemas or disallowed tools.\n\nAPI: `await tools.web_search(q, count?)`, `web_fetch(url, maxChars?)`, `read_file(path, limit?)`, `write_file(path, content)`, `grep(pattern, opts?)`, `find(glob, opts?)`, `exec_command(cmd, cwd?)`. Use `console.log` for output.",
 		parameters: ExecuteCodeSchema,
 		async execute(_toolCallId, params, signal) {
 			const p = params;

package/dist/src/agent/tools/execute-code-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute-code-tool.js","names":[],"sources":["../../../../src/agent/tools/execute-code-tool.ts"],"sourcesContent":["/**\n * Programmatic tool calling (PTC): run sandboxed JS that invokes a subset of agent tools.\n * vm is not a strong security boundary; only trusted models should use this tool.\n */\n\nimport { Script, createContext } from 'node:vm';\n\nimport { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\n\n/** Default script wall time when `timeout` omitted (30 minutes). */\nconst DEFAULT_TIMEOUT_SEC = 30 * 60;\n/** Hard cap for `timeout` parameter (4 hours). */\nconst MAX_TIMEOUT_SEC = 4 * 60 * 60;\n\nconst ExecuteCodeSchema = Type.Object({\n  code: Type.String({\n    description:\n      'JavaScript to run. Exposed as `tools` (async functions) and `console`:\\n' +\n      '  await tools.web_search(query, count?)\\n' +\n      '  await tools.web_fetch(url, maxChars?)\\n' +\n      '  await tools.read_file(path, limit?)\\n' +\n      '  await tools.write_file(path, content)\\n' +\n      '  await tools.grep(pattern, { path?, glob?, ignoreCase?, literal?, context?, limit? })\\n' +\n      '  await tools.find(pattern, { path?, limit? })\\n' +\n      '  await tools.shell(command)\\n\\n' +\n      'Use console.log() for output; combined stdout/stderr is returned.',\n  }),\n  timeout: Type.Optional(\n    Type.Number({\n      description: 'Execution timeout in seconds (default: 3600 = 60m, max: 14400 = 4h)',\n      default: DEFAULT_TIMEOUT_SEC,\n    }),\n  ),\n});\n\nexport const SANDBOX_ALLOWED_TOOLS = new Set([\n  'web_search',\n  'web_fetch',\n  'read_file',\n  'write_file',\n  'grep',\n  'find',\n  'shell',\n  'skills_list',\n  'skill_view',\n]);\n\nconst MAX_TIMEOUT_MS = MAX_TIMEOUT_SEC * 1000;\nconst MAX_TOOL_CALLS = 50;\nconst MAX_STDOUT_CHARS = 50_000;\nconst MAX_STDERR_CHARS = 10_000;\n\nfunction stringifyArg(a: unknown): string {\n  if (typeof a === 'string') {\n    return a;\n  }\n  try {\n    return JSON.stringify(a);\n  } catch {\n    return String(a);\n  }\n}\n\nfunction extractTextFromResult(result: AgentToolResult<unknown>): string {\n  return result.content\n    .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n    .map((c) => c.text)\n    .join('');\n}\n\nexport function buildSandboxToolMap(tools: AgentTool<any, any>[]): Map<string, AgentTool<any, any>> {\n  const m = new Map<string, AgentTool<any, any>>();\n  for (const t of tools) {\n    if (SANDBOX_ALLOWED_TOOLS.has(t.name)) {\n      m.set(t.name, t);\n    }\n  }\n  return m;\n}\n\nfunction createToolsApi(\n  getMap: () => Map<string, AgentTool<any, any>>,\n  signal: AbortSignal | undefined,\n): Record<string, (...args: unknown[]) => Promise<string>> {\n  let seq = 0;\n  let calls = 0;\n\n  const bump = (): void => {\n    calls += 1;\n    if (calls > MAX_TOOL_CALLS) {\n      throw new Error(`Exceeded max sandbox tool calls (${MAX_TOOL_CALLS})`);\n    }\n  };\n\n  const run = async (name: string, params: Record<string, unknown>): Promise<string> => {\n    if (signal?.aborted) {\n      throw new Error('aborted');\n    }\n    bump();\n    const tool = getMap().get(name);\n    if (!tool) {\n      throw new Error(`Tool not available in sandbox: ${name}`);\n    }\n    const id = `ptc-${Date.now()}-${seq++}`;\n    const result = await (tool as any).execute(id, params, signal);\n    return extractTextFromResult(result);\n  };\n\n  return {\n    web_search: async (query: unknown, count?: unknown) =>\n      run('web_search', {\n        query: String(query ?? ''),\n        ...(typeof count === 'number' && Number.isFinite(count) ? { count } : {}),\n      }),\n\n    web_fetch: async (url: unknown, maxChars?: unknown) =>\n      run('web_fetch', {\n        url: String(url ?? ''),\n        ...(typeof maxChars === 'number' && Number.isFinite(maxChars) ? { maxChars } : {}),\n      }),\n\n    read_file: async (path: unknown, limit?: unknown) =>\n      run('read_file', {\n        path: String(path ?? ''),\n        ...(typeof limit === 'number' && Number.isFinite(limit) ? { limit } : {}),\n      }),\n\n    write_file: async (path: unknown, content: unknown) =>\n      run('write_file', {\n        path: String(path ?? ''),\n        content: String(content ?? ''),\n      }),\n\n    grep: async (pattern: unknown, opts?: unknown) => {\n      const o = opts && typeof opts === 'object' && opts !== null ? (opts as Record<string, unknown>) : {};\n      return run('grep', {\n        pattern: String(pattern ?? ''),\n        ...(typeof o.path === 'string' ? { path: o.path } : {}),\n        ...(typeof o.glob === 'string' ? { glob: o.glob } : {}),\n        ...(typeof o.ignoreCase === 'boolean' ? { ignoreCase: o.ignoreCase } : {}),\n        ...(typeof o.literal === 'boolean' ? { literal: o.literal } : {}),\n        ...(typeof o.context === 'number' && Number.isFinite(o.context) ? { context: o.context } : {}),\n        ...(typeof o.limit === 'number' && Number.isFinite(o.limit) ? { limit: o.limit } : {}),\n      });\n    },\n\n    find: async (pattern: unknown, opts?: unknown) => {\n      const o = opts && typeof opts === 'object' && opts !== null ? (opts as Record<string, unknown>) : {};\n      return run('find', {\n        pattern: String(pattern ?? ''),\n        ...(typeof o.path === 'string' ? { path: o.path } : {}),\n        ...(typeof o.limit === 'number' && Number.isFinite(o.limit) ? { limit: o.limit } : {}),\n      });\n    },\n\n    shell: async (command: unknown) => run('shell', { command: String(command ?? '') }),\n  };\n}\n\nasync function runSandboxedScript(\n  code: string,\n  sandbox: Record<string, unknown>,\n  timeoutMs: number,\n  signal?: AbortSignal,\n): Promise<void> {\n  const context = createContext(sandbox, { name: 'execute_code' });\n  const wrapped = `(async () => {\\n${code}\\n})()`;\n  const script = new Script(wrapped, { filename: 'execute_code.vm' });\n  const runPromise = script.runInContext(context) as Promise<unknown>;\n\n  let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n  const timeoutPromise = new Promise<never>((_, rej) => {\n    timeoutId = setTimeout(\n      () => rej(new Error(`Script timed out after ${Math.round(timeoutMs / 1000)}s`)),\n      timeoutMs,\n    );\n  });\n\n  const abortPromise =\n    signal &&\n    new Promise<never>((_, rej) => {\n      if (signal.aborted) {\n        rej(new Error('aborted'));\n        return;\n      }\n      signal.addEventListener('abort', () => rej(new Error('aborted')), { once: true });\n    });\n\n  const racers: Promise<unknown>[] = [runPromise, timeoutPromise];\n  if (abortPromise) {\n    racers.push(abortPromise);\n  }\n\n  try {\n    await Promise.race(racers);\n  } finally {\n    if (timeoutId !== undefined) {\n      clearTimeout(timeoutId);\n    }\n  }\n}\n\nexport interface ExecuteCodeToolDeps {\n  getSandboxToolMap: () => Map<string, AgentTool<any, any>>;\n}\n\ntype ExecuteCodeParams = { code: string; timeout?: number };\n\nexport function createExecuteCodeTool(deps: ExecuteCodeToolDeps): AgentTool {\n  return {\n    name: 'execute_code',\n    label: '⚡ Execute Code',\n    description:\n      'Run sandboxed JavaScript that calls a subset of tools via `tools.*` (batch work in one step).\\n\\n' +\n      'Only stdout/stderr from `console` plus tool return text (as strings) are visible — not full tool JSON.\\n\\n' +\n      'WHEN TO USE: loops over files/URLs, simple branching between tool calls.\\n' +\n      'WHEN NOT TO USE: single tool calls; tasks needing full tool schemas or disallowed tools.\\n\\n' +\n      'API: `await tools.web_search(q, count?)`, `web_fetch(url, maxChars?)`, `read_file(path, limit?)`, ' +\n      '`write_file(path, content)`, `grep(pattern, opts?)`, `find(glob, opts?)`, `shell(command)`. ' +\n      'Use `console.log` for output.',\n    parameters: ExecuteCodeSchema,\n\n    async execute(\n      _toolCallId: string,\n      params: any,\n      signal?: AbortSignal,\n    ): Promise<AgentToolResult<{ exitCode: number }>> {\n      const p = params as ExecuteCodeParams;\n      const sec = p.timeout ?? DEFAULT_TIMEOUT_SEC;\n      const timeoutMs = Math.min(\n        Math.max(1, Number.isFinite(sec) ? sec : DEFAULT_TIMEOUT_SEC) * 1000,\n        MAX_TIMEOUT_MS,\n      );\n\n      const stdout: string[] = [];\n      const stderr: string[] = [];\n\n      const toolsApi = createToolsApi(deps.getSandboxToolMap, signal);\n\n      const sandbox: Record<string, unknown> = {\n        tools: toolsApi,\n        Promise,\n        JSON,\n        Math,\n        Date,\n        Array,\n        Object,\n        String,\n        Number,\n        Boolean,\n        RegExp,\n        Map,\n        Set,\n        Error,\n        TypeError,\n        RangeError,\n        parseInt,\n        parseFloat,\n        isNaN,\n        isFinite,\n        console: {\n          log: (...args: unknown[]) => {\n            stdout.push(args.map(stringifyArg).join(' '));\n          },\n          error: (...args: unknown[]) => {\n            stderr.push(args.map(stringifyArg).join(' '));\n          },\n          warn: (...args: unknown[]) => {\n            stderr.push(args.map(stringifyArg).join(' '));\n          },\n        },\n        setTimeout,\n        clearTimeout,\n      };\n\n      try {\n        await runSandboxedScript(p.code, sandbox, timeoutMs, signal);\n\n        let out = stdout.join('\\n');\n        if (out.length > MAX_STDOUT_CHARS) {\n          out = `${out.slice(0, MAX_STDOUT_CHARS)}\\n...(truncated)`;\n        }\n\n        const parts: string[] = [];\n        if (out.length > 0) {\n          parts.push(out);\n        }\n        if (stderr.length > 0) {\n          let err = stderr.join('\\n');\n          if (err.length > MAX_STDERR_CHARS) {\n            err = `${err.slice(0, MAX_STDERR_CHARS)}\\n...(truncated)`;\n          }\n          parts.push(`\\nSTDERR:\\n${err}`);\n        }\n\n        return {\n          content: [{ type: 'text', text: parts.join('') || '(no output)' }],\n          details: { exitCode: 0 },\n        };\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error);\n        return {\n          content: [{ type: 'text', text: `Execution failed: ${message}` }],\n          details: { exitCode: 1 },\n        };\n      }\n    },\n  } as any;\n}\n"],"mappings":"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"}
+{"version":3,"file":"execute-code-tool.js","names":[],"sources":["../../../../src/agent/tools/execute-code-tool.ts"],"sourcesContent":["/**\n * Programmatic tool calling (PTC): run sandboxed JS that invokes a subset of agent tools.\n * vm is not a strong security boundary; only trusted models should use this tool.\n */\n\nimport { Script, createContext } from 'node:vm';\n\nimport { Type } from '@sinclair/typebox';\nimport type { AgentTool, AgentToolResult } from '@earendil-works/pi-agent-core';\n\n/** Default script wall time when `timeout` omitted (30 minutes). */\nconst DEFAULT_TIMEOUT_SEC = 30 * 60;\n/** Hard cap for `timeout` parameter (4 hours). */\nconst MAX_TIMEOUT_SEC = 4 * 60 * 60;\n\nconst ExecuteCodeSchema = Type.Object({\n  code: Type.String({\n    description:\n      'JavaScript to run. Exposed as `tools` (async functions) and `console`:\\n' +\n      '  await tools.web_search(query, count?)\\n' +\n      '  await tools.web_fetch(url, maxChars?)\\n' +\n      '  await tools.read_file(path, limit?)\\n' +\n      '  await tools.write_file(path, content)\\n' +\n      '  await tools.grep(pattern, { path?, glob?, ignoreCase?, literal?, context?, limit? })\\n' +\n      '  await tools.find(pattern, { path?, limit? })\\n' +\n      '  await tools.exec_command(cmd, cwd?)\\n\\n' +\n      'Use console.log() for output; combined stdout/stderr is returned.',\n  }),\n  timeout: Type.Optional(\n    Type.Number({\n      description: 'Execution timeout in seconds (default: 3600 = 60m, max: 14400 = 4h)',\n      default: DEFAULT_TIMEOUT_SEC,\n    }),\n  ),\n});\n\nexport const SANDBOX_ALLOWED_TOOLS = new Set([\n  'web_search',\n  'web_fetch',\n  'read_file',\n  'write_file',\n  'grep',\n  'find',\n  'exec_command',\n  'skills_list',\n  'skill_view',\n]);\n\nconst MAX_TIMEOUT_MS = MAX_TIMEOUT_SEC * 1000;\nconst MAX_TOOL_CALLS = 50;\nconst MAX_STDOUT_CHARS = 50_000;\nconst MAX_STDERR_CHARS = 10_000;\n\nfunction stringifyArg(a: unknown): string {\n  if (typeof a === 'string') {\n    return a;\n  }\n  try {\n    return JSON.stringify(a);\n  } catch {\n    return String(a);\n  }\n}\n\nfunction extractTextFromResult(result: AgentToolResult<unknown>): string {\n  return result.content\n    .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n    .map((c) => c.text)\n    .join('');\n}\n\nexport function buildSandboxToolMap(tools: AgentTool<any, any>[]): Map<string, AgentTool<any, any>> {\n  const m = new Map<string, AgentTool<any, any>>();\n  for (const t of tools) {\n    if (SANDBOX_ALLOWED_TOOLS.has(t.name)) {\n      m.set(t.name, t);\n    }\n  }\n  return m;\n}\n\nfunction createToolsApi(\n  getMap: () => Map<string, AgentTool<any, any>>,\n  signal: AbortSignal | undefined,\n): Record<string, (...args: unknown[]) => Promise<string>> {\n  let seq = 0;\n  let calls = 0;\n\n  const bump = (): void => {\n    calls += 1;\n    if (calls > MAX_TOOL_CALLS) {\n      throw new Error(`Exceeded max sandbox tool calls (${MAX_TOOL_CALLS})`);\n    }\n  };\n\n  const run = async (name: string, params: Record<string, unknown>): Promise<string> => {\n    if (signal?.aborted) {\n      throw new Error('aborted');\n    }\n    bump();\n    const tool = getMap().get(name);\n    if (!tool) {\n      throw new Error(`Tool not available in sandbox: ${name}`);\n    }\n    const id = `ptc-${Date.now()}-${seq++}`;\n    const result = await (tool as any).execute(id, params, signal);\n    return extractTextFromResult(result);\n  };\n\n  return {\n    web_search: async (query: unknown, count?: unknown) =>\n      run('web_search', {\n        query: String(query ?? ''),\n        ...(typeof count === 'number' && Number.isFinite(count) ? { count } : {}),\n      }),\n\n    web_fetch: async (url: unknown, maxChars?: unknown) =>\n      run('web_fetch', {\n        url: String(url ?? ''),\n        ...(typeof maxChars === 'number' && Number.isFinite(maxChars) ? { maxChars } : {}),\n      }),\n\n    read_file: async (path: unknown, limit?: unknown) =>\n      run('read_file', {\n        path: String(path ?? ''),\n        ...(typeof limit === 'number' && Number.isFinite(limit) ? { limit } : {}),\n      }),\n\n    write_file: async (path: unknown, content: unknown) =>\n      run('write_file', {\n        path: String(path ?? ''),\n        content: String(content ?? ''),\n      }),\n\n    grep: async (pattern: unknown, opts?: unknown) => {\n      const o = opts && typeof opts === 'object' && opts !== null ? (opts as Record<string, unknown>) : {};\n      return run('grep', {\n        pattern: String(pattern ?? ''),\n        ...(typeof o.path === 'string' ? { path: o.path } : {}),\n        ...(typeof o.glob === 'string' ? { glob: o.glob } : {}),\n        ...(typeof o.ignoreCase === 'boolean' ? { ignoreCase: o.ignoreCase } : {}),\n        ...(typeof o.literal === 'boolean' ? { literal: o.literal } : {}),\n        ...(typeof o.context === 'number' && Number.isFinite(o.context) ? { context: o.context } : {}),\n        ...(typeof o.limit === 'number' && Number.isFinite(o.limit) ? { limit: o.limit } : {}),\n      });\n    },\n\n    find: async (pattern: unknown, opts?: unknown) => {\n      const o = opts && typeof opts === 'object' && opts !== null ? (opts as Record<string, unknown>) : {};\n      return run('find', {\n        pattern: String(pattern ?? ''),\n        ...(typeof o.path === 'string' ? { path: o.path } : {}),\n        ...(typeof o.limit === 'number' && Number.isFinite(o.limit) ? { limit: o.limit } : {}),\n      });\n    },\n\n    exec_command: async (cmd: unknown, cwd?: unknown) =>\n      run('exec_command', {\n        cmd: String(cmd ?? ''),\n        ...(typeof cwd === 'string' && cwd.trim() ? { cwd } : {}),\n      }),\n  };\n}\n\nasync function runSandboxedScript(\n  code: string,\n  sandbox: Record<string, unknown>,\n  timeoutMs: number,\n  signal?: AbortSignal,\n): Promise<void> {\n  const context = createContext(sandbox, { name: 'execute_code' });\n  const wrapped = `(async () => {\\n${code}\\n})()`;\n  const script = new Script(wrapped, { filename: 'execute_code.vm' });\n  const runPromise = script.runInContext(context) as Promise<unknown>;\n\n  let timeoutId: ReturnType<typeof setTimeout> | undefined;\n\n  const timeoutPromise = new Promise<never>((_, rej) => {\n    timeoutId = setTimeout(\n      () => rej(new Error(`Script timed out after ${Math.round(timeoutMs / 1000)}s`)),\n      timeoutMs,\n    );\n  });\n\n  const abortPromise =\n    signal &&\n    new Promise<never>((_, rej) => {\n      if (signal.aborted) {\n        rej(new Error('aborted'));\n        return;\n      }\n      signal.addEventListener('abort', () => rej(new Error('aborted')), { once: true });\n    });\n\n  const racers: Promise<unknown>[] = [runPromise, timeoutPromise];\n  if (abortPromise) {\n    racers.push(abortPromise);\n  }\n\n  try {\n    await Promise.race(racers);\n  } finally {\n    if (timeoutId !== undefined) {\n      clearTimeout(timeoutId);\n    }\n  }\n}\n\nexport interface ExecuteCodeToolDeps {\n  getSandboxToolMap: () => Map<string, AgentTool<any, any>>;\n}\n\ntype ExecuteCodeParams = { code: string; timeout?: number };\n\nexport function createExecuteCodeTool(deps: ExecuteCodeToolDeps): AgentTool {\n  return {\n    name: 'execute_code',\n    label: '⚡ Execute Code',\n    description:\n      'Run sandboxed JavaScript that calls a subset of tools via `tools.*` (batch work in one step).\\n\\n' +\n      'Only stdout/stderr from `console` plus tool return text (as strings) are visible — not full tool JSON.\\n\\n' +\n      'WHEN TO USE: loops over files/URLs, simple branching between tool calls.\\n' +\n      'WHEN NOT TO USE: single tool calls; tasks needing full tool schemas or disallowed tools.\\n\\n' +\n      'API: `await tools.web_search(q, count?)`, `web_fetch(url, maxChars?)`, `read_file(path, limit?)`, ' +\n      '`write_file(path, content)`, `grep(pattern, opts?)`, `find(glob, opts?)`, `exec_command(cmd, cwd?)`. ' +\n      'Use `console.log` for output.',\n    parameters: ExecuteCodeSchema,\n\n    async execute(\n      _toolCallId: string,\n      params: any,\n      signal?: AbortSignal,\n    ): Promise<AgentToolResult<{ exitCode: number }>> {\n      const p = params as ExecuteCodeParams;\n      const sec = p.timeout ?? DEFAULT_TIMEOUT_SEC;\n      const timeoutMs = Math.min(\n        Math.max(1, Number.isFinite(sec) ? sec : DEFAULT_TIMEOUT_SEC) * 1000,\n        MAX_TIMEOUT_MS,\n      );\n\n      const stdout: string[] = [];\n      const stderr: string[] = [];\n\n      const toolsApi = createToolsApi(deps.getSandboxToolMap, signal);\n\n      const sandbox: Record<string, unknown> = {\n        tools: toolsApi,\n        Promise,\n        JSON,\n        Math,\n        Date,\n        Array,\n        Object,\n        String,\n        Number,\n        Boolean,\n        RegExp,\n        Map,\n        Set,\n        Error,\n        TypeError,\n        RangeError,\n        parseInt,\n        parseFloat,\n        isNaN,\n        isFinite,\n        console: {\n          log: (...args: unknown[]) => {\n            stdout.push(args.map(stringifyArg).join(' '));\n          },\n          error: (...args: unknown[]) => {\n            stderr.push(args.map(stringifyArg).join(' '));\n          },\n          warn: (...args: unknown[]) => {\n            stderr.push(args.map(stringifyArg).join(' '));\n          },\n        },\n        setTimeout,\n        clearTimeout,\n      };\n\n      try {\n        await runSandboxedScript(p.code, sandbox, timeoutMs, signal);\n\n        let out = stdout.join('\\n');\n        if (out.length > MAX_STDOUT_CHARS) {\n          out = `${out.slice(0, MAX_STDOUT_CHARS)}\\n...(truncated)`;\n        }\n\n        const parts: string[] = [];\n        if (out.length > 0) {\n          parts.push(out);\n        }\n        if (stderr.length > 0) {\n          let err = stderr.join('\\n');\n          if (err.length > MAX_STDERR_CHARS) {\n            err = `${err.slice(0, MAX_STDERR_CHARS)}\\n...(truncated)`;\n          }\n          parts.push(`\\nSTDERR:\\n${err}`);\n        }\n\n        return {\n          content: [{ type: 'text', text: parts.join('') || '(no output)' }],\n          details: { exitCode: 0 },\n        };\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error);\n        return {\n          content: [{ type: 'text', text: `Execution failed: ${message}` }],\n          details: { exitCode: 1 },\n        };\n      }\n    },\n  } as any;\n}\n"],"mappings":"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"}

package/dist/src/agent/tools/executor.d.ts

@@ -12,6 +12,9 @@
  * instead of synthesising fake-success results.
  */
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from '@earendil-works/pi-agent-core';
+import type { XopcToolMetadata } from './metadata.js';
+import { ToolConcurrencyController } from './concurrency.js';
+import type { ToolConcurrencyController as ToolConcurrencyControllerType } from './concurrency.js';
 export interface ToolExecutorConfig {
     /** Default per-tool timeout when the tool does not declare its own `timeoutMs`. */
     defaultTimeoutMs: number;
@@ -32,9 +35,8 @@ declare const DEFAULT_CONFIG: ToolExecutorConfig;
  * - `idempotent`: marks a tool as safe to retry. The wrapper retries only
  *   tools that opt in — write/edit-like tools must leave this `false`.
  */
-export interface XopcToolHints {
+export interface XopcToolHints extends XopcToolMetadata {
     timeoutMs?: number;
-    idempotent?: boolean;
 }
 /**
  * Execute tool with timeout (always) and retry (only for idempotent tools).
@@ -45,9 +47,9 @@ export declare function executeToolWithProtection<TDetails>(tool: AgentTool<any,
  * Wrap a single tool with the protection pipeline. Preserves the original
  * `execute` signature so streaming `signal` / `onUpdate` reach the tool.
  */
-export declare function wrapToolWithProtection<TDetails>(tool: AgentTool<any, TDetails>, config?: Partial<ToolExecutorConfig>): AgentTool<any, TDetails>;
+export declare function wrapToolWithProtection<TDetails>(tool: AgentTool<any, TDetails>, config?: Partial<ToolExecutorConfig>, concurrency?: ToolConcurrencyControllerType): AgentTool<any, TDetails>;
 /**
  * Wrap a batch of tools with protection.
  */
-export declare function wrapToolsWithProtection(tools: AgentTool<any, any>[], config?: Partial<ToolExecutorConfig>): AgentTool<any, any>[];
+export declare function wrapToolsWithProtection(tools: AgentTool<any, any>[], config?: Partial<ToolExecutorConfig>, concurrency?: ToolConcurrencyController): AgentTool<any, any>[];
 export { DEFAULT_CONFIG as DEFAULT_TOOL_EXECUTOR_CONFIG };

package/dist/src/agent/tools/executor.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { ToolConcurrencyController, resolveToolLockMode } from "./concurrency.js";
 import { TimeoutError, executeWithTimeout } from "../lifecycle/timeout-wrapper.js";
 import { withRetry } from "../../infra/retry.js";
 //#region src/agent/tools/executor.ts
@@ -91,19 +92,21 @@ async function executeToolWithProtection(tool, toolCallId, params, signal, onUpd
 * Wrap a single tool with the protection pipeline. Preserves the original
 * `execute` signature so streaming `signal` / `onUpdate` reach the tool.
 */
-function wrapToolWithProtection(tool, config) {
+function wrapToolWithProtection(tool, config, concurrency) {
+	const lockMode = resolveToolLockMode(tool);
 	return {
 		...tool,
 		async execute(toolCallId, params, signal, onUpdate) {
-			return executeToolWithProtection(tool, toolCallId, params, signal, onUpdate, config);
+			const run = () => executeToolWithProtection(tool, toolCallId, params, signal, onUpdate, config);
+			return concurrency ? concurrency.run(lockMode, run) : run();
 		}
 	};
 }
 /**
 * Wrap a batch of tools with protection.
 */
-function wrapToolsWithProtection(tools, config) {
-	return tools.map((tool) => wrapToolWithProtection(tool, config));
+function wrapToolsWithProtection(tools, config, concurrency = new ToolConcurrencyController()) {
+	return tools.map((tool) => wrapToolWithProtection(tool, config, concurrency));
 }
 //#endregion
 export { DEFAULT_CONFIG as DEFAULT_TOOL_EXECUTOR_CONFIG, executeToolWithProtection, wrapToolWithProtection, wrapToolsWithProtection };

package/dist/src/agent/tools/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","names":[],"sources":["../../../../src/agent/tools/executor.ts"],"sourcesContent":["/**\n * Tool Executor - Unified tool execution wrapper.\n *\n * Adds:\n * - Timeout protection (tools that hang would otherwise stall the turn).\n * - Optional retry for tools explicitly marked `idempotent`.\n *\n * Pi-agent contract (from `AgentTool.execute` docstring): \"Throw on failure\n * instead of encoding errors in `content`.\" Pi-agent turns thrown errors into\n * `tool_execution_end` events with `isError=true`, which feeds the loop guard,\n * error tracker, and error-pattern matcher. This wrapper therefore re-throws\n * instead of synthesising fake-success results.\n */\n\nimport type {\n  AgentTool,\n  AgentToolResult,\n  AgentToolUpdateCallback,\n} from '@earendil-works/pi-agent-core';\nimport { createLogger } from '../../utils/logger.js';\nimport { executeWithTimeout, TimeoutError } from '../lifecycle/timeout-wrapper.js';\nimport { withRetry } from '../../infra/retry.js';\n\nconst log = createLogger('ToolExecutor');\n\nexport interface ToolExecutorConfig {\n  /** Default per-tool timeout when the tool does not declare its own `timeoutMs`. */\n  defaultTimeoutMs: number;\n\n  /** Max retry attempts for tools opted into retry via `idempotent: true`. */\n  maxRetries: number;\n  /** Initial backoff between retries (passed straight to `withRetry`). */\n  retryDelayMs: number;\n\n  /** Master switches; default both on so the wrapper is still effective. */\n  enableTimeout: boolean;\n  enableRetry: boolean;\n}\n\nconst DEFAULT_CONFIG: ToolExecutorConfig = {\n  defaultTimeoutMs: 5 * 60 * 1000, // 5 minutes\n  maxRetries: 2,\n  retryDelayMs: 1000,\n  enableTimeout: true,\n  enableRetry: true,\n};\n\n/**\n * Optional xopc-side hints that any tool may attach. They are not part of the\n * pi-agent `AgentTool` contract; the wrapper reads them via structural typing.\n *\n * - `timeoutMs`: per-tool override of the default execution timeout.\n * - `idempotent`: marks a tool as safe to retry. The wrapper retries only\n *   tools that opt in — write/edit-like tools must leave this `false`.\n */\nexport interface XopcToolHints {\n  timeoutMs?: number;\n  idempotent?: boolean;\n}\n\nfunction readToolHints(tool: AgentTool<any, any>): XopcToolHints {\n  const t = tool as AgentTool<any, any> & XopcToolHints;\n  return {\n    timeoutMs: typeof t.timeoutMs === 'number' && t.timeoutMs > 0 ? t.timeoutMs : undefined,\n    idempotent: t.idempotent === true,\n  };\n}\n\nfunction resolveTimeoutMs(tool: AgentTool<any, any>, config: ToolExecutorConfig): number {\n  const hints = readToolHints(tool);\n  return hints.timeoutMs ?? config.defaultTimeoutMs;\n}\n\n/**\n * Execute tool with timeout (always) and retry (only for idempotent tools).\n * Re-throws on failure so pi-agent records `isError=true`.\n */\nexport async function executeToolWithProtection<TDetails>(\n  tool: AgentTool<any, TDetails>,\n  toolCallId: string,\n  params: any,\n  signal?: AbortSignal,\n  onUpdate?: AgentToolUpdateCallback<TDetails>,\n  config: Partial<ToolExecutorConfig> = {},\n): Promise<AgentToolResult<TDetails>> {\n  const fullConfig = { ...DEFAULT_CONFIG, ...config };\n  const toolName = tool.name;\n  const hints = readToolHints(tool);\n\n  const runOnce = (): Promise<AgentToolResult<TDetails>> =>\n    tool.execute(toolCallId, params, signal, onUpdate);\n\n  let operation: () => Promise<AgentToolResult<TDetails>> = runOnce;\n\n  if (fullConfig.enableTimeout) {\n    const timeoutMs = resolveTimeoutMs(tool, fullConfig);\n    const inner = operation;\n    operation = () =>\n      executeWithTimeout(inner, {\n        toolName,\n        timeoutMs,\n        description: `Executing ${toolName}`,\n      });\n  }\n\n  const shouldRetry = fullConfig.enableRetry && fullConfig.maxRetries > 0 && hints.idempotent;\n  if (shouldRetry) {\n    const inner = operation;\n    operation = () =>\n      withRetry(inner, {\n        attempts: fullConfig.maxRetries + 1,\n        minDelayMs: fullConfig.retryDelayMs,\n        onRetry: (info) => {\n          log.warn(\n            { tool: toolName, attempt: info.attempt, delayMs: info.delayMs, error: info.error },\n            'Tool execution failed, retrying (idempotent)',\n          );\n        },\n      });\n  }\n\n  const startTime = Date.now();\n  try {\n    const result = await operation();\n    log.debug(\n      { tool: toolName, durationMs: Date.now() - startTime, success: true },\n      'Tool execution completed',\n    );\n    return result;\n  } catch (error) {\n    const durationMs = Date.now() - startTime;\n\n    if (error instanceof TimeoutError) {\n      log.error(\n        { tool: toolName, timeoutMs: error.timeoutMs, durationMs },\n        'Tool execution timed out',\n      );\n      throw new Error(`Tool '${toolName}' timed out after ${error.timeoutMs}ms`, { cause: error });\n    }\n\n    const errorMessage = error instanceof Error ? error.message : String(error);\n    log.error(\n      { tool: toolName, error: errorMessage, durationMs },\n      'Tool execution failed',\n    );\n    throw error instanceof Error ? error : new Error(errorMessage);\n  }\n}\n\n/**\n * Wrap a single tool with the protection pipeline. Preserves the original\n * `execute` signature so streaming `signal` / `onUpdate` reach the tool.\n */\nexport function wrapToolWithProtection<TDetails>(\n  tool: AgentTool<any, TDetails>,\n  config?: Partial<ToolExecutorConfig>,\n): AgentTool<any, TDetails> {\n  return {\n    ...tool,\n    async execute(\n      toolCallId: string,\n      params: any,\n      signal?: AbortSignal,\n      onUpdate?: AgentToolUpdateCallback<TDetails>,\n    ): Promise<AgentToolResult<TDetails>> {\n      return executeToolWithProtection(tool, toolCallId, params, signal, onUpdate, config);\n    },\n  } as AgentTool<any, TDetails>;\n}\n\n/**\n * Wrap a batch of tools with protection.\n */\nexport function wrapToolsWithProtection(\n  tools: AgentTool<any, any>[],\n  config?: Partial<ToolExecutorConfig>,\n): AgentTool<any, any>[] {\n  return tools.map((tool) => wrapToolWithProtection(tool, config));\n}\n\n// Export configuration\nexport { DEFAULT_CONFIG as DEFAULT_TOOL_EXECUTOR_CONFIG };\n"],"mappings":";;;;;aAmBqD;AAIrD,MAAM,MAAM,aAAa,eAAe;AAgBxC,MAAM,iBAAqC;CACzC,kBAAkB,MAAS;CAC3B,YAAY;CACZ,cAAc;CACd,eAAe;CACf,aAAa;CACd;AAeD,SAAS,cAAc,MAA0C;CAC/D,MAAM,IAAI;AACV,QAAO;EACL,WAAW,OAAO,EAAE,cAAc,YAAY,EAAE,YAAY,IAAI,EAAE,YAAY,KAAA;EAC9E,YAAY,EAAE,eAAe;EAC9B;;AAGH,SAAS,iBAAiB,MAA2B,QAAoC;AAEvF,QADc,cAAc,KAChB,CAAC,aAAa,OAAO;;;;;;AAOnC,eAAsB,0BACpB,MACA,YACA,QACA,QACA,UACA,SAAsC,EAAE,EACJ;CACpC,MAAM,aAAa;EAAE,GAAG;EAAgB,GAAG;EAAQ;CACnD,MAAM,WAAW,KAAK;CACtB,MAAM,QAAQ,cAAc,KAAK;CAEjC,MAAM,gBACJ,KAAK,QAAQ,YAAY,QAAQ,QAAQ,SAAS;CAEpD,IAAI,YAAsD;AAE1D,KAAI,WAAW,eAAe;EAC5B,MAAM,YAAY,iBAAiB,MAAM,WAAW;EACpD,MAAM,QAAQ;AACd,oBACE,mBAAmB,OAAO;GACxB;GACA;GACA,aAAa,aAAa;GAC3B,CAAC;;AAIN,KADoB,WAAW,eAAe,WAAW,aAAa,KAAK,MAAM,YAChE;EACf,MAAM,QAAQ;AACd,oBACE,UAAU,OAAO;GACf,UAAU,WAAW,aAAa;GAClC,YAAY,WAAW;GACvB,UAAU,SAAS;AACjB,QAAI,KACF;KAAE,MAAM;KAAU,SAAS,KAAK;KAAS,SAAS,KAAK;KAAS,OAAO,KAAK;KAAO,EACnF,+CACD;;GAEJ,CAAC;;CAGN,MAAM,YAAY,KAAK,KAAK;AAC5B,KAAI;EACF,MAAM,SAAS,MAAM,WAAW;AAChC,MAAI,MACF;GAAE,MAAM;GAAU,YAAY,KAAK,KAAK,GAAG;GAAW,SAAS;GAAM,EACrE,2BACD;AACD,SAAO;UACA,OAAO;EACd,MAAM,aAAa,KAAK,KAAK,GAAG;AAEhC,MAAI,iBAAiB,cAAc;AACjC,OAAI,MACF;IAAE,MAAM;IAAU,WAAW,MAAM;IAAW;IAAY,EAC1D,2BACD;AACD,SAAM,IAAI,MAAM,SAAS,SAAS,oBAAoB,MAAM,UAAU,KAAK,EAAE,OAAO,OAAO,CAAC;;EAG9F,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAC3E,MAAI,MACF;GAAE,MAAM;GAAU,OAAO;GAAc;GAAY,EACnD,wBACD;AACD,QAAM,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,aAAa;;;;;;;AAQlE,SAAgB,uBACd,MACA,QAC0B;AAC1B,QAAO;EACL,GAAG;EACH,MAAM,QACJ,YACA,QACA,QACA,UACoC;AACpC,UAAO,0BAA0B,MAAM,YAAY,QAAQ,QAAQ,UAAU,OAAO;;EAEvF;;;;;AAMH,SAAgB,wBACd,OACA,QACuB;AACvB,QAAO,MAAM,KAAK,SAAS,uBAAuB,MAAM,OAAO,CAAC"}
+{"version":3,"file":"executor.js","names":[],"sources":["../../../../src/agent/tools/executor.ts"],"sourcesContent":["/**\n * Tool Executor - Unified tool execution wrapper.\n *\n * Adds:\n * - Timeout protection (tools that hang would otherwise stall the turn).\n * - Optional retry for tools explicitly marked `idempotent`.\n *\n * Pi-agent contract (from `AgentTool.execute` docstring): \"Throw on failure\n * instead of encoding errors in `content`.\" Pi-agent turns thrown errors into\n * `tool_execution_end` events with `isError=true`, which feeds the loop guard,\n * error tracker, and error-pattern matcher. This wrapper therefore re-throws\n * instead of synthesising fake-success results.\n */\n\nimport type {\n  AgentTool,\n  AgentToolResult,\n  AgentToolUpdateCallback,\n} from '@earendil-works/pi-agent-core';\nimport { createLogger } from '../../utils/logger.js';\nimport { executeWithTimeout, TimeoutError } from '../lifecycle/timeout-wrapper.js';\nimport { withRetry } from '../../infra/retry.js';\nimport type { XopcToolMetadata } from './metadata.js';\nimport { ToolConcurrencyController, resolveToolLockMode } from './concurrency.js';\nimport type { ToolConcurrencyController as ToolConcurrencyControllerType } from './concurrency.js';\n\nconst log = createLogger('ToolExecutor');\n\nexport interface ToolExecutorConfig {\n  /** Default per-tool timeout when the tool does not declare its own `timeoutMs`. */\n  defaultTimeoutMs: number;\n\n  /** Max retry attempts for tools opted into retry via `idempotent: true`. */\n  maxRetries: number;\n  /** Initial backoff between retries (passed straight to `withRetry`). */\n  retryDelayMs: number;\n\n  /** Master switches; default both on so the wrapper is still effective. */\n  enableTimeout: boolean;\n  enableRetry: boolean;\n}\n\nconst DEFAULT_CONFIG: ToolExecutorConfig = {\n  defaultTimeoutMs: 5 * 60 * 1000, // 5 minutes\n  maxRetries: 2,\n  retryDelayMs: 1000,\n  enableTimeout: true,\n  enableRetry: true,\n};\n\n/**\n * Optional xopc-side hints that any tool may attach. They are not part of the\n * pi-agent `AgentTool` contract; the wrapper reads them via structural typing.\n *\n * - `timeoutMs`: per-tool override of the default execution timeout.\n * - `idempotent`: marks a tool as safe to retry. The wrapper retries only\n *   tools that opt in — write/edit-like tools must leave this `false`.\n */\nexport interface XopcToolHints extends XopcToolMetadata {\n  timeoutMs?: number;\n}\n\nfunction readToolHints(tool: AgentTool<any, any>): XopcToolHints {\n  const t = tool as AgentTool<any, any> & XopcToolHints;\n  return {\n    timeoutMs: typeof t.timeoutMs === 'number' && t.timeoutMs > 0 ? t.timeoutMs : undefined,\n    idempotent: t.idempotent === true,\n  };\n}\n\nfunction resolveTimeoutMs(tool: AgentTool<any, any>, config: ToolExecutorConfig): number {\n  const hints = readToolHints(tool);\n  return hints.timeoutMs ?? config.defaultTimeoutMs;\n}\n\n/**\n * Execute tool with timeout (always) and retry (only for idempotent tools).\n * Re-throws on failure so pi-agent records `isError=true`.\n */\nexport async function executeToolWithProtection<TDetails>(\n  tool: AgentTool<any, TDetails>,\n  toolCallId: string,\n  params: any,\n  signal?: AbortSignal,\n  onUpdate?: AgentToolUpdateCallback<TDetails>,\n  config: Partial<ToolExecutorConfig> = {},\n): Promise<AgentToolResult<TDetails>> {\n  const fullConfig = { ...DEFAULT_CONFIG, ...config };\n  const toolName = tool.name;\n  const hints = readToolHints(tool);\n\n  const runOnce = (): Promise<AgentToolResult<TDetails>> =>\n    tool.execute(toolCallId, params, signal, onUpdate);\n\n  let operation: () => Promise<AgentToolResult<TDetails>> = runOnce;\n\n  if (fullConfig.enableTimeout) {\n    const timeoutMs = resolveTimeoutMs(tool, fullConfig);\n    const inner = operation;\n    operation = () =>\n      executeWithTimeout(inner, {\n        toolName,\n        timeoutMs,\n        description: `Executing ${toolName}`,\n      });\n  }\n\n  const shouldRetry = fullConfig.enableRetry && fullConfig.maxRetries > 0 && hints.idempotent;\n  if (shouldRetry) {\n    const inner = operation;\n    operation = () =>\n      withRetry(inner, {\n        attempts: fullConfig.maxRetries + 1,\n        minDelayMs: fullConfig.retryDelayMs,\n        onRetry: (info) => {\n          log.warn(\n            { tool: toolName, attempt: info.attempt, delayMs: info.delayMs, error: info.error },\n            'Tool execution failed, retrying (idempotent)',\n          );\n        },\n      });\n  }\n\n  const startTime = Date.now();\n  try {\n    const result = await operation();\n    log.debug(\n      { tool: toolName, durationMs: Date.now() - startTime, success: true },\n      'Tool execution completed',\n    );\n    return result;\n  } catch (error) {\n    const durationMs = Date.now() - startTime;\n\n    if (error instanceof TimeoutError) {\n      log.error(\n        { tool: toolName, timeoutMs: error.timeoutMs, durationMs },\n        'Tool execution timed out',\n      );\n      throw new Error(`Tool '${toolName}' timed out after ${error.timeoutMs}ms`, { cause: error });\n    }\n\n    const errorMessage = error instanceof Error ? error.message : String(error);\n    log.error(\n      { tool: toolName, error: errorMessage, durationMs },\n      'Tool execution failed',\n    );\n    throw error instanceof Error ? error : new Error(errorMessage);\n  }\n}\n\n/**\n * Wrap a single tool with the protection pipeline. Preserves the original\n * `execute` signature so streaming `signal` / `onUpdate` reach the tool.\n */\nexport function wrapToolWithProtection<TDetails>(\n  tool: AgentTool<any, TDetails>,\n  config?: Partial<ToolExecutorConfig>,\n  concurrency?: ToolConcurrencyControllerType,\n): AgentTool<any, TDetails> {\n  const lockMode = resolveToolLockMode(tool);\n  return {\n    ...tool,\n    async execute(\n      toolCallId: string,\n      params: any,\n      signal?: AbortSignal,\n      onUpdate?: AgentToolUpdateCallback<TDetails>,\n    ): Promise<AgentToolResult<TDetails>> {\n      const run = () => executeToolWithProtection(tool, toolCallId, params, signal, onUpdate, config);\n      return concurrency ? concurrency.run(lockMode, run) : run();\n    },\n  } as AgentTool<any, TDetails>;\n}\n\n/**\n * Wrap a batch of tools with protection.\n */\nexport function wrapToolsWithProtection(\n  tools: AgentTool<any, any>[],\n  config?: Partial<ToolExecutorConfig>,\n  concurrency = new ToolConcurrencyController(),\n): AgentTool<any, any>[] {\n  return tools.map((tool) => wrapToolWithProtection(tool, config, concurrency));\n}\n\n// Export configuration\nexport { DEFAULT_CONFIG as DEFAULT_TOOL_EXECUTOR_CONFIG };\n"],"mappings":";;;;;;aAmBqD;AAOrD,MAAM,MAAM,aAAa,eAAe;AAgBxC,MAAM,iBAAqC;CACzC,kBAAkB,MAAS;CAC3B,YAAY;CACZ,cAAc;CACd,eAAe;CACf,aAAa;CACd;AAcD,SAAS,cAAc,MAA0C;CAC/D,MAAM,IAAI;AACV,QAAO;EACL,WAAW,OAAO,EAAE,cAAc,YAAY,EAAE,YAAY,IAAI,EAAE,YAAY,KAAA;EAC9E,YAAY,EAAE,eAAe;EAC9B;;AAGH,SAAS,iBAAiB,MAA2B,QAAoC;AAEvF,QADc,cAAc,KAChB,CAAC,aAAa,OAAO;;;;;;AAOnC,eAAsB,0BACpB,MACA,YACA,QACA,QACA,UACA,SAAsC,EAAE,EACJ;CACpC,MAAM,aAAa;EAAE,GAAG;EAAgB,GAAG;EAAQ;CACnD,MAAM,WAAW,KAAK;CACtB,MAAM,QAAQ,cAAc,KAAK;CAEjC,MAAM,gBACJ,KAAK,QAAQ,YAAY,QAAQ,QAAQ,SAAS;CAEpD,IAAI,YAAsD;AAE1D,KAAI,WAAW,eAAe;EAC5B,MAAM,YAAY,iBAAiB,MAAM,WAAW;EACpD,MAAM,QAAQ;AACd,oBACE,mBAAmB,OAAO;GACxB;GACA;GACA,aAAa,aAAa;GAC3B,CAAC;;AAIN,KADoB,WAAW,eAAe,WAAW,aAAa,KAAK,MAAM,YAChE;EACf,MAAM,QAAQ;AACd,oBACE,UAAU,OAAO;GACf,UAAU,WAAW,aAAa;GAClC,YAAY,WAAW;GACvB,UAAU,SAAS;AACjB,QAAI,KACF;KAAE,MAAM;KAAU,SAAS,KAAK;KAAS,SAAS,KAAK;KAAS,OAAO,KAAK;KAAO,EACnF,+CACD;;GAEJ,CAAC;;CAGN,MAAM,YAAY,KAAK,KAAK;AAC5B,KAAI;EACF,MAAM,SAAS,MAAM,WAAW;AAChC,MAAI,MACF;GAAE,MAAM;GAAU,YAAY,KAAK,KAAK,GAAG;GAAW,SAAS;GAAM,EACrE,2BACD;AACD,SAAO;UACA,OAAO;EACd,MAAM,aAAa,KAAK,KAAK,GAAG;AAEhC,MAAI,iBAAiB,cAAc;AACjC,OAAI,MACF;IAAE,MAAM;IAAU,WAAW,MAAM;IAAW;IAAY,EAC1D,2BACD;AACD,SAAM,IAAI,MAAM,SAAS,SAAS,oBAAoB,MAAM,UAAU,KAAK,EAAE,OAAO,OAAO,CAAC;;EAG9F,MAAM,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AAC3E,MAAI,MACF;GAAE,MAAM;GAAU,OAAO;GAAc;GAAY,EACnD,wBACD;AACD,QAAM,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,aAAa;;;;;;;AAQlE,SAAgB,uBACd,MACA,QACA,aAC0B;CAC1B,MAAM,WAAW,oBAAoB,KAAK;AAC1C,QAAO;EACL,GAAG;EACH,MAAM,QACJ,YACA,QACA,QACA,UACoC;GACpC,MAAM,YAAY,0BAA0B,MAAM,YAAY,QAAQ,QAAQ,UAAU,OAAO;AAC/F,UAAO,cAAc,YAAY,IAAI,UAAU,IAAI,GAAG,KAAK;;EAE9D;;;;;AAMH,SAAgB,wBACd,OACA,QACA,cAAc,IAAI,2BAA2B,EACtB;AACvB,QAAO,MAAM,KAAK,SAAS,uBAAuB,MAAM,QAAQ,YAAY,CAAC"}