@cgh567/agent 2.4.1 → 2.4.3

package/daemon/lib/mental-model-cache.js

@@ -1,96 +0,0 @@
-'use strict';
-/**
- * mental-model-cache.js — CachedPersonModel node CRUD
- * Pre-assembled mental models for fast agent brief injection.
- * Cache is invalidated by enrichmentNeeded flag on Person node.
- */
-
-const SCHEMA_VERSION = 1;
-
-/**
- * writeCachedModel — upsert a CachedPersonModel node for a person in a company.
- *
- * @param {Function} mgQuery       — Memgraph query function (async)
- * @param {string}   personId      — Person node id
- * @param {string}   companyId     — Company node id
- * @param {object}   assembledModel — Output from assembleMentalModel()
- */
-async function writeCachedModel(mgQuery, personId, companyId, assembledModel) {
-  const modelId = `model:${companyId}:${personId}`;
-  const contextBrief = assembledModel.contextBrief || '';
-  const faveeJson = JSON.stringify(assembledModel.favee || {});
-  const topicsJson = JSON.stringify((assembledModel.activeTopics || []).slice(0, 10));
-  const questionsJson = JSON.stringify((assembledModel.openQuestions || []).slice(0, 5));
-  const completeness = contextBrief ? 'full' : (faveeJson !== '{}' ? 'partial' : 'none');
-
-  await mgQuery(
-    `MERGE (m:CachedPersonModel {id: $id})
-     ON CREATE SET
-       m.personId = $personId, m.companyId = $companyId,
-       m.contextBrief = $brief, m.faveeJson = $favee,
-       m.topicsJson = $topics, m.questionsJson = $questions,
-       m.assembledAt = localdatetime(), m.completeness = $completeness,
-       m.schemaVersion = $sv
-     ON MATCH SET
-       m.contextBrief = $brief, m.faveeJson = $favee,
-       m.topicsJson = $topics, m.questionsJson = $questions,
-       m.assembledAt = localdatetime(), m.completeness = $completeness,
-       m.dirtyAt = null
-     WITH m
-     MATCH (p:Person {id: $personId})
-     MERGE (p)-[:HAS_CACHED_MODEL]->(m)`,
-    { id: modelId, personId, companyId, brief: contextBrief,
-      favee: faveeJson, topics: topicsJson, questions: questionsJson,
-      completeness, sv: SCHEMA_VERSION }
-  );
-}
-
-/**
- * invalidateCache — mark a CachedPersonModel dirty so next read triggers a refresh.
- * Non-fatal: silently ignores errors if the model node doesn't exist yet.
- *
- * @param {Function} mgQuery
- * @param {string}   personId
- * @param {string}   companyId
- */
-async function invalidateCache(mgQuery, personId, companyId) {
-  const modelId = `model:${companyId}:${personId}`;
-  await mgQuery(
-    `MATCH (m:CachedPersonModel {id: $id}) SET m.dirtyAt = localdatetime()`,
-    { id: modelId }
-  ).catch(() => {});
-}
-
-/**
- * getCachedModel — return a cached model if it exists, is not dirty, and is within maxAge.
- * Returns null if the cache is cold, dirty, or expired.
- *
- * @param {Function} mgQuery
- * @param {string}   personId
- * @param {string}   companyId
- * @param {number}   maxAgeMinutes — default 60 minutes
- * @returns {object|null}
- */
-async function getCachedModel(mgQuery, personId, companyId, maxAgeMinutes = 60) {
-  const modelId = `model:${companyId}:${personId}`;
-  const rows = await mgQuery(
-    `MATCH (m:CachedPersonModel {id: $id})
-     WHERE m.dirtyAt IS NULL
-       AND m.assembledAt > localdatetime() - duration({minutes: $maxAge})
-     RETURN m.contextBrief, m.faveeJson, m.topicsJson, m.questionsJson,
-            m.assembledAt, m.completeness`,
-    { id: modelId, maxAge: maxAgeMinutes }
-  );
-  if (!rows?.rows?.length) return null;
-  const r = rows.rows[0];
-  return {
-    contextBrief:  r[0],
-    faveeJson:     r[1],
-    topicsJson:    r[2],
-    questionsJson: r[3],
-    assembledAt:   r[4],
-    completeness:  r[5],
-  };
-}
-
-module.exports = { writeCachedModel, invalidateCache, getCachedModel, SCHEMA_VERSION };

