@misterscan/sesi 1.2.3 → 1.3.0

package/README.md

@@ -2,7 +2,7 @@
   <img src="./sesi-logo.svg" alt="Sesi Logo" width="250" />
 </p>
 
-<h1 align="center">Sesi: A High-Performance Systems Language</h1>
+<h1 align="center">Sesi: A Concise, Legible Programming Language</h1>
 
 <p align="center">
   <em>Pronounced "say-see" — What you say, you'll see.</em>
@@ -10,13 +10,13 @@
 
 <p align="center">
   <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
-  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Interpreter-blue?logo=typescript">
   <img alt="Powered by Gemini" src="https://img.shields.io/badge/Powered%20By-Google%20Gemini-orange">
   <img alt="Framework" src="https://img.shields.io/badge/Node.js-Engine-success?logo=node.js">
 </p>
 
 <p align="center">
-  <strong>Sesi</strong> is a high-performance <strong>Systems Language</strong> designed for building resilient, stateful applications. It provides first-class primitives for process management, filesystem orchestration, and integrated reasoning, enabling developers to build complex logic with a fraction of the boilerplate required by traditional languages.
+  <strong>Sesi</strong> is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. Because the language itself is so simple, integrating external tools like shell commands or Reasoning models becomes effortless. It is a language built for clarity.
 </p>
 
 <p align="center">
@@ -79,6 +79,26 @@ sesi examples/08_model_call.sesi
 sesi examples.sesi
 ```
 
+Useful CLI shortcuts:
+
+```bash
+# Evaluate a quick snippet
+sesi -e "print 'hello'"
+
+# Ask the built-in co-pilot a question
+sesi -help "how do I use memory?"
+
+# Ask for help about a specific file
+sesi main/playground.sesi -h "why is this failing"
+
+# Encrypt or decrypt a script file
+sesi -encrypt my_script.sesi -p "my-password"
+sesi -decrypt my_script.sesi -p "my-password"
+
+# Run with sandbox restrictions disabled
+sesi main/start.sesi --local
+```
+
 # Local Execution (Development)
 
 If you choose not install `sesi` globally, use the helper npm scripts:
@@ -143,7 +163,7 @@ When embedding Sesi inside a host application, you can statically configure safe
 ```typescript
 const interpreter = new Interpreter(scriptDir, {
   safeMode: true,        // Enable full sandbox limits (on by default)
-  allowUnsafeFs: false,  // Block directory escapes (on by default)
+  allowLocalFs: false,  // Block directory escapes (on by default)
   allowedPaths: ['/var/tmp/sandbox'] // Custom strict whitelist directories
 });
 ```
@@ -155,11 +175,11 @@ const interpreter = new Interpreter(scriptDir, {
 - [Language Specification](./docs/SPECIFICATION.md)
 - [Language Comparison Showcase](./docs/COMPARISON.md)
 - [Built-in Functions](./docs/BUILTINS.md)
-- [Reasoning Guide](./docs/SYSTEMS_REASONING.md)
-- [Distributed Systems](./docs/DISTRIBUTED_SYSTEMS.md)
+- [Reasoning](./docs/REASONING.md)
+- [Concurrency Systems](./docs/CONCURRENCY.md)
 - [Runtime Architecture](./docs/ARCHITECTURE.md)
 
-## AI Agent Context
+## Agent Context
 
 The root-level `SKILLS.md` file is a workspace context file for AI agents. It records repo-specific constraints such as valid Sesi syntax expectations, execution conventions, and the intended meaning of directories like `main/` and `main/tests/`.
 
@@ -167,37 +187,83 @@ The root-level `SKILLS.md` file is a workspace context file for AI agents. It re
 
 ```
 Sesi/
