@tyvm/knowhow 0.0.108 → 0.0.109-dev.e88af1e

package/src/agents/tools/executeScript/README.md

@@ -1,94 +0,0 @@
-# Execute Script Tool
-
-The `executeScript` tool provides secure, isolated execution of TypeScript scripts with access to the Knowhow platform's tools and AI capabilities.
-
-## Requirements
-
-### Node.js Version and Configuration
-
-**Important**: For Node.js 20.x and later, the `--no-node-snapshot` flag is required due to isolated-vm compatibility requirements.
-
-```bash
-# Required for Node.js 20+
-node --no-node-snapshot your-app.js
-
-# Or set in package.json scripts
-"scripts": {
-  "start": "node --no-node-snapshot dist/index.js"
-}
-```
-
-## Features
-
-- **Secure Sandbox**: Scripts run in isolated-vm with no access to Node.js APIs
-- **Tool Integration**: Access to all existing Knowhow tools via `callTool()`
-- **AI Integration**: Direct access to AI completions via `llm()`
-- **Resource Quotas**: Configurable limits on execution time, memory, tool calls, and tokens
-- **Comprehensive Tracing**: Full audit trail of all script activities
-- **Policy Enforcement**: Fine-grained security controls and access restrictions
-
-## Usage
-
-```typescript
-// Basic usage
-await executeScript({
-  script: `
-    console.log("Hello from script!");
-    
-    const files = await callTool("fileSearch", { searchTerm: "*.ts" });
-    console.log("Found TypeScript files:", files);
-    
-    const response = await llm([
-      { role: "user", content: "What is TypeScript?" }
-    ]);
-    
-    return { message: "Script completed successfully" };
-  `
-});
-
-// With custom policy
-await executeScript({
-  script: "...",
-  policy: {
-    maxExecutionTimeMs: 10000,
-    maxMemoryMB: 64,
-    maxToolCalls: 5,
-    maxTokens: 1000,
-    allowedTools: ["fileSearch", "textSearch"],
-    deniedTools: ["execCommand"]
-  }
-});
-```
-
-## Available Functions in Scripts
-
-### `callTool(name: string, args: any): Promise<any>`
-Call any available Knowhow tool by name with arguments.
-
-### `llm(messages: ChatMessage[], options?: LLMOptions): Promise<ChatCompletion>`
-Make AI completion requests with message history and options.
-
-## Security Features
-
-- **No Node.js Access**: Scripts cannot access filesystem, network, or system APIs directly
-- **Tool Authorization**: All external access goes through existing authorization systems
-- **Resource Limits**: Prevents runaway scripts with time, memory, and usage quotas
-- **Trace Sanitization**: Sensitive data is redacted from execution logs
-- **Policy Enforcement**: Granular control over what tools and resources scripts can access
-
-## Implementation Details
-
-- **ScriptExecutor**: Handles compilation and isolated execution
-- **SandboxContext**: Provides `callTool` and `llm` function implementations
-- **ScriptTracer**: Records all script activities for debugging and audit
-- **ScriptPolicyEnforcer**: Enforces resource quotas and security policies
-
-## Files
-
-- `types.ts` - TypeScript interfaces and type definitions
-- `ScriptExecutor.ts` - Core execution engine with isolated-vm
-- `SandboxContext.ts` - Script execution context with tool/AI access
-- `ScriptTracer.ts` - Event tracing and monitoring system
-- `ScriptPolicyEnforcer.ts` - Security policy enforcement
-- `executeScript.ts` - Tool handler and main entry point
-- `examples/` - Example scripts demonstrating capabilities

package/src/agents/tools/executeScript/definition.ts