package/daemon/lib/project-factory.js

@@ -1,47 +0,0 @@
-'use strict';
-/**
- * project-factory.js — Creates HeliosProject + ProjectDocument nodes when
- * a GoalPillar is initialized via tickGoalDecompose().
- *
- * Called from daemon/lib/hbo-bridge.js tickGoalDecompose() after
- * mandala.initializeMandala() succeeds for each GoalPillar.
- *
- * ID conventions:
- *   HeliosProject:    proj:<companyId>:<pillarSlug>
- *   ProjectDocument:  pdoc:<projectId>:main
- */
-
-async function ensureProject(mgQuery, companyId, goalId, pillarId, pillarTitle) {
-  const slug   = pillarId.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 40);
-  const projId = `proj:${companyId}:${slug}`;
-  const docId  = `pdoc:${projId}:main`;
-
-  await mgQuery(
-    `MERGE (p:HeliosProject {id: $projId})
-     ON CREATE SET
-       p.companyId = $cid,
-       p.goalId    = $goalId,
-       p.pillarId  = $pillarId,
-       p.name      = $name,
-       p.status    = 'planning',
-       p.phase     = 'planning',
-       p.createdAt = datetime()`,
-    { projId, cid: companyId, goalId, pillarId, name: pillarTitle }
-  ).catch(() => {});
-
-  await mgQuery(
-    `MERGE (d:ProjectDocument {id: $docId})
-     ON CREATE SET
-       d.projectId       = $projId,
-       d.purpose         = '',
-       d.approach        = '',
-       d.successCriteria = '[]',
-       d.intentAnchor    = '',
-       d.exclusions      = '[]',
-       d.version         = toInteger(1),
-       d.updatedAt       = datetime()`,
-    { docId, projId }
-  ).catch(() => {});
-}
-
-module.exports = { ensureProject };

package/daemon/lib/session-log-reader.js

