aios-core 4.2.5 → 4.2.7

package/.aios-core/core/code-intel/providers/code-graph-provider.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const { CodeIntelProvider } = require('./provider-interface');
+
+/**
+ * Code Graph MCP tool name mapping.
+ * Maps abstract capabilities to Code Graph MCP tool names.
+ */
+const TOOL_MAP = {
+  findDefinition: 'find_definition',
+  findReferences: 'find_references',
+  findCallers: 'find_callers',
+  findCallees: 'find_callees',
+  analyzeDependencies: 'dependency_analysis',
+  analyzeComplexity: 'complexity_analysis',
+  analyzeCodebase: 'analyze_codebase',
+  getProjectStats: 'project_statistics',
+};
+
+/**
+ * CodeGraphProvider — Adapter for Code Graph MCP server.
+ *
+ * Translates the 8 abstract capabilities into Code Graph MCP tool calls.
+ * Normalizes responses to match the provider-interface contract.
+ */
+class CodeGraphProvider extends CodeIntelProvider {
+  constructor(options = {}) {
+    super('code-graph', options);
+    this._mcpServerName = options.mcpServerName || 'code-graph';
+  }
+
+  /**
+   * Execute an MCP tool call via the configured server.
+   * This method is the single point of MCP communication — all capabilities route through here.
+   *
+   * @param {string} toolName - MCP tool name (e.g. 'find_definition')
+   * @param {Object} params - Tool parameters
+   * @returns {Promise<Object|null>} Tool result or null on failure
+   * @private
+   */
+  async _callMcpTool(toolName, params = {}) {
+    // MCP tool calls are executed via the Claude Code MCP protocol.
+    // In production, this is invoked by the Claude Code runtime.
+    // For testing, this method is mocked.
+    //
+    // The actual MCP call signature:
+    //   mcp__<server>__<tool>(params)
+    //
+    // Since we run inside Claude Code agent context, the MCP call
+    // is abstracted. Consumers of this module use the client layer
+    // which handles the actual invocation.
+
+    if (typeof this.options.mcpCallFn === 'function') {
+      return await this.options.mcpCallFn(this._mcpServerName, toolName, params);
+    }
+
+    // No MCP call function configured — provider cannot operate
+    return null;
+  }
+
+  async findDefinition(symbol, options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.findDefinition, {
+      symbol,
+      ...options,
+    });
+    return this._normalizeDefinitionResult(result);
+  }
+
+  async findReferences(symbol, options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.findReferences, {
+      symbol,
+      ...options,
+    });
+    return this._normalizeReferencesResult(result);
+  }
+
+  async findCallers(symbol, options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.findCallers, {
+      symbol,
+      ...options,
+    });
+    return this._normalizeCallersResult(result);
+  }
+
+  async findCallees(symbol, options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.findCallees, {
+      symbol,
+      ...options,
+    });
+    return this._normalizeCalleesResult(result);
+  }
+
+  async analyzeDependencies(path, options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.analyzeDependencies, {
+      path,
+      ...options,
+    });
+    return this._normalizeDependenciesResult(result);
+  }
+
+  async analyzeComplexity(path, options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.analyzeComplexity, {
+      path,
+      ...options,
+    });
+    return this._normalizeComplexityResult(result);
+  }
+
+  async analyzeCodebase(path, options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.analyzeCodebase, {
+      path,
+      ...options,
+    });
+    return this._normalizeCodebaseResult(result);
+  }
+
+  async getProjectStats(options = {}) {
+    const result = await this._callMcpTool(TOOL_MAP.getProjectStats, options);
+    return this._normalizeStatsResult(result);
+  }
+
+  // --- Normalization helpers ---
+  // Normalize MCP responses to provider-interface contract format.
+  // If result is null/undefined, return null (fallback).
+
+  _normalizeDefinitionResult(result) {
+    if (!result) return null;
+    return {
+      file: result.file ?? result.path ?? null,
+      line: result.line != null ? result.line : (result.row != null ? result.row : null),
+      column: result.column != null ? result.column : (result.col != null ? result.col : null),
+      context: result.context || result.snippet || null,
+    };
+  }
+
+  _normalizeReferencesResult(result) {
+    if (!result) return null;
+    const items = Array.isArray(result) ? result : result.references || result.results || [];
+    return items.map((r) => ({
+      file: r.file ?? r.path ?? null,
+      line: r.line != null ? r.line : (r.row != null ? r.row : null),
+      context: r.context || r.snippet || null,
+    }));
+  }
+
+  _normalizeCallersResult(result) {
+    if (!result) return null;
+    const items = Array.isArray(result) ? result : result.callers || result.results || [];
+    return items.map((r) => ({
+      caller: r.caller || r.name || null,
+      file: r.file ?? r.path ?? null,
+      line: r.line != null ? r.line : (r.row != null ? r.row : null),
+    }));
+  }
+
+  _normalizeCalleesResult(result) {
+    if (!result) return null;
+    const items = Array.isArray(result) ? result : result.callees || result.results || [];
+    return items.map((r) => ({
+      callee: r.callee || r.name || null,
+      file: r.file ?? r.path ?? null,
+      line: r.line != null ? r.line : (r.row != null ? r.row : null),
+    }));
+  }
+
+  _normalizeDependenciesResult(result) {
+    if (!result) return null;
+    return {
+      nodes: result.nodes || result.files || [],
+      edges: result.edges || result.dependencies || [],
+    };
+  }
+
+  _normalizeComplexityResult(result) {
+    if (!result) return null;
+    return {
+      score: result.score != null ? result.score : (result.complexity != null ? result.complexity : 0),
+      details: result.details || result.metrics || {},
+    };
+  }
+
+  _normalizeCodebaseResult(result) {
+    if (!result) return null;
+    return {
+      files: result.files || [],
+      structure: result.structure || {},
+      patterns: result.patterns || [],
+    };
+  }
+
+  _normalizeStatsResult(result) {
+    if (!result) return null;
+    return {
+      files: result.files != null ? result.files : (result.total_files != null ? result.total_files : 0),
+      lines: result.lines != null ? result.lines : (result.total_lines != null ? result.total_lines : 0),
+      languages: result.languages || {},
+    };
+  }
+}
+
+module.exports = { CodeGraphProvider, TOOL_MAP };

