@utcp/code-mode

Execute TypeScript code with direct access to UTCP tools using isolated-vm for secure sandboxed execution.

Installation

npm install @utcp/code-mode @utcp/sdk @utcp/direct-call isolated-vm

Quick Start

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.

const client = await CodeModeUtcpClient.create(
  process.cwd(),  // optional: root directory
  null            // optional: UtcpClientConfig
);

client.callToolChain(code, options?)

Executes TypeScript code with tool access.

const result = await client.callToolChain(code, {
  timeout: 30000,     // execution timeout in ms (default: 30000)
  memoryLimit: 128    // memory limit in MB (default: 128)
});

Returns:

{
  result: any;           // return value from code
  consoleOutput: string[]; // captured console.log/error output
}

client.getToolInterfaces()

Returns TypeScript interface definitions for all registered tools.

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.

const systemPrompt = CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE;

Tool Access Patterns

Tools are accessed using their namespace:

// 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

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:

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 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