groove-dev 0.27.196 → 0.27.198

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

@@ -0,0 +1,340 @@
+// GROOVE — Axom Connector
+// FSL-1.1-Apache-2.0 — see LICENSE
+//
+// Consumes the Axom provider protocol (GROOVE ⇄ Axom Integration Contract v0,
+// Axom-Labs/Axom-Private docs/GROOVE_INTEGRATION.md):
+//
+//   GET  /about                          identity + KINDS schema handshake
+//   GET  /sessions                       [{session, started, live}]
+//   WS   /ws/session/{id}?since=<ev-id>  envelope stream, verbatim
+//   POST /session/{id}/interrupt {text}  -> {id, truncated}
+//   POST /session/{id}/stop      {}      -> {ok}
+//
+// The envelope schema is additive-only: unknown kinds are surfaced and passed
+// through, never dropped. GROOVE consumes the protocol; it never imports Axom
+// code. Host-agnostic by contract §5 — an endpoint is a URL, nothing here may
+// assume where the runtime lives.
+
+import { WebSocket } from 'ws';
+
+export const AXOM_DEFAULT_PORT = 8737;
+
+// The frozen KINDS enumeration from Axom's events.py, mirrored for the /about
+// handshake. Drift (either direction) is surfaced on the endpoint status —
+// new kinds still flow through; this list is for visibility, not filtering.
+export const KNOWN_KINDS = Object.freeze([
+  'pipeline_start', 'firing_start', 'step_start', 'firing_end', 'pipeline_done',
+  'thought', 'text', 'action', 'observation', 'resolution',
+  'delegate', 'yield', 'interrupt', 'interrupt_ack',
+  'trace_other', 'tool_start', 'tool_end', 'recall_end',
+  'swarm_start', 'swarm_weights', 'swarm_agent_done', 'swarm_agent_error',
+  'swarm_memory_fused', 'swarm_fused', 'swarm_facts_extracted', 'swarm_done',
+  'leaf_swap', 'stop_requested', 'stop_effected', 'candidate_banked',
+  'narration', 'narration_dropped',
+  'candidate_arrived', 'evidence_scored', 'champion_changed',
+  'confidence_updated', 'verifier_verdict',
+]);
+
+const RING_SIZE = 4096;
+const SESSION_POLL_MS = 15000;
+const BACKOFF_BASE_MS = 1000;
+const BACKOFF_MAX_MS = 30000;
+const FETCH_TIMEOUT_MS = 5000;
+
+export function validateEndpoint(entry) {
+  if (!entry || typeof entry !== 'object') return 'endpoint must be an object';
+  const { name, url } = entry;
+  if (!name || typeof name !== 'string' || !/^[a-zA-Z0-9_-]{1,40}$/.test(name)) {
+    return 'endpoint name must be 1-40 chars (letters, digits, dash, underscore)';
+  }
+  if (!url || typeof url !== 'string') return 'endpoint url is required';
+  let parsed;
+  try { parsed = new URL(url); } catch { return `invalid url: ${url}`; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return 'endpoint url must be http(s)';
+  }
+  if (parsed.username || parsed.password) return 'credentials in the url are not allowed';
+  return null;
+}
+
+function seqOf(eventId) {
+  if (typeof eventId !== 'string' || !eventId.startsWith('ev-')) return null;
+  const n = parseInt(eventId.slice(3), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+export class AxomConnector {
+  constructor(daemon, opts = {}) {
+    this.daemon = daemon;
+    this.ringSize = opts.ringSize || RING_SIZE;
+    this.backoffBaseMs = opts.backoffBaseMs || BACKOFF_BASE_MS;
+    this.sessionPollMs = opts.sessionPollMs || SESSION_POLL_MS;
+    this.endpoints = new Map(); // name -> endpoint state
+    this.destroyed = false;
+  }
+
+  start() {
+    const configured = this.daemon.config?.axom?.endpoints || [];
+    this.configure(configured);
+  }
+
+  // Reconcile live connections against a validated endpoint list. Persistence
+  // is the caller's job (routes save config); this manages connections only.
+  configure(entries) {
+    const keep = new Set();
+    for (const entry of entries) {
+      if (validateEndpoint(entry)) continue; // routes validate; skip defensively
+      keep.add(entry.name);
+      const existing = this.endpoints.get(entry.name);
+      if (existing && existing.url === entry.url.replace(/\/+$/, '')) continue;
+      if (existing) this._teardownEndpoint(existing);
+      this._connectEndpoint(entry);
+    }
+    for (const [name, ep] of this.endpoints) {
+      if (!keep.has(name)) {
+        this._teardownEndpoint(ep);
+        this.endpoints.delete(name);
+      }
+    }
+  }
+
+  _connectEndpoint({ name, url }) {
+    const ep = {
+      name,
+      url: url.replace(/\/+$/, ''),
+      status: 'connecting', // connecting | connected | error
+      error: null,
+      about: null,
+      drift: null, // {novel: [], missing: []} vs KNOWN_KINDS
+      sessions: new Map(), // sessionId -> session state
+      pollTimer: null,
+      backoffMs: this.backoffBaseMs,
+    };
+    this.endpoints.set(name, ep);
+    this._handshake(ep);
+    return ep;
+  }
+
+  async _fetch(ep, path, options = {}) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const res = await fetch(`${ep.url}${path}`, { ...options, signal: controller.signal });
+      if (!res.ok) throw new Error(`HTTP ${res.status} from ${path}`);
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async _handshake(ep) {
+    if (this.destroyed) return;
+    try {
+      const about = await this._fetch(ep, '/about');
+      ep.about = about;
+      // Mechanical schema handshake (contract §6): compare, surface, never drop.
+      const remote = Array.isArray(about.kinds) ? about.kinds : [];
+      ep.drift = {
+        novel: remote.filter((k) => !KNOWN_KINDS.includes(k)),
+        missing: remote.length ? KNOWN_KINDS.filter((k) => !remote.includes(k)) : [],
+      };
+      ep.status = 'connected';
+      ep.error = null;
+      ep.backoffMs = this.backoffBaseMs;
+      this._broadcastStatus();
+      await this._pollSessions(ep);
+      ep.pollTimer = setInterval(() => {
+        this._pollSessions(ep).catch(() => this._endpointLost(ep));
+      }, this.sessionPollMs);
+    } catch (err) {
+      ep.status = 'error';
+      ep.error = err.message;
+      this._broadcastStatus();
+      this._scheduleEndpointRetry(ep);
+    }
+  }
+
+  _endpointLost(ep) {
+    if (this.destroyed || ep.status === 'error') return;
+    ep.status = 'error';
+    ep.error = 'endpoint unreachable';
+    if (ep.pollTimer) { clearInterval(ep.pollTimer); ep.pollTimer = null; }
+    this._broadcastStatus();
+    this._scheduleEndpointRetry(ep);
+  }
+
+  _scheduleEndpointRetry(ep) {
+    if (this.destroyed) return;
+    ep.retryTimer = setTimeout(() => {
+      ep.backoffMs = Math.min(ep.backoffMs * 2, BACKOFF_MAX_MS);
+      this._handshake(ep);
+    }, ep.backoffMs);
+  }
+
+  async _pollSessions(ep) {
+    const list = await this._fetch(ep, '/sessions');
+    if (!Array.isArray(list)) return;
+    for (const info of list) {
+      const id = info.session;
+      if (!id || typeof id !== 'string') continue;
+      let s = ep.sessions.get(id);
+      if (!s) {
+        s = {
+          id,
+          started: info.started ?? null,
+          live: !!info.live,
+          ws: null,
+          lastSeq: 0,
+          ring: [],
+          overflow: 0,
+          unknownKinds: {},
+          reconnectTimer: null,
+        };
+        ep.sessions.set(id, s);
+      }
+      // §12: `live` means a turn is in flight; sessions persist between turns
+      // and events can start at any moment — stay attached regardless.
+      s.live = !!info.live;
+      if (!s.ws) this._watchSession(ep, s);
+    }
+  }
+
+  _watchSession(ep, s) {
+    if (this.destroyed) return;
+    const since = s.lastSeq > 0 ? `?since=ev-${String(s.lastSeq).padStart(6, '0')}` : '';
+    const wsUrl = `${ep.url.replace(/^http/, 'ws')}/ws/session/${encodeURIComponent(s.id)}${since}`;
+    const ws = new WebSocket(wsUrl);
+    s.ws = ws;
+
+    ws.on('message', (data) => {
+      let envelope;
+      try { envelope = JSON.parse(data.toString()); } catch { return; }
+      const seq = seqOf(envelope.id);
+      // Dedup on ring-buffer replay after reconnect — ids are monotonic.
+      if (seq !== null && seq <= s.lastSeq) return;
+      if (seq !== null) s.lastSeq = seq;
+      if (s.ring.length >= this.ringSize) {
+        s.ring.shift();
+        // The ring bounds memory, not delivery: overflow is counted, never
+        // silent, and every event still broadcasts — mirrors the runtime.
+        s.overflow += 1;
+      }
+      s.ring.push(envelope);
+      if (envelope.kind && !KNOWN_KINDS.includes(envelope.kind)) {
+        s.unknownKinds[envelope.kind] = (s.unknownKinds[envelope.kind] || 0) + 1;
+      }
+      // Verbatim passthrough — the envelope is the contract, GROOVE adds
+      // routing metadata around it, never inside it.
+      this.daemon.broadcast({ type: 'axom:event', endpoint: ep.name, session: s.id, envelope });
+    });
+
+    const onGone = () => {
+      if (s.ws !== ws) return;
+      s.ws = null;
+      // Identity check, not name check: after configure() replaces an
+      // endpoint, a late close from the old socket must not re-arm a
+      // reconnect loop on the orphaned object — destroy() could never reach
+      // it (this exact leak wedged a test worker into an infinite loop).
+      if (this.destroyed || this.endpoints.get(ep.name) !== ep) return;
+      s.reconnectTimer = setTimeout(() => this._watchSession(ep, s), ep.backoffMs);
+    };
+    ws.on('close', onGone);
+    ws.on('error', onGone);
+  }
+
+  // §12 message verb: starts a turn (interrupt steers, stop halts). Status is
+  // part of the contract (202 accepted / 409 busy / 413 too_long) so this
+  // returns {status, body} verbatim instead of throwing on non-2xx.
+  async message(endpointName, sessionId, text) {
+    const ep = this._requireEndpoint(endpointName);
+    const res = await fetch(`${ep.url}/session/${encodeURIComponent(sessionId)}/message`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    const body = await res.json().catch(() => ({}));
+    // First message creates the session (caller-chosen id) — poll now so the
+    // WS attaches before the turn's first events age out of nothing.
+    if (res.status === 202) this._pollSessions(ep).catch(() => {});
+    return { status: res.status, body };
+  }
+
+  async interrupt(endpointName, sessionId, text) {
+    const ep = this._requireEndpoint(endpointName);
+    return this._fetch(ep, `/session/${encodeURIComponent(sessionId)}/interrupt`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+    });
+  }
+
+  async stop(endpointName, sessionId) {
+    const ep = this._requireEndpoint(endpointName);
+    return this._fetch(ep, `/session/${encodeURIComponent(sessionId)}/stop`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+  }
+
+  _requireEndpoint(name) {
+    // Single-endpoint convenience: an omitted name resolves iff unambiguous.
+    if (!name && this.endpoints.size === 1) return this.endpoints.values().next().value;
+    const ep = this.endpoints.get(name);
+    if (!ep) throw new Error(`No Axom endpoint named "${name}"`);
+    return ep;
+  }
+
+  events(endpointName, sessionId, sinceSeq = 0) {
+    const ep = this._requireEndpoint(endpointName);
+    const s = ep.sessions.get(sessionId);
+    if (!s) throw new Error(`No session "${sessionId}" on endpoint "${ep.name}"`);
+    const events = sinceSeq > 0 ? s.ring.filter((e) => (seqOf(e.id) || 0) > sinceSeq) : s.ring;
+    return { session: s.id, overflow: s.overflow, events };
+  }
+
+  status() {
+    return {
+      endpoints: [...this.endpoints.values()].map((ep) => ({
+        name: ep.name,
+        url: ep.url,
+        status: ep.status,
+        error: ep.error,
+        about: ep.about,
+        drift: ep.drift,
+        sessions: [...ep.sessions.values()].map((s) => ({
+          session: s.id,
+          started: s.started,
+          live: s.live,
+          watching: !!s.ws,
+          lastEventId: s.lastSeq > 0 ? `ev-${String(s.lastSeq).padStart(6, '0')}` : null,
+          buffered: s.ring.length,
+          overflow: s.overflow,
+          unknownKinds: s.unknownKinds,
+        })),
+      })),
+    };
+  }
+
+  _broadcastStatus() {
+    this.daemon.broadcast({ type: 'axom:status', data: this.status() });
+  }
+
+  _teardownEndpoint(ep) {
+    if (ep.pollTimer) clearInterval(ep.pollTimer);
+    if (ep.retryTimer) clearTimeout(ep.retryTimer);
+    for (const s of ep.sessions.values()) {
+      if (s.reconnectTimer) clearTimeout(s.reconnectTimer);
+      // terminate, not close: close() on a CONNECTING socket defers teardown
+      // until the connect completes — a live handle that can outlast us.
+      if (s.ws) { try { s.ws.terminate(); } catch { /* already gone */ } s.ws = null; }
+    }
+  }
+
+  destroy() {
+    this.destroyed = true;
+    for (const ep of this.endpoints.values()) this._teardownEndpoint(ep);
+    this.endpoints.clear();
+  }
+}

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;
+    }
+  }
+}