@@ -1,79 +0,0 @@
-import { Tool } from "../../../clients";
-
-/**
- * Tool for executing TypeScript scripts in a secure sandbox
- */
-export const executeScriptDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "executeScript",
-    description: `Used to contruct a script that calls tools and analyzes data, not for general purpose scripting.
-
-    This is most useful for complex workflows of tool calls that need conditional logic based off tool responses.
-
-  The script has access to:
-  - callTool(toolName, parameters): Call any available tool
-  - llm(messages, options): Make LLM calls
-  - createArtifact(name, content, type): Create downloadable artifacts
-  - console: Standard console logging
-  - getQuotaUsage(): Check resource usage
-  - sleep(ms): Pause execution for a specified time, max 2000ms
-
-  The script cannot:
-    - import or require
-    - make external network requests, outside of callTool and llm
-
-  Example:
-  \`\`\`typescript
-  // Call a tool
-  const searchResult = await callTool('textSearch', { searchTerm: 'hello world' });
-  console.log('Search found:', searchResult);
-
-  // Call LLM
-  const response = await llm([
-    { role: 'user', content: 'Explain quantum computing' }
-  ], { model: 'gpt-4o-mini', maxTokens: 100 });
-  console.log('LLM response:', response.choices[0].message.content);
-
-  // Create an artifact
-  createArtifact('summary.md', '# Summary\\nThis is a test', 'markdown');
-
-  return { message: 'Script completed successfully' };
-  \`\`\`
-
-  You must return the data you want to be the functionResp
-
-  Test tools yourself to know the return type when scripting. Can pass JSON.stringified data into llm call if you don't need to know the type.
-  You cannot use isolation breaking methods like: setTimeout setInterval setImmediate clearTimeout clearInterval
-
-  Security: Scripts run in isolation with quotas on tool calls, tokens, time, and cost.`,
-
-    parameters: {
-      type: "object",
-      properties: {
-        script: {
-          type: "string",
-          description: "The TypeScript code to execute. 4000 tokens or less",
-        },
-        maxToolCalls: {
-          type: "number",
-          description: "Maximum number of tool calls allowed (default: 50)",
-        },
-        maxTokens: {
-          type: "number",
-          description: "Maximum tokens for LLM calls (default: 10000)",
-        },
-        maxExecutionTimeMs: {
-          type: "number",
-          description:
-            "Maximum execution time in milliseconds (default: 30000)",
-        },
-        maxCostUsd: {
-          type: "number",
-          description: "Maximum cost in USD (default: 1.0)",
-        },
-      },
-      required: ["script"],
-    },
-  },
-};

package/src/agents/tools/executeScript/examples/dependency-injection-validation.ts

