@vibe-lang/runtime 0.2.5

package/src/runtime/tools/types.ts

@@ -0,0 +1,89 @@
+// JSON Schema type for tool parameters
+export interface JsonSchema {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  items?: JsonSchema;
+  required?: string[];
+  additionalProperties?: boolean;
+}
+
+// Tool parameter schema for AI function calling
+export interface ToolParameterSchema {
+  name: string;
+  type: JsonSchema;
+  description?: string;
+  required: boolean;
+}
+
+// Tool schema for AI function calling
+export interface ToolSchema {
+  name: string;
+  description?: string;
+  parameters: ToolParameterSchema[];
+  returns?: JsonSchema;
+}
+
+// Context passed to tool executors
+export interface ToolContext {
+  rootDir: string;  // Root directory for path sandboxing
+}
+
+// Tool executor function signature
+export type ToolExecutor = (
+  args: Record<string, unknown>,
+  context?: ToolContext
+) => Promise<unknown>;
+
+// Pending tool call (when runtime is paused)
+export interface PendingToolCall {
+  toolName: string;
+  toolCallId: string;
+  args: Record<string, unknown>;
+  executor: ToolExecutor;  // The tool's executor function
+  // For multi-turn AI tool calling (deferred for now)
+  aiConversationState?: unknown;
+}
+
+// Tool execution result
+export interface ToolResult {
+  value: unknown;
+  error?: string;
+}
+
+// Tool as a first-class Vibe value (like VibeModelValue)
+// This is the value stored when a tool declaration is executed
+export interface VibeToolValue {
+  __vibeTool: true;           // Type guard marker
+  name: string;
+  schema: ToolSchema;
+  executor: ToolExecutor;
+}
+
+// Type guard for VibeToolValue
+export function isVibeToolValue(value: unknown): value is VibeToolValue {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '__vibeTool' in value &&
+    (value as VibeToolValue).__vibeTool === true
+  );
+}
+
+// Registered tool in the registry
+export interface RegisteredTool {
+  name: string;
+  kind: 'builtin' | 'user';
+  schema: ToolSchema;
+  executor: ToolExecutor;
+}
+
+// Tool registry interface
+export interface ToolRegistry {
+  register(tool: RegisteredTool): void;
+  registerAll(tools: RegisteredTool[]): void;
+  get(name: string): RegisteredTool | undefined;
+  has(name: string): boolean;
+  list(): RegisteredTool[];
+  getSchemas(): ToolSchema[];
+}

package/src/runtime/tools/utility-tools.ts

@@ -0,0 +1,198 @@
+import type { RegisteredTool } from './types';
+import { resolveValue } from '../types';
+
+/**
+ * Utility tools: env, sleep, now, jsonParse, jsonStringify, print, random, uuid
+ */
+export const utilityTools = [
+  {
+    name: 'env',
+    kind: 'builtin',
+    schema: {
+      name: 'env',
+      description: 'Get an environment variable.',
+      parameters: [
+        {
+          name: 'name',
+          type: { type: 'string' },
+          description: 'The environment variable name',
+          required: true,
+        },
+        {
+          name: 'defaultValue',
+          type: { type: 'string' },
+          description: 'Default value if not set',
+          required: false,
+        },
+      ],
+      returns: { type: 'string' },
+    },
+    executor: async (args: Record<string, unknown>) => {
+      const name = args.name as string;
+      const defaultValue = args.defaultValue as string | undefined;
+      return process.env[name] ?? defaultValue ?? '';
+    },
+  },
+
+  {
+    name: 'sleep',
+    kind: 'builtin',
+    schema: {
+      name: 'sleep',
+      description: 'Pause execution for a specified number of milliseconds.',
+      parameters: [
+        {
+          name: 'ms',
+          type: { type: 'number' },
+          description: 'Milliseconds to sleep',
+          required: true,
+        },
+      ],
+      returns: { type: 'boolean' },
+    },
+    executor: async (args: Record<string, unknown>) => {
+      const ms = args.ms as number;
+      await new Promise((resolve) => setTimeout(resolve, ms));
+      return true;
+    },
+  },
+
+  {
+    name: 'now',
+    kind: 'builtin',
+    schema: {
+      name: 'now',
+      description: 'Get the current timestamp in milliseconds.',
+      parameters: [],
+      returns: { type: 'number' },
+    },
+    executor: async () => {
+      return Date.now();
+    },
+  },
+
+  {
+    name: 'jsonParse',
+    kind: 'builtin',
+    schema: {
+      name: 'jsonParse',
+      description: 'Parse a JSON string into an object.',
+      parameters: [
+        {
+          name: 'text',
+          type: { type: 'string' },
+          description: 'The JSON string to parse',
+          required: true,
+        },
+      ],
+      returns: { type: 'object', additionalProperties: true },
+    },
+    executor: async (args: Record<string, unknown>) => {
+      const text = args.text as string;
+      return JSON.parse(text);
+    },
+  },
+
+  {
+    name: 'jsonStringify',
+    kind: 'builtin',
+    schema: {
+      name: 'jsonStringify',
+      description: 'Convert an object to a JSON string.',
+      parameters: [
+        {
+          name: 'value',
+          type: { type: 'object', additionalProperties: true },
+          description: 'The value to stringify',
+          required: true,
+        },
+        {
+          name: 'pretty',
+          type: { type: 'boolean' },
+          description: 'Whether to format with indentation',
+          required: false,
+        },
+      ],
+      returns: { type: 'string' },
+    },
+    executor: async (args: Record<string, unknown>) => {
+      const value = args.value;
+      const pretty = args.pretty as boolean | undefined;
+      return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+    },
+  },
+
+  {
+    name: 'print',
+    kind: 'builtin',
+    schema: {
+      name: 'print',
+      description: 'Output a message to the console.',
+      parameters: [
+        {
+          name: 'message',
+          type: { type: 'string' },
+          description: 'The message to print',
+          required: true,
+        },
+      ],
+      returns: { type: 'boolean' },
+    },
+    executor: async (args: Record<string, unknown>) => {
+      // Resolve AIResultObject to its value before printing
+      const message = resolveValue(args.message);
+      console.log(message);
+      return true;
+    },
+  },
+
+  {
+    name: 'random',
+    kind: 'builtin',
+    schema: {
+      name: 'random',
+      description: 'Generate a random number. Without arguments, returns 0-1. With min/max, returns integer in range.',
+      parameters: [
+        {
+          name: 'min',
+          type: { type: 'number' },
+          description: 'Minimum value (inclusive)',
+          required: false,
+        },
+        {
+          name: 'max',
+          type: { type: 'number' },
+          description: 'Maximum value (inclusive)',
+          required: false,
+        },
+      ],
+      returns: { type: 'number' },
+    },
+    executor: async (args: Record<string, unknown>) => {
+      const min = args.min as number | undefined;
+      const max = args.max as number | undefined;
+
+      if (min !== undefined && max !== undefined) {
+        // Return random integer in range [min, max]
+        return Math.floor(Math.random() * (max - min + 1)) + min;
+      }
+
+      // Return random float [0, 1)
+      return Math.random();
+    },
+  },
+
+  {
+    name: 'uuid',
+    kind: 'builtin',
+    schema: {
+      name: 'uuid',
+      description: 'Generate a UUID v4.',
+      parameters: [],
+      returns: { type: 'string' },
+    },
+    executor: async () => {
+      return crypto.randomUUID();
+    },
+  },
+] satisfies RegisteredTool[];

