jazz-ai 0.2.2 → 0.4.3

package/dist/core/agent/tools/base-tool.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defineTool = defineTool;
-exports.makeJsonSchemaValidator = makeJsonSchemaValidator;
+exports.makeZodValidator = makeZodValidator;
 exports.withApprovalBoolean = withApprovalBoolean;
 const effect_1 = require("effect");
 const zod_1 = require("zod");
@@ -63,7 +63,7 @@ function defineTool(config) {
                                 message: approvalMessage,
                                 ...(execute
                                     ? {
-                                        instruction: `Please ask the user for confirmation. If they confirm, call this tool again with { "confirm": true } or call: ${execute.toolName} with these exact arguments: ${JSON.stringify(execute.buildArgs(validated))}`,
+                                        instruction: `Please ask the user for confirmation. If they confirm, ${execute.toolName} with these exact arguments: ${JSON.stringify(execute.buildArgs(validated))}`,
                                         executeToolName: execute.toolName,
                                         executeArgs: execute.buildArgs(validated),
                                     }
@@ -82,59 +82,19 @@ function defineTool(config) {
     };
 }
 /**
- * Build a minimal runtime validator from a JSON Schema subset.
- * Supports: type = string|number|boolean|array(object: items.type), required[], additionalProperties.
+ * Build a runtime validator from a Zod schema. Keeps validation logic and typing in sync.
  */
-function makeJsonSchemaValidator(schema) {
+function makeZodValidator(schema) {
     return (args) => {
-        const errors = [];
-        const s = schema;
-        if (s.type !== undefined && s.type !== "object") {
-            errors.push("Root schema.type must be 'object'");
-        }
-        const properties = (s.properties || {});
-        const required = new Set((s.required || []));
-        for (const key of required) {
-            if (!(key in args)) {
-                errors.push(`Missing required property: ${key}`);
-            }
-        }
-        for (const [key, value] of Object.entries(args)) {
-            const prop = properties[key];
-            if (!prop) {
-                if (s.additionalProperties === false) {
-                    errors.push(`Unknown property: ${key}`);
-                }
-                continue;
-            }
-            const expected = prop.type;
-            if (!expected)
-                continue;
-            const actual = typeof value;
-            if (expected === "array") {
-                if (!Array.isArray(value)) {
-                    errors.push(`Property '${key}' expected array, got ${actual}`);
-                }
-                else {
-                    const itemType = prop.items?.type;
-                    if (itemType) {
-                        for (let i = 0; i < value.length; i++) {
-                            const t = typeof value[i];
-                            if (t !== itemType) {
-                                errors.push(`Property '${key}[${i}]' expected ${itemType}, got ${t}`);
-                            }
-                        }
-                    }
-                }
-            }
-            else if (actual !== expected) {
-                errors.push(`Property '${key}' expected ${expected}, got ${actual}`);
-            }
-        }
-        if (errors.length > 0) {
+        const result = schema.safeParse(args);
+        if (!result.success) {
+            const errors = result.error.issues.map((issue) => {
+                const path = issue.path.join(".");
+                return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+            });
             return { valid: false, errors };
         }
-        return { valid: true, value: args };
+        return { valid: true, value: result.data };
     };
 }
 /**

package/dist/core/agent/tools/base-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-tool.js","sourceRoot":"","sources":["../../../../src/core/agent/tools/base-tool.ts"],"names":[],"mappings":";;AAgKA,gCAyDC;AAMD,0DAiEC;AAMD,kDAeC;AArTD,mCAAgC;AAChC,6BAAwB;AAqIxB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,UAAU,CACxB,MAA+B;IAE/B,MAAM,uBAAuB,GAAG,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;IAEnE,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,KAAK,IAAI;QAC9B,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,EAAE,uBAAuB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,OAAO,CACL,IAA6B,EAC7B,OAA6B;YAE7B,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACrC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;oBAClB,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACpE,OAAO,eAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;gBAC1E,CAAC;gBACD,MAAM,SAAS,GAAG,MAAM,CAAC,KAAa,CAAC;gBACvC,iCAAiC;gBACjC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;oBACpB,qCAAqC;oBACrC,OAAO,eAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;wBACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,QAA+C,CAAC;wBACxE,MAAM,eAAe,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;wBACpE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;wBACjC,OAAO;4BACL,OAAO,EAAE,KAAK;4BACd,MAAM,EAAE;gCACN,gBAAgB,EAAE,IAAI;gCACtB,OAAO,EAAE,eAAe;gCACxB,GAAG,CAAC,OAAO;oCACT,CAAC,CAAC;wCACE,WAAW,EAAE,iHAAiH,OAAO,CAAC,QAAQ,gCAAgC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE;wCAC5N,eAAe,EAAE,OAAO,CAAC,QAAQ;wCACjC,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC;qCAC1C;oCACH,CAAC,CAAC,EAAE,CAAC;6BACR;4BACD,KAAK,EACH,QAAQ,CAAC,YAAY;gCACrB,4DAA4D;yBACxC,CAAC;oBAC3B,CAAC,CAAC,CAAC;gBACL,CAAC;gBACD,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC5C,CAAC;YAED,yCAAyC;YACzC,OAAO,MAAM,CAAC,OAAO,CAAC,IAAY,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,uBAAuB,CACrC,MAA+B;IAE/B,OAAO,CAAC,IAA6B,EAAE,EAAE;QACvC,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,MAAM,CAAC,GAAG,MAKT,CAAC;QAEF,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,UAAU,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAGrC,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAa,CAAC,CAAC;QAEzD,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;gBACnB,MAAM,CAAC,IAAI,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;QAED,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,IAAI,CAAC,CAAC,oBAAoB,KAAK,KAAK,EAAE,CAAC;oBACrC,MAAM,CAAC,IAAI,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAC;gBAC1C,CAAC;gBACD,SAAS;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;YAC3B,IAAI,CAAC,QAAQ;gBAAE,SAAS;YACxB,MAAM,MAAM,GAAG,OAAO,KAAK,CAAC;YAC5B,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;gBACzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CAAC,aAAa,GAAG,yBAAyB,MAAM,EAAE,CAAC,CAAC;gBACjE,CAAC;qBAAM,CAAC;oBACN,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC;oBAClC,IAAI,QAAQ,EAAE,CAAC;wBACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;4BACtC,MAAM,CAAC,GAAG,OAAQ,KAAmB,CAAC,CAAC,CAAC,CAAC;4BACzC,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;gCACnB,MAAM,CAAC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,eAAe,QAAQ,SAAS,CAAC,EAAE,CAAC,CAAC;4BACxE,CAAC;wBACH,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/B,MAAM,CAAC,IAAI,CAAC,aAAa,GAAG,cAAc,QAAQ,SAAS,MAAM,EAAE,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAW,CAAC;QAC3C,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,IAAY,EAAW,CAAC;IACvD,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CACjC,MAAoB,EACpB,OAAsD;IAEtD,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,SAAS,CAAC;IAClD,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,qCAAqC,CAAC;IAElF,4EAA4E;IAC5E,IAAI,MAAM,YAAY,OAAC,CAAC,SAAS,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,CAAC,SAAS,CAAC,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;SAC/C,CAAC,CAAC;IACL,CAAC;IACD,yEAAyE;IACzE,OAAO,OAAC,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,CAAC,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAClF,CAAC"}
+{"version":3,"file":"base-tool.js","sourceRoot":"","sources":["../../../../src/core/agent/tools/base-tool.ts"],"names":[],"mappings":"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"}

package/dist/core/agent/tools/context-utils.d.ts

@@ -0,0 +1,6 @@
+import { type ToolExecutionContext } from "./tool-registry";
+export declare function buildKeyFromContext(context: ToolExecutionContext): {
+    readonly agentId: string;
+    readonly conversationId?: string;
+};
+//# sourceMappingURL=context-utils.d.ts.map

package/dist/core/agent/tools/context-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-utils.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/tools/context-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC,CAIA"}

package/dist/core/agent/tools/context-utils.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildKeyFromContext = buildKeyFromContext;
+function buildKeyFromContext(context) {
+    return context.conversationId
+        ? { agentId: context.agentId, conversationId: context.conversationId }
+        : { agentId: context.agentId };
+}
+//# sourceMappingURL=context-utils.js.map

package/dist/core/agent/tools/context-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-utils.js","sourceRoot":"","sources":["../../../../src/core/agent/tools/context-utils.ts"],"names":[],"mappings":";;AAEA,kDAOC;AAPD,SAAgB,mBAAmB,CAAC,OAA6B;IAI/D,OAAO,OAAO,CAAC,cAAc;QAC3B,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE;QACtE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;AACnC,CAAC"}

package/dist/core/agent/tools/env-utils.d.ts

@@ -0,0 +1,7 @@
+export type ProcessEnvRecord = Record<string, string | undefined>;
+/**
+ * Build a sanitized environment for child process execution.
+ * Strips sensitive vars while preserving essentials like PATH.
+ */
+export declare function createSanitizedEnv(overrides?: ProcessEnvRecord): ProcessEnvRecord;
+//# sourceMappingURL=env-utils.d.ts.map

package/dist/core/agent/tools/env-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-utils.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/tools/env-utils.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAElE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,GAAE,gBAAqB,GAAG,gBAAgB,CAoCrF"}

package/dist/core/agent/tools/env-utils.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSanitizedEnv = createSanitizedEnv;
+/**
+ * Build a sanitized environment for child process execution.
+ * Strips sensitive vars while preserving essentials like PATH.
+ */
+function createSanitizedEnv(overrides = {}) {
+    const baseEnv = {
+        PATH: process.env["PATH"] ?? "/usr/local/bin:/usr/bin:/bin",
+        HOME: process.env["HOME"],
+        USER: process.env["USER"],
+        LOGNAME: process.env["LOGNAME"] ?? process.env["USER"] ?? "jazz",
+        SHELL: process.env["SHELL"] ?? "/bin/sh",
+        LANG: process.env["LANG"] ?? "en_US.UTF-8",
+        LC_ALL: process.env["LC_ALL"] ?? "C",
+        LC_CTYPE: process.env["LC_CTYPE"] ?? "UTF-8",
+        TERM: process.env["TERM"] ?? "xterm-256color",
+        PWD: process.cwd(),
+        TMPDIR: process.env["TMPDIR"] ?? "/tmp",
+        XDG_RUNTIME_DIR: process.env["XDG_RUNTIME_DIR"],
+        GIT_PAGER: process.env["GIT_PAGER"] ?? "cat",
+        GIT_TERMINAL_PROMPT: "0",
+        ...overrides,
+    };
+    for (const [key, value] of Object.entries(process.env ?? {})) {
+        if (value === undefined) {
+            continue;
+        }
+        if (/API|KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|AUTH/i.test(key) ||
+            key in baseEnv ||
+            key.startsWith("SSH_")) {
+            continue;
+        }
+        baseEnv[key] = value;
+    }
+    return baseEnv;
+}
+//# sourceMappingURL=env-utils.js.map

package/dist/core/agent/tools/env-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-utils.js","sourceRoot":"","sources":["../../../../src/core/agent/tools/env-utils.ts"],"names":[],"mappings":";;AAMA,gDAoCC;AAxCD;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,YAA8B,EAAE;IACjE,MAAM,OAAO,GAAqB;QAChC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,8BAA8B;QAC3D,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;QACzB,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;QACzB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM;QAChE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,SAAS;QACxC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,aAAa;QAC1C,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG;QACpC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,OAAO;QAC5C,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,gBAAgB;QAC7C,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,MAAM;QACvC,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC/C,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK;QAC5C,mBAAmB,EAAE,GAAG;QACxB,GAAG,SAAS;KACb,CAAC;IAEF,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;QAC7D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QAED,IACE,gDAAgD,CAAC,IAAI,CAAC,GAAG,CAAC;YAC1D,GAAG,IAAI,OAAO;YACd,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EACtB,CAAC;YACD,SAAS;QACX,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/core/agent/tools/fs-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs-tools.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/tools/fs-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,KAAK,IAAI,EAA6B,MAAM,iBAAiB,CAAC;AAyDvE,wBAAgB,kBAAkB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAkK3F;AAGD,wBAAgB,aAAa,IAAI,IAAI,CAAC,wBAAwB,CAAC,CAoB9D;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAsIrF;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA6DrF;AAGD,wBAAgB,kBAAkB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAoI3F;AAKD,wBAAgB,mBAAmB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAkD5F;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAChD,UAAU,CAAC,UAAU,GAAG,wBAAwB,CACjD,CAsDA;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAsMvF;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAmOvF;AAGD,wBAAgB,eAAe,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA2DxF;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA0D/F;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAqEvF;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA+CrF;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA2E5F;AAGD,wBAAgB,iBAAiB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA0D1F;AAGD,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAGrF"}
+{"version":3,"file":"fs-tools.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/tools/fs-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAgD5C,wBAAgB,kBAAkB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAkK3F;AAGD,wBAAgB,aAAa,IAAI,IAAI,CAAC,wBAAwB,CAAC,CAoB9D;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAsIrF;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA6DrF;AAGD,wBAAgB,kBAAkB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAoI3F;AAKD,wBAAgB,mBAAmB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAkD5F;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAChD,UAAU,CAAC,UAAU,GAAG,wBAAwB,CACjD,CAsDA;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAsMvF;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAmOvF;AAGD,wBAAgB,eAAe,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA2DxF;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA0D/F;AAGD,wBAAgB,cAAc,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CAqEvF;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA+CrF;AAED,wBAAgB,mBAAmB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA2E5F;AAGD,wBAAgB,iBAAiB,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,GAAG,wBAAwB,CAAC,CA0D1F;AAGD,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,CAGrF"}

package/dist/core/agent/tools/fs-tools.js

@@ -22,16 +22,11 @@ const effect_1 = require("effect");
 const zod_1 = require("zod");
 const shell_1 = require("../../../services/shell");
 const base_tool_1 = require("./base-tool");
+const context_utils_1 = require("./context-utils");
 /**
  * Filesystem and shell tools: pwd, ls, cd, grep, find, mkdir, rm
  * mkdir and rm require explicit approval and are executed via hidden execute* tools.
  */
-// Utility helpers
-function buildKeyFromContext(context) {
-    return context.conversationId
-        ? { agentId: context.agentId, conversationId: context.conversationId }
-        : { agentId: context.agentId };
-}
 function normalizeFilterPattern(pattern) {
     if (!pattern || pattern.trim() === "")
         return { type: "substring" };
@@ -63,7 +58,7 @@ function normalizeStatSize(size) {
     }
     return null;
 }
-// findPath - helps agent discover paths when unsure
+// find_path - helps agent discover paths when unsure
 function createFindPathTool() {
     const parameters = zod_1.z
         .object({
@@ -82,8 +77,8 @@ function createFindPathTool() {
     })
         .strict();
     return (0, base_tool_1.defineTool)({
-        name: "findPath",
-        description: "Find directories or files by name using the system find command",
+        name: "find_path",
+        description: "Quick search for files or directories by name with shallow depth (default 3 levels). Use when you need to quickly locate a specific file or directory by name without deep traversal.",
         tags: ["filesystem", "search"],
         parameters,
         validate: (args) => {
@@ -97,9 +92,9 @@ function createFindPathTool() {
         },
         handler: (args, context) => effect_1.Effect.gen(function* () {
             const shell = yield* shell_1.FileSystemContextServiceTag;
-            const currentDir = yield* shell.getCwd(buildKeyFromContext(context));
+            const currentDir = yield* shell.getCwd((0, context_utils_1.buildKeyFromContext)(context));
             const searchDir = args.searchPath
-                ? yield* shell.resolvePath(buildKeyFromContext(context), args.searchPath)
+                ? yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.searchPath)
                 : currentDir;
             const maxDepth = args.maxDepth ?? 3;
             const searchType = args.type ?? "both";
@@ -206,7 +201,7 @@ function createPwdTool() {
         },
         handler: (_args, context) => effect_1.Effect.gen(function* () {
             const shell = yield* shell_1.FileSystemContextServiceTag;
-            const cwd = yield* shell.getCwd(buildKeyFromContext(context));
+            const cwd = yield* shell.getCwd((0, context_utils_1.buildKeyFromContext)(context));
             return { success: true, result: cwd };
         }),
     });
@@ -232,7 +227,7 @@ function createLsTool() {
         .strict();
     return (0, base_tool_1.defineTool)({
         name: "ls",
-        description: "List directory contents with optional filtering and recursion",
+        description: "List files and directories within a specified path. Supports recursive traversal, filtering by name patterns (substring or regex), showing hidden files, and limiting results. Returns file/directory names, paths, and types.",
         tags: ["filesystem", "listing"],
         parameters,
         validate: (args) => {
@@ -248,12 +243,12 @@ function createLsTool() {
             const fs = yield* platform_1.FileSystem.FileSystem;
             const shell = yield* shell_1.FileSystemContextServiceTag;
             const basePath = args.path
-                ? yield* shell.resolvePath(buildKeyFromContext(context), args.path).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.succeed({
+                ? yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.succeed({
                     success: false,
                     result: null,
                     error: error instanceof Error ? error.message : String(error),
                 })))
-                : yield* shell.getCwd(buildKeyFromContext(context));
+                : yield* shell.getCwd((0, context_utils_1.buildKeyFromContext)(context));
             // If path resolution failed, return the error with suggestions
             if (typeof basePath === "object" && "success" in basePath && !basePath.success) {
                 return basePath;
@@ -341,7 +336,7 @@ function createCdTool() {
             const fs = yield* platform_1.FileSystem.FileSystem;
             const shell = yield* shell_1.FileSystemContextServiceTag;
             // Try to resolve the path - this will provide helpful suggestions if the path doesn't exist
-            const targetResult = yield* shell.resolvePath(buildKeyFromContext(context), args.path).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.succeed({
+            const targetResult = yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path).pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.succeed({
                 success: false,
                 result: null,
                 error: error instanceof Error ? error.message : String(error),
@@ -358,7 +353,7 @@ function createCdTool() {
                 if (stat.type !== "Directory") {
                     return { success: false, result: null, error: `Not a directory: ${target}` };
                 }
-                yield* shell.setCwd(buildKeyFromContext(context), target);
+                yield* shell.setCwd((0, context_utils_1.buildKeyFromContext)(context), target);
                 return { success: true, result: target };
             }
             catch (error) {
@@ -388,8 +383,8 @@ function createReadFileTool() {
     })
         .strict();
     return (0, base_tool_1.defineTool)({
-        name: "readFile",
-        description: "Read a text file with optional line range and size limit",
+        name: "read_file",
+        description: "Read the contents of a text file with optional line range selection (startLine/endLine). Automatically handles UTF-8 BOM, enforces size limits to prevent memory issues (default 128KB), and reports truncation. Returns file content, encoding, line counts, and range information.",
         tags: ["filesystem", "read"],
         parameters,
         validate: (args) => {
@@ -405,7 +400,7 @@ function createReadFileTool() {
             const fs = yield* platform_1.FileSystem.FileSystem;
             const shell = yield* shell_1.FileSystemContextServiceTag;
             const filePathResult = yield* shell
-                .resolvePath(buildKeyFromContext(context), args.path)
+                .resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path)
                 .pipe(effect_1.Effect.catchAll((error) => effect_1.Effect.succeed({
                 success: false,
                 result: null,
@@ -492,7 +487,7 @@ function createWriteFileTool() {
     })
         .strict();
     return (0, base_tool_1.defineTool)({
-        name: "writeFile",
+        name: "write_file",
         description: "Write content to a file, creating it if it doesn't exist (requires user approval)",
         tags: ["filesystem", "write"],
         parameters,
@@ -505,14 +500,14 @@ function createWriteFileTool() {
         approval: {
             message: (args, context) => effect_1.Effect.gen(function* () {
                 const shell = yield* shell_1.FileSystemContextServiceTag;
-                const target = yield* shell.resolvePath(buildKeyFromContext(context), args.path, {
+                const target = yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path, {
                     skipExistenceCheck: true,
                 });
-                return `About to write to file: ${target}${args.createDirs === true ? " (will create parent directories)" : ""}.\n\nIMPORTANT: After getting user confirmation, you MUST call the executeWriteFile tool with these exact arguments: {"path": "${args.path}", "content": ${JSON.stringify(args.content)}, "encoding": "${args.encoding ?? "utf-8"}", "createDirs": ${args.createDirs === true}}`;
+                return `About to write to file: ${target}${args.createDirs === true ? " (will create parent directories)" : ""}.\n\nIMPORTANT: After getting user confirmation, you MUST call the execute_write_file tool with these exact arguments: {"path": "${args.path}", "content": ${JSON.stringify(args.content)}, "encoding": "${args.encoding ?? "utf-8"}", "createDirs": ${args.createDirs === true}}`;
             }),
             errorMessage: "Approval required: File writing requires user confirmation.",
             execute: {
-                toolName: "executeWriteFile",
+                toolName: "execute_write_file",
                 buildArgs: (args) => ({
                     path: args.path,
                     content: args.content,
@@ -537,8 +532,8 @@ function createExecuteWriteFileTool() {
     })
         .strict();
     return (0, base_tool_1.defineTool)({
-        name: "executeWriteFile",
-        description: "Execute writeFile after user approval",
+        name: "execute_write_file",
+        description: "Internal tool that performs the actual file write operation after user has approved the write_file request. Creates or overwrites the file at the specified path with the provided content.",
         hidden: true,
         parameters,
         validate: (args) => {
@@ -550,7 +545,7 @@ function createExecuteWriteFileTool() {
         handler: (args, context) => effect_1.Effect.gen(function* () {
             const fs = yield* platform_1.FileSystem.FileSystem;
             const shell = yield* shell_1.FileSystemContextServiceTag;
-            const target = yield* shell.resolvePath(buildKeyFromContext(context), args.path, {
+            const target = yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path, {
                 skipExistenceCheck: true,
             });
             try {
@@ -593,7 +588,7 @@ function createGrepTool() {
         .strict();
     return (0, base_tool_1.defineTool)({
         name: "grep",
-        description: "Search for a pattern in files using the system grep command",
+        description: "Search for text patterns within file contents using grep. Supports literal strings and regex patterns. Use to find specific code, text, or patterns across files. Returns matching lines with file paths and line numbers.",
         tags: ["search", "text"],
         parameters,
         validate: (args) => {
@@ -608,8 +603,8 @@ function createGrepTool() {
         handler: (args, context) => effect_1.Effect.gen(function* () {
             const shell = yield* shell_1.FileSystemContextServiceTag;
             const start = args.path
-                ? yield* shell.resolvePath(buildKeyFromContext(context), args.path)
-                : yield* shell.getCwd(buildKeyFromContext(context));
+                ? yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path)
+                : yield* shell.getCwd((0, context_utils_1.buildKeyFromContext)(context));
             const recursive = args.recursive !== false;
             const maxResults = typeof args.maxResults === "number" && args.maxResults > 0 ? args.maxResults : 5000;
             // Build grep command arguments
@@ -747,7 +742,7 @@ function createFindTool() {
         .strict();
     return (0, base_tool_1.defineTool)({
         name: "find",
-        description: "Find files and directories using the system find command with smart hierarchical search",
+        description: "Advanced file and directory search with smart hierarchical search strategy (searches cwd, home, and parent directories in order). Supports deep traversal (default 25 levels), regex patterns, type filters, and hidden files. Use for comprehensive searches when find_path doesn't locate what you need.",
         tags: ["filesystem", "search"],
         parameters,
         validate: (args) => {
@@ -770,13 +765,13 @@ function createFindTool() {
             const searchPaths = [];
             if (args.path) {
                 // If path is specified, use it directly
-                const start = yield* shell.resolvePath(buildKeyFromContext(context), args.path);
+                const start = yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path);
                 searchPaths.push(start);
             }
             else if (useSmart) {
                 // Smart search: start with most likely locations
                 const home = process.env["HOME"] || "";
-                const cwd = yield* shell.getCwd(buildKeyFromContext(context));
+                const cwd = yield* shell.getCwd((0, context_utils_1.buildKeyFromContext)(context));
                 // 1. Current working directory (most likely)
                 if (cwd && cwd !== home) {
                     searchPaths.push(cwd);
@@ -800,7 +795,7 @@ function createFindTool() {
             }
             else {
                 // Traditional search: start from current directory
-                const start = yield* shell.getCwd(buildKeyFromContext(context));
+                const start = yield* shell.getCwd((0, context_utils_1.buildKeyFromContext)(context));
                 searchPaths.push(start);
             }
             const allResults = [];
@@ -926,7 +921,7 @@ function createMkdirTool() {
             message: (args, context) => effect_1.Effect.gen(function* () {
                 const shell = yield* shell_1.FileSystemContextServiceTag;
                 const fs = yield* platform_1.FileSystem.FileSystem;
-                const target = yield* shell.resolvePathForMkdir(buildKeyFromContext(context), args.path);
+                const target = yield* shell.resolvePathForMkdir((0, context_utils_1.buildKeyFromContext)(context), args.path);
                 // Check if directory already exists
                 const statResult = yield* fs
                     .stat(target)
@@ -939,11 +934,11 @@ function createMkdirTool() {
                         return `Path exists but is not a directory: ${target}\n\nCannot create directory at this location because a file already exists.`;
                     }
                 }
-                return `About to create directory: ${target}${args.recursive === false ? "" : " (with parents)"}.\n\nIMPORTANT: After getting user confirmation, you MUST call the executeMkdir tool with these exact arguments: {"path": "${args.path}", "recursive": ${args.recursive !== false}}`;
+                return `About to create directory: ${target}${args.recursive === false ? "" : " (with parents)"}.\n\nIMPORTANT: After getting user confirmation, you MUST call the execute_mkdir tool with these exact arguments: {"path": "${args.path}", "recursive": ${args.recursive !== false}}`;
             }),
             errorMessage: "Approval required: Directory creation requires user confirmation.",
             execute: {
-                toolName: "executeMkdir",
+                toolName: "execute_mkdir",
                 buildArgs: (args) => ({
                     path: args.path,
                     recursive: args.recursive,
@@ -961,8 +956,8 @@ function createExecuteMkdirTool() {
     })
         .strict();
     return (0, base_tool_1.defineTool)({
-        name: "executeMkdir",
-        description: "Execute mkdir after user approval",
+        name: "execute_mkdir",
+        description: "Internal tool that performs the actual directory creation after user has approved the mkdir request. Creates the directory at the specified path, optionally creating parent directories.",
         hidden: true,
         parameters,
         validate: (args) => {
@@ -977,7 +972,7 @@ function createExecuteMkdirTool() {
         handler: (args, context) => effect_1.Effect.gen(function* () {
             const fs = yield* platform_1.FileSystem.FileSystem;
             const shell = yield* shell_1.FileSystemContextServiceTag;
-            const target = yield* shell.resolvePathForMkdir(buildKeyFromContext(context), args.path);
+            const target = yield* shell.resolvePathForMkdir((0, context_utils_1.buildKeyFromContext)(context), args.path);
             // Check if directory already exists
             const statResult = yield* fs.stat(target).pipe(effect_1.Effect.catchAll(() => effect_1.Effect.succeed(null)));
             if (statResult) {
@@ -1015,7 +1010,7 @@ function createStatTool() {
         .strict();
     return (0, base_tool_1.defineTool)({
         name: "stat",
-        description: "Check if a file or directory exists and get its information",
+        description: "Check if a file or directory exists and retrieve its metadata (type, size, modification time, access time). Use this to verify existence before operations or to get file information without reading contents.",
         tags: ["filesystem", "info"],
         parameters,
         validate: (args) => {
@@ -1030,7 +1025,7 @@ function createStatTool() {
         handler: (args, context) => effect_1.Effect.gen(function* () {
             const fs = yield* platform_1.FileSystem.FileSystem;
             const shell = yield* shell_1.FileSystemContextServiceTag;
-            const target = yield* shell.resolvePathForMkdir(buildKeyFromContext(context), args.path);
+            const target = yield* shell.resolvePathForMkdir((0, context_utils_1.buildKeyFromContext)(context), args.path);
             try {
                 const stat = yield* fs.stat(target);
                 const normalizedSize = normalizeStatSize(stat.size);
@@ -1100,13 +1095,13 @@ function createRmTool() {
         approval: {
             message: (args, context) => effect_1.Effect.gen(function* () {
                 const shell = yield* shell_1.FileSystemContextServiceTag;
-                const target = yield* shell.resolvePath(buildKeyFromContext(context), args.path);
+                const target = yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path);
                 const recurse = args.recursive === true ? " recursively" : "";
-                return `About to delete${recurse}: ${target}. This action may be irreversible.\nIf the user confirms, call executeRm with the same arguments.`;
+                return `About to delete${recurse}: ${target}. This action may be irreversible.\n\nIMPORTANT: After getting user confirmation, you MUST call the execute_rm tool with the same arguments: {"path": "${args.path}", "recursive": ${args.recursive === true}, "force": ${args.force === true}}`;
             }),
             errorMessage: "Approval required: File/directory deletion requires user confirmation.",
             execute: {
-                toolName: "executeRm",
+                toolName: "execute_rm",
                 buildArgs: (args) => ({
                     path: args.path,
                     recursive: args.recursive,
@@ -1126,8 +1121,8 @@ function createExecuteRmTool() {
     })
         .strict();
     return (0, base_tool_1.defineTool)({
-        name: "executeRm",
-        description: "Execute rm after user approval",
+        name: "execute_rm",
+        description: "Internal tool that performs the actual file/directory removal after user has approved the rm request. Deletes the specified path, optionally recursively for directories.",
         hidden: true,
         parameters,
         validate: (args) => {
@@ -1142,7 +1137,7 @@ function createExecuteRmTool() {
         handler: (args, context) => effect_1.Effect.gen(function* () {
             const fs = yield* platform_1.FileSystem.FileSystem;
             const shell = yield* shell_1.FileSystemContextServiceTag;
-            const target = yield* shell.resolvePath(buildKeyFromContext(context), args.path);
+            const target = yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path);
             try {
                 // Basic safeguards: do not allow deleting root or home dir directly
                 if (target === "/" || target === process.env["HOME"]) {
@@ -1203,8 +1198,8 @@ function createFindDirTool() {
     })
         .strict();
     return (0, base_tool_1.defineTool)({
-        name: "finddir",
-        description: "Search for directories by name with partial matching",
+        name: "find_dir",
+        description: "Search specifically for directories by name with partial matching support. Specialized version of find_path that only returns directories. Use when you need to locate a directory and want to filter out files from results.",
         tags: ["filesystem", "search"],
         parameters,
         validate: (args) => {
@@ -1219,9 +1214,9 @@ function createFindDirTool() {
         handler: (args, context) => effect_1.Effect.gen(function* () {
             const shell = yield* shell_1.FileSystemContextServiceTag;
             const startPath = args.path
-                ? yield* shell.resolvePath(buildKeyFromContext(context), args.path)
-                : yield* shell.getCwd(buildKeyFromContext(context));
-            const found = yield* shell.findDirectory(buildKeyFromContext(context), args.name, args.maxDepth || 3);
+                ? yield* shell.resolvePath((0, context_utils_1.buildKeyFromContext)(context), args.path)
+                : yield* shell.getCwd((0, context_utils_1.buildKeyFromContext)(context));
+            const found = yield* shell.findDirectory((0, context_utils_1.buildKeyFromContext)(context), args.name, args.maxDepth || 3);
             return {
                 success: true,
                 result: {