package/.aios-core/core/code-intel/providers/provider-interface.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * CodeIntelProvider — Abstract base class for all code intelligence providers.
+ *
+ * Every provider MUST extend this class and implement all 8 primitive capabilities.
+ * Default implementations return null (graceful fallback built-in).
+ *
+ * @abstract
+ */
+class CodeIntelProvider {
+  constructor(name, options = {}) {
+    this.name = name;
+    this.options = options;
+  }
+
+  /**
+   * Locate the definition of a symbol.
+   * @param {string} symbol - Symbol name to find
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<{file: string, line: number, column: number, context: string}|null>}
+   */
+  async findDefinition(_symbol, _options) {
+    return null;
+  }
+
+  /**
+   * Find all references (usages) of a symbol.
+   * @param {string} symbol - Symbol name to search
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<Array<{file: string, line: number, context: string}>|null>}
+   */
+  async findReferences(_symbol, _options) {
+    return null;
+  }
+
+  /**
+   * Find all callers of a function/method.
+   * @param {string} symbol - Function/method name
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<Array<{caller: string, file: string, line: number}>|null>}
+   */
+  async findCallers(_symbol, _options) {
+    return null;
+  }
+
+  /**
+   * Find all callees (functions called by) a function/method.
+   * @param {string} symbol - Function/method name
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<Array<{callee: string, file: string, line: number}>|null>}
+   */
+  async findCallees(_symbol, _options) {
+    return null;
+  }
+
+  /**
+   * Analyze dependency graph for a file or directory.
+   * @param {string} path - File or directory path
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<{nodes: Array, edges: Array}|null>}
+   */
+  async analyzeDependencies(_path, _options) {
+    return null;
+  }
+
+  /**
+   * Analyze code complexity metrics.
+   * @param {string} path - File or directory path
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<{score: number, details: Object}|null>}
+   */
+  async analyzeComplexity(_path, _options) {
+    return null;
+  }
+
+  /**
+   * Analyze codebase structure, files and patterns.
+   * @param {string} path - Root path to analyze
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<{files: Array, structure: Object, patterns: Array}|null>}
+   */
+  async analyzeCodebase(_path, _options) {
+    return null;
+  }
+
+  /**
+   * Get project-level statistics.
+   * @param {Object} [options] - Provider-specific options
+   * @returns {Promise<{files: number, lines: number, languages: Object}|null>}
+   */
+  async getProjectStats(_options) {
+    return null;
+  }
+}
+
+const CAPABILITIES = [
+  'findDefinition',
+  'findReferences',
+  'findCallers',
+  'findCallees',
+  'analyzeDependencies',
+  'analyzeComplexity',
+  'analyzeCodebase',
+  'getProjectStats',
+];
+
+module.exports = { CodeIntelProvider, CAPABILITIES };

