future-lang 0.3.2 → 0.4.1

package/runtime/providers/openai-compat.js

@@ -7,19 +7,20 @@
 // No separate SDK or special casing needed.
 
 import { parseSSE, keywordVector } from './util.js';
+import { AiError } from './anthropic.js';
 
 /**
  * Well-known provider presets. Used when FUTURE_AI_PROVIDER is set without FUTURE_AI_BASE_URL.
  * Users can always override by setting FUTURE_AI_BASE_URL directly.
  */
 export const PRESETS = {
-  openai:      { baseUrl: 'https://api.openai.com/v1',                         embedModel: 'text-embedding-3-small' },
-  ollama:      { baseUrl: 'http://localhost:11434/v1',                          embedModel: 'nomic-embed-text' },
-  openrouter:  { baseUrl: 'https://openrouter.ai/api/v1',                       embedModel: null },
+  openai:      { baseUrl: 'https://api.openai.com/v1',                              embedModel: 'text-embedding-3-small' },
+  ollama:      { baseUrl: 'http://localhost:11434/v1',                               embedModel: 'nomic-embed-text' },
+  openrouter:  { baseUrl: 'https://openrouter.ai/api/v1',                            embedModel: null },
   gemini:      { baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai', embedModel: 'text-embedding-004' },
-  venice:      { baseUrl: 'https://api.venice.ai/api/v1',                       embedModel: null },
-  groq:        { baseUrl: 'https://api.groq.com/openai/v1',                     embedModel: null },
-  together:    { baseUrl: 'https://api.together.xyz/v1',                        embedModel: 'togethercomputer/m2-bert-80M-8k-retrieval' },
+  venice:      { baseUrl: 'https://api.venice.ai/api/v1',                            embedModel: null },
+  groq:        { baseUrl: 'https://api.groq.com/openai/v1',                          embedModel: null },
+  together:    { baseUrl: 'https://api.together.xyz/v1',                             embedModel: 'togethercomputer/m2-bert-80M-8k-retrieval' },
 };
 
 /**
@@ -27,38 +28,53 @@ export const PRESETS = {
  * @param {{ baseUrl: string, apiKey: string, model?: string, embedModel?: string }} config
  */
 export function create(config) {
-  const baseUrl    = config.baseUrl.replace(/\/$/, '');
-  const apiKey     = config.apiKey;
-  const model      = config.model     ?? 'gpt-4o-mini';
-  const embedModel = config.embedModel ?? null;
+  const baseUrl      = config.baseUrl.replace(/\/$/, '');
+  const apiKey       = config.apiKey;
+  const defaultModel = config.model      ?? 'gpt-4o-mini';
+  const embedModel   = config.embedModel ?? null;
+  const providerTag  = `openai-compat(${baseUrl})`;
 
   const headers = {
     'content-type':  'application/json',
     'authorization': `Bearer ${apiKey}`,
   };
 
-  async function chat(messages) {
+  async function chat(messages, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, messages, max_tokens };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
     const res = await fetch(`${baseUrl}/chat/completions`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, messages, max_tokens: 1024 }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[ai/${baseUrl}] HTTP ${res.status}: ${await res.text()}`);
+    if (!res.ok) {
+      let errBody;
+      try { errBody = await res.json(); } catch { errBody = await res.text(); }
+      throw new AiError(res.status, providerTag, errBody);
+    }
     const data = await res.json();
     return data.choices?.[0]?.message?.content?.trim() ?? '';
   }
 
-  async function ask(prompt) {
-    return chat([{ role: 'user', content: String(prompt) }]);
+  async function ask(prompt, opts = {}) {
+    return chat([{ role: 'user', content: String(prompt) }], opts);
   }
 
-  async function stream(messages, onChunk) {
+  async function stream(messages, onChunk, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, messages, max_tokens, stream: true };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
     const res = await fetch(`${baseUrl}/chat/completions`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, messages, max_tokens: 1024, stream: true }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[ai/${baseUrl}] stream HTTP ${res.status}`);
+    if (!res.ok) throw new AiError(res.status, providerTag, `stream HTTP ${res.status}`);
     for await (const { data } of parseSSE(res.body)) {
       const chunk = data.choices?.[0]?.delta?.content;
       if (chunk) onChunk(chunk);
@@ -81,5 +97,5 @@ export function create(config) {
     }
   }
 
-  return { name: `openai-compat(${baseUrl})`, ask, chat, stream, embed };
+  return { name: providerTag, ask, chat, stream, embed };
 }

package/src/cli.js

@@ -11,7 +11,7 @@
 //   future help | --help
 //   future version | --version
 
-import { readFileSync, writeFileSync, unlinkSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { tmpdir } from 'node:os';
@@ -20,8 +20,9 @@ import process from 'node:process';
 import { compile, tokenize, parse } from './index.js';
 import { format } from './formatter.js';
 import { FutureError } from './errors.js';
+import { buildSourceMap } from './sourcemap.js';
 
-const VERSION = '0.3.2';
+const VERSION = '0.4.1';
 const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const RUNTIME_INDEX = join(PROJECT_ROOT, 'runtime', 'index.js');
 
@@ -30,6 +31,7 @@ const USAGE = `Future ${VERSION} — a tiny language that compiles to JavaScript
 Usage:
   future run <file.future>          Compile and run a program
   future compile <file.future>      Compile to JavaScript (<file>.js)
+  future test [pattern]             Run *.test.future files
   future new <name>                  Create a new project
   future check <file.future>        Check for syntax errors
   future fmt <file.future>          Format source code in-place
@@ -41,13 +43,23 @@ Usage:
 Import system:
   use "./utils.future"              Import all functions from a file
   use "./math.future" as math       Import as a namespace (math.add, math.pi …)
+  use "lodash" as _                 Import an npm package as a namespace
+
+Flags:
+  future run --debug <file>         Show timing for every namespace call
+  future compile --sourcemap <file> Also emit a .js.map source map
 `;
 
 async function main(argv) {
-  const [command, arg] = argv;
+  const debug     = argv.includes('--debug');
+  const sourcemap = argv.includes('--sourcemap');
+  if (debug) process.env.FUTURE_DEBUG = '1';
+  const rest = argv.filter((a) => a !== '--debug' && a !== '--sourcemap');
+  const [command, arg] = rest;
   switch (command) {
     case 'run':        return cmdRun(arg);
-    case 'compile':    return cmdCompile(arg);
+    case 'compile':    return cmdCompile(arg, { sourcemap });
+    case 'test':       return cmdTest(arg);
     case 'new':        return cmdNew(arg);
     case 'check':      return cmdCheck(arg);
     case 'fmt':        return cmdFmt(arg);
@@ -138,6 +150,7 @@ function compileDepsToTemp(sourcePath, sourceText, tempDir, pathMap = new Map())
   const uses = findUseStatements(sourceText);
   for (const { path: relPath } of uses) {
     if (pathMap.has(relPath)) continue; // already compiled
+    if (!relPath.startsWith('./') && !relPath.startsWith('../')) continue; // npm module
     const depAbsPath = resolve(dirname(sourcePath), relPath);
     if (!existsSync(depAbsPath)) continue;
     const depSource = readFileSync(depAbsPath, 'utf8');
@@ -163,6 +176,7 @@ function compileDepModule(source, sourcePath, tempDir, pathMap) {
   // Ensure transitive deps are compiled first so pathMap is populated.
   for (const { path: relPath } of uses) {
     if (pathMap.has(relPath)) continue;
+    if (!relPath.startsWith('./') && !relPath.startsWith('../')) continue; // npm module
     const depAbsPath = resolve(dirname(sourcePath), relPath);
     if (!existsSync(depAbsPath)) continue;
     const depSrc = readFileSync(depAbsPath, 'utf8');
@@ -189,7 +203,7 @@ function compileDepModule(source, sourcePath, tempDir, pathMap) {
 // Commands
 // ---------------------------------------------------------------------------
 
-function cmdCompile(file) {
+function cmdCompile(file, { sourcemap = false } = {}) {
   let path, source;
   try { ({ path, source } = readSource(file)); }
   catch (err) { return fail(err, file); }
@@ -199,6 +213,7 @@ function cmdCompile(file) {
   // Compile each imported .future dep as a module next to its source.
   const uses = findUseStatements(source);
   for (const { path: relPath } of uses) {
+    if (!relPath.startsWith('./') && !relPath.startsWith('../')) continue; // npm module
     const depAbsPath = resolve(outDir, relPath);
     if (!existsSync(depAbsPath)) {
       process.stderr.write(`warning: imported file not found: ${relPath}\n`);
@@ -220,18 +235,30 @@ function cmdCompile(file) {
     console.log(`Compiled ${relPath} -> ${depOut}`);
   }
 
-  const js = compileOrReport(source, file, {
+  const rawJs = compileOrReport(source, file, {
     runtimeSpecifier: relativeRuntimeSpecifier(outDir),
+    sourceMaps: sourcemap,
     resolveSource: (relPath) => {
       const abs = resolve(outDir, relPath);
       return existsSync(abs) ? readFileSync(abs, 'utf8') : null;
     },
   });
-  if (js === null) return 1;
-
-  const outPath = join(outDir, `${basename(path, extname(path))}.js`);
-  writeFileSync(outPath, js, 'utf8');
-  console.log(`Compiled ${file} -> ${outPath}`);
+  if (rawJs === null) return 1;
+
+  const outBase = join(outDir, basename(path, extname(path)));
+  const outPath = `${outBase}.js`;
+
+  if (sourcemap) {
+    const mapFile = `${outBase}.js.map`;
+    const { code, map } = buildSourceMap(rawJs, basename(file), source);
+    writeFileSync(outPath, `${code}//# sourceMappingURL=${basename(mapFile)}\n`, 'utf8');
+    writeFileSync(mapFile, JSON.stringify(map), 'utf8');
+    console.log(`Compiled ${file} -> ${outPath}`);
+    console.log(`Source map   -> ${mapFile}`);
+  } else {
+    writeFileSync(outPath, rawJs, 'utf8');
+    console.log(`Compiled ${file} -> ${outPath}`);
+  }
   return 0;
 }
 
@@ -318,6 +345,88 @@ function cmdFmt(file) {
   return 0;
 }
 
+/** Recursively collect .future files matching a pattern or default test globs. */
+function findTestFiles(pattern) {
+  const cwd = process.cwd();
+  const files = [];
+
+  function walk(dir) {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const entry of entries) {
+      if (entry === 'node_modules') continue;
+      const full = join(dir, entry);
+      const st = statSync(full);
+      if (st.isDirectory()) { walk(full); continue; }
+      if (!entry.endsWith('.future')) continue;
+      const rel = relative(cwd, full).split('\\').join('/');
+      if (pattern) {
+        if (rel.includes(pattern) || entry.includes(pattern)) files.push(full);
+      } else {
+        if (entry.endsWith('.test.future') || rel.startsWith('test/')) files.push(full);
+      }
+    }
+  }
+
+  walk(cwd);
+  return files;
+}
+
+/** Run *.test.future files and report results. */
+async function cmdTest(pattern) {
+  const testFiles = findTestFiles(pattern);
+  if (testFiles.length === 0) {
+    process.stderr.write('No test files found.\n');
+    process.stderr.write('  Naming: *.test.future or test/**/*.future\n');
+    return 1;
+  }
+
+  const tempDir = tmpdir();
+  let passed = 0;
+  let failed = 0;
+
+  for (const testFile of testFiles) {
+    const rel = relative(process.cwd(), testFile).split('\\').join('/');
+    let source;
+    try { source = readFileSync(testFile, 'utf8'); } catch (err) { process.stderr.write(`error reading ${rel}: ${err.message}\n`); failed++; continue; }
+
+    // Compile dependencies.
+    const pathMap = compileDepsToTemp(testFile, source, tempDir);
+    if (pathMap === null) { failed++; continue; }
+
+    const js = compileOrReport(source, rel, {
+      runtimeSpecifier: pathToFileURL(RUNTIME_INDEX).href,
+      pathMap,
+      resolveSource: (p) => {
+        const abs = resolve(dirname(testFile), p);
+        return existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+      },
+    });
+    if (js === null) { failed++; continue; }
+
+    const tmp = join(tempDir, `future-test-${process.pid}-${Date.now()}.mjs`);
+    writeFileSync(tmp, js, 'utf8');
+    const depTmps = [...pathMap.values()].map((u) => fileURLToPath(u));
+    try {
+      await import(pathToFileURL(tmp).href);
+      console.log(`  ✓ ${rel}`);
+      passed++;
+    } catch (err) {
+      const isAssert = err.name === 'AssertionError' || err.namespace === 'assert';
+      process.stderr.write(`  ✗ ${rel}\n`);
+      process.stderr.write(`    ${isAssert ? 'AssertionError' : err.name ?? 'Error'}: ${err.message}\n`);
+      failed++;
+    } finally {
+      try { unlinkSync(tmp); } catch { /* ignore */ }
+      for (const p of depTmps) { try { unlinkSync(p); } catch { /* ignore */ } }
+    }
+  }
+
+  const total = passed + failed;
+  console.log(`\n${passed}/${total} tests passed${failed > 0 ? `, ${failed} failed` : ''}`);
+  return failed > 0 ? 1 : 0;
+}
+
 /** Create a new project scaffold. */
 function cmdNew(name) {
   if (!name) {

package/src/generator.js

@@ -24,6 +24,7 @@ export const NAMESPACES = new Set([
   'rag', 'vision', 'home',              // AI / automation extension points
   'memory', 'schedule', 'system', 'device', // optional new modules
   'math',                               // general-purpose math
+  'assert',                             // test assertions
 ]);
 
 export class Generator {
@@ -36,6 +37,7 @@ export class Generator {
     this.runtimeSpecifier = options.runtimeSpecifier ?? 'future-lang/runtime';
     this.browserMode = options.browserMode ?? false;
     this.isModule = options.isModule ?? false;
+    this.sourceMaps = options.sourceMaps ?? false;
     // Map<importedFuturePath, string[]> — exported names for non-aliased use statements.
     this.importedNames = options.importedNames ?? new Map();
     // Map<importedFuturePath, resolvedJsPath> — path override for `future run` temp files.
@@ -62,6 +64,12 @@ export class Generator {
       lines.push('');
     }
 
+    // __safe wraps async event handlers so errors are logged instead of crashing silently.
+    if (usesHandlers(program)) {
+      lines.push('const __safe = (ns, fn) => async (...a) => { try { return await fn(...a); } catch (e) { console.error(`[future:${ns}]`, e.message); } };');
+      lines.push('');
+    }
+
     // Emit __len helper only when len() is actually used — keeps simple programs clean.
     if (usesBuiltin(program, 'len')) {
       lines.push('function __len(x) { return x == null ? 0 : (x.length ?? Object.keys(x).length); }');
@@ -73,18 +81,29 @@ export class Generator {
     }
     for (const stmt of program.body) {
       if (stmt.type === NodeType.UseStatement) continue; // already emitted above
-      lines.push(this.genStatement(stmt, 0, /* topLevel= */ true));
+      const code = this.genStatement(stmt, 0, /* topLevel= */ true);
+      if (this.sourceMaps && stmt.line != null) {
+        lines.push(`/*@FL:${stmt.line}*/${code}`);
+      } else {
+        lines.push(code);
+      }
     }
     return lines.join('\n') + '\n';
   }
 
   /** Emit an ES `import` for a `use` statement. */
   genUseStatement(node) {
-    const jsPath = node.path.replace(/\.future$/, '.js');
+    const isRelative = node.path.startsWith('./') || node.path.startsWith('../');
+    const jsPath  = isRelative ? node.path.replace(/\.future$/, '.js') : node.path;
     const resolved = this.pathMap.get(node.path) ?? jsPath;
+
     if (node.alias) {
       return `import * as ${node.alias} from ${JSON.stringify(resolved)};`;
     }
+    if (!isRelative) {
+      // npm module without alias — side-effect import
+      return `import ${JSON.stringify(resolved)};`;
+    }
     const names = this.importedNames.get(node.path) ?? [];
     if (names.length > 0) {
       return `import { ${names.join(', ')} } from ${JSON.stringify(resolved)};`;
@@ -111,7 +130,13 @@ export class Generator {
         out += this.genBody(node.consequent, depth + 1);
         out += `\n${pad}}`;
         if (node.alternate) {
-          out += ` else {\n${this.genBody(node.alternate, depth + 1)}\n${pad}}`;
+          // Single chained IfStatement → `else if (...)` without extra braces.
+          if (node.alternate.length === 1 && node.alternate[0].type === NodeType.IfStatement) {
+            const elseIf = this.genStatement(node.alternate[0], depth);
+            out += ` else ${elseIf.trimStart()}`;
+          } else {
+            out += ` else {\n${this.genBody(node.alternate, depth + 1)}\n${pad}}`;
+          }
         }
         return out;
       }
@@ -172,7 +197,7 @@ export class Generator {
         const args = call.arguments.map((a) => this.genExpression(a)).join(', ');
         const sep  = args ? ', ' : '';
         const inner = this.genBody(node.body, depth + 1);
-        return `${pad}await __rt.${ns}.stream(${args}${sep}async (chunk) => {\n${inner}\n${pad}});`;
+        return `${pad}await __rt.${ns}.stream(${args}${sep}__safe("stream", async (chunk) => {\n${inner}\n${pad}}));`;
       }
 
       case NodeType.TryStatement: {
@@ -201,18 +226,19 @@ export class Generator {
 
       case NodeType.OnStatement: {
         // `on mqtt "topic" ... end`
-        // Compiles to: await __rt.<source>.subscribe(<channel>, async (message) => { ... })
+        // → await __rt.<source>.subscribe(<channel>, __safe("<source>", async (message) => { ... }))
         const inner = this.genBody(node.body, depth + 1);
         const chan  = this.genExpression(node.channel);
-        return `${pad}await __rt.${node.source}.subscribe(${chan}, async (message) => {\n${inner}\n${pad}});`;
+        const ns    = JSON.stringify(node.source);
+        return `${pad}await __rt.${node.source}.subscribe(${chan}, __safe(${ns}, async (message) => {\n${inner}\n${pad}}));`;
       }
 
       case NodeType.EveryStatement: {
         // `every "30m" ... end`
-        // Compiles to: await __rt.schedule.every(<interval>, async () => { ... })
+        // → await __rt.schedule.every(<interval>, __safe("schedule", async () => { ... }))
         const inner    = this.genBody(node.body, depth + 1);
         const interval = this.genExpression(node.interval);
-        return `${pad}await __rt.schedule.every(${interval}, async () => {\n${inner}\n${pad}});`;
+        return `${pad}await __rt.schedule.every(${interval}, __safe("schedule", async () => {\n${inner}\n${pad}}));`;
       }
 
       default:
@@ -390,6 +416,22 @@ function usesRuntime(node, useAliases = new Set()) {
   return false;
 }
 
+/** True if the program has any async event handlers (on/every/stream). */
+function usesHandlers(node) {
+  if (!node || typeof node !== 'object') return false;
+  if (
+    node.type === NodeType.OnStatement ||
+    node.type === NodeType.EveryStatement ||
+    node.type === NodeType.StreamStatement
+  ) return true;
+  for (const key of Object.keys(node)) {
+    const v = node[key];
+    if (Array.isArray(v)) { if (v.some(usesHandlers)) return true; }
+    else if (v && typeof v === 'object' && v.type) { if (usesHandlers(v)) return true; }
+  }
+  return false;
+}
+
 /** Walk the AST and check if a specific built-in function name is called. */
 function usesBuiltin(node, name) {
   if (!node || typeof node !== 'object') return false;

package/src/index.js

@@ -31,6 +31,8 @@ export function compile(source, options = {}) {
   if (options.resolveSource) {
     for (const stmt of ast.body) {
       if (stmt.type !== 'UseStatement' || stmt.alias) continue;
+      // Skip npm module imports — no source to resolve.
+      if (!stmt.path.startsWith('./') && !stmt.path.startsWith('../')) continue;
       try {
         const importedSrc = options.resolveSource(stmt.path);
         if (importedSrc) {

package/src/parser.js

@@ -16,6 +16,12 @@ import * as AST from './ast.js';
  */
 const EXPR_TERMINATORS = new Set(['END', 'ELSE', 'CATCH', 'EOF']);
 
+/** Built-in namespace names that cannot be redefined by user code. */
+const RESERVED_NAMESPACES = new Set([
+  'ai', 'http', 'mqtt', 'tts', 'rag', 'vision', 'home',
+  'memory', 'schedule', 'system', 'device', 'math', 'assert',
+]);
+
 export class Parser {
   /** @param {import('./lexer.js').Token[]} tokens */
   constructor(tokens) {
@@ -113,27 +119,51 @@ export class Parser {
 
   parseAssignment() {
     const name = this.advance(); // IDENTIFIER
+    if (RESERVED_NAMESPACES.has(name.value)) {
+      throw new FutureError(
+        `'${name.value}' is a reserved namespace and cannot be reassigned`,
+        name.line, name.column, 'parse',
+      );
+    }
     this.expect('ASSIGN', "'='");
     const value = this.parseExpression();
     return AST.Assignment(name.value, value, name.line, name.column);
   }
 
-  parseIf() {
+  /**
+   * `if cond ... [else if cond ...]* [else ...] end`
+   * @param {boolean} isChained  True when parsing an `else if` branch — the
+   *   outer `if` owns the single `end`, so this call must NOT consume it.
+   */
+  parseIf(isChained = false) {
     const kw = this.advance(); // IF
     const condition = this.parseExpression();
-    const consequent = this.parseBlock(['ELSE', 'END']);
+    const consequent = this.parseBlock(['ELSE', 'END'], 'if');
     let alternate = null;
     if (this.check('ELSE')) {
-      this.advance();
-      alternate = this.parseBlock(['END']);
+      this.advance(); // ELSE
+      if (this.check('IF')) {
+        // else if — recurse; the chained call skips its own `end`
+        alternate = [this.parseIf(true)];
+      } else {
+        alternate = this.parseBlock(['END'], 'else');
+      }
+    }
+    if (!isChained) {
+      this.expect('END', "'end' to close 'if'");
     }
-    this.expect('END', "'end'");
     return AST.IfStatement(condition, consequent, alternate, kw.line, kw.column);
   }
 
   parseFunction() {
     const kw = this.advance(); // FUNCTION
     const name = this.expect('IDENTIFIER', 'function name');
+    if (RESERVED_NAMESPACES.has(name.value)) {
+      throw new FutureError(
+        `'${name.value}' is a reserved namespace and cannot be used as a function name`,
+        name.line, name.column, 'parse',
+      );
+    }
     this.expect('LPAREN', "'('");
     const params = [];
     if (!this.check('RPAREN')) {
@@ -142,8 +172,8 @@ export class Parser {
       } while (this.match('COMMA'));
     }
     this.expect('RPAREN', "')'");
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'function');
+    this.expect('END', "'end' to close 'function'");
     return AST.FunctionDeclaration(name.value, params, body, kw.line, kw.column);
   }
 
@@ -169,8 +199,8 @@ export class Parser {
     const variable = this.expect('IDENTIFIER', 'loop variable name');
     this.expect('IN', "'in'");
     const iterable = this.parseExpression();
-    const body     = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body     = this.parseBlock(['END'], 'for');
+    this.expect('END', "'end' to close 'for'");
     return AST.ForStatement(variable.value, iterable, body, kw.line, kw.column);
   }
 
@@ -179,11 +209,11 @@ export class Parser {
    */
   parseTry() {
     const kw      = this.advance(); // TRY
-    const body    = this.parseBlock(['CATCH']);
-    this.expect('CATCH', "'catch'");
+    const body    = this.parseBlock(['CATCH'], 'try');
+    this.expect('CATCH', "'catch' after 'try' block");
     const errVar  = this.expect('IDENTIFIER', 'error variable name');
-    const catchBody = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const catchBody = this.parseBlock(['END'], 'catch');
+    this.expect('END', "'end' to close 'try'");
     return AST.TryStatement(body, errVar.value, catchBody, kw.line, kw.column);
   }
 
@@ -211,7 +241,7 @@ export class Parser {
         body.push(this.parseStatement());
       }
     }
-    this.expect('END', "'end'");
+    this.expect('END', "'end' to close 'agent'");
     return AST.AgentDeclaration(name.value, capabilities, body, kw.line, kw.column);
   }
 
@@ -221,8 +251,8 @@ export class Parser {
   parseWhile() {
     const kw = this.advance(); // WHILE
     const condition = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'while');
+    this.expect('END', "'end' to close 'while'");
     return AST.WhileStatement(condition, body, kw.line, kw.column);
   }
 
@@ -235,8 +265,8 @@ export class Parser {
   parseStream() {
     const kw = this.advance(); // STREAM
     const call = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'stream');
+    this.expect('END', "'end' to close 'stream'");
     return AST.StreamStatement(call, body, kw.line, kw.column);
   }
 
@@ -249,8 +279,8 @@ export class Parser {
     const kw = this.advance(); // ON
     const source = this.expect('IDENTIFIER', 'event source name (e.g. mqtt)');
     const channel = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'on');
+    this.expect('END', "'end' to close 'on'");
     return AST.OnStatement(source.value, channel, body, kw.line, kw.column);
   }
 
@@ -262,8 +292,8 @@ export class Parser {
   parseEvery() {
     const kw = this.advance(); // EVERY
     const interval = this.parseExpression();
-    const body = this.parseBlock(['END']);
-    this.expect('END', "'end'");
+    const body = this.parseBlock(['END'], 'every');
+    this.expect('END', "'end' to close 'every'");
     return AST.EveryStatement(interval, body, kw.line, kw.column);
   }
 
@@ -271,7 +301,7 @@ export class Parser {
    * Collect statements until one of `terminators` (or EOF) is next.
    * Throws if EOF is reached before a terminator (e.g. a missing `end`).
    */
-  parseBlock(terminators) {
+  parseBlock(terminators, openedBy = null) {
     const statements = [];
     while (!this.check('EOF') && !terminators.includes(this.peek().type)) {
       statements.push(this.parseStatement());
@@ -279,8 +309,9 @@ export class Parser {
     if (this.check('EOF')) {
       const tok = this.peek();
       const expected = terminators.map((t) => `'${t.toLowerCase()}'`).join(' or ');
+      const hint = openedBy ? ` to close '${openedBy}'` : '';
       throw new FutureError(
-        `Unexpected end of file, expected ${expected}`,
+        `Unexpected end of file — expected ${expected}${hint}`,
         tok.line, tok.column, 'parse',
       );
     }