myxo-lang 1.5.0

package/myxo-lsp.js

@@ -0,0 +1,226 @@
+'use strict';
+// myxo-lsp.js — a minimal Language Server for Myxo (stdio JSON-RPC, LSP 3.x).
+// v1 scope: diagnostics (parse/syntax errors), hover (keyword + builtin docs), completion
+// (keywords + builtins + TOP-LEVEL names in the file), and formatting (comment-preserving).
+// The analysis core (diagnostics/hoverAt/completions/docNames/formatDoc) is pure and unit-tested;
+// `handle` is a pure JSON-RPC dispatcher; `serve` is the thin stdio transport.
+// HONEST scope: syntax/parse diagnostics ONLY — a parseable-but-semantically-broken file shows NO squiggles
+// (type/runtime errors surface only at run time). Completion offers top-level names, NOT scope-aware. No
+// go-to-definition / references / rename / document-symbols. Single-file; not yet run in a live editor.
+
+const { parse } = require('./parser');
+const { MyxoError } = require('./errors');
+const { KEYWORDS } = require('./lexer');
+const { formatSource } = require('./format');
+const { makeInterpreter } = require('./myxo');
+
+// ---- name tables -----------------------------------------------------------
+
+let NAMES = null;
+function builtinNames() {                       // builtins + self-hosted stdlib, straight from a booted interpreter
+  if (NAMES) return NAMES;
+  try { NAMES = [...makeInterpreter().globals.vars.keys()].sort(); }
+  catch { NAMES = []; }
+  return NAMES;
+}
+
+const KEYWORD_DOCS = {
+  seed: 'seed name = value — bind a pathway (seed name: Type = value to type it).',
+  decay: 'decay name — remove a pathway (or decay x[i] for a slot).',
+  emit: 'emit a, b, ... — print the values, space-joined.',
+  when: 'when cond { ... } otherwise { ... } — conditional.',
+  otherwise: 'otherwise { ... } / otherwise when ... — the else of a when.',
+  reinforce: 'reinforce cond { ... } (while) · reinforce N times { ... } (repeat).',
+  times: 'reinforce N times { ... } — repeat a block N times.',
+  for: 'for each x in iterable { ... } — iterate a list/mesh/string.',
+  each: 'for each x in iterable { ... }.',
+  in: 'for each x in iterable { ... }.',
+  agent: 'agent name(params) { body } — define an agent (closure). : Type for a return type.',
+  report: 'report expr — return a value from the enclosing agent.',
+  attempt: 'attempt { ... } rescue err { ... } — catch a failure (err is a mesh).',
+  rescue: 'rescue err { ... } — handle a failure from attempt.',
+  fail: 'fail expr — raise a failure an enclosing attempt can rescue.',
+  weave: 'weave "path" [as alias] — import a module strand (fenced).',
+  expose: 'expose name — make a pathway public for weaving.',
+  as: 'weave "path" as alias — namespace the imported names.',
+  needs: 'needs cap, cap(max N, total M) — declare/limit capabilities.',
+  live: 'live — boolean true.',
+  dead: 'dead — boolean false.',
+  void: 'void — the empty value (also a type name).',
+  and: 'a and b — returns a if dead, else b (value-returning, short-circuit).',
+  or: 'a or b — returns a if live, else b (so `x or default`).',
+  not: 'not x — boolean negation.',
+  test: 'test "name" { expect ... } — a test case (runs under `myxo test`).',
+  expect: 'expect e [is v | is not v | to fail | to fail with "s"] — an assertion.',
+  match: 'match subject { pattern { ... } _ { ... } } — pattern matching.',
+};
+
+// ---- pure analysis (unit-tested) -------------------------------------------
+
+// Parse the text; return LSP-shaped diagnostics (0-based line/char). Syntax-level only.
+function diagnostics(text) {
+  try { parse(text); return []; }
+  catch (e) {
+    const line = (typeof e.line === 'number' ? e.line : 1) - 1;
+    const col = (typeof e.col === 'number' ? e.col : 1) - 1;
+    return [{ line: Math.max(0, line), col: Math.max(0, col), message: e.message }];
+  }
+}
+
+const isWordChar = (c) => /[A-Za-z0-9_]/.test(c || '');
+
+// The identifier/keyword token straddling a 0-based (line, character), or '' .
+function wordAt(text, line, character) {
+  const lines = text.split('\n');
+  const src = lines[line];
+  if (src == null) return '';
+  let s = character, e = character;
+  while (s > 0 && isWordChar(src[s - 1])) s--;
+  while (e < src.length && isWordChar(src[e])) e++;
+  return src.slice(s, e);
+}
+
+function hoverAt(text, line, character) {
+  const w = wordAt(text, line, character);
+  if (!w) return null;
+  if (KEYWORD_DOCS[w]) return KEYWORD_DOCS[w];
+  if (builtinNames().includes(w)) return `${w} — Myxo builtin/stdlib agent.`;
+  return null;
+}
+
+// Names declared in this file: seeded pathways, agents, and destructured bindings.
+function docNames(text) {
+  let ast;
+  try { ast = parse(text); } catch { return []; }
+  const out = new Set();
+  const fromPattern = (p) => {
+    if (!p) return;
+    if (p.type === 'PBind') out.add(p.name);
+    else if (p.type === 'PList') { p.elements.forEach(fromPattern); if (p.rest) out.add(p.rest); }
+    else if (p.type === 'PMesh') p.pairs.forEach(pr => fromPattern(pr.pattern));
+  };
+  for (const s of ast.body) {
+    if (s.type === 'Seed') out.add(s.name);
+    else if (s.type === 'Agent') out.add(s.name);
+    else if (s.type === 'SeedDestructure') fromPattern(s.pattern);
+  }
+  return [...out];
+}
+
+// LSP CompletionItemKind: Function=3, Variable=6, Keyword=14.
+function completions(text) {
+  const items = [];
+  for (const n of docNames(text)) items.push({ label: n, kind: 6, detail: 'in this file' });
+  for (const k of KEYWORDS) items.push({ label: k, kind: 14, detail: 'keyword' });
+  for (const b of builtinNames()) items.push({ label: b, kind: 3, detail: 'builtin' });
+  const seen = new Set(), out = [];
+  for (const it of items) { if (!seen.has(it.label)) { seen.add(it.label); out.push(it); } }   // doc names win
+  return out;
+}
+
+function formatDoc(text) {
+  try { return formatSource(text); } catch { return null; }   // comments are preserved now; just don't reformat invalid source
+}
+
+// ---- JSON-RPC dispatch (pure: state + message -> { response?, notifications? }) ----
+
+function lspDiagnostics(text) {
+  return diagnostics(text).map(d => ({
+    range: { start: { line: d.line, character: d.col }, end: { line: d.line, character: d.col + 1 } },
+    severity: 1,                                  // Error
+    source: 'myxo',
+    message: d.message,
+  }));
+}
+
+function handle(state, msg) {
+  const { id, method, params } = msg;
+  const docs = state.docs;
+  const textOf = (p) => docs.get(p && p.textDocument && p.textDocument.uri);
+  const publish = (uri) => ({ method: 'textDocument/publishDiagnostics', params: { uri, diagnostics: lspDiagnostics(docs.get(uri) || '') } });
+
+  switch (method) {
+    case 'initialize':
+      return { response: { id, result: {
+        serverInfo: { name: 'myxo-lsp', version: '1.0' },
+        capabilities: {
+        textDocumentSync: 1,                      // full-document sync
+        hoverProvider: true,
+        completionProvider: { triggerCharacters: [] },
+        documentFormattingProvider: true,
+      } } } };
+    case 'initialized': return {};
+    case 'textDocument/didOpen': {
+      const uri = params.textDocument.uri;
+      docs.set(uri, params.textDocument.text || '');
+      return { notifications: [publish(uri)] };
+    }
+    case 'textDocument/didChange': {
+      const uri = params.textDocument.uri;
+      const last = params.contentChanges[params.contentChanges.length - 1];
+      docs.set(uri, last ? last.text : (docs.get(uri) || ''));   // full sync: last change is the whole doc
+      return { notifications: [publish(uri)] };
+    }
+    case 'textDocument/didClose':
+      docs.delete(params.textDocument.uri);
+      return {};
+    case 'textDocument/hover': {
+      const h = hoverAt(textOf(params) || '', params.position.line, params.position.character);
+      return { response: { id, result: h ? { contents: { kind: 'plaintext', value: h } } : null } };
+    }
+    case 'textDocument/completion':
+      return { response: { id, result: { isIncomplete: false, items: completions(textOf(params) || '') } } };
+    case 'textDocument/formatting': {
+      const text = textOf(params) || '';
+      const f = formatDoc(text);
+      if (f == null || f === text) return { response: { id, result: [] } };
+      const lines = text.split('\n');
+      const end = { line: lines.length - 1, character: lines[lines.length - 1].length };
+      return { response: { id, result: [{ range: { start: { line: 0, character: 0 }, end }, newText: f }] } };
+    }
+    case 'shutdown': state.shuttingDown = true; return { response: { id, result: null } };
+    case 'exit': return { exit: true, code: state.shuttingDown ? 0 : 1 };   // LSP: exit before shutdown is an error
+    default:
+      return id != null ? { response: { id, error: { code: -32601, message: `method not found: ${method}` } } } : {};
+  }
+}
+
+// ---- stdio transport -------------------------------------------------------
+
+function serve(input = process.stdin, output = process.stdout) {
+  const state = { docs: new Map() };
+  let buf = Buffer.alloc(0);
+  const send = (obj) => {
+    const body = Buffer.from(JSON.stringify({ jsonrpc: '2.0', ...obj }), 'utf8');
+    output.write(`Content-Length: ${body.length}\r\n\r\n`);
+    output.write(body);
+  };
+  input.on('data', (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    for (;;) {
+      const headerEnd = buf.indexOf('\r\n\r\n');
+      if (headerEnd < 0) break;
+      const header = buf.slice(0, headerEnd).toString('utf8');
+      const m = /Content-Length:\s*(\d+)/i.exec(header);
+      if (!m) { buf = buf.slice(headerEnd + 4); continue; }
+      const len = parseInt(m[1], 10);
+      const start = headerEnd + 4;
+      if (buf.length < start + len) break;             // wait for the full body
+      const body = buf.slice(start, start + len).toString('utf8');
+      buf = buf.slice(start + len);
+      let msg;
+      try { msg = JSON.parse(body); } catch { continue; }
+      let out;
+      try { out = handle(state, msg); }   // a malformed/unexpected message must never kill the server
+      catch (e) {
+        if (msg && msg.id != null) send({ id: msg.id, error: { code: -32603, message: 'internal error: ' + e.message } });
+        continue;
+      }
+      if (out.response) send(out.response);
+      if (out.notifications) for (const n of out.notifications) send(n);
+      if (out.exit) process.exit(out.code || 0);
+    }
+  });
+}
+
+module.exports = { diagnostics, wordAt, hoverAt, docNames, completions, formatDoc, handle, serve, KEYWORD_DOCS };

