Code execution mode for UTCP - enables executing TypeScript code chains with tool access using isolated-vm for security
npm install @utcp/code-modebash
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(
);
console.log(result);
// { city: 'London', temperature: 22, condition: 'sunny' }
`
API
$3
Creates a new client instance.
`typescript
const client = await CodeModeUtcpClient.create(
process.cwd(), // optional: root directory
null // optional: UtcpClientConfig
);
`
$3
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
}
`
$3
Returns TypeScript interface definitions for all registered tools.
`typescript
const interfaces = await client.getToolInterfaces();
console.log(interfaces);
// "interface Weather_get_current_Input { city: string; } ..."
`
$3
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(
);
`
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(
);
``