@tyvm/knowhow 0.0.108 → 0.0.109-dev.2b94ba2

package/src/services/script-execution/ScriptExecutor.ts

@@ -1,441 +0,0 @@
-import ivm from "isolated-vm";
-import { services, ToolsService } from "../../services";
-import { AIClient, Clients } from "../../clients";
-import { SandboxContext } from "./SandboxContext";
-import { ScriptTracer } from "./ScriptTracer";
-import { ScriptPolicyEnforcer } from "./ScriptPolicy";
-import {
-  ExecutionRequest,
-  ExecutionResult,
-  ResourceQuotas,
-  SecurityPolicy,
-  ExecutionTrace,
-} from "./types";
-
-/**
- * Executes TypeScript scripts in a secure sandbox environment
- */
-export class ScriptExecutor {
-  private defaultQuotas: ResourceQuotas = {
-    maxToolCalls: 50,
-    maxTokens: 10000,
-    maxExecutionTimeMs: 30000, // 30 seconds
-    maxCostUsd: 1.0,
-    maxMemoryMb: 100,
-  };
-
-  private defaultPolicy: SecurityPolicy = {
-    allowlistedTools: [], // Empty means all tools allowed
-    denylistedTools: [
-      "executeScript", // Circular script execution
-      "execCommand", // Dangerous system commands
-      "writeFileChunk", // File system write access
-      "patchFile", // File system modification
-    ],
-    maxScriptLength: 50000, // 50KB
-    allowNetworkAccess: false,
-    allowFileSystemAccess: false,
-  };
-
-  constructor(private toolsService: ToolsService, private clients: AIClient) {
-    this.validateNodejsEnvironment();
-  }
-
-  /**
-   * Validate that Node.js environment is properly configured for isolated-vm
-   */
-  private validateNodejsEnvironment(): void {
-    // Get Node.js version
-    const nodeVersion = process.version;
-    const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
-    
-    // Check if Node.js 20+ and --no-node-snapshot flag is required
-    if (majorVersion >= 20) {
-      const hasNoNodeSnapshot = process.execArgv.includes('--no-node-snapshot');
-      
-      if (!hasNoNodeSnapshot) {
-        const errorMessage = [
-          `Node.js ${nodeVersion} detected. The executeScript tool requires the --no-node-snapshot flag for isolated-vm compatibility.`,
-          '',
-          'This flag is automatically included when running knowhow commands via the CLI (e.g., `knowhow agent`, `knowhow chat`).',
-          '',
-          'If you are programmatically using knowhow or running custom scripts:',
-          '1. Start your application with: node --no-node-snapshot your-app.js',
-          '2. Or update your package.json scripts to include the flag:',
-          '   "scripts": {',
-          '     "start": "node --no-node-snapshot dist/index.js"',
-          '   }',
-          '',
-          'Note: This flag is required for Node.js 20+ to ensure isolated-vm works correctly.'
-        ].join('\n');
-        
-        throw new Error(errorMessage);
-      }
-    }
-  }
-
-  /**
-   * Execute a TypeScript script in sandbox
-   */
-  async execute(request: ExecutionRequest): Promise<ExecutionResult> {
-    const tracer = new ScriptTracer();
-    const quotas = { ...this.defaultQuotas, ...request.quotas };
-    const policy = { ...this.defaultPolicy, ...request.policy };
-    const policyEnforcer = new ScriptPolicyEnforcer(quotas, policy);
-
-    tracer.emitEvent("execution_start", {
-      scriptLength: request.script.length,
-      quotas,
-      policy: {
-        ...policy,
-        // Don't log the full tool lists
-        allowlistedTools: `${policy.allowlistedTools.length} tools`,
-        denylistedTools: `${policy.denylistedTools.length} tools`,
-      },
-    });
-
-    try {
-      // Validate script
-      const validation = policyEnforcer.validateScript(request.script, policy.allowNetworkAccess);
-      if (!validation.valid) {
-        tracer.emitEvent("script_validation_failed", {
-          issues: validation.issues,
-        });
-
-        return {
-          success: false,
-          error: `Script validation failed: ${validation.issues.join(", ")}`,
-          result: null,
-          trace: tracer.getTrace(),
-          artifacts: [],
-          consoleOutput: [],
-        };
-      }
-
-      tracer.emitEvent("script_validation_passed", {});
-
-      // Create sandbox context
-      const context = new SandboxContext(
-        this.toolsService,
-        this.clients,
-        tracer,
-        policyEnforcer
-      );
-
-      // Execute script with timeout
-      const startTime = Date.now();
-      const timeoutMs = quotas.maxExecutionTimeMs;
-
-      const result = await this.executeWithTimeout(
-        request.script,
-        context,
-        timeoutMs,
-        tracer,
-        policyEnforcer
-      );
-
-      const executionTime = Date.now() - startTime;
-      tracer.emitEvent("execution_complete", {
-        executionTimeMs: executionTime,
-        finalUsage: policyEnforcer.getUsage(),
-      });
-
-      return {
-        success: true,
-        error: null,
-        result,
-        trace: tracer.getTrace(),
-        artifacts: context.getArtifacts(),
-        consoleOutput: context.getConsoleOutput(),
-      };
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-
-      tracer.emitEvent("execution_error", {
-        error: errorMessage,
-        finalUsage: policyEnforcer.getUsage(),
-      });
-
-      return {
-        success: false,
-        error: errorMessage,
-        result: null,
-        trace: tracer.getTrace(),
-        artifacts: [],
-        consoleOutput: [],
-      };
-    }
-  }
-
-  /**
-   * Execute script with timeout protection
-   */
-  private async executeWithTimeout(
-    script: string,
-    context: SandboxContext,
-    timeoutMs: number,
-    tracer: ScriptTracer,
-    policyEnforcer: ScriptPolicyEnforcer
-  ): Promise<any> {
-    return new Promise((resolve, reject) => {
-      const timeoutId = setTimeout(() => {
-        tracer.emitEvent("execution_timeout", { timeoutMs });
-        reject(new Error(`Script execution timed out after ${timeoutMs}ms`));
-      }, timeoutMs);
-
-      // Use isolated-vm for secure execution
-      this.executeScriptSecure(script, context, tracer, policyEnforcer)
-        .then((result) => {
-          clearTimeout(timeoutId);
-          resolve(result);
-        })
-        .catch((error) => {
-          clearTimeout(timeoutId);
-          reject(error);
-        });
-    });
-  }
-
-  /**
-   * Secure script execution using isolated-vm
-   */
-  private async executeScriptSecure(
-    script: string,
-    context: SandboxContext,
-    tracer: ScriptTracer,
-    policyEnforcer: ScriptPolicyEnforcer
-  ) {
-    tracer.emitEvent("secure_execution_start", {
-      note: "Using isolated-vm for secure execution",
-    });
-
-    // Create isolated VM instance with memory limit
-    const isolate = new ivm.Isolate({
-      memoryLimit: policyEnforcer.getQuotas().maxMemoryMb,
-    });
-
-    try {
-      // Create new context within the isolate
-      const vmContext = await isolate.createContext();
-
-      tracer.emitEvent("vm_context_created", {});
-
-      // Set up the global environment in the isolated context
-      await this.setupIsolatedContext(vmContext, context, tracer);
-
-      tracer.emitEvent("script_compilation_start", {});
-
-      // Compile the script.
-      // Many scripts follow the pattern: define functions, then call `main();` at the end.
-      // The IIFE wrapper captures the *return value* of the function body, but `main();`
-      // is an expression statement — it doesn't return anything from the IIFE.
-      // We fix this by rewriting the last bare expression-statement into `return <expr>;`
-      // so that the script's return value (e.g. the object from main()) is captured.
-      const scriptWithReturn = this.injectReturnForLastExpression(script);
-
-      const wrappedScript = `
-        (async function() {
-          "use strict";
-          ${scriptWithReturn}
-        })()
-      `;
-
-      const compiledScript = await isolate.compileScript(wrappedScript);
-
-      tracer.emitEvent("script_compilation_complete", {});
-      tracer.emitEvent("script_execution_start", {});
-
-      // Execute the script and get the result
-      // Note: do NOT set timeout here — it kills the isolate while awaiting host async promises.
-      // The outer executeWithTimeout wrapper handles wall-clock timeout instead.
-      const result = await compiledScript.run(vmContext, {
-        promise: true,
-        copy: true,
-      });
-
-      tracer.emitEvent("script_execution_complete", {
-        resultType: typeof result,
-      });
-
-      return result;
-    } finally {
-      // Clean up the isolate
-      isolate.dispose();
-      tracer.emitEvent("vm_cleanup_complete", {});
-    }
-  }
-
-  /**
-   * Set up the isolated context with safe globals and sandbox functions
-   */
-  private async setupIsolatedContext(
-    vmContext: ivm.Context,
-    sandboxContext: SandboxContext,
-    tracer: ScriptTracer
-  ): Promise<void> {
-    tracer.emitEvent("context_setup_start", {});
-
-    const globalRef = vmContext.global;
-    await globalRef.set("globalThis", globalRef.derefInto());
-
-    // Helper function to expose async host functions
-    const exposeAsync = async (
-      name: string,
-      fn: (...a: any[]) => Promise<any>
-    ) => {
-      await globalRef.set(
-        `__host_${name}`,
-        new ivm.Reference(async (...args: any[]) => {
-          const result = await fn(...args);
-          const safeResult = result !== undefined ? result : null;
-          const plainResult =
-            safeResult !== null && typeof safeResult === 'object'
-              ? JSON.parse(JSON.stringify(safeResult))
-              : safeResult;
-          // copyInto() transfers the value into the isolate heap so it's directly usable
-          return new ivm.ExternalCopy(plainResult).copyInto();
-        })
-      );
-      // Use applySyncPromise so the script isolate suspends and yields the Node.js event loop
-      // back to the host while waiting for async host operations (MCP stdio calls etc.).
-      // Without this, the ivm isolate blocks the event loop and stdio-based MCP transports
-      // can never deliver their responses → deadlock.
-      await vmContext.eval(`
-        globalThis.${name} = (...a) =>
-          new Promise((resolve, reject) => {
-            try {
-              // applySyncPromise does not support result options — the Reference fn returns ExternalCopy
-              const result = __host_${name}.applySyncPromise(undefined, a,
-                { arguments: { copy: true } });
-              resolve(result);
-            } catch(e) { reject(e); }
-          });
-      `);
-    };
-
-    // Helper function to expose sync host functions
-    const exposeSync = async (name: string, fn: (...a: any[]) => any) => {
-      await globalRef.set(
-        `__host_${name}`,
-        new ivm.Reference((...args: any[]) => {
-          const result = fn(...args);
-          return new ivm.ExternalCopy(result).copyInto();
-        })
-      );
-      await vmContext.eval(`
-        globalThis.${name} = (...a) =>
-          __host_${name}.apply(undefined, a,
-            { arguments: { copy: true }, result: { copy: true } });
-      `);
-    };
-
-    // Expose async sandbox functions
-    await exposeAsync("callTool", async (tool, params) => {
-      try {
-        const result = await sandboxContext.callTool(tool as string, params);
-        const { functionResp } = result;
-        return functionResp !== undefined ? functionResp : null;
-      } catch (err) {
-        throw err;
-      }
-    });
-    await exposeAsync("llm", (messages, options) =>
-      sandboxContext.llm(messages, options || {})
-    );
-    await exposeAsync("sleep", (ms) => sandboxContext.sleep(ms));
-
-    // Expose sync sandbox functions
-    await exposeSync("createArtifact", (name, content, type) =>
-      sandboxContext.createArtifact(name as string, content, type)
-    );
-    await exposeSync("getQuotaUsage", () => sandboxContext.getQuotaUsage());
-
-    // Set up console bridging with individual function references
-    for (const level of ["log", "info", "warn", "error"] as const) {
-      await globalRef.set(
-        `__console_${level}`,
-        new ivm.Reference((...args: any[]) =>
-          sandboxContext.console[level](...args)
-        )
-      );
-    }
-    await vmContext.eval(`
-      globalThis.console = {};
-      for (const lvl of ["log", "info", "warn", "error"]) {
-        globalThis.console[lvl] = (...a) =>
-          globalThis["__console_" + lvl].apply(undefined, a,
-            { arguments: { copy: true } });
-      }
-    `);
-
-    tracer.emitEvent("context_setup_complete", {});
-  }
-
-  /**
-   * Legacy fallback execution method
-   */
-  private async executeScriptFallback(
-    script: string,
-    context: SandboxContext,
-    tracer: ScriptTracer,
-    policyEnforcer: ScriptPolicyEnforcer
-  ): Promise<any> {
-    // This is a fallback method that could use vm2 or other sandboxing
-    throw new Error("Isolated-vm execution failed, no fallback available");
-  }
-
-  /**
-   * Get default quotas
-   */
-  getDefaultQuotas(): ResourceQuotas {
-    return { ...this.defaultQuotas };
-  }
-
-  /**
-   * Get default policy
-   */
-  getDefaultPolicy(): SecurityPolicy {
-    return { ...this.defaultPolicy };
-  }
-
-
-  /**
-   * Rewrite the last bare expression-statement in a script to use `return` so
-   * that the value propagates out of the IIFE wrapper.
-   *
-   * For example:
-   *   main();        →  return main();
-   *   main()         →  return main()
-   *   someExpr;      →  return someExpr;
-   *
-   * We only transform the last non-empty, non-comment line that looks like a
-   * plain expression statement (i.e. does NOT start with keywords that aren't
-   * valid in expression position: `function`, `class`, `const`, `let`, `var`,
-   * `if`, `for`, `while`, `do`, `switch`, `try`, `return`, `throw`, `break`,
-   * `continue`, `import`, `export`, `{`).
-   */
-  private injectReturnForLastExpression(script: string): string {
-    const lines = script.split('\n');
-
-    // Walk backwards to find the last non-empty, non-comment line
-    for (let i = lines.length - 1; i >= 0; i--) {
-      const trimmed = lines[i].trim();
-      if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) {
-        continue;
-      }
-
-      // Skip lines that start with statement keywords — these can't be returned
-      const statementKeywords = /^(function\s|class\s|const\s|let\s|var\s|if\s*[(]|for\s*[(]|while\s*[(]|do\s*[{]|switch\s*[(]|try\s*[{]|return\s|throw\s|break;|continue;|import\s|export\s|[{])/;
-      if (statementKeywords.test(trimmed)) {
-        break; // last meaningful line is a statement — don't touch it
-      }
-
-      // It looks like an expression statement — prepend `return`
-      lines[i] = lines[i].replace(trimmed, `return ${trimmed}`);
-      return lines.join('\n');
-    }
-
-    // No suitable last expression found — return script unchanged
-    return script;
-  }}

package/src/services/script-execution/ScriptPolicy.ts

@@ -1,194 +0,0 @@
-import {
-  ResourceQuotas,
-  SecurityPolicy,
-  QuotaUsage,
-  PolicyViolation
-} from './types';
-
-/**
- * Enforces security policies and resource quotas for script execution
- */
-export class ScriptPolicyEnforcer {
-  private usage: QuotaUsage;
-  private violations: PolicyViolation[] = [];
-  private complexityLimit: number = 150; // Arbitrary limit for script complexity
-
-  constructor(
-    private quotas: ResourceQuotas,
-    private policy: SecurityPolicy,
-  ) {
-    this.usage = {
-      toolCalls: 0,
-      tokens: 0,
-      executionTimeMs: 0,
-      costUsd: 0
-    };
-  }
-
-  /**
-   * Check if a tool call is allowed
-   */
-  checkToolCall(toolName: string): boolean {
-    // Check if tool is in denylist
-    if (this.policy.denylistedTools && this.policy.denylistedTools.includes(toolName)) {
-      this.recordViolation('tool_denied', `Tool '${toolName}' is in denylist`);
-      return false;
-    }
-
-    // Check if tool is in allowlist (if allowlist is defined and not empty)
-    if (this.policy.allowlistedTools && this.policy.allowlistedTools.length > 0 &&
-        !this.policy.allowlistedTools.includes(toolName)) {
-      this.recordViolation('tool_not_allowed', `Tool '${toolName}' is not in allowlist`);
-      return false;
-    }
-
-    // Check quota
-    if (this.usage.toolCalls >= this.quotas.maxToolCalls) {
-      this.recordViolation('quota_exceeded', 'Maximum tool calls exceeded');
-      return false;
-    }
-
-    return true;
-  }
-
-  /**
-   * Record a tool call
-   */
-  recordToolCall(): void {
-    this.usage.toolCalls++;
-  }
-
-  /**
-   * Check if token usage is allowed
-   */
-  checkTokenUsage(tokens: number): boolean {
-    if (this.usage.tokens + tokens > this.quotas.maxTokens) {
-      this.recordViolation('quota_exceeded', 'Maximum tokens would be exceeded');
-      return false;
-    }
-    return true;
-  }
-
-  /**
-   * Record token usage
-   */
-  recordTokenUsage(tokens: number): void {
-    this.usage.tokens += tokens;
-  }
-
-  /**
-   * Check if execution time limit is exceeded
-   */
-  checkExecutionTime(currentTimeMs: number): boolean {
-    if (currentTimeMs > this.quotas.maxExecutionTimeMs) {
-      this.recordViolation('quota_exceeded', 'Maximum execution time exceeded');
-      return false;
-    }
-    this.usage.executionTimeMs = currentTimeMs;
-    return true;
-  }
-
-  /**
-   * Check if cost limit is exceeded
-   */
-  checkCost(additionalCost: number): boolean {
-    if (this.usage.costUsd + additionalCost > this.quotas.maxCostUsd) {
-      this.recordViolation('quota_exceeded', 'Maximum cost would be exceeded');
-      return false;
-    }
-    return true;
-  }
-
-  /**
-   * Record cost usage
-   */
-  recordCost(cost: number): void {
-    this.usage.costUsd += cost;
-  }
-
-  /**
-   * Get current usage
-   */
-  getUsage(): QuotaUsage {
-    return { ...this.usage };
-  }
-
-  /**
-   * Get current quotas
-   */
-  getQuotas(): ResourceQuotas {
-    return { ...this.quotas };
-  }
-
-  /**
-   * Get all policy violations
-   */
-  getViolations(): PolicyViolation[] {
-    return [...this.violations];
-  }
-
-  /**
-   * Check if there are any violations
-   */
-  hasViolations(): boolean {
-    return this.violations.length > 0;
-  }
-
-  /**
-   * Get the most recent violation
-   */
-  getLastViolation(): PolicyViolation | undefined {
-    return this.violations[this.violations.length - 1];
-  }
-
-  /**
-   * Reset usage counters
-   */
-  resetUsage(): void {
-    this.usage = {
-      toolCalls: 0,
-      tokens: 0,
-      executionTimeMs: 0,
-      costUsd: 0
-    };
-  }
-
-  /**
-   * Reset violations
-   */
-  resetViolations(): void {
-    this.violations = [];
-  }
-
-  /**
-   * Validate script content for security issues
-   */
-  validateScript(scriptContent: string, allowNetworkAccess?: boolean): { valid: boolean; issues: string[] } {
-    const issues: string[] = [];
-
-    // Check script length
-    if (scriptContent.length > this.policy.maxScriptLength) {
-      issues.push(`Script too long: ${scriptContent.length} > ${this.policy.maxScriptLength}`);
-    }
-
-    return {
-      valid: issues.length === 0,
-      issues
-    };
-  }
-
-  /**
-   * Record a policy violation
-   */
-  private recordViolation(type: 'quota_exceeded' | 'tool_denied' | 'tool_not_allowed' | 'script_validation', message: string): void {
-    const violation: PolicyViolation = {
-      id: `violation-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
-      type,
-      message,
-      timestamp: Date.now(),
-      usage: { ...this.usage }
-    };
-
-    this.violations.push(violation);
-  }
-}