neuralos 3.8.9 → 3.9.1

package/package.json

@@ -1,7 +1,22 @@
 {
-  "name": "neuralos",
-  "version": "3.8.9",
-  "description": "Standalone neuralOS backend (rterm-backend): AI-native terminal & agentic-AI operations platform.",
+  "main": "bin/gybackend.cjs",
+  "bin": {
+    "gybackend": "bin/gybackend.cjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@nats-io/jetstream": "^3.4.0",
+    "@nats-io/kv": "^3.4.0",
+    "@nats-io/transport-node": "^3.4.0",
+    "better-sqlite3": "^12.11.1"
+  },
+  "optionalDependencies": {
+    "node-pty": "1.2.0-beta.3",
+    "serialport": "^12.0.0",
+    "ssh2": "^1.17.0"
+  },
   "keywords": [
     "forward-deployed-engineer",
     "fde",
@@ -34,22 +49,7 @@
     "type": "git",
     "url": "git+https://github.com/DrOlu/RTerm.git"
   },
-  "engines": {
-    "node": ">=18"
-  },
-  "bin": {
-    "gybackend": "bin/gybackend.cjs"
-  },
-  "main": "bin/gybackend.cjs",
-  "dependencies": {
-    "@nats-io/jetstream": "^3.4.0",
-    "@nats-io/kv": "^3.4.0",
-    "@nats-io/transport-node": "^3.4.0",
-    "better-sqlite3": "^12.11.1"
-  },
-  "optionalDependencies": {
-    "serialport": "^12.0.0",
-    "ssh2": "^1.17.0",
-    "node-pty": "1.2.0-beta.3"
-  }
+  "name": "neuralos",
+  "version": "3.9.1",
+  "description": "Standalone neuralOS backend (rterm-backend): AI-native terminal & agentic-AI operations platform. Ships the neuralOS plugin — on-device data agents (verified probe menus over real data sources, engine + weights auto-provisioned on first use)."
 }

package/plugins/neuralos/index.mjs

@@ -0,0 +1,137 @@
+/**
+ * neuralos — neuralOS instances as RTerm agent tools.
+ *
+ * neuralOS instances (~/neuralos-instances) are on-device data agents: a
+ * verified menu of probes over a real data source (databases, APIs, log
+ * sets), selected by the 121M neuralOS engine and executed by each
+ * instance's Python bridge. This plugin wires four agent tools:
+ *
+ *   neuralos_list_instances — what can be queried
+ *   neuralos_ask            — plain-English question -> verified digest
+ *   neuralos_graph          — relationship maps (overview/neighbors/connect)
+ *   neuralos_admin          — write probes, confirm='yes' interlocked
+ *
+ * The engine ships with the RTerm desktop bundle ({resourcesPath}/neuralos);
+ * the standalone backend auto-provisions ~/.cache/neuralos on first use
+ * (one ~36 MB fetch from HuggingFace, offline forever after).
+ *
+ * Config (settings.neuralos, or env NEURALOS_*):
+ *   instancesDir  — instances root (default ~/neuralos-instances)
+ *   pythonBin    — interpreter with pydantic for the bridges (default python3)
+ *   engineBin / engineWeights — explicit engine override
+ *   autoDownload — provision the shared cache when nothing local (default true)
+ */
+
+import { resolveConfig, listInstances, instanceDirFor, resolveEngine, engineSelect, executeProbe, graphProbe, adminProbe, truncate, defaultExec } from './neuralosEngine.mjs'
+
+export { resolveConfig } from './neuralosEngine.mjs'
+
+export function register(ctx) {
+  const cfg = resolveConfig(ctx)
+  const exec = defaultExec()
+  const log = (line) => {
+    try {
+      if (typeof ctx.log === 'function') ctx.log(`[neuralos] ${line}`)
+    } catch { /* logging must never break a tool */ }
+  }
+
+  const settings = (typeof ctx.getSettings === 'function' ? ctx.getSettings() : ctx.settings) || {}
+  if (settings.neuralos?.enabled === false) {
+    log('disabled in settings — not registering tools')
+    return
+  }
+
+  registerList(ctx, cfg, log)
+  registerAsk(ctx, cfg, exec, log)
+  registerGraph(ctx, cfg, exec, log)
+  registerAdmin(ctx, cfg, exec, log)
+
+  log('registered neuralos tools (list_instances, ask, graph, admin)')
+}
+
+function registerList(ctx, cfg, log) {
+  ctx.registerTool({
+    name: 'neuralos_list_instances',
+    description:
+      'List the available neuralOS instances (on-device data agents). Each instance is a verified menu of probes over a real data source (a database, API, or file set). Use this first to see what can be queried.',
+    params: {},
+    handler: async () => {
+      const result = await listInstances(cfg)
+      log('list_instances')
+      return result
+    },
+  })
+}
+
+function registerAsk(ctx, cfg, exec, log) {
+  ctx.registerTool({
+    name: 'neuralos_ask',
+    description:
+      'Ask a neuralOS instance a question in plain English. The on-device engine selects the probe, the instance bridge executes it against the real data source, and a verified digest comes back. Route data questions through this instead of querying the source directly.',
+    params: {
+      instance: { type: 'string', description: 'instance name from neuralos_list_instances' },
+      question: { type: 'string', description: 'the question in plain English, verbatim' },
+    },
+    handler: async (p) => {
+      const instance = String(p?.instance ?? '')
+      const question = String(p?.question ?? '')
+      const dir = await instanceDirFor(cfg, instance)
+      if (typeof dir !== 'string') return dir
+      const engine = await resolveEngine(cfg)
+      if (engine.error) return engine
+      const selection = await engineSelect(exec, engine, `${dir}/needle_menu.json`, question, { timeoutMs: cfg.timeoutMs })
+      if (selection.error) return { instance, question, ...selection }
+      const result = await executeProbe(exec, cfg, dir, selection.pick, selection.args, { timeoutMs: cfg.timeoutMs })
+      log(`ask ${instance} -> ${selection.pick} (conf ${selection.confidence})`)
+      return truncate({ instance, question, pick: selection.pick, confidence: selection.confidence, result })
+    },
+  })
+}
+
+function registerGraph(ctx, cfg, exec, log) {
+  ctx.registerTool({
+    name: 'neuralos_graph',
+    description:
+      'Relationship questions over an instance: overview (the verified entity/edge map), neighbors (one-hop adjacency for a node fragment), or connect (path between two entities). Executes the graph probe directly.',
+    params: {
+      instance: { type: 'string', description: 'instance name' },
+      op: { type: 'string', description: 'overview | neighbors | connect' },
+      node: { type: 'string', description: 'node fragment for neighbors', optional: true },
+      a: { type: 'string', description: 'first entity for connect', optional: true },
+      b: { type: 'string', description: 'second entity for connect', optional: true },
+    },
+    handler: async (p) => {
+      const dir = await instanceDirFor(cfg, String(p?.instance ?? ''))
+      if (typeof dir !== 'string') return dir
+      const result = await graphProbe(exec, cfg, dir, { op: String(p?.op ?? 'overview'), node: p?.node, a: p?.a, b: p?.b })
+      log(`graph ${p?.op}`)
+      return truncate(result)
+    },
+  })
+}
+
+function registerAdmin(ctx, cfg, exec, log) {
+  ctx.registerTool({
+    name: 'neuralos_admin',
+    description:
+      'Execute a WRITE/admin probe on an instance (boot a server, tag a resource, purge DNS). Destructive and reversible only per the instance design; the confirm parameter must be the literal string "yes" — that is the operator interlock. Read-only questions must use neuralos_ask instead.',
+    params: {
+      instance: { type: 'string', description: 'instance name' },
+      probe: { type: 'string', description: 'admin probe name, e.g. aws_power' },
+      args: { type: 'object', description: 'probe arguments as JSON', optional: true },
+      confirm: { type: 'string', description: 'must be the literal "yes"' },
+    },
+    handler: async (p) => {
+      if (p?.confirm !== 'yes') return { error: 'admin probes require confirm="yes" — restate what you intend to run and pass confirm="yes"' }
+      const dir = await instanceDirFor(cfg, String(p?.instance ?? ''))
+      if (typeof dir !== 'string') return dir
+      const result = await adminProbe(exec, cfg, dir, String(p?.probe ?? ''), p?.args ?? {})
+      log(`admin ${p?.probe} on ${p?.instance}`)
+      return truncate(result)
+    },
+  })
+}
+
+export function unregister() {
+  /* tools deregister with the plugin record; nothing to stop here */
+}