package/src/runtime/ts-eval.ts

@@ -0,0 +1,126 @@
+// TypeScript evaluation with caching
+// Uses AsyncFunction constructor to compile and execute TypeScript code
+
+import type { SourceLocation } from '../errors';
+
+// Cache compiled functions by signature (params + body)
+const functionCache = new Map<string, (...args: unknown[]) => Promise<unknown>>();
+
+// Get the AsyncFunction constructor
+const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor as new (
+  ...args: string[]
+) => (...args: unknown[]) => Promise<unknown>;
+
+// Generate cache key from params and body
+function getCacheKey(params: string[], body: string): string {
+  return `${params.join(',')}::${body}`;
+}
+
+// Custom error for TS block failures
+export class TsBlockError extends Error {
+  constructor(
+    message: string,
+    public readonly params: string[],
+    public readonly body: string,
+    public readonly originalError: Error,
+    public readonly location?: SourceLocation
+  ) {
+    super(message);
+    this.name = 'TsBlockError';
+  }
+
+  // Format error with source location and original stack trace
+  format(): string {
+    let result = '';
+
+    // Add Vibe source location if available
+    if (this.location) {
+      const loc = `[${this.location.file ?? 'vibe'}:${this.location.line}:${this.location.column}]`;
+      result = `${loc} `;
+    }
+
+    result += this.message;
+
+    // Add original TypeScript stack trace for debugging
+    if (this.originalError.stack) {
+      result += `\n\nTypeScript stack trace:\n${this.originalError.stack}`;
+    }
+
+    return result;
+  }
+}
+
+// Evaluate a TypeScript block
+export async function evalTsBlock(
+  params: string[],
+  body: string,
+  paramValues: unknown[],
+  location?: SourceLocation
+): Promise<unknown> {
+  const cacheKey = getCacheKey(params, body);
+
+  // Get or compile function
+  let fn = functionCache.get(cacheKey);
+  if (!fn) {
+    try {
+      // Prepend 'use strict' to ensure frozen object mutations throw errors
+      const strictBody = `'use strict';\n${body}`;
+      fn = new AsyncFunction(...params, strictBody);
+      functionCache.set(cacheKey, fn);
+    } catch (error) {
+      // Syntax error in TS block
+      const snippet = body.length > 50 ? body.slice(0, 50) + '...' : body;
+      throw new TsBlockError(
+        `ts block compilation error: ${error instanceof Error ? error.message : String(error)}\n  Code: ${snippet}`,
+        params,
+        body,
+        error instanceof Error ? error : new Error(String(error)),
+        location
+      );
+    }
+  }
+
+  // Call with parameter values
+  try {
+    return await fn(...paramValues);
+  } catch (error) {
+    // Runtime error in TS block
+    const snippet = body.length > 50 ? body.slice(0, 50) + '...' : body;
+    throw new TsBlockError(
+      `ts block runtime error: ${error instanceof Error ? error.message : String(error)}\n  Code: ${snippet}`,
+      params,
+      body,
+      error instanceof Error ? error : new Error(String(error)),
+      location
+    );
+  }
+}
+
+// Validate return type against expected type annotation
+export function validateReturnType(
+  value: unknown,
+  expectedType: string | null,
+  varName: string
+): void {
+  if (!expectedType) return; // No type annotation, accept anything
+
+  if (expectedType === 'text' && typeof value !== 'string') {
+    throw new TypeError(`Variable '${varName}': expected text, got ${typeof value}`);
+  }
+
+  if (expectedType === 'json') {
+    if (typeof value !== 'object' || value === null) {
+      throw new TypeError(`Variable '${varName}': expected json (object/array), got ${typeof value}`);
+    }
+  }
+}
+
+// Clear the function cache (useful for testing)
+export function clearFunctionCache(): void {
+  functionCache.clear();
+}
+
+// Get cache size (useful for testing)
+export function getFunctionCacheSize(): number {
+  return functionCache.size;
+}