package/myxo-par-worker.js

@@ -0,0 +1,39 @@
+'use strict';
+// myxo-par-worker.js — the worker half of Myxo parallelism. Receives ONE agent (its params + body AST) and its
+// args, runs it in a fresh isolated interpreter, posts the JSON result back, and signals the shared barrier.
+// Isolation is the point: a dispatched agent gets its own interpreter (builtins + stdlib), so there is no
+// shared mutable state to race. It is therefore self-contained — it sees its params, the stdlib, and itself
+// (recursion), but NOT other user agents or the parent's pathways.
+
+const { workerData } = require('worker_threads');
+if (!workerData) return;   // this file is only meaningful when launched as a Worker; running it standalone is a no-op
+
+// Pull only what we need to release the barrier FIRST, so that even a failure while loading the interpreter
+// modules (a bad require) still ticks the counter from the `finally` — the parent must never hang on us.
+const { name, params, body, argsJSON, counterSab, port } = workerData;
+const counter = new Int32Array(counterSab);
+
+let msg;
+try {
+  const { makeInterpreter } = require('./myxo');
+  const { jsToNx, nxToJs } = require('./polyglot');
+  const { assertSerializable } = require('./myxo-concurrent');
+  const { performance } = require('perf_hooks');
+  const interp = makeInterpreter();
+  const agent = { __agent: true, name: name || 'task', params, body, closure: interp.globals };
+  interp.globals.define(name || 'task', agent, true);          // define under its own name so recursion resolves
+  const args = JSON.parse(argsJSON).map(jsToNx);
+  const t0 = performance.now();
+  const result = interp.callValue(agent, args, 0);
+  const ms = performance.now() - t0;                           // pure compute time (excludes worker startup) — the scheduler's speed signal
+  assertSerializable(result, 'a gathered result');             // a task must return data, not code, to cross back
+  msg = { ok: true, resultJSON: JSON.stringify(nxToJs(result)), ms };
+} catch (e) {
+  msg = { ok: false, error: e && e.message ? e.message : String(e) };
+} finally {
+  // ALWAYS post-then-tick, on every path: the parent drains the message only after the barrier is satisfied,
+  // so posting before ticking guarantees the message is queued by the time a visible tick releases the wait.
+  try { port.postMessage(msg || { ok: false, error: 'worker produced no result' }); } catch {}
+  Atomics.add(counter, 0, 1);
+  Atomics.notify(counter, 0);
+}

