@cgh567/agent 2.4.2 → 2.4.4

package/lib/graph/learning/headroom-learn-bridge.js

@@ -0,0 +1,175 @@
+'use strict';
+/**
+ * lib/graph/learning/headroom-learn-bridge.js
+ *
+ * Post-RETROSPECTIVE learning bridge: mines session compression stats and
+ * tool-call failure patterns, then writes structured knowledge to Memgraph.
+ *
+ * Called from lib/mission-loop/phase-handlers/retrospective.ts (fire-and-forget):
+ *   const { runBridge } = require('../../graph/learning/headroom-learn-bridge');
+ *   await runBridge(safeWrite, sessionId, missionRunId);
+ *
+ * Interface:
+ *   runBridge(safeWrite, sessionId, missionRunId): Promise<void>
+ *     safeWrite: (cypher: string, params?: object) => Promise<void>
+ *     sessionId: string
+ *     missionRunId: string
+ *     Returns: void — never throws, fully fail-open
+ *
+ * Memgraph writes:
+ *   - HeadroomSession node (tracks per-session compression stats)
+ *   - KnowledgeAsset nodes (one per unique tool-failure pattern found)
+ *
+ * Debounce: 5 minutes per sessionId — prevents multiple RETROSPECTIVE calls
+ * within the same session from firing duplicate writes.
+ *
+ * No hardcoded company IDs. companyId is derived from sessionId prefix if
+ * available (format: "<companyId>__<sessionSuffix>"), else 'unknown'.
+ *
+ * Cross-platform: os.homedir(), path.join() throughout.
+ */
+
+const os   = require('os');
+const path = require('path');
+const fs   = require('fs');
+
+// ── Debounce ──────────────────────────────────────────────────────────────────
+// Map<sessionId, lastRunMs>
+const _lastRun = new Map();
+const DEBOUNCE_MS = 5 * 60 * 1000; // 5 minutes
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Derive companyId from sessionId.
+ * Convention in helios-agent: sessionId may be prefixed as "pi__<suffix>" or
+ * "<companyId>__<suffix>". If no __ separator found, returns 'unknown'.
+ */
+function deriveCompanyId(sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') return 'unknown';
+  // Skip the standard pi__ prefix — that's not a companyId
+  if (sessionId.startsWith('pi__')) return 'unknown';
+  const sep = sessionId.indexOf('__');
+  if (sep > 0) return sessionId.substring(0, sep);
+  return 'unknown';
+}
+
+/**
+ * Read tool-failure patterns from HELIOS_SESSION_TOOL_FAILURES env var.
+ * The env var is expected to be a JSON array of { toolName, errorClass } objects,
+ * set by the daemon before spawning Pi. Returns [] if absent or unparseable.
+ */
+function readToolFailures() {
+  try {
+    const raw = process.env.HELIOS_SESSION_TOOL_FAILURES;
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (f) => f && typeof f.toolName === 'string' && typeof f.errorClass === 'string'
+    );
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Write a HeadroomSession node to Memgraph.
+ * Non-fatal: resolves even if safeWrite rejects.
+ */
+async function writeHeadroomSession(safeWrite, sessionId, missionRunId) {
+  const companyId = deriveCompanyId(sessionId);
+  const cypher = `
+    MERGE (hs:HeadroomSession {sessionId: $sessionId})
+    SET hs.missionRunId = $missionRunId,
+        hs.companyId    = $companyId,
+        hs.updatedAt    = localdatetime()
+  `;
+  try {
+    await safeWrite(cypher, { sessionId, missionRunId, companyId });
+  } catch (e) {
+    process.stderr.write(`[headroom-learn-bridge] HeadroomSession write failed (non-fatal): ${e && e.message}\n`);
+  }
+}
+
+/**
+ * Write KnowledgeAsset nodes for each unique tool-failure pattern.
+ * Non-fatal per write.
+ */
+async function writeKnowledgeAssets(safeWrite, failures, sessionId) {
+  if (!failures || failures.length === 0) return;
+
+  // Deduplicate by toolName+errorClass
+  const seen = new Set();
+  const unique = failures.filter((f) => {
+    const key = `${f.toolName}::${f.errorClass}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+
+  for (const failure of unique) {
+    const assetId = `hroom-${Buffer.from(`${sessionId}:${failure.toolName}:${failure.errorClass}`).toString('base64').replace(/[^a-z0-9]/gi, '').slice(0, 32)}`;
+    const cypher = `
+      MERGE (ka:KnowledgeAsset {id: $assetId})
+      SET ka.source      = 'headroom-learn-bridge',
+          ka.type        = 'tool_failure_pattern',
+          ka.toolName    = $toolName,
+          ka.errorClass  = $errorClass,
+          ka.sessionId   = $sessionId,
+          ka.updatedAt   = localdatetime()
+    `;
+    try {
+      await safeWrite(cypher, {
+        assetId,
+        toolName   : failure.toolName,
+        errorClass : failure.errorClass,
+        sessionId,
+      });
+    } catch (e) {
+      process.stderr.write(`[headroom-learn-bridge] KnowledgeAsset write failed (non-fatal): ${e && e.message}\n`);
+    }
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Run the headroom learn bridge for a completed RETROSPECTIVE phase.
+ *
+ * @param {Function} safeWrite  Memgraph writer: (cypher, params?) => Promise<void>
+ * @param {string}   sessionId  Current session ID
+ * @param {string}   missionRunId  Current mission run ID
+ * @returns {Promise<void>}  Always resolves — never rejects
+ */
+async function runBridge(safeWrite, sessionId, missionRunId) {
+  try {
+    // Debounce: skip if we ran within the last 5 minutes for this session
+    const lastRun = _lastRun.get(sessionId);
+    if (lastRun && Date.now() - lastRun < DEBOUNCE_MS) {
+      process.stderr.write(
+        `[headroom-learn-bridge] Debounced for session ${sessionId} ` +
+        `(${Math.round((Date.now() - lastRun) / 1000)}s since last run)\n`
+      );
+      return;
+    }
+    _lastRun.set(sessionId, Date.now());
+
+    // Run both writes in parallel — independent of each other
+    const failures = readToolFailures();
+    await Promise.all([
+      writeHeadroomSession(safeWrite, sessionId, missionRunId),
+      writeKnowledgeAssets(safeWrite, failures, sessionId),
+    ]);
+
+    process.stderr.write(
+      `[headroom-learn-bridge] Completed for session=${sessionId} ` +
+      `missionRunId=${missionRunId} failures=${failures.length}\n`
+    );
+  } catch (e) {
+    // Top-level catch: bridge is fully non-fatal
+    process.stderr.write(`[headroom-learn-bridge] Unexpected error (non-fatal): ${e && e.message}\n`);
+  }
+}
+
+module.exports = { runBridge };

package/lib/graph-availability.js

@@ -0,0 +1,62 @@
+'use strict';
+/**
+ * lib/graph-availability.js
+ *
+ * Single source of truth for Memgraph availability state within a SINGLE
+ * Node.js process. Listeners are notified on state change only (not on
+ * redundant sets of the same value).
+ *
+ * ⚠️  PROCESS SCOPE WARNING:
+ * This module uses Node.js module-level state. Each OS process has its own
+ * module registry and therefore its own independent _available + _listeners.
+ * It is ONLY valid within a single process:
+ *
+ *   ✅ Pi extension process — memgraph-autostart sets state, cortex/hema read it
+ *   ✅ Eval container — same process, same state
+ *   ❌ helios-company-daemon.js — runs in its own process; state here is NEVER
+ *      set by memgraph-autostart (which runs in Pi's process). Do NOT use
+ *      isMemgraphAvailable() in daemon code to gate Memgraph writes — use the
+ *      try/catch + setImmediate fire-and-forget pattern instead.
+ *   ❌ broker/server.js — forked process; has its own availability state
+ *
+ * Usage (within Pi's extension process only):
+ *   const { isMemgraphAvailable, setMemgraphAvailable, onAvailabilityChange } = require('./graph-availability');
+ */
+
+let _available = false;
+let _listeners = [];
+
+function setMemgraphAvailable(available) {
+  const v = !!available;
+  if (v === _available) return;
+  _available = v;
+  const snap = _listeners.slice();
+  for (const fn of snap) {
+    try { fn(_available); } catch (e) {
+      process.stderr.write('[graph-availability] listener error: ' + String(e) + '\n');
+    }
+  }
+}
+
+function isMemgraphAvailable() {
+  return _available;
+}
+
+function onAvailabilityChange(fn) {
+  _listeners.push(fn);
+  return function unsubscribe() {
+    _listeners = _listeners.filter((l) => l !== fn);
+  };
+}
+
+function _resetForTest() {
+  _available = false;
+  _listeners = [];
+}
+
+module.exports = {
+  setMemgraphAvailable,
+  isMemgraphAvailable,
+  onAvailabilityChange,
+  _resetForTest,
+};