groove-dev 0.27.197 → 0.27.198

package/packages/daemon/src/axom-install.js

@@ -0,0 +1,140 @@
+// GROOVE — Axom Installer (manifest-driven)
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Installs the Axom runtime + models against an install manifest per contract
+// §11. The GUI (and this module) NEVER hardcodes a source — dev vs launch is
+// purely a manifest swap. Models are sha256-verified before anything is
+// configured; a failed verify configures nothing.
+//
+// Manifest shape (§11):
+//   {runtime: {kind: "pip"|"wheel-url"|"tarball", ref, sha256},
+//    models: [{file, url, sha256, bytes}], min_version}
+
+import { execFile } from 'child_process';
+import { createHash } from 'crypto';
+import { createWriteStream } from 'fs';
+import { mkdir, rename, rm } from 'fs/promises';
+import { join } from 'path';
+import os from 'os';
+import { pipeline } from 'stream/promises';
+import { Transform } from 'stream';
+import { AXOM_REQUIREMENTS } from './axom-server.js';
+
+export class AxomInstaller {
+  constructor(daemon, opts = {}) {
+    this.daemon = daemon;
+    this.pipCommand = opts.pipCommand || ['python3', '-m', 'pip'];
+    this.totalRamGbOverride = opts.totalRamGb; // tests inject; prod reads os
+    this.status = { phase: 'idle', file: null, receivedBytes: 0, totalBytes: 0, error: null };
+    this._running = false;
+  }
+
+  getStatus() {
+    return { ...this.status };
+  }
+
+  _update(patch) {
+    this.status = { ...this.status, ...patch };
+    this.daemon.broadcast({ type: 'axom:install:progress', data: this.getStatus() });
+  }
+
+  async install(manifestUrl) {
+    const url = manifestUrl || this.daemon.config?.axom?.manifestUrl;
+    if (!url) throw new Error('no install manifest configured (axom.manifestUrl)');
+    if (this._running) throw new Error('an install is already running');
+    // Same hardware floor as the instance manager — never download 4GB of
+    // weights onto a machine that can't safely run them. Manifest min_ram_gb
+    // (when present) is the authority; the static floor is the fallback.
+    if (!this.daemon.config?.axom?.allowUnderspec) {
+      const totalRamGb = this.totalRamGbOverride ?? os.totalmem() / 2 ** 30;
+      if (totalRamGb < AXOM_REQUIREMENTS.minRamGb) {
+        throw new Error(
+          `This machine has ${Math.round(totalRamGb)}GB RAM — below Axom's ${AXOM_REQUIREMENTS.minRamGb}GB floor for local inference. `
+          + 'Connect to a remote Axom endpoint instead.',
+        );
+      }
+    }
+    this._running = true;
+    try {
+      this._update({ phase: 'manifest', file: null, receivedBytes: 0, totalBytes: 0, error: null });
+      const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
+      if (!res.ok) throw new Error(`manifest fetch failed: HTTP ${res.status}`);
+      const manifest = await res.json();
+      if (!Array.isArray(manifest.models)) throw new Error('manifest has no models list');
+
+      if (manifest.runtime) await this._installRuntime(manifest.runtime);
+
+      const modelDir = this.daemon.axomServer?._modelDir()
+        || join(this.daemon.grooveDir, 'axom', 'models');
+      await mkdir(modelDir, { recursive: true });
+      for (const model of manifest.models) {
+        await this._downloadVerified(model, modelDir);
+      }
+
+      this._update({ phase: 'done', file: null });
+      this.daemon.audit.log('axom.install.complete', { models: manifest.models.length });
+      return { ok: true, models: manifest.models.length };
+    } catch (err) {
+      this._update({ phase: 'error', error: err.message });
+      throw err;
+    } finally {
+      this._running = false;
+    }
+  }
+
+  async _installRuntime(runtime) {
+    this._update({ phase: 'runtime', file: runtime.ref || null });
+    if (runtime.kind === 'pip') {
+      const [cmd, ...base] = this.pipCommand;
+      await new Promise((resolve, reject) => {
+        execFile(cmd, [...base, 'install', runtime.ref], { timeout: 600000 }, (err, _out, stderr) => {
+          if (err) reject(new Error(`pip install failed: ${stderr?.slice(-400) || err.message}`));
+          else resolve();
+        });
+      });
+      return;
+    }
+    // Honest v0 boundary — no silent no-op for kinds we don't handle yet.
+    throw new Error(`runtime kind "${runtime.kind}" is not supported by this GROOVE version`);
+  }
+
+  async _downloadVerified({ file, url, sha256, bytes }, modelDir) {
+    if (!file || !/^[a-zA-Z0-9._-]+$/.test(file)) throw new Error(`unsafe model filename: ${file}`);
+    if (!sha256) throw new Error(`manifest entry ${file} has no sha256 — refusing unverifiable download`);
+    const finalPath = join(modelDir, file);
+    const tmpPath = `${finalPath}.part`;
+    this._update({ phase: 'models', file, receivedBytes: 0, totalBytes: bytes || 0 });
+
+    const res = await fetch(url);
+    if (!res.ok || !res.body) throw new Error(`download failed for ${file}: HTTP ${res.status}`);
+
+    const hash = createHash('sha256');
+    let received = 0;
+    let lastBroadcast = 0;
+    const meter = new Transform({
+      transform: (chunk, _enc, cb) => {
+        hash.update(chunk);
+        received += chunk.length;
+        const now = Date.now();
+        if (now - lastBroadcast > 500) { // progress, throttled
+          lastBroadcast = now;
+          this._update({ receivedBytes: received });
+        }
+        cb(null, chunk);
+      },
+    });
+
+    try {
+      await pipeline(res.body, meter, createWriteStream(tmpPath));
+      const digest = hash.digest('hex');
+      if (digest !== sha256.toLowerCase()) {
+        throw new Error(`sha256 mismatch for ${file}: expected ${sha256}, got ${digest}`);
+      }
+      await rename(tmpPath, finalPath);
+      this._update({ receivedBytes: received });
+    } catch (err) {
+      await rm(tmpPath, { force: true });
+      throw err;
+    }
+  }
+}