@@ -1,93 +0,0 @@
-'use strict';
-
-const path = require('path');
-const os = require('os');
-
-/**
- * SessionLogReader — reads OpenCode session logs from opencode.db
- * to reconstruct agent decision traces for HED audit.
- * Uses better-sqlite3 (already a dependency via daemon) for read-only access.
- */
-
-// OpenCode stores sessions at platform-specific paths:
-//   Linux/WSL: ~/.local/share/opencode/opencode.db
-//   macOS:     ~/Library/Application Support/opencode/opencode.db
-//   Windows:   %APPDATA%\opencode\opencode.db
-function getOpenCodeDbPath() {
-  if (process.platform === 'linux') {
-    return path.join(os.homedir(), '.local', 'share', 'opencode', 'opencode.db');
-  }
-  if (process.platform === 'darwin') {
-    return path.join(os.homedir(), 'Library', 'Application Support', 'opencode', 'opencode.db');
-  }
-  return path.join(os.homedir(), 'AppData', 'Local', 'opencode', 'opencode.db');
-}
-
-async function readSessionLog(sessionKey) {
-  if (!sessionKey) return [];
-  let Database;
-  try {
-    Database = require('better-sqlite3');
-  } catch {
-    console.warn('[session-log-reader] better-sqlite3 not available — cannot read session log');
-    return [];
-  }
-  const dbPath = getOpenCodeDbPath();
-  let db;
-  try {
-    db = new Database(dbPath, { readonly: true, fileMustExist: true });
-  } catch (err) {
-    console.warn('[session-log-reader] cannot open opencode.db:', err.message);
-    return [];
-  }
-  try {
-    const messages = db.prepare(
-      `SELECT role, content, created_at FROM messages WHERE session_id = ? ORDER BY created_at ASC`
-    ).all(sessionKey);
-    return messages.map((m, i) => ({
-      index: i,
-      role: m.role,
-      content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content),
-      createdAt: m.created_at
-    }));
-  } catch (err) {
-    console.warn('[session-log-reader] query failed:', err.message);
-    return [];
-  } finally {
-    db.close();
-  }
-}
-
-// Classify messages into XEPV sequence: eXplore, Execute, Plan, Verify
-function classifyXEPV(messages) {
-  return messages.map(m => {
-    const content = m.content || '';
-    // Tool calls in content indicate action type
-    if (content.includes('"edit"') || content.includes('"write"')) return { ...m, xepv: 'X_Execute' };
-    if (content.includes('"read"') || content.includes('"grep"') || content.includes('"search_codebase"') || content.includes('"glob"')) return { ...m, xepv: 'X_Explore' };
-    if (content.includes('"bash"') && (content.includes('test') || content.includes('vitest') || content.includes('grep -n'))) return { ...m, xepv: 'X_Verify' };
-    if (m.role === 'assistant' && (content.includes('plan') || content.includes('approach') || content.includes('strategy') || content.includes('first'))) return { ...m, xepv: 'X_Plan' };
-    return { ...m, xepv: 'X_Unknown' };
-  });
-}
-
-// Find the branch point where the agent deviated from the declared target
-function findBranchPoint(xepvMessages, opTarget) {
-  const exploreBeforeExecute = xepvMessages.filter(m => m.xepv === 'X_Explore');
-  for (const msg of exploreBeforeExecute) {
-    // If the agent explored files NOT in the declared target, that's the branch point
-    if (opTarget && !msg.content.includes(opTarget)) {
-      return { message: msg, reason: `Agent explored ${msg.content.slice(0, 200)} instead of declared target ${opTarget}` };
-    }
-  }
-  return null;
-}
-
-// Compute P-ratio: plan steps vs execution steps
-function computePRatio(xepvMessages) {
-  const plan = xepvMessages.filter(m => m.xepv === 'X_Plan').length;
-  const execute = xepvMessages.filter(m => m.xepv === 'X_Execute').length;
-  return { planSteps: plan, executeSteps: execute, ratio: execute > 0 ? plan / execute : plan };
-}
-
-module.exports = { readSessionLog, classifyXEPV, findBranchPoint, computePRatio };

package/daemon/routes/hed.js