package/plugins/neuralos/neuralos.extreme.spec.mts

@@ -0,0 +1,298 @@
+/**
+ * neuralos — plugin extreme spec.
+ *
+ * Pure invariants, always run, no network and no engine required:
+ * config precedence, engine-name mapping, JSON recovery, instance
+ * discovery, engine selection against a FAKE engine script (node is the
+ * only dependency), probe execution against a FAKE python (the runner is
+ * exercised via an injected exec), the graph direct-execution rule, and
+ * the admin confirm interlock. The auto-download path is tested with an
+ * injected fetch that writes local files — CI never touches HuggingFace.
+ *
+ * Run:  npx tsx plugins/neuralos/neuralos.extreme.spec.mts
+ */
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync, mkdirSync, existsSync, readFileSync, chmodSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  HF_BASE,
+  adminProbe,
+  bundledEngineName,
+  defaultExec,
+  engineSelect,
+  ensureEngine,
+  executeProbe,
+  graphProbe,
+  listInstances,
+  parseJsonObject,
+  resolveConfig,
+  resolveEngine,
+  truncate,
+} from './neuralosEngine.mjs'
+import { register } from './index.mjs'
+
+let pass = 0
+let fail = 0
+const failures: string[] = []
+
+function ok(cond: unknown, label: string, note = ''): void {
+  if (cond) {
+    pass++
+    console.log(`PASS ${label}`)
+  } else {
+    fail++
+    failures.push(`${label}${note ? ` — ${note}` : ''}`)
+    console.log(`FAIL ${label}${note ? ` — ${note}` : ''}`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 1. Config precedence: settings block > env > default; blank = unset.
+// ---------------------------------------------------------------------------
+{
+  const cfg = resolveConfig({ getSettings: () => ({ neuralos: { pythonBin: '/framework/python3.12', instancesDir: '  ' } }) }, {})
+  ok(cfg.pythonBin === '/framework/python3.12', 'settings block wins for pythonBin')
+  ok(cfg.instancesDir === join(homedir(), 'neuralos-instances'), 'blank settings value falls through to default', cfg.instancesDir)
+
+  const cfgEnv = resolveConfig({ getSettings: () => ({}) }, { NEURALOS_INSTANCES_DIR: '/custom/instances' })
+  ok(cfgEnv.instancesDir === '/custom/instances', 'env wins when settings are silent')
+
+  const cfgOff = resolveConfig({ getSettings: () => ({ neuralos: { autoDownload: false } }) }, {})
+  ok(cfgOff.autoDownload === false, 'autoDownload can be disabled in settings')
+  const cfgOn = resolveConfig({ getSettings: () => ({}) }, {})
+  ok(cfgOn.autoDownload === true, 'autoDownload defaults on')
+}
+// ---------------------------------------------------------------------------
+// 2. Engine name mapping (macos-x64 has no published engine).
+// ---------------------------------------------------------------------------
+{
+  ok(bundledEngineName('darwin', 'arm64') === 'engine-macos-arm64', 'darwin/arm64 maps to engine-macos-arm64')
+  ok(bundledEngineName('linux', 'x64') === 'engine-linux-x86_64', 'linux/x64 maps to engine-linux-x86_64')
+  ok(bundledEngineName('linux', 'arm64') === 'engine-linux-arm64', 'linux/arm64 maps to engine-linux-arm64')
+  ok(bundledEngineName('win32', 'x64') === 'engine-windows-x86_64.exe', 'win32/x64 maps to engine-windows-x86_64.exe')
+  ok(bundledEngineName('darwin', 'x64') === null, 'darwin/x64 has no published engine')
+}
+
+// ---------------------------------------------------------------------------
+// 3. JSON recovery from noisy engine output.
+// ---------------------------------------------------------------------------
+{
+  const parsed = parseJsonObject('noise {"function_calls":[{"name":"p"}], "confidence": 0.9} trailing')
+  ok(parsed?.function_calls?.[0]?.name === 'p', 'parseJsonObject recovers JSON embedded in noise')
+  ok(parseJsonObject('not json') === null, 'parseJsonObject returns null for garbage')
+}
+
+// ---------------------------------------------------------------------------
+// 4. Instance discovery (fake instances root in a temp dir).
+// ---------------------------------------------------------------------------
+{
+  const root = mkdtempSync(join(tmpdir(), 'neuralos-spec-'))
+  mkdirSync(join(root, 'chinook'))
+  writeFileSync(join(root, 'chinook', 'needle_menu.json'), JSON.stringify([{ name: 'p1' }, { name: 'p2' }]))
+  mkdirSync(join(root, 'not-an-instance'))
+
+  const cfg = resolveConfig({}, { NEURALOS_INSTANCES_DIR: root })
+  const listed = await listInstances(cfg)
+  ok(
+    Array.isArray(listed) && listed.length === 1 && listed[0].name === 'chinook' && listed[0].probeCount === 2,
+    'listInstances finds only dirs with a needle_menu.json',
+    JSON.stringify(listed),
+  )
+
+  const missing = await listInstances(cfg, { readdir: async () => { throw new Error('ENOENT') }, readFile: async () => '' })
+  ok(
+    (missing as { error?: string }).error?.includes('no instances directory'),
+    'listInstances reports a missing root as data',
+  )
+}
+
+// ---------------------------------------------------------------------------
+// 5. Engine selection against a FAKE engine (a node script).
+// ---------------------------------------------------------------------------
+{
+  const dir = mkdtempSync(join(tmpdir(), 'neuralos-engine-'))
+  const fakeEngine = join(dir, 'fake-engine.mjs')
+  writeFileSync(
+    fakeEngine,
+    `const args = process.argv.slice(2)
+const qi = args.indexOf('--prompt')
+const q = qi >= 0 ? args[qi + 1] : ''
+if (q === 'refuse me') { console.log(JSON.stringify({ function_calls: [] })) }
+else if (q === 'garbage') { console.log('not json at all') }
+else if (q === 'crash') { process.stderr.write('boom'); process.exit(1) }
+else { console.log(JSON.stringify({ function_calls: [{ name: 'transactions_count', arguments: { limit: 5 } }], confidence: 0.98 })) }
+`,
+  )
+  const runEngine = (q: string) =>
+    engineSelect(
+      (cmd: string, args: string[]) => {
+        void cmd
+        const r = spawnSync(process.execPath, [fakeEngine, ...args.slice(2)], { encoding: 'utf8' })
+        return Promise.resolve({ ok: r.status === 0, code: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' })
+      },
+      { engineBin: fakeEngine, engineWeights: join(dir, 'weights.cact') },
+      '/i/needle_menu.json',
+      q,
+    )
+
+  const hit = await runEngine('count invoices')
+  ok(hit.pick === 'transactions_count' && hit.confidence === 0.98, 'engineSelect parses the selection with confidence', JSON.stringify(hit))
+  const refused = await runEngine('refuse me')
+  ok((refused as { error?: string }).error === 'engine refused the question (no call selected)', 'refusal is data, not an exception')
+  const garbage = await runEngine('garbage')
+  ok((garbage as { error?: string }).error?.includes('engine output not JSON'), 'non-JSON engine output is data')
+  const crash = await runEngine('crash')
+  ok((crash as { error?: string }).error === 'engine exited 1: boom', 'engine crash with empty stdout is data')
+}
+
+// ---------------------------------------------------------------------------
+// 6. Probe execution via an injected exec (the real path spawns python).
+// ---------------------------------------------------------------------------
+{
+  const cfg = resolveConfig({}, { NEURALOS_PYTHON: '/framework/python3.12' })
+  const seen: Array<{ cmd: string; args: string[]; env: Record<string, string> }> = []
+  const exec = (cmd: string, args: string[], opts: { env?: Record<string, string> }) => {
+    seen.push({ cmd, args, env: opts.env ?? {} })
+    return Promise.resolve({ ok: true, code: 0, stdout: '{"count": 42}', stderr: '' })
+  }
+  const result = await executeProbe(exec, cfg, '/i', 'transactions_count', { limit: 5 })
+  ok(result.count === 42, 'executeProbe returns the parsed digest')
+  ok(seen[0].cmd === '/framework/python3.12' && seen[0].args[0] === '-c', 'executeProbe spawns the configured python with the runner')
+  ok(
+    seen[0].env.NEURALOS_INSTANCE_DIR === '/i' && seen[0].env.NEURALOS_PROBE === 'transactions_count' && seen[0].env.NEURALOS_ARGS === '{"limit":5}',
+    'probe name and args travel through the environment, never the command line',
+  )
+
+  const failed = await executeProbe((() => Promise.resolve({ ok: false, code: 1, stdout: '', stderr: 'boom' })) as never, cfg, '/i', 'p', {})
+  ok((failed as { error?: string }).error === 'probe exited 1: boom', 'probe failure surfaces as data')
+}
+
+// ---------------------------------------------------------------------------
+// 7. Graph direct execution + admin interlock.
+// ---------------------------------------------------------------------------
+{
+  const dir = mkdtempSync(join(tmpdir(), 'neuralos-graph-'))
+  writeFileSync(
+    join(dir, 'needle_menu.json'),
+    JSON.stringify([{ name: 'cb_graph_overview' }, { name: 'cb_graph_neighbors' }, { name: 'transactions_count' }]),
+  )
+  const cfg = resolveConfig({}, {})
+  const exec = () => Promise.resolve({ ok: true, code: 0, stdout: '{"nodes":[]}', stderr: '' })
+
+  const overview = await graphProbe(exec, cfg, dir, { op: 'overview' })
+  ok((overview as { probe?: string }).probe === 'cb_graph_overview' && (overview as { nodes?: unknown[] }).nodes?.length === 0, 'graph overview executes the probe directly by name')
+  const neighbors = await graphProbe(exec, cfg, dir, { op: 'neighbors', node: '4001234567' })
+  ok((neighbors as { probe?: string }).probe === 'cb_graph_neighbors', 'graph neighbors executes by name (numeric fragments bypass engine grounding)')
+  const missingOp = await graphProbe(exec, cfg, dir, { op: 'connect', a: 'x', b: 'y' })
+  ok(
+    (missingOp as { error?: string }).error === 'this instance has no connect graph probe' &&
+      Array.isArray((missingOp as { available_graph_probes?: string[] }).available_graph_probes),
+    'a missing graph op lists what exists instead of guessing',
+  )
+
+  const admin = await adminProbe(exec, cfg, dir, 'aws_tag', { confirm: 'yes' })
+  ok(admin.admin === true && admin.probe === 'aws_tag', 'admin wraps the result with the probe name and admin flag')
+  const badName = await adminProbe(exec, cfg, dir, 'rm -rf', {})
+  ok((badName as { error?: string }).error === 'invalid probe name: rm -rf', 'admin rejects probe names that are not identifiers')
+}
+
+// ---------------------------------------------------------------------------
+// 8. Engine resolution: settings override wins; auto-download provisions the
+//    cache via an injected fetch (no network in CI); idempotent on re-run.
+// ---------------------------------------------------------------------------
+{
+  const explicitDir = mkdtempSync(join(tmpdir(), 'neuralos-explicit-'))
+  writeFileSync(join(explicitDir, 'needle'), 'fake-engine')
+  writeFileSync(join(explicitDir, 'needle3.cact'), 'fake-weights')
+  const cacheAlt = mkdtempSync(join(tmpdir(), 'neuralos-cache-alt-'))
+  writeFileSync(join(cacheAlt, 'engine-macos-arm64'), 'cache-engine')
+  writeFileSync(join(cacheAlt, 'needle3.cact'), 'cache-weights')
+  const explicit = await resolveEngine(
+    resolveConfig({ getSettings: () => ({ neuralos: { engineBin: join(explicitDir, 'needle'), engineWeights: join(explicitDir, 'needle3.cact'), cacheDir: cacheAlt } }) }, {}),
+    { platform: 'darwin', arch: 'arm64' },
+  )
+  ok(explicit.engineBin === join(explicitDir, 'needle'), 'explicit settings engine wins over a populated cache')
+
+  const cache = mkdtempSync(join(tmpdir(), 'neuralos-cache-'))
+  const downloads: string[] = []
+  const fetchImpl = async (url: string, target: string) => {
+    downloads.push(url)
+    writeFileSync(target, `fake:${url}`)
+  }
+  const cfg = resolveConfig({ getSettings: () => ({}) }, { NEURALOS_INSTANCES_DIR: mkdtempSync(join(tmpdir(), 'neuralos-none-')), NEURALOS_CACHE_DIR: cache })
+  const first = await ensureEngine({ platform: 'darwin', arch: 'arm64', cacheDir: cache, fetchImpl })
+  ok(first.engineBin === join(cache, 'engine-macos-arm64') && first.engineWeights === join(cache, 'needle3.cact'), 'ensureEngine provisions weights + per-arch engine into the cache', JSON.stringify(first))
+  ok(downloads.length === 2 && downloads[0] === `${HF_BASE}/needle3.cact` && downloads[1].includes('macos-arm64/needle'), 'downloads come from the public Cactus-Compute/needle3 URLs')
+  ok(existsSync(join(cache, 'engine-macos-arm64')), 'the engine file exists on disk after provisioning')
+
+  const second = await ensureEngine({ platform: 'darwin', arch: 'arm64', cacheDir: cache, fetchImpl })
+  ok(second.engineBin === first.engineBin && downloads.length === 2, 'provisioning is idempotent — no re-download when cached')
+
+  // resolution now finds the cache without any download
+  const resolved = await resolveEngine(cfg, { platform: 'darwin', arch: 'arm64' })
+  ok(resolved.engineBin === join(cache, 'engine-macos-arm64'), 'resolveEngine picks the provisioned cache copy')
+}
+
+// ---------------------------------------------------------------------------
+// 9. Tool registration + the admin confirm interlock at the tool layer.
+// ---------------------------------------------------------------------------
+{
+  const registered: Array<{ name: string; params: Record<string, unknown>; handler: (args: unknown) => Promise<unknown> }> = []
+  const logged: string[] = []
+  register({
+    registerTool: (t) => registered.push(t as never),
+    log: (l: string) => logged.push(l),
+    getSettings: () => ({}),
+  })
+  ok(
+    registered.map((t) => t.name).sort().join(',') === 'neuralos_admin,neuralos_ask,neuralos_graph,neuralos_list_instances',
+    'register() wires exactly the four neuralos tools',
+  )
+  const admin = registered.find((t) => t.name === 'neuralos_admin')
+  const denied = (await admin.handler({ instance: 'aws', probe: 'aws_power', confirm: 'no' })) as { error?: string }
+  ok(denied.error?.includes('confirm="yes"'), 'the tool layer refuses admin without confirm="yes"')
+  const unknown = registered.find((t) => t.name === 'neuralos_ask')
+  const answered = (await unknown.handler({ instance: 'does-not-exist', question: 'x' })) as { error?: string }
+  ok(answered.error?.includes("no instance named 'does-not-exist'"), 'ask answers an unknown instance as data')
+  ok(logged.some((l) => l.includes('registered neuralos tools')), 'the plugin announces registration through ctx.log')
+
+  // the enabled=false settings gate: the Settings panel switch is honest
+  const off: Array<{ name: string }> = []
+  register({
+    registerTool: (t) => off.push(t as never),
+    log: () => {},
+    getSettings: () => ({ neuralos: { enabled: false } }),
+  })
+  ok(off.length === 0, 'enabled=false registers zero tools')
+}
+
+// ---------------------------------------------------------------------------
+// 10. Digest truncation keeps tool results bounded.
+// ---------------------------------------------------------------------------
+{
+  const big = { rows: 'x'.repeat(20_000) }
+  const text = truncate(big, 6000)
+  ok(text.length < 21_000 && text.includes('truncated at 6000 chars'), 'truncate caps large digests with an honest marker')
+  ok(truncate('small') === 'small', 'small digests pass through untouched')
+}
+
+// ---------------------------------------------------------------------------
+// 11. The REAL defaultExec forwards opts.env (probe transport) to the child
+//     while keeping the parent environment (PATH etc.) intact.
+// ---------------------------------------------------------------------------
+{
+  const exec = defaultExec()
+  const out = await exec(process.execPath, ['-e', 'console.log(process.env.NEURALOS_SPEC_PROBE ?? "missing")'], { env: { NEURALOS_SPEC_PROBE: 'forwarded' } })
+  ok(out.code === 0 && out.stdout.trim() === 'forwarded', 'defaultExec forwards opts.env to the child process')
+  const plain = await exec(process.execPath, ['-e', 'console.log(Boolean(process.env.PATH))'])
+  ok(plain.code === 0 && plain.stdout.trim() === 'true', 'defaultExec keeps the parent environment for plain calls')
+}
+
+console.log(`\n${pass} passed, ${fail} failed`)
+if (fail > 0) {
+  console.log(`FAILURES:\n${failures.map((f) => `  - ${f}`).join('\n')}`)
+  process.exit(1)
+}
+console.log('neuralos: ALL TESTS PASSED')

package/plugins/neuralos/neuralosEngine.mjs

@@ -0,0 +1,299 @@
+/**
+ * neuralosEngine — the neuralOS runtime for the RTerm neuralos plugin.
+ *
+ * neuralOS instances are on-device data agents: each instance directory
+ * carries a probe menu (needle_menu.json) over a real data source, the
+ * 121M engine binary picks the probe that answers a question, and the
+ * instance's bridge (Python) executes it against the source. Everything
+ * here returns errors as data — a missing engine or instance is an
+ * answer, never a thrown exception.
+ *
+ * Engine resolution order (first existing wins):
+ *   1. settings.neuralos.engineBin/engineWeights (or NEURALOS_ENGINE_* env)
+ *   2. the desktop bundle: {process.resourcesPath}/neuralos/<per-arch engine>
+ *      (electron-builder extraResources; present in the packaged app only)
+ *   3. the shared cache ~/.cache/neuralos/ (auto-downloaded on first use —
+ *      this is what makes `npm i -g neuralos` self-provisioning: one fetch,
+ *      then offline forever)
+ *   4. <instancesRoot>/engine/needle (+ needle3.cact) — the fleet convention
+ * If nothing exists and autoDownload is enabled, the cache is provisioned
+ * from https://huggingface.co/Cactus-Compute/needle3 (public, no auth).
+ */
+
+import { execFile as cpExecFile, spawn } from 'node:child_process'
+import { promises as fs, constants as fsConstants } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+export const HF_BASE = 'https://huggingface.co/Cactus-Compute/needle3/resolve/main'
+export const WEIGHTS_NAME = 'needle3.cact'
+export const MAX_RESULT_CHARS = 6000
+
+/** Per-arch bundled engine name, matching the release-workflow download. */
+export function bundledEngineName(platform, arch) {
+  const os = platform === 'darwin' ? 'macos' : platform === 'win32' ? 'windows' : 'linux'
+  if (os === 'macos') return arch === 'arm64' ? 'engine-macos-arm64' : null
+  if (os === 'linux') return arch === 'arm64' ? 'engine-linux-arm64' : arch === 'x64' ? 'engine-linux-x86_64' : null
+  return arch === 'arm64' ? 'engine-windows-arm64.exe' : arch === 'x64' ? 'engine-windows-x86_64.exe' : null
+}
+
+/** The HF platform folder for a bundled engine name. */
+export function hfFolderFor(platform, arch) {
+  const os = platform === 'darwin' ? 'macos' : platform === 'win32' ? 'windows' : 'linux'
+  if (os === 'macos') return 'macos-arm64'
+  if (os === 'linux') return arch === 'arm64' ? 'linux-arm64' : 'linux-x86_64'
+  return arch === 'arm64' ? 'windows-arm64' : 'windows-x86_64'
+}
+
+export function cacheDir(env = process.env) {
+  if (env.NEURALOS_CACHE_DIR) return env.NEURALOS_CACHE_DIR
+  return path.join(homedir(), '.cache', 'neuralos')
+}
+
+/** Settings block -> env -> default. Blank values mean unset. */
+function pick(settingsValue, envValue, fallback) {
+  const s = typeof settingsValue === 'string' ? settingsValue.trim() : ''
+  if (s) return s
+  const e = typeof envValue === 'string' ? envValue.trim() : ''
+  if (e) return e
+  return fallback
+}
+
+export function resolveConfig(ctx = {}, env = process.env) {
+  const settings = (typeof ctx.getSettings === 'function' ? ctx.getSettings() : ctx.settings) || {}
+  const block = settings.neuralos || {}
+  return {
+    instancesDir: pick(block.instancesDir, env.NEURALOS_INSTANCES_DIR, path.join(homedir(), 'neuralos-instances')),
+    pythonBin: pick(block.pythonBin, env.NEURALOS_PYTHON, 'python3'),
+    engineBin: pick(block.engineBin, env.NEURALOS_ENGINE_BIN) || null,
+    engineWeights: pick(block.engineWeights, env.NEURALOS_ENGINE_WEIGHTS) || null,
+    autoDownload: block.autoDownload !== false && env.NEURALOS_AUTO_DOWNLOAD !== '0',
+    cacheDir: pick(block.cacheDir, env.NEURALOS_CACHE_DIR, cacheDir(env)),
+    timeoutMs: Number(block.timeoutMs) > 0 ? Number(block.timeoutMs) : 120000,
+  }
+}
+
+/** Default execFile promisified; injectable for the spec. */
+export function defaultExec() {
+  return (cmd, args, opts = {}) =>
+    new Promise((resolve) => {
+      const execEnv = opts.env ? { ...process.env, ...opts.env } : process.env
+      const child = cpExecFile(cmd, args, { timeout: opts.timeoutMs ?? 120000, maxBuffer: 16 * 1024 * 1024, env: execEnv }, (err, stdout, stderr) => {
+        resolve({ ok: !err, code: err ? err.code ?? 1 : 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })
+      })
+      void child
+    })
+}
+
+async function exists(p) {
+  try {
+    await fs.access(p, fsConstants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Download one file over HTTPS into dir with its basename (idempotent). */
+async function download(deps, url, dir) {
+  await fs.mkdir(dir, { recursive: true })
+  const target = path.join(dir, path.basename(url))
+  if (await exists(target)) return target
+  const tmp = `${target}.part`
+  if (!deps.fetchImpl) {
+    const res = await fetch(url, { redirect: 'follow' })
+    if (!res.ok) throw new Error(`download ${url} -> HTTP ${res.status}`)
+    const buf = Buffer.from(await res.arrayBuffer())
+    await fs.writeFile(tmp, buf)
+  } else {
+    await deps.fetchImpl(url, tmp)
+  }
+  await fs.rename(tmp, target)
+  return target
+}
+
+/**
+ * Provision the shared cache with the weights + this platform's engine.
+ * One-time (~36 MB); afterwards everything resolves offline. Injectable
+ * fetch/download for the spec; the real path uses global fetch (Node >=18).
+ */
+export async function ensureEngine(deps, { force = false } = {}) {
+  const engineName = bundledEngineName(deps.platform ?? process.platform, deps.arch ?? process.arch)
+  if (!engineName) return { error: `no published neuralOS engine for ${deps.platform ?? process.platform}-${deps.arch ?? process.arch}` }
+  const dir = deps.cacheDir ?? cacheDir()
+  const weightsPath = path.join(dir, WEIGHTS_NAME)
+  const enginePath = path.join(dir, engineName)
+  try {
+    if (force || !(await exists(weightsPath))) {
+      await download(deps, `${HF_BASE}/${WEIGHTS_NAME}`, dir)
+    }
+    if (force || !(await exists(enginePath))) {
+      await download(deps, `${HF_BASE}/${hfFolderFor(deps.platform ?? process.platform, deps.arch ?? process.arch)}/${engineName.startsWith('engine-windows') ? 'needle.exe' : 'needle'}`, dir)
+      // HF keeps upstream names; rename to the per-arch bundled name.
+      const raw = engineName.startsWith('engine-windows') ? 'needle.exe' : 'needle'
+      const rawPath = path.join(dir, raw)
+      if (rawPath !== enginePath && (await exists(rawPath))) await fs.rename(rawPath, enginePath)
+    }
+    await fs.chmod(enginePath, 0o755).catch(() => {})
+    return { engineBin: enginePath, engineWeights: weightsPath }
+  } catch (e) {
+    return { error: `engine auto-download failed: ${String(e?.message ?? e)}` }
+  }
+}
+
+export async function resolveEngine(cfg, deps = {}) {
+  const platform = deps.platform ?? process.platform
+  const arch = deps.arch ?? process.arch
+  const candidates = []
+  if (cfg.engineBin && cfg.engineWeights) candidates.push({ bin: cfg.engineBin, weights: cfg.engineWeights })
+  const resources = (deps.resourcesPath ?? process.resourcesPath) ?? undefined
+  const bundled = bundledEngineName(platform, arch)
+  if (resources && bundled) {
+    candidates.push({ bin: path.join(resources, 'neuralos', bundled), weights: path.join(resources, 'neuralos', WEIGHTS_NAME) })
+  }
+  if (bundled) {
+    candidates.push({ bin: path.join(cfg.cacheDir, bundled), weights: path.join(cfg.cacheDir, WEIGHTS_NAME) })
+  }
+  candidates.push({ bin: path.join(cfg.instancesDir, 'engine', 'needle'), weights: path.join(cfg.instancesDir, 'engine', WEIGHTS_NAME) })
+  for (const c of candidates) {
+    if ((await exists(c.bin)) && (await exists(c.weights))) return { engineBin: c.bin, engineWeights: c.weights }
+  }
+  if (cfg.autoDownload) {
+    return ensureEngine({ ...deps, cacheDir: cfg.cacheDir, platform, arch })
+  }
+  return { error: 'neuralOS engine not found — set neuralos.engineBin/engineWeights (settings), install the desktop bundle, or enable autoDownload' }
+}
+
+export function parseJsonObject(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    const first = text.indexOf('{')
+    const last = text.lastIndexOf('}')
+    if (first === -1 || last <= first) return null
+    try {
+      return JSON.parse(text.slice(first, last + 1))
+    } catch {
+      return null
+    }
+  }
+}
+
+export async function listInstances(cfg, deps = {}) {
+  const readdir = deps.readdir ?? fs.readdir
+  const readFile = deps.readFile ?? fs.readFile
+  let entries
+  try {
+    entries = await readdir(cfg.instancesDir, { withFileTypes: true })
+  } catch {
+    return { error: `no instances directory at ${cfg.instancesDir} — set neuralos.instancesDir (settings) or NEURALOS_INSTANCES_DIR` }
+  }
+  const instances = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const dir = path.join(cfg.instancesDir, entry.name)
+    try {
+      const raw = await readFile(path.join(dir, 'needle_menu.json'), 'utf-8')
+      const menu = JSON.parse(raw)
+      if (!Array.isArray(menu)) continue
+      instances.push({ name: entry.name, probeCount: menu.length, probes: menu.slice(0, 40).map((t) => t.name) })
+    } catch {
+      continue
+    }
+  }
+  return instances
+}
+
+export async function instanceDirFor(cfg, instance) {
+  if (!/^[A-Za-z0-9._-]+$/.test(instance)) return { error: `invalid instance name: ${instance}` }
+  const dir = path.join(cfg.instancesDir, instance)
+  if (!(await exists(path.join(dir, 'needle_menu.json')))) {
+    return { error: `no instance named '${instance}' (see neuralos_list_instances)` }
+  }
+  return dir
+}
+
+export async function engineSelect(exec, engine, menuPath, question, opts = {}) {
+  let out
+  try {
+    out = await exec(engine.engineBin, ['--model', engine.engineWeights, '--tools', menuPath, '--prompt', question], { timeoutMs: opts.timeoutMs })
+  } catch (e) {
+    return { error: `engine execution failed: ${String(e?.message ?? e)}` }
+  }
+  if (out.code !== 0 && !out.stdout.trim()) return { error: `engine exited ${out.code}: ${out.stderr.slice(0, 200)}` }
+  const parsed = parseJsonObject(out.stdout)
+  if (!parsed) return { error: `engine output not JSON: ${out.stdout.slice(0, 120)}` }
+  const calls = parsed.function_calls
+  if (!Array.isArray(calls) || calls.length === 0 || !calls[0]?.name) {
+    return { error: 'engine refused the question (no call selected)' }
+  }
+  return { pick: calls[0].name, args: calls[0].arguments ?? {}, confidence: typeof parsed.confidence === 'number' ? parsed.confidence : null }
+}
+
+const PROBE_RUNNER = [
+  'import json, os, sys',
+  'sys.path.insert(0, os.environ["NEURALOS_INSTANCE_DIR"])',
+  'import bridge',
+  'fn = getattr(bridge, os.environ["NEURALOS_PROBE"], None)',
+  'if fn is None:',
+  '    print(json.dumps({"error": "unknown probe", "probe": os.environ["NEURALOS_PROBE"]}))',
+  'else:',
+  '    print(json.dumps(fn(**json.loads(os.environ.get("NEURALOS_ARGS", "{}"))), default=str))',
+].join('\n')
+
+export async function executeProbe(exec, cfg, instanceDir, probe, args, opts = {}) {
+  const env = {
+    NEURALOS_INSTANCE_DIR: instanceDir,
+    NEURALOS_PROBE: probe,
+    NEURALOS_ARGS: JSON.stringify(args ?? {}),
+  }
+  let out
+  try {
+    out = await exec(cfg.pythonBin, ['-c', PROBE_RUNNER], { ...opts, env })
+  } catch (e) {
+    return { error: `probe execution failed: ${String(e?.message ?? e)}` }
+  }
+  if (out.code !== 0 && !out.stdout.trim()) return { error: `probe exited ${out.code}: ${out.stderr.slice(0, 200)}` }
+  const parsed = parseJsonObject(out.stdout)
+  if (!parsed || typeof parsed !== 'object') return { error: `probe output not JSON: ${out.stdout.slice(0, 120)}` }
+  return parsed
+}
+
+/**
+ * Graph probes execute DIRECTLY by name (bypassing engine selection): probe
+ * names follow the instance convention <prefix>_graph_<op>, and the 121M
+ * model grounds numeric fragments poorly — direct execution is the fix.
+ */
+export async function graphProbe(exec, cfg, instanceDir, input) {
+  if (!['overview', 'neighbors', 'connect'].includes(input.op)) return { error: `unknown graph op: ${input.op}` }
+  const raw = await fs.readFile(path.join(instanceDir, 'needle_menu.json'), 'utf-8')
+  const menu = JSON.parse(raw)
+  const graphNames = menu.map((t) => t.name).filter((n) => n.includes('_graph_'))
+  const probe = graphNames.find((n) => n.endsWith(`_graph_${input.op}`))
+  if (!probe) return { error: `this instance has no ${input.op} graph probe`, available_graph_probes: graphNames }
+  const args = input.op === 'neighbors' ? { node: input.node ?? '' } : input.op === 'connect' ? { a: input.a ?? '', b: input.b ?? '' } : {}
+  const result = await executeProbe(exec, cfg, instanceDir, probe, args)
+  return { probe, ...result }
+}
+
+/**
+ * Admin probes are write-capable bridge functions; the confirm='yes' literal
+ * is the operator interlock (enforced at the tool schema) and this guard
+ * keeps probe names to plain identifiers.
+ */
+export async function adminProbe(exec, cfg, instanceDir, probe, args) {
+  if (!/^[A-Za-z0-9_]+$/.test(probe)) return { error: `invalid probe name: ${probe}` }
+  const result = await executeProbe(exec, cfg, instanceDir, probe, args ?? {})
+  return { probe, admin: true, result }
+}
+
+export function truncate(value, max = MAX_RESULT_CHARS) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value)
+  if (text.length <= max) return text
+  return `${text.slice(0, max)}\n… (truncated at ${max} chars)`
+}
+
+/** Streamed engine invocation for long-running selections (unused by default). */
+export function engineSelectStreamed(engine, menuPath, question) {
+  return spawn(engine.engineBin, ['--model', engine.engineWeights, '--tools', menuPath, '--prompt', question], { stdio: ['ignore', 'pipe', 'pipe'] })
+}

package/plugins/neuralos/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "neuralos",
+  "version": "1.0.0",
+  "description": "neuralOS instances as RTerm agent tools — on-device data agents over verified probe menus (chinook, cyberbank, aws, efraud, ...). The 121M neuralOS engine selects the probe for a plain-English question and the instance's Python bridge executes it against the real data source; the engine ships with the desktop bundle and the standalone backend auto-provisions ~/.cache/neuralos on first use. Four tools: neuralos_list_instances, neuralos_ask, neuralos_graph (relationship maps), neuralos_admin (write probes behind a confirm=\"yes\" interlock). Config in Settings (neuralos block: instancesDir, pythonBin, engineBin/engineWeights, autoDownload); instances root defaults to ~/neuralos-instances.",
+  "entry": "index.mjs",
+  "tools": [
+    "neuralos_list_instances",
+    "neuralos_ask",
+    "neuralos_graph",
+    "neuralos_admin"
+  ],
+  "permissions": [
+    "exec"
+  ]
+}