package/packages/daemon/src/axom-server.js

@@ -0,0 +1,229 @@
+// GROOVE — Axom Server Manager (per-session local instances)
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Manages local `axom serve` processes per contract §11: one instance per
+// GROOVE session that wants its own Axom, each with its own port and its own
+// SOVEREIGN --data-dir (ledgers never shared — that isolation is the product,
+// not an implementation detail). Same lifecycle family as LlamaServerManager.
+// The serve binary refuses a locked data-dir; we surface that error verbatim
+// rather than retrying around it.
+
+import { spawn } from 'child_process';
+import { mkdirSync, statfsSync } from 'fs';
+import { join } from 'path';
+import os from 'os';
+import { AXOM_DEFAULT_PORT } from './axom-connector.js';
+
+const START_TIMEOUT_MS = 60000; // model load can be slow on first start
+
+// Local-inference floor, learned 2026-07-25: an 8GB Mac loaded the 4GB Q8
+// chassis fine, then llama_decode failed at the Metal working-set ceiling and
+// memory pressure took the whole machine down. Refusing is a feature. The
+// install manifest's min_ram_gb overrides these when present.
+export const AXOM_REQUIREMENTS = {
+  minRamGb: 12,
+  recommendedRamGb: 16,
+  minDiskGb: 6,
+  downloadGb: 4.4,
+};
+
+export function hardwareReport(dir = os.homedir(), requirements = AXOM_REQUIREMENTS) {
+  const totalRamGb = os.totalmem() / 2 ** 30;
+  let freeDiskGb = null;
+  try {
+    const s = statfsSync(dir);
+    freeDiskGb = (s.bavail * s.bsize) / 2 ** 30;
+  } catch { /* stat unavailable — report null, never guess */ }
+  const appleSilicon = process.platform === 'darwin' && process.arch === 'arm64';
+  const verdict = totalRamGb < requirements.minRamGb ? 'insufficient'
+    : totalRamGb < requirements.recommendedRamGb ? 'marginal' : 'ready';
+  return {
+    totalRamGb: Math.round(totalRamGb * 10) / 10,
+    cpuCores: os.cpus().length,
+    arch: process.arch,
+    platform: process.platform,
+    appleSilicon,
+    gpu: appleSilicon ? 'Metal (unified memory)' : null, // CUDA detection: v1
+    freeDiskGb: freeDiskGb === null ? null : Math.round(freeDiskGb * 10) / 10,
+    diskOk: freeDiskGb === null ? null : freeDiskGb >= requirements.minDiskGb,
+    verdict,
+    requirements,
+  };
+}
+
+export class AxomServerManager {
+  constructor(daemon, opts = {}) {
+    this.daemon = daemon;
+    this.command = opts.command || null; // resolved lazily from config
+    this.totalRamGbOverride = opts.totalRamGb; // tests inject; prod reads os
+    this.instances = new Map(); // id -> {id, proc, port, dataDir, status, startedAt, error}
+  }
+
+  _command() {
+    return this.command || this.daemon.config?.axom?.command || 'axom';
+  }
+
+  _modelDir() {
+    return this.daemon.config?.axom?.modelDir
+      || join(this.daemon.grooveDir, 'axom', 'models');
+  }
+
+  _allocatePort() {
+    const used = new Set([...this.instances.values()].map((i) => i.port));
+    for (const ep of this.daemon.axom?.endpoints?.values?.() || []) {
+      try { used.add(Number(new URL(ep.url).port)); } catch { /* non-numeric */ }
+    }
+    let port = AXOM_DEFAULT_PORT;
+    while (used.has(port)) port += 1;
+    return port;
+  }
+
+  list() {
+    return [...this.instances.values()].map(({ proc, ...rest }) => rest);
+  }
+
+  // Start a local instance. `id` doubles as the data-dir name, so the same id
+  // across restarts resumes the same sovereign memory.
+  async start(id = 'default') {
+    if (!/^[a-zA-Z0-9_-]{1,40}$/.test(id)) throw new Error('invalid instance id');
+    const existing = this.instances.get(id);
+    if (existing && existing.status === 'running') return this.list().find((i) => i.id === id);
+
+    // Hardware floor — refuse under-spec local inference instead of letting
+    // it take the host down. Mock mode is weightless and exempt.
+    if (!this.daemon.config?.axom?.mock && !this.daemon.config?.axom?.allowUnderspec) {
+      const totalRamGb = this.totalRamGbOverride ?? os.totalmem() / 2 ** 30;
+      if (totalRamGb < AXOM_REQUIREMENTS.minRamGb) {
+        throw new Error(
+          `This machine has ${Math.round(totalRamGb)}GB RAM — below Axom's ${AXOM_REQUIREMENTS.minRamGb}GB floor for local inference. `
+          + 'Connect to a remote Axom endpoint instead (axom.allowUnderspec overrides at your own risk).',
+        );
+      }
+    }
+
+    const port = this._allocatePort();
+    const dataDir = join(this.daemon.grooveDir, 'axom', 'instances', id);
+    mkdirSync(dataDir, { recursive: true });
+
+    const args = [
+      'serve',
+      '--host', '127.0.0.1',
+      '--port', String(port),
+      '--data-dir', dataDir,
+      '--model-dir', this._modelDir(),
+    ];
+    // config.axom.mock: run the scripted engine (§11 addendum) — the
+    // no-weights bring-up mode. /about reports family "mock" so the GUI can
+    // never mistake it for the real thing.
+    if (this.daemon.config?.axom?.mock) args.push('--mock');
+    const instance = {
+      id, port, dataDir, status: 'starting', startedAt: Date.now(), error: null, proc: null,
+    };
+    this.instances.set(id, instance);
+    this._broadcast();
+
+    let proc;
+    try {
+      proc = spawn(this._command(), args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (err) {
+      instance.status = 'error';
+      instance.error = err.message;
+      this._broadcast();
+      throw err;
+    }
+    instance.proc = proc;
+    let stderrTail = '';
+    proc.stderr?.on('data', (d) => { stderrTail = (stderrTail + d.toString()).slice(-2000); });
+    proc.on('error', (err) => {
+      instance.status = 'error';
+      instance.error = err.code === 'ENOENT'
+        ? `"${this._command()}" not found — install the Axom runtime first`
+        : err.message;
+      this._broadcast();
+    });
+    proc.on('exit', (code, signal) => {
+      const wasRunning = instance.status === 'running';
+      instance.status = instance.status === 'stopping' ? 'stopped' : 'error';
+      if (instance.status === 'error') {
+        // The lockfile refusal (§11: two instances on one data-dir) lands
+        // here — surface the runtime's own words, don't paraphrase.
+        instance.error = instance.error || stderrTail.trim().split('\n').pop() || `exited (code ${code}, signal ${signal})`;
+      }
+      instance.proc = null;
+      if (wasRunning) this._deregisterEndpoint(id);
+      this._broadcast();
+      this.daemon.audit.log('axom.instance.exit', { id, code, signal });
+    });
+
+    await this._waitForAbout(port, instance);
+    if (instance.status !== 'error') {
+      instance.status = 'running';
+      this._registerEndpoint(id, port);
+      this.daemon.audit.log('axom.instance.start', { id, port, dataDir });
+    }
+    this._broadcast();
+    if (instance.status === 'error') throw new Error(instance.error || 'instance failed to start');
+    return this.list().find((i) => i.id === id);
+  }
+
+  async stop(id) {
+    const instance = this.instances.get(id);
+    if (!instance) throw new Error(`no instance "${id}"`);
+    instance.status = 'stopping';
+    this._broadcast();
+    this._deregisterEndpoint(id);
+    if (instance.proc) {
+      instance.proc.kill('SIGTERM');
+      await new Promise((resolve) => {
+        const t = setTimeout(() => { instance.proc?.kill('SIGKILL'); resolve(); }, 5000);
+        instance.proc.once('exit', () => { clearTimeout(t); resolve(); });
+      });
+    } else {
+      instance.status = 'stopped';
+    }
+    this._broadcast();
+    this.daemon.audit.log('axom.instance.stop', { id });
+  }
+
+  async _waitForAbout(port, instance) {
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      if (instance.status === 'error') return;
+      try {
+        const res = await fetch(`http://127.0.0.1:${port}/about`, { signal: AbortSignal.timeout(2000) });
+        if (res.ok) return;
+      } catch { /* not up yet */ }
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    instance.status = 'error';
+    instance.error = instance.error || `no /about on port ${port} within ${START_TIMEOUT_MS / 1000}s`;
+    instance.proc?.kill('SIGKILL');
+  }
+
+  // Managed instances surface through the same connector as any endpoint —
+  // one socket, every tier (contract §5).
+  _registerEndpoint(id, port) {
+    const name = `local-${id}`;
+    const entries = (this.daemon.config.axom?.endpoints || []).filter((e) => e.name !== name);
+    entries.push({ name, url: `http://127.0.0.1:${port}`, managed: true });
+    this.daemon.config.axom = { ...(this.daemon.config.axom || {}), endpoints: entries };
+    this.daemon.axom.configure(entries);
+  }
+
+  _deregisterEndpoint(id) {
+    const name = `local-${id}`;
+    const entries = (this.daemon.config.axom?.endpoints || []).filter((e) => e.name !== name);
+    this.daemon.config.axom = { ...(this.daemon.config.axom || {}), endpoints: entries };
+    this.daemon.axom.configure(entries);
+  }
+
+  _broadcast() {
+    this.daemon.broadcast({ type: 'axom:instances', data: this.list() });
+  }
+
+  async destroy() {
+    for (const id of [...this.instances.keys()]) {
+      try { await this.stop(id); } catch { /* shutting down */ }
+    }
+  }
+}

package/packages/daemon/src/federation.js

@@ -355,6 +355,12 @@ export class Federation {
     };
   }
 
+  // Public accessor for this daemon's stable id (used by cross-daemon InnerChat
+  // relay to identify and verify the sender). Same value as _daemonId().
+  getDaemonId() {
+    return this._daemonId();
+  }
+
   _daemonId() {
     // Stable ID derived from keypair — fingerprint of public key
     const idPath = resolve(this.fedDir, 'daemon.id');

package/packages/daemon/src/index.js

@@ -53,6 +53,10 @@ import { Orchestrator } from './orchestrator.js';
 import { TrajectoryCapture, ConsentManager } from '../../../moe-training/client/index.js';
 import { isFirstRun, runFirstTimeSetup, loadConfig, saveConfig, printWelcome } from './firstrun.js';
 import { bindDaemon as bindGrooveNetworkDaemon } from './providers/groove-network.js';
+import { bindDaemon as bindAxomDaemon } from './providers/axom.js';
+import { AxomConnector } from './axom-connector.js';
+import { AxomServerManager } from './axom-server.js';
+import { AxomInstaller } from './axom-install.js';
 import { setProviderPaths } from './providers/index.js';
 
 const DEFAULT_PORT = 31415;
@@ -166,6 +170,9 @@ export class Daemon {
     this.watcher = new Watcher(this);
     this.autoState = new AutoState(this.grooveDir);
     this.orchestrator = new Orchestrator(this);
+    this.axom = new AxomConnector(this);
+    this.axomServer = new AxomServerManager(this);
+    this.axomInstaller = new AxomInstaller(this);
     this.trajectoryCapture = null;
 
     // Hook teams.delete to clean up agent-loop session files
@@ -202,6 +209,7 @@ export class Daemon {
     // Give the groove-network provider a handle to the daemon so it can read
     // networkBeta config at spawn time without a circular import.
     bindGrooveNetworkDaemon(this);
+    bindAxomDaemon(this);
 
     // HTTP + WebSocket server
     this.app = express();
@@ -626,6 +634,7 @@ export class Daemon {
         this.orchestrator.start();
         this.timeline.start();
         this.gateways.start();
+        this.axom.start();
         this.federation.initialize();
         this._startGarbageCollector();
 
@@ -877,6 +886,8 @@ export class Daemon {
     this.chatStore.stop();
     this.orchestrator.stop();
     this.timeline.stop();
+    await this.axomServer.destroy();
+    this.axom.destroy();
     if (this._gcInterval) clearInterval(this._gcInterval);
     if (this._stateSaveInterval) clearInterval(this._stateSaveInterval);
     if (this._classifierInterval) clearInterval(this._classifierInterval);

package/packages/daemon/src/innerchat-docs.js

@@ -9,7 +9,13 @@
 //
 // No imports on purpose — process.js and introducer.js both pull from here.
 
-export function innerChatInstructions(port = 31415, agentName = 'YOUR_NAME') {
+export function innerChatInstructions(port = 31415, agentName = 'YOUR_NAME', peers = []) {
+  const aliases = Array.isArray(peers) ? peers.map((p) => p.alias).filter(Boolean) : [];
+  const peerRule = aliases.length
+    ? `- Agents on peer machines are addressed as \`name@peer\` (configured peers: ${aliases.join(', ')}). `
+      + 'A plain name is always local; `name@peer` routes the same ask/tell to that daemon and relays the reply back.'
+    : '- To reach an agent on another machine, address it as `name@peer` (a peer must be configured first with '
+      + '`POST /api/innerchat/peers`); a plain name is always local.';
   return [
     '## Consulting Other Agents (InnerChat)',
     '',
@@ -56,6 +62,7 @@ export function innerChatInstructions(port = 31415, agentName = 'YOUR_NAME') {
     '- Only start a conversation when the user asks you to. Never consult other agents on your own initiative.',
     `- \`from\` must be your own agent name${agentName === 'YOUR_NAME' ? ' (it is in your $GROOVE_AGENT_NAME environment variable)' : ''}.`,
     '- Agent names are listed in `AGENTS_REGISTRY.md`, including agents on other teams.',
+    peerRule,
     '- Use `ask` when you need the reply now; use `tell` to hand off or notify without waiting.',
     '- One message per call. With `ask`, wait for the answer before deciding what to ask next.',
     '- Ground truth lives in files (specs, code, run output), not in chat — use InnerChat to',

package/packages/daemon/src/innerchat-relay.js

@@ -0,0 +1,89 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Cross-daemon InnerChat relay transport (spec: plans/cross-daemon-innerchat-spec.md).
+//
+// An agent addresses a peer's agent as `name@alias`. A plain `name` stays purely
+// local (zero behavior change); `name@alias` routes to the daemon configured
+// under that alias. Transport is whatever the user can already reach — a
+// tunnel-forwarded localhost port today, a Tailscale address tomorrow — so this
+// module never assumes the topology: a peer is just a URL. The daemon stays
+// bound to loopback; no new listener is opened.
+
+const RELAY_FETCH_TIMEOUT_MS = 30000; // ask holds the peer's request open
+
+// Peer config entry: { alias, url, daemonId }. Reuses the Axom connector's
+// endpoint rules for the URL (http(s), no embedded credentials) and pins the
+// peer's federation daemon id so replies/signatures resolve to one identity.
+export function validatePeer(entry) {
+  if (!entry || typeof entry !== 'object') return 'peer must be an object';
+  const { alias, url, daemonId } = entry;
+  if (!alias || typeof alias !== 'string' || !/^[a-zA-Z0-9_-]{1,40}$/.test(alias)) {
+    return 'peer alias must be 1-40 chars (letters, digits, dash, underscore)';
+  }
+  if (!url || typeof url !== 'string') return 'peer url is required';
+  let parsed;
+  try { parsed = new URL(url); } catch { return `invalid url: ${url}`; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return 'peer url must be http(s)';
+  }
+  if (parsed.username || parsed.password) return 'credentials in the url are not allowed';
+  if (!daemonId || typeof daemonId !== 'string' || !/^[a-f0-9]{6,64}$/.test(daemonId)) {
+    return 'peer daemonId must be lowercase hex (the peer daemon\'s federation id)';
+  }
+  return null;
+}
+
+// Split an InnerChat address. `name` → local (peer null). `name@alias` → remote.
+// Agent names never contain '@', so it reliably marks a peer reference. Returns
+// null on a malformed reference (empty name or empty/multi alias).
+export function parsePeerRef(ref) {
+  if (!ref || typeof ref !== 'string' || !ref.includes('@')) return { name: ref, alias: null };
+  const parts = ref.split('@');
+  if (parts.length !== 2) return null; // transitive/garbled — one hop only
+  const [name, alias] = parts.map((s) => s.trim());
+  if (!name || !alias) return null;
+  return { name, alias };
+}
+
+// Thin HTTP client for the relay. Kept injectable so tests can drive the relay
+// logic without binding two real servers.
+export class RelayClient {
+  constructor({ fetchImpl = fetch, timeoutMs = RELAY_FETCH_TIMEOUT_MS } = {}) {
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async _post(url, body, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs || this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      const json = await res.json().catch(() => ({}));
+      return { ok: res.ok, status: res.status, json };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // POST a signed relay envelope to a peer. `{ payload, signature }`.
+  sendRelay(peerUrl, envelope, timeoutMs) {
+    return this._post(`${trimUrl(peerUrl)}/api/innerchat/relay`, envelope, timeoutMs);
+  }
+
+  // Drain replies queued on a peer for us (async `tell` answers). Signed so the
+  // peer can confirm which daemon is asking and hand back only its entries.
+  fetchOutbox(peerUrl, envelope, timeoutMs) {
+    return this._post(`${trimUrl(peerUrl)}/api/innerchat/relay/outbox`, envelope, timeoutMs);
+  }
+}
+
+function trimUrl(url) {
+  return url.replace(/\/+$/, '');
+}
+
+export { RELAY_FETCH_TIMEOUT_MS };