@vibe-lang/runtime 0.2.5

package/src/runtime/exec/tools.ts

@@ -0,0 +1,129 @@
+// Tool execution handlers
+
+import * as AST from '../../ast';
+import type { RuntimeState } from '../types';
+import { createVibeValue } from '../types';
+import type { ToolSchema, ToolParameterSchema, VibeToolValue } from '../tools/types';
+import { vibeTypeToJsonSchema } from '../tools/ts-schema';
+import { currentFrame } from '../state';
+
+/**
+ * Execute a tool declaration - stores the tool as a variable in frame locals.
+ */
+export function execToolDeclaration(
+  state: RuntimeState,
+  decl: AST.ToolDeclaration
+): RuntimeState {
+  // Build tool schema from declaration
+  const schema = buildToolSchema(state, decl);
+
+  // Create executor that wraps the tool body
+  const executor = createToolExecutor(state, decl);
+
+  // Create the tool value (like a model value)
+  const toolValue: VibeToolValue = {
+    __vibeTool: true,
+    name: decl.name,
+    schema,
+    executor,
+  };
+
+  // Store as a variable in frame locals (like model declarations)
+  const frame = currentFrame(state);
+  const newLocals = {
+    ...frame.locals,
+    [decl.name]: createVibeValue(toolValue, { isConst: true, typeAnnotation: null }),
+  };
+
+  return {
+    ...state,
+    callStack: [
+      ...state.callStack.slice(0, -1),
+      { ...frame, locals: newLocals },
+    ],
+    executionLog: [
+      ...state.executionLog,
+      {
+        timestamp: Date.now(),
+        instructionType: 'tool_declaration',
+        details: { toolName: decl.name },
+      },
+    ],
+  };
+}
+
+/**
+ * Build a tool schema from the AST declaration.
+ * Converts Vibe types to JSON Schema, merging in @param descriptions.
+ */
+function buildToolSchema(
+  state: RuntimeState,
+  decl: AST.ToolDeclaration
+): ToolSchema {
+  // Build map of imported types for resolving TS type references
+  const importedTypes = new Map<string, string>();
+  for (const [name, info] of Object.entries(state.importedNames)) {
+    if (info.sourceType === 'ts') {
+      importedTypes.set(name, info.source);
+    }
+  }
+
+  const parameters: ToolParameterSchema[] = decl.params.map((param) => ({
+    name: param.name,
+    type: vibeTypeToJsonSchema(param.typeAnnotation, importedTypes),
+    description: param.description,
+    required: true, // All tool parameters are required for now
+  }));
+
+  return {
+    name: decl.name,
+    description: decl.description,
+    parameters,
+    returns: decl.returnType
+      ? vibeTypeToJsonSchema(decl.returnType, importedTypes)
+      : undefined,
+  };
+}
+
+/**
+ * Create an executor function for a user-defined tool.
+ * The executor extracts the TS block from the tool body and runs it.
+ */
+function createToolExecutor(
+  _state: RuntimeState,
+  decl: AST.ToolDeclaration
+): (args: Record<string, unknown>) => Promise<unknown> {
+  // Find the TsBlock in the tool body
+  const tsBlock = findTsBlock(decl.body);
+
+  if (!tsBlock) {
+    throw new Error(`Tool '${decl.name}' must have a ts block as its body`);
+  }
+
+  // Return an executor that runs the TS code with the provided args
+  return async (args: Record<string, unknown>): Promise<unknown> => {
+    // Build parameter values in the order they appear in the ts block params
+    const paramValues = tsBlock.params.map((paramName) => args[paramName]);
+
+    // Create async function from the TS body
+    const asyncFn = new Function(
+      ...tsBlock.params,
+      `return (async () => { ${tsBlock.body} })()`
+    );
+
+    return await asyncFn(...paramValues);
+  };
+}
+
+/**
+ * Find the first TsBlock expression in a block statement.
+ */
+function findTsBlock(block: AST.BlockStatement): AST.TsBlock | null {
+  for (const stmt of block.body) {
+    if (stmt.type === 'ExpressionStatement' && stmt.expression.type === 'TsBlock') {
+      return stmt.expression;
+    }
+  }
+  return null;
+}
+