-├── SKILLS.md             # AI-agent workspace context and repo guardrails
-├── index.html            # Sesi-generated landing page
-├── eslint.config.mjs     # ESLint configuration
-├── dist/                 # Compiled TypeScript output
-├── example.js            # Helper script to run basic examples
-├── example-ai.js         # Helper script to run Reasoning examples
-├── package.json          # Dependencies & scripts
-├── tsconfig.json         # TypeScript configuration
-├── QUICKSTART.md         # Quick start guide
-├── IMPLEMENTATION_SUMMARY.md # Progress and tracking
-├── src/
-│   ├── types.ts          # Type system & AST nodes
-│   ├── lexer.ts          # Tokenization
-│   ├── parser.ts         # AST generation
-│   ├── interpreter.ts    # Execution engine
-│   ├── builtins.ts       # Standard library
-│   ├── ai-runtime.ts     # Gemini integration
-│   └── index.ts          # Main entry point
+├── SKILLS.md                        # Workspace context and repo guardrails
+├── index.html                       # Sesi-generated systems landing page
+├── eslint.config.mjs                # ESLint configuration
+├── example.js                       # Helper script to run basic examples
+├── example-ai.js                    # Helper script to run reasoning examples
+├── examples.sesi                    # Central execution suite for examples
+├── README.md                        # Project overview
+├── QUICKSTART.md                    # Getting started guide
+├── package.json                     # Dependencies & scripts
+├── tsconfig.json                    # TypeScript configuration
+├── dist/                            # Compiled TypeScript output
+│
+├── src/                             # Source code
+│   ├── types.ts                     # Type definitions & AST nodes (400+ lines)
+│   ├── lexer.ts                     # Tokenization (350+ lines)
+│   ├── parser.ts                    # Recursive descent parser (700+ lines)
+│   ├── interpreter.ts               # Tree-walking interpreter (600+ lines)
+│   ├── builtins.ts                  # Built-in functions (250+ lines)
+│   ├── ai-runtime.ts                # Integrated reasoning integration (120+ lines)
+│   └── index.ts                     # Entry point (30+ lines)
+│
 ├── bin/