@@ -1,133 +0,0 @@
-'use strict';
-
-const { HEDEngine } = require('../lib/hed-engine');
-
-/**
- * HED API routes — /api/hed/*
- * Follows the standard Helios router pattern: returns true if handled, false otherwise.
- * Initialized lazily inside startApi() via createHedRoutes(mgQuery).
- */
-
-function jsonOk(res, data, status = 200) {
-  res.writeHead(status, {
-    'Content-Type': 'application/json',
-    'Access-Control-Allow-Origin': '*',
-    'Access-Control-Allow-Methods': 'GET, POST, PATCH, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type, Accept',
-  });
-  res.end(JSON.stringify(data));
-}
-
-function jsonErr(res, status, message) {
-  res.writeHead(status, {
-    'Content-Type': 'application/json',
-    'Access-Control-Allow-Origin': '*',
-    'Access-Control-Allow-Methods': 'GET, POST, PATCH, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type, Accept',
-  });
-  res.end(JSON.stringify({ error: message }));
-}
-
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    let body = '';
-    req.on('data', chunk => { body += chunk; });
-    req.on('end', () => {
-      try { resolve(body ? JSON.parse(body) : {}); }
-      catch (e) { reject(new Error('Invalid JSON body')); }
-    });
-    req.on('error', reject);
-  });
-}
-
-function createHedRoutes(mgQuery) {
-  const engine = new HEDEngine(mgQuery);
-
-  return async function hedRoute(req, res, ctx, pathname, method) {
-    // Only handle /api/hed paths
-    if (!pathname.startsWith('/api/hed')) return false;
-
-    const mg = ctx?.mgQuery ?? mgQuery;
-    const _engine = ctx?.mgQuery ? new HEDEngine(ctx.mgQuery) : engine;
-
-    try {
-      // POST /api/hed — create a new HED
-      if (method === 'POST' && pathname === '/api/hed') {
-        const body = await readBody(req);
-        const { companyId, title, intent, worldStateSnapshot, operations, goalId } = body;
-        if (!companyId || !title || !operations?.length) {
-          jsonErr(res, 400, 'companyId, title, and operations are required');
-          return true;
-        }
-        const result = await _engine.createHED({ companyId, title, intent, worldStateSnapshot, operations, goalId });
-        jsonOk(res, result, 201);
-        return true;
-      }
-
-      // POST /api/hed/:id/approve — HITL approval
-      const approveMatch = method === 'POST' && pathname.match(/^\/api\/hed\/([^/]+)\/approve$/);
-      if (approveMatch) {
-        const hedId = approveMatch[1];
-        const body = await readBody(req);
-        const { approvedBy } = body;
-        await _engine.approveHED(hedId, approvedBy || 'human');
-        jsonOk(res, { hedId, approved: true });
-        return true;
-      }
-
-      // GET /api/hed/:id/review — aggregated review report
-      const reviewMatch = method === 'GET' && pathname.match(/^\/api\/hed\/([^/]+)\/review$/);
-      if (reviewMatch) {
-        const hedId = reviewMatch[1];
-        const operations = await _engine.getOperations(hedId);
-        const findings = operations.map(op => ({
-          opId: op.id,
-          status: op.status,
-          reviewVerdict: op.reviewVerdict || 'pending'
-        }));
-        const aligned = findings.filter(f => f.reviewVerdict === 'ALIGNED').length;
-        const deviated = findings.filter(f => f.reviewVerdict === 'DEVIATED').length;
-        const failed = findings.filter(f => f.reviewVerdict === 'FAILED').length;
-        jsonOk(res, {
-          hedId,
-          findings,
-          summary: { aligned, deviated, failed, pending: findings.length - aligned - deviated - failed }
-        });
-        return true;
-      }
-
-      // PATCH /api/hed/:hedId/operations/:opId — update operation status
-      const opPatchMatch = method === 'PATCH' && pathname.match(/^\/api\/hed\/([^/]+)\/operations\/([^/]+)$/);
-      if (opPatchMatch) {
-        const opId = opPatchMatch[2];
-        const body = await readBody(req);
-        const { status, summary, sessionKey, verdict } = body;
-        if (status === 'done' || status === 'completed') {
-          await _engine.completeOperation(opId, { summary, sessionKey, verdict });
-        }
-        jsonOk(res, { opId, updated: true });
-        return true;
-      }
-
-      // GET /api/hed/:id — get HED + all operations
-      const hedMatch = method === 'GET' && pathname.match(/^\/api\/hed\/([^/]+)$/);
-      if (hedMatch) {
-        const hedId = hedMatch[1];
-        const hed = await _engine.getHED(hedId);
-        if (!hed) { jsonErr(res, 404, 'HED not found'); return true; }
-        const operations = await _engine.getOperations(hedId);
-        jsonOk(res, { ...hed, operations });
-        return true;
-      }
-
-    } catch (err) {
-      console.error('[hed-routes] error:', err.message);
-      jsonErr(res, 500, err.message);
-      return true;
-    }
-
-    return false;
-  };
-}
-
-module.exports = { createHedRoutes };

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

