@holoscript/framework 6.0.3

package/src/self-improve/absorb-scanner.ts

@@ -0,0 +1,252 @@
+/**
+ * Absorb Scanner — Framework scans its own codebase for improvements.
+ *
+ * Queries the MCP Orchestrator knowledge store for framework-related
+ * insights, and scans local source files for TODO/FIXME markers.
+ *
+ * Does NOT depend on the absorb service being up — the orchestrator's
+ * knowledge store is the source of truth (always available).
+ */
+
+import { execSync } from 'child_process';
+import { resolve } from 'path';
+
+export interface AbsorbScanConfig {
+  /** MCP Orchestrator URL (default: production) */
+  orchestratorUrl?: string;
+  /** MCP API key for orchestrator auth */
+  mcpApiKey?: string;
+  /** Workspace ID for knowledge queries (default: ai-ecosystem) */
+  workspaceId?: string;
+  /** Max improvement tasks to generate */
+  maxTasks?: number;
+  /** Search query for knowledge store */
+  searchQuery?: string;
+}
+
+export interface ScanResult {
+  scanned: boolean;
+  filesAnalyzed: number;
+  issuesFound: number;
+  improvements: ImprovementTask[];
+  knowledge: ExtractedKnowledge[];
+  error?: string;
+}
+
+export interface ImprovementTask {
+  title: string;
+  description: string;
+  priority: number;
+  category: 'refactor' | 'test' | 'docs' | 'performance' | 'type-safety';
+  file?: string;
+  line?: number;
+}
+
+export interface ExtractedKnowledge {
+  type: 'wisdom' | 'pattern' | 'gotcha';
+  content: string;
+  domain: string;
+  confidence: number;
+}
+
+const DEFAULT_ORCHESTRATOR_URL = 'https://mcp-orchestrator-production-45f9.up.railway.app';
+const DEFAULT_WORKSPACE_ID = 'ai-ecosystem';
+
+/** Orchestrator knowledge entry shape */
+interface KnowledgeEntry {
+  id?: string;
+  type?: 'wisdom' | 'pattern' | 'gotcha';
+  content?: string;
+  metadata?: {
+    domain?: string;
+    confidence?: number;
+    source?: string;
+  };
+}
+
+/**
+ * Scan the framework via the MCP Orchestrator knowledge store.
+ * Returns improvement tasks + extracted knowledge.
+ * Falls back gracefully if the orchestrator is unreachable.
+ */
+export async function scanFramework(config: AbsorbScanConfig = {}): Promise<ScanResult> {
+  const orchestratorUrl = config.orchestratorUrl || DEFAULT_ORCHESTRATOR_URL;
+  const apiKey = config.mcpApiKey || process.env.MCP_API_KEY || '';
+  const workspaceId = config.workspaceId || DEFAULT_WORKSPACE_ID;
+  const maxTasks = config.maxTasks || 20;
+  const searchQuery = config.searchQuery ||
+    'framework improvement opportunities type-safety test-coverage refactoring agents';
+
+  if (!apiKey) {
+    return {
+      scanned: false,
+      filesAnalyzed: 0,
+      issuesFound: 0,
+      improvements: [],
+      knowledge: [],
+      error: 'MCP_API_KEY required for knowledge store query',
+    };
+  }
+
+  try {
+    const queryRes = await fetch(`${orchestratorUrl}/knowledge/query`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-mcp-api-key': apiKey,
+      },
+      body: JSON.stringify({
+        search: searchQuery,
+        limit: maxTasks,
+        workspace_id: workspaceId,
+      }),
+      signal: AbortSignal.timeout(15_000),
+    });
+
+    const improvements: ImprovementTask[] = [];
+    const knowledge: ExtractedKnowledge[] = [];
+    let filesAnalyzed = 0;
+
+    if (queryRes.ok) {
+      const data = await queryRes.json() as {
+        results?: KnowledgeEntry[];
+        entries?: KnowledgeEntry[];
+      };
+      const entries = data.results || data.entries || [];
+      filesAnalyzed = entries.length;
+
+      for (const entry of entries.slice(0, maxTasks)) {
+        const content = entry.content || '';
+        const entryType = entry.type || 'pattern';
+        const domain = entry.metadata?.domain || 'framework';
+        const confidence = entry.metadata?.confidence ?? 0.5;
+
+        // Skip gated entries that we can't read
+        if (content.includes('[Requires API key')) continue;
+
+        // Gotchas become improvement tasks (things to fix)
+        if (entryType === 'gotcha') {
+          improvements.push({
+            title: content.slice(0, 120),
+            description: `Knowledge store gotcha (${domain}): ${content.slice(0, 300)}`,
+            priority: 2,
+            category: categorizeContent(content),
+          });
+        }
+
+        // All entries become extracted knowledge
+        knowledge.push({
+          type: entryType,
+          content: content.slice(0, 500),
+          domain,
+          confidence,
+        });
+      }
+    }
+
+    return {
+      scanned: true,
+      filesAnalyzed,
+      issuesFound: improvements.length,
+      improvements,
+      knowledge,
+    };
+  } catch (err) {
+    return {
+      scanned: false,
+      filesAnalyzed: 0,
+      issuesFound: 0,
+      improvements: [],
+      knowledge: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Scan local source files for TODO/FIXME/HACK markers.
+ * Returns improvement tasks derived from code comments.
+ */
+export async function scanTodos(codebasePath: string): Promise<ScanResult> {
+  const absPath = resolve(codebasePath);
+  const improvements: ImprovementTask[] = [];
+
+  try {
+    // Use grep to find TODO/FIXME/HACK across .ts/.tsx files
+    // grep returns exit code 1 when no matches (not an error)
+    let grepOutput = '';
+    try {
+      grepOutput = execSync(
+        `grep -rn --include="*.ts" --include="*.tsx" -E "(TODO|FIXME|HACK):" "${absPath}"`,
+        { encoding: 'utf-8', timeout: 10_000, maxBuffer: 1024 * 1024 }
+      );
+    } catch (grepErr: unknown) {
+      // grep exits 1 when no matches — that's fine
+      const execErr = grepErr as { status?: number; stdout?: string };
+      if (execErr.status === 1) {
+        grepOutput = execErr.stdout || '';
+      } else {
+        throw grepErr;
+      }
+    }
+
+    const lines = grepOutput.split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      // Format: filepath:linenum:content
+      const match = line.match(/^(.+?):(\d+):(.+)$/);
+      if (!match) continue;
+
+      const [, filePath, lineStr, content] = match;
+      const lineNum = parseInt(lineStr, 10);
+      const trimmed = content.trim();
+
+      // Extract the marker type
+      const isFixme = trimmed.includes('FIXME');
+      const isHack = trimmed.includes('HACK');
+
+      // Extract the comment text after the marker
+      const markerMatch = trimmed.match(/(?:TODO|FIXME|HACK):\s*(.+)/);
+      const commentText = markerMatch ? markerMatch[1].trim() : trimmed;
+
+      // Relativize path for readability
+      const relPath = filePath.replace(absPath, '').replace(/^[\\/]/, '');
+
+      improvements.push({
+        title: commentText.slice(0, 120),
+        description: `${isFixme ? 'FIXME' : isHack ? 'HACK' : 'TODO'} in ${relPath}:${lineNum}`,
+        priority: isFixme ? 1 : isHack ? 2 : 3,
+        category: categorizeContent(commentText),
+        file: relPath,
+        line: lineNum,
+      });
+    }
+
+    return {
+      scanned: true,
+      filesAnalyzed: lines.length,
+      issuesFound: improvements.length,
+      improvements,
+      knowledge: [],
+    };
+  } catch (err) {
+    return {
+      scanned: false,
+      filesAnalyzed: 0,
+      issuesFound: 0,
+      improvements: [],
+      knowledge: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/** Categorize content into an improvement category based on keywords. */
+function categorizeContent(content: string): ImprovementTask['category'] {
+  const lower = content.toLowerCase();
+  if (lower.includes('test') || lower.includes('coverage') || lower.includes('spec')) return 'test';
+  if (lower.includes('perf') || lower.includes('slow') || lower.includes('optim')) return 'performance';
+  if (lower.includes('doc') || lower.includes('readme') || lower.includes('comment')) return 'docs';
+  if (lower.includes('type') || lower.includes('any') || lower.includes('cast')) return 'type-safety';
+  return 'refactor';
+}

package/src/self-improve/evolution-engine.ts

@@ -0,0 +1,149 @@
+/**
+ * Evolution Engine — The framework improves itself.
+ *
+ * The pipeline:
+ * 1. SCAN: Query orchestrator knowledge store + scan local TODOs
+ * 2. PROPOSE: Convert findings to improvement suggestions
+ * 3. VOTE: Team agents vote on which improvements matter
+ * 4. EXECUTE: Winning suggestions become board tasks
+ * 5. COMPOUND: Knowledge from execution feeds back into the store
+ *
+ * This is the v1.0 singularity point — the framework's own agents
+ * can propose, vote on, and ship improvements to themselves.
+ */
+
+import type { Team } from '../team';
+import type { KnowledgeInsight } from '../types';
+import { scanFramework, scanTodos } from './absorb-scanner';
+import type { AbsorbScanConfig, ScanResult, ImprovementTask } from './absorb-scanner';
+
+export interface EvolutionConfig {
+  /** Absorb scan configuration */
+  absorb?: AbsorbScanConfig;
+  /** Path to scan for TODOs (default: none — skip TODO scan) */
+  codebasePath?: string;
+  /** Auto-propose improvements as suggestions (default: true) */
+  autoPropose?: boolean;
+  /** Auto-add high-priority improvements to board (default: false) */
+  autoBoard?: boolean;
+  /** Minimum priority to auto-board (1=critical, default: 2) */
+  autoBoardMinPriority?: number;
+}
+
+export interface EvolutionResult {
+  scan: ScanResult;
+  todoScan?: ScanResult;
+  suggestionsCreated: number;
+  tasksCreated: number;
+  knowledgePublished: number;
+}
+
+/**
+ * Merge two ScanResults by combining their improvements and knowledge.
+ */
+function mergeScanResults(a: ScanResult, b: ScanResult): ScanResult {
+  return {
+    scanned: a.scanned || b.scanned,
+    filesAnalyzed: a.filesAnalyzed + b.filesAnalyzed,
+    issuesFound: a.issuesFound + b.issuesFound,
+    improvements: [...a.improvements, ...b.improvements],
+    knowledge: [...a.knowledge, ...b.knowledge],
+    error: a.error && b.error ? `${a.error}; ${b.error}` : a.error || b.error,
+  };
+}
+
+/**
+ * Run one evolution cycle on a team.
+ *
+ * Scans the orchestrator knowledge store and local TODOs,
+ * proposes improvements as suggestions, publishes extracted knowledge,
+ * and optionally adds high-priority items directly to the board.
+ */
+export async function evolve(team: Team, config: EvolutionConfig = {}): Promise<EvolutionResult> {
+  const autoPropose = config.autoPropose !== false;
+  const autoBoard = config.autoBoard ?? false;
+  const autoBoardMinPriority = config.autoBoardMinPriority ?? 2;
+
+  // Step 1: Scan knowledge store
+  const knowledgeScan = await scanFramework(config.absorb);
+
+  // Step 1b: Scan local TODOs if codebasePath provided
+  let todoScan: ScanResult | undefined;
+  if (config.codebasePath) {
+    todoScan = await scanTodos(config.codebasePath);
+  }
+
+  // Merge results for unified processing
+  const scan = todoScan ? mergeScanResults(knowledgeScan, todoScan) : knowledgeScan;
+
+  if (!scan.scanned || (scan.improvements.length === 0 && scan.knowledge.length === 0)) {
+    return { scan, todoScan, suggestionsCreated: 0, tasksCreated: 0, knowledgePublished: 0 };
+  }
+
+  let suggestionsCreated = 0;
+  let tasksCreated = 0;
+  let knowledgePublished = 0;
+
+  // Step 2: Propose improvements as suggestions
+  if (autoPropose && team.isRemote) {
+    for (const imp of scan.improvements) {
+      try {
+        await team.suggest(imp.title, {
+          description: imp.description,
+          category: mapCategory(imp.category),
+          evidence: imp.file ? `Detected in ${imp.file}${imp.line ? `:${imp.line}` : ''}` : undefined,
+        });
+        suggestionsCreated++;
+      } catch {
+        // Suggestion may already exist (dedup)
+      }
+    }
+  }
+
+  // Step 3: Auto-board critical items
+  if (autoBoard) {
+    const critical = scan.improvements.filter(imp => imp.priority <= autoBoardMinPriority);
+    if (critical.length > 0) {
+      const tasks = critical.map(imp => ({
+        title: imp.title,
+        description: `[Self-improvement] ${imp.description}`,
+        priority: imp.priority,
+        source: 'evolution:self-scan',
+        role: 'coder' as const,
+      }));
+      const added = await team.addTasks(tasks);
+      tasksCreated = added.length;
+    }
+  }
+
+  // Step 4: Publish extracted knowledge
+  for (const k of scan.knowledge) {
+    team.knowledge.publish(
+      { type: k.type, content: k.content, domain: k.domain, confidence: k.confidence, source: 'evolution:self-scan' },
+      'evolution-engine'
+    );
+    knowledgePublished++;
+  }
+
+  // Step 5: Compound
+  team.knowledge.compound(scan.knowledge.map(k => ({
+    type: k.type,
+    content: k.content,
+    domain: k.domain,
+    confidence: k.confidence,
+    source: 'evolution:self-scan',
+  })));
+
+  return { scan, todoScan, suggestionsCreated, tasksCreated, knowledgePublished };
+}
+
+function mapCategory(cat: ImprovementTask['category']): 'process' | 'tooling' | 'architecture' | 'testing' | 'docs' | 'performance' | 'other' {
+  switch (cat) {
+    case 'refactor': return 'architecture';
+    case 'test': return 'testing';
+    case 'docs': return 'docs';
+    case 'performance': return 'performance';
+    case 'type-safety': return 'tooling';
+    default: return 'other';
+  }
+}

package/src/self-improve/framework-absorber.ts

@@ -0,0 +1,214 @@
+// STATUS: Scaffold — requires absorb service connection and LLM provider for production use
+/**
+ * FrameworkAbsorber — Class-based absorb integration for framework self-scanning.
+ *
+ * @experimental
+ *
+ * Wraps the absorb service (https://absorb.holoscript.net) to scan the
+ * framework codebase, query for code health, and surface improvements.
+ * Falls back to the MCP Orchestrator knowledge store when the absorb
+ * service is unreachable.
+ */
+
+import type { AbsorbScanConfig, ScanResult, ImprovementTask, ExtractedKnowledge } from './absorb-scanner';
+import { scanFramework, scanTodos } from './absorb-scanner';
+
+export interface CodebaseGraph {
+  /** Number of files in the graph */
+  fileCount: number;
+  /** Number of edges (dependencies) between files */
+  edgeCount: number;
+  /** Top-level modules detected */
+  modules: string[];
+  /** Raw graph data from absorb (opaque — shape depends on service version) */
+  raw?: unknown;
+}
+
+export interface Improvement {
+  id: string;
+  title: string;
+  description: string;
+  priority: number;
+  category: ImprovementTask['category'];
+  file?: string;
+  line?: number;
+  /** Confidence score from absorb analysis (0-1) */
+  confidence: number;
+}
+
+export interface AbsorberConfig extends AbsorbScanConfig {
+  /** Absorb service URL (default: production) */
+  absorbUrl?: string;
+  /** Absorb API key (default: ABSORB_API_KEY env var) */
+  absorbApiKey?: string;
+  /** Path to scan for local TODOs */
+  codebasePath?: string;
+}
+
+const DEFAULT_ABSORB_URL = 'https://absorb.holoscript.net';
+
+/**
+ * FrameworkAbsorber — scans the framework codebase for improvements.
+ *
+ * @experimental
+ *
+ * Usage:
+ * ```ts
+ * const absorber = new FrameworkAbsorber({ codebasePath: 'packages/framework' });
+ * const graph = await absorber.scanSelf();
+ * const improvements = await absorber.findImprovements();
+ * ```
+ */
+export class FrameworkAbsorber {
+  private readonly config: AbsorberConfig;
+  private lastScan: ScanResult | null = null;
+
+  constructor(config: AbsorberConfig = {}) {
+    this.config = {
+      absorbUrl: config.absorbUrl || DEFAULT_ABSORB_URL,
+      absorbApiKey: config.absorbApiKey || process.env.ABSORB_API_KEY || '',
+      ...config,
+    };
+  }
+
+  /**
+   * Scan the framework codebase via the absorb service.
+   * Returns a CodebaseGraph with module/dependency info.
+   *
+   * Calls absorb_run_absorb MCP tool via JSON-RPC for full graph analysis.
+   * Falls back to knowledge store scan if the absorb service is unreachable.
+   */
+  async scanSelf(): Promise<CodebaseGraph> {
+    const absorbUrl = this.config.absorbUrl || DEFAULT_ABSORB_URL;
+    const apiKey = this.config.absorbApiKey || '';
+
+    // Try absorb service via MCP JSON-RPC
+    if (apiKey) {
+      try {
+        const repoUrl = this.config.codebasePath || 'packages/framework';
+        const rpcPayload = {
+          jsonrpc: '2.0' as const,
+          id: `absorb-scan-${Date.now()}`,
+          method: 'tools/call',
+          params: {
+            name: 'absorb_run_absorb',
+            arguments: { repo_url: repoUrl },
+          },
+        };
+
+        const res = await fetch(`${absorbUrl}/mcp`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify(rpcPayload),
+          signal: AbortSignal.timeout(30_000),
+        });
+
+        if (res.ok) {
+          const rpcResult = (await res.json()) as {
+            result?: {
+              content?: Array<{ text?: string }>;
+            };
+            error?: { message?: string };
+          };
+
+          if (rpcResult.result?.content) {
+            // Parse the absorb graph from the MCP response
+            const raw = rpcResult.result.content;
+            const textContent = raw.find(c => c.text)?.text;
+            let parsed: Record<string, unknown> = {};
+            if (textContent) {
+              try {
+                parsed = JSON.parse(textContent) as Record<string, unknown>;
+              } catch {
+                // Text response not JSON — use as-is
+                parsed = { text: textContent };
+              }
+            }
+
+            return {
+              fileCount: typeof parsed.file_count === 'number'
+                ? parsed.file_count
+                : typeof parsed.files === 'number'
+                  ? parsed.files
+                  : 0,
+              edgeCount: typeof parsed.edge_count === 'number'
+                ? parsed.edge_count
+                : typeof parsed.edges === 'number'
+                  ? parsed.edges
+                  : 0,
+              modules: Array.isArray(parsed.modules)
+                ? parsed.modules as string[]
+                : [],
+              raw: parsed,
+            };
+          }
+        }
+      } catch {
+        // Absorb service unreachable — fall through to knowledge store
+      }
+    }
+
+    // Fallback: scan via knowledge store
+    const scan = await scanFramework(this.config);
+    this.lastScan = scan;
+
+    return {
+      fileCount: scan.filesAnalyzed,
+      edgeCount: 0,
+      modules: [],
+    };
+  }
+
+  /**
+   * Find improvements by scanning knowledge store + local TODOs.
+   * Returns ranked improvement list with confidence scores.
+   */
+  async findImprovements(): Promise<Improvement[]> {
+    const scan = this.lastScan || await this.runFullScan();
+    return scan.improvements.map((imp, i) => ({
+      id: `fw-imp-${i}-${Date.now()}`,
+      title: imp.title,
+      description: imp.description,
+      priority: imp.priority,
+      category: imp.category,
+      file: imp.file,
+      line: imp.line,
+      confidence: 0.5 + (imp.priority <= 2 ? 0.3 : 0),
+    }));
+  }
+
+  /**
+   * Get extracted knowledge from the last scan.
+   */
+  getKnowledge(): ExtractedKnowledge[] {
+    return this.lastScan?.knowledge || [];
+  }
+
+  /**
+   * Run a full scan (knowledge store + local TODOs).
+   */
+  private async runFullScan(): Promise<ScanResult> {
+    const knowledgeScan = await scanFramework(this.config);
+    let todoScan: ScanResult | undefined;
+
+    if (this.config.codebasePath) {
+      todoScan = await scanTodos(this.config.codebasePath);
+    }
+
+    const merged: ScanResult = todoScan
+      ? {
+          scanned: knowledgeScan.scanned || todoScan.scanned,
+          filesAnalyzed: knowledgeScan.filesAnalyzed + todoScan.filesAnalyzed,
+          issuesFound: knowledgeScan.issuesFound + todoScan.issuesFound,
+          improvements: [...knowledgeScan.improvements, ...todoScan.improvements],
+          knowledge: [...knowledgeScan.knowledge, ...todoScan.knowledge],
+        }
+      : knowledgeScan;
+
+    this.lastScan = merged;
+    return merged;
+  }
+}

package/src/self-improve/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Self-Improvement Module — The framework evolves itself.
+ *
+ * @experimental All exports in this module are scaffolds (FW-1.0).
+ * They compile and have correct type signatures but require a live
+ * absorb service connection and/or LLM provider to do real work.
+ * Do not treat these as production-ready.
+ *
+ * FW-1.0: absorb integration, self-evolution, auto-test generation,
+ * prompt optimization via A/B testing.
+ */
+
+export {
+  type AbsorbScanConfig,
+  type ScanResult,
+  type ImprovementTask,
+  type ExtractedKnowledge,
+  scanFramework,
+  scanTodos,
+} from './absorb-scanner';
+
+export {
+  type EvolutionConfig,
+  type EvolutionResult,
+  evolve,
+} from './evolution-engine';
+
+// FW-1.0: Class-based absorb integration
+export {
+  FrameworkAbsorber,
+  type AbsorberConfig,
+  type CodebaseGraph,
+  type Improvement,
+} from './framework-absorber';
+
+// FW-1.0: Auto-test generation via LLM
+export {
+  TestGenerator,
+  type TestGeneratorConfig,
+  type GeneratedTest,
+} from './test-generator';
+
+// FW-1.0: Prompt optimization via A/B testing
+export {
+  PromptOptimizer,
+  type ABTestConfig,
+  type ABTestResult,
+  type PromptVariantResult,
+  type EvaluationCriteria,
+} from './prompt-optimizer';