@frontmcp/plugins 0.4.1 → 0.5.1

package/src/codecall/services/enclave.service.js

@@ -0,0 +1,214 @@
+"use strict";
+// file: libs/plugins/src/codecall/services/enclave.service.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScriptTooLargeError = void 0;
+const tslib_1 = require("tslib");
+const sdk_1 = require("@frontmcp/sdk");
+const enclave_vm_1 = require("enclave-vm");
+/**
+ * Service for executing AgentScript code using enclave-vm
+ *
+ * This service wraps the Enclave class and provides:
+ * - Safe AgentScript execution with AST validation
+ * - Automatic code transformation (callTool -> __safe_callTool)
+ * - Runtime limits (timeout, iterations, tool calls)
+ * - Tool call integration with FrontMCP pipeline
+ */
+/**
+ * Error thrown when script exceeds maximum length and sidecar is disabled
+ */
+class ScriptTooLargeError extends Error {
+    code = 'SCRIPT_TOO_LARGE';
+    scriptLength;
+    maxLength;
+    constructor(scriptLength, maxLength) {
+        super(`Script length (${scriptLength} characters) exceeds maximum allowed length (${maxLength} characters). ` +
+            `Enable sidecar to handle large data, or reduce script size.`);
+        this.name = 'ScriptTooLargeError';
+        this.scriptLength = scriptLength;
+        this.maxLength = maxLength;
+    }
+}
+exports.ScriptTooLargeError = ScriptTooLargeError;
+let EnclaveService = class EnclaveService {
+    vmOptions;
+    sidecarOptions;
+    constructor(config) {
+        // Use getAll() to avoid deep type instantiation with DottedPath<T>
+        const all = config.getAll();
+        this.vmOptions = all.resolvedVm;
+        this.sidecarOptions = all.sidecar;
+    }
+    /**
+     * Execute AgentScript code in the enclave
+     *
+     * @param code - The AgentScript code to execute (raw, not transformed)
+     * @param environment - The VM environment with callTool, getTool, etc.
+     * @returns Execution result with success/error and logs
+     * @throws ScriptTooLargeError if script exceeds max length and sidecar is disabled
+     */
+    async execute(code, environment) {
+        const logs = [];
+        // Validate script length when sidecar is disabled
+        if (!this.sidecarOptions.enabled && this.sidecarOptions.maxScriptLengthWhenDisabled !== null) {
+            const maxLength = this.sidecarOptions.maxScriptLengthWhenDisabled;
+            if (code.length > maxLength) {
+                throw new ScriptTooLargeError(code.length, maxLength);
+            }
+        }
+        // Create tool handler that bridges to CodeCallVmEnvironment
+        const toolHandler = async (toolName, args) => {
+            return environment.callTool(toolName, args);
+        };
+        // Build sidecar configuration if enabled
+        const sidecar = this.sidecarOptions.enabled
+            ? {
+                enabled: true,
+                maxTotalSize: this.sidecarOptions.maxTotalSize,
+                maxReferenceSize: this.sidecarOptions.maxReferenceSize,
+                extractionThreshold: this.sidecarOptions.extractionThreshold,
+                maxResolvedSize: this.sidecarOptions.maxResolvedSize,
+                allowComposites: this.sidecarOptions.allowComposites,
+            }
+            : undefined;
+        // Create enclave with configuration from CodeCallConfig
+        const enclave = new enclave_vm_1.Enclave({
+            timeout: this.vmOptions.timeoutMs,
+            maxToolCalls: this.vmOptions.maxSteps || 100,
+            maxIterations: 10000,
+            toolHandler,
+            validate: true,
+            transform: true,
+            sidecar,
+            // Allow functions in globals since we intentionally provide getTool, mcpLog, mcpNotify, and console
+            allowFunctionsInGlobals: true,
+            globals: {
+                // Provide getTool as a custom global
+                getTool: environment.getTool,
+                // Provide logging functions if available
+                ...(environment.mcpLog
+                    ? {
+                        mcpLog: (level, message, metadata) => {
+                            environment.mcpLog(level, message, metadata);
+                            logs.push(`[mcp:${level}] ${message}`);
+                        },
+                    }
+                    : {}),
+                ...(environment.mcpNotify
+                    ? {
+                        mcpNotify: (event, payload) => {
+                            environment.mcpNotify(event, payload);
+                            logs.push(`[notify] ${event}`);
+                        },
+                    }
+                    : {}),
+                // Provide console if allowed
+                ...(this.vmOptions.allowConsole
+                    ? {
+                        console: {
+                            log: (...args) => {
+                                const message = args.map((arg) => String(arg)).join(' ');
+                                logs.push(`[log] ${message}`);
+                            },
+                            warn: (...args) => {
+                                const message = args.map((arg) => String(arg)).join(' ');
+                                logs.push(`[warn] ${message}`);
+                            },
+                            error: (...args) => {
+                                const message = args.map((arg) => String(arg)).join(' ');
+                                logs.push(`[error] ${message}`);
+                            },
+                        },
+                    }
+                    : {}),
+            },
+        });
+        try {
+            const result = await enclave.run(code);
+            return this.mapEnclaveResult(result, logs);
+        }
+        finally {
+            enclave.dispose();
+        }
+    }
+    /**
+     * Map Enclave ExecutionResult to EnclaveExecutionResult
+     */
+    mapEnclaveResult(result, logs) {
+        if (result.success) {
+            return {
+                success: true,
+                result: result.value,
+                logs,
+                timedOut: false,
+                stats: {
+                    duration: result.stats.duration,
+                    toolCallCount: result.stats.toolCallCount,
+                    iterationCount: result.stats.iterationCount,
+                },
+            };
+        }
+        // Handle error cases
+        const error = result.error;
+        const timedOut = error.message?.includes('timed out') || error.code === 'TIMEOUT';
+        // Check if it's a validation error
+        if (error.code === 'VALIDATION_ERROR') {
+            return {
+                success: false,
+                error: {
+                    message: error.message,
+                    name: 'ValidationError',
+                    code: error.code,
+                },
+                logs,
+                timedOut: false,
+            };
+        }
+        // Check if it's a tool error (has toolName in the error data)
+        const errorData = error.data;
+        const toolName = errorData?.['toolName'];
+        if (toolName) {
+            return {
+                success: false,
+                error: {
+                    message: error.message,
+                    name: error.name,
+                    stack: error.stack,
+                    code: error.code,
+                    toolName,
+                    toolInput: errorData?.['toolInput'],
+                    details: errorData?.['details'],
+                },
+                logs,
+                timedOut,
+            };
+        }
+        // Generic error
+        return {
+            success: false,
+            error: {
+                message: error.message,
+                name: error.name,
+                stack: error.stack,
+                code: error.code,
+            },
+            logs,
+            timedOut,
+            stats: {
+                duration: result.stats.duration,
+                toolCallCount: result.stats.toolCallCount,
+                iterationCount: result.stats.iterationCount,
+            },
+        };
+    }
+};
+EnclaveService = tslib_1.__decorate([
+    (0, sdk_1.Provider)({
+        name: 'codecall:enclave',
+        description: 'Executes AgentScript code in a secure enclave',
+        scope: sdk_1.ProviderScope.GLOBAL,
+    }),
+    tslib_1.__metadata("design:paramtypes", [Function])
+], EnclaveService);
+exports.default = EnclaveService;
+//# sourceMappingURL=enclave.service.js.map

