code-mode-core 2.0.0

package/src/engine.ts

@@ -0,0 +1,211 @@
+/**
+ * @code-mode/core — CodeModeEngine
+ *
+ * Platform-agnostic engine for executing TypeScript code with tool access
+ * in a secure isolated-vm sandbox.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { UtcpClient } from '@utcp/sdk';
+import type {
+  ExecutionOptions,
+  ExecutionResult,
+  ToolSourceConfig,
+  RegisterResult,
+  ToolCallRecord,
+  ExecutionStats,
+} from './types';
+import {
+  toolToTypeScriptInterface,
+  clearInterfaceCache,
+} from './schema-to-ts';
+import type { ToolLike } from './schema-to-ts';
+import { executeInSandbox } from './sandbox';
+import {
+  computeToolsHash,
+  getCachedSetup,
+  setCachedSetup,
+  clearSetupCache,
+} from './cache';
+import type { CachedSetup } from './cache';
+
+const DEFAULT_OPTIONS: ExecutionOptions = {
+  timeout: 30000,
+  memoryLimit: 128,
+  enableTrace: false,
+};
+
+export class CodeModeEngine {
+  private client: UtcpClient;
+  private toolsHash: string = '';
+
+  private constructor(client: UtcpClient) {
+    this.client = client;
+  }
+
+  /** Create a new CodeModeEngine instance. */
+  static async create(): Promise<CodeModeEngine> {
+    const client = await UtcpClient.create();
+    return new CodeModeEngine(client);
+  }
+
+  /** Register a tool source (MCP server, HTTP API, etc.). */
+  async registerToolSource(config: ToolSourceConfig): Promise<RegisterResult> {
+    // Always invalidate cache — tool state may have changed regardless of outcome
+    this.toolsHash = '';
+    try {
+      const result = await this.client.registerManual(config as any);
+      if (result.success) {
+        const toolNames = (result.manual?.tools ?? []).map((t: any) => t.name ?? 'unknown');
+        return { success: true, toolNames };
+      }
+      return {
+        success: false,
+        toolNames: [],
+        errors: result.errors ?? ['Registration failed'],
+      };
+    } catch (err) {
+      return {
+        success: false,
+        toolNames: [],
+        errors: [err instanceof Error ? err.message : String(err)],
+      };
+    }
+  }
+
+  /** Execute code in the sandbox with registered tools. */
+  async execute(
+    code: string,
+    options?: Partial<ExecutionOptions>,
+  ): Promise<ExecutionResult> {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const tools = await this.getToolsAsToolLike();
+
+    // Get or compute cached setup
+    const setup = await this.getOrComputeSetup(tools);
+
+    // Build callToolFn — optionally with tracing
+    const trace: ToolCallRecord[] = [];
+    const callToolFn = opts.enableTrace
+      ? this.createTracedCallTool(trace)
+      : this.createCallTool();
+
+    const sandboxResult = await executeInSandbox(
+      code,
+      tools,
+      callToolFn,
+      setup.interfacesString,
+      setup.interfaceMap,
+      { timeout: opts.timeout, memoryLimit: opts.memoryLimit },
+    );
+
+    const executionResult: ExecutionResult = {
+      result: sandboxResult.result,
+      logs: sandboxResult.logs,
+      ...(sandboxResult.error ? { error: sandboxResult.error } : {}),
+    };
+
+    if (opts.enableTrace) {
+      executionResult.trace = trace;
+      executionResult.stats = this.computeStats(trace);
+    }
+
+    return executionResult;
+  }
+
+  /** Get tool descriptions for LLM prompt generation. */
+  async getToolDescription(): Promise<string> {
+    const tools = await this.getToolsAsToolLike();
+    const setup = await this.getOrComputeSetup(tools);
+    return setup.toolDescription;
+  }
+
+  /** Clean up resources including the underlying UTCP client and MCP transports. */
+  async close(): Promise<void> {
+    this.toolsHash = '';
+    clearInterfaceCache();
+    clearSetupCache();
+    await this.client.close();
+  }
+
+  private async getToolsAsToolLike(): Promise<ToolLike[]> {
+    const tools = await this.client.getTools();
+    return tools.map((t: any) => ({
+      name: t.name,
+      description: t.description,
+      inputs: t.inputs,
+      outputs: t.outputs,
+      tags: t.tags ?? [],
+    }));
+  }
+
+  private async getOrComputeSetup(tools: ToolLike[]): Promise<CachedSetup> {
+    const hash = computeToolsHash(tools);
+
+    if (hash === this.toolsHash) {
+      const cached = getCachedSetup(hash);
+      if (cached) return cached;
+    }
+
+    // Compute fresh — build interfaceMap in one pass, then join for interfacesString
+    clearInterfaceCache();
+    const interfaceMap: Record<string, string> = {};
+    for (const tool of tools) {
+      interfaceMap[tool.name] = toolToTypeScriptInterface(tool);
+    }
+    const interfacesString = `// Auto-generated TypeScript interfaces for UTCP tools\n${Object.values(interfaceMap).join('\n\n')}`;
+
+    const toolDescription = [
+      'Execute a TypeScript code block with access to registered UTCP tools.',
+      'The code runs in an isolated sandbox. Tools are called as synchronous functions: manual.tool({ param: value }).',
+      'Use `return` to return the final result.',
+      '',
+      'Available tool interfaces:',
+      interfacesString || '(no tools registered — configure tool sources on the node)',
+    ].join('\n');
+
+    const setup: CachedSetup = { interfacesString, interfaceMap, toolDescription };
+    setCachedSetup(hash, setup);
+    this.toolsHash = hash;
+
+    return setup;
+  }
+
+  private createCallTool(): (toolName: string, args: Record<string, unknown>) => Promise<unknown> {
+    return async (toolName: string, args: Record<string, unknown>) => {
+      return this.client.callTool(toolName, args);
+    };
+  }
+
+  private createTracedCallTool(
+    trace: ToolCallRecord[],
+  ): (toolName: string, args: Record<string, unknown>) => Promise<unknown> {
+    return async (toolName: string, args: Record<string, unknown>) => {
+      const start = performance.now();
+      try {
+        const result = await this.client.callTool(toolName, args);
+        trace.push({ toolName, args, result, durationMs: performance.now() - start });
+        return result;
+      } catch (err) {
+        trace.push({
+          toolName,
+          args,
+          error: err instanceof Error ? err.message : String(err),
+          durationMs: performance.now() - start,
+        });
+        throw err;
+      }
+    };
+  }
+
+  private computeStats(trace: ToolCallRecord[]): ExecutionStats {
+    return {
+      totalCalls: trace.length,
+      totalDurationMs: trace.reduce((sum, r) => sum + r.durationMs, 0),
+      failures: trace.filter(r => r.error !== undefined).length,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @code-mode/core — Public API
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+export { CodeModeEngine } from './engine';
+
+export type {
+  ExecutionOptions,
+  ExecutionResult,
+  ToolDefinition,
+  ToolCallRecord,
+  ExecutionStats,
+  ToolSourceConfig,
+  RegisterResult,
+  JsonSchemaLike,
+} from './types';

package/src/sandbox.ts

@@ -0,0 +1,85 @@
+/**
+ * @code-mode/core — SandboxManager
+ *
+ * Only file that imports isolated-vm. Contains isolate creation and
+ * code execution within the sandbox.
+ *
+ * Adapted from @utcp/code-mode (CodeModeUtcpClient) by UTCP Contributors.
+ * Original: https://github.com/universal-tool-calling-protocol/code-mode
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import type { ToolLike } from './schema-to-ts';
+import { setupConsoleBridge, setupToolBridges, setupUtilities } from './bridges';
+import type { CallToolFn } from './bridges';
+
+/** Create an isolated-vm isolate with the given memory limit. */
+export async function createIsolate(memoryLimit: number) {
+  const ivm = await import('isolated-vm');
+  const isolate = new ivm.default.Isolate({ memoryLimit });
+  return { isolate, ivm: ivm.default };
+}
+
+export interface SandboxExecuteOptions {
+  timeout: number;
+  memoryLimit: number;
+}
+
+/**
+ * Execute code in an isolated sandbox with tool access.
+ *
+ * Sets up console bridges, tool bridges, and utilities, then runs the
+ * user code. Returns the result and captured logs.
+ */
+export async function executeInSandbox(
+  code: string,
+  tools: ToolLike[],
+  callToolFn: CallToolFn,
+  interfacesString: string,
+  interfaceMap: Record<string, string>,
+  options: SandboxExecuteOptions,
+): Promise<{ result: unknown; logs: string[]; error?: string }> {
+  const { isolate, ivm: ivm_module } = await createIsolate(options.memoryLimit);
+  const logs: string[] = [];
+
+  try {
+    const context = await isolate.createContext();
+    const jail = context.global;
+
+    await jail.set('global', jail.derefInto());
+
+    await setupConsoleBridge(isolate, context, jail, logs, ivm_module);
+    await setupToolBridges(isolate, context, jail, tools, callToolFn, ivm_module);
+    await setupUtilities(isolate, context, jail, tools, interfacesString, interfaceMap);
+
+    const wrappedCode = `
+      (function() {
+        var __result = (function() {
+          ${code}
+        })();
+        return JSON.stringify({ __result: __result });
+      })()
+    `;
+
+    const script = await isolate.compileScript(wrappedCode);
+    const resultJson = await script.run(context, { timeout: options.timeout });
+
+    const result = typeof resultJson === 'string'
+      ? JSON.parse(resultJson).__result
+      : resultJson;
+
+    return { result, logs };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      result: null,
+      logs: [...logs, `[ERROR] Code execution failed: ${errorMessage}`],
+      error: errorMessage,
+    };
+  } finally {
+    isolate.dispose();
+  }
+}

package/src/schema-to-ts.ts

@@ -0,0 +1,262 @@
+/**
+ * @code-mode/core — JSON Schema to TypeScript converter
+ *
+ * Adapted from @utcp/code-mode (CodeModeUtcpClient) by UTCP Contributors.
+ * Original: https://github.com/universal-tool-calling-protocol/code-mode
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import type { JsonSchemaLike } from './types';
+
+/** Tool-like shape expected by the converter. */
+export interface ToolLike {
+  name: string;
+  description: string;
+  inputs: JsonSchemaLike;
+  outputs: JsonSchemaLike;
+  tags: string[];
+}
+
+const MAX_CACHE_SIZE = 16;
+const interfaceCache = new Map<string, string>();
+
+// Names that would pollute the global/prototype chain if set on `global`
+const RESERVED_NAMES = new Set([
+  '__proto__', 'constructor', 'prototype', 'toString', 'valueOf',
+  'hasOwnProperty', '__defineGetter__', '__defineSetter__',
+  '__lookupGetter__', '__lookupSetter__', 'global',
+]);
+
+/** Sanitize a name to be a valid, safe TypeScript identifier. */
+export function sanitizeIdentifier(name: string): string {
+  const id = name
+    .replace(/[^a-zA-Z0-9_]/g, '_')
+    .replace(/^[0-9]/, '_$&');
+  return RESERVED_NAMES.has(id) ? `_${id}` : id;
+}
+
+/** Escape text for safe use in JSDoc comments. */
+export function escapeComment(text: string): string {
+  return text.replace(/\*\//g, '*\\/').replace(/\n/g, ' ');
+}
+
+/** Map a JSON Schema type string to a TypeScript type. */
+function mapJsonTypeToTS(type: string): string {
+  switch (type) {
+    case 'string': return 'string';
+    case 'number':
+    case 'integer': return 'number';
+    case 'boolean': return 'boolean';
+    case 'null': return 'null';
+    case 'object': return 'object';
+    case 'array': return 'any[]';
+    default: return 'any';
+  }
+}
+
+/** Convert a JSON Schema to an inline TypeScript type string. */
+export function jsonSchemaToTypeScriptType(schema: JsonSchemaLike): string {
+  if (!schema || typeof schema !== 'object') {
+    return 'any';
+  }
+
+  if (schema.enum) {
+    return schema.enum.map(val =>
+      typeof val === 'string' ? JSON.stringify(val) : String(val)
+    ).join(' | ');
+  }
+
+  switch (schema.type) {
+    case 'object':
+      if (!schema.properties) return '{ [key: string]: any }';
+      const props = Object.entries(schema.properties).map(([key, propSchema]) => {
+        const isRequired = schema.required?.includes(key) ?? false;
+        const optional = isRequired ? '' : '?';
+        const propType = jsonSchemaToTypeScriptType(propSchema);
+        return `${key}${optional}: ${propType}`;
+      }).join('; ');
+      return `{ ${props} }`;
+
+    case 'array':
+      if (!schema.items) return 'any[]';
+      const itemType = Array.isArray(schema.items)
+        ? schema.items.map(item => jsonSchemaToTypeScriptType(item)).join(' | ')
+        : jsonSchemaToTypeScriptType(schema.items);
+      return `(${itemType})[]`;
+
+    case 'string': return 'string';
+    case 'number':
+    case 'integer': return 'number';
+    case 'boolean': return 'boolean';
+    case 'null': return 'null';
+
+    default:
+      if (Array.isArray(schema.type)) {
+        return schema.type.map(t => mapJsonTypeToTS(t)).join(' | ');
+      }
+      return 'any';
+  }
+}
+
+/** Convert a JSON Schema to TypeScript object content (properties only). */
+function jsonSchemaToObjectContent(schema: JsonSchemaLike): string {
+  if (!schema || typeof schema !== 'object' || schema.type !== 'object') {
+    return '    [key: string]: any;';
+  }
+
+  const properties = schema.properties || {};
+  const required = schema.required || [];
+  const lines: string[] = [];
+
+  for (const [propName, propSchema] of Object.entries(properties)) {
+    const isRequired = required.includes(propName);
+    const optionalMarker = isRequired ? '' : '?';
+    const description = propSchema.description || '';
+    const tsType = jsonSchemaToTypeScriptType(propSchema);
+
+    if (description) {
+      lines.push(`    /** ${escapeComment(description)} */`);
+    }
+    lines.push(`    ${propName}${optionalMarker}: ${tsType};`);
+  }
+
+  return lines.length > 0 ? lines.join('\n') : '    [key: string]: any;';
+}
+
+/** Convert a JSON Schema to a full TypeScript type definition. */
+function jsonSchemaToTypeScript(schema: JsonSchemaLike, typeName: string): string {
+  if (!schema || typeof schema !== 'object') {
+    return `type ${typeName} = any;`;
+  }
+
+  switch (schema.type) {
+    case 'object':
+      return objectSchemaToTypeScript(schema, typeName);
+    case 'array':
+      return arraySchemaToTypeScript(schema, typeName);
+    case 'string':
+      return primitiveSchemaToTypeScript(schema, typeName, 'string');
+    case 'number':
+    case 'integer':
+      return primitiveSchemaToTypeScript(schema, typeName, 'number');
+    case 'boolean':
+      return primitiveSchemaToTypeScript(schema, typeName, 'boolean');
+    case 'null':
+      return `type ${typeName} = null;`;
+    default:
+      if (Array.isArray(schema.type)) {
+        const types = schema.type.map(t => mapJsonTypeToTS(t)).join(' | ');
+        return `type ${typeName} = ${types};`;
+      }
+      return `type ${typeName} = any;`;
+  }
+}
+
+function objectSchemaToTypeScript(schema: JsonSchemaLike, typeName: string): string {
+  if (!schema.properties) {
+    return `interface ${typeName} {\n  [key: string]: any;\n}`;
+  }
+
+  const properties = Object.entries(schema.properties).map(([key, propSchema]) => {
+    const isRequired = schema.required?.includes(key) ?? false;
+    const optional = isRequired ? '' : '?';
+    const propType = jsonSchemaToTypeScriptType(propSchema);
+    const description = propSchema.description ? `  /** ${escapeComment(propSchema.description)} */\n` : '';
+
+    return `${description}  ${key}${optional}: ${propType};`;
+  }).join('\n');
+
+  return `interface ${typeName} {\n${properties}\n}`;
+}
+
+function arraySchemaToTypeScript(schema: JsonSchemaLike, typeName: string): string {
+  if (!schema.items) {
+    return `type ${typeName} = any[];`;
+  }
+
+  const itemType = Array.isArray(schema.items)
+    ? schema.items.map(item => jsonSchemaToTypeScriptType(item)).join(' | ')
+    : jsonSchemaToTypeScriptType(schema.items);
+
+  return `type ${typeName} = (${itemType})[];`;
+}
+
+function primitiveSchemaToTypeScript(schema: JsonSchemaLike, typeName: string, baseType: string): string {
+  if (schema.enum) {
+    const enumValues = schema.enum.map(val =>
+      typeof val === 'string' ? JSON.stringify(val) : String(val)
+    ).join(' | ');
+    return `type ${typeName} = ${enumValues};`;
+  }
+
+  return `type ${typeName} = ${baseType};`;
+}
+
+/** Convert a Tool to its TypeScript interface string (cached). */
+export function toolToTypeScriptInterface(tool: ToolLike): string {
+  if (interfaceCache.has(tool.name)) {
+    return interfaceCache.get(tool.name)!;
+  }
+
+  let interfaceContent: string;
+  let accessPattern: string;
+
+  if (tool.name.includes('.')) {
+    const [manualName, ...toolParts] = tool.name.split('.');
+    const sanitizedManualName = sanitizeIdentifier(manualName);
+    const toolName = toolParts.map(part => sanitizeIdentifier(part)).join('_');
+    accessPattern = `${sanitizedManualName}.${toolName}`;
+
+    const inputInterfaceContent = jsonSchemaToObjectContent(tool.inputs);
+    const outputInterfaceContent = jsonSchemaToObjectContent(tool.outputs);
+
+    interfaceContent = `
+namespace ${sanitizedManualName} {
+  interface ${toolName}Input {
+${inputInterfaceContent}
+  }
+
+  interface ${toolName}Output {
+${outputInterfaceContent}
+  }
+}`;
+  } else {
+    const sanitizedToolName = sanitizeIdentifier(tool.name);
+    accessPattern = sanitizedToolName;
+    const inputType = jsonSchemaToTypeScript(tool.inputs, `${sanitizedToolName}Input`);
+    const outputType = jsonSchemaToTypeScript(tool.outputs, `${sanitizedToolName}Output`);
+    interfaceContent = `${inputType}\n\n${outputType}`;
+  }
+
+  const interfaceString = `
+${interfaceContent}
+
+/**
+ * ${escapeComment(tool.description)}
+ * Tags: ${escapeComment(tool.tags.join(', '))}
+ * Access as: ${accessPattern}(args)
+ */`;
+
+  if (!interfaceCache.has(tool.name) && interfaceCache.size >= MAX_CACHE_SIZE) {
+    const oldestKey = interfaceCache.keys().next().value;
+    if (oldestKey !== undefined) interfaceCache.delete(oldestKey);
+  }
+  interfaceCache.set(tool.name, interfaceString);
+  return interfaceString;
+}
+
+/** Generate TypeScript interfaces for all tools. */
+export function getAllToolsTypeScriptInterfaces(tools: ToolLike[]): string {
+  const interfaces = tools.map(tool => toolToTypeScriptInterface(tool));
+
+  return `// Auto-generated TypeScript interfaces for UTCP tools
+${interfaces.join('\n\n')}`;
+}
+
+/** Clear the interface cache (e.g., when tools change). */
+export function clearInterfaceCache(): void {
+  interfaceCache.clear();
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+/**
+ * @code-mode/core — Type definitions
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/** Minimal JSON Schema subset used for tool input/output definitions. */
+export interface JsonSchemaLike {
+  type?: string | string[];
+  properties?: Record<string, JsonSchemaLike>;
+  required?: string[];
+  items?: JsonSchemaLike | JsonSchemaLike[];
+  enum?: unknown[];
+  description?: string;
+}
+
+/** A tool registered with the engine. */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: JsonSchemaLike;
+  outputSchema: JsonSchemaLike;
+  tags: string[];
+}
+
+/** Options for code execution. */
+export interface ExecutionOptions {
+  /** Timeout in milliseconds. Default: 30000 */
+  timeout: number;
+  /** Memory limit in MB for the isolate. Default: 128 */
+  memoryLimit: number;
+  /** Enable execution tracing (tool call timing). Default: false */
+  enableTrace: boolean;
+}
+
+/** A single tool call recorded during traced execution. */
+export interface ToolCallRecord {
+  toolName: string;
+  args: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+  durationMs: number;
+}
+
+/** Aggregate execution statistics. */
+export interface ExecutionStats {
+  totalCalls: number;
+  totalDurationMs: number;
+  failures: number;
+}
+
+/** Result of executing code in the sandbox. */
+export interface ExecutionResult {
+  result: unknown;
+  logs: string[];
+  /** Set when sandbox execution fails (timeout, syntax error, runtime error). */
+  error?: string;
+  trace?: ToolCallRecord[];
+  stats?: ExecutionStats;
+}
+
+/** Configuration for a tool source to register with the engine. */
+export interface ToolSourceConfig {
+  name: string;
+  call_template_type: string;
+  callable_name?: string;
+  config?: Record<string, unknown>;
+}
+
+/** Result of registering a tool source. */
+export interface RegisterResult {
+  success: boolean;
+  toolNames: string[];
+  errors?: string[];
+}