@cgh567/agent 2.4.2 → 2.4.3

package/extensions/cortex/wal-replay.ts

@@ -0,0 +1,91 @@
+/**
+ * extensions/cortex/wal-replay.ts
+ *
+ * Auto-replay cortex WAL entries when Memgraph becomes available.
+ * Called by learn.ts on the memgraph:available event (P4-2).
+ *
+ * Reads cortex-write-journal.jsonl, replays each entry via rawWrite,
+ * removes successfully replayed entries atomically (temp file + rename).
+ *
+ * Uses extensions/lib/helios-root (same module as learn.ts) to ensure
+ * the journal path resolves identically in both files.
+ */
+import * as fs from 'fs';
+
+// Re-use the same path derivation as learn.ts.
+// MUST use '../lib/helios-root' (extensions/lib/helios-root), NOT
+// '../../lib/helios-root' (lib/helios-root) — different fallback strategies.
+const { heliosPath } = require('../lib/helios-root');
+const WRITE_JOURNAL_PATH: string = heliosPath('sessions', 'cortex-write-journal.jsonl');
+
+interface WalEntry {
+  cypher: string;
+  params: Record<string, unknown>;
+  timestamp?: number;
+}
+
+function readJournalEntries(): WalEntry[] {
+  if (!fs.existsSync(WRITE_JOURNAL_PATH)) return [];
+  try {
+    const lines = fs.readFileSync(WRITE_JOURNAL_PATH, 'utf8')
+      .split('\n')
+      .filter(Boolean);
+    return lines.map(line => {
+      try { return JSON.parse(line) as WalEntry; } catch { return null; }
+    }).filter((e): e is WalEntry => e !== null && typeof e.cypher === 'string');
+  } catch (e) {
+    process.stderr.write(`[cortex-wal-replay] failed to read journal: ${String(e)}\n`);
+    return [];
+  }
+}
+
+function writeJournalEntries(entries: WalEntry[]): void {
+  const tmp = WRITE_JOURNAL_PATH + '.tmp';
+  try {
+    fs.writeFileSync(tmp, entries.map(e => JSON.stringify(e)).join('\n') + (entries.length ? '\n' : ''), 'utf8');
+    fs.renameSync(tmp, WRITE_JOURNAL_PATH);
+  } catch (e) {
+    process.stderr.write(`[cortex-wal-replay] failed to write journal: ${String(e)}\n`);
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
+export async function replayCortexWal(): Promise<void> {
+  const entries = readJournalEntries();
+  if (entries.length === 0) return;
+
+  let rawWrite: ((cypher: string, params: Record<string, unknown>) => Promise<unknown>) | null = null;
+  try {
+    const mg = require('../../lib/safe-memgraph');
+    rawWrite = mg.rawWrite ?? mg.safeWrite ?? null;
+  } catch (e) {
+    process.stderr.write(`[cortex-wal-replay] failed to load safe-memgraph: ${String(e)}\n`);
+    return;
+  }
+
+  if (!rawWrite) {
+    process.stderr.write('[cortex-wal-replay] rawWrite not available — skipping replay\n');
+    return;
+  }
+
+  const remaining: WalEntry[] = [];
+  let replayed = 0;
+  let failed = 0;
+
+  for (const entry of entries) {
+    try {
+      await rawWrite(entry.cypher, entry.params ?? {});
+      replayed++;
+    } catch (e) {
+      failed++;
+      remaining.push(entry);
+      process.stderr.write(`[cortex-wal-replay] entry replay failed (kept in journal): ${String(e)}\n`);
+    }
+  }
+
+  writeJournalEntries(remaining);
+
+  process.stderr.write(
+    `[cortex-wal-replay] Replayed ${replayed} / ${entries.length} entries. ${failed} failed (left in journal).\n`
+  );
+}

package/extensions/hema-dispatch-v3/index.ts

@@ -682,15 +682,20 @@ export default function hemaDispatchV3(pi: any): void {
     } catch (_) { process.stderr.write(`[hema:catch] fail-open: graceful degradation: ${(_ as Error)?.message || _}\n`); } // HeliosRuntime may not be initialized — fail-open
 
     // ═══ TASK-13: Budget Pre-Admission Gate ═══
-    // Reads ~/helios-agent/brainv2/budget-status.json (written by GraphSyncService).
+    // MT-02: Path resolves from HELIOS_ROOT env var (required). If unset, daemon logs a startup error.
+    // budget-status.json is written by GraphSyncService at $HELIOS_ROOT/brainv2/budget-status.json.
     // Fail-open: if file missing or unreadable, proceed normally.
     // blocked=true  → hard block, return early with ⛔ message
     // warningActive → inject budget warning into agent context (soft signal)
     let _budgetStatus: { blocked?: boolean; warningActive?: boolean; policies?: any[] } = {};
     let _budgetWarning: string | null = null;
     try {
-      const _budgetStatusPath = join(homedir(), 'helios-agent/brainv2/budget-status.json');
-      if (fs.existsSync(_budgetStatusPath)) {
+      const _heliosRoot = process.env['HELIOS_ROOT'];
+      if (!_heliosRoot) {
+        process.stderr.write('[hema] HELIOS_ROOT not set — budget-status.json cannot be read. Set HELIOS_ROOT to the helios-agent repo root.\n');
+      }
+      const _budgetStatusPath = _heliosRoot ? join(_heliosRoot, 'brainv2/budget-status.json') : null;
+      if (_budgetStatusPath && fs.existsSync(_budgetStatusPath)) {
         _budgetStatus = JSON.parse(fs.readFileSync(_budgetStatusPath, 'utf8'));
       }
     } catch (_budgetErr) {
@@ -2676,9 +2681,10 @@ export default function hemaDispatchV3(pi: any): void {
       } catch (_) { process.stderr.write(`[hema:catch] fail-open: ${(_ as Error)?.message || _}\n`); }
 
       // Load hot memory — ensure file exists
-      const hotMemoryPath = join(homedir(), 'helios-agent', 'sessions', 'hot-memory.json');
+      const _heliosRootForMem = process.env['HELIOS_ROOT'] ?? join(homedir(), 'helios-agent');
+      const hotMemoryPath = join(_heliosRootForMem, 'sessions', 'hot-memory.json');
       if (!fs.existsSync(hotMemoryPath)) {
-        const sessDir = join(homedir(), 'helios-agent', 'sessions');
+        const sessDir = join(_heliosRootForMem, 'sessions');
         if (!fs.existsSync(sessDir)) fs.mkdirSync(sessDir, { recursive: true });
         fs.writeFileSync(hotMemoryPath, JSON.stringify({ sessions: [] }, null, 2), 'utf8');
       }
@@ -2706,7 +2712,7 @@ export default function hemaDispatchV3(pi: any): void {
         const pendingIds = [..._pendingDispatchIds.keys()];
         try {
           const _walSessionId = di('sessionId') || process.pid;
-        const walPath = join(homedir(), `helios-agent/sessions/.pending-dispatches-${_walSessionId}.json`);
+        const walPath = join(process.env['HELIOS_ROOT'] ?? join(homedir(), 'helios-agent'), `sessions/.pending-dispatches-${_walSessionId}.json`);
           fs.writeFileSync(walPath, JSON.stringify({ ids: pendingIds, timestamp: Date.now(), sessionId: di('sessionId') || 'unknown' }));
           process.stderr.write(`[hema] session_shutdown: wrote ${pendingIds.length} pending dispatch ID(s) to WAL\n`);
         } catch (e: any) {
@@ -3144,7 +3150,7 @@ export default function hemaDispatchV3(pi: any): void {
         return { systemPrompt: appendDynamic(event.systemPrompt, '\n' + evalContext) };
       }
 
-      const hotMemoryPath = join(homedir(), 'helios-agent', 'sessions', 'hot-memory.json');
+      const hotMemoryPath = join(process.env['HELIOS_ROOT'] ?? join(homedir(), 'helios-agent'), 'sessions', 'hot-memory.json');
 
       let hotMemory: any = null;
       if (fs.existsSync(hotMemoryPath)) {

package/extensions/warm-tick/warm-tick-maintenance.ts

@@ -713,6 +713,14 @@ export async function runScheduledMaintenance(): Promise<void> {
     }
   }
 
+  // SEC-5: Daily cleanup of expired DraftAction PII nodes (30-day TTL)
+  try {
+    const { rawWrite: _rawWrite } = require('../../lib/safe-memgraph.js');
+    await _rawWrite('MATCH (da:DraftAction) WHERE da.expiresAt < datetime() DETACH DELETE da', {});
+  } catch (err: any) {
+    console.warn('[warm-tick] DraftAction TTL cleanup failed:', err?.message || String(err));
+  }
+
   // Daily: incremental label backfill (ensures critical graph labels are never empty)
   try {
     const { runIncrementalBackfill } = await import('./warm-tick-backfill.js');

package/lib/__tests__/hbo-core-store.test.js

@@ -0,0 +1,238 @@
+'use strict';
+/**
+ * lib/__tests__/hbo-core-store.test.js
+ *
+ * Unit tests for hbo-core-store.ts (SQLite fallback store).
+ * Uses node:sqlite (Node.js v22+ built-in) — no native compilation required.
+ * Runs natively on Windows and macOS.
+ *
+ * Run: node --experimental-sqlite lib/__tests__/hbo-core-store.test.js
+ * Or:  pnpm run test:hbo-store
+ *
+ * Invariants verified:
+ *   - Memgraph is the primary data model; SQLite is the fallback
+ *   - No hardcoded company IDs (process.pid suffix)
+ *   - INSERT OR REPLACE is idempotent
+ *   - company_id isolation prevents cross-tenant data bleed
+ *   - company_id=undefined throws (never silently stores null)
+ *   - updateTask/updateApproval upsert when record is missing
+ */
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+// Unique per test run — no cross-run state pollution
+const TEST_ROOT = path.join(os.tmpdir(), 'hbo-core-store-test-' + process.pid);
+process.env.HELIOS_ROOT = TEST_ROOT;
+fs.mkdirSync(path.join(TEST_ROOT, 'data'), { recursive: true });
+
+// Must require AFTER setting HELIOS_ROOT
+const store = require('../hbo-core-store');
+
+// Unique company IDs — no hardcoded tenant names
+const CID_A = 'test:hbo-store:co-a:' + process.pid;
+const CID_B = 'test:hbo-store:co-b:' + process.pid;
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    const err = new Error('FAIL: ' + message);
+    failures.push(err);
+    failed++;
+    console.error('  ✗', message);
+  } else {
+    passed++;
+    console.log('  ✓', message);
+  }
+}
+
+function assertEqual(a, b, message) {
+  assert(a === b, `${message} (expected ${JSON.stringify(b)}, got ${JSON.stringify(a)})`);
+}
+
+function assertNull(a, message) {
+  assert(a === null, `${message} (expected null, got ${JSON.stringify(a)})`);
+}
+
+function assertThrows(fn, messagePart, label) {
+  try {
+    fn();
+    assert(false, `${label}: expected throw but did not throw`);
+  } catch (e) {
+    if (messagePart && !e.message.includes(messagePart)) {
+      assert(false, `${label}: threw but message "${e.message}" did not contain "${messagePart}"`);
+    } else {
+      assert(true, label);
+    }
+  }
+}
+
+// ── Task tests ────────────────────────────────────────────────────────────────
+
+console.log('\n[Tasks]');
+
+store.createTask({ id: 't-1', companyId: CID_A, title: 'Test Task', status: 'todo', priority: 1 });
+const t1 = store.getTask('t-1', CID_A);
+assert(t1 !== null, 'getTask returns record after createTask');
+assertEqual(t1.title, 'Test Task', 'getTask.title correct');
+assertEqual(t1.status, 'todo', 'getTask.status correct');
+
+assertNull(store.getTask('t-1', CID_B), 'getTask returns null for wrong company (isolation)');
+
+store.updateTask('t-1', CID_A, { status: 'in_progress' });
+assertEqual(store.getTask('t-1', CID_A).status, 'in_progress', 'updateTask changes status');
+
+// updateTask upsert: record not yet in SQLite → creates it
+store.updateTask('t-upsert', CID_A, { title: 'Upserted', status: 'todo' });
+const tu = store.getTask('t-upsert', CID_A);
+assert(tu !== null, 'updateTask upserts when record is missing');
+assertEqual(tu.status, 'todo', 'upserted task has correct status');
+
+store.createTask({ id: 't-2', companyId: CID_A, title: 'Task 2', status: 'done' });
+const todos = store.getTasksByCompanyStatus(CID_A, 'todo');
+assert(todos.some(t => t.id === 't-upsert'), 'getTasksByCompanyStatus(todo) includes todo tasks');
+assert(!todos.some(t => t.id === 't-2'), 'getTasksByCompanyStatus(todo) excludes done tasks');
+
+store.updateTask('t-1', CID_A, { status: 'in_progress' });
+const active = store.getTasksByCompanyStatus(CID_A, ['todo', 'in_progress']);
+assert(active.some(t => t.id === 't-1'), 'multi-status filter includes in_progress');
+assert(active.some(t => t.id === 't-upsert'), 'multi-status filter includes todo');
+assert(!active.some(t => t.id === 't-2'), 'multi-status filter excludes done');
+
+assertThrows(
+  () => store.createTask({ id: 't-nocompany', title: 'X' }),
+  'company_id is required',
+  'createTask throws when companyId is missing'
+);
+
+// Idempotency
+store.createTask({ id: 't-1', companyId: CID_A, title: 'Updated Title', status: 'in_progress' });
+const allTasks = store.getTasksByCompanyStatus(CID_A, ['todo', 'in_progress', 'done']);
+assertEqual(allTasks.filter(t => t.id === 't-1').length, 1, 'createTask is idempotent (no duplicate rows)');
+assertEqual(store.getTask('t-1', CID_A).title, 'Updated Title', 'second createTask updates the record');
+
+store.deleteTask('t-2', CID_A);
+assertNull(store.getTask('t-2', CID_A), 'deleteTask removes the record');
+
+// ── Approval tests ────────────────────────────────────────────────────────────
+
+console.log('\n[Approvals]');
+
+store.createApproval({ id: 'ap-1', companyId: CID_A, type: 'budget_exceeded', status: 'pending', requestedBy: 'agent:ceo' });
+const ap1 = store.getApproval('ap-1', CID_A);
+assert(ap1 !== null, 'getApproval returns record after createApproval');
+assertEqual(ap1.type, 'budget_exceeded', 'approval type correct');
+assertNull(store.getApproval('ap-1', CID_B), 'approval isolated from other company');
+
+store.updateApproval('ap-1', CID_A, { status: 'approved', followUpTaskCreated: false });
+assertEqual(store.getApproval('ap-1', CID_A).status, 'approved', 'updateApproval changes status');
+
+store.updateApproval('ap-upsert', CID_A, { status: 'pending', type: 'belief_confirmation' });
+assert(store.getApproval('ap-upsert', CID_A) !== null, 'updateApproval upserts when missing');
+
+const pendingApprovals = store.getApprovalsByCompanyStatus(CID_A, 'pending');
+assert(pendingApprovals.some(a => a.id === 'ap-upsert'), 'getApprovalsByCompanyStatus returns pending');
+assert(!pendingApprovals.some(a => a.id === 'ap-1'), 'getApprovalsByCompanyStatus excludes approved');
+
+assertThrows(
+  () => store.createApproval({ id: 'ap-nocompany', type: 'x' }),
+  'company_id is required',
+  'createApproval throws when companyId is missing'
+);
+
+// ── BudgetPolicy tests ────────────────────────────────────────────────────────
+
+console.log('\n[Goals]');
+
+store.createGoal({
+  id: 'goal-1',
+  companyId: CID_A,
+  title: 'Increase retention',
+  description: 'Company-level goal',
+  level: 'company',
+  status: 'active',
+});
+const goal1 = store.getGoal('goal-1', CID_A);
+assert(goal1 !== null, 'getGoal returns record after createGoal');
+assertEqual(goal1.title, 'Increase retention', 'getGoal.title correct');
+assertEqual(goal1.level, 'company', 'getGoal.level correct');
+assertNull(store.getGoal('goal-1', CID_B), 'getGoal returns null for wrong company (isolation)');
+
+store.updateGoal('goal-1', CID_A, { title: 'Increase net retention', status: 'paused' });
+const updatedGoal = store.getGoal('goal-1', CID_A);
+assertEqual(updatedGoal.title, 'Increase net retention', 'updateGoal changes title');
+assertEqual(updatedGoal.status, 'paused', 'updateGoal changes status');
+
+store.createGoal({
+  id: 'goal-child',
+  companyId: CID_A,
+  title: 'Improve onboarding',
+  level: 'department',
+  status: 'active',
+  parentId: 'goal-1',
+});
+const companyGoals = store.getGoalsByCompany(CID_A);
+assert(companyGoals.some(g => g.id === 'goal-1'), 'getGoalsByCompany includes parent goal');
+assert(companyGoals.some(g => g.id === 'goal-child' && g.parentId === 'goal-1'), 'getGoalsByCompany includes child goal with parentId');
+assert(!store.getGoalsByCompany(CID_B).some(g => g.id === 'goal-1'), 'goals isolated from other company');
+
+assertThrows(
+  () => store.createGoal({ id: 'goal-nocompany', title: 'X' }),
+  'company_id is required',
+  'createGoal throws when companyId is missing'
+);
+
+store.deleteGoal('goal-child', CID_A);
+assertNull(store.getGoal('goal-child', CID_A), 'deleteGoal removes the record');
+
+// ── BudgetPolicy tests ───────────────────────────────────────────────────────
+
+console.log('\n[BudgetPolicy]');
+
+store.upsertBudgetPolicy({ id: 'bp-1', companyId: CID_A, agentId: 'agent:sales', limitCents: 50000, warnPercent: 80, hardStopEnabled: true });
+assert(store.getBudgetPolicy('bp-1', CID_A) !== null, 'getBudgetPolicy returns record after upsert');
+assert(store.getBudgetPoliciesByCompany(CID_A).some(p => p.id === 'bp-1'), 'getBudgetPoliciesByCompany returns the policy');
+assert(!store.getBudgetPoliciesByCompany(CID_B).some(p => p.id === 'bp-1'), 'policy isolated from other company');
+
+// ── OKR tests ─────────────────────────────────────────────────────────────────
+
+console.log('\n[OKRs]');
+
+store.upsertOKR({ id: 'okr-1', companyId: CID_A, type: 'quarterly_okr', status: 'active', title: 'Q3 OKR' });
+assert(store.getOKRsByCompanyType(CID_A, 'quarterly_okr', 'active').some(o => o.id === 'okr-1'), 'getOKRsByCompanyType returns active quarterly OKR');
+assert(!store.getOKRsByCompanyType(CID_A, 'quarterly', 'active').some(o => o.id === 'okr-1'), "type='quarterly' does NOT match 'quarterly_okr'");
+assert(!store.getOKRsByCompanyType(CID_B, 'quarterly_okr', 'active').some(o => o.id === 'okr-1'), 'OKR isolated from other company');
+
+// ── Lead tests ────────────────────────────────────────────────────────────────
+
+console.log('\n[Leads]');
+
+store.upsertLead({ id: 'lead-1', companyId: CID_A, status: 'new', name: 'Alice', email: 'alice@example.com' });
+assert(store.getLeadsByCompanyStatus(CID_A, ['new', 'stale']).some(l => l.id === 'lead-1'), 'getLeadsByCompanyStatus returns new lead');
+assert(!store.getLeadsByCompanyStatus(CID_B, ['new']).some(l => l.id === 'lead-1'), 'lead isolated from other company');
+
+// ── CostEvent tests ───────────────────────────────────────────────────────────
+
+console.log('\n[CostEvents]');
+
+const now = Date.now();
+store.createCostEvent({ id: 'ce-1', companyId: CID_A, feature: 'llm', model: 'claude-sonnet', amountUsd: 0.05, createdAt: now });
+assert(store.getCostEventsByCompanyRange(CID_A, now - 1000, now + 1000).some(e => e.id === 'ce-1'), 'getCostEventsByCompanyRange returns event in range');
+assert(!store.getCostEventsByCompanyRange(CID_B, now - 1000, now + 1000).some(e => e.id === 'ce-1'), 'cost event isolated from other company');
+
+// ── Summary ───────────────────────────────────────────────────────────────────
+
+console.log('\n─────────────────────────────────────────');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+if (failed > 0) {
+  console.error('\nFailures:');
+  failures.forEach(f => console.error(' -', f.message));
+  process.exit(1);
+} else {
+  console.log('All tests passed.');
+  process.exit(0);
+}

package/lib/event-bus.mts

@@ -46,7 +46,7 @@ interface EventMap {
     senderHandle: string;
     subject: string;
     snippet: string;
-    body: string;
+    // body intentionally excluded — PII (SEC-6)
     threadId: string;
     receivedAt: string;
     suggestedAction: string;

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