@@ -1,215 +0,0 @@
-'use strict';
-
-/**
- * lib/graph/learning/headroom-learn-bridge.js
- *
- * Bridges headroom's session failure-learning system with Helios's Memgraph
- * learning graph. Called asynchronously from the RETROSPECTIVE phase after
- * each CausalLesson extraction.
- *
- * Pipeline:
- *   1. Run `headroom learn --apply --project {helios-agent-root} --target AGENTS.md`
- *      using the vendored headroom package at vendor/headroom-proxy/
- *   2. headroom learn scans Pi session logs (SQLite DB + tool-output blobs)
- *      and writes corrections to AGENTS.md (marker-delimited, git-tracked)
- *   3. Parse corrections from AGENTS.md headroom:learn markers
- *   4. Write corrections as KnowledgeAsset nodes to Memgraph
- *   5. KnowledgeAsset nodes surface via biz-lesson-recall + lesson-recall channels
- *      in future sessions
- *
- * Why this improves the whole system (not just one company):
- *   - Structural patterns (path corrections, command patterns, search scope fixes)
- *     are cross-company: they describe helios-agent behavior, not company data
- *   - KnowledgeAsset confidence increases each time a pattern is reinforced
- *   - Corrections in AGENTS.md are git-tracked and manually reviewable
- *   - The global AGENTS.md (~/.config/opencode/AGENTS.md) is NEVER touched
- *
- * Debounce: runs at most once per 5 minutes across all sessions to avoid
- * hammering the Pi session log scanner.
- */
-
-const path     = require('path');
-const fs       = require('fs');
-const crypto   = require('crypto');
-const { execFile } = require('child_process');
-
-const HELIOS_ROOT   = process.env.HELIOS_ROOT || path.resolve(__dirname, '..', '..', '..');
-const AGENTS_MD     = path.join(HELIOS_ROOT, 'AGENTS.md');
-const VENDOR_PATH   = path.join(HELIOS_ROOT, 'vendor', 'headroom-proxy');
-const MARKER_START  = '<!-- headroom:learn:start -->';
-const MARKER_END    = '<!-- headroom:learn:end -->';
-const DEBOUNCE_MS   = 5 * 60 * 1000; // 5 minutes between runs
-
-let _lastRunAt = 0;
-
-/**
- * Main entry point. Called from retrospective.ts after CausalLesson extraction.
- * @param {Function} mgQueryAsync - Memgraph query function
- * @param {string} sessionId - Current session ID
- * @param {string} missionRunId - Current mission run ID
- */
-async function runBridge(mgQueryAsync, sessionId, missionRunId) {
-  const now = Date.now();
-  if (now - _lastRunAt < DEBOUNCE_MS) return;
-  _lastRunAt = now;
-
-  // Verify vendor path exists before attempting anything
-  if (!fs.existsSync(VENDOR_PATH)) {
-    process.stderr.write('[headroom-learn-bridge] vendor/headroom-proxy not found — skipping learn run\n');
-    return;
-  }
-
-  try {
-    // Step 1: Run headroom learn
-    await _runHeadroomLearn();
-
-    // Step 2: Parse corrections from AGENTS.md
-    const corrections = _parseCorrections();
-    if (!corrections.length) {
-      process.stderr.write('[headroom-learn-bridge] No corrections found in AGENTS.md markers\n');
-      return;
-    }
-
-    // Step 3: Write to Memgraph
-    await _writeToMemgraph(mgQueryAsync, corrections, sessionId, missionRunId);
-
-    process.stderr.write(
-      `[headroom-learn-bridge] Wrote ${corrections.length} corrections to Memgraph KnowledgeAsset nodes\n`
-    );
-  } catch (err) {
-    // Completely non-fatal — never block RETROSPECTIVE phase
-    process.stderr.write(`[headroom-learn-bridge] Failed (non-fatal): ${err.message}\n`);
-  }
-}
-
-/**
- * Run `headroom learn --apply` using the vendored package.
- * Writes to AGENTS.md with <!-- headroom:learn:start/end --> markers.
- * Only the marker block is replaced — existing AGENTS.md content is preserved.
- */
-function _runHeadroomLearn() {
-  return new Promise((resolve, reject) => {
-    const pythonBin = process.env.HEADROOM_PYTHON || 'python3';
-
-    // Use CLAUDE.local.md as target to avoid polluting shared AGENTS.md
-    // The corrections are written to a separate local file, then we parse
-    // them and write to Memgraph. Per-repo AGENTS.md gets the marker block.
-    const args = [
-      '-m', 'headroom.learn',
-      '--apply',
-      '--project', HELIOS_ROOT,
-      '--target', 'AGENTS.md',  // per-repo AGENTS.md (NOT global ~/.config/opencode/AGENTS.md)
-    ];
-
-    execFile(pythonBin, args, {
-      cwd: VENDOR_PATH,
-      env: {
-        ...process.env,
-        PYTHONPATH: VENDOR_PATH,
-        HEADROOM_TELEMETRY: 'off',
-      },
-      timeout: 120_000, // 2-minute timeout (session log scanning can be slow on large projects)
-    }, (err, stdout, stderr) => {
-      if (err) {
-        // Non-zero exit is common when no sessions have been scanned yet
-        // Only reject on hard failures (ENOENT, etc.)
-        if (err.code === 'ENOENT') {
-          return reject(new Error(`Python not found: ${pythonBin}`));
-        }
-        // For other errors, log but resolve — partial output may still be useful
-        if (stderr) process.stderr.write(`[headroom-learn] ${stderr.slice(0, 500)}\n`);
-        return resolve(null); // resolve, not reject
-      }
-      if (stdout) process.stderr.write(`[headroom-learn] ${stdout.slice(0, 200)}\n`);
-      resolve(null);
-    });
-  });
-}
-
-/**
- * Parse the headroom:learn marker block from AGENTS.md.
- * Returns an array of { category, content } corrections.
- */
-function _parseCorrections() {
-  try {
-    if (!fs.existsSync(AGENTS_MD)) return [];
-    const content = fs.readFileSync(AGENTS_MD, 'utf-8');
-    const start = content.indexOf(MARKER_START);
-    const end   = content.indexOf(MARKER_END);
-    if (start === -1 || end === -1 || end <= start) return [];
-
-    const block = content.slice(start + MARKER_START.length, end);
-    return _parseMarkdownBlock(block);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Parse markdown sections into structured corrections.
- * Headings become categories; bullet items become corrections.
- */
-function _parseMarkdownBlock(markdown) {
-  const corrections = [];
-  const lines = markdown.split('\n');
-  let currentCategory = 'general';
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (trimmed.startsWith('### ')) {
-      currentCategory = trimmed.slice(4).toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
-    } else if (trimmed.startsWith('## ') && !trimmed.startsWith('### ')) {
-      currentCategory = trimmed.slice(3).toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
-    } else if (trimmed.startsWith('- ') && trimmed.length > 5) {
-      const content = trimmed.slice(2).trim();
-      // Filter out boilerplate / empty corrections
-      if (content.length >= 15 && !content.startsWith('*Auto-generated')) {
-        corrections.push({ category: currentCategory, content });
-      }
-    }
-  }
-  return corrections;
-}
-
-/**
- * Write corrections as KnowledgeAsset nodes to Memgraph.
- * Uses MERGE on a stable content-hash ID for idempotency.
- * Confidence increases each time the same pattern is reinforced.
- */
-async function _writeToMemgraph(mgQueryAsync, corrections, sessionId, missionRunId) {
-  for (const correction of corrections) {
-    const id = 'headroom-learn:' + crypto.createHash('sha256')
-      .update(correction.content).digest('hex').slice(0, 16);
-
-    await mgQueryAsync(`
-      MERGE (ka:KnowledgeAsset {id: $id})
-      ON CREATE SET
-        ka.type            = 'headroom-correction',
-        ka.category        = $category,
-        ka.content         = $content,
-        ka.confidence      = 0.65,
-        ka.source          = 'headroom-learn',
-        ka.sessionId       = $sessionId,
-        ka.missionRunId    = $missionRunId,
-        ka.createdAt       = localdatetime(),
-        ka.lastSeenAt      = localdatetime()
-      ON MATCH SET
-        ka.confidence      = CASE
-          WHEN ka.confidence < 0.95 THEN ka.confidence + 0.05
-          ELSE 0.95
-        END,
-        ka.lastSeenAt      = localdatetime(),
-        ka.updatedAt       = localdatetime(),
-        ka.sessionId       = $sessionId,
-        ka.missionRunId    = $missionRunId
-    `, {
-      id,
-      category: correction.category,
-      content: correction.content,
-      sessionId: sessionId ?? 'unknown',
-      missionRunId: missionRunId ?? 'unknown',
-    });
-  }
-}
-
-module.exports = { runBridge };