aios-core 4.0.4 → 4.2.0

package/.aios-core/core/synapse/diagnostics/collectors/relevance-matrix.js

@@ -0,0 +1,174 @@
+/**
+ * Relevance Matrix — Agent-specific importance mapping for context components.
+ *
+ * Maps each UAP loader and Hook layer to an importance level per agent type.
+ * Used by diagnostics to show which context is most critical for the active agent.
+ *
+ * @module core/synapse/diagnostics/collectors/relevance-matrix
+ * @version 1.0.0
+ * @created Story SYN-14
+ */
+
+'use strict';
+
+const path = require('path');
+const { safeReadJson } = require('./safe-read-json');
+
+/**
+ * Importance levels for context components.
+ * @enum {string}
+ */
+const IMPORTANCE = {
+  CRITICAL: 'critical',
+  IMPORTANT: 'important',
+  OPTIONAL: 'optional',
+  IRRELEVANT: 'irrelevant',
+};
+
+/**
+ * Default relevance map — applies to agents without specific overrides.
+ * @type {Object.<string, string>}
+ */
+const DEFAULT_RELEVANCE = {
+  // UAP loaders
+  agentConfig: IMPORTANCE.CRITICAL,
+  permissionMode: IMPORTANCE.OPTIONAL,
+  gitConfig: IMPORTANCE.OPTIONAL,
+  sessionContext: IMPORTANCE.IMPORTANT,
+  projectStatus: IMPORTANCE.OPTIONAL,
+  memories: IMPORTANCE.IMPORTANT,
+  synapseSession: IMPORTANCE.OPTIONAL,
+  // Hook layers
+  constitution: IMPORTANCE.CRITICAL,
+  global: IMPORTANCE.IMPORTANT,
+  agent: IMPORTANCE.CRITICAL,
+  workflow: IMPORTANCE.OPTIONAL,
+  task: IMPORTANCE.OPTIONAL,
+  squad: IMPORTANCE.IRRELEVANT,
+  keyword: IMPORTANCE.OPTIONAL,
+  'star-command': IMPORTANCE.OPTIONAL,
+};
+
+/**
+ * Agent-specific overrides. Only components that differ from DEFAULT_RELEVANCE.
+ * @type {Object.<string, Object.<string, string>>}
+ */
+const AGENT_OVERRIDES = {
+  dev: {
+    gitConfig: IMPORTANCE.IMPORTANT,
+    projectStatus: IMPORTANCE.IMPORTANT,
+    workflow: IMPORTANCE.IMPORTANT,
+    task: IMPORTANCE.CRITICAL,
+  },
+  qa: {
+    projectStatus: IMPORTANCE.IMPORTANT,
+    task: IMPORTANCE.IMPORTANT,
+  },
+  devops: {
+    gitConfig: IMPORTANCE.CRITICAL,
+    permissionMode: IMPORTANCE.IMPORTANT,
+    squad: IMPORTANCE.OPTIONAL,
+  },
+  architect: {
+    projectStatus: IMPORTANCE.IMPORTANT,
+    memories: IMPORTANCE.CRITICAL,
+  },
+  pm: {
+    projectStatus: IMPORTANCE.CRITICAL,
+    workflow: IMPORTANCE.IMPORTANT,
+  },
+  sm: {
+    workflow: IMPORTANCE.IMPORTANT,
+    task: IMPORTANCE.IMPORTANT,
+  },
+};
+
+/**
+ * Build relevance matrix for a given agent.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{
+ *   available: boolean,
+ *   agentId: string,
+ *   matrix: Array<{ component: string, importance: string, status: string, gap: boolean }>,
+ *   gaps: Array<{ component: string, importance: string }>,
+ *   score: number
+ * }}
+ */
+function collectRelevanceMatrix(projectRoot) {
+  const metricsDir = path.join(projectRoot, '.synapse', 'metrics');
+
+  const uapData = safeReadJson(path.join(metricsDir, 'uap-metrics.json'));
+  const hookData = safeReadJson(path.join(metricsDir, 'hook-metrics.json'));
+  const bridgeData = safeReadJson(path.join(projectRoot, '.synapse', 'sessions', '_active-agent.json'));
+
+  const agentId = (uapData && uapData.agentId) || (bridgeData && bridgeData.id) || 'unknown';
+
+  if (!uapData && !hookData) {
+    return { available: false, agentId, matrix: [], gaps: [], score: 0 };
+  }
+
+  const relevanceMap = _getRelevanceForAgent(agentId);
+  const matrix = [];
+  const gaps = [];
+  let totalWeight = 0;
+  let achievedWeight = 0;
+
+  const weightMap = { critical: 4, important: 2, optional: 1, irrelevant: 0 };
+
+  for (const [component, importance] of Object.entries(relevanceMap)) {
+    const weight = weightMap[importance] || 0;
+    totalWeight += weight;
+
+    const status = _getComponentStatus(component, uapData, hookData);
+    const gap = importance !== IMPORTANCE.IRRELEVANT && status !== 'ok' && status !== 'skipped';
+
+    if (gap && weight > 0) {
+      gaps.push({ component, importance });
+    } else {
+      achievedWeight += weight;
+    }
+
+    matrix.push({ component, importance, status, gap });
+  }
+
+  const score = totalWeight > 0 ? Math.round((achievedWeight / totalWeight) * 100) : 0;
+
+  return { available: true, agentId, matrix, gaps, score };
+}
+
+/**
+ * Get relevance map for a specific agent (default + overrides).
+ * @param {string} agentId
+ * @returns {Object.<string, string>}
+ */
+function _getRelevanceForAgent(agentId) {
+  const overrides = AGENT_OVERRIDES[agentId] || {};
+  return { ...DEFAULT_RELEVANCE, ...overrides };
+}
+
+/**
+ * Get the status of a component from UAP or Hook data.
+ * @param {string} component
+ * @param {Object|null} uapData
+ * @param {Object|null} hookData
+ * @returns {string}
+ */
+function _getComponentStatus(component, uapData, hookData) {
+  // Check UAP loaders
+  if (uapData && uapData.loaders && uapData.loaders[component]) {
+    return uapData.loaders[component].status || 'unknown';
+  }
+  // Check Hook layers
+  if (hookData && hookData.perLayer && hookData.perLayer[component]) {
+    return hookData.perLayer[component].status || 'unknown';
+  }
+  return 'missing';
+}
+
+module.exports = {
+  collectRelevanceMatrix,
+  IMPORTANCE,
+  DEFAULT_RELEVANCE,
+  AGENT_OVERRIDES,
+};

