agentic-qe 3.7.20 → 3.7.21

package/dist/routing/agent-dependency-graph.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Agent Dependency Graph (Issue #342, Item 2)
+ *
+ * Parses agent .md frontmatter for structured dependency declarations
+ * and builds a dependency graph for spawn ordering and validation.
+ *
+ * Dependency types (from Skillsmith pattern):
+ * - hard: Required. Warn if missing but don't block (advisory philosophy).
+ * - soft: Nice-to-have. Advisory warning only.
+ * - peer: Works alongside. Informational.
+ */
+export type DependencyType = 'hard' | 'soft' | 'peer';
+export interface AgentDependency {
+    readonly name: string;
+    readonly type: DependencyType;
+    readonly reason: string;
+}
+export interface McpServerDependency {
+    readonly name: string;
+    readonly required: boolean;
+}
+export interface ModelRequirement {
+    readonly minimum?: string;
+    readonly capabilities?: string[];
+}
+export interface AgentDependencies {
+    readonly agents?: AgentDependency[];
+    readonly mcpServers?: McpServerDependency[];
+    readonly models?: ModelRequirement;
+}
+export interface DependencyNode {
+    readonly agentName: string;
+    readonly hardDeps: string[];
+    readonly softDeps: string[];
+    readonly peerDeps: string[];
+    readonly dependencies: AgentDependencies;
+}
+export interface DependencyGraphResult {
+    readonly nodes: Map<string, DependencyNode>;
+    readonly spawnOrder: string[];
+    readonly cycles: string[][];
+    readonly warnings: string[];
+}
+export interface SpawnPlan {
+    readonly phases: string[][];
+    readonly unsatisfiedHardDeps: Array<{
+        agent: string;
+        missing: string[];
+    }>;
+    readonly warnings: string[];
+}
+/**
+ * Parse structured dependency declarations from agent frontmatter.
+ * Uses a state-machine: reads lines, tracks current section, builds objects.
+ */
+export declare function parseDependenciesFromFrontmatter(content: string): AgentDependencies | null;
+/**
+ * Build a dependency graph from all qe-*.md agent files in a directory.
+ * Reads frontmatter, parses dependencies, detects cycles, computes topo sort.
+ */
+export declare function buildDependencyGraph(agentsDir: string): DependencyGraphResult;
+/**
+ * Create a spawn plan for a set of agents, respecting dependencies.
+ * Groups into ordered phases (parallel within each phase).
+ * Advisory philosophy: unsatisfied hard deps warn but don't block.
+ */
+export declare function createSpawnPlan(agentNames: string[], graph: DependencyGraphResult): SpawnPlan;
+/**
+ * Get all transitive dependencies for a given agent.
+ * Follows the graph recursively, collecting hard, soft, and peer deps.
+ */
+export declare function getAgentDependencies(agentName: string, graph: DependencyGraphResult): {
+    hardDeps: string[];
+    softDeps: string[];
+    peerDeps: string[];
+};
+//# sourceMappingURL=agent-dependency-graph.d.ts.map

package/dist/routing/agent-dependency-graph.js

@@ -0,0 +1,359 @@
+/**
+ * Agent Dependency Graph (Issue #342, Item 2)
+ *
+ * Parses agent .md frontmatter for structured dependency declarations
+ * and builds a dependency graph for spawn ordering and validation.
+ *
+ * Dependency types (from Skillsmith pattern):
+ * - hard: Required. Warn if missing but don't block (advisory philosophy).
+ * - soft: Nice-to-have. Advisory warning only.
+ * - peer: Works alongside. Informational.
+ */
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join, basename } from 'path';
+// ============================================================================
+// Frontmatter Parsing
+// ============================================================================
+/** Extract YAML frontmatter content between --- markers. */
+function extractFrontmatter(content) {
+    const lines = content.split('\n');
+    if (lines.length < 2 || lines[0].trim() !== '---')
+        return null;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---')
+            return lines.slice(1, i).join('\n');
+    }
+    return null;
+}
+/** Parse a simple YAML value, stripping surrounding quotes. */
+function parseYamlValue(raw) {
+    const t = raw.trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+/**
+ * Parse structured dependency declarations from agent frontmatter.
+ * Uses a state-machine: reads lines, tracks current section, builds objects.
+ */
+export function parseDependenciesFromFrontmatter(content) {
+    const frontmatter = extractFrontmatter(content);
+    if (!frontmatter)
+        return null;
+    const lines = frontmatter.split('\n');
+    let depsStart = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^dependencies:\s*$/.test(lines[i])) {
+            depsStart = i + 1;
+            break;
+        }
+    }
+    if (depsStart === -1)
+        return null;
+    const depsLines = [];
+    for (let i = depsStart; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '')
+            continue;
+        if (line.length > 0 && line[0] !== ' ' && line[0] !== '\t')
+            break;
+        depsLines.push(line);
+    }
+    if (depsLines.length === 0)
+        return null;
+    const result = {};
+    const st = { section: 'none', item: {}, inList: false };
+    const flushAgent = () => {
+        if (!st.item.name)
+            return;
+        if (!result.agents)
+            result.agents = [];
+        result.agents.push({ name: st.item.name, type: st.item.type || 'hard', reason: st.item.reason || '' });
+        st.item = {};
+    };
+    const flushMcp = () => {
+        if (!st.item.name)
+            return;
+        if (!result.mcpServers)
+            result.mcpServers = [];
+        result.mcpServers.push({ name: st.item.name, required: st.item.required === 'true' });
+        st.item = {};
+    };
+    for (const line of depsLines) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        const secMatch = trimmed.match(/^(agents|mcp_servers|models):\s*$/);
+        if (secMatch) {
+            if (st.section === 'agents' && st.inList)
+                flushAgent();
+            if (st.section === 'mcp_servers' && st.inList)
+                flushMcp();
+            st.inList = false;
+            st.section = secMatch[1];
+            continue;
+        }
+        if (st.section === 'agents' || st.section === 'mcp_servers') {
+            const listStart = trimmed.match(/^-\s+(\w+):\s*(.*)$/);
+            if (listStart) {
+                if (st.inList) {
+                    st.section === 'agents' ? flushAgent() : flushMcp();
+                }
+                st.inList = true;
+                st.item = { [listStart[1]]: parseYamlValue(listStart[2]) };
+                continue;
+            }
+            if (st.inList) {
+                const kv = trimmed.match(/^(\w+):\s*(.*)$/);
+                if (kv) {
+                    st.item[kv[1]] = parseYamlValue(kv[2]);
+                    continue;
+                }
+            }
+        }
+        if (st.section === 'models') {
+            if (!result.models)
+                result.models = {};
+            const kv = trimmed.match(/^(\w+):\s*(.*)$/);
+            if (kv) {
+                const val = parseYamlValue(kv[2]);
+                if (kv[1] === 'minimum')
+                    result.models = { ...result.models, minimum: val };
+                else if (kv[1] === 'capabilities') {
+                    const arr = val.match(/^\[(.+)]$/);
+                    if (arr)
+                        result.models = { ...result.models, capabilities: arr[1].split(',').map(s => parseYamlValue(s.trim())) };
+                }
+            }
+            const li = trimmed.match(/^-\s+(.+)$/);
+            if (li && result.models) {
+                const caps = result.models.capabilities || [];
+                result.models = { ...result.models, capabilities: [...caps, parseYamlValue(li[1])] };
+            }
+        }
+    }
+    if (st.section === 'agents' && st.inList)
+        flushAgent();
+    if (st.section === 'mcp_servers' && st.inList)
+        flushMcp();
+    if (!result.agents && !result.mcpServers && !result.models)
+        return null;
+    return result;
+}
+// ============================================================================
+// Graph Building
+// ============================================================================
+function extractAgentName(content) {
+    const fm = extractFrontmatter(content);
+    if (!fm)
+        return null;
+    for (const line of fm.split('\n')) {
+        const m = line.match(/^name:\s*(.+)$/);
+        if (m)
+            return parseYamlValue(m[1]);
+    }
+    return null;
+}
+/**
+ * Build a dependency graph from all qe-*.md agent files in a directory.
+ * Reads frontmatter, parses dependencies, detects cycles, computes topo sort.
+ */
+export function buildDependencyGraph(agentsDir) {
+    const nodes = new Map();
+    const warnings = [];
+    if (!existsSync(agentsDir)) {
+        warnings.push(`Agents directory not found: ${agentsDir}`);
+        return { nodes, spawnOrder: [], cycles: [], warnings };
+    }
+    const files = readdirSync(agentsDir).filter(f => f.startsWith('qe-') && f.endsWith('.md'));
+    for (const file of files) {
+        let content;
+        try {
+            content = readFileSync(join(agentsDir, file), 'utf-8');
+        }
+        catch {
+            warnings.push(`Failed to read agent file: ${file}`);
+            continue;
+        }
+        const agentName = extractAgentName(content) || basename(file, '.md');
+        const deps = parseDependenciesFromFrontmatter(content);
+        const hardDeps = [], softDeps = [], peerDeps = [];
+        if (deps?.agents) {
+            for (const dep of deps.agents) {
+                if (dep.type === 'hard')
+                    hardDeps.push(dep.name);
+                else if (dep.type === 'soft')
+                    softDeps.push(dep.name);
+                else if (dep.type === 'peer')
+                    peerDeps.push(dep.name);
+            }
+        }
+        nodes.set(agentName, { agentName, hardDeps, softDeps, peerDeps, dependencies: deps || {} });
+    }
+    // Warn about missing hard deps
+    const allNames = new Set(nodes.keys());
+    for (const [name, node] of nodes) {
+        for (const dep of node.hardDeps) {
+            if (!allNames.has(dep)) {
+                warnings.push(`Agent "${name}" declares hard dependency on "${dep}" which is not in the agent directory`);
+            }
+        }
+    }
+    const cycles = detectCycles(nodes);
+    for (const cycle of cycles)
+        warnings.push(`Dependency cycle detected: ${cycle.join(' -> ')}`);
+    return { nodes, spawnOrder: topologicalSort(nodes, cycles), cycles, warnings };
+}
+/** Detect cycles in the hard-dependency graph using DFS. */
+function detectCycles(nodes) {
+    const cycles = [];
+    const visited = new Set();
+    const stack = new Set();
+    const path = [];
+    function dfs(name) {
+        visited.add(name);
+        stack.add(name);
+        path.push(name);
+        const node = nodes.get(name);
+        if (node) {
+            for (const dep of node.hardDeps) {
+                if (!visited.has(dep) && nodes.has(dep))
+                    dfs(dep);
+                else if (stack.has(dep)) {
+                    const start = path.indexOf(dep);
+                    if (start !== -1)
+                        cycles.push([...path.slice(start), dep]);
+                }
+            }
+        }
+        path.pop();
+        stack.delete(name);
+    }
+    for (const name of nodes.keys()) {
+        if (!visited.has(name))
+            dfs(name);
+    }
+    return cycles;
+}
+/** Topological sort respecting hard deps. Cycle agents placed at end. */
+function topologicalSort(nodes, cycles) {
+    const cycleAgents = new Set(cycles.flat());
+    const sorted = [];
+    const visited = new Set();
+    const temp = new Set();
+    function visit(name) {
+        if (visited.has(name) || cycleAgents.has(name) || temp.has(name))
+            return;
+        temp.add(name);
+        const node = nodes.get(name);
+        if (node) {
+            for (const dep of node.hardDeps) {
+                if (nodes.has(dep))
+                    visit(dep);
+            }
+        }
+        temp.delete(name);
+        visited.add(name);
+        sorted.push(name);
+    }
+    for (const name of nodes.keys())
+        visit(name);
+    for (const agent of cycleAgents) {
+        if (!sorted.includes(agent))
+            sorted.push(agent);
+    }
+    return sorted;
+}
+// ============================================================================
+// Spawn Planning
+// ============================================================================
+/**
+ * Create a spawn plan for a set of agents, respecting dependencies.
+ * Groups into ordered phases (parallel within each phase).
+ * Advisory philosophy: unsatisfied hard deps warn but don't block.
+ */
+export function createSpawnPlan(agentNames, graph) {
+    const requested = new Set(agentNames);
+    const warnings = [];
+    const unsatisfiedHardDeps = [];
+    for (const name of agentNames) {
+        const node = graph.nodes.get(name);
+        if (!node)
+            continue;
+        const missing = node.hardDeps.filter(d => !requested.has(d));
+        if (missing.length > 0) {
+            unsatisfiedHardDeps.push({ agent: name, missing });
+            warnings.push(`Advisory: "${name}" has unsatisfied hard dependencies: ${missing.join(', ')}. Proceeding anyway.`);
+        }
+    }
+    const phases = [];
+    const placed = new Set();
+    let remaining = new Set(agentNames);
+    while (remaining.size > 0) {
+        const phase = [];
+        for (const name of remaining) {
+            const node = graph.nodes.get(name);
+            if (!node) {
+                phase.push(name);
+                continue;
+            }
+            const inScopeHard = node.hardDeps.filter(d => requested.has(d));
+            if (inScopeHard.every(d => placed.has(d)))
+                phase.push(name);
+        }
+        if (phase.length === 0) {
+            warnings.push(`Could not resolve dependency ordering for: ${[...remaining].join(', ')}. Placing in final phase.`);
+            phases.push([...remaining]);
+            break;
+        }
+        phases.push(phase);
+        for (const a of phase) {
+            placed.add(a);
+            remaining.delete(a);
+        }
+        remaining = new Set([...remaining]);
+    }
+    return { phases, unsatisfiedHardDeps, warnings };
+}
+// ============================================================================
+// Transitive Dependency Resolution
+// ============================================================================
+/**
+ * Get all transitive dependencies for a given agent.
+ * Follows the graph recursively, collecting hard, soft, and peer deps.
+ */
+export function getAgentDependencies(agentName, graph) {
+    const hard = new Set();
+    const soft = new Set();
+    const peer = new Set();
+    const visited = new Set();
+    function collect(name, transitive) {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        const node = graph.nodes.get(name);
+        if (!node)
+            return;
+        for (const dep of node.hardDeps) {
+            if (dep !== agentName) {
+                hard.add(dep);
+                collect(dep, true);
+            }
+        }
+        for (const dep of node.softDeps) {
+            if (dep !== agentName && !hard.has(dep)) {
+                soft.add(dep);
+                if (!transitive)
+                    collect(dep, true);
+            }
+        }
+        for (const dep of node.peerDeps) {
+            if (dep !== agentName && !hard.has(dep) && !soft.has(dep))
+                peer.add(dep);
+        }
+    }
+    collect(agentName, false);
+    return { hardDeps: [...hard], softDeps: [...soft], peerDeps: [...peer] };
+}
+//# sourceMappingURL=agent-dependency-graph.js.map

