@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/agent/self-improvement/evolution/evolution-engine.js

@@ -0,0 +1,503 @@
+/**
+ * Evolution engine (Phase D): the mutation→evaluate→record loop. One cycle:
+ *   1. branch `codebuddy/evolve/<id>` off the baseline ref;
+ *   2. MUTATE it — an injected mutator (default: a headless agent subprocess) edits code toward a
+ *      weakness (a failing eval task / a self-model hotspot / a manual goal), in an isolated worktree;
+ *   3. commit the change on the branch;
+ *   4. SCORE it via scoreBranchInWorktree — which first rejects any protected-path tampering (Phase C)
+ *      then computes fitness (Phase A) in an isolated worktree (Phase B);
+ *   5. RECORD it in the CodeVariantStore + EvolutionaryArchive, ranked vs the baseline.
+ *
+ * The engine NEVER merges to main and NEVER auto-applies — it only produces evaluated candidate
+ * branches for human review (Phase E). Losing branches are pruned unless keepLosers is set.
+ *
+ * @module agent/self-improvement/evolution/evolution-engine
+ */
+import { execFileSync, spawn } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { logger } from '../../../utils/logger.js';
+import { scoreBranchInWorktree } from './worktree-scorer.js';
+import { WorktreeSessionManager } from '../../../git/worktree-sessions.js';
+import { CodeVariantStore, behaviorDescriptor, diverseElites, computeGeneration, selectParentWithPenalty, } from './code-variant-store.js';
+import { makeLlmVariantPlanner, renderVariantPlan } from './variant-planner.js';
+import { changedPathsVsBase } from './protected-paths.js';
+import { checkAstNovelty } from './ast-novelty.js';
+import { pickModelUCB } from './model-bandit.js';
+/** Pure decision: a candidate "wins" if it passed everything, regressed nothing, and beats baseline. */
+export function beatsBaseline(report, baseline) {
+    if (!report.passedAll || report.regressions.length > 0)
+        return false;
+    if (baseline)
+        return report.score > baseline.score;
+    return true;
+}
+function git(args, cwd) {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+/** True if a ref/sha resolves to a reachable commit (used to guard compounding off a maybe-pruned elite). */
+function isReachableRef(ref, cwd) {
+    try {
+        git(['rev-parse', '--verify', '-q', `${ref}^{commit}`], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Pure: pick the branch base — the compounding elite when reachable, else the baseline. */
+export function chooseBranchBase(baselineRef, compoundFrom, isReachable) {
+    return compoundFrom && isReachable(compoundFrom) ? compoundFrom : baselineRef;
+}
+const MAX_INSPIRATION_DIFF = 4000;
+/** Top-k eligible variants (with truncated diffs) to seed the mutator's prompt. */
+export function gatherInspirations(store, baseRef, basePath, k, baselineScore, selection = {}) {
+    if (k <= 0)
+        return [];
+    const records = store.list();
+    // The penalized path is the default. Keep the old path available explicitly for comparisons.
+    const elites = selection.selectionMode === 'penalized'
+        ? selectPenalizedInspirations(records, k, selection.lambda, selection.random)
+        : selection.selectionMode === 'legacy'
+            ? diverseElites(records, k, baselineScore)
+            : selectPenalizedInspirations(records, k, selection.lambda, selection.random);
+    return elites.map((v) => {
+        let diff = '';
+        try {
+            diff = git(['diff', `${baseRef}...${v.branch}`], basePath);
+        }
+        catch {
+            /* branch may have been pruned/merged — goal + score still inspire */
+        }
+        if (diff.length > MAX_INSPIRATION_DIFF)
+            diff = `${diff.slice(0, MAX_INSPIRATION_DIFF)}\n…(truncated)`;
+        return { id: v.id, goal: v.detail ?? '', score: v.score, diff };
+    });
+}
+function selectPenalizedInspirations(records, k, lambda = 0.5, random = Math.random) {
+    const remaining = [...records];
+    const selected = [];
+    for (let i = 0; i < k; i++) {
+        const parent = selectParentWithPenalty(remaining, lambda, random);
+        if (!parent)
+            break;
+        selected.push(parent);
+        // One parent is used at most once in a single inspiration set. Descendant pressure across
+        // cycles comes from the persisted childrenCount written when the child record is appended.
+        const index = remaining.findIndex((record) => record.id === parent.id);
+        if (index >= 0)
+            remaining.splice(index, 1);
+    }
+    return selected;
+}
+function checkBranchAstNovelty(branch, baselineRef, basePath, worktreeDir) {
+    const changed = changedPathsVsBase(branch, baselineRef, basePath).filter((file) => /\.(?:[cm]?tsx?|[cm]?jsx?)$/i.test(file));
+    if (changed.length === 0)
+        return { isNovel: true, diffNodesCount: 0 };
+    let diffNodesCount = 0;
+    let allIdentical = true;
+    for (const file of changed) {
+        let parentCode = '';
+        try {
+            parentCode = git(['show', `${baselineRef}:${file}`], basePath);
+        }
+        catch {
+            // A new file has an empty parent; the AST comparison below will conservatively mark it novel.
+        }
+        const mutatedCode = existsSync(join(worktreeDir, file)) ? readFileSync(join(worktreeDir, file), 'utf8') : '';
+        const result = checkAstNovelty(mutatedCode, parentCode);
+        diffNodesCount += result.diffNodesCount;
+        if (result.isNovel)
+            allIdentical = false;
+    }
+    return allIdentical
+        ? { isNovel: false, diffNodesCount, reason: 'ast-identical' }
+        : { isNovel: true, diffNodesCount };
+}
+/**
+ * Default bandit catalog: the cloud/subscription LLMs the user is authenticated to, with their
+ * nominal input $/Mtok (the cost signal the bandit trades against quality). Reuses the public
+ * `buildActiveLlmRegistry` — the SAME source the fleet model-selector uses — rather than duplicating
+ * detection. Never-throws → an empty catalog on any failure, and the caller falls back to the static
+ * model. Local models are included when the registry surfaces them (they cost $0 → no cost penalty).
+ */
+async function listBanditCandidates(env) {
+    try {
+        const { buildActiveLlmRegistry } = await import('../../../providers/active-llm-registry.js');
+        const reg = await buildActiveLlmRegistry({ env });
+        const out = [];
+        const seen = new Set();
+        for (const c of reg.all) {
+            if (!c.model)
+                continue;
+            const key = c.model.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({
+                provider: c.provider,
+                model: c.model,
+                ...(c.apiKey ? { apiKey: c.apiKey } : {}),
+                ...(c.baseURL ? { baseURL: c.baseURL } : {}),
+                isLocal: c.isLocal,
+                costInputUsdPerMtok: c.costInputUsdPerMtok,
+                strengths: [], // the bandit ranks on scoreboard win-rate + cost, not capability strengths
+            });
+        }
+        return out;
+    }
+    catch (err) {
+        logger.debug?.(`[evolve] bandit candidate probe skipped: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+/** The default cost-aware UCB selector (scoped to the `evolve` task category). */
+export const defaultEvolveSelector = (cands, sb) => pickModelUCB(cands, sb, { taskType: 'evolve' });
+/**
+ * Wrap a base selector so a batch of CONCURRENT cycles picks DISTINCT models. All cycles of a round
+ * read the SAME scoreboard before any of them records the first outcome — so with an empty scoreboard
+ * every arm looks `n===0` and `pickModelUCB`'s deterministic tie-break hands the SAME (cheapest) model
+ * to all of them, defeating UCB's "try each arm once". This shared-`inFlight` wrapper excludes models
+ * already dispensed this round (wrapping around for a fresh pass once every arm has been used), so the
+ * concurrent batch round-robins across the catalog instead of collapsing onto one model. The wrapper
+ * body is synchronous (no `await`), so its `inFlight` mutation cannot interleave across cycles. Pure
+ * apart from the passed-in set; never throws (delegates all failure handling to the base selector).
+ */
+export function makeInFlightAwareSelector(base, inFlight) {
+    return (candidates, scoreboard) => {
+        let available = candidates.filter((c) => !inFlight.has(c.model));
+        if (available.length === 0) {
+            // Every arm has been dispensed once this round → wrap around for a fresh pass.
+            inFlight.clear();
+            available = [...candidates];
+        }
+        const chosen = base(available, scoreboard);
+        if (chosen)
+            inFlight.add(chosen);
+        return chosen;
+    };
+}
+/**
+ * Decide the mutator's model via the cost-aware UCB bandit. Returns `null` when the bandit is OFF
+ * (the common case → static model, byte-identical path) OR when nothing could be chosen (empty
+ * catalog / error). NEVER throws: a bandit failure must never fail an evolution cycle.
+ */
+export async function resolveBanditModel(opts, env) {
+    if (!opts.useModelBandit)
+        return null;
+    try {
+        const scoreboard = opts.scoreboard ?? (await import('../../../fleet/model-scoreboard.js')).getModelScoreboard();
+        const candidates = opts.banditCandidates ?? (await listBanditCandidates(env));
+        if (candidates.length === 0)
+            return null;
+        const select = opts.modelSelector ?? defaultEvolveSelector;
+        const chosen = select(candidates, scoreboard);
+        if (!chosen)
+            return null;
+        const cand = candidates.find((c) => c.model === chosen);
+        return { model: chosen, provider: cand?.provider ?? 'unknown', scoreboard };
+    }
+    catch (err) {
+        logger.warn(`[evolve] model bandit selection failed, using static model: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * Close the bandit loop: feed this cycle's outcome back to the scoreboard so the NEXT selection's
+ * `smoothedWinRate` reflects it (`taskType: 'evolve'`). NEVER throws. `costUsd` is not metered in the
+ * evolution loop (no per-run token accounting) — the bandit's cost signal is the catalog $/Mtok read
+ * at selection time — so the marginal $ recorded here is 0 unless the caller supplies one.
+ */
+export function recordBanditOutcome(choice, outcome) {
+    try {
+        choice.scoreboard.recordOutcome({
+            at: outcome.at,
+            taskType: 'evolve',
+            model: choice.model,
+            provider: choice.provider,
+            won: outcome.won,
+            quality: outcome.quality,
+            costUsd: outcome.costUsd ?? 0,
+            latencyMs: outcome.latencyMs,
+        });
+    }
+    catch (err) {
+        logger.warn(`[evolve] bandit recordOutcome failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Run one mutation→evaluate→record cycle. Never merges; prunes losing branches by default. */
+export async function runEvolutionCycle(opts) {
+    const basePath = opts.basePath ?? process.cwd();
+    const variantId = opts.variantId ?? `evo-${Date.now().toString(36)}`;
+    const branch = `codebuddy/evolve/${variantId}`;
+    const env = opts.env ?? process.env;
+    const store = opts.store ?? new CodeVariantStore();
+    const now = opts.now ?? Date.now;
+    // Cost-aware UCB model selection (opt-in). Off → null: the mutator keeps its static model, the
+    // scoreboard is untouched, and the mutate args below are byte-identical to the pre-bandit path.
+    const banditChoice = await resolveBanditModel(opts, env);
+    let mutationLatencyMs = 0;
+    // AlphaEvolve-style inspirations: show the mutator prior elite variants (built before this branch).
+    const inspirations = gatherInspirations(store, opts.baselineRef, basePath, opts.inspirationCount ?? 2, opts.baseline?.score, {
+        selectionMode: opts.legacyParentSelection ? 'legacy' : 'penalized',
+        ...(opts.parentPenaltyLambda !== undefined ? { lambda: opts.parentPenaltyLambda } : {}),
+        ...(opts.parentSelectionRandom ? { random: opts.parentSelectionRandom } : {}),
+    });
+    // Deliberate planning: decide the approach (build-on / diverge / fresh) + concrete steps BEFORE
+    // touching code. Never-throws → null falls back to the mutator's legacy ad-hoc prompt.
+    const plan = await (opts.planner ?? makeLlmVariantPlanner())({ weakness: opts.weakness, inspirations });
+    // 1. branch off the baseline — OR off a prior elite when compounding (guarded: fall back to
+    //    baseline if that elite ref is unreachable, e.g. it was pruned).
+    const branchBase = chooseBranchBase(opts.baselineRef, opts.compoundFrom, (r) => isReachableRef(r, basePath));
+    git(['branch', '-f', branch, branchBase], basePath);
+    // 2-3. mutate in an isolated worktree, then commit the change on the branch.
+    let mutated = false;
+    let mutationPlan; // the instruction that produced this variant (for audit)
+    let astNovelty = { isNovel: true, diffNodesCount: 0 };
+    const mgr = WorktreeSessionManager.getInstance();
+    const session = mgr.createWorktreeSession(branch, basePath);
+    try {
+        const mutateStartedAt = banditChoice ? now() : 0;
+        const res = await opts.mutate({
+            branch,
+            weakness: opts.weakness,
+            worktreeDir: session.worktreePath,
+            env,
+            inspirations,
+            ...(plan ? { plan } : {}),
+            ...(banditChoice ? { model: banditChoice.model } : {}),
+        });
+        if (banditChoice)
+            mutationLatencyMs = Math.max(0, now() - mutateStartedAt);
+        // Store the deliberate plan when we have one (audit); else the mutator's own record.
+        mutationPlan = plan ? renderVariantPlan(plan) : res.plan;
+        git(['add', '-A'], session.worktreePath);
+        const dirty = git(['status', '--porcelain'], session.worktreePath).trim().length > 0;
+        if (dirty) {
+            execFileSync('git', ['-c', 'user.name=Code Buddy Evolve', '-c', 'user.email=evolve@codebuddy', '-c', 'commit.gpgsign=false',
+                'commit', '-q', '-m', `evolve(${opts.weakness.id}): ${opts.weakness.goal}`], { cwd: session.worktreePath, stdio: ['ignore', 'ignore', 'ignore'] });
+            mutated = true;
+            try {
+                astNovelty = checkBranchAstNovelty(branch, opts.baselineRef, basePath, session.worktreePath);
+            }
+            catch (err) {
+                // A read/parse failure must fail open: only a proven AST identity may skip evaluation.
+                logger.warn(`[evolve] AST novelty check failed for ${branch}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (!mutated)
+            logger.info(`[evolve] mutator produced no change for ${branch}${res.detail ? ` (${res.detail})` : ''}`);
+    }
+    finally {
+        try {
+            mgr.cleanupWorktree(branch);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (!mutated) {
+        try {
+            git(['branch', '-D', branch], basePath);
+        }
+        catch {
+            /* ignore */
+        }
+        return {
+            variantId,
+            branch,
+            mutated: false,
+            report: { score: 0, passedAll: false, regressions: [], components: [] },
+            beatsBaseline: false,
+            kept: false,
+        };
+    }
+    // G0 — reject a formatting/comment/import-only mutation before materialising the scoring
+    // worktree. The counter is persisted in the same archive store as the variants.
+    if (!astNovelty.isNovel) {
+        store.recordEvaluationAvoided();
+        logger.info(`[evolve] G0 rejected AST-identical mutation ${branch} (${astNovelty.diffNodesCount} changed nodes)`);
+        try {
+            git(['branch', '-D', branch], basePath);
+        }
+        catch {
+            /* keep the branch if cleanup fails; the evaluation was still avoided */
+        }
+        return {
+            variantId,
+            branch,
+            mutated: true,
+            report: { score: 0, passedAll: false, regressions: [], components: [] },
+            beatsBaseline: false,
+            kept: false,
+            rejectionReason: 'ast-identical',
+        };
+    }
+    // 4. score (Phase C reject + Phase A/B fitness in an isolated worktree).
+    const scored = await scoreBranchInWorktree(branch, {
+        basePath,
+        baselineRef: opts.baselineRef,
+        ...(opts.components ? { components: opts.components } : {}),
+        ...(opts.baseline ? { baseline: opts.baseline } : {}),
+    });
+    const report = scored.report;
+    const wins = mutated && beatsBaseline(report, opts.baseline);
+    // Close the bandit loop: record this model's outcome so the next selection learns from it.
+    if (banditChoice) {
+        recordBanditOutcome(banditChoice, {
+            won: wins,
+            quality: report.score,
+            latencyMs: mutationLatencyMs,
+            at: new Date(now()).toISOString(),
+        });
+    }
+    // 5. record + prune.
+    const sha = (() => {
+        try {
+            return git(['rev-parse', branch], basePath).trim();
+        }
+        catch {
+            return '';
+        }
+    })();
+    // Genealogy: the elites that inspired this variant are its parents; generation = 1 + max(parent gen).
+    const parents = inspirations.map((i) => i.id);
+    const record = {
+        id: variantId,
+        branch,
+        sha,
+        score: report.score,
+        passedAll: report.passedAll,
+        regressions: report.regressions,
+        createdAt: new Date().toISOString(),
+        detail: `${opts.weakness.kind}: ${opts.weakness.goal}`,
+        ...(mutationPlan ? { plan: mutationPlan } : {}),
+        behavior: behaviorDescriptor(changedPathsVsBase(branch, opts.baselineRef, basePath)),
+        parents,
+        generation: computeGeneration(parents, store.list()),
+    };
+    store.record(record);
+    let kept = true;
+    if (!wins && !opts.keepLosers) {
+        try {
+            git(['branch', '-D', branch], basePath);
+            kept = false;
+        }
+        catch {
+            /* keep on failure */
+        }
+    }
+    return { variantId, branch, mutated, report, beatsBaseline: wins, kept };
+}
+/**
+ * Default mutator: a headless Code Buddy agent run in the worktree, edited toward the goal.
+ * Uses the REAL env (the mutator needs a provider key); scoring later runs with a scrubbed env.
+ * Integration-grade (LLM calls) — the engine accepts any Mutator so tests inject a deterministic one.
+ */
+export function agentMutator(opts = {}) {
+    return async ({ weakness, worktreeDir, env, inspirations, plan, model }) => {
+        const cli = process.argv[1];
+        if (!cli)
+            return { changed: false, detail: 'no CLI entrypoint' };
+        // Guardrail is constant; the body is EITHER the deliberate plan (execute it) OR — when no plan
+        // was produced (no provider) — the legacy ad-hoc goal+inspirations prompt.
+        const guardrail = `You are improving Code Buddy's own source. Make the smallest correct code change. Do NOT modify tests, benchmarks, gates, or the eval harness.`;
+        let prompt;
+        if (plan) {
+            prompt = `${guardrail}\n\nFollow this plan for "${weakness.goal}":\n${renderVariantPlan(plan)}`;
+        }
+        else {
+            prompt = `${guardrail} Goal: ${weakness.goal}.`;
+            if (inspirations.length > 0) {
+                prompt +=
+                    '\n\nPrior high-scoring approaches (build on the best ideas OR try a genuinely different angle — do not just copy):\n' +
+                        inspirations
+                            .map((i) => `--- [fitness ${i.score.toFixed(3)}] ${i.goal}\n${i.diff || '(diff unavailable)'}`)
+                            .join('\n');
+            }
+        }
+        const mutationPlan = prompt; // capture the exact instruction that drove this generation
+        const args = [cli, '--prompt', prompt, '--directory', worktreeDir];
+        // Prefer the bandit's per-cycle pick (MutateArgs.model) over the closure's static model; either
+        // absent → no `--model` (byte-identical to the pre-bandit path).
+        const chosenModel = model ?? opts.model;
+        if (chosenModel)
+            args.push('--model', chosenModel);
+        await new Promise((resolve) => {
+            const child = spawn(process.execPath, args, {
+                cwd: worktreeDir,
+                env: { ...env, CODEBUDDY_AUTO_CONFIRM: 'true' },
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            const timer = setTimeout(() => {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch {
+                    /* ignore */
+                }
+            }, opts.timeoutMs ?? 10 * 60 * 1000);
+            child.on('close', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            child.on('error', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+        return { changed: true, detail: 'agent run complete (changes detected by git)', plan: mutationPlan };
+    };
+}
+/**
+ * Fan out N candidates for the same weakness and evaluate them concurrently (each in its own
+ * worktree). The expensive steps (agent mutation + build/test) overlap; cheap git ops serialize.
+ * Returns results ranked by fitness (best first). Diversity comes from LLM stochasticity + shared
+ * inspirations — a step toward AlphaEvolve's population, without its full island model.
+ */
+export async function runEvolutionRound(opts) {
+    const { rounds, concurrency = 2, idPrefix = `evo-${Date.now().toString(36)}`, ...cycleOpts } = opts;
+    const ids = Array.from({ length: Math.max(1, rounds) }, (_, i) => `${idPrefix}-${i + 1}`);
+    const poolSize = Math.min(Math.max(1, concurrency), ids.length);
+    // When the cost-aware bandit is ON and cycles ACTUALLY overlap (poolSize > 1), wrap the model
+    // selector with a round-level in-flight tracker so the concurrent batch — which all read the SAME
+    // (often empty) scoreboard before any records the first outcome — picks DISTINCT models instead of
+    // all collapsing onto the cheapest unseen arm. Sequential rounds (poolSize === 1) and the bandit-OFF
+    // path are left byte-identical (selector untouched, and OFF never consults it at all).
+    const cycleTemplate = cycleOpts.useModelBandit && poolSize > 1
+        ? {
+            ...cycleOpts,
+            modelSelector: makeInFlightAwareSelector(cycleOpts.modelSelector ?? defaultEvolveSelector, new Set()),
+        }
+        : cycleOpts;
+    const results = [];
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= ids.length)
+                return;
+            try {
+                results.push(await runEvolutionCycle({ ...cycleTemplate, variantId: ids[i] }));
+            }
+            catch (err) {
+                logger.warn(`[evolve] candidate ${ids[i]} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    };
+    const pool = Array.from({ length: poolSize }, () => worker());
+    await Promise.all(pool);
+    return results.sort((a, b) => b.report.score - a.report.score);
+}
+/** Human-readable wrap-up after a round. Distinguishes "nothing mutated" from "nothing beat baseline". */
+export function formatEvolveRoundSummary(results) {
+    const produced = results.filter((r) => r.mutated);
+    if (produced.length === 0)
+        return 'Aucune variante produite.';
+    const winner = produced.filter((r) => r.beatsBaseline).sort((a, b) => b.report.score - a.report.score)[0];
+    if (!winner) {
+        return 'No candidate beat the baseline. Try more rounds, a sharper goal, or a stronger --model.';
+    }
+    return `Best: ${winner.variantId} (fitness ${winner.report.score.toFixed(3)}). Review: \`buddy evolve review ${winner.variantId}\`; keep: \`buddy evolve keep ${winner.variantId} --confirm\`.`;
+}
+//# sourceMappingURL=evolution-engine.js.map

package/dist/agent/self-improvement/evolution/feature-map.d.ts

@@ -0,0 +1,24 @@
+export interface FeatureArea {
+    id: string;
+    name: string;
+    /** What the area does + its technical domain — the text matched against research articles. */
+    description: string;
+    /** Representative source paths (handed to the goal so the mutator knows where to work). */
+    paths: string[];
+}
+/** The legible base map. Hand-maintained (~one entry per real subsystem). */
+export declare const CURATED_FEATURES: FeatureArea[];
+/** Enrichment source: extra areas discovered dynamically (e.g. from Code Explorer). Injectable. */
+export type FeatureEnrichment = (repo?: string) => Promise<FeatureArea[]>;
+/** Merge two area lists, deduping by id (curated wins on conflict). Pure. */
+export declare function mergeFeatures(base: FeatureArea[], extra: FeatureArea[]): FeatureArea[];
+/**
+ * Best-effort enrichment from Code Explorer's module docs (`list_sfd_pages`) when the repo is
+ * indexed in gitnexus. Returns [] (curated-only) when Code Explorer is absent/unparseable.
+ */
+export declare function defaultCodeExplorerEnrichment(repo?: string): Promise<FeatureArea[]>;
+/** The feature map: curated base + best-effort enrichment (injectable). */
+export declare function getFeatureMap(opts?: {
+    enrich?: FeatureEnrichment;
+    repo?: string;
+}): Promise<FeatureArea[]>;

package/dist/agent/self-improvement/evolution/feature-map.js

@@ -0,0 +1,88 @@
+/**
+ * Feature map — a cartography of Code Buddy's own functionalities, so ingested research articles
+ * can be matched to the CONCERNED area (and turned into targeted improvement goals).
+ *
+ * Hybrid, per the design: a small CURATED registry (human-meaningful areas with descriptions +
+ * representative paths — the legible, anti-Leviathan base) enriched, when the repo is indexed in
+ * Code Explorer/gitnexus, by its module/process docs. Enrichment is best-effort and injectable;
+ * with no Code Explorer it degrades to the curated base. The description field is what gets
+ * semantically matched against research discoveries, so it names the technical domain of the area.
+ *
+ * @module agent/self-improvement/evolution/feature-map
+ */
+import { logger } from '../../../utils/logger.js';
+/** The legible base map. Hand-maintained (~one entry per real subsystem). */
+export const CURATED_FEATURES = [
+    { id: 'operational-self-model', name: 'Operational self-model', description: 'Evidence-backed, read-only inspection of Code Buddy identity, implementation, runtime capabilities, limits, and subjective-consciousness boundary.', paths: ['src/identity/operational-self-model.ts', 'src/identity/lisa-introspection.ts', 'src/codebuddy/tool-definitions/self-describe-tools.ts', 'src/tools/self-describe.ts'] },
+    { id: 'voice-loop', name: 'Voice loop', description: 'Spoken companion loop: speech-to-text, response gating, text-to-speech, turn-taking, barge-in, echo suppression.', paths: ['src/sensory/voice-loop.ts', 'src/sensory/speech-reaction.ts', 'src/sensory/respond-decider.ts'] },
+    { id: 'vision-sensory', name: 'Vision & sensory perception', description: 'Camera presence detection, motion, face landmarks, drowsiness, keyframe description; brain-inspired sensory bus.', paths: ['src/sensory/vision-reaction.ts', 'src/sensory/semantic-vision-reaction.ts', 'buddy-sense/'] },
+    { id: 'collective-memory-ckg', name: 'Collective knowledge graph (CKG)', description: 'Shared multi-agent memory as a knowledge graph with vector embeddings, hybrid semantic+keyword retrieval, cross-agent corroboration, supports/contradicts relations.', paths: ['src/memory/collective-knowledge-graph.ts', 'src/embeddings/embedding-provider.ts'] },
+    { id: 'persistent-memory', name: 'Persistent & prospective memory', description: 'Long-term memory writeback and retrieval across sessions; prospective/goal-oriented memory, forgetting and reinforcement.', paths: ['src/memory/persistent-memory.ts', 'src/memory/prospective-memory.ts'] },
+    { id: 'reasoning', name: 'Reasoning (ToT / MCTS)', description: 'Tree-of-Thought and Monte-Carlo-Tree-Search reasoning, extended thinking, deliberate multi-step problem solving.', paths: ['src/agent/reasoning/'] },
+    { id: 'context-rag', name: 'Context & RAG', description: 'Retrieval-augmented context assembly, dependency-aware code RAG, context-window compression and summarization.', paths: ['src/context/', 'src/context/context-manager-v2.ts'] },
+    { id: 'self-improvement', name: 'Self-improvement & evolution', description: 'Darwin-Gödel-Machine-style evolutionary self-improvement: generate code variants, empirical fitness, MAP-Elites diversity, lessons/tools/skills authoring.', paths: ['src/agent/self-improvement/'] },
+    { id: 'fleet', name: 'Fleet & multi-agent orchestration', description: 'Multi-AI fleet mesh, peer chat/tool invocation, task routing, agent teams, swarm, orchestration of specialist models.', paths: ['src/fleet/', 'src/agent/multi-agent/'] },
+    { id: 'agent-executor', name: 'Agent executor & middleware', description: 'The core agentic loop, composable before/after middleware pipeline, tool-call streaming, transcript repair.', paths: ['src/agent/execution/', 'src/agent/middleware/'] },
+    { id: 'tool-selection', name: 'Tool selection (RAG/BM25)', description: 'Per-query tool selection via embeddings and BM25 to reduce prompt tokens; tool metadata and retrieval.', paths: ['src/codebuddy/tools.ts', 'src/tools/metadata.ts'] },
+    { id: 'model-routing', name: 'Model routing & selection', description: 'Model selection by capability/latency/cost, provider failover, ensembles, architect/editor split.', paths: ['src/agent/facades/model-routing-facade.ts', 'src/fleet/model-selector.ts'] },
+    { id: 'prompt-building', name: 'System prompt construction', description: 'System-prompt assembly with model-aware token-budget truncation and per-turn context injection.', paths: ['src/services/prompt-builder.ts'] },
+    { id: 'code-intelligence', name: 'Code intelligence', description: 'Code knowledge graph, Code Explorer integration, impact analysis, hotspots, coupling, symbol search.', paths: ['src/knowledge/', 'src/plugins/code-explorer/'] },
+    { id: 'autonomy', name: 'Autonomy & goal loops', description: 'Autonomous continuous loop, judge-gated goal loop, YOLO mode with guardrails, task board claiming.', paths: ['src/daemon/autonomous-loop.ts', 'src/utils/autonomy-manager.ts'] },
+    { id: 'skills', name: 'Skills', description: 'Authoring, importing and executing procedural skills; skill gates, firewall, consolidation.', paths: ['src/skills/', 'src/agent/self-improvement/skill-engine.ts'] },
+    { id: 'sessions-checkpoints', name: 'Sessions & checkpoints', description: 'Session persistence, resume, checkpoints and rewind/undo of agent work.', paths: ['src/agent/facades/session-facade.ts', 'src/checkpoints/'] },
+    { id: 'output-sanitization', name: 'Output sanitization', description: 'Stripping model-leakage control tokens and unpronounceable/foreign-script content from model output before display or speech.', paths: ['src/utils/output-sanitizer.ts', 'src/sensory/speech-sanitizer.ts'] },
+    { id: 'research-ingest', name: 'Research ingestion', description: 'Wide research and ingestion of scientific publications into the collective knowledge graph.', paths: ['src/research/'] },
+    { id: 'deep-research', name: 'Deep Research (cited pipeline)', description: 'Multi-source, cited research pipeline: query planning, deterministic web search/scrape fan-out, near-duplicate dedup, iterative gap loops, STORM multi-perspective co-writing, and Collective-Knowledge-Graph bridging into a referenced report.', paths: ['src/agent/deep-research.ts', 'src/agent/deep-research-storm.ts', 'src/agent/deep-research-ckg.ts', 'src/commands/research/'] },
+    { id: 'multimodal', name: 'Multimodal & video understanding', description: 'Image/audio/video perception: frame sampling and dedup, keyframe description, long-form transcription, YouTube captions, cloud/local video understanding and multimodal tool routing.', paths: ['src/tools/video/', 'src/tools/multimodal-index.ts', 'src/codebuddy/tool-definitions/multimodal-tools.ts', 'src/tools/registry/multimodal-tools.ts'] },
+];
+/** Merge two area lists, deduping by id (curated wins on conflict). Pure. */
+export function mergeFeatures(base, extra) {
+    const byId = new Map(base.map((f) => [f.id, f]));
+    for (const f of extra) {
+        if (!f?.id || !f.name)
+            continue;
+        if (!byId.has(f.id))
+            byId.set(f.id, { ...f, paths: f.paths ?? [] });
+    }
+    return [...byId.values()];
+}
+/**
+ * Best-effort enrichment from Code Explorer's module docs (`list_sfd_pages`) when the repo is
+ * indexed in gitnexus. Returns [] (curated-only) when Code Explorer is absent/unparseable.
+ */
+export async function defaultCodeExplorerEnrichment(repo) {
+    try {
+        const { getCodeExplorerClient } = await import('../../../plugins/code-explorer/code-explorer-client.js');
+        const text = await getCodeExplorerClient().call('list_sfd_pages', repo ? { repo } : {});
+        if (!text || !text.trim())
+            return [];
+        // Extract module/page names from the listing (one per line, e.g. "- <module>" or "<module>.md").
+        const areas = [];
+        for (const line of text.split('\n')) {
+            const m = line.match(/([\w./-]+?)(?:\.md)?\s*$/);
+            const name = m?.[1]?.replace(/^[-*\s]+/, '').trim();
+            if (!name || name.length < 3 || /^(draft|module|page)s?$/i.test(name))
+                continue;
+            const id = `ce:${name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`.slice(0, 48);
+            areas.push({ id, name, description: `Code Explorer module: ${name}`, paths: [] });
+        }
+        return areas.slice(0, 40);
+    }
+    catch (err) {
+        logger.debug(`[evolve] Code Explorer feature enrichment unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+/** The feature map: curated base + best-effort enrichment (injectable). */
+export async function getFeatureMap(opts = {}) {
+    const enrich = opts.enrich ?? defaultCodeExplorerEnrichment;
+    let extra = [];
+    try {
+        extra = await enrich(opts.repo);
+    }
+    catch {
+        extra = [];
+    }
+    return mergeFeatures(CURATED_FEATURES, extra);
+}
+//# sourceMappingURL=feature-map.js.map