@@ -1,272 +0,0 @@
-#!/usr/bin/env ts-node
-/**
- * Comprehensive test for Tools Dependency Injection System
- *
- * This test validates:
- * 1. Context injection is working properly
- * 2. Tools can access services via `this.getContext()`
- * 3. Agent isolation is functioning (each agent has independent context)
- * 4. No singleton usage in tool implementations
- * 5. Backward compatibility is maintained
- *
- * Usage: npx ts-node src/agents/tools/executeScript/examples/dependency-injection-validation.ts
- */
-
-import { ToolsService } from "../../../../services/Tools";
-import { Clients } from "../../../../clients";
-import { EventService, services } from "../../../../services/";
-import { BaseAgent } from "../../../base/base";
-import { Message } from "../../../../clients/types";
-import { includedTools } from "../../list";
-import { executeScript } from "../";
-import { executeScriptDefinition } from "../definition";
-
-// Test Agent that extends BaseAgent to test agent isolation
-class TestAgent1 extends BaseAgent {
-  name = "TestAgent1";
-  description = "Test agent for dependency injection validation";
-
-  async getInitialMessages(userInput: string): Promise<Message[]> {
-    return [
-      { role: "system", content: this.description },
-      { role: "user", content: userInput },
-    ];
-  }
-
-  // Expose toolsService for testing
-  public getToolsServiceForTest() {
-    return this.tools;
-  }
-}
-
-class TestAgent2 extends BaseAgent {
-  name = "TestAgent2";
-  description = "Another test agent for dependency injection validation";
-
-  async getInitialMessages(userInput: string): Promise<Message[]> {
-    return [
-      { role: "system", content: this.description },
-      { role: "user", content: userInput },
-    ];
-  }
-
-  // Expose toolsService for testing
-  public getToolsServiceForTest() {
-    return this.tools;
-  }
-}
-
-// Test tool function that uses context injection
-function testToolWithContext(this: ToolsService, params: { message: string }) {
-  const context = this.getContext();
-
-  console.log("✅ Tool called with context:");
-  console.log("- AgentService available:", !!context.Agents);
-  console.log("- EventService available:", !!context.Events);
-  console.log("- Clients available:", !!context.Clients);
-  console.log("- ToolsService self-reference available:", !!context.Tools);
-  console.log("- Test message:", params.message);
-
-  return {
-    success: true,
-    contextValidated: true,
-    hasAgentService: !!context.Agents,
-    hasEventService: !!context.Events,
-    hasClients: !!context.Clients,
-    hasToolsService: !!context.Tools,
-    testMessage: params.message,
-  };
-}
-
-async function runValidationTests() {
-  console.log("🧪 Starting Tools Dependency Injection Validation Tests\n");
-
-  // Test 1: Create independent agents with their own ToolsService instances
-  console.log("📍 Test 1: Agent Isolation");
-  const agent1 = new TestAgent1({
-    Events: new EventService(),
-    Tools: new ToolsService({ Clients }),
-  });
-  const agent2 = new TestAgent2({
-    Events: new EventService(),
-    Tools: new ToolsService(),
-  });
-
-  const toolsService1 = agent1.getToolsServiceForTest();
-  const toolsService2 = agent2.getToolsServiceForTest();
-
-  // Verify agents have different ToolsService instances
-  console.log(
-    "✅ Agent1 and Agent2 have different ToolsService instances:",
-    toolsService1 !== toolsService2
-  );
-
-  // Test 2: Context validation for each agent
-  console.log("\n📍 Test 2: Context Injection Validation");
-
-  const context1 = toolsService1.getContext();
-  const context2 = toolsService2.getContext();
-
-  console.log("✅ Agent1 context has required services:", {
-    agentService: !!context1.Agents,
-    eventService: !!context1.Events,
-    clients: !!context1.Clients,
-    toolsService: !!context1.Tools,
-  });
-
-  console.log("✅ Agent2 context has required services:", {
-    agentService: !!context2.Agents,
-    eventService: !!context2.Events,
-    clients: !!context2.Clients,
-    toolsService: !!context2.Tools,
-  });
-
-  // Test 3: Register a test tool and verify it can access context
-  console.log("\n📍 Test 3: Tool Context Access");
-
-  // Register the test tool on agent1's ToolsService
-  toolsService1.addTool({
-    type: "function",
-    function: {
-      name: "testToolWithContext",
-      description: "Test tool for context validation",
-      parameters: {
-        type: "object",
-        properties: {
-          message: { type: "string", description: "Test message" },
-        },
-        required: ["message"],
-      },
-    },
-  });
-
-  toolsService1.setFunction("testToolWithContext", testToolWithContext);
-  try {
-    const result = await toolsService1.callTool({
-      id: "test-call",
-      type: "function",
-      function: {
-        name: "testToolWithContext",
-        arguments: JSON.stringify({ message: "Hello from Agent1!" }),
-      },
-    });
-    console.log(
-      "✅ Tool executed successfully with context access:",
-      result.functionResp?.success
-    );
-  } catch (error) {
-    console.error("❌ Tool execution failed:", error);
-  }
-
-  // Test 4: Verify agent isolation - agent2 should not have agent1's tool
-  console.log("\n📍 Test 4: Tool Isolation Between Agents");
-
-  const agent1Tools = toolsService1.getTools().map((t) => t.function.name);
-  const agent2Tools = toolsService2.getTools().map((t) => t.function.name);
-
-  console.log("Agent1 tools:", agent1Tools.length);
-  console.log("Agent2 tools:", agent2Tools.length);
-  console.log(
-    "✅ Agent2 does not have agent1's custom tool:",
-    !agent2Tools.includes("testToolWithContext")
-  );
-
-  // Test 5: Add different tool to agent2 to verify independence
-  function agent2SpecificTool(this: ToolsService, params: { data: string }) {
-    const context = this.getContext();
-    return {
-      agent: "Agent2",
-      data: params.data,
-      contextAvailable: !!context,
-    };
-  }
-
-  toolsService2.addTool({
-    type: "function",
-    function: {
-      name: "agent2SpecificTool",
-      description: "Tool specific to Agent2",
-      parameters: {
-        type: "object",
-        properties: {
-          data: { type: "string", description: "Test data" },
-        },
-        required: ["data"],
-      },
-    },
-  });
-  toolsService2.setFunction("agent2SpecificTool", agent2SpecificTool);
-
-  const agent1ToolsAfter = toolsService1.getTools().map((t) => t.function.name);
-  const agent2ToolsAfter = toolsService2.getTools().map((t) => t.function.name);
-
-  console.log(
-    "✅ Agent1 does not have agent2's tool:",
-    !agent1ToolsAfter.includes("agent2SpecificTool")
-  );
-  console.log(
-    "✅ Agent2 has its specific tool:",
-    agent2ToolsAfter.includes("agent2SpecificTool")
-  );
-
-  // Test 6: Verify executeScript tool is using context injection
-  console.log("\n📍 Test 6: executeScript Context Integration");
-
-  // Test that executeScript uses the bound context instead of singletons
-  const executeScriptTest = `
-    async function main() {
-      return callTool("testToolWithContext", {message: "Hello from executeScript!"});
-    }
-    return main()
-  `;
-
-  toolsService1.defineTools([executeScriptDefinition], { executeScript });
-
-  try {
-    const executeResult = await toolsService1.callTool({
-      id: "execute-test",
-      type: "function",
-      function: {
-        name: "executeScript",
-        arguments: JSON.stringify({ script: executeScriptTest }),
-      },
-    });
-    console.log(
-      "✅ executeScript using dependency injection:",
-      executeResult.functionResp
-    );
-  } catch (error) {
-    console.error("❌ executeScript test failed:", error);
-  }
-
-  console.log("\n🎉 All Tests Completed!");
-  console.log("\n📊 Test Summary:");
-  console.log(
-    "✅ Agent isolation working - each agent has independent ToolsService"
-  );
-  console.log(
-    "✅ Context injection working - tools can access all required services"
-  );
-  console.log("✅ No singleton usage - tools use bound context instead");
-  console.log(
-    "✅ Backward compatibility maintained - existing patterns still work"
-  );
-  console.log("✅ executeScript migrated successfully to dependency injection");
-
-  return true;
-}
-
-// Run the validation tests
-if (require.main === module) {
-  runValidationTests()
-    .then(() => {
-      console.log("\n🏆 Dependency Injection Implementation Complete!");
-      process.exit(0);
-    })
-    .catch((error) => {
-      console.error("\n❌ Validation tests failed:", error);
-      process.exit(1);
-    });
-}
-
-export { runValidationTests, TestAgent1, TestAgent2 };