package/.aios-core/core/synapse/diagnostics/collectors/safe-read-json.js

@@ -0,0 +1,31 @@
+/**
+ * Shared utility — safely reads and parses a JSON file.
+ *
+ * Extracted from multiple collectors to eliminate duplication.
+ *
+ * @module core/synapse/diagnostics/collectors/safe-read-json
+ * @version 1.0.0
+ * @created Story SYN-14 (QA refactor)
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Safely read and parse a JSON file.
+ * Returns null on any error (file not found, invalid JSON, permissions, etc.)
+ *
+ * @param {string} filePath - Absolute path to JSON file
+ * @returns {Object|null} Parsed data or null
+ */
+function safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { safeReadJson };

package/.aios-core/core/synapse/diagnostics/collectors/session-collector.js

@@ -0,0 +1,102 @@
+/**
+ * Session Collector — Reads current SYNAPSE session state.
+ *
+ * Validates session fields: active_agent, prompt_count, bracket, schema.
+ *
+ * @module core/synapse/diagnostics/collectors/session-collector
+ * @version 1.0.0
+ * @created Story SYN-13
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Collect session status data.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {string} [sessionId] - Optional session UUID to load
+ * @returns {{ fields: Array<{ field: string, expected: string, actual: string, status: string }>, raw: object|null }}
+ */
+function collectSessionStatus(projectRoot, sessionId) {
+  const sessionsDir = path.join(projectRoot, '.synapse', 'sessions');
+  const fields = [];
+  let raw = null;
+
+  // Try to load session by ID, or find the most recent one
+  let session = null;
+
+  if (sessionId) {
+    const sessionPath = path.join(sessionsDir, `${sessionId}.json`);
+    session = _readJsonSafe(sessionPath);
+  }
+
+  // Fallback: read _active-agent.json bridge file
+  const bridgePath = path.join(sessionsDir, '_active-agent.json');
+  const bridgeData = _readJsonSafe(bridgePath);
+
+  // Check active_agent
+  const agentId = session?.active_agent?.id || bridgeData?.id || null;
+  fields.push({
+    field: 'active_agent.id',
+    expected: '(any agent)',
+    actual: agentId || '(none)',
+    status: agentId ? 'PASS' : 'WARN',
+  });
+
+  // Check activation_quality
+  const quality = session?.active_agent?.activation_quality || bridgeData?.activation_quality || null;
+  fields.push({
+    field: 'activation_quality',
+    expected: 'full|partial|fallback',
+    actual: quality || '(none)',
+    status: quality ? 'PASS' : 'WARN',
+  });
+
+  // Check prompt_count
+  const promptCount = session?.prompt_count ?? null;
+  fields.push({
+    field: 'prompt_count',
+    expected: '>= 0',
+    actual: promptCount !== null ? String(promptCount) : '(no session)',
+    status: promptCount !== null ? 'PASS' : 'INFO',
+  });
+
+  // Check bracket
+  const bracket = session?.context?.last_bracket || null;
+  fields.push({
+    field: 'bracket',
+    expected: 'FRESH|MODERATE|DEPLETED|CRITICAL',
+    actual: bracket || '(no session)',
+    status: bracket ? 'PASS' : 'INFO',
+  });
+
+  // Check bridge file exists
+  fields.push({
+    field: '_active-agent.json',
+    expected: 'exists',
+    actual: bridgeData ? 'exists' : 'missing',
+    status: bridgeData ? 'PASS' : 'WARN',
+  });
+
+  raw = { session, bridgeData };
+  return { fields, raw };
+}
+
+/**
+ * Safely read and parse a JSON file.
+ * @param {string} filePath
+ * @returns {object|null}
+ */
+function _readJsonSafe(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { collectSessionStatus };

package/.aios-core/core/synapse/diagnostics/collectors/timing-collector.js

@@ -0,0 +1,126 @@
+/**
+ * Timing Collector — Reads persisted UAP and Hook metrics for diagnostics.
+ *
+ * Reads `.synapse/metrics/uap-metrics.json` and `.synapse/metrics/hook-metrics.json`
+ * written by the UAP activation pipeline and SynapseEngine respectively.
+ *
+ * @module core/synapse/diagnostics/collectors/timing-collector
+ * @version 1.0.0
+ * @created Story SYN-12
+ */
+
+'use strict';
+
+const path = require('path');
+const { safeReadJson } = require('./safe-read-json');
+
+/**
+ * Loader tier mapping for UAP loaders.
+ * @type {Object.<string, string>}
+ */
+/** Maximum staleness threshold in ms (5 minutes). Data older than this is WARN. */
+const MAX_STALENESS_MS = 5 * 60 * 1000;
+
+const LOADER_TIER_MAP = {
+  agentConfig: 'Critical',
+  permissionMode: 'High',
+  gitConfig: 'High',
+  sessionContext: 'Best-effort',
+  projectStatus: 'Best-effort',
+  memories: 'Pro',
+  synapseSession: 'Bridge',
+};
+
+/**
+ * Collect timing metrics from persisted UAP and Hook metrics files.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{
+ *   uap: { available: boolean, totalDuration: number, quality: string, loaders: Array },
+ *   hook: { available: boolean, totalDuration: number, bracket: string, layers: Array },
+ *   combined: { totalMs: number }
+ * }}
+ */
+function collectTimingMetrics(projectRoot) {
+  const metricsDir = path.join(projectRoot, '.synapse', 'metrics');
+  const now = Date.now();
+
+  // --- UAP Metrics ---
+  const uapData = safeReadJson(path.join(metricsDir, 'uap-metrics.json'));
+  const uap = _buildUapTiming(uapData, now);
+
+  // --- Hook Metrics ---
+  const hookData = safeReadJson(path.join(metricsDir, 'hook-metrics.json'));
+  const hook = _buildHookTiming(hookData, now);
+
+  return {
+    uap,
+    hook,
+    combined: {
+      totalMs: (uap.available ? uap.totalDuration : 0) + (hook.available ? hook.totalDuration : 0),
+    },
+  };
+}
+
+/**
+ * Build UAP timing section from persisted data.
+ * @param {Object|null} data - Parsed uap-metrics.json
+ * @returns {Object} UAP timing data
+ */
+function _buildUapTiming(data, now) {
+  if (!data || !data.loaders) {
+    return { available: false, totalDuration: 0, quality: 'unknown', loaders: [], stale: false, ageMs: 0 };
+  }
+
+  const ageMs = data.timestamp ? now - new Date(data.timestamp).getTime() : 0;
+  const stale = ageMs > MAX_STALENESS_MS;
+
+  const loaders = Object.entries(data.loaders).map(([name, info]) => ({
+    name,
+    duration: info.duration || 0,
+    status: info.status || 'unknown',
+    tier: LOADER_TIER_MAP[name] || 'Unknown',
+  }));
+
+  return {
+    available: true,
+    totalDuration: data.totalDuration || 0,
+    quality: data.quality || 'unknown',
+    loaders,
+    stale,
+    ageMs,
+  };
+}
+
+/**
+ * Build Hook timing section from persisted data.
+ * @param {Object|null} data - Parsed hook-metrics.json
+ * @returns {Object} Hook timing data
+ */
+function _buildHookTiming(data, now) {
+  if (!data || !data.perLayer) {
+    return { available: false, totalDuration: 0, bracket: 'unknown', layers: [], stale: false, ageMs: 0 };
+  }
+
+  const ageMs = data.timestamp ? now - new Date(data.timestamp).getTime() : 0;
+  const stale = ageMs > MAX_STALENESS_MS;
+
+  const layers = Object.entries(data.perLayer).map(([name, info]) => ({
+    name,
+    duration: info.duration || 0,
+    status: info.status || 'unknown',
+    rules: info.rules || 0,
+  }));
+
+  return {
+    available: true,
+    totalDuration: data.totalDuration || 0,
+    hookBootMs: data.hookBootMs || 0,
+    bracket: data.bracket || 'unknown',
+    layers,
+    stale,
+    ageMs,
+  };
+}
+
+module.exports = { collectTimingMetrics, LOADER_TIER_MAP, MAX_STALENESS_MS };

package/.aios-core/core/synapse/diagnostics/collectors/uap-collector.js

@@ -0,0 +1,83 @@
+/**
+ * UAP Collector — Verifies UAP → SYNAPSE bridge status.
+ *
+ * Checks if _active-agent.json exists and contains valid data.
+ *
+ * @module core/synapse/diagnostics/collectors/uap-collector
+ * @version 1.0.0
+ * @created Story SYN-13
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Collect UAP bridge status data.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {{ checks: Array<{ name: string, status: string, detail: string }> }}
+ */
+function collectUapBridgeStatus(projectRoot) {
+  const checks = [];
+  const bridgePath = path.join(projectRoot, '.synapse', 'sessions', '_active-agent.json');
+
+  // Check 1: Bridge file exists
+  const exists = fs.existsSync(bridgePath);
+  checks.push({
+    name: '_active-agent.json exists',
+    status: exists ? 'PASS' : 'FAIL',
+    detail: exists ? 'Written at activation' : 'File not found — UAP may not have written it',
+  });
+
+  if (!exists) {
+    checks.push({
+      name: 'active_agent matches',
+      status: 'SKIP',
+      detail: 'Bridge file does not exist',
+    });
+    return { checks };
+  }
+
+  // Check 2: File is valid JSON with expected fields
+  try {
+    const data = JSON.parse(fs.readFileSync(bridgePath, 'utf8'));
+
+    if (data.id) {
+      checks.push({
+        name: 'active_agent matches',
+        status: 'PASS',
+        detail: `Agent: ${data.id}, quality: ${data.activation_quality || 'unknown'}, source: ${data.source || 'unknown'}`,
+      });
+    } else {
+      checks.push({
+        name: 'active_agent matches',
+        status: 'FAIL',
+        detail: 'Bridge file exists but id field is missing',
+      });
+    }
+
+    // Check 3: Freshness (was it written recently?)
+    if (data.activated_at) {
+      const activatedAt = new Date(data.activated_at);
+      const ageMs = Date.now() - activatedAt.getTime();
+      const ageMinutes = Math.round(ageMs / 60000);
+      checks.push({
+        name: 'Bridge freshness',
+        status: ageMinutes < 60 ? 'PASS' : 'WARN',
+        detail: `Activated ${ageMinutes}m ago${ageMinutes >= 60 ? ' (stale — may be from previous session)' : ''}`,
+      });
+    }
+  } catch (error) {
+    checks.push({
+      name: 'active_agent matches',
+      status: 'ERROR',
+      detail: `Failed to parse bridge file: ${error.message}`,
+    });
+  }
+
+  return { checks };
+}
+
+module.exports = { collectUapBridgeStatus };