@vibe-lang/runtime 0.2.8 → 0.2.10

package/src/parser/test/model-declaration.test.ts

@@ -110,6 +110,20 @@ model myModel = {
     expect(model.config.apiKey.value).toBe('sk-test');
     expect(model.config.url.value).toBe('https://api.openai.com');
   });
+
+  test('model with trailing comma', () => {
+    const ast = parse(`
+model myModel = {
+  name: "gpt-4",
+  apiKey: "sk-test",
+  url: "https://api.openai.com",
+}
+`);
+    expect(ast.body).toHaveLength(1);
+    const model = ast.body[0] as any;
+    expect(model.type).toBe('ModelDeclaration');
+    expect(model.config.providedFields).toEqual(['name', 'apiKey', 'url']);
+  });
 });
 
 describe('Syntax Errors - Model Declaration', () => {

package/src/parser/visitor.ts

@@ -61,6 +61,7 @@ class VibeAstVisitor extends BaseVibeVisitor {
     if (ctx.toolDeclaration) return this.visit(ctx.toolDeclaration);
     if (ctx.returnStatement) return this.visit(ctx.returnStatement);
     if (ctx.breakStatement) return this.visit(ctx.breakStatement);
+    if (ctx.throwStatement) return this.visit(ctx.throwStatement);
     if (ctx.ifStatement) return this.visit(ctx.ifStatement);
     if (ctx.forInStatement) return this.visit(ctx.forInStatement);
     if (ctx.whileStatement) return this.visit(ctx.whileStatement);
@@ -409,6 +410,14 @@ class VibeAstVisitor extends BaseVibeVisitor {
     return { type: 'BreakStatement', location: tokenLocation(ctx.Break[0]) };
   }
 
+  throwStatement(ctx: { Throw: IToken[]; expression: CstNode[] }): AST.ThrowStatement {
+    return {
+      type: 'ThrowStatement',
+      message: this.visit(ctx.expression),
+      location: tokenLocation(ctx.Throw[0]),
+    };
+  }
+
   ifStatement(ctx: { If: IToken[]; expression: CstNode[]; blockStatement: CstNode[]; ifStatement?: CstNode[] }): AST.IfStatement {
     const alternate = ctx.ifStatement ? this.visit(ctx.ifStatement) : ctx.blockStatement.length > 1 ? this.visit(ctx.blockStatement[1]) : null;
     return { type: 'IfStatement', condition: this.visit(ctx.expression), consequent: this.visit(ctx.blockStatement[0]), alternate, location: tokenLocation(ctx.If[0]) };

package/src/runtime/async/dependencies.ts

@@ -83,8 +83,15 @@ export function getReferencedVariables(expr: AST.Expression): string[] {
         }
         break;
 
-      // Literals don't reference variables
       case 'StringLiteral':
+        // Extract variables from {varName} and !{varName} interpolation in strings
+        const stringMatches = node.value.matchAll(/!?\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g);
+        for (const match of stringMatches) {
+          variables.push(match[1]);
+        }
+        break;
+
+      // These literals don't reference variables
       case 'NumberLiteral':
       case 'BooleanLiteral':
       case 'NullLiteral':

package/src/runtime/async/test/dependencies.test.ts

@@ -22,11 +22,37 @@ describe('Async Dependency Detection', () => {
       expect(getReferencedVariables(expr)).toEqual(['myVar']);
     });
 
-    test('extracts no variables from string literal', () => {
+    test('extracts no variables from plain string literal', () => {
       const expr = parseExpr('"hello"');
       expect(getReferencedVariables(expr)).toEqual([]);
     });
 
+    test('extracts variables from string literal with {var} interpolation', () => {
+      const expr = parseExpr('"Hello {name}!"');
+      const vars = getReferencedVariables(expr);
+      expect(vars).toContain('name');
+    });
+
+    test('extracts variables from string literal with !{var} expansion', () => {
+      const expr = parseExpr('"Process this: !{data}"');
+      const vars = getReferencedVariables(expr);
+      expect(vars).toContain('data');
+    });
+
+    test('extracts multiple variables from string literal interpolation', () => {
+      const expr = parseExpr('"Hello {greeting} {name}, your data is !{info}"');
+      const vars = getReferencedVariables(expr);
+      expect(vars).toContain('greeting');
+      expect(vars).toContain('name');
+      expect(vars).toContain('info');
+    });
+
+    test('extracts variables from single-quoted string with interpolation', () => {
+      const expr = parseExpr("'User: {user}'");
+      const vars = getReferencedVariables(expr);
+      expect(vars).toContain('user');
+    });
+
     test('extracts no variables from number literal', () => {
       const expr = parseExpr('42');
       expect(getReferencedVariables(expr)).toEqual([]);

package/src/runtime/exec/statements.ts

@@ -3,7 +3,7 @@
 import * as AST from '../../ast';
 import type { SourceLocation } from '../../errors';
 import type { RuntimeState, VibeValue } from '../types';
-import { createVibeValue, resolveValue, isVibeValue } from '../types';
+import { createVibeValue, createVibeError, resolveValue, isVibeValue } from '../types';
 import { currentFrame } from '../state';
 import { requireBoolean, validateAndCoerce } from '../validation';
 import { execDeclareVar } from './variables';
@@ -441,6 +441,53 @@ export function execReturnValue(state: RuntimeState): RuntimeState {
   return { ...state, callStack: newCallStack, instructionStack: newInstructionStack, lastResult: validatedReturnValue };
 }
 
+/**
+ * Throw statement - evaluate message and throw error.
+ */
+export function execThrowStatement(state: RuntimeState, stmt: AST.ThrowStatement): RuntimeState {
+  return {
+    ...state,
+    instructionStack: [
+      { op: 'exec_expression', expr: stmt.message, location: stmt.message.location },
+      { op: 'throw_error', location: stmt.location },
+      ...state.instructionStack,
+    ],
+  };
+}
+
+/**
+ * Throw error - create error value and unwind to function boundary.
+ * Uses lastResult as the error message.
+ */
+export function execThrowError(state: RuntimeState, location: SourceLocation): RuntimeState {
+  // Get the error message from lastResult
+  const messageValue = resolveValue(state.lastResult);
+  const message = typeof messageValue === 'string' ? messageValue : String(messageValue);
+
+  // Create error VibeValue
+  const errorValue = createVibeError(message, location);
+
+  // Check if we're at top level (only main frame) or in a function
+  const isTopLevel = state.callStack.length === 1;
+
+  if (isTopLevel) {
+    // At top level - complete with error but keep the frame for variable access
+    return { ...state, status: 'completed', instructionStack: [], lastResult: errorValue };
+  }
+
+  // In a function - unwind like return: pop frame and skip to after pop_frame instruction
+  const newCallStack = state.callStack.slice(0, -1);
+
+  // Find and skip past the pop_frame instruction
+  let newInstructionStack = state.instructionStack;
+  const popFrameIndex = newInstructionStack.findIndex((i) => i.op === 'pop_frame');
+  if (popFrameIndex !== -1) {
+    newInstructionStack = newInstructionStack.slice(popFrameIndex + 1);
+  }
+
+  return { ...state, callStack: newCallStack, instructionStack: newInstructionStack, lastResult: errorValue };
+}
+
 /**
  * Execute statements at index - sequential statement execution.
  */
@@ -598,6 +645,9 @@ export function execStatement(state: RuntimeState, stmt: AST.Statement): Runtime
     case 'BreakStatement':
       return execBreakStatement(state, stmt);
 
+    case 'ThrowStatement':
+      return execThrowStatement(state, stmt);
+
     default:
       throw new Error(`Unknown statement type: ${(stmt as AST.Statement).type}`);
   }

package/src/runtime/index.ts

@@ -185,13 +185,12 @@ export class Runtime {
     return resolveValue(variable?.value);
   }
 
-  // Get raw value including VibeValue wrapper if present
+  // Get raw VibeValue wrapper (for testing error state, toolCalls, etc.)
   getRawValue(name: string): unknown {
     const frame = this.state.callStack[this.state.callStack.length - 1];
     if (!frame) return undefined;
 
-    const variable = frame.locals[name];
-    return variable?.value;
+    return frame.locals[name];
   }
 
   // Get all AI interactions (for debugging)

package/src/runtime/modules.ts

@@ -9,7 +9,7 @@ import { resolve, dirname, join } from 'path';
 
 // Map system module names to their implementation files
 const SYSTEM_MODULES: Record<string, string> = {
-  'system': join(__dirname, 'stdlib', 'index.ts'),
+  'system/utils': join(__dirname, 'stdlib', 'utils', 'index.ts'),
   'system/tools': join(__dirname, 'stdlib', 'tools', 'index.ts'),
 };
 

package/src/runtime/stdlib/index.ts

@@ -1,16 +1,12 @@
-// Standard library functions for Vibe scripts
-// Import with: import { uuid } from "system"
+// System module - re-exports utility functions for convenience
+// Prefer importing from "system/utils" directly.
+//
+// Import with: import { uuid, random, now } from "system"
+// Or directly: import { uuid, random, now } from "system/utils"
 //
-// These are TypeScript functions that can be called directly from Vibe scripts.
 // For AI tools, use: import { allTools } from "system/tools"
 //
 // NOTE: print() and env() are auto-imported core functions.
-// They are available everywhere without import and CANNOT be imported from "system".
+// They are available everywhere without import.
 
-/**
- * Generate a UUID v4.
- * @returns A new UUID string
- */
-export function uuid(): string {
-  return crypto.randomUUID();
-}
+export { uuid, now, random, jsonParse, jsonStringify } from './utils';

package/src/runtime/stdlib/tools/index.ts

@@ -2,7 +2,7 @@
 // Import with: import { allTools, readFile, writeFile, ... } from "system/tools"
 //
 // These are tools that AI models can use via the tools parameter.
-// For direct script use, import functions from "system" instead.
+// For utility functions (uuid, random, now, etc.), use: import { ... } from "system/utils"
 
 import type { VibeToolValue, ToolContext } from '../../tools/types';
 import { validatePathInSandbox } from '../../tools/security';
@@ -386,117 +386,6 @@ export const dirExists: VibeToolValue = {
   },
 };
 
-// =============================================================================
-// Utility Tools
-// =============================================================================
-
-export const env: VibeToolValue = {
-  __vibeTool: true,
-  name: 'env',
-  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 ?? '';
-  },
-};
-
-export const now: VibeToolValue = {
-  __vibeTool: true,
-  name: 'now',
-  schema: {
-    name: 'now',
-    description: 'Get the current timestamp in milliseconds.',
-    parameters: [],
-    returns: { type: 'number' },
-  },
-  executor: async () => {
-    return Date.now();
-  },
-};
-
-export const jsonParse: VibeToolValue = {
-  __vibeTool: true,
-  name: 'jsonParse',
-  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);
-  },
-};
-
-export const jsonStringify: VibeToolValue = {
-  __vibeTool: true,
-  name: 'jsonStringify',
-  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);
-  },
-};
-
-export const random: VibeToolValue = {
-  __vibeTool: true,
-  name: 'random',
-  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 Math.floor(Math.random() * (max - min + 1)) + min;
-    }
-
-    return Math.random();
-  },
-};
-
-export const uuid: VibeToolValue = {
-  __vibeTool: true,
-  name: 'uuid',
-  schema: {
-    name: 'uuid',
-    description: 'Generate a UUID v4.',
-    parameters: [],
-    returns: { type: 'string' },
-  },
-  executor: async () => {
-    return crypto.randomUUID();
-  },
-};
-
 // =============================================================================
 // System Tools
 // =============================================================================
