groove-dev 0.27.197 → 0.27.199

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

@@ -0,0 +1,267 @@
+// FSL-1.1-Apache-2.0 — see LICENSE
+
+import os from 'os';
+import { saveConfig } from '../firstrun.js';
+import { validateEndpoint, AXOM_DEFAULT_PORT } from '../axom-connector.js';
+import { hardwareReport } from '../axom-server.js';
+import { validateRemote } from '../axom-remote.js';
+
+// Interrupt text is capped runtime-side at 2000 chars (contract §2, with a
+// `truncated` flag in the response); we allow headroom and let the runtime be
+// the authority on truncation — its flag is the honest signal, not ours.
+const MAX_INTERRUPT_CHARS = 8000;
+
+export function registerAxomRoutes(app, daemon) {
+  app.get('/api/axom/status', (req, res) => {
+    res.json(daemon.axom.status());
+  });
+
+  app.get('/api/axom/sessions', (req, res) => {
+    const sessions = daemon.axom.status().endpoints.flatMap((ep) =>
+      ep.sessions.map((s) => ({ endpoint: ep.name, ...s })));
+    res.json(sessions);
+  });
+
+  // In-daemon ring backfill for the GUI (initial load / scrubber). `since` is
+  // an envelope id ("ev-000123"); events after it are returned.
+  app.get('/api/axom/sessions/:id/events', (req, res) => {
+    try {
+      const sinceSeq = /^ev-\d+$/.test(req.query.since || '')
+        ? parseInt(req.query.since.slice(3), 10) : 0;
+      res.json(daemon.axom.events(req.query.endpoint, req.params.id, sinceSeq));
+    } catch (err) {
+      res.status(404).json({ error: err.message });
+    }
+  });
+
+  // §12: message starts a turn. Contract statuses (202/409/413) mirror
+  // through verbatim — the GUI reads them, we don't reinterpret.
+  app.post('/api/axom/sessions/:id/message', async (req, res) => {
+    try {
+      const { text, endpoint, clientRef } = req.body || {};
+      if (!text || typeof text !== 'string' || !text.trim()) {
+        return res.status(400).json({ error: 'text is required' });
+      }
+      if (clientRef !== undefined && (typeof clientRef !== 'string' || clientRef.length > 64)) {
+        return res.status(400).json({ error: 'clientRef must be a string of at most 64 chars' });
+      }
+      const result = await daemon.axom.message(endpoint, req.params.id, text, clientRef);
+      daemon.audit.log('axom.message', { session: req.params.id, chars: text.length, status: result.status });
+      res.status(result.status).json(result.body);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/sessions/:id/interrupt', async (req, res) => {
+    try {
+      const { text, endpoint } = req.body || {};
+      if (!text || typeof text !== 'string' || !text.trim()) {
+        return res.status(400).json({ error: 'text is required' });
+      }
+      if (text.length > MAX_INTERRUPT_CHARS) {
+        return res.status(400).json({ error: `text exceeds ${MAX_INTERRUPT_CHARS} chars` });
+      }
+      const result = await daemon.axom.interrupt(endpoint, req.params.id, text);
+      daemon.audit.log('axom.interrupt', { session: req.params.id, chars: text.length });
+      res.json(result); // verbatim {id, truncated} from the runtime
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/sessions/:id/stop', async (req, res) => {
+    try {
+      const result = await daemon.axom.stop(req.body?.endpoint, req.params.id);
+      daemon.audit.log('axom.stop', { session: req.params.id });
+      res.json(result);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  // Machine readiness for local inference — powers the welcome page's
+  // "can this device run Axom?" verdict.
+  app.get('/api/axom/hardware', (req, res) => {
+    res.json(hardwareReport(daemon.grooveDir));
+  });
+
+  // This GROOVE's own Axom endpoint — what another instance would paste.
+  // serve binds 127.0.0.1 (§6), so cross-machine reach is the user's own
+  // channel; we hand them the exact tunnel one-liner rather than pretending
+  // the URL travels on its own.
+  app.get('/api/axom/my-endpoint', (req, res) => {
+    const running = daemon.axomServer.list().find((i) => i.status === 'running');
+    const port = running?.port || AXOM_DEFAULT_PORT;
+    const host = os.hostname();
+    const user = os.userInfo().username;
+    res.json({
+      url: `http://127.0.0.1:${port}`,
+      port,
+      host,
+      running: !!running,
+      instanceId: running?.id || null,
+      tunnelCommand: `ssh -N -L ${port}:localhost:${port} ${user}@${host}`,
+    });
+  });
+
+  // §14: shut down the runtime itself. Works for any endpoint that supports
+  // the verb — including remote ones, which GROOVE could never reach with a
+  // signal. A 404 means the runtime predates §14; the GUI must say so rather
+  // than claim the runtime is gone.
+  app.post('/api/axom/shutdown', async (req, res) => {
+    try {
+      const result = await daemon.axom.shutdown(req.body?.endpoint, { force: !!req.body?.force });
+      daemon.audit.log('axom.shutdown', { endpoint: req.body?.endpoint || null, status: result.status });
+      res.status(result.status === 404 ? 501 : result.status)
+        .json(result.status === 404
+          ? { error: 'this runtime does not support remote shutdown (predates contract §14)' }
+          : result.body);
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  // ── Remote runtime control over SSH (manual only, never automatic) ──────
+
+  app.get('/api/axom/remote', async (req, res) => {
+    res.json(await daemon.axomRemote.status());
+  });
+
+  app.patch('/api/axom/remote', (req, res) => {
+    const remote = req.body || {};
+    if (remote.clear === true) {
+      delete daemon.config.axom?.remote;
+      saveConfig(daemon.grooveDir, daemon.config);
+      return res.json({ configured: false });
+    }
+    const problem = validateRemote(remote);
+    if (problem) return res.status(400).json({ error: problem });
+    const { host, user, sshPort, port, command, logPath } = remote;
+    daemon.config.axom = {
+      ...(daemon.config.axom || {}),
+      remote: { host, user, sshPort, port, command, logPath },
+    };
+    saveConfig(daemon.grooveDir, daemon.config);
+    daemon.audit.log('axom.remote.config', { host, user });
+    res.json(daemon.config.axom.remote);
+  });
+
+  // Reachability only — opens/heals the port-forward. Never starts a runtime.
+  app.post('/api/axom/remote/tunnel', async (req, res) => {
+    try {
+      res.json(await daemon.axomRemote.ensureTunnel());
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/remote/start', async (req, res) => {
+    try {
+      res.json(await daemon.axomRemote.start());
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/axom/remote/stop', async (req, res) => {
+    try {
+      res.json(await daemon.axomRemote.stop({ force: !!req.body?.force }));
+    } catch (err) {
+      res.status(502).json({ error: err.message });
+    }
+  });
+
+  // ── Managed local instances (contract §11) ──────────────────────────────
+
+  app.get('/api/axom/instances', (req, res) => {
+    res.json(daemon.axomServer.list());
+  });
+
+  app.post('/api/axom/instances', async (req, res) => {
+    try {
+      const instance = await daemon.axomServer.start(req.body?.id || 'default');
+      res.json(instance);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.delete('/api/axom/instances/:id', async (req, res) => {
+    try {
+      await daemon.axomServer.stop(req.params.id);
+      res.json({ ok: true });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // ── Manifest-driven install (contract §11) ──────────────────────────────
+
+  app.get('/api/axom/install', (req, res) => {
+    res.json(daemon.axomInstaller.getStatus());
+  });
+
+  app.post('/api/axom/install', (req, res) => {
+    // Long-running — kick off and let the axom:install:progress broadcasts
+    // carry the story; the GUI polls GET /api/axom/install as backstop.
+    daemon.axomInstaller.install(req.body?.manifestUrl).catch(() => { /* status carries the error */ });
+    res.json({ started: true });
+  });
+
+  app.get('/api/axom/config', (req, res) => {
+    res.json({ endpoints: daemon.config.axom?.endpoints || [] });
+  });
+
+  app.patch('/api/axom/config', (req, res) => {
+    const { endpoints, command, mock, manifestUrl, modelDir } = req.body || {};
+
+    // Runtime settings (contract §11): serve binary path, mock mode,
+    // install-manifest URL, model dir. Any subset may be patched alone.
+    const settings = {};
+    if (command !== undefined) {
+      if (command !== null && (typeof command !== 'string' || !command.trim())) {
+        return res.status(400).json({ error: 'command must be a non-empty string or null' });
+      }
+      settings.command = command;
+    }
+    if (mock !== undefined) settings.mock = !!mock;
+    if (manifestUrl !== undefined) {
+      if (manifestUrl !== null && !/^https?:\/\//.test(manifestUrl)) {
+        return res.status(400).json({ error: 'manifestUrl must be http(s) or null' });
+      }
+      settings.manifestUrl = manifestUrl;
+    }
+    if (modelDir !== undefined) settings.modelDir = modelDir;
+    if (Object.keys(settings).length > 0) {
+      daemon.config.axom = { ...(daemon.config.axom || {}), ...settings };
+      if (endpoints === undefined) {
+        saveConfig(daemon.grooveDir, daemon.config);
+        daemon.audit.log('axom.config', { keys: Object.keys(settings) });
+        return res.json({ ...daemon.config.axom });
+      }
+    }
+
+    if (!Array.isArray(endpoints)) {
+      return res.status(400).json({ error: 'endpoints array is required' });
+    }
+    if (endpoints.length > 16) {
+      return res.status(400).json({ error: 'too many endpoints (max 16)' });
+    }
+    const seen = new Set();
+    for (const entry of endpoints) {
+      const problem = validateEndpoint(entry);
+      if (problem) return res.status(400).json({ error: problem });
+      if (seen.has(entry.name)) {
+        return res.status(400).json({ error: `duplicate endpoint name: ${entry.name}` });
+      }
+      seen.add(entry.name);
+    }
+    const cleaned = endpoints.map(({ name, url }) => ({ name, url: url.replace(/\/+$/, '') }));
+    daemon.config.axom = { ...(daemon.config.axom || {}), endpoints: cleaned };
+    saveConfig(daemon.grooveDir, daemon.config);
+    daemon.axom.configure(cleaned);
+    daemon.audit.log('axom.config', { endpoints: cleaned.map((e) => e.name) });
+    res.json({ endpoints: cleaned });
+  });
+}

package/node_modules/@groove-dev/daemon/src/routes/innerchat.js

@@ -1,6 +1,11 @@
 // FSL-1.1-Apache-2.0 — see LICENSE
 
 import { MAX_EXCHANGES } from '../innerchat.js';
+import { readFileSync } from 'fs';
+import { validatePeer, parsePeerRef } from '../innerchat-relay.js';
+import { saveConfig } from '../firstrun.js';
+
+const pkgVersion = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
 
 // Agents know each other by name, not id. Exact matches win first so
 // `fullstack-1` never resolves to `fullstack-14`; only if nothing matches
@@ -22,14 +27,16 @@ function resolveAgent(daemon, ref) {
   return partial.length === 1 ? partial[0] : null;
 }
 
-// Resolve the from/to pair from a request body, or write the appropriate
-// 400/404 and return null so the caller bails.
-function resolveParties(daemon, req, res) {
-  const { from, to, message } = req.body || {};
-
+// The calling agent is always local. Writes a 404 and returns null on miss.
+function resolveFrom(daemon, from, res) {
   const fromAgent = resolveAgent(daemon, from);
   if (!fromAgent) { res.status(404).json({ error: `Unknown calling agent: ${from}` }); return null; }
+  return fromAgent;
+}
 
+// Resolve a LOCAL to/message pair, or write the appropriate 400/404 and return
+// null. Used only when `to` is a plain (non-peer) name.
+function resolveLocalTo(daemon, fromAgent, to, message, res) {
   const toAgent = resolveAgent(daemon, to);
   if (!toAgent) {
     const others = daemon.registry.getAll().filter((a) => a.id !== fromAgent.id);
@@ -42,32 +49,157 @@ function resolveParties(daemon, req, res) {
     }
     return null;
   }
-
   if (!message || typeof message !== 'string' || !message.trim()) {
     res.status(400).json({ error: 'message is required' }); return null;
   }
-  return { fromAgent, toAgent, message: message.trim() };
+  return { toAgent, message: message.trim() };
+}
+
+// Confirm a relay request is from a configured, signature-verified peer.
+// Returns the peer record, or writes a 403 and returns null.
+function verifyRelayCaller(daemon, body, res) {
+  const { payload, signature } = body || {};
+  if (!payload || typeof payload !== 'object' || !signature) {
+    res.status(400).json({ error: 'signed relay envelope required ({ payload, signature })' });
+    return null;
+  }
+  const fromDaemonId = payload.fromDaemonId;
+  const peer = daemon.innerchat._peerByDaemonId(fromDaemonId);
+  if (!peer) {
+    res.status(403).json({ error: `Unknown daemon "${String(fromDaemonId).slice(0, 16)}" — not a configured InnerChat peer.` });
+    return null;
+  }
+  if (!daemon.federation.verify(fromDaemonId, payload, signature)) {
+    res.status(403).json({ error: 'Signature verification failed.' });
+    return null;
+  }
+  return peer;
+}
+
+// A peer relay is accepted only when the sender is BOTH a configured peer
+// (in innerchatPeers — the human's decision) AND signature-verifies against a
+// stored federation public key. Those are independent gates, which is what
+// makes automatic key exchange safe: holding someone's public key grants
+// nothing on its own. So adding a peer can fetch and store its key without a
+// separate manual pairing step.
+async function exchangeKeys(daemon, url, alias) {
+  const base = url.replace(/\/+$/, '');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8000);
+  try {
+    const res = await fetch(`${base}/api/innerchat/identity`, { signal: controller.signal });
+    if (!res.ok) throw new Error(`peer returned HTTP ${res.status}`);
+    const id = await res.json();
+    if (!id?.daemonId || !id?.publicKey) throw new Error('peer did not return an identity');
+
+    // Store their key so we can verify what they send us.
+    daemon.federation._savePeer({
+      id: id.daemonId,
+      name: alias,
+      host: new URL(base).hostname,
+      port: Number(new URL(base).port) || 80,
+      publicKey: id.publicKey,
+      pairedAt: new Date().toISOString(),
+    });
+
+    // Push ours so they can verify what WE send — this is the half that
+    // otherwise required a manual step on the other machine.
+    let pushed = false;
+    try {
+      const push = await fetch(`${base}/api/innerchat/identity`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          daemonId: daemon.federation.getDaemonId(),
+          publicKey: daemon.federation.getPublicKeyPem(),
+          name: daemon.config?.daemonName || 'groove',
+        }),
+        signal: controller.signal,
+      });
+      pushed = push.ok;
+    } catch { /* reachable for GET but not POST — report partial */ }
+
+    return { ok: true, peerDaemonId: id.daemonId, peerVersion: id.version, pushed };
+  } finally {
+    clearTimeout(timer);
+  }
 }
 
 export function registerInnerChatRoutes(app, daemon) {
+  /**
+   * This daemon's federation identity. Read-only and non-secret (a public key
+   * plus an id); the peer needs it to verify signed relays from us.
+   */
+  app.get('/api/innerchat/identity', (req, res) => {
+    res.json({
+      daemonId: daemon.federation.getDaemonId(),
+      publicKey: daemon.federation.getPublicKeyPem(),
+      version: pkgVersion,
+      port: daemon.port,
+      agents: daemon.registry.getAll().map((a) => a.name),
+    });
+  });
+
+  /**
+   * Accept a peer's public key so we can verify its signed relays. Storing a
+   * key authorizes nothing by itself — a relay ALSO requires that daemon to be
+   * listed in innerchatPeers, which only the user can do. That second gate is
+   * what keeps this endpoint safe to accept without a pairing dance.
+   */
+  app.post('/api/innerchat/identity', (req, res) => {
+    const { daemonId, publicKey, name } = req.body || {};
+    if (!daemonId || !/^[a-f0-9]{6,64}$/.test(String(daemonId))) {
+      return res.status(400).json({ error: 'valid daemonId required' });
+    }
+    if (!publicKey || typeof publicKey !== 'string' || !publicKey.includes('PUBLIC KEY')) {
+      return res.status(400).json({ error: 'publicKey (PEM) required' });
+    }
+    daemon.federation._savePeer({
+      id: daemonId,
+      name: typeof name === 'string' && name.trim() ? name.trim().slice(0, 40) : daemonId,
+      host: (req.ip || '').replace('::ffff:', '') || '127.0.0.1',
+      port: 0,
+      publicKey,
+      pairedAt: new Date().toISOString(),
+    });
+    daemon.audit.log('innerchat.key.received', { daemonId });
+    res.json({
+      ok: true,
+      // Hand back ours so a single call completes the exchange either way.
+      daemonId: daemon.federation.getDaemonId(),
+      publicKey: daemon.federation.getPublicKeyPem(),
+    });
+  });
+
   /**
    * Ask another agent a question and BLOCK until it answers.
    *
-   * This request is held open deliberately — the calling agent is waiting on
-   * it, and the response body is the other agent's reply. Best for tight
-   * interface negotiation, where the finite exchange budget keeps both sides
-   * writing decision-dense messages.
+   * `to` may be a local name or `name@peer`. A peer target is relayed to the
+   * configured peer daemon; the reply rides the still-open response back.
    */
   app.post('/api/innerchat/ask', async (req, res) => {
     try {
-      const parties = resolveParties(daemon, req, res);
-      if (!parties) return;
+      const { from, to, message } = req.body || {};
+      const fromAgent = resolveFrom(daemon, from, res);
+      if (!fromAgent) return;
 
       // Held open until the target answers — see the class doc in innerchat.js.
       req.setTimeout(0);
       res.setTimeout(0);
 
-      const result = await daemon.innerchat.ask(parties.fromAgent.id, parties.toAgent.id, parties.message, {
+      if (daemon.innerchat.isRemoteRef(to)) {
+        const { name, alias } = parsePeerRef(to);
+        if (!message || !String(message).trim()) return res.status(400).json({ error: 'message is required' });
+        const result = await daemon.innerchat.askRemote(fromAgent, name, alias, String(message).trim(), {
+          timeoutMs: req.body?.timeoutMs,
+        });
+        return res.json({ from: `${name}@${alias}`, reply: result.reply, threadId: result.threadId, remote: true });
+      }
+
+      const parties = resolveLocalTo(daemon, fromAgent, to, message, res);
+      if (!parties) return;
+
+      const result = await daemon.innerchat.ask(fromAgent.id, parties.toAgent.id, parties.message, {
         timeoutMs: req.body?.timeoutMs,
       });
 
@@ -86,17 +218,34 @@ export function registerInnerChatRoutes(app, daemon) {
   });
 
   /**
-   * Send a message WITHOUT blocking — returns as soon as it's delivered. If the
-   * target replies, the reply is routed back to the sender asynchronously
-   * (resuming it if its turn ended). Best for handing off to a heads-down agent
-   * where waiting out a timeout would waste the turn.
+   * Send a message WITHOUT blocking. `to` may be local or `name@peer`. For a
+   * peer target the reply (if any) is queued on the peer and picked up by this
+   * daemon's outbox poll, then routed back to the sender.
    */
   app.post('/api/innerchat/tell', async (req, res) => {
     try {
-      const parties = resolveParties(daemon, req, res);
+      const { from, to, message } = req.body || {};
+      const fromAgent = resolveFrom(daemon, from, res);
+      if (!fromAgent) return;
+
+      if (daemon.innerchat.isRemoteRef(to)) {
+        const { name, alias } = parsePeerRef(to);
+        if (!message || !String(message).trim()) return res.status(400).json({ error: 'message is required' });
+        const result = await daemon.innerchat.tellRemote(fromAgent, name, alias, String(message).trim());
+        return res.json({
+          ok: true,
+          to: `${name}@${alias}`,
+          delivered: result.delivered,
+          threadId: result.threadId,
+          remote: true,
+          note: `Message relayed to ${name}@${alias}. Its reply, if any, will be routed back to you — you can end your turn.`,
+        });
+      }
+
+      const parties = resolveLocalTo(daemon, fromAgent, to, message, res);
       if (!parties) return;
 
-      const result = await daemon.innerchat.tell(parties.fromAgent.id, parties.toAgent.id, parties.message, {
+      const result = await daemon.innerchat.tell(fromAgent.id, parties.toAgent.id, parties.message, {
         threadId: req.body?.threadId,
       });
 
@@ -115,6 +264,171 @@ export function registerInnerChatRoutes(app, daemon) {
     }
   });
 
+  // ── Cross-daemon relay endpoints (peer daemon → this daemon) ──
+
+  /**
+   * Receive a relayed ask/tell from a peer daemon. Signature-verified and
+   * restricted to configured peers. Resolves the target locally and delivers
+   * with a guest identity. For 'ask' the response is held open until the local
+   * agent answers.
+   */
+  app.post('/api/innerchat/relay', async (req, res) => {
+    const peer = verifyRelayCaller(daemon, req.body, res);
+    if (!peer) return;
+    const p = req.body.payload;
+    if (p.type !== 'innerchat.relay' || (p.kind !== 'ask' && p.kind !== 'tell')) {
+      return res.status(400).json({ error: 'invalid relay payload' });
+    }
+    try {
+      req.setTimeout(0);
+      res.setTimeout(0);
+      const result = await daemon.innerchat.receiveRelay({
+        fromName: p.fromName,
+        fromRole: p.fromRole,
+        fromDaemonId: p.fromDaemonId,
+        peerAlias: peer.alias,
+        toName: p.toName,
+        message: p.message,
+        kind: p.kind,
+        threadId: p.threadId,
+        timeoutMs: p.timeoutMs,
+      });
+      res.json(result);
+    } catch (err) {
+      const body = { error: err.message };
+      if (err.availableAgents) body.availableAgents = err.availableAgents;
+      res.status(404).json(body);
+    }
+  });
+
+  /**
+   * Drain this daemon's outbox of async (tell) replies queued for the calling
+   * peer. Signature-verified; returns and removes only that peer's entries.
+   */
+  app.post('/api/innerchat/relay/outbox', (req, res) => {
+    const peer = verifyRelayCaller(daemon, req.body, res);
+    if (!peer) return;
+    if (req.body.payload.type !== 'innerchat.outbox') {
+      return res.status(400).json({ error: 'invalid outbox payload' });
+    }
+    res.json({ entries: daemon.innerchat.drainOutbox(req.body.payload.fromDaemonId) });
+  });
+
+  // ── Peer configuration (alias ↔ url ↔ daemonId) ──────────────
+
+  app.get('/api/innerchat/peers', (req, res) => {
+    res.json({ peers: daemon.innerchat._peers() });
+  });
+
+  /**
+   * Add a peer. The daemonId is discovered from the peer itself rather than
+   * typed, and public keys are exchanged automatically, so the user only has
+   * to supply a name and a reachable URL.
+   */
+  app.post('/api/innerchat/peers', async (req, res) => {
+    const alias = req.body?.alias;
+    const rawUrl = req.body?.url;
+    if (!alias || typeof alias !== 'string' || !/^[a-zA-Z0-9_-]{1,40}$/.test(alias)) {
+      return res.status(400).json({ error: 'peer name must be 1-40 chars (letters, digits, dash, underscore)' });
+    }
+    if (!rawUrl || typeof rawUrl !== 'string') return res.status(400).json({ error: 'peer url is required' });
+
+    let url;
+    try {
+      const parsed = new URL(rawUrl.trim());
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return res.status(400).json({ error: 'peer url must be http(s)' });
+      }
+      if (parsed.username || parsed.password) return res.status(400).json({ error: 'credentials in the url are not allowed' });
+      url = rawUrl.trim().replace(/\/+$/, '');
+    } catch { return res.status(400).json({ error: `invalid url: ${rawUrl}` }); }
+
+    // Reach the peer, learn its id, and trade keys. This is the step that used
+    // to be a manual federation pairing.
+    let exchange;
+    try {
+      exchange = await exchangeKeys(daemon, url, alias);
+    } catch (err) {
+      return res.status(502).json({
+        error: `Could not reach a Groove daemon at ${url} — ${err.message}. `
+          + 'Check the URL (for a tunnelled peer this is the forwarded local port, not 31415) and that the peer daemon is running the current version.',
+      });
+    }
+
+    if (exchange.peerDaemonId === daemon.federation.getDaemonId()) {
+      return res.status(400).json({
+        error: `That URL points at THIS daemon, not a peer. For a tunnelled machine use the forwarded local port (e.g. http://127.0.0.1:31416), not ${url}.`,
+      });
+    }
+
+    const entry = { alias, url, daemonId: exchange.peerDaemonId };
+    const check = validatePeer(entry);
+    if (check) return res.status(400).json({ error: check });
+
+    const peers = Array.isArray(daemon.config.innerchatPeers) ? daemon.config.innerchatPeers : [];
+    const next = peers.filter((p) => p.alias !== alias);
+    next.push(entry);
+    daemon.config.innerchatPeers = next;
+    saveConfig(daemon.grooveDir, daemon.config);
+    daemon.audit.log('innerchat.peer.set', { alias, url, daemonId: entry.daemonId });
+    // Registry files carry the @peer instructions + alias list — refresh now so
+    // running agents see the new peer without waiting for a spawn or restart.
+    try { daemon.introducer?.writeRegistryFile?.(daemon.projectDir); } catch { /* best effort */ }
+
+    res.json({
+      peers: next,
+      exchanged: true,
+      keyPushed: exchange.pushed,
+      peerDaemonId: exchange.peerDaemonId,
+      note: exchange.pushed
+        ? `Keys exchanged with ${alias}. Add this machine as a peer there too if you want its agents to start conversations.`
+        : `Stored ${alias}'s key, but could not send ours — ${alias} may be running an older version. Update it, then re-add.`,
+    });
+  });
+
+  /**
+   * Verify a configured peer end to end: reachable, identity matches what we
+   * stored, and keys are present on both sides.
+   */
+  app.get('/api/innerchat/peers/:alias/test', async (req, res) => {
+    const peer = daemon.innerchat._peerByAlias(req.params.alias);
+    if (!peer) return res.status(404).json({ error: `No peer named "${req.params.alias}"` });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8000);
+    try {
+      const r = await fetch(`${peer.url}/api/innerchat/identity`, { signal: controller.signal });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      const id = await r.json();
+      const idMatches = id.daemonId === peer.daemonId;
+      const weHaveTheirKey = daemon.federation.peers.has(peer.daemonId);
+      res.json({
+        ok: idMatches && weHaveTheirKey,
+        reachable: true,
+        idMatches,
+        weHaveTheirKey,
+        peerDaemonId: id.daemonId,
+        peerVersion: id.version,
+        agents: Array.isArray(id.agents) ? id.agents : [],
+        error: !idMatches
+          ? `The daemon at ${peer.url} reports id ${id.daemonId}, but this peer is configured as ${peer.daemonId}. Re-add the peer.`
+          : !weHaveTheirKey ? 'Missing this peer\'s public key — re-add the peer to exchange keys.' : null,
+      });
+    } catch (err) {
+      res.json({ ok: false, reachable: false, error: `Could not reach ${peer.url} — ${err.message}` });
+    } finally {
+      clearTimeout(timer);
+    }
+  });
+
+  app.delete('/api/innerchat/peers/:alias', (req, res) => {
+    const peers = Array.isArray(daemon.config.innerchatPeers) ? daemon.config.innerchatPeers : [];
+    const next = peers.filter((p) => p.alias !== req.params.alias);
+    daemon.config.innerchatPeers = next;
+    saveConfig(daemon.grooveDir, daemon.config);
+    daemon.audit.log('innerchat.peer.remove', { alias: req.params.alias });
+    res.json({ peers: next });
+  });
+
   app.get('/api/innerchat/threads', (req, res) => {
     const { agentId } = req.query;
     res.json({ threads: daemon.innerchat.getThreads(agentId || null) });