package/dist/routing/co-execution-repository.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Co-Execution Repository (Issue #342, Item 3)
+ *
+ * Tracks which agent combinations succeed together on similar tasks.
+ * Behavioral confidence ramps linearly: min(1.0, success_count / 20).
+ * A single co-execution registers at 0.05; twenty successes reach full confidence.
+ */
+import type { Database as DatabaseType } from 'better-sqlite3';
+/** A record of two agents executing together on a task */
+export interface CoExecutionRecord {
+    /** First agent ID */
+    readonly agentA: string;
+    /** Second agent ID */
+    readonly agentB: string;
+    /** Task domain */
+    readonly domain: string;
+    /** Whether the co-execution was successful */
+    readonly success: boolean;
+    /** Optional task description (truncated) */
+    readonly taskDescription?: string;
+}
+/** Co-execution statistics for an agent pair */
+export interface CoExecutionStats {
+    /** First agent */
+    readonly agentA: string;
+    /** Second agent */
+    readonly agentB: string;
+    /** Total co-executions */
+    readonly totalExecutions: number;
+    /** Successful co-executions */
+    readonly successCount: number;
+    /** Success rate */
+    readonly successRate: number;
+    /** Behavioral confidence: min(1.0, successCount / 20) */
+    readonly behavioralConfidence: number;
+}
+export declare class CoExecutionRepository {
+    private db;
+    private initialized;
+    /**
+     * Initialize with a database connection.
+     * Creates the co-execution table if it doesn't exist.
+     */
+    initialize(db: DatabaseType): void;
+    /**
+     * Record a co-execution event between two agents.
+     * Agent order is normalized (sorted) so A-B and B-A are the same pair.
+     */
+    recordCoExecution(record: CoExecutionRecord): void;
+    /**
+     * Get co-execution stats for a specific agent pair.
+     * Returns behavioral confidence using linear ramp: min(1.0, successCount / 20).
+     */
+    getCoExecutionStats(agentA: string, agentB: string): CoExecutionStats | null;
+    /**
+     * Get all agents that have successfully co-executed with the given agent.
+     * Returns them sorted by behavioral confidence (descending).
+     */
+    getCoExecutionPartners(agentId: string, limit?: number): CoExecutionStats[];
+    /**
+     * Record a batch of co-executions from a swarm task.
+     * Given a list of agents that participated in a task together,
+     * records co-execution for every unique pair.
+     */
+    recordSwarmCoExecution(agentIds: string[], domain: string, success: boolean, taskDescription?: string): void;
+}
+export declare function getCoExecutionRepository(): CoExecutionRepository;
+//# sourceMappingURL=co-execution-repository.d.ts.map

package/dist/routing/co-execution-repository.js

@@ -0,0 +1,184 @@
+/**
+ * Co-Execution Repository (Issue #342, Item 3)
+ *
+ * Tracks which agent combinations succeed together on similar tasks.
+ * Behavioral confidence ramps linearly: min(1.0, success_count / 20).
+ * A single co-execution registers at 0.05; twenty successes reach full confidence.
+ */
+import { toErrorMessage } from '../shared/error-utils.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Number of successes needed for full behavioral confidence */
+const CONFIDENCE_RAMP_THRESHOLD = 20;
+// ============================================================================
+// Repository
+// ============================================================================
+export class CoExecutionRepository {
+    db = null;
+    initialized = false;
+    /**
+     * Initialize with a database connection.
+     * Creates the co-execution table if it doesn't exist.
+     */
+    initialize(db) {
+        if (this.initialized)
+            return;
+        this.db = db;
+        try {
+            this.db.exec(`
+        CREATE TABLE IF NOT EXISTS qe_agent_co_execution (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          agent_a TEXT NOT NULL,
+          agent_b TEXT NOT NULL,
+          domain TEXT NOT NULL,
+          success INTEGER NOT NULL DEFAULT 0,
+          task_description TEXT,
+          created_at TEXT DEFAULT (datetime('now'))
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_co_exec_agents
+          ON qe_agent_co_execution(agent_a, agent_b);
+        CREATE INDEX IF NOT EXISTS idx_co_exec_domain
+          ON qe_agent_co_execution(domain);
+      `);
+            this.initialized = true;
+        }
+        catch (error) {
+            console.error(`[CoExecutionRepository] Init error: ${toErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Record a co-execution event between two agents.
+     * Agent order is normalized (sorted) so A-B and B-A are the same pair.
+     */
+    recordCoExecution(record) {
+        if (!this.db)
+            return;
+        const [a, b] = [record.agentA, record.agentB].sort();
+        try {
+            this.db.prepare(`
+        INSERT INTO qe_agent_co_execution (agent_a, agent_b, domain, success, task_description)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(a, b, record.domain, record.success ? 1 : 0, record.taskDescription?.slice(0, 500) || null);
+        }
+        catch (error) {
+            console.debug(`[CoExecutionRepository] Record error: ${toErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Get co-execution stats for a specific agent pair.
+     * Returns behavioral confidence using linear ramp: min(1.0, successCount / 20).
+     */
+    getCoExecutionStats(agentA, agentB) {
+        if (!this.db)
+            return null;
+        const [a, b] = [agentA, agentB].sort();
+        try {
+            const row = this.db.prepare(`
+        SELECT
+          agent_a,
+          agent_b,
+          COUNT(*) as total_executions,
+          SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count
+        FROM qe_agent_co_execution
+        WHERE agent_a = ? AND agent_b = ?
+        GROUP BY agent_a, agent_b
+      `).get(a, b);
+            if (!row)
+                return null;
+            const successRate = row.total_executions > 0
+                ? row.success_count / row.total_executions
+                : 0;
+            // Linear ramp: min(1.0, successCount / 20)
+            const behavioralConfidence = Math.min(1.0, row.success_count / CONFIDENCE_RAMP_THRESHOLD);
+            return {
+                agentA: row.agent_a,
+                agentB: row.agent_b,
+                totalExecutions: row.total_executions,
+                successCount: row.success_count,
+                successRate,
+                behavioralConfidence,
+            };
+        }
+        catch (error) {
+            console.debug(`[CoExecutionRepository] Stats error: ${toErrorMessage(error)}`);
+            return null;
+        }
+    }
+    /**
+     * Get all agents that have successfully co-executed with the given agent.
+     * Returns them sorted by behavioral confidence (descending).
+     */
+    getCoExecutionPartners(agentId, limit = 10) {
+        if (!this.db)
+            return [];
+        try {
+            const rows = this.db.prepare(`
+        SELECT
+          agent_a,
+          agent_b,
+          COUNT(*) as total_executions,
+          SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count
+        FROM qe_agent_co_execution
+        WHERE agent_a = ? OR agent_b = ?
+        GROUP BY agent_a, agent_b
+        ORDER BY success_count DESC
+        LIMIT ?
+      `).all(agentId, agentId, limit);
+            return rows.map(row => {
+                const successRate = row.total_executions > 0
+                    ? row.success_count / row.total_executions
+                    : 0;
+                return {
+                    agentA: row.agent_a,
+                    agentB: row.agent_b,
+                    totalExecutions: row.total_executions,
+                    successCount: row.success_count,
+                    successRate,
+                    behavioralConfidence: Math.min(1.0, row.success_count / CONFIDENCE_RAMP_THRESHOLD),
+                };
+            });
+        }
+        catch (error) {
+            console.debug(`[CoExecutionRepository] Partners error: ${toErrorMessage(error)}`);
+            return [];
+        }
+    }
+    /**
+     * Record a batch of co-executions from a swarm task.
+     * Given a list of agents that participated in a task together,
+     * records co-execution for every unique pair.
+     */
+    recordSwarmCoExecution(agentIds, domain, success, taskDescription) {
+        if (!this.db || agentIds.length < 2)
+            return;
+        try {
+            const insert = this.db.prepare(`
+        INSERT INTO qe_agent_co_execution (agent_a, agent_b, domain, success, task_description)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+            const transaction = this.db.transaction(() => {
+                for (let i = 0; i < agentIds.length; i++) {
+                    for (let j = i + 1; j < agentIds.length; j++) {
+                        const [a, b] = [agentIds[i], agentIds[j]].sort();
+                        insert.run(a, b, domain, success ? 1 : 0, taskDescription?.slice(0, 500) || null);
+                    }
+                }
+            });
+            transaction();
+        }
+        catch (error) {
+            console.debug(`[CoExecutionRepository] Swarm record error: ${toErrorMessage(error)}`);
+        }
+    }
+}
+/** Singleton instance */
+let _instance = null;
+export function getCoExecutionRepository() {
+    if (!_instance) {
+        _instance = new CoExecutionRepository();
+    }
+    return _instance;
+}
+//# sourceMappingURL=co-execution-repository.js.map