@@ -567,12 +456,12 @@ export const runCode: VibeToolValue = {
   schema: {
     name: 'runCode',
     description:
-      'Execute TypeScript/JavaScript code in a sandboxed subprocess. ' +
+      'Execute TypeScript code in a sandboxed subprocess. IMPORTANT: Only write TypeScript code, never Python or other languages. ' +
       'All scope variables are automatically available as local variables. ' +
       'Use `return value` to pass results back. Bun APIs are available. ' +
       'Each execution creates a unique folder in .vibe-cache/ for intermediate files.',
     parameters: [
-      { name: 'code', type: { type: 'string' }, description: 'TypeScript/JavaScript code to execute', required: true },
+      { name: 'code', type: { type: 'string' }, description: 'TypeScript code to execute (not Python or other languages)', required: true },
       { name: 'scope', type: { type: 'object', additionalProperties: true }, description: 'Variables to make available in the code', required: false },
       { name: 'timeout', type: { type: 'number' }, description: 'Timeout in milliseconds (default: 30000)', required: false },
     ],
@@ -659,8 +548,8 @@ console.log('__VIBE_RESULT__' + JSON.stringify(__result));
 // =============================================================================
 
 /**
- * All tools - the complete set of standard tools.
- * Includes all file, search, directory, utility, and system tools.
+ * All tools - the complete set of standard AI tools.
+ * Includes file, search, directory, and system tools.
  */
 export const allTools: VibeToolValue[] = [
   // File tools
@@ -669,8 +558,6 @@ export const allTools: VibeToolValue[] = [
   glob, grep,
   // Directory tools
   mkdir, dirExists,
-  // Utility tools
-  env, now, jsonParse, jsonStringify, random, uuid,
   // System tools
   bash, runCode,
 ];
@@ -686,8 +573,6 @@ export const readonlyTools: VibeToolValue[] = [
   glob, grep,
   // Directory tools (read-only)
   dirExists,
-  // Utility tools
-  env, now, jsonParse, jsonStringify, random, uuid,
 ];
 
 /**
@@ -701,7 +586,5 @@ export const safeTools: VibeToolValue[] = [
   glob, grep,
   // Directory tools
   mkdir, dirExists,
-  // Utility tools
-  env, now, jsonParse, jsonStringify, random, uuid,
 ];
 

package/src/runtime/stdlib/utils/index.ts

@@ -0,0 +1,58 @@
+// System utility functions for Vibe scripts
+// Import with: import { uuid, now, random, jsonParse, jsonStringify } from "system/utils"
+//
+// These are utility functions that can be called directly from Vibe scripts.
+// For AI tools, use: import { readFile, writeFile, ... } from "system/tools"
+//
+// NOTE: print() and env() are auto-imported core functions.
+// They are available everywhere without import.
+
+/**
+ * Generate a UUID v4.
+ * @returns A new UUID string
+ */
+export function uuid(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Get the current timestamp in milliseconds.
+ * @returns Unix timestamp in milliseconds
+ */
+export function now(): number {
+  return Date.now();
+}
+
+/**
+ * Generate a random number.
+ * Without arguments, returns a float between 0 and 1.
+ * With min/max, returns an integer in the range [min, max] inclusive.
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @returns Random number
+ */
+export function random(min?: number, max?: number): number {
+  if (min !== undefined && max !== undefined) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
+  return Math.random();
+}
+
+/**
+ * Parse a JSON string into an object.
+ * @param text - The JSON string to parse
+ * @returns Parsed object
+ */
+export function jsonParse(text: string): unknown {
+  return JSON.parse(text);
+}
+
+/**
+ * Convert a value to a JSON string.
+ * @param value - The value to stringify
+ * @param pretty - Whether to format with indentation
+ * @returns JSON string
+ */
+export function jsonStringify(value: unknown, pretty?: boolean): string {
+  return pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+}

package/src/runtime/step.ts

@@ -10,6 +10,7 @@ import {
   execStatement,
   execStatements,
   execReturnValue,
+  execThrowError,
   execIfBranch,
   execEnterBlock,
   execExitBlock,
@@ -317,6 +318,9 @@ function executeInstruction(state: RuntimeState, instruction: Instruction): Runt
     case 'return_value':
       return execReturnValue(state);
 
+    case 'throw_error':
+      return execThrowError(state, instruction.location);
+
     case 'enter_block':
       return execEnterBlock(state, instruction.savedKeys);
 

package/src/runtime/test/core-functions.test.ts

@@ -176,22 +176,22 @@ if true {
   });
 
   describe('core functions cannot be imported', () => {
-    test('importing env from system fails', async () => {
+    test('importing env from system/utils fails (env is core function)', async () => {
       const ast = parse(`
-import { env } from "system"
+import { env } from "system/utils"
 let x = 1
 `);
       const runtime = new Runtime(ast, createMockProvider());
-      await expect(runtime.run()).rejects.toThrow("'env' is not exported from 'system'");
+      await expect(runtime.run()).rejects.toThrow("'env' is not exported from 'system/utils'");
     });
 
-    test('importing print from system fails', async () => {
+    test('importing print from system/utils fails (print is core function)', async () => {
       const ast = parse(`
-import { print } from "system"
+import { print } from "system/utils"
 let x = 1
 `);
       const runtime = new Runtime(ast, createMockProvider());
-      await expect(runtime.run()).rejects.toThrow("'print' is not exported from 'system'");
+      await expect(runtime.run()).rejects.toThrow("'print' is not exported from 'system/utils'");
     });
 
     test('importing from system/core is blocked', async () => {
@@ -202,10 +202,19 @@ let x = 1
       const runtime = new Runtime(ast, createMockProvider());
       await expect(runtime.run()).rejects.toThrow("'system/core' cannot be imported");
     });
+
+    test('importing from bare "system" fails (not a valid module)', async () => {
+      const ast = parse(`
+import { uuid } from "system"
+let x = 1
+`);
+      const runtime = new Runtime(ast, createMockProvider());
+      await expect(runtime.run()).rejects.toThrow("Unknown system module: 'system'");
+    });
   });
 
-  describe('library functions still require import', () => {
-    test('uuid requires import from system', async () => {
+  describe('utility functions require import from system/utils', () => {
+    test('uuid requires import', async () => {
       const ast = parse(`
 let id = uuid()
 `);
@@ -213,9 +222,9 @@ let id = uuid()
       await expect(runtime.run()).rejects.toThrow("'uuid' is not defined");
     });
 
-    test('uuid works when imported from system', async () => {
+    test('uuid works when imported from system/utils', async () => {
       const ast = parse(`
-import { uuid } from "system"
+import { uuid } from "system/utils"
 let id = uuid()
 `);
       const runtime = new Runtime(ast, createMockProvider());