groove-dev 0.27.197 → 0.27.199

package/node_modules/@groove-dev/daemon/src/axom-remote.js

@@ -0,0 +1,230 @@
+// GROOVE — Axom Remote Runtime Control (SSH)
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Start and stop an `axom serve` on a machine you own, over SSH, from the
+// GROOVE that talks to it. Deliberately MANUAL: nothing here auto-starts, and
+// nothing supervises or restarts a runtime that stops. The user decides when
+// the workhorse is working (Ryan, 2026-07-25: "I will turn it off and on as I
+// need... I just need the control").
+//
+// Only ever runs commands the user configured, on a host the user configured,
+// with their own SSH credentials. GROOVE holds no keys of its own.
+
+import { execFile, spawn } from 'child_process';
+import { AXOM_DEFAULT_PORT } from './axom-connector.js';
+
+const SSH_OPTS = [
+  '-o', 'ConnectTimeout=8',
+  '-o', 'StrictHostKeyChecking=accept-new',
+  '-o', 'BatchMode=yes',
+];
+
+function validateHost(host) {
+  // Hostname or IP only — no user@, no flags, no shell metacharacters. The
+  // value reaches execFile as a single argv entry, never a shell string.
+  return typeof host === 'string' && /^[a-zA-Z0-9._-]{1,253}$/.test(host);
+}
+
+function validateUser(user) {
+  return typeof user === 'string' && /^[a-zA-Z0-9._-]{1,32}$/.test(user);
+}
+
+export function validateRemote(remote) {
+  if (!remote || typeof remote !== 'object') return 'remote config must be an object';
+  if (!validateHost(remote.host)) return 'invalid host';
+  if (!validateUser(remote.user)) return 'invalid user';
+  if (remote.sshPort !== undefined && !(Number.isInteger(remote.sshPort) && remote.sshPort > 0 && remote.sshPort < 65536)) {
+    return 'invalid sshPort';
+  }
+  if (remote.port !== undefined && !(Number.isInteger(remote.port) && remote.port > 0 && remote.port < 65536)) {
+    return 'invalid port';
+  }
+  if (remote.command !== undefined && (typeof remote.command !== 'string' || remote.command.length > 500)) {
+    return 'command must be a string of at most 500 chars';
+  }
+  return null;
+}
+
+export class AxomRemote {
+  constructor(daemon, opts = {}) {
+    this.daemon = daemon;
+    this.exec = opts.exec || execFile; // tests inject
+  }
+
+  _config() {
+    return this.daemon.config?.axom?.remote || null;
+  }
+
+  _ssh(command, timeoutMs = 30000) {
+    const cfg = this._config();
+    if (!cfg) return Promise.reject(new Error('no remote Axom host configured'));
+    const problem = validateRemote(cfg);
+    if (problem) return Promise.reject(new Error(`remote config invalid: ${problem}`));
+
+    const args = [...SSH_OPTS, '-p', String(cfg.sshPort || 22), `${cfg.user}@${cfg.host}`, command];
+    return new Promise((resolve, reject) => {
+      this.exec('ssh', args, { encoding: 'utf8', timeout: timeoutMs }, (err, stdout, stderr) => {
+        if (err && !stdout) return reject(new Error((stderr || err.message || '').trim().split('\n').pop()));
+        resolve({ stdout: String(stdout || ''), stderr: String(stderr || '') });
+      });
+    });
+  }
+
+  // Is a runtime listening on the remote port right now?
+  async status() {
+    const cfg = this._config();
+    if (!cfg) return { configured: false, running: null };
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+    try {
+      const { stdout } = await this._ssh(
+        `curl -sf --max-time 4 http://127.0.0.1:${port}/about >/dev/null 2>&1 && echo UP || echo DOWN`,
+        15000,
+      );
+      return {
+        configured: true,
+        host: cfg.host,
+        user: cfg.user,
+        port,
+        running: stdout.includes('UP'),
+        error: null,
+      };
+    } catch (err) {
+      // Unreachable host is not "not running" — we genuinely do not know.
+      return { configured: true, host: cfg.host, user: cfg.user, port, running: null, error: err.message };
+    }
+  }
+
+  async start() {
+    const cfg = this._config();
+    if (!cfg) throw new Error('no remote Axom host configured');
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+    const already = await this.status();
+    if (already.running) return { started: false, alreadyRunning: true, port };
+
+    const command = cfg.command
+      || `axom serve --port ${port} --data-dir ~/axom-serve/data --model-dir ~/axom-serve/models`;
+    // Detached from this SSH session so it survives the connection closing.
+    // No supervisor, no restart-on-exit: manual control means manual.
+    const log = cfg.logPath || '~/axom-serve/serve.log';
+    await this._ssh(`nohup ${command} >> ${log} 2>&1 < /dev/null & disown; echo STARTED`, 30000);
+
+    // Confirm it actually came up rather than reporting optimism.
+    for (let i = 0; i < 30; i++) {
+      await new Promise((r) => setTimeout(r, 2000));
+      const s = await this.status();
+      if (s.running) {
+        this.daemon.audit.log('axom.remote.start', { host: cfg.host, port });
+        this._broadcast();
+        return { started: true, port, logPath: log };
+      }
+    }
+    throw new Error(`started the command but nothing answered on port ${port} within 60s — check ${log} on ${cfg.host}`);
+  }
+
+  async stop({ force = false } = {}) {
+    const cfg = this._config();
+    if (!cfg) throw new Error('no remote Axom host configured');
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+
+    // Prefer the contract's own verb (§14): it flushes the ledger and
+    // releases the lockfile. Fall back to a signal only if the runtime
+    // predates the verb.
+    try {
+      const { stdout } = await this._ssh(
+        `curl -s -o /dev/null -w '%{http_code}' --max-time 8 -X POST `
+        + `-H 'Content-Type: application/json' -d '{"force":${force ? 'true' : 'false'}}' `
+        + `http://127.0.0.1:${port}/shutdown`,
+        20000,
+      );
+      const code = parseInt(stdout.trim().slice(-3), 10);
+      if (code === 202) {
+        this.daemon.audit.log('axom.remote.stop', { host: cfg.host, port, via: 'shutdown' });
+        this._broadcast();
+        return { stopped: true, via: 'shutdown' };
+      }
+      if (code === 409) return { stopped: false, turnInFlight: true };
+      if (code !== 404) throw new Error(`shutdown returned HTTP ${code}`);
+    } catch (err) {
+      if (!/HTTP 404/.test(err.message)) throw err;
+    }
+
+    // Pre-§14 runtime: signal the process that owns the port. Still the
+    // user's own machine, still an explicit action they asked for.
+    await this._ssh(`PID=$(lsof -t -i:${port} 2>/dev/null | head -1); [ -n "$PID" ] && kill $PID && echo KILLED || echo NOTFOUND`, 20000);
+    this.daemon.audit.log('axom.remote.stop', { host: cfg.host, port, via: 'signal' });
+    this._broadcast();
+    return { stopped: true, via: 'signal' };
+  }
+
+  // ── Reachability (the port-forward), distinct from runtime lifecycle ──────
+  //
+  // The runtime is the user's workhorse and is never touched automatically.
+  // The TUNNEL is plumbing: it dies on every sleep/wake (ssh's keepalive exits
+  // on resume and nothing respawns it), costs the remote machine nothing, and
+  // its death looks identical to "Axom is down" from the GUI. So we heal it on
+  // demand — but only ever a tunnel GROOVE opened, and only after a health
+  // check proves the port is genuinely dead (an unconditional teardown kills
+  // slow-but-working tunnels — learned by fullstack-3 the hard way).
+
+  async _portAnswers(port, timeoutMs = 2500) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/about`, { signal: AbortSignal.timeout(timeoutMs) });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async ensureTunnel() {
+    const cfg = this._config();
+    if (!cfg) return { tunneled: false, reason: 'no remote configured' };
+    const problem = validateRemote(cfg);
+    if (problem) return { tunneled: false, reason: problem };
+    const port = cfg.port || AXOM_DEFAULT_PORT;
+
+    if (await this._portAnswers(port)) return { tunneled: true, healed: false, port };
+
+    // Port is genuinely dead. If a tunnel process of ours is lingering, drop
+    // it before opening another (a stale forward holds the local port and the
+    // new ssh would fail with "address already in use").
+    if (this._tunnelProc && !this._tunnelProc.killed) {
+      try { this._tunnelProc.kill(); } catch { /* already gone */ }
+      this._tunnelProc = null;
+    }
+
+    const args = [
+      '-N', '-L', `127.0.0.1:${port}:localhost:${port}`,
+      ...SSH_OPTS,
+      '-o', 'ServerAliveInterval=30',
+      '-o', 'ExitOnForwardFailure=yes',
+      '-p', String(cfg.sshPort || 22),
+      `${cfg.user}@${cfg.host}`,
+    ];
+    const proc = spawn('ssh', args, { stdio: 'ignore', detached: false });
+    this._tunnelProc = proc;
+    proc.on('exit', () => { if (this._tunnelProc === proc) this._tunnelProc = null; });
+
+    for (let i = 0; i < 10; i++) {
+      await new Promise((r) => setTimeout(r, 500));
+      if (await this._portAnswers(port, 1500)) {
+        this.daemon.audit.log('axom.remote.tunnel', { host: cfg.host, port });
+        return { tunneled: true, healed: true, port };
+      }
+      if (proc.exitCode !== null) break;
+    }
+    // Honest failure: the forward may be up while the runtime is down — say
+    // what we know (port silent) rather than asserting a cause.
+    return { tunneled: false, healed: false, port, reason: `nothing answers on 127.0.0.1:${port} after opening the forward — the runtime may be stopped` };
+  }
+
+  closeTunnel() {
+    if (this._tunnelProc && !this._tunnelProc.killed) {
+      try { this._tunnelProc.kill(); } catch { /* already gone */ }
+    }
+    this._tunnelProc = null;
+  }
+
+  _broadcast() {
+    this.status().then((s) => this.daemon.broadcast({ type: 'axom:remote', data: s })).catch(() => {});
+  }
+}

package/node_modules/@groove-dev/daemon/src/axom-server.js

@@ -0,0 +1,249 @@
+// 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.portBase = opts.portBase || AXOM_DEFAULT_PORT;
+    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 = this.portBase;
+    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) {
+          // Verify the answer is OURS. Another process (or an SSH tunnel to a
+          // remote runtime) can already own this port; adopting it would let
+          // GROOVE claim — and offer to shut down — a runtime it never
+          // launched. §11 gives /about an instance block; when it names a
+          // different pid or data-dir, this port is not ours.
+          const about = await res.json().catch(() => null);
+          const claimed = about?.instance;
+          const foreign = claimed
+            && ((claimed.pid && instance.proc?.pid && claimed.pid !== instance.proc.pid)
+              || (claimed.data_dir && claimed.data_dir !== instance.dataDir));
+          if (foreign) {
+            instance.status = 'error';
+            instance.error = `port ${port} is already served by another Axom runtime `
+              + `(${claimed.data_dir || `pid ${claimed.pid}`}) — refusing to adopt it`;
+            instance.proc?.kill('SIGKILL');
+            return;
+          }
+          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/node_modules/@groove-dev/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/node_modules/@groove-dev/daemon/src/index.js

@@ -53,6 +53,11 @@ 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 { AxomRemote } from './axom-remote.js';
 import { setProviderPaths } from './providers/index.js';
 
 const DEFAULT_PORT = 31415;
@@ -166,6 +171,10 @@ 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.axomRemote = new AxomRemote(this);
     this.trajectoryCapture = null;
 
     // Hook teams.delete to clean up agent-loop session files
@@ -202,6 +211,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 +636,7 @@ export class Daemon {
         this.orchestrator.start();
         this.timeline.start();
         this.gateways.start();
+        this.axom.start();
         this.federation.initialize();
         this._startGarbageCollector();
 
@@ -877,6 +888,9 @@ export class Daemon {
     this.chatStore.stop();
     this.orchestrator.stop();
     this.timeline.stop();
+    this.axomRemote.closeTunnel();
+    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/node_modules/@groove-dev/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/node_modules/@groove-dev/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 };