sinapse-ai 1.6.1 → 1.8.0

package/.sinapse-ai/core/registry/squad-agent-resolver.js

@@ -0,0 +1,253 @@
+/**
+ * Squad Agent Resolver
+ *
+ * epic: orchestration-consolidation, F2 — makes the 177 squad personas (plus the
+ * framework agents) addressable BY CODE. Before this, the SubagentDispatcher knew
+ * only ~10 generic agents (@dev/@qa/...) and built a one-line "You are @x" prompt,
+ * discarding the real persona. This indexes every agent .md across `squads/` and
+ * the framework agent dirs, and loads the FULL persona on demand.
+ *
+ * Convention (verified across all squads): the agent id IS the file basename in
+ * kebab-case (e.g. `penetration-tester.md` -> id `penetration-tester`), which
+ * matches the embedded `id:` field. We key by basename for robustness and also
+ * register the embedded id / display name as aliases when present.
+ *
+ * @module core/registry/squad-agent-resolver
+ * @version 1.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Directories scanned for agent definitions, relative to projectRoot. */
+const AGENT_DIRS = [
+  'squads', // squads/<squad>/agents/<id>.md
+  path.join('.sinapse-ai', 'agents'),
+  path.join('.sinapse-ai', 'development', 'agents'),
+];
+
+/**
+ * Short-form aliases used across the framework (dispatcher agentMapping, CLAUDE.md
+ * command table) → canonical file id. Lets '@dev' resolve to the developer persona
+ * instead of falling through to a one-line generic prompt.
+ */
+const ALIASES = {
+  dev: 'developer',
+  qa: 'quality-gate',
+  pm: 'project-lead',
+  po: 'product-lead',
+  sm: 'sprint-lead',
+  ux: 'ux-design-expert',
+  'ux-expert': 'ux-design-expert',
+};
+
+class SquadAgentResolver {
+  /**
+   * @param {string} projectRoot - Project root directory
+   */
+  constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
+    this._index = null; // Map<normalizedKey, entry> — built lazily
+    this._personaCache = new Map(); // id -> persona content
+  }
+
+  /**
+   * Normalize an agent reference for lookup: strip leading '@', lowercase,
+   * collapse separators. So '@penetration-tester', 'penetration_tester' and
+   * 'Penetration Tester' all resolve to the same key.
+   * @param {string} ref
+   * @returns {string}
+   */
+  static normalizeKey(ref) {
+    return String(ref || '')
+      .replace(/^@/, '')
+      .trim()
+      .toLowerCase()
+      .replace(/[\s_]+/g, '-');
+  }
+
+  /**
+   * Build (once) the index of every agent definition on disk.
+   * @returns {Map<string, Object>} normalizedKey -> { id, name, squad, filePath }
+   */
+  buildIndex() {
+    if (this._index) return this._index;
+    const index = new Map();
+
+    const addEntry = (filePath, squad) => {
+      const base = path.basename(filePath, '.md');
+      if (!base || base.toUpperCase() === 'README') return;
+      const key = SquadAgentResolver.normalizeKey(base);
+      // First writer wins for a given key, but squad agents take precedence over
+      // framework duplicates only if a squad entry isn't already registered.
+      if (!index.has(key)) {
+        index.set(key, { id: base, name: base, squad, filePath });
+      }
+    };
+
+    for (const rel of AGENT_DIRS) {
+      const dir = path.join(this.projectRoot, rel);
+      if (!fs.existsSync(dir)) continue;
+
+      if (rel === 'squads') {
+        // squads/<squad>/agents/*.md
+        let squadDirs = [];
+        try {
+          squadDirs = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+          squadDirs = [];
+        }
+        for (const sd of squadDirs) {
+          if (!sd.isDirectory()) continue;
+          const agentsDir = path.join(dir, sd.name, 'agents');
+          if (!fs.existsSync(agentsDir)) continue;
+          for (const f of this._listMd(agentsDir)) {
+            addEntry(path.join(agentsDir, f), sd.name);
+          }
+        }
+      } else {
+        // flat dir of *.md
+        for (const f of this._listMd(dir)) {
+          addEntry(path.join(dir, f), null);
+        }
+      }
+    }
+
+    this._index = index;
+    return index;
+  }
+
+  /**
+   * List .md files in a directory (non-recursive), tolerant of read errors.
+   * @param {string} dir
+   * @returns {string[]}
+   * @private
+   */
+  _listMd(dir) {
+    try {
+      return fs.readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.md'));
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Resolve an agent reference to its index entry.
+   * @param {string} ref - e.g. '@penetration-tester', 'dev', 'cloud-security-engineer'
+   * @returns {Object|null} { id, name, squad, filePath } or null when unknown
+   */
+  resolve(ref) {
+    const index = this.buildIndex();
+    const key = SquadAgentResolver.normalizeKey(ref);
+    return index.get(key) || index.get(ALIASES[key]) || null;
+  }
+
+  /**
+   * True when the reference maps to a known agent definition on disk.
+   * @param {string} ref
+   * @returns {boolean}
+   */
+  has(ref) {
+    return this.resolve(ref) !== null;
+  }
+
+  /**
+   * Load the full persona markdown for an agent reference.
+   * @param {string} ref
+   * @returns {string|null} persona content, or null when unknown/unreadable
+   */
+  loadPersona(ref) {
+    const entry = this.resolve(ref);
+    if (!entry) return null;
+    if (this._personaCache.has(entry.id)) return this._personaCache.get(entry.id);
+    let content = null;
+    try {
+      content = fs.readFileSync(entry.filePath, 'utf8');
+    } catch {
+      content = null;
+    }
+    this._personaCache.set(entry.id, content);
+    return content;
+  }
+
+  /**
+   * All known agent ids (sorted), for diagnostics / `sinapse` listing.
+   * @returns {string[]}
+   */
+  listIds() {
+    return [...this.buildIndex().values()].map((e) => e.id).sort();
+  }
+
+  /**
+   * Count of indexed agents.
+   * @returns {number}
+   */
+  size() {
+    return this.buildIndex().size;
+  }
+
+  /**
+   * Normalized metadata for an agent, extracted from whatever structure the
+   * file uses (frontmatter, `# Agent: X`, `# X`, or an embedded ```yaml block).
+   * This is the uniform schema (SCHEMA-001 closure) without mutating the 199
+   * heterogeneous persona files — the canonical shape is DERIVED, not imposed.
+   *
+   * @param {string} ref
+   * @returns {{id, name, squad, type, hasStructuredYaml, file}|null}
+   */
+  describe(ref) {
+    const entry = this.resolve(ref);
+    if (!entry) return null;
+    const content = this.loadPersona(entry.id) || '';
+    return {
+      id: entry.id,
+      name: SquadAgentResolver.extractName(content, entry.id),
+      squad: entry.squad || 'framework',
+      type: /-orqx$/.test(entry.id) ? 'orchestrator' : 'specialist',
+      hasStructuredYaml: /```ya?ml/.test(content) || /^\s*agent:\s*$/m.test(content),
+      file: entry.filePath,
+    };
+  }
+
+  /**
+   * Describe every indexed agent (sorted by id) — the uniform registry view.
+   * @returns {Array<Object>}
+   */
+  list() {
+    return this.listIds().map((id) => this.describe(id));
+  }
+
+  /**
+   * Best-effort display name from heterogeneous structures. Falls back to a
+   * title-cased id so the result is never empty.
+   * @param {string} content - File content
+   * @param {string} id - Canonical id (filename)
+   * @returns {string}
+   */
+  static extractName(content, id) {
+    const src = String(content || '');
+    // 1. YAML frontmatter `name:`
+    const fm = src.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (fm) {
+      const m = fm[1].match(/^\s*name:\s*["']?([^"'\n]+)["']?\s*$/m);
+      if (m && m[1].trim()) return m[1].trim();
+    }
+    // 2. Embedded yaml `name:` (inside an ```yaml block or agent: section)
+    const ym = src.match(/^\s*name:\s*["']?([^"'\n]+)["']?\s*$/m);
+    if (ym && ym[1].trim()) return ym[1].trim();
+    // 3. `# Agent: Name`
+    const ah = src.match(/^#\s*Agent:\s*(.+?)\s*$/m);
+    if (ah && ah[1].trim()) return ah[1].trim();
+    // 4. First `# Heading`
+    const h1 = src.match(/^#\s+(.+?)\s*$/m);
+    if (h1 && h1[1].trim()) return h1[1].trim().replace(/^@/, '');
+    // 5. Title-cased id
+    return String(id)
+      .split('-')
+      .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+      .join(' ');
+  }
+}
+
+module.exports = SquadAgentResolver;
+module.exports.SquadAgentResolver = SquadAgentResolver;

package/.sinapse-ai/core/synapse/context/context-tracker.js

@@ -5,13 +5,16 @@
  * based on estimated token usage. Provides token budgets and layer filtering
  * per bracket for the SynapseEngine orchestrator.
  *
- * Pure arithmetic module — zero I/O, zero external dependencies.
+ * Reads model context window from core-config.yaml → models.registry.
  *
  * @module core/synapse/context/context-tracker
- * @version 1.0.0
+ * @version 1.1.0
  * @created Story SYN-3 - Context Bracket Tracker
  */
 
+const fs = require('fs');
+const path = require('path');
+
 /**
  * Bracket definitions with thresholds and token budgets.
  *
@@ -51,11 +54,84 @@ const XML_SAFETY_MULTIPLIER = 1.2;
 
 /**
  * Default configuration values.
+ * maxContext is the fallback when core-config.yaml is unavailable.
  */
-const DEFAULTS = {
+const DEFAULTS = Object.freeze({
   avgTokensPerPrompt: 1500,
   maxContext: 200000,
-};
+});
+
+/** Cache for model config by project root (read once per root per process). */
+const _modelConfigCache = new Map();
+
+function cloneModelConfig(config) {
+  return { ...config };
+}
+
+function cacheModelConfig(root, config) {
+  const cachedConfig = Object.freeze(cloneModelConfig(config));
+  _modelConfigCache.set(root, cachedConfig);
+  return cloneModelConfig(cachedConfig);
+}
+
+function isPositiveFiniteNumber(value) {
+  return Number.isFinite(value) && value > 0;
+}
+
+/**
+ * Resolve the project root used for model config lookup.
+ *
+ * @param {string|null} basePath - Optional project root override
+ * @returns {string}
+ */
+function resolveConfigRoot(basePath) {
+  return path.resolve(basePath || path.resolve(__dirname, '..', '..', '..', '..'));
+}
+
+/**
+ * Read model configuration from core-config.yaml → models section.
+ * Returns { contextWindow, avgTokensPerPrompt } for the active model.
+ * Falls back to DEFAULTS if config is missing or malformed.
+ *
+ * @param {string|null} [basePath=null] - Project root override (defaults to __dirname-based resolution)
+ * @returns {{ maxContext: number, avgTokensPerPrompt: number }}
+ */
+function getModelConfig(basePath = null) {
+  const root = resolveConfigRoot(basePath);
+  if (_modelConfigCache.has(root)) return cloneModelConfig(_modelConfigCache.get(root));
+
+  try {
+    const yaml = require('js-yaml');
+    const configPath = path.join(root, '.sinapse-ai', 'core-config.yaml');
+    if (!fs.existsSync(configPath)) {
+      return cacheModelConfig(root, DEFAULTS);
+    }
+
+    const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+    const models = config && config.models;
+    if (!models || !models.registry || !models.active) {
+      return cacheModelConfig(root, DEFAULTS);
+    }
+
+    const activeModel = models.registry[models.active];
+    if (!activeModel || !isPositiveFiniteNumber(activeModel.contextWindow)) {
+      return cacheModelConfig(root, DEFAULTS);
+    }
+
+    const modelConfig = {
+      maxContext: activeModel.contextWindow,
+      avgTokensPerPrompt: isPositiveFiniteNumber(activeModel.avgTokensPerPrompt)
+        ? activeModel.avgTokensPerPrompt
+        : DEFAULTS.avgTokensPerPrompt,
+    };
+    return cacheModelConfig(root, modelConfig);
+  } catch (err) {
+    if (process.env.DEBUG || process.env.SINAPSE_DEBUG) {
+      console.warn('[context-tracker] Failed to load model config, using defaults:', err.message);
+    }
+    return cacheModelConfig(root, DEFAULTS);
+  }
+}
 
 /**
  * Layer configurations per bracket.
@@ -101,16 +177,20 @@ function calculateBracket(contextPercent) {
  * Formula: 100 - ((promptCount * avgTokensPerPrompt) / maxContext * 100)
  * Result is clamped to 0-100 range.
  *
+ * Reads maxContext and avgTokensPerPrompt from core-config.yaml → models.registry
+ * for the active model. Options parameter can override for testing.
+ *
  * @param {number} promptCount - Number of prompts in current session
- * @param {Object} [options={}] - Configuration options
- * @param {number} [options.avgTokensPerPrompt=1500] - Average tokens per prompt
- * @param {number} [options.maxContext=200000] - Maximum context window size in tokens
+ * @param {Object} [options={}] - Configuration options (override config values)
+ * @param {number} [options.avgTokensPerPrompt] - Average tokens per prompt
+ * @param {number} [options.maxContext] - Maximum context window size in tokens
  * @returns {number} Percentage of context remaining (0.0 to 100.0)
  */
 function estimateContextPercent(promptCount, options = {}) {
+  const modelConfig = getModelConfig();
   const {
-    avgTokensPerPrompt = DEFAULTS.avgTokensPerPrompt,
-    maxContext = DEFAULTS.maxContext,
+    avgTokensPerPrompt = modelConfig.avgTokensPerPrompt,
+    maxContext = modelConfig.maxContext,
   } = options;
 
   if (typeof promptCount !== 'number' || isNaN(promptCount) || promptCount < 0) {
@@ -184,6 +264,19 @@ function needsMemoryHints(bracket) {
   return bracket === 'DEPLETED' || bracket === 'CRITICAL';
 }
 
+/**
+ * Reset the model config cache. Useful for tests or after config changes.
+ *
+ * @param {string|null} [basePath=null] - Optional project root override
+ */
+function resetModelConfigCache(basePath = null) {
+  if (basePath === null) {
+    _modelConfigCache.clear();
+    return;
+  }
+  _modelConfigCache.delete(resolveConfigRoot(basePath));
+}
+
 module.exports = {
   calculateBracket,
   estimateContextPercent,
@@ -191,6 +284,8 @@ module.exports = {
   getActiveLayers,
   needsHandoffWarning,
   needsMemoryHints,
+  getModelConfig,
+  resetModelConfigCache,
   BRACKETS,
   TOKEN_BUDGETS,
   DEFAULTS,

package/.sinapse-ai/core/synapse/context/index.js

@@ -0,0 +1,19 @@
+/**
+ * SYNAPSE context runtime exports.
+ *
+ * @module core/synapse/context
+ */
+
+'use strict';
+
+const path = require('path');
+
+const contextTracker = require(path.resolve(__dirname, './context-tracker.js'));
+const contextBuilder = require(path.resolve(__dirname, './context-builder.js'));
+const semanticHandshake = require(path.resolve(__dirname, './semantic-handshake-engine.js'));
+
+module.exports = {
+  ...contextTracker,
+  ...contextBuilder,
+  ...semanticHandshake,
+};