package/src/agents/tools/executeScript/examples/quick-test.ts

@@ -1,74 +0,0 @@
-#!/usr/bin/env ts-node
-/**
- * Quick test for executeScript - minimal example
- * Usage: npx ts-node src/agents/tools/executeScript/examples/quick-test.ts
- */
-
-import { executeScript } from "../../executeScript";
-import { services } from "../../../../services";
-
-// Simple test script
-const simpleScript = `
-console.log("Hello from executeScript!");
-
-async function main() {
-  // Test basic functionality
-  console.log("Running simple test...");
-
-  // Try a simple tool call
-  const files = await callTool("fileSearch", { searchTerm: "*.ts" });
-  console.log("Found", files?.length || 0, "TypeScript files");
-
-  return {
-    message: "Simple test completed!",
-    filesFound: files?.length || 0,
-    timestamp: new Date().toISOString()
-  };
-}
-
-await main().then(result => {
-  console.log("Result:", result);
-}).catch(error => {
-  console.error("Error:", error);
-});
-`;
-
-async function quickTest() {
-  console.log("🧪 Quick executeScript test\n");
-
-  try {
-    const { Tools, Clients } = services();
-    const result = await executeScript({
-      script: simpleScript,
-      maxToolCalls: 5,
-      maxTokens: 100,
-      maxExecutionTimeMs: 10000,
-      maxCostUsd: 0.1,
-    });
-
-    console.log("\n📊 QUICK TEST RESULT:");
-    console.log("Success:", result.success);
-    console.log("Result:", result.result);
-    console.log("Tool calls:", result.quotaUsage.toolCalls);
-    console.log("Cost: $" + result.quotaUsage.costUsd.toFixed(4));
-
-    if (result.consoleOutput.length > 0) {
-      console.log("\n📝 Console Output:");
-      result.consoleOutput.forEach((entry) => {
-        console.log(`  ${entry}`);
-      });
-    }
-
-    if (!result.success) {
-      console.log("❌ Error:", result.error);
-    }
-  } catch (error) {
-    console.error("💥 Test failed:", error);
-  }
-}
-
-if (require.main === module) {
-  quickTest();
-}
-
-export { quickTest };