@utcp/code-mode - npm Package Compare versions

Comparing version 1.2.8 to 1.2.9

README.md

+# @utcp/code-mode
+
+Execute TypeScript code with direct access to UTCP tools using isolated-vm for secure sandboxed execution.
+
+## Installation
+
+```bash
+npm install @utcp/code-mode @utcp/sdk @utcp/direct-call isolated-vm
+```
+
+## Quick Start
+
+```typescript
+import { CodeModeUtcpClient } from '@utcp/code-mode';
+import { addFunctionToUtcpDirectCall } from '@utcp/direct-call';
+
+// Register a function that returns a UTCP manual
+addFunctionToUtcpDirectCall('getWeatherManual', async () => ({
+  utcp_version: '0.2.0',
+  tools: [{
+    name: 'get_current',
+    description: 'Get current weather for a city',
+    inputs: {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city']
+    },
+    tool_call_template: {
+      call_template_type: 'direct-call',
+      callable_name: 'getWeather'
+    }
+  }]
+}));
+
+// Register the actual tool implementation
+addFunctionToUtcpDirectCall('getWeather', async (city: string) => ({
+  city,
+  temperature: 22,
+  condition: 'sunny'
+}));
+
+// Create client and register manual
+const client = await CodeModeUtcpClient.create();
+await client.registerManual({
+  name: 'weather',
+  call_template_type: 'direct-call',
+  callable_name: 'getWeatherManual'
+});
+
+// Execute code with tool access
+const { result, logs } = await client.callToolChain(`
+  const data = weather.get_current({ city: 'London' });
+  console.log('Weather:', data);
+  return data;
+`);
+
+console.log(result);
+// { city: 'London', temperature: 22, condition: 'sunny' }
+```
+
+## API
+
+### `CodeModeUtcpClient.create(root_dir?, config?)`
+
+Creates a new client instance.
+
+```typescript
+const client = await CodeModeUtcpClient.create(
+  process.cwd(),  // optional: root directory
+  null            // optional: UtcpClientConfig
+);
+```
+
+### `client.callToolChain(code, options?)`
+
+Executes TypeScript code with tool access.
+
+```typescript
+const result = await client.callToolChain(code, {
+  timeout: 30000,     // execution timeout in ms (default: 30000)
+  memoryLimit: 128    // memory limit in MB (default: 128)
+});
+```
+
+**Returns:**
+```typescript
+{
+  result: any;           // return value from code
+  consoleOutput: string[]; // captured console.log/error output
+}
+```
+
+### `client.getToolInterfaces()`
+
+Returns TypeScript interface definitions for all registered tools.
+
+```typescript
+const interfaces = await client.getToolInterfaces();
+console.log(interfaces);
+// "interface Weather_get_current_Input { city: string; } ..."
+```
+
+### `CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE`
+
+Static prompt template for AI agents explaining how to use code-mode.
+
+```typescript
+const systemPrompt = CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE;
+```
+
+## Tool Access Patterns
+
+Tools are accessed using their namespace:
+
+```typescript
+// Namespaced tools (from manuals)
+manual_name.tool_name({ param: value })
+
+// Examples
+weather.get_current({ city: 'Tokyo' })
+procurement.search_parts({ mpn: 'ABC123' })
+```
+
+## Runtime Context
+
+Inside `callToolChain`, you have access to:
+
+| Variable | Description |
+|----------|-------------|
+| `__interfaces` | String with all TypeScript interface definitions |
+| `__getToolInterface(name)` | Get interface for specific tool |
+| `__availableTools` | Array of available tool access patterns |
+| `console.log/error/warn` | Captured and returned in `consoleOutput` |
+| Standard JS globals | `JSON`, `Math`, `Date`, `Array`, etc. |
+
+## Example: Chaining Tools
+
+```typescript
+const result = await client.callToolChain(`
+  // Get parts from supplier
+  const parts = procurement.search_parts({ mpn: 'LM358' });
+  
+  // Get pricing for each part
+  const pricing = parts.map(part => 
+    procurement.get_pricing({ part_id: part.id })
+  );
+  
+  // Return combined result
+  return { parts, pricing };
+`);
+```
+
+## Using Text Templates
+
+For loading tools from UTCP manual files:
+
+```typescript
+import { CodeModeUtcpClient } from '@utcp/code-mode';
+import '@utcp/text'; // Enables text call template support
+
+const client = await CodeModeUtcpClient.create();
+
+// Register from a UTCP manual file
+await client.registerManual({
+  name: 'myapi',
+  call_template_type: 'text',
+  file_path: './my-api-manual.utcp.json'
+});
+
+// Use tools defined in the manual
+const result = await client.callToolChain(`
+  return myapi.some_tool({ param: 'value' });
+`);
+```
+
+## Security
+
+Code execution uses [isolated-vm](https://github.com/laverdet/isolated-vm) for sandboxing:
+
+- Isolated V8 context (no access to Node.js APIs)
+- Memory limits enforced
+- Execution timeouts
+- No file system or network access from sandbox
+
+## License
+
+MPL-2.0

package.json

 {
   "name": "@utcp/code-mode",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "Code execution mode for UTCP - enables executing TypeScript code chains with tool access using isolated-vm for security",
@@ -35,3 +35,4 @@ "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
@@ -38,0 +39,0 @@ "exports": {

New alerts

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

118775

4.17%

Number of package files

8

14.29%

Number of medium quality alerts

0

-100%

Number of lines in readme file

188

Infinity%

No dependency changes