package/src/runtime/exec/typescript.ts

@@ -0,0 +1,215 @@
+// TypeScript execution: interpolation, ts blocks, ts eval
+
+import * as AST from '../../ast';
+import type { SourceLocation } from '../../errors';
+import type { RuntimeState } from '../types';
+import { resolveValue, isVibeValue } from '../types';
+import { lookupVariable } from './variables';
+import { getImportedValue } from '../modules';
+import { scheduleAsyncOperation, isInAsyncContext } from '../async/scheduling';
+
+/**
+ * Deep freeze an object to prevent any mutation.
+ * Used to enforce const semantics for objects passed to ts blocks.
+ */
+function deepFreeze<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  // Freeze the object itself
+  Object.freeze(obj);
+
+  // Recursively freeze all properties
+  for (const key of Object.keys(obj)) {
+    const value = (obj as Record<string, unknown>)[key];
+    if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+
+  return obj;
+}
+
+/**
+ * String interpolation - {varName} syntax.
+ * Resolves AIResultObject to its value for string conversion.
+ * If any interpolated variable is a pending async operation, triggers awaiting_async.
+ */
+export function execInterpolateString(state: RuntimeState, template: string, location?: SourceLocation): RuntimeState {
+  // First pass: check for pending async variables
+  const varPattern = /\{(\w+)\}/g;
+  const pendingAsyncIds: string[] = [];
+  let match;
+
+  while ((match = varPattern.exec(template)) !== null) {
+    const name = match[1];
+    const found = lookupVariable(state, name);
+    if (found) {
+      const variable = found.variable;
+      if (isVibeValue(variable) && variable.asyncOperationId) {
+        const opId = variable.asyncOperationId;
+        const operation = state.asyncOperations.get(opId);
+        if (operation && (operation.status === 'pending' || operation.status === 'running')) {
+          pendingAsyncIds.push(opId);
+        }
+      }
+    }
+  }
+
+  // If there are pending async variables, wait for them
+  if (pendingAsyncIds.length > 0) {
+    return {
+      ...state,
+      status: 'awaiting_async',
+      awaitingAsyncIds: pendingAsyncIds,
+      instructionStack: [
+        { op: 'interpolate_string', template, location: location ?? { line: 0, column: 0 } },
+        ...state.instructionStack,
+      ],
+    };
+  }
+
+  // All variables ready, do the interpolation
+  const result = template.replace(/\{(\w+)\}/g, (_, name) => {
+    const found = lookupVariable(state, name);
+    if (found) {
+      const value = resolveValue(found.variable.value);
+      return String(value);
+    }
+    return `{${name}}`;
+  });
+
+  return { ...state, lastResult: result };
+}
+
+/**
+ * Template literal interpolation - ${varName} syntax.
+ * Resolves AIResultObject to its value for string conversion.
+ * If any interpolated variable is a pending async operation, triggers awaiting_async.
+ */
+export function execInterpolateTemplate(state: RuntimeState, template: string, location?: SourceLocation): RuntimeState {
+  // First pass: check for pending async variables
+  const varPattern = /\$\{(\w+)\}/g;
+  const pendingAsyncIds: string[] = [];
+  let match;
+
+  while ((match = varPattern.exec(template)) !== null) {
+    const name = match[1];
+    const found = lookupVariable(state, name);
+    if (found) {
+      const variable = found.variable;
+      if (isVibeValue(variable) && variable.asyncOperationId) {
+        const opId = variable.asyncOperationId;
+        const operation = state.asyncOperations.get(opId);
+        if (operation && (operation.status === 'pending' || operation.status === 'running')) {
+          pendingAsyncIds.push(opId);
+        }
+      }
+    }
+  }
+
+  // If there are pending async variables, wait for them
+  if (pendingAsyncIds.length > 0) {
+    return {
+      ...state,
+      status: 'awaiting_async',
+      awaitingAsyncIds: pendingAsyncIds,
+      instructionStack: [
+        { op: 'interpolate_template', template, location: location ?? { line: 0, column: 0 } },
+        ...state.instructionStack,
+      ],
+    };
+  }
+
+  // All variables ready, do the interpolation
+  const result = template.replace(/\$\{(\w+)\}/g, (_, name) => {
+    const found = lookupVariable(state, name);
+    if (found) {
+      const value = resolveValue(found.variable.value);
+      return String(value);
+    }
+    return `\${${name}}`;
+  });
+
+  return { ...state, lastResult: result };
+}
+
+/**
+ * TypeScript block - push ts_eval instruction.
+ */
+export function execTsBlock(state: RuntimeState, expr: AST.TsBlock): RuntimeState {
+  return {
+    ...state,
+    instructionStack: [
+      { op: 'ts_eval', params: expr.params, body: expr.body, location: expr.location },
+      ...state.instructionStack,
+    ],
+  };
+}
+
+/**
+ * TypeScript eval - pause for async evaluation.
+ * When currentAsyncVarName is set (async declaration), schedules the operation
+ * for non-blocking execution instead of pausing.
+ */
+export function execTsEval(state: RuntimeState, params: string[], body: string, location: SourceLocation): RuntimeState {
+  // Look up parameter values from scope or imports
+  const paramValues = params.map((name) => {
+    // First try regular variables
+    const found = lookupVariable(state, name);
+    if (found) {
+      // Resolve AIResultObject to primitive value for ts blocks
+      const value = resolveValue(found.variable.value);
+      // Freeze const objects to prevent mutation in ts blocks
+      if (found.variable.isConst && value !== null && typeof value === 'object') {
+        return deepFreeze(value);
+      }
+      return value;
+    }
+    // Then try imported values
+    const imported = getImportedValue(state, name);
+    if (imported !== undefined) {
+      return imported;
+    }
+    throw new Error(`ReferenceError: '${name}' is not defined`);
+  });
+
+  // Check if we're in async context (variable, destructuring, or fire-and-forget)
+  if (isInAsyncContext(state)) {
+    // Schedule for non-blocking execution using shared helper
+    return scheduleAsyncOperation(
+      state,
+      {
+        type: 'ts',
+        tsDetails: {
+          params,
+          body,
+          paramValues,
+          location,
+        },
+      },
+      'async_ts_scheduled'
+    );
+  }
+
+  // Normal blocking execution
+  return {
+    ...state,
+    status: 'awaiting_ts',
+    pendingTS: {
+      params,
+      body,
+      paramValues,
+      location,  // Include source location for error reporting
+    },
+    executionLog: [
+      ...state.executionLog,
+      {
+        timestamp: Date.now(),
+        instructionType: 'ts_eval_request',
+        details: { params, body: body.slice(0, 100) },  // Truncate body for log
+      },
+    ],
+  };
+}