package/myxo-plan.js

@@ -0,0 +1,207 @@
+'use strict';
+// myxo-plan.js — the capability preview. Given a script, report what it is ALLOWED to touch (its `needs` manifest)
+// versus what it actually TRIES to touch (capabilities it calls). This is the approval surface for handing Myxo to
+// an agent: a gate (or a human) can see a script's reach BEFORE running it, and catch fence mistakes statically —
+//   • referenced-but-undeclared  -> the fence would DENY it at runtime (or, with no manifest, it runs ungoverned)
+//   • declared-but-unreferenced  -> an over-grant to tighten
+// Static + single-file: a "capability" is any called name that is neither a user `agent` nor a core builtin.
+// Honest limit: names imported via `weave` aren't resolved, so an imported agent can look like a capability.
+
+const fs = require('fs');
+const path = require('path');
+const { parse } = require('./parser');
+const { builtins } = require('./builtins');
+
+// Generic AST walk: visit every node (object with a string `type`), recursing through all properties.
+function walk(node, visit) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const n of node) walk(n, visit); return; }
+  if (typeof node.type === 'string') visit(node);
+  for (const k of Object.keys(node)) { if (k !== 'type') walk(node[k], visit); }
+}
+
+function calleeName(n) {
+  if (!n) return null;
+  if (n.type === 'Call' && n.callee && n.callee.type === 'Identifier') return n.callee.name;
+  if (n.type === 'Pipe') return n.right && n.right.type === 'Call'
+    ? (n.right.callee && n.right.callee.type === 'Identifier' ? n.right.callee.name : null)
+    : (n.right && n.right.type === 'Identifier' ? n.right.name : null);   // `x | f`
+  return null;
+}
+
+// The "safe core" in scope for every program: JS builtins + every agent the stdlib (std.myx) defines. We parse
+// std.myx directly (NOT via makeInterpreter) to avoid a require cycle through myxo.js — that's what makes the stdlib
+// (`map`/`filter`/`sum`/…) not look like host capabilities.
+let SAFE_CACHE = null;
+function safeCore() {
+  if (SAFE_CACHE) return SAFE_CACHE;
+  const safe = new Set(Object.keys(builtins()));
+  try {
+    walk(parse(fs.readFileSync(path.join(__dirname, 'std.myx'), 'utf8')), (n) => { if (n.type === 'Agent') safe.add(n.name); });
+  } catch { /* fall back to JS builtins only */ }
+  SAFE_CACHE = safe;
+  return safe;
+}
+
+// Names a pattern binds (so `match`/destructure binds shadow correctly and aren't seen as capabilities).
+function patternBinds(pat, set) {
+  if (!pat || typeof pat !== 'object') return;
+  if (pat.type === 'PBind') set.add(pat.name);
+  else if (pat.type === 'PList') { for (const e of pat.elements) patternBinds(e, set); if (pat.rest) set.add(pat.rest); }
+  else if (pat.type === 'PMesh') { for (const pr of pat.pairs) patternBinds(pr.pattern, set); }
+}
+
+// Names DECLARED directly in a statement list (agents + seeds) — pre-collected so intra-scope references resolve
+// regardless of order. A nested agent is NOT pulled up here; it only enters its enclosing scope, never the parent's.
+function scopeDecls(stmts, set) {
+  for (const s of stmts) {
+    if (!s || typeof s !== 'object') continue;
+    if (s.type === 'Agent') set.add(s.name);
+    else if (s.type === 'Seed') set.add(s.name);
+    else if (s.type === 'SeedDestructure') patternBinds(s.pattern, set);
+  }
+}
+
+// Scope-aware capability detection with TWO resolution modes, mirroring the runtime (interpreter.js has NO hoisting):
+//   • IMMEDIATE code (run in statement order) resolves only against decls seen SO FAR — so a call placed BEFORE a
+//     same-named `agent` decl is NOT masked by it (closes the declaration-order decoy).
+//   • DEFERRED bodies (an agent runs when CALLED, later) resolve against the FULL scope — so mutual recursion and
+//     ordinary forward references still work.
+// A called name not resolvable is a host capability.
+
+// analyzeExpr: an expression runs immediately in `visible`; a deferred body (AgentExpr) sees the enclosing `full`
+// scope (so forward refs resolve). `full` is threaded so the anon-agent path matches the named-agent path.
+function analyzeExpr(node, visible, full, refs) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) { for (const n of node) analyzeExpr(n, visible, full, refs); return; }
+  if (node.type === 'Call' || node.type === 'Pipe') {
+    const name = calleeName(node);
+    if (name && !visible.has(name) && !refs.has(name)) refs.set(name, node.line || 0);
+    for (const k of Object.keys(node)) { if (k !== 'type') analyzeExpr(node[k], visible, full, refs); }
+    return;
+  }
+  if (node.type === 'AgentExpr') {                 // DEFERRED body: sees the full enclosing scope + params (like a named agent)
+    const child = new Set(full);
+    for (const p of node.params) { child.add(p.name); if (p.def) analyzeExpr(p.def, child, full, refs); }
+    analyzeBody(node.body, child, refs);
+    return;
+  }
+  for (const k of Object.keys(node)) { if (k !== 'type') analyzeExpr(node[k], visible, full, refs); }
+}
+
+// analyzeBody: a statement list. `running` grows as decls are seen (for immediate code); `full` = parent + ALL of
+// this scope's decls (for deferred agent bodies / forward refs).
+function analyzeBody(stmts, parentVisible, refs) {
+  const full = new Set(parentVisible); scopeDecls(stmts, full);
+  const running = new Set(parentVisible);
+  for (const s of stmts) {
+    analyzeStmt(s, running, full, refs);
+    if (s.type === 'Agent') running.add(s.name);
+    else if (s.type === 'Seed') running.add(s.name);
+    else if (s.type === 'SeedDestructure') patternBinds(s.pattern, running);
+    else if (s.type === 'Take') running.add(s.name);
+  }
+}
+
+function analyzeStmt(s, running, full, refs) {
+  switch (s.type) {
+    case 'Agent': {   // DEFERRED body: sees the full enclosing scope (forward refs OK) + its params
+      const child = new Set(full);
+      for (const p of s.params) { child.add(p.name); if (p.def) analyzeExpr(p.def, child, full, refs); }
+      analyzeBody(s.body, child, refs);
+      return;
+    }
+    // immediate blocks: run in order; their own bodies resolve against `running` (decls so far) + block-local binds
+    case 'When':
+      analyzeExpr(s.cond, running, full, refs);
+      analyzeBody(s.thenBlock, running, refs);
+      if (s.elseBlock) analyzeBody(s.elseBlock, running, refs);
+      return;
+    case 'Reinforce': analyzeExpr(s.cond, running, full, refs); analyzeBody(s.body, running, refs); return;
+    case 'ReinforceTimes': analyzeExpr(s.count, running, full, refs); analyzeBody(s.body, running, refs); return;
+    case 'ForEach': { analyzeExpr(s.iterable, running, full, refs); analyzeBody(s.body, addAll(running, [s.varName]), refs); return; }
+    case 'Match': {
+      analyzeExpr(s.subject, running, full, refs);
+      for (const arm of s.arms) { const c = new Set(running); patternBinds(arm.pattern, c); analyzeBody(arm.body, c, refs); }
+      return;
+    }
+    case 'Attempt':
+      analyzeBody(s.tryBlock, running, refs);
+      analyzeBody(s.catchBlock, addAll(running, [s.errName]), refs);
+      return;
+    case 'Test': analyzeBody(s.body, running, refs); return;
+    default:
+      analyzeExpr(s, running, full, refs);   // seed/emit/report/assign/decay/give/take/expression-statement -> immediate
+      return;
+  }
+}
+
+function addAll(set, names) { const c = new Set(set); for (const n of names) c.add(n); return c; }
+
+// planScript(src) -> { needs:[{name,limit}], referenced:[{name,line,declared}], undeclared:[name], unused:[name], hasManifest }
+function planScript(src) {
+  const ast = parse(src);
+  const needs = [];
+  walk(ast, (n) => { if (n.type === 'Needs') for (const it of n.items) needs.push(it); });
+  const declared = new Set(needs.map(x => x.name));
+
+  const refs = new Map();      // host-capability name -> first line
+  analyzeBody(ast.body, safeCore(), refs);
+
+  const referenced = [...refs.entries()]
+    .map(([name, line]) => ({ name, line, declared: declared.has(name) }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const undeclared = referenced.filter(r => !r.declared).map(r => r.name);
+  const referencedSet = new Set(referenced.map(r => r.name));
+  const unused = [...declared].filter(n => !referencedSet.has(n)).sort();
+  return { needs, referenced, undeclared, unused, hasManifest: needs.length > 0 };
+}
+
+function fmtLimit(limit) {
+  if (!limit) return '';
+  const parts = [];
+  if (limit.max != null) parts.push(`max ${limit.max}`);
+  if (limit.total != null) parts.push(`total ${limit.total}`);
+  return parts.length ? `  (${parts.join(', ')})` : '';
+}
+
+// A readable report. Returns { text, ok } — ok=false means the script would be refused at runtime (undeclared use).
+function formatPlan(plan, file) {
+  const L = [];
+  L.push(`myxo plan: ${file || '(script)'}`);
+  L.push('');
+  L.push('Declared capabilities (needs):');
+  if (plan.needs.length === 0) L.push('  (none)');
+  else for (const it of plan.needs) L.push(`  ${it.name}${fmtLimit(it.limit)}`);
+  L.push('');
+  L.push('Capabilities referenced in code:');
+  if (plan.referenced.length === 0) L.push('  (none — this script reaches for nothing outside the language)');
+  else for (const r of plan.referenced) {
+    L.push(`  ${r.name}${' '.repeat(Math.max(1, 16 - r.name.length))}${r.declared ? 'OK declared' : 'XX NOT declared (line ' + r.line + ') — the fence would deny it'}`);
+  }
+  if (plan.unused.length) {
+    L.push('');
+    L.push('Over-grants (declared but never used — tighten these):');
+    for (const n of plan.unused) L.push(`  ${n}`);
+  }
+  L.push('');
+  let ok = true;
+  if (plan.undeclared.length) {
+    L.push(`VERDICT: ${plan.undeclared.length} referenced capability(ies) not declared — this script would be REFUSED at runtime (or run UNGOVERNED if the host requires no manifest).`);
+    ok = false;
+  } else if (!plan.hasManifest && plan.referenced.length) {
+    L.push('VERDICT: no `needs` manifest, but capabilities are referenced — they would run UNGOVERNED unless the host requires a manifest. Declare a `needs` to bound them.');
+    ok = false;
+  } else {
+    L.push('VERDICT: no undeclared capability reach detected (best-effort static preview). The runtime fence is the actual boundary.');
+  }
+  return { text: L.join('\n') + FOOTER, ok };
+}
+
+// Honest about what this is: a BEST-EFFORT static preview, NOT a sound security gate. The RUNTIME fence is what
+// actually stops a capability call — `myxo plan` is a lint to SEE a script's likely reach and catch common mistakes.
+// It cannot soundly resolve capability vs. user-agent names statically (that needs whole-program flow analysis),
+// so the disclosed blind spots below can hide a real reach. Always back it with the fence; never approve on it alone.
+const FOOTER = '\n\n(Best-effort static preview, NOT the boundary — the RUNTIME FENCE enforces. It can be fooled by: a user agent that SHARES A NAME with a host capability (it masks the capability here, but the fence still resolves by execution order); a capability passed as a VALUE then invoked elsewhere (aliased to a variable, or handed to a higher-order function like sort/map/route/schedule); a name pulled in via weave; or a host capability registered under a core-builtin name. Use it to see intent and catch mistakes — never approve on it alone.)';
+
+module.exports = { planScript, formatPlan, walk };

package/myxo-run.js

@@ -0,0 +1,63 @@
+'use strict';
+// myxo-run.js — the production entry for running an agent-written Myxo script behind the
+// fence. This is what an MCP tool like `james_nx_run` calls: hand it a script and a
+// live tool client, get back structured output + the audit ledger. It never throws —
+// a tool handler wants a result object, not an exception.
+//
+// THREE gates, defense in depth:
+//   1. host allowlist  — the host decides which tools are even BRIDGED (absence > refusal)
+//   2. the script's `needs` manifest — the script declares what it will touch
+//   3. value budgets (`max`/`total`) — the script's own ceilings, runtime-enforced
+// Everything privileged lands in the audit ledger, returned even when the run fails.
+
+const { run } = require('./myxo');
+
+// Wrap a live client so only allow-listed tools exist, and a call to anything outside
+// the list is hard-stopped at the host boundary (belt to the script-manifest braces).
+function gateClient(client, allow) {
+  if (!client) return undefined;
+  if (!Array.isArray(allow)) return client;             // no allowlist -> bridge everything given
+  const set = new Set(allow);
+  return {
+    tools: (client.tools || []).filter(t => set.has(t.name)),
+    call(name, args) {
+      if (!set.has(name)) throw new Error(`tool '${name}' is not in the host allowlist`);
+      return client.call(name, args);
+    },
+  };
+}
+
+// Run `script` with `client` bridged as fenced capabilities.
+// opts: { client, allow, dir, maxDepth, maxSteps, natives, requireManifest, moduleLoader }
+// returns: { ok, output, audit, error }
+function runScript(script, opts = {}) {
+  let audit = [];
+  const result = { ok: true, output: '', audit, error: null };
+  const requireManifest = opts.requireManifest !== undefined ? !!opts.requireManifest : true;
+  const moduleLoader = opts.moduleLoader !== undefined ? opts.moduleLoader : null;
+  // Accumulate output OUTSIDE run() so it survives a failing script. With capture:true the chunks
+  // died inside the throw and a failed run returned output:'' — everything the script emitted before
+  // failing (a monitor's verdict, an agent's partial report) was silently dropped. Evidence survives.
+  let buf = '';
+  try {
+    run(script, {
+      output: (s) => { buf += s; },
+      dir: opts.dir,
+      maxDepth: opts.maxDepth,
+      maxSteps: opts.maxSteps,
+      requireManifest,
+      moduleLoader,
+      natives: opts.natives,
+      valueCaps: opts.valueCaps,   // caps the host meters by value (e.g. spend); everything else = call-count
+      mcp: gateClient(opts.client, opts.allow),
+      onAudit: (l) => { audit = result.audit = l; },
+    });
+  } catch (e) {
+    result.ok = false;
+    result.error = typeof e.format === 'function' ? e.format() : e.message;
+  }
+  result.output = buf;
+  return result;
+}
+
+module.exports = { runScript, gateClient };