@o-lang/olang 1.0.0

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2025 Olalekan Ogundipe
+
+Permission is hereby granted, free of charge, ...

package/README.md

@@ -0,0 +1,42 @@
+# O-Lang Kernel
+
+Minimal O-Lang language core (parser + runtime) for agent orchestration.
+
+---
+
+## Overview
+
+O-Lang is a **plain-English orchestration language** designed to let users define workflows as sequences of actions.  
+This repository ships the **kernel only**—no agents, no integrations, no heavy dependencies. It is **language first**, not a framework.
+
+> “Be the grammar. Let others build the world.” — Philosophy behind O-Lang
+
+### What This Repository Ships
+
+- **Parser** – Convert `.olang` files into an abstract syntax tree (AST).  
+- **Runtime** – Execute the AST with a user-provided `agentResolver` function.  
+- **CLI** – `olang run workflow.olang` example runner.  
+- **Spec & Examples** – Minimal documentation for syntax and execution.
+
+### What This Repository Does NOT Ship
+
+- Agents (Slack, Groq, Google Drive, OCR, etc.)  
+- PDF parsing, OCR, or databases  
+- Configuration files (`.env`, secrets)  
+- Desktop UI or setup wizard  
+
+> Agents, databases, and other integrations are the responsibility of the user or third-party packages.
+
+---
+
+## Getting Started
+
+### Installation
+
+```bash
+# Clone the repo
+git clone https://github.com/O-Lang-Central/olang-kernel.git
+cd olang
+
+# Install dependencies (minimal parser/runtime)
+npm install

package/cli.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+const { Command } = require('commander');
+const { parse } = require('./src/parser');
+const { execute } = require('./src/runtime');
+const fs = require('fs');
+const path = require('path');
+
+async function defaultMockResolver(action, context) {
+  if (action.startsWith('Search for ')) {
+    return {
+      title: "HR Policy 2025",
+      text: "Employees are entitled to 20 days of paid leave per year. All requests must be submitted via the HR portal.",
+      url: "mock://hr-policy"
+    };
+  }
+  if (action.startsWith('Ask ')) {
+    return "✅ [Mock] Summarized for staff.";
+  }
+  if (action.startsWith('Notify ')) {
+    const recipient = action.match(/Notify (\S+)/)?.[1] || 'user@example.com';
+    return `📬 Notification sent to ${recipient}`;
+  }
+  if (action.startsWith('Debrief ') || action.startsWith('Evolve ')) {
+    console.log(`[O-Lang] ${action}`);
+    return 'Acknowledged';
+  }
+  return `[Unhandled: ${action}]`;
+}
+
+function createResolverChain(resolvers) {
+  return async (action, context) => {
+    for (const resolver of resolvers) {
+      try {
+        const result = await resolver(action, context);
+        if (result !== null && result !== undefined) {
+          return result;
+        }
+      } catch (err) {
+        console.error(`❌ Resolver error for action "${action}":`, err.message);
+        throw err;
+      }
+    }
+    return `[Unhandled: ${action}]`;
+  };
+}
+
+function loadSingleResolver(specifier) {
+  if (!specifier) return defaultMockResolver;
+
+  try {
+    const resolver = require(specifier);
+    if (typeof resolver !== 'function') {
+      throw new Error(`Resolver must export a function`);
+    }
+    console.log(`📦 Loaded resolver: ${specifier}`);
+    return resolver;
+  } catch (e1) {
+    try {
+      const absolutePath = path.resolve(process.cwd(), specifier);
+      const resolver = require(absolutePath);
+      console.log(`📁 Loaded resolver: ${absolutePath}`);
+      return resolver;
+    } catch (e2) {
+      throw new Error(`Failed to load resolver '${specifier}':\n  npm: ${e1.message}\n  file: ${e2.message}`);
+    }
+  }
+}
+
+function loadResolverChain(specifiers) {
+  if (!specifiers || specifiers.length === 0) {
+    console.log('ℹ️ No resolver provided. Using default mock resolver.');
+    return defaultMockResolver;
+  }
+
+  const resolvers = specifiers.map(loadSingleResolver);
+  return createResolverChain(resolvers);
+}
+
+const program = new Command();
+
+program
+  .name('olang')
+  .description('O-Lang CLI: run .olang workflows')
+  .command('run <file>')
+  .option('-r, --resolver <specifier>', 'Resolver (npm package or local path). Can be used multiple times.\nExample:\n  -r @o-lang/llm-groq\n  -r @o-lang/notify-telegram', (val, acc) => {
+    acc.push(val);
+    return acc;
+  }, [])
+  .option('-i, --input <k=v>', 'Input parameters', (val, acc = {}) => {
+    const [k, v] = val.split('=');
+    acc[k] = v;
+    return acc;
+  }, {})
+  .action(async (file, options) => {
+    try {
+      const content = fs.readFileSync(file, 'utf8');
+      const workflow = parse(content);
+      const resolver = loadResolverChain(options.resolver);
+      const result = await execute(workflow, options.input, resolver);
+      console.log('\n=== Workflow Result ===');
+      console.log(JSON.stringify(result, null, 2));
+    } catch (err) {
+      console.error('❌ Error:', err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);
+
+
+
+
+
+
+
+
+
+// #!/usr/bin/env node
+// const { Command } = require('commander');
+// const { parse } = require('./src/parser');
+// const { execute } = require('./src/runtime');
+// const fs = require('fs');
+// const path = require('path');
+
+// // Default mock resolver (for demos)
+// async function defaultMockResolver(action, context) {
+//   if (action.startsWith('Search for ')) {
+//     return {
+//       title: "HR Policy 2025",
+//       text: "Employees are entitled to 20 days of paid leave per year. All requests must be submitted via the HR portal.",
+//       url: "mock://hr-policy"
+//     };
+//   }
+//   if (action.startsWith('Ask ')) {
+//     return "✅ [Mock] Summarized for staff.";
+//   }
+//   if (action.startsWith('Notify ')) {
+//     const recipient = action.match(/Notify (\S+)/)?.[1] || 'user@example.com';
+//     return `📬 Notification sent to ${recipient}`;
+//   }
+//   if (action.startsWith('Debrief ') || action.startsWith('Evolve ')) {
+//     console.log(`[O-Lang] ${action}`);
+//     return 'Acknowledged';
+//   }
+//   return `[Unhandled: ${action}]`;
+// }
+
+// function loadResolver(resolverPath) {
+//   if (!resolverPath) {
+//     console.log('ℹ️ No resolver provided. Using default mock resolver.');
+//     return defaultMockResolver;
+//   }
+
+//   try {
+//     // Resolve relative to current working directory
+//     const absolutePath = path.resolve(process.cwd(), resolverPath);
+//     return require(absolutePath);
+//   } catch (err) {
+//     console.error(`❌ Failed to load resolver from: ${resolverPath}`);
+//     console.error(`Error: ${err.message}`);
+//     process.exit(1);
+//   }
+// }
+
+// const program = new Command();
+
+// program
+//   .name('olang')
+//   .description('O-Lang CLI: run .olang workflows')
+//   .command('run <file>')
+//   .option('-r, --resolver <path>', 'Path to agent resolver (e.g., ./examples/groq-slack-resolver.js)')
+//   .option('-i, --input <k=v>', 'Input parameters', (val, acc = {}) => {
+//     const [k, v] = val.split('=');
+//     acc[k] = v;
+//     return acc;
+//   }, {})
+//   .action(async (file, options) => {
+//     try {
+//       const content = fs.readFileSync(file, 'utf8');
+//       const workflow = parse(content);
+//       const resolver = loadResolver(options.resolver);
+//       const result = await execute(workflow, options.input, resolver);
+//       console.log('\n=== Workflow Result ===');
+//       console.log(JSON.stringify(result, null, 2));
+//     } catch (err) {
+//       console.error('❌ Error:', err.message);
+//       process.exit(1);
+//     }
+//   });
+
+// program.parse(process.argv);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@o-lang/olang",
+  "version": "1.0.0",
+  "author": "Olalekan Ogundipe <info@workfily.com>",
+  "description": "O-Lang: A governance language for user-directed, rule-enforced agent workflows",
+  "main": "./src/index.js",
+  "bin": {
+    "olang": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node cli.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "dotenv": "^17.2.3"
+  },
+  "keywords": ["agent", "governance", "workflow", "llm", "automation", "olang", "ai"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/O-Lang-Central/olang-kernel.git"
+  },
+  "homepage": "https://github.com/O-Lang-Central/olang-kernel"
+}

package/src/parser.js

@@ -0,0 +1,462 @@
+// src/parser.js
+function parse(code) {
+  const lines = code
+    .split(/\r?\n/)
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('#') && !l.startsWith('//'));
+
+  const workflow = {
+    name: 'Unnamed Workflow',
+    parameters: [],
+    steps: [],
+    returnValues: []
+  };
+
+  let i = 0;
+  while (i < lines.length) {
+    let line = lines[i];
+
+    // Workflow
+    const wfMatch = line.match(/^Workflow\s+"([^"]+)"(?:\s+with\s+(.+))?/i);
+    if (wfMatch) {
+      workflow.name = wfMatch[1];
+      workflow.parameters = wfMatch[2] ? wfMatch[2].split(',').map(p => p.trim()) : [];
+      i++;
+      continue;
+    }
+
+    // Step
+    const stepMatch = line.match(/^Step\s+(\d+)\s*:\s*(.+)$/i);
+    if (stepMatch) {
+      workflow.steps.push({
+        type: 'action',
+        stepNumber: parseInt(stepMatch[1], 10),
+        actionRaw: stepMatch[2].trim(),
+        saveAs: null,
+        constraints: {} // Initialize constraints
+      });
+      i++;
+      continue;
+    }
+
+    // Save as
+    const saveMatch = line.match(/^Save as\s+(.+)$/i);
+    if (saveMatch && workflow.steps.length > 0) {
+      workflow.steps[workflow.steps.length - 1].saveAs = saveMatch[1].trim();
+      i++;
+      continue;
+    }
+
+    // Constraint (NEW: parse key = value lines and attach to last step)
+    const constraintMatch = line.match(/^Constraint:\s*(.+)$/i);
+    if (constraintMatch && workflow.steps.length > 0) {
+      const lastStep = workflow.steps[workflow.steps.length - 1];
+      if (!lastStep.constraints) lastStep.constraints = {};
+
+      const constraintLine = constraintMatch[1].trim();
+      const eq = constraintLine.match(/^([^=]+)=\s*(.+)$/);
+      if (eq) {
+        let key = eq[1].trim();
+        let value = eq[2].trim();
+
+        // Parse list: [a, b, c]
+        if (value.startsWith('[') && value.endsWith(']')) {
+          value = value.slice(1, -1).split(',').map(v => v.trim().replace(/^"/, '').replace(/"$/, ''));
+        }
+        // Parse number
+        else if (!isNaN(value)) {
+          value = Number(value);
+        }
+        // Keep string (remove quotes if present)
+        else if (value.startsWith('"') && value.endsWith('"')) {
+          value = value.slice(1, -1);
+        }
+
+        lastStep.constraints[key] = value;
+      }
+      i++;
+      continue;
+    }
+
+    // If
+    const ifMatch = line.match(/^If\s+(.+)\s+then$/i);
+    if (ifMatch) {
+      const condition = ifMatch[1].trim();
+      const body = [];
+      i++;
+      while (i < lines.length && !/^\s*End If\s*$/i.test(lines[i])) {
+        body.push(lines[i]);
+        i++;
+      }
+      if (i < lines.length) i++; // skip 'End If'
+      workflow.steps.push({ type: 'if', condition, body: parseBlock(body) });
+      continue;
+    }
+
+    // Parallel
+    const parMatch = line.match(/^Run in parallel$/i);
+    if (parMatch) {
+      const steps = [];
+      i++;
+      while (i < lines.length && !/^\s*End\s*$/i.test(lines[i])) {
+        steps.push(lines[i]);
+        i++;
+      }
+      if (i < lines.length) i++;
+      workflow.steps.push({ type: 'parallel', steps: parseBlock(steps) });
+      continue;
+    }
+
+    // Connect
+    const connMatch = line.match(/^Connect\s+"([^"]+)"\s+using\s+"([^"]+)"$/i);
+    if (connMatch) {
+      workflow.steps.push({
+        type: 'connect',
+        resource: connMatch[1],
+        endpoint: connMatch[2]
+      });
+      i++;
+      continue;
+    }
+
+    // Agent ... uses ...
+    const agentUseMatch = line.match(/^Agent\s+"([^"]+)"\s+uses\s+"([^"]+)"$/i);
+    if (agentUseMatch) {
+      workflow.steps.push({
+        type: 'agent_use',
+        logicalName: agentUseMatch[1],
+        resource: agentUseMatch[2]
+      });
+      i++;
+      continue;
+    }
+
+    // Debrief
+    const debriefMatch = line.match(/^Debrief\s+(\w+)\s+with\s+"(.+)"$/i);
+    if (debriefMatch) {
+      workflow.steps.push({
+        type: 'debrief',
+        agent: debriefMatch[1],
+        message: debriefMatch[2]
+      });
+      i++;
+      continue;
+    }
+
+    // Evolve
+    const evolveMatch = line.match(/^Evolve\s+(\w+)\s+using\s+feedback:\s+"(.+)"$/i);
+    if (evolveMatch) {
+      workflow.steps.push({
+        type: 'evolve',
+        agent: evolveMatch[1],
+        feedback: evolveMatch[2]
+      });
+      i++;
+      continue;
+    }
+
+    // Prompt
+    const promptMatch = line.match(/^Prompt user to\s+"(.+)"$/i);
+    if (promptMatch) {
+      workflow.steps.push({
+        type: 'prompt',
+        question: promptMatch[1],
+        saveAs: null
+      });
+      i++;
+      continue;
+    }
+
+    // Persist
+    const persistMatch = line.match(/^Persist\s+(.+)\s+to\s+"(.+)"$/i);
+    if (persistMatch) {
+      workflow.steps.push({
+        type: 'persist',
+        variable: persistMatch[1].trim(),
+        target: persistMatch[2]
+      });
+      i++;
+      continue;
+    }
+
+    // Emit
+    const emitMatch = line.match(/^Emit\s+"(.+)"\s+with\s+(.+)$/i);
+    if (emitMatch) {
+      workflow.steps.push({
+        type: 'emit',
+        event: emitMatch[1],
+        payload: emitMatch[2].trim()
+      });
+      i++;
+      continue;
+    }
+
+    // Return
+    const returnMatch = line.match(/^Return\s+(.+)$/i);
+    if (returnMatch) {
+      workflow.returnValues = returnMatch[1].split(',').map(v => v.trim());
+      i++;
+      continue;
+    }
+
+    i++;
+  }
+
+  return workflow;
+}
+
+function parseBlock(lines) {
+  const steps = [];
+  let current = null;
+  for (const line of lines) {
+    const stepMatch = line.match(/^Step\s+(\d+)\s*:\s*(.+)$/i);
+    if (stepMatch) {
+      current = {
+        type: 'action',
+        stepNumber: parseInt(stepMatch[1], 10),
+        actionRaw: stepMatch[2].trim(),
+        saveAs: null,
+        constraints: {}
+      };
+      steps.push(current);
+      continue;
+    }
+    const saveMatch = line.match(/^Save as\s+(.+)$/i);
+    if (saveMatch && current) {
+      current.saveAs = saveMatch[1].trim();
+    }
+    const debriefMatch = line.match(/^Debrief\s+(\w+)\s+with\s+"(.+)"$/i);
+    if (debriefMatch) {
+      steps.push({ type: 'debrief', agent: debriefMatch[1], message: debriefMatch[2] });
+    }
+    const evolveMatch = line.match(/^Evolve\s+(\w+)\s+using\s+feedback:\s+"(.+)"$/i);
+    if (evolveMatch) {
+      steps.push({ type: 'evolve', agent: evolveMatch[1], feedback: evolveMatch[2] });
+    }
+    const promptMatch = line.match(/^Prompt user to\s+"(.+)"$/i);
+    if (promptMatch) {
+      steps.push({ type: 'prompt', question: promptMatch[1], saveAs: null });
+    }
+  }
+  return steps;
+}
+
+module.exports = { parse };
+
+
+
+
+
+
+
+// // src/parser.js
+// function parse(code) {
+//   const lines = code
+//     .split(/\r?\n/)
+//     .map(l => l.trim())
+//     .filter(l => l && !l.startsWith('#') && !l.startsWith('//'));
+
+//   const workflow = {
+//     name: 'Unnamed Workflow',
+//     parameters: [],
+//     steps: [],
+//     returnValues: []
+//   };
+
+//   let i = 0;
+//   while (i < lines.length) {
+//     let line = lines[i];
+
+//     // Workflow
+//     const wfMatch = line.match(/^Workflow\s+"([^"]+)"(?:\s+with\s+(.+))?/i);
+//     if (wfMatch) {
+//       workflow.name = wfMatch[1];
+//       workflow.parameters = wfMatch[2] ? wfMatch[2].split(',').map(p => p.trim()) : [];
+//       i++;
+//       continue;
+//     }
+
+//     // Step
+//     const stepMatch = line.match(/^Step\s+(\d+)\s*:\s*(.+)$/i);
+//     if (stepMatch) {
+//       workflow.steps.push({
+//         type: 'action',
+//         stepNumber: parseInt(stepMatch[1], 10),
+//         actionRaw: stepMatch[2].trim(),
+//         saveAs: null
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Save as
+//     const saveMatch = line.match(/^Save as\s+(.+)$/i);
+//     if (saveMatch && workflow.steps.length > 0) {
+//       workflow.steps[workflow.steps.length - 1].saveAs = saveMatch[1].trim();
+//       i++;
+//       continue;
+//     }
+
+//     // If
+//     const ifMatch = line.match(/^If\s+(.+)\s+then$/i);
+//     if (ifMatch) {
+//       const condition = ifMatch[1].trim();
+//       const body = [];
+//       i++;
+//       while (i < lines.length && !/^\s*End If\s*$/i.test(lines[i])) {
+//         body.push(lines[i]);
+//         i++;
+//       }
+//       if (i < lines.length) i++; // skip 'End If'
+//       workflow.steps.push({ type: 'if', condition, body: parseBlock(body) });
+//       continue;
+//     }
+
+//     // Parallel
+//     const parMatch = line.match(/^Run in parallel$/i);
+//     if (parMatch) {
+//       const steps = [];
+//       i++;
+//       while (i < lines.length && !/^\s*End\s*$/i.test(lines[i])) {
+//         steps.push(lines[i]);
+//         i++;
+//       }
+//       if (i < lines.length) i++;
+//       workflow.steps.push({ type: 'parallel', steps: parseBlock(steps) });
+//       continue;
+//     }
+
+//     // Connect
+//     const connMatch = line.match(/^Connect\s+"([^"]+)"\s+using\s+"([^"]+)"$/i);
+//     if (connMatch) {
+//       workflow.steps.push({
+//         type: 'connect',
+//         resource: connMatch[1],
+//         endpoint: connMatch[2]
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Agent ... uses ...
+//     const agentUseMatch = line.match(/^Agent\s+"([^"]+)"\s+uses\s+"([^"]+)"$/i);
+//     if (agentUseMatch) {
+//       workflow.steps.push({
+//         type: 'agent_use',
+//         logicalName: agentUseMatch[1],
+//         resource: agentUseMatch[2]
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Debrief
+//     const debriefMatch = line.match(/^Debrief\s+(\w+)\s+with\s+"(.+)"$/i);
+//     if (debriefMatch) {
+//       workflow.steps.push({
+//         type: 'debrief',
+//         agent: debriefMatch[1],
+//         message: debriefMatch[2]
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Evolve
+//     const evolveMatch = line.match(/^Evolve\s+(\w+)\s+using\s+feedback:\s+"(.+)"$/i);
+//     if (evolveMatch) {
+//       workflow.steps.push({
+//         type: 'evolve',
+//         agent: evolveMatch[1],
+//         feedback: evolveMatch[2]
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Prompt
+//     const promptMatch = line.match(/^Prompt user to\s+"(.+)"$/i);
+//     if (promptMatch) {
+//       workflow.steps.push({
+//         type: 'prompt',
+//         question: promptMatch[1],
+//         saveAs: null
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Persist
+//     const persistMatch = line.match(/^Persist\s+(.+)\s+to\s+"(.+)"$/i);
+//     if (persistMatch) {
+//       workflow.steps.push({
+//         type: 'persist',
+//         variable: persistMatch[1].trim(),
+//         target: persistMatch[2]
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Emit
+//     const emitMatch = line.match(/^Emit\s+"(.+)"\s+with\s+(.+)$/i);
+//     if (emitMatch) {
+//       workflow.steps.push({
+//         type: 'emit',
+//         event: emitMatch[1],
+//         payload: emitMatch[2].trim()
+//       });
+//       i++;
+//       continue;
+//     }
+
+//     // Return
+//     const returnMatch = line.match(/^Return\s+(.+)$/i);
+//     if (returnMatch) {
+//       workflow.returnValues = returnMatch[1].split(',').map(v => v.trim());
+//       i++;
+//       continue;
+//     }
+
+//     i++;
+//   }
+
+//   return workflow;
+// }
+
+// function parseBlock(lines) {
+//   const steps = [];
+//   let current = null;
+//   for (const line of lines) {
+//     const stepMatch = line.match(/^Step\s+(\d+)\s*:\s*(.+)$/i);
+//     if (stepMatch) {
+//       current = {
+//         type: 'action',
+//         stepNumber: parseInt(stepMatch[1], 10),
+//         actionRaw: stepMatch[2].trim(),
+//         saveAs: null
+//       };
+//       steps.push(current);
+//       continue;
+//     }
+//     const saveMatch = line.match(/^Save as\s+(.+)$/i);
+//     if (saveMatch && current) {
+//       current.saveAs = saveMatch[1].trim();
+//     }
+//     const debriefMatch = line.match(/^Debrief\s+(\w+)\s+with\s+"(.+)"$/i);
+//     if (debriefMatch) {
+//       steps.push({ type: 'debrief', agent: debriefMatch[1], message: debriefMatch[2] });
+//     }
+//     const evolveMatch = line.match(/^Evolve\s+(\w+)\s+using\s+feedback:\s+"(.+)"$/i);
+//     if (evolveMatch) {
+//       steps.push({ type: 'evolve', agent: evolveMatch[1], feedback: evolveMatch[2] });
+//     }
+//     const promptMatch = line.match(/^Prompt user to\s+"(.+)"$/i);
+//     if (promptMatch) {
+//       steps.push({ type: 'prompt', question: promptMatch[1], saveAs: null });
+//     }
+//   }
+//   return steps;
+// }
+
+// module.exports = { parse };

package/src/runtime.js

@@ -0,0 +1,313 @@
+// src/runtime.js
+const fs = require('fs');
+
+class RuntimeAPI {
+  constructor() {
+    this.context = {};
+    this.resources = {};
+    this.agentMap = {};
+    this.events = {};
+    this.workflowSteps = []; // store for evolve lookup
+  }
+
+  on(eventName, cb) {
+    if (!this.events[eventName]) this.events[eventName] = [];
+    this.events[eventName].push(cb);
+  }
+
+  emit(eventName, payload) {
+    if (this.events[eventName]) {
+      this.events[eventName].forEach(cb => cb(payload));
+    }
+  }
+
+  evaluateCondition(cond, ctx) {
+    cond = cond.trim();
+    const eq = cond.match(/^\{(.+)\}\s+equals\s+"(.*)"$/);
+    if (eq) return this.getNested(ctx, eq[1]) === eq[2];
+    const gt = cond.match(/^\{(.+)\}\s+greater than\s+(\d+\.?\d*)$/);
+    if (gt) return parseFloat(this.getNested(ctx, gt[1])) > parseFloat(gt[2]);
+    return Boolean(this.getNested(ctx, cond.replace(/\{|\}/g, '')));
+  }
+
+  getNested(obj, path) {
+    if (!path) return undefined;
+    return path.split('.').reduce((o, k) => (o && o[k] !== undefined) ? o[k] : undefined, obj);
+  }
+
+  // 🔍 Find the last "Ask ... Save as ..." step that can be evolved
+  findLastSummaryStep() {
+    for (let i = this.workflowSteps.length - 1; i >= 0; i--) {
+      const step = this.workflowSteps[i];
+      if (step.type === 'action' && step.actionRaw?.startsWith('Ask ') && step.saveAs) {
+        return step;
+      }
+    }
+    return null;
+  }
+
+  async executeStep(step, agentResolver) {
+    switch (step.type) {
+      case 'action': {
+        const action = step.actionRaw.replace(/\{([^\}]+)\}/g, (_, path) => {
+          const value = this.getNested(this.context, path.trim());
+          return value !== undefined ? String(value) : `{${path}}`;
+        });
+        const res = await agentResolver(action, this.context);
+        if (step.saveAs) this.context[step.saveAs] = res;
+        break;
+      }
+
+      case 'if': {
+        if (this.evaluateCondition(step.condition, this.context)) {
+          for (const s of step.body) await this.executeStep(s, agentResolver);
+        }
+        break;
+      }
+
+      case 'parallel': {
+        await Promise.all(step.steps.map(s => this.executeStep(s, agentResolver)));
+        break;
+      }
+
+      case 'connect': {
+        this.resources[step.resource] = step.endpoint;
+        break;
+      }
+
+      case 'agent_use': {
+        this.agentMap[step.logicalName] = step.resource;
+        break;
+      }
+
+      case 'debrief': {
+        this.emit('debrief', { agent: step.agent, message: step.message });
+        break;
+      }
+
+      case 'evolve': {
+        // ✅ Runtime-enforced bounded evolution
+        const maxGen = step.constraints?.max_generations || 1;
+        if (maxGen < 1) {
+          this.context['improved_summary'] = this.context['summary'] || '';
+          return;
+        }
+
+        const summaryStep = this.findLastSummaryStep();
+        if (!summaryStep) {
+          console.warn('[O-Lang] Evolve: No prior "Ask ... Save as" step found to evolve');
+          this.context['improved_summary'] = this.context['summary'] || '';
+          return;
+        }
+
+        const varName = summaryStep.saveAs; // e.g., "summary"
+        let currentOutput = this.context[varName] || '';
+
+        // Run up to max_generations attempts
+        for (let attempt = 0; attempt < maxGen; attempt++) {
+          // Rebuild the original action with current context (re-interpolates {doc.text}, etc.)
+          let revisedAction = summaryStep.actionRaw.replace(/\{([^\}]+)\}/g, (_, path) => {
+            const val = this.getNested(this.context, path.trim());
+            return val !== undefined ? String(val) : `{${path}}`;
+          });
+
+          // Append improvement feedback on every attempt (including first)
+          if (step.feedback) {
+            revisedAction = revisedAction.replace(/(")$/ , `\n\n[IMPROVEMENT FEEDBACK: ${step.feedback}]$1`);
+          }
+
+          // Delegate ONLY the "Ask ..." action to the resolver
+          currentOutput = await agentResolver(revisedAction, this.context);
+          this.context[varName] = currentOutput; // update original variable
+
+          // Optional: emit debrief for observability
+          this.emit('debrief', {
+            agent: step.agent || 'Evolver',
+            message: `Evolve attempt ${attempt + 1}/${maxGen}: ${currentOutput.substring(0, 80)}...`
+          });
+        }
+
+        // ✅ Always expose final result as 'improved_summary' for downstream use
+        this.context['improved_summary'] = currentOutput;
+        break;
+      }
+
+      case 'prompt': {
+        const input = await this.getUserInput(step.question);
+        if (step.saveAs) this.context[step.saveAs] = input;
+        break;
+      }
+
+      case 'persist': {
+        const val = this.context[step.variable];
+        if (val !== undefined) {
+          fs.appendFileSync(step.target, JSON.stringify(val) + '\n', 'utf8');
+        }
+        break;
+      }
+
+      case 'emit': {
+        const payload = step.payload ? this.getNested(this.context, step.payload) : undefined;
+        this.emit(step.event, payload || step.payload);
+        break;
+      }
+    }
+  }
+
+  async getUserInput(question) {
+    return new Promise(resolve => {
+      process.stdout.write(`${question}: `);
+      process.stdin.resume();
+      process.stdin.once('data', data => {
+        process.stdin.pause();
+        resolve(data.toString().trim());
+      });
+    });
+  }
+
+  async executeWorkflow(workflow, inputs, agentResolver) {
+    this.context = { ...inputs };
+    this.workflowSteps = workflow.steps; // critical for evolve lookup
+
+    for (const step of workflow.steps) {
+      await this.executeStep(step, agentResolver);
+    }
+
+    const result = {};
+    for (const key of workflow.returnValues) {
+      result[key] = this.getNested(this.context, key);
+    }
+    return result;
+  }
+}
+
+async function execute(workflow, inputs, agentResolver) {
+  const rt = new RuntimeAPI();
+  return rt.executeWorkflow(workflow, inputs, agentResolver);
+}
+
+module.exports = { execute, RuntimeAPI };
+
+
+// // src/runtime.js
+// const fs = require('fs');
+
+// class RuntimeAPI {
+//   constructor() {
+//     this.context = {};
+//     this.resources = {};
+//     this.agentMap = {};
+//     this.events = {};
+//   }
+
+//   on(eventName, cb) {
+//     if (!this.events[eventName]) this.events[eventName] = [];
+//     this.events[eventName].push(cb);
+//   }
+
+//   emit(eventName, payload) {
+//     if (this.events[eventName]) {
+//       this.events[eventName].forEach(cb => cb(payload));
+//     }
+//   }
+
+//   evaluateCondition(cond, ctx) {
+//     cond = cond.trim();
+//     const eq = cond.match(/^\{(.+)\}\s+equals\s+"(.*)"$/);
+//     if (eq) return this.getNested(ctx, eq[1]) === eq[2];
+//     const gt = cond.match(/^\{(.+)\}\s+greater than\s+(\d+\.?\d*)$/);
+//     if (gt) return parseFloat(this.getNested(ctx, gt[1])) > parseFloat(gt[2]);
+//     return Boolean(this.getNested(ctx, cond.replace(/\{|\}/g, '')));
+//   }
+
+//   getNested(obj, path) {
+//     if (!path) return undefined;
+//     return path.split('.').reduce((o, k) => (o && o[k] !== undefined) ? o[k] : undefined, obj);
+//   }
+
+//   async executeStep(step, agentResolver) {
+//     switch (step.type) {
+//       case 'action':
+//         // ✅ Support nested interpolation: {doc.text}, {user.name}, etc.
+//         const action = step.actionRaw.replace(/\{([^\}]+)\}/g, (_, path) => {
+//           const value = this.getNested(this.context, path.trim());
+//           return value !== undefined ? String(value) : `{${path}}`;
+//         });
+//         const res = await agentResolver(action, this.context);
+//         if (step.saveAs) this.context[step.saveAs] = res;
+//         break;
+
+//       case 'if':
+//         if (this.evaluateCondition(step.condition, this.context)) {
+//           for (const s of step.body) await this.executeStep(s, agentResolver);
+//         }
+//         break;
+
+//       case 'parallel':
+//         await Promise.all(step.steps.map(s => this.executeStep(s, agentResolver)));
+//         break;
+
+//       case 'connect':
+//         this.resources[step.resource] = step.endpoint;
+//         break;
+
+//       case 'agent_use':
+//         this.agentMap[step.logicalName] = step.resource;
+//         break;
+
+//       case 'debrief':
+//         this.emit('debrief', { agent: step.agent, message: step.message });
+//         break;
+
+//       case 'evolve':
+//         // Pass evolve as a structured action (optional: could use dedicated handler)
+//         await agentResolver(`Evolve ${step.agent} using feedback: "${step.feedback}"`, this.context);
+//         break;
+
+//       case 'prompt':
+//         const input = await this.getUserInput(step.question);
+//         if (step.saveAs) this.context[step.saveAs] = input;
+//         break;
+
+//       case 'persist':
+//         const val = this.context[step.variable];
+//         fs.appendFileSync(step.target, JSON.stringify(val) + '\n', 'utf8');
+//         break;
+
+//       case 'emit':
+//         const payload = step.payload ? this.getNested(this.context, step.payload) : undefined;
+//         this.emit(step.event, payload || step.payload);
+//         break;
+//     }
+//   }
+
+//   async getUserInput(question) {
+//     return new Promise(resolve => {
+//       process.stdout.write(`${question}: `);
+//       process.stdin.resume();
+//       process.stdin.once('data', data => {
+//         process.stdin.pause();
+//         resolve(data.toString().trim());
+//       });
+//     });
+//   }
+
+//   async executeWorkflow(workflow, inputs, agentResolver) {
+//     this.context = { ...inputs };
+//     for (const step of workflow.steps) {
+//       await this.executeStep(step, agentResolver);
+//     }
+//     const result = {};
+//     for (const key of workflow.returnValues) {
+//       result[key] = this.getNested(this.context, key);
+//     }
+//     return result;
+//   }
+// }
+
+// async function execute(workflow, inputs, agentResolver) {
+//   const rt = new RuntimeAPI();
+//   return rt.executeWorkflow(workflow, inputs, agentResolver);
+// }
+
+// module.exports = { execute, RuntimeAPI };