package/src/codecall/services/enclave.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enclave.service.js","sourceRoot":"","sources":["../../../../src/codecall/services/enclave.service.ts"],"names":[],"mappings":";AAAA,8DAA8D;;;;AAE9D,uCAAwD;AACxD,2CAA2G;AA8B3G;;;;;;;;GAQG;AACH;;GAEG;AACH,MAAa,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,kBAAkB,CAAC;IAC1B,YAAY,CAAS;IACrB,SAAS,CAAS;IAE3B,YAAY,YAAoB,EAAE,SAAiB;QACjD,KAAK,CACH,kBAAkB,YAAY,gDAAgD,SAAS,gBAAgB;YACrG,6DAA6D,CAChE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAdD,kDAcC;AAOc,IAAM,cAAc,GAApB,MAAM,cAAc;IAChB,SAAS,CAA4B;IACrC,cAAc,CAAyB;IAExD,YAAY,MAAsB;QAChC,mEAAmE;QACnE,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC;QAChC,IAAI,CAAC,cAAc,GAAG,GAAG,CAAC,OAAO,CAAC;IACpC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,WAAkC;QAC5D,MAAM,IAAI,GAAa,EAAE,CAAC;QAE1B,kDAAkD;QAClD,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,2BAA2B,KAAK,IAAI,EAAE,CAAC;YAC7F,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,2BAA2B,CAAC;YAClE,IAAI,IAAI,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;gBAC5B,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAED,4DAA4D;QAC5D,MAAM,WAAW,GAAgB,KAAK,EAAE,QAAgB,EAAE,IAA6B,EAAE,EAAE;YACzF,OAAO,WAAW,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC9C,CAAC,CAAC;QAEF,yCAAyC;QACzC,MAAM,OAAO,GAAwC,IAAI,CAAC,cAAc,CAAC,OAAO;YAC9E,CAAC,CAAC;gBACE,OAAO,EAAE,IAAI;gBACb,YAAY,EAAE,IAAI,CAAC,cAAc,CAAC,YAAY;gBAC9C,gBAAgB,EAAE,IAAI,CAAC,cAAc,CAAC,gBAAgB;gBACtD,mBAAmB,EAAE,IAAI,CAAC,cAAc,CAAC,mBAAmB;gBAC5D,eAAe,EAAE,IAAI,CAAC,cAAc,CAAC,eAAe;gBACpD,eAAe,EAAE,IAAI,CAAC,cAAc,CAAC,eAAe;aACrD;YACH,CAAC,CAAC,SAAS,CAAC;QAEd,wDAAwD;QACxD,MAAM,OAAO,GAAG,IAAI,oBAAO,CAAC;YAC1B,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS;YACjC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,IAAI,GAAG;YAC5C,aAAa,EAAE,KAAK;YACpB,WAAW;YACX,QAAQ,EAAE,IAAI;YACd,SAAS,EAAE,IAAI;YACf,OAAO;YACP,oGAAoG;YACpG,uBAAuB,EAAE,IAAI;YAC7B,OAAO,EAAE;gBACP,qCAAqC;gBACrC,OAAO,EAAE,WAAW,CAAC,OAAO;gBAC5B,yCAAyC;gBACzC,GAAG,CAAC,WAAW,CAAC,MAAM;oBACpB,CAAC,CAAC;wBACE,MAAM,EAAE,CACN,KAA0C,EAC1C,OAAe,EACf,QAAkC,EAClC,EAAE;4BACF,WAAW,CAAC,MAAO,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;4BAC9C,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,OAAO,EAAE,CAAC,CAAC;wBACzC,CAAC;qBACF;oBACH,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,WAAW,CAAC,SAAS;oBACvB,CAAC,CAAC;wBACE,SAAS,EAAE,CAAC,KAAa,EAAE,OAAgC,EAAE,EAAE;4BAC7D,WAAW,CAAC,SAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;4BACvC,IAAI,CAAC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC;wBACjC,CAAC;qBACF;oBACH,CAAC,CAAC,EAAE,CAAC;gBACP,6BAA6B;gBAC7B,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY;oBAC7B,CAAC,CAAC;wBACE,OAAO,EAAE;4BACP,GAAG,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE;gCAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gCACzD,IAAI,CAAC,IAAI,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;4BAChC,CAAC;4BACD,IAAI,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE;gCAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gCACzD,IAAI,CAAC,IAAI,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;4BACjC,CAAC;4BACD,KAAK,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE;gCAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gCACzD,IAAI,CAAC,IAAI,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC;4BAClC,CAAC;yBACF;qBACF;oBACH,CAAC,CAAC,EAAE,CAAC;aACR;SACF,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAU,IAAI,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7C,CAAC;gBAAS,CAAC;YACT,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC;IACH,CAAC;IAED;;OAEG;IACK,gBAAgB,CAAC,MAAgC,EAAE,IAAc;QACvE,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,MAAM,CAAC,KAAK;gBACpB,IAAI;gBACJ,QAAQ,EAAE,KAAK;gBACf,KAAK,EAAE;oBACL,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ;oBAC/B,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,aAAa;oBACzC,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,cAAc;iBAC5C;aACF,CAAC;QACJ,CAAC;QAED,qBAAqB;QACrB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAM,CAAC;QAC5B,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;QAElF,mCAAmC;QACnC,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YACtC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,IAAI,EAAE,iBAAiB;oBACvB,IAAI,EAAE,KAAK,CAAC,IAAI;iBACjB;gBACD,IAAI;gBACJ,QAAQ,EAAE,KAAK;aAChB,CAAC;QACJ,CAAC;QAED,8DAA8D;QAC9D,MAAM,SAAS,GAAG,KAAK,CAAC,IAA2C,CAAC;QACpE,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC,UAAU,CAAuB,CAAC;QAC/D,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,QAAQ;oBACR,SAAS,EAAE,SAAS,EAAE,CAAC,WAAW,CAAC;oBACnC,OAAO,EAAE,SAAS,EAAE,CAAC,SAAS,CAAC;iBAChC;gBACD,IAAI;gBACJ,QAAQ;aACT,CAAC;QACJ,CAAC;QAED,gBAAgB;QAChB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACL,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB;YACD,IAAI;YACJ,QAAQ;YACR,KAAK,EAAE;gBACL,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ;gBAC/B,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,aAAa;gBACzC,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,cAAc;aAC5C;SACF,CAAC;IACJ,CAAC;CACF,CAAA;AA1LoB,cAAc;IALlC,IAAA,cAAQ,EAAC;QACR,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,+CAA+C;QAC5D,KAAK,EAAE,mBAAa,CAAC,MAAM;KAC5B,CAAC;;GACmB,cAAc,CA0LlC;kBA1LoB,cAAc","sourcesContent":["// file: libs/plugins/src/codecall/services/enclave.service.ts\n\nimport { Provider, ProviderScope } from '@frontmcp/sdk';\nimport { Enclave, type ExecutionResult, type ToolHandler, type ReferenceSidecarOptions } from 'enclave-vm';\nimport type CodeCallConfig from '../providers/code-call.config';\nimport type { CodeCallVmEnvironment, ResolvedCodeCallVmOptions } from '../codecall.symbol';\nimport type { CodeCallSidecarOptions } from '../codecall.types';\n\n/**\n * Result from enclave execution - maps to existing VmExecutionResult interface\n */\nexport interface EnclaveExecutionResult {\n  success: boolean;\n  result?: unknown;\n  error?: {\n    message: string;\n    name: string;\n    stack?: string;\n    code?: string;\n    toolName?: string;\n    toolInput?: unknown;\n    details?: unknown;\n    [key: string]: unknown;\n  };\n  logs: string[];\n  timedOut: boolean;\n  stats?: {\n    duration: number;\n    toolCallCount: number;\n    iterationCount: number;\n  };\n}\n\n/**\n * Service for executing AgentScript code using enclave-vm\n *\n * This service wraps the Enclave class and provides:\n * - Safe AgentScript execution with AST validation\n * - Automatic code transformation (callTool -> __safe_callTool)\n * - Runtime limits (timeout, iterations, tool calls)\n * - Tool call integration with FrontMCP pipeline\n */\n/**\n * Error thrown when script exceeds maximum length and sidecar is disabled\n */\nexport class ScriptTooLargeError extends Error {\n  readonly code = 'SCRIPT_TOO_LARGE';\n  readonly scriptLength: number;\n  readonly maxLength: number;\n\n  constructor(scriptLength: number, maxLength: number) {\n    super(\n      `Script length (${scriptLength} characters) exceeds maximum allowed length (${maxLength} characters). ` +\n        `Enable sidecar to handle large data, or reduce script size.`,\n    );\n    this.name = 'ScriptTooLargeError';\n    this.scriptLength = scriptLength;\n    this.maxLength = maxLength;\n  }\n}\n\n@Provider({\n  name: 'codecall:enclave',\n  description: 'Executes AgentScript code in a secure enclave',\n  scope: ProviderScope.GLOBAL,\n})\nexport default class EnclaveService {\n  private readonly vmOptions: ResolvedCodeCallVmOptions;\n  private readonly sidecarOptions: CodeCallSidecarOptions;\n\n  constructor(config: CodeCallConfig) {\n    // Use getAll() to avoid deep type instantiation with DottedPath<T>\n    const all = config.getAll();\n    this.vmOptions = all.resolvedVm;\n    this.sidecarOptions = all.sidecar;\n  }\n\n  /**\n   * Execute AgentScript code in the enclave\n   *\n   * @param code - The AgentScript code to execute (raw, not transformed)\n   * @param environment - The VM environment with callTool, getTool, etc.\n   * @returns Execution result with success/error and logs\n   * @throws ScriptTooLargeError if script exceeds max length and sidecar is disabled\n   */\n  async execute(code: string, environment: CodeCallVmEnvironment): Promise<EnclaveExecutionResult> {\n    const logs: string[] = [];\n\n    // Validate script length when sidecar is disabled\n    if (!this.sidecarOptions.enabled && this.sidecarOptions.maxScriptLengthWhenDisabled !== null) {\n      const maxLength = this.sidecarOptions.maxScriptLengthWhenDisabled;\n      if (code.length > maxLength) {\n        throw new ScriptTooLargeError(code.length, maxLength);\n      }\n    }\n\n    // Create tool handler that bridges to CodeCallVmEnvironment\n    const toolHandler: ToolHandler = async (toolName: string, args: Record<string, unknown>) => {\n      return environment.callTool(toolName, args);\n    };\n\n    // Build sidecar configuration if enabled\n    const sidecar: ReferenceSidecarOptions | undefined = this.sidecarOptions.enabled\n      ? {\n          enabled: true,\n          maxTotalSize: this.sidecarOptions.maxTotalSize,\n          maxReferenceSize: this.sidecarOptions.maxReferenceSize,\n          extractionThreshold: this.sidecarOptions.extractionThreshold,\n          maxResolvedSize: this.sidecarOptions.maxResolvedSize,\n          allowComposites: this.sidecarOptions.allowComposites,\n        }\n      : undefined;\n\n    // Create enclave with configuration from CodeCallConfig\n    const enclave = new Enclave({\n      timeout: this.vmOptions.timeoutMs,\n      maxToolCalls: this.vmOptions.maxSteps || 100,\n      maxIterations: 10000,\n      toolHandler,\n      validate: true,\n      transform: true,\n      sidecar,\n      // Allow functions in globals since we intentionally provide getTool, mcpLog, mcpNotify, and console\n      allowFunctionsInGlobals: true,\n      globals: {\n        // Provide getTool as a custom global\n        getTool: environment.getTool,\n        // Provide logging functions if available\n        ...(environment.mcpLog\n          ? {\n              mcpLog: (\n                level: 'debug' | 'info' | 'warn' | 'error',\n                message: string,\n                metadata?: Record<string, unknown>,\n              ) => {\n                environment.mcpLog!(level, message, metadata);\n                logs.push(`[mcp:${level}] ${message}`);\n              },\n            }\n          : {}),\n        ...(environment.mcpNotify\n          ? {\n              mcpNotify: (event: string, payload: Record<string, unknown>) => {\n                environment.mcpNotify!(event, payload);\n                logs.push(`[notify] ${event}`);\n              },\n            }\n          : {}),\n        // Provide console if allowed\n        ...(this.vmOptions.allowConsole\n          ? {\n              console: {\n                log: (...args: unknown[]) => {\n                  const message = args.map((arg) => String(arg)).join(' ');\n                  logs.push(`[log] ${message}`);\n                },\n                warn: (...args: unknown[]) => {\n                  const message = args.map((arg) => String(arg)).join(' ');\n                  logs.push(`[warn] ${message}`);\n                },\n                error: (...args: unknown[]) => {\n                  const message = args.map((arg) => String(arg)).join(' ');\n                  logs.push(`[error] ${message}`);\n                },\n              },\n            }\n          : {}),\n      },\n    });\n\n    try {\n      const result = await enclave.run<unknown>(code);\n      return this.mapEnclaveResult(result, logs);\n    } finally {\n      enclave.dispose();\n    }\n  }\n\n  /**\n   * Map Enclave ExecutionResult to EnclaveExecutionResult\n   */\n  private mapEnclaveResult(result: ExecutionResult<unknown>, logs: string[]): EnclaveExecutionResult {\n    if (result.success) {\n      return {\n        success: true,\n        result: result.value,\n        logs,\n        timedOut: false,\n        stats: {\n          duration: result.stats.duration,\n          toolCallCount: result.stats.toolCallCount,\n          iterationCount: result.stats.iterationCount,\n        },\n      };\n    }\n\n    // Handle error cases\n    const error = result.error!;\n    const timedOut = error.message?.includes('timed out') || error.code === 'TIMEOUT';\n\n    // Check if it's a validation error\n    if (error.code === 'VALIDATION_ERROR') {\n      return {\n        success: false,\n        error: {\n          message: error.message,\n          name: 'ValidationError',\n          code: error.code,\n        },\n        logs,\n        timedOut: false,\n      };\n    }\n\n    // Check if it's a tool error (has toolName in the error data)\n    const errorData = error.data as Record<string, unknown> | undefined;\n    const toolName = errorData?.['toolName'] as string | undefined;\n    if (toolName) {\n      return {\n        success: false,\n        error: {\n          message: error.message,\n          name: error.name,\n          stack: error.stack,\n          code: error.code,\n          toolName,\n          toolInput: errorData?.['toolInput'],\n          details: errorData?.['details'],\n        },\n        logs,\n        timedOut,\n      };\n    }\n\n    // Generic error\n    return {\n      success: false,\n      error: {\n        message: error.message,\n        name: error.name,\n        stack: error.stack,\n        code: error.code,\n      },\n      logs,\n      timedOut,\n      stats: {\n        duration: result.stats.duration,\n        toolCallCount: result.stats.toolCallCount,\n        iterationCount: result.stats.iterationCount,\n      },\n    };\n  }\n}\n"]}