-│   └── sesi.js           # CLI executable
-├── examples/             # 18 sample programs demonstrating all features
-├── main/                 # Main entry and specialized tests
-│   ├── playground.sesi   # Main playground script
-│   ├── start.sesi        # Beginner script
-│   ├── build_website.sesi # Sesi-powered landing page generator
-│   └── tests/            # Debug and syntax scripts
-├── tests/                # Test suite
-└── docs/                 # Documentation (ARCHITECTURE, BUILTINS, SPECIFICATION, etc.)
+│   └── sesi.js                      # CLI executable
+│
+├── main/                            # Playgrounds & debugging
+│   ├── playground.sesi              # Main playground script
+│   ├── start.sesi                   # Beginner script
+│   └── tests/                       # Additional syntax validation scripts
+│
+├── docs/
+│   ├── SPECIFICATION.md             # Complete language spec (600+ lines)
+│   ├── ARCHITECTURE.md              # Runtime & system design (400+ lines)
+│   ├── BUILTINS.md                  # Built-in functions reference (450+ lines)
+│   ├── COMPARISON.md                # Language comparison showcase
+│   ├── CONCURRENCY.md               # Concurrency & coordination guide (>100 lines)
+│   ├── IMAGE_GENERATION.md          # Image generation guide (>100 lines)
+│   ├── REASONING.md                 # Reasoning and simple logic guide (>500 lines)
+│   ├── ROADMAP.md                   # V2-V4+ development plan (400+ lines)
+│   └── sesi_ai_chronicles.md        # AI project history & notes
+│
+├── examples/
+│   ├── 01_hello.sesi                # Hello World
+│   ├── 02_variables.sesi            # Variables & operations
+│   ├── 03_functions.sesi            # Functions with parameters
+│   ├── 04_conditionals.sesi         # If/else control flow
+│   ├── 05_loops.sesi                # While, for, for-in loops
+│   ├── 06_arrays_objects.sesi       # Collections
+│   ├── 07_prompts.sesi              # Reasoning blocks
+│   ├── 08_model_call.sesi           # Basic reasoning calls
+│   ├── 09_structured_output.sesi    # Type-safe reasoning responses
+│   ├── 10_code_generation.sesi      # Systems logic generation
+│   ├── 11_memory_conversation.sesi  # Multi-turn stateful reasoning
+│   ├── 12_classification.sesi       # Systems classification loop
+│   ├── 13_data_pipeline.sesi        # Complete systems pipeline
+│   ├── 14_folder_explainer.sesi     # Directory parsing & reasoning
+│   ├── 15_image_generation.sesi     # Image generation API test
+│   ├── 16_modules.sesi              # Modules & std library namespaces
+│   ├── 17_http_client.sesi          # Network GET/POST client
+│   ├── 18_parallel_requests.sesi    # Parallel requests concurrency
+│   ├── 19_search_web.sesi           # Web search integration
+│   ├── 20_model_aliases.sesi        # Custom model naming aliases
+│   ├── 21_custom_tools.sesi         # Custom runtime tool definitions
+│   └── 22_reasoning_plus_custom_tools.sesi # Reasoning composed with custom tools
+│
+└── tests/                           # Engine test suite
+    ├── basic.test.ts                # Core parsing & evaluation tests
+    ├── cache.test.ts                # Execution caching tests
+    ├── http.test.ts                 # Web request builtins testing
+    ├── module.test.ts               # Imports & module loading tests
+    ├── parallel.test.ts             # Concurrent execution tests
+    ├── security.test.ts             # Sandbox & guardrail tests
+    ├── test-gemini.ts               # Base model integration test
+    ├── test-gemini2.ts              # Extended model integration test
+    └── workflow.test.ts             # Complex sequence workflows tests
 ```
 
-## Version 1.2 Features (In Progress)
+## Version 1.3 Features (In Progress)
 
 ### Core Language ✅
 

package/bin/sesi.js

@@ -1,57 +1,182 @@
 #!/usr/bin/env node
 require('@dotenvx/dotenvx').config();
-const { runSesiFile } = require('../dist/index.js');
+const { runSesiFile, runSesi } = require('../dist/index.js');
 const fs = require('fs');
 const path = require('path');
 
 const args = process.argv.slice(2);
 
-if (args.length === 0) {
-  console.log(`
-Sesi Programming Language v1.2.2
+const argsHeader = `
+Sesi Programming Language v1.3.0
 
 Usage:
-  sesi <file>          Run a Sesi program
-  sesi -help <query>   Ask for help from our Sesi Co-Pilot
-  sesi --help <query>  
-  sesi -h <query>      
+  sesi <file> [options]  Run a Sesi program
+  sesi -e "code"         Evaluate Sesi code directly
+  sesi -help <query>    Ask for help from our Sesi Co-Pilot
 
   Options:
-  --version            Show version
+  --local               Disable safe mode (careful!)
+  --allowed-paths <p>    Comma-separated list of allowed directories
+  -encrypt <file>        Encrypt a file
+  -decrypt <file>        Decrypt a file
+  -p, --password <pass>  Password for encryption/decryption
+  --version              Show version
+  --help, -h             Show this help
 
 Examples:
   sesi main/start.sesi
-  sesi examples/01_hello.sesi
-  sesi -help "how do I parse a json string?"
-  `);
-  process.exit(0);
+  sesi -e "print 'hello'"
+  sesi -help "how do I use memory?"
+`;
+
+function parseArgs(args) {
+  const options = {
+    file: null,
+    eval: null,
+    helpQuery: null,
+    helpFile: null,
+    encryptFile: null,
+    decryptFile: null,
+    password: null,
+    sesiOptions: {
+      safeMode: true,
+      allowedPaths: [process.cwd()]
+    }
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const isHelpFlag = arg === '--help' || arg === '-help' || arg === '-h';
+
+    if (arg === '--version') {
+      console.log('Sesi v1.3.0');
+      process.exit(0);
+    } else if (isHelpFlag && i === 0 && !options.file && !options.eval) {
+      if (args[i + 1] && !args[i + 1].startsWith('-')) {
+        options.helpQuery = args.slice(i + 1).join(' ').trim();
+        break;
+      } else {
+        console.log(argsHeader);
+        process.exit(0);
+      }
+    } else if (isHelpFlag && options.file) {
+      options.helpFile = options.file;
+      options.helpQuery = args[i + 1] && !args[i + 1].startsWith('-')
+        ? args.slice(i + 1).join(' ').trim()
+        : 'Help me understand this file.';
+      break;
+    } else if (arg === '-e' || arg === '--eval') {
+      options.eval = args[++i];
+    } else if (arg === '-encrypt' || arg === '--encrypt') {
+      options.encryptFile = args[++i];
+    } else if (arg === '-decrypt' || arg === '--decrypt') {
+      options.decryptFile = args[++i];
+    } else if (arg === '-p' || arg === '--password') {
+      options.password = args[++i];
+    } else if (arg === '--local') {
+      options.sesiOptions.safeMode = false;
+      options.sesiOptions.allowLocalFs = true;
+    } else if (arg === '--allowed-paths') {
+      const paths = args[++i].split(',');
+      options.sesiOptions.allowedPaths.push(...paths.map(p => path.resolve(p)));
+    } else if (!arg.startsWith('-') && !options.file) {
+      options.file = arg;
+    }
+  }
+
+  return options;
 }
 
-if (args[0] === '--help' || args[0] === '-help' || args[0] === '-h') {
-  let queryText = args.slice(1).join(' ').trim();
-  if (!queryText) {
-    queryText = "how do I parse a json string?";
+const parsed = parseArgs(args);
+
+async function main() {
+  if (!parsed.file && !parsed.eval && !parsed.helpQuery && !parsed.encryptFile && !parsed.decryptFile) {
+    console.log(argsHeader);
+    process.exit(0);
   }
-  fs.writeFileSync('query.txt', queryText, 'utf-8');
-
-  const copilotPath = path.join(__dirname, '../main/sesi_db_chatbot.sesi');
-  runSesiFile(copilotPath).catch((error) => {
-    console.error('Fatal error in Sesi Co-Pilot:', error.message);
-    process.exit(1);
-  });
-} else if (args[0] === '--version') {
-  console.log('Sesi v1.2.2');
-  process.exit(0);
-} else {
-  const filePath = args[0];
-
-  if (!fs.existsSync(filePath)) {
-    console.error(`Error: File not found: ${filePath}`);
-    process.exit(1);
+
+  if (parsed.encryptFile || parsed.decryptFile) {
+    if (!parsed.password) {
+      console.error('Error: Password is required for encryption/decryption. Use -p <password>.');
+      process.exit(1);
+    }
+    const crypto = require('crypto');
+    const targetFile = parsed.encryptFile || parsed.decryptFile;
+    const isEncrypt = !!parsed.encryptFile;
+    
+    if (!fs.existsSync(targetFile)) {
+      console.error(`Error: File not found: ${targetFile}`);
+      process.exit(1);
+    }
+    
+    const content = fs.readFileSync(targetFile, 'utf-8');
+    try {
+      const algorithm = 'aes-256-cbc';
+      const key = crypto.createHash('sha256').update(String(parsed.password)).digest();
+      
+      if (isEncrypt) {
+        const iv = crypto.randomBytes(16);
+        const cipher = crypto.createCipheriv(algorithm, key, iv);
+        let encrypted = cipher.update(content, 'utf8', 'hex');
+        encrypted += cipher.final('hex');
+        const finalOutput = iv.toString('hex') + ':' + encrypted;
+        fs.writeFileSync(targetFile, finalOutput, 'utf-8');
+        console.log(`Successfully encrypted ${targetFile}`);
+      } else {
+        const parts = content.split(':');
+        if (parts.length !== 2) throw new Error('Invalid encrypted format');
+        const iv = Buffer.from(parts[0], 'hex');
+        const decipher = crypto.createDecipheriv(algorithm, key, iv);
+        let decrypted = decipher.update(parts[1], 'hex', 'utf8');
+        decrypted += decipher.final('utf8');
+        fs.writeFileSync(targetFile, decrypted, 'utf-8');
+        console.log(`Successfully decrypted ${targetFile}`);
+      }
+    } catch (e) {
+      console.error(`Error during ${isEncrypt ? 'encryption' : 'decryption'}:`, e.message);
+      process.exit(1);
+    }
+    return;
   }
 
-  runSesiFile(filePath).catch((error) => {
-    console.error('Fatal error:', error.message);
-    process.exit(1);
-  });
-}
+  if (parsed.helpQuery) {
+    fs.writeFileSync('query.txt', parsed.helpQuery, 'utf-8');
+    if (parsed.helpFile) {
+      const resolvedFile = path.resolve(parsed.helpFile);
+      const fileContext = fs.readFileSync(resolvedFile, 'utf-8');
+      fs.writeFileSync('help_context.txt', `File: ${resolvedFile}\n\n${fileContext}`, 'utf-8');
+    } else if (fs.existsSync('help_context.txt')) {
+      fs.unlinkSync('help_context.txt');
+    }
+    const copilotPath = path.join(__dirname, '../main/sesi_db_chatbot.sesi');
+    await runSesiFile(copilotPath).catch((error) => {
+      console.error('Fatal error in Sesi Co-Pilot:', error.message);
+      process.exit(1);
+    });
+  } else if (parsed.eval) {
+    await runSesi(parsed.eval, process.cwd(), parsed.sesiOptions).catch((error) => {
+      console.error('Fatal error:', error.message);
+      process.exit(1);
+    });
+  } else if (parsed.file === '-') {
+    let input = '';
+    process.stdin.on('data', data => { input += data; });
+    process.stdin.on('end', async () => {
+      await runSesi(input, process.cwd(), parsed.sesiOptions).catch((error) => {
+        console.error('Fatal error:', error.message);
+        process.exit(1);
+      });
+    });
+  } else if (parsed.file) {
+    if (!fs.existsSync(parsed.file)) {
+      console.error(`Error: File not found: ${parsed.file}`);
+      process.exit(1);
+    }
+    await runSesiFile(parsed.file, parsed.sesiOptions).catch((error) => {
+      console.error('Fatal error:', error.message);
+      process.exit(1);
+    });
+  }
+}
+
+main();

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAgCxD,wBAAgB,WAAW,CAAC,WAAW,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAgf3E;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAIrD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAY7C;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CAWjE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAmBrD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAQtE"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAiC1E,wBAAgB,WAAW,CAAC,WAAW,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAirB3E;AAqBD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAIrD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAY7C;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,OAAO,CAWjE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAmBrD;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAQtE"}

package/dist/builtins.js

@@ -39,15 +39,18 @@ exports.stripPrototypes = stripPrototypes;
 exports.isEqual = isEqual;
 exports.stringify = stringify;
 exports.compareValues = compareValues;
+// Built-in functions for Sesi
+const types_1 = require("./types");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const ai_runtime_1 = require("./ai-runtime");
 function ensureSafePath(filePath, interpreter, baseDir = process.cwd()) {
     const resolved = path.resolve(baseDir, filePath);
-    const allowUnsafeFs = interpreter?.allowUnsafeFs ?? (process.env.SESI_UNSAFE_FS === 'true');
+    const allowLocalFs = interpreter?.allowLocalFs ?? (process.env.SESI_LOCAL_FS === 'true');
     const safeMode = interpreter?.safeMode ?? (process.env.SESI_SAFE_MODE !== 'false');
-    // If in safe mode, allowUnsafeFs is strictly disabled.
-    if (allowUnsafeFs && !safeMode) {
+    // If in safe mode, allowLocalFs is strictly disabled.
+    if (allowLocalFs && !safeMode) {
         return resolved;
     }
     const allowedDirs = [...(interpreter?.allowedPaths || [process.cwd()])];
@@ -475,6 +478,113 @@ function getBuiltins(interpreter) {
         isBuiltin: true,
         builtin: () => Math.random(),
     });
+    builtins.set('set_alias', {
+        type: 'function',
+        name: 'set_alias',
+        params: [{ name: 'alias' }, { name: 'model' }],
+        body: {},
+        closure: {},
+        isBuiltin: true,
+        builtin: (alias, model) => {
+            if (typeof alias !== 'string' || typeof model !== 'string') {
+                throw new Error('set_alias expects (string alias, string model)');
+            }
+            if (!interpreter || typeof interpreter.setModelAlias !== 'function') {
+                throw new Error('set_alias interpreter reference is missing');
+            }
+            interpreter.setModelAlias(alias, model);
+            return true;
+        },
+    });
+    builtins.set('error_type', {
+        type: 'function',
+        name: 'error_type',
+        params: [{ name: 'type' }, { name: 'message' }, { name: 'data', defaultValue: null }],
+        body: {},
+        closure: {},
+        isBuiltin: true,
+        builtin: (typeVal, messageVal, dataVal = null) => {
+            if (typeof typeVal !== 'string' || typeVal.trim() === '') {
+                throw new Error('error_type expects a non-empty string type');
+            }
+            if (typeof messageVal !== 'string') {
+                throw new Error('error_type expects a string message');
+            }
+            const obj = Object.create(null);
+            obj.type = typeVal;
+            obj.message = messageVal;
+            obj.data = dataVal;
+            return obj;
+        },
+    });
+    builtins.set('raise_error', {
+        type: 'function',
+        name: 'raise_error',
+        params: [
+            { name: 'type_or_error' },
+            { name: 'message', defaultValue: '' },
+            { name: 'data', defaultValue: null },
+        ],
+        body: {},
+        closure: {},
+        isBuiltin: true,
+        builtin: (typeOrError, messageVal = '', dataVal = null) => {
+            if (typeof typeOrError === 'object' && typeOrError !== null && !Array.isArray(typeOrError)) {
+                const type = typeOrError.type;
+                const message = typeOrError.message;
+                const data = typeOrError.data ?? null;
+                if (typeof type !== 'string' || type.trim() === '' || typeof message !== 'string') {
+                    throw new Error('raise_error expects error object with string type and message');
+                }
+                throw new types_1.SesiRuntimeError(type, message, data);
+            }
+            if (typeof typeOrError !== 'string' || typeOrError.trim() === '') {
+                throw new Error('raise_error expects first argument to be error object or non-empty string type');
+            }
+            if (typeof messageVal !== 'string' || messageVal.trim() === '') {
+                throw new Error('raise_error expects a non-empty string message');
+            }
+            throw new types_1.SesiRuntimeError(typeOrError, messageVal, dataVal);
+        },
+    });
+    builtins.set('define_tool', {
+        type: 'function',
+        name: 'define_tool',
+        params: [{ name: 'name' }, { name: 'fn' }, { name: 'description', defaultValue: '' }],
+        body: {},
+        closure: {},
+        isBuiltin: true,
+        builtin: (name, fn, description = '') => {
+            if (typeof name !== 'string') {
+                throw new Error('define_tool expects first argument to be a string name');
+            }
+            if (typeof fn !== 'object' || !fn || fn.type !== 'function') {
+                throw new Error('define_tool expects second argument to be a function');
+            }
+            if (description !== null && typeof description !== 'string') {
+                throw new Error('define_tool description must be a string');
+            }
+            if (!interpreter || typeof interpreter.defineCustomTool !== 'function') {
+                throw new Error('define_tool interpreter reference is missing');
+            }
+            interpreter.defineCustomTool(name, fn, typeof description === 'string' ? description : '');
+            return true;
+        },
+    });
+    builtins.set('list_tools', {
+        type: 'function',
+        name: 'list_tools',
+        params: [],
+        body: {},
+        closure: {},
+        isBuiltin: true,
+        builtin: () => {
+            if (!interpreter || typeof interpreter.listCustomToolNames !== 'function') {
+                throw new Error('list_tools interpreter reference is missing');
+            }
+            return interpreter.listCustomToolNames();
+        },
+    });
     builtins.set('web_get', {
         type: 'function',
         name: 'web_get',
@@ -556,7 +666,7 @@ function getBuiltins(interpreter) {
                 const InterpreterClass = interpreter.constructor;
                 const subInterpreter = new InterpreterClass(undefined, {
                     safeMode: interpreter.safeMode,
-                    allowUnsafeFs: interpreter.allowUnsafeFs,
+                    allowLocalFs: interpreter.allowLocalFs,
                     allowedPaths: interpreter.allowedPaths
                 });
                 subInterpreter.prompts = new Map(interpreter.prompts);
@@ -566,8 +676,90 @@ function getBuiltins(interpreter) {
             return await Promise.all(promises);
         }
     });
+    const workflowBuiltin = {
+        type: 'function',
+        name: 'workflow',
+        params: [{ name: 'steps' }, { name: 'input', defaultValue: '' }],
+        body: {},
+        closure: {},
+        isBuiltin: true,
+        builtin: async (...args) => {
+            const [stepsVal, inputVal] = args;
+            if (!Array.isArray(stepsVal)) {
+                throw new Error('workflow expects steps to be an array of objects');
+            }
+            const initialInput = stringify(inputVal ?? '');
+            let previous = initialInput;
+            const outputs = [];
+            for (let i = 0; i < stepsVal.length; i++) {
+                const step = stepsVal[i];
+                if (typeof step !== 'object' || step === null || Array.isArray(step)) {
+                    throw new Error(`workflow step ${i + 1} must be an object`);
+                }
+                const stepObj = step;
+                const rawPrompt = stepObj.prompt;
+                if (typeof rawPrompt !== 'string' || rawPrompt.trim() === '') {
+                    throw new Error(`workflow step ${i + 1} requires a non-empty string prompt`);
+                }
+                let prompt = rawPrompt;
+                const fromRef = typeof stepObj.from === 'string' ? stepObj.from.trim() : '';
+                if (fromRef !== '') {
+                    const context = resolveWorkflowReference(fromRef, initialInput, previous, outputs);
+                    prompt = context === '' ? rawPrompt : `${rawPrompt} ${context}`;
+                }
+                else {
+                    // Intuitive default wiring: first step uses input, later steps use previous output.
+                    const defaultRef = i === 0 ? 'input' : 'previous';
+                    const context = resolveWorkflowReference(defaultRef, initialInput, previous, outputs);
+                    prompt = context === '' ? rawPrompt : `${rawPrompt} ${context}`;
+                }
+                const modelName = typeof stepObj.model === 'string' && stepObj.model.trim() !== ''
+                    ? stepObj.model
+                    : 'gemini-3.1-flash-lite';
+                const model = interpreter && typeof interpreter.resolveModelName === 'function'
+                    ? interpreter.resolveModelName(modelName)
+                    : modelName;
+                const response = await ai_runtime_1.aiRuntime.callModel({
+                    model,
+                    prompt,
+                    temperature: typeof stepObj.temperature === 'number' ? stepObj.temperature : undefined,
+                    maxTokens: typeof stepObj.max_tokens === 'number' ? stepObj.max_tokens : undefined,
+                    topK: typeof stepObj.top_k === 'number' ? stepObj.top_k : undefined,
+                    topP: typeof stepObj.top_p === 'number' ? stepObj.top_p : undefined,
+                    thinkingLevel: typeof stepObj.thinkingLevel === 'object' || typeof stepObj.thinkingLevel === 'string'
+                        ? stepObj.thinkingLevel
+                        : undefined,
+                    cache: typeof stepObj.cache === 'boolean' ? stepObj.cache : undefined,
+                    search: typeof stepObj.search === 'boolean' ? stepObj.search : undefined,
+                });
+                previous = response.text;
+                outputs.push(response.text);
+            }
+            const result = Object.create(null);
+            result.input = initialInput;
+            result.steps = outputs;
+            result.final = previous;
+            return result;
+        },
+    };
+    builtins.set('workflow', workflowBuiltin);
     return builtins;
 }
+function resolveWorkflowReference(key, input, previous, outputs) {
+    if (key === 'input')
+        return input;
+    if (key === 'previous')
+        return previous;
+    const stepMatch = /^step(\d+)$/.exec(key);
+    if (stepMatch) {
+        const index = Number(stepMatch[1]) - 1;
+        if (index >= 0 && index < outputs.length) {
+            return outputs[index];
+        }
+        throw new Error(`workflow reference ${key} is out of range`);
+    }
+    throw new Error(`workflow reference ${key} is invalid`);
+}
 function isTruthy(value) {
     if (value === null || value === false)
         return false;