package/.aios-core/core/orchestration/context-manager.js

@@ -32,6 +32,8 @@ class ContextManager {
     // State file path
     this.stateDir = path.join(projectRoot, '.aios', 'workflow-state');
     this.statePath = path.join(this.stateDir, `${workflowId}.json`);
+    this.handoffDir = path.join(this.stateDir, 'handoffs');
+    this.confidenceDir = path.join(this.stateDir, 'confidence');
 
     // In-memory cache
     this._stateCache = null;
@@ -43,6 +45,8 @@ class ContextManager {
    */
   async ensureStateDir() {
     await fs.ensureDir(this.stateDir);
+    await fs.ensureDir(this.handoffDir);
+    await fs.ensureDir(this.confidenceDir);
   }
 
   /**
@@ -76,6 +80,7 @@ class ContextManager {
       phases: {},
       metadata: {
         projectRoot: this.projectRoot,
+        delivery_confidence: null,
       },
     };
   }
@@ -113,19 +118,25 @@ class ContextManager {
    * @param {number} phaseNum - Phase number
    * @param {Object} output - Phase output data
    */
-  async savePhaseOutput(phaseNum, output) {
+  async savePhaseOutput(phaseNum, output, options = {}) {
     const state = await this.loadState();
+    const completedAt = new Date().toISOString();
+    state.currentPhase = phaseNum;
+    state.status = 'in_progress';
+    const handoff = this._buildHandoffPackage(phaseNum, output, state, options, completedAt);
 
     state.phases[phaseNum] = {
       ...output,
-      completedAt: new Date().toISOString(),
+      completedAt,
+      handoff,
     };
-
-    state.currentPhase = phaseNum;
-    state.status = 'in_progress';
+    state.metadata = state.metadata || {};
+    state.metadata.delivery_confidence = this._calculateDeliveryConfidence(state);
 
     this._stateCache = state;
     await this._saveState();
+    await this._saveHandoffFile(handoff);
+    await this._saveConfidenceFile(state.metadata.delivery_confidence);
   }
 
   /**
@@ -145,10 +156,18 @@ class ContextManager {
       }
     }
 
+    const previousHandoffs = {};
+    for (const [phaseId, phaseData] of Object.entries(previousPhases)) {
+      if (phaseData && phaseData.handoff) {
+        previousHandoffs[phaseId] = phaseData.handoff;
+      }
+    }
+
     return {
       workflowId: this.workflowId,
       currentPhase: phaseNum,
       previousPhases,
+      previousHandoffs,
       metadata: state.metadata,
     };
   }
@@ -247,9 +266,318 @@ class ContextManager {
       currentPhase: state.currentPhase,
       completedPhases: phases,
       totalPhases: phases.length,
+      deliveryConfidence: state.metadata?.delivery_confidence || null,
     };
   }
 
+  /**
+   * Get latest delivery confidence score metadata.
+   * @returns {Object|null} Confidence payload
+   */
+  getDeliveryConfidence() {
+    return this._stateCache?.metadata?.delivery_confidence || null;
+  }
+
+  /**
+   * Build standardized handoff package for inter-agent transfer.
+   * @private
+   */
+  _buildHandoffPackage(phaseNum, output, state, options, completedAt) {
+    const handoffTarget = options.handoffTarget || {};
+    const decision = this._extractDecisionLog(output);
+    const evidence = this._extractEvidenceLinks(output);
+    const risks = this._extractOpenRisks(output);
+
+    return {
+      version: '1.0.0',
+      workflow_id: this.workflowId,
+      generated_at: completedAt,
+      from: {
+        phase: phaseNum,
+        agent: output.agent || null,
+        action: output.action || null,
+        task: output.task || null,
+      },
+      to: {
+        phase: handoffTarget.phase || null,
+        agent: handoffTarget.agent || null,
+      },
+      context_snapshot: {
+        workflow_status: state.status,
+        current_phase: state.currentPhase,
+        metadata: state.metadata || {},
+      },
+      decision_log: decision,
+      evidence_links: evidence,
+      open_risks: risks,
+    };
+  }
+
+  /**
+   * Persist handoff package as a dedicated artifact.
+   * @private
+   */
+  async _saveHandoffFile(handoff) {
+    const phase = handoff?.from?.phase || 'unknown';
+    const filePath = path.join(this.handoffDir, `${this.workflowId}-phase-${phase}.handoff.json`);
+    await fs.ensureDir(this.handoffDir);
+    await fs.writeJson(filePath, handoff, { spaces: 2 });
+  }
+
+  /**
+   * Persist confidence score as a dedicated artifact.
+   * @private
+   */
+  async _saveConfidenceFile(confidence) {
+    if (!confidence) return;
+    const filePath = path.join(this.confidenceDir, `${this.workflowId}.delivery-confidence.json`);
+    await fs.ensureDir(this.confidenceDir);
+    await fs.writeJson(filePath, confidence, { spaces: 2 });
+  }
+
+  /**
+   * @private
+   */
+  _extractDecisionLog(output = {}) {
+    const result = output.result || {};
+    const entries = Array.isArray(result.decisions)
+      ? result.decisions
+      : Array.isArray(result.decision_log)
+        ? result.decision_log
+        : [];
+    const sourcePaths = [];
+
+    if (result.decisionLogPath) sourcePaths.push(result.decisionLogPath);
+    if (result.decision_log_path) sourcePaths.push(result.decision_log_path);
+
+    return {
+      entries,
+      source_paths: sourcePaths,
+      count: entries.length,
+    };
+  }
+
+  /**
+   * @private
+   */
+  _extractEvidenceLinks(output = {}) {
+    const evidence = [];
+    const result = output.result || {};
+    const validation = output.validation || {};
+
+    if (Array.isArray(result.evidence_links)) {
+      evidence.push(...result.evidence_links);
+    }
+
+    if (Array.isArray(validation.checks)) {
+      for (const check of validation.checks) {
+        if (check.path) evidence.push(check.path);
+        if (check.checklist) evidence.push(check.checklist);
+      }
+    }
+
+    return [...new Set(evidence)];
+  }
+
+  /**
+   * @private
+   */
+  _extractOpenRisks(output = {}) {
+    const result = output.result || {};
+    const risks = [];
+
+    if (Array.isArray(result.open_risks)) {
+      risks.push(...result.open_risks);
+    }
+    if (Array.isArray(result.risks)) {
+      risks.push(...result.risks);
+    }
+    if (Array.isArray(result.risk_register)) {
+      risks.push(...result.risk_register);
+    }
+
+    return risks;
+  }
+
+  /**
+   * Compute delivery confidence score from workflow state.
+   * @private
+   */
+  _calculateDeliveryConfidence(state) {
+    const phases = Object.values(state.phases || {});
+    const weights = {
+      test_coverage: 0.25,
+      ac_completion: 0.30,
+      risk_score_inv: 0.20,
+      debt_score_inv: 0.15,
+      regression_clear: 0.10,
+    };
+    const components = {
+      test_coverage: this._calculateTestCoverage(phases),
+      ac_completion: this._calculateAcCompletion(phases),
+      risk_score_inv: this._calculateRiskInverseScore(phases),
+      debt_score_inv: this._calculateDebtInverseScore(phases),
+      regression_clear: this._calculateRegressionClear(phases),
+    };
+
+    const scoreBase = Object.keys(weights).reduce(
+      (acc, key) => acc + (components[key] || 0) * weights[key],
+      0,
+    );
+    const score = Number((scoreBase * 100).toFixed(2));
+    const threshold = this._resolveConfidenceThreshold();
+
+    return {
+      version: '1.0.0',
+      calculated_at: new Date().toISOString(),
+      score,
+      threshold,
+      gate_passed: score >= threshold,
+      formula: {
+        expression:
+          'confidence = (test_coverage*0.25 + ac_completion*0.30 + risk_score_inv*0.20 + debt_score_inv*0.15 + regression_clear*0.10) * 100',
+        weights,
+      },
+      components,
+      phase_count: phases.length,
+    };
+  }
+
+  /**
+   * @private
+   */
+  _resolveConfidenceThreshold() {
+    const raw = process.env.AIOS_DELIVERY_CONFIDENCE_THRESHOLD;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : 70;
+  }
+
+  /**
+   * @private
+   */
+  _calculateTestCoverage(phases) {
+    let totalChecks = 0;
+    let passedChecks = 0;
+
+    for (const phase of phases) {
+      const checks = phase?.validation?.checks;
+      if (!Array.isArray(checks)) continue;
+      for (const check of checks) {
+        totalChecks += 1;
+        if (check?.passed === true) passedChecks += 1;
+      }
+    }
+
+    if (totalChecks === 0) {
+      return phases.length > 0 ? 1 : 0;
+    }
+
+    return passedChecks / totalChecks;
+  }
+
+  /**
+   * @private
+   */
+  _calculateAcCompletion(phases) {
+    let total = 0;
+    let done = 0;
+    let hasExplicitData = false;
+
+    for (const phase of phases) {
+      const result = phase?.result || {};
+      if (Number.isFinite(result.ac_total) && Number.isFinite(result.ac_completed)) {
+        hasExplicitData = true;
+        total += Math.max(0, result.ac_total);
+        done += Math.min(Math.max(0, result.ac_completed), Math.max(0, result.ac_total));
+      } else if (Array.isArray(result.acceptance_criteria)) {
+        hasExplicitData = true;
+        total += result.acceptance_criteria.length;
+        done += result.acceptance_criteria.filter((item) => item?.done || item?.status === 'done').length;
+      }
+    }
+
+    if (hasExplicitData && total > 0) {
+      return done / total;
+    }
+
+    if (phases.length === 0) {
+      return 0;
+    }
+
+    const successful = phases.filter((phase) => phase?.result?.status !== 'failed').length;
+    return successful / phases.length;
+  }
+
+  /**
+   * @private
+   */
+  _calculateRiskInverseScore(phases) {
+    const totalRisks = phases.reduce((sum, phase) => {
+      const handoffRisks = Array.isArray(phase?.handoff?.open_risks) ? phase.handoff.open_risks.length : 0;
+      const resultRisks = this._extractOpenRisks(phase).length;
+      return sum + Math.max(handoffRisks, resultRisks);
+    }, 0);
+
+    return Math.max(0, 1 - totalRisks / 10);
+  }
+
+  /**
+   * @private
+   */
+  _calculateDebtInverseScore(phases) {
+    const totalDebt = phases.reduce((sum, phase) => {
+      const result = phase?.result || {};
+      const explicitCount = Number.isFinite(result.technical_debt_count)
+        ? result.technical_debt_count
+        : Number.isFinite(result.debt_count)
+          ? result.debt_count
+          : 0;
+      const listCount = [
+        result.technical_debt,
+        result.debt_items,
+        result.todos,
+        result.hacks,
+      ].reduce((listSum, list) => listSum + (Array.isArray(list) ? list.length : 0), 0);
+      return sum + explicitCount + listCount;
+    }, 0);
+
+    return Math.max(0, 1 - totalDebt / 10);
+  }
+
+  /**
+   * @private
+   */
+  _calculateRegressionClear(phases) {
+    let totalRegressionChecks = 0;
+    let passedRegressionChecks = 0;
+
+    for (const phase of phases) {
+      const checks = phase?.validation?.checks;
+      if (!Array.isArray(checks)) continue;
+
+      for (const check of checks) {
+        const type = String(check?.type || '').toLowerCase();
+        const pathValue = String(check?.path || '').toLowerCase();
+        const checklist = String(check?.checklist || '').toLowerCase();
+        const isRegression = type.includes('regression')
+          || pathValue.includes('regression')
+          || checklist.includes('regression');
+
+        if (!isRegression) continue;
+        totalRegressionChecks += 1;
+        if (check?.passed === true) {
+          passedRegressionChecks += 1;
+        }
+      }
+    }
+
+    if (totalRegressionChecks === 0) {
+      return this._calculateTestCoverage(phases);
+    }
+
+    return passedRegressionChecks / totalRegressionChecks;
+  }
+
   /**
    * Reset workflow state (for re-execution)
    * @param {boolean} keepMetadata - Whether to preserve metadata