package/src/codecall/services/error-enrichment.service.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Error categories for classification.
+ */
+export declare const ERROR_CATEGORIES: {
+    /** Script syntax or parsing error */
+    readonly SYNTAX: "syntax";
+    /** AST validation blocked dangerous code */
+    readonly SECURITY: "security";
+    /** Script exceeded timeout */
+    readonly TIMEOUT: "timeout";
+    /** Tool not found */
+    readonly TOOL_NOT_FOUND: "tool_not_found";
+    /** Tool access denied */
+    readonly TOOL_ACCESS_DENIED: "tool_access_denied";
+    /** Tool validation error */
+    readonly TOOL_VALIDATION: "tool_validation";
+    /** Tool execution error */
+    readonly TOOL_EXECUTION: "tool_execution";
+    /** Runtime error in script */
+    readonly RUNTIME: "runtime";
+    /** Unknown error */
+    readonly UNKNOWN: "unknown";
+};
+export type ErrorCategory = (typeof ERROR_CATEGORIES)[keyof typeof ERROR_CATEGORIES];
+/**
+ * Enriched error with actionable suggestions.
+ */
+export interface EnrichedError {
+    /** Error category */
+    category: ErrorCategory;
+    /** User-friendly error message */
+    message: string;
+    /** Actionable suggestions for fixing the error */
+    suggestions: string[];
+    /** Related documentation links */
+    docs?: string[];
+    /** Example of correct usage (if applicable) */
+    example?: string;
+    /** Original error code (if available) */
+    code?: string;
+    /** Whether the error is recoverable */
+    recoverable: boolean;
+}
+/**
+ * Error Enrichment Service
+ *
+ * Transforms raw errors into user-friendly, actionable error messages.
+ * Provides suggestions for fixing common errors and links to documentation.
+ *
+ * Security: Never exposes internal details, only provides helpful guidance.
+ */
+export declare class ErrorEnrichmentService {
+    /**
+     * Enrich an error with category, suggestions, and examples.
+     *
+     * @param error - The error to enrich (Error object, string, or unknown)
+     * @param context - Optional context for more specific suggestions
+     * @returns Enriched error with actionable information
+     */
+    enrich(error: unknown, context?: {
+        toolName?: string;
+        scriptSnippet?: string;
+    }): EnrichedError;
+    /**
+     * Enrich a tool-specific error.
+     */
+    enrichToolError(toolName: string, errorCode: string, rawMessage?: string): EnrichedError;
+    /**
+     * Create a brief error summary for logging.
+     */
+    summarize(error: unknown): string;
+    /**
+     * Extract error message from various error types.
+     */
+    private extractMessage;
+    /**
+     * Extract error code if available.
+     */
+    private extractCode;
+    /**
+     * Format error message for user consumption.
+     * Removes technical details while keeping useful information.
+     */
+    private formatMessage;
+    /**
+     * Get a human-readable prefix for error category.
+     */
+    private getCategoryPrefix;
+    /**
+     * Contextualize suggestions based on context.
+     */
+    private contextualizeSuggestions;
+}
+export default ErrorEnrichmentService;