package/src/runtime/exec/variables.ts

@@ -0,0 +1,279 @@
+// Variable handling: lookup, declare, assign
+
+import type { VibeType } from '../../ast';
+import type { SourceLocation } from '../../errors';
+import type { RuntimeState, VibeValue, StackFrame, ToolCallRecord } from '../types';
+import { createVibeValue, isVibeValue } from '../types';
+import { currentFrame } from '../state';
+import { validateAndCoerce } from '../validation';
+import { getModuleGlobals } from '../modules';
+
+/**
+ * Look up a variable by walking the scope chain.
+ * Returns the variable and its frame index, or null if not found.
+ *
+ * Module isolation: If we're in an imported function (frame has modulePath),
+ * we check that module's globals instead of walking up to the main program.
+ */
+export function lookupVariable(state: RuntimeState, name: string): { variable: VibeValue; frameIndex: number } | null {
+  let frameIndex: number | null = state.callStack.length - 1;
+  let modulePath: string | undefined;
+
+  while (frameIndex !== null && frameIndex >= 0) {
+    const frame: StackFrame = state.callStack[frameIndex];
+
+    // Check frame locals
+    if (frame.locals[name]) {
+      return { variable: frame.locals[name], frameIndex };
+    }
+
+    // Track the module path from any frame in the chain
+    if (frame.modulePath && !modulePath) {
+      modulePath = frame.modulePath;
+    }
+
+    // If we're in a module context and this is the module's root frame,
+    // don't walk up to the caller's frames - check module globals instead
+    if (modulePath && frame.modulePath === modulePath) {
+      // Check module globals before walking to parent (caller's context)
+      const moduleGlobals = getModuleGlobals(state, modulePath);
+      if (moduleGlobals?.[name]) {
+        return { variable: moduleGlobals[name], frameIndex: -1 };
+      }
+      // Don't continue to caller's frames - module isolation
+      return null;
+    }
+
+    frameIndex = frame.parentFrameIndex;
+  }
+
+  // Not in module context - variable not found in main program
+  return null;
+}
+
+/**
+ * Declare a variable with value from lastResult (or explicit initialValue).
+ */
+export function execDeclareVar(
+  state: RuntimeState,
+  name: string,
+  isConst: boolean,
+  type: VibeType,
+  initialValue?: unknown,
+  isPrivate?: boolean,
+  location?: SourceLocation
+): RuntimeState {
+  const frame = currentFrame(state);
+
+  if (frame.locals[name]) {
+    throw new Error(`Variable '${name}' is already declared`);
+  }
+
+  const rawValue = initialValue !== undefined ? initialValue : state.lastResult;
+
+  // If value is already a VibeValue (e.g., from AI response or error), extract its properties
+  let innerValue: unknown;
+  let toolCalls: ToolCallRecord[] = [];
+  let source = initialValue !== undefined ? null : state.lastResultSource;
+  let err: VibeValue['err'] = false;
+  let errDetails: VibeValue['errDetails'] = null;
+  let asyncOperationId: string | undefined;
+
+  if (isVibeValue(rawValue)) {
+    innerValue = rawValue.value;
+    toolCalls = rawValue.toolCalls;
+    source = rawValue.source ?? source;
+    err = rawValue.err;  // Preserve error boolean from operations like null arithmetic
+    errDetails = rawValue.errDetails;  // Preserve error details
+    asyncOperationId = rawValue.asyncOperationId;  // Preserve async operation ID for pending async
+  } else {
+    innerValue = rawValue;
+  }
+
+  const { value: validatedValue, inferredType } = validateAndCoerce(innerValue, type, name, location, source);
+
+  // Use explicit type if provided, otherwise use inferred type
+  const finalType = type ?? inferredType;
+
+  const newLocals = {
+    ...frame.locals,
+    [name]: createVibeValue(validatedValue, { isConst, typeAnnotation: finalType, source, toolCalls, err, errDetails, isPrivate, asyncOperationId }),
+  };
+
+  // Add variable to ordered entries with snapshotted value for context tracking
+  const newOrderedEntries = [
+    ...frame.orderedEntries,
+    {
+      kind: 'variable' as const,
+      name,
+      value: validatedValue,  // Snapshot at assignment time
+      type: finalType,
+      isConst,
+      source,
+      ...(isPrivate ? { isPrivate: true } : {}),
+    },
+  ];
+
+  const newState: RuntimeState = {
+    ...state,
+    lastResultSource: null,  // Clear after consuming
+    callStack: [
+      ...state.callStack.slice(0, -1),
+      { ...frame, locals: newLocals, orderedEntries: newOrderedEntries },
+    ],
+    executionLog: [
+      ...state.executionLog,
+      {
+        timestamp: Date.now(),
+        instructionType: isConst ? 'const_declaration' : 'let_declaration',
+        details: { name, type, isConst },
+        result: validatedValue,
+      },
+    ],
+  };
+
+  return newState;
+}
+
+/**
+ * Assign a value to an existing variable (from lastResult).
+ */
+export function execAssignVar(state: RuntimeState, name: string, location?: SourceLocation): RuntimeState {
+  // Walk scope chain to find the variable
+  const found = lookupVariable(state, name);
+
+  if (!found) {
+    throw new Error(`ReferenceError: '${name}' is not defined`);
+  }
+
+  const { variable, frameIndex } = found;
+
+  if (variable.isConst) {
+    throw new Error(`TypeError: Cannot assign to constant '${name}'`);
+  }
+
+  // Warn if modifying non-local variable in async isolation
+  // (modifications won't persist after the async function returns)
+  const currentFrameIndex = state.callStack.length - 1;
+  if (state.isInAsyncIsolation && frameIndex !== currentFrameIndex && frameIndex >= 0) {
+    console.warn(
+      `Warning: Modifying non-local variable '${name}' in async function. ` +
+      `This modification will not persist after the function returns.`
+    );
+  }
+
+  const rawValue = state.lastResult;
+
+  // If value is already a VibeValue (e.g., from AI response or error), extract its properties
+  let innerValue: unknown;
+  let toolCalls: ToolCallRecord[] = [];
+  let source = state.lastResultSource;
+  let err: VibeValue['err'] = false;
+  let errDetails: VibeValue['errDetails'] = null;
+
+  if (isVibeValue(rawValue)) {
+    innerValue = rawValue.value;
+    toolCalls = rawValue.toolCalls;
+    source = rawValue.source ?? source;
+    err = rawValue.err;  // Preserve error boolean from operations like null arithmetic
+    errDetails = rawValue.errDetails;  // Preserve error details
+  } else {
+    innerValue = rawValue;
+  }
+
+  const { value: validatedValue } = validateAndCoerce(innerValue, variable.typeAnnotation, name, location, source);
+
+  // Handle module global assignment (frameIndex -1)
+  if (frameIndex === -1) {
+    // Find which module this belongs to by checking current frame's modulePath
+    const currentModulePath = getCurrentModulePath(state);
+    if (!currentModulePath) {
+      throw new Error(`Internal error: module global assignment without module context`);
+    }
+
+    const module = state.vibeModules[currentModulePath];
+    if (!module) {
+      throw new Error(`Internal error: module not found: ${currentModulePath}`);
+    }
+
+    const newGlobals = {
+      ...module.globals,
+      [name]: { ...variable, value: validatedValue, source, toolCalls, err, errDetails },
+    };
+
+    return {
+      ...state,
+      lastResultSource: null,
+      vibeModules: {
+        ...state.vibeModules,
+        [currentModulePath]: { ...module, globals: newGlobals },
+      },
+      executionLog: [
+        ...state.executionLog,
+        {
+          timestamp: Date.now(),
+          instructionType: 'assignment',
+          details: { name, moduleGlobal: true },
+          result: validatedValue,
+        },
+      ],
+    };
+  }
+
+  // Regular frame local assignment
+  const frame = state.callStack[frameIndex];
+  const newLocals = {
+    ...frame.locals,
+    [name]: { ...variable, value: validatedValue, source, toolCalls, err, errDetails },
+  };
+
+  // Add assignment to ordered entries with snapshotted value for context tracking
+  // This captures the history of value changes
+  const newOrderedEntries = [
+    ...frame.orderedEntries,
+    {
+      kind: 'variable' as const,
+      name,
+      value: validatedValue,  // Snapshot at assignment time
+      type: variable.typeAnnotation,
+      isConst: false,  // Assignments only happen to non-const variables
+      source,
+    },
+  ];
+
+  // Update the correct frame in the call stack
+  return {
+    ...state,
+    lastResultSource: null,  // Clear after consuming
+    callStack: [
+      ...state.callStack.slice(0, frameIndex),
+      { ...frame, locals: newLocals, orderedEntries: newOrderedEntries },
+      ...state.callStack.slice(frameIndex + 1),
+    ],
+    executionLog: [
+      ...state.executionLog,
+      {
+        timestamp: Date.now(),
+        instructionType: 'assignment',
+        details: { name },
+        result: validatedValue,
+      },
+    ],
+  };
+}
+
+/**
+ * Get the module path from the current execution context.
+ * Walks up the call stack to find a frame with modulePath.
+ */
+function getCurrentModulePath(state: RuntimeState): string | undefined {
+  let frameIndex: number | null = state.callStack.length - 1;
+  while (frameIndex !== null && frameIndex >= 0) {
+    const frame: StackFrame = state.callStack[frameIndex];
+    if (frame.modulePath) {
+      return frame.modulePath;
+    }
+    frameIndex = frame.parentFrameIndex;
+  }
+  return undefined;
+}