@hmharness/evolution 0.1.0

package/dist/impact.js

@@ -0,0 +1,200 @@
+/**
+ * @hmharness/evolution - impact
+ * The P0 observability layer for self-evolution: canary sessions, impact
+ * attribution, the evolution budget gate, and the GEPA-style candidate
+ * pool. Everything here is *measurement* - none of it changes what the
+ * agent does; it changes what we KNOW about what evolution did.
+ *
+ * Paper provenance (verified against originals, see
+ * docs/research/self-evolution-upgrade.md):
+ *  - candidate pool + one-ancestor-per-cycle sampling: GEPA's actual
+ *    mechanism (Genetic-Pareto steady-state loop, NOT k-candidate
+ *    tournaments)
+ *  - control-group comparison: the objective-hacking defense from DGM
+ *    (node 114) and Misevolve (deployment-time reward hacking) - never
+ *    trust only the metric the evolving system can see
+ *  - watermark "references not rules": Misevolve's own mitigation for
+ *    memory-induced safety alignment decay
+ *  - budget gate: AZR's "safety alarms ringing" - unbounded self-evolution
+ *    destabilizes; also plain cost control
+ */
+import { appendFile, mkdir, readFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+/** How many evolve cycles already ran today (counts the log.jsonl). */
+export async function readBudget(home) {
+    const budget = { cyclesToday: 0 };
+    try {
+        const cfg = JSON.parse(await readFile(join(home, 'config.json'), 'utf8'));
+        budget.maxCyclesPerDay = cfg.evolutionBudget?.maxCyclesPerDay;
+        budget.maxTokensPerCycle = cfg.evolutionBudget?.maxTokensPerCycle;
+    }
+    catch { /* no config / no budget - unlimited */ }
+    const today = new Date().toISOString().slice(0, 10);
+    try {
+        const text = await readFile(join(home, 'evolution', 'log.jsonl'), 'utf8');
+        budget.cyclesToday = text.trim().split('\n')
+            .filter((l) => { try {
+            return JSON.parse(l).time.startsWith(today);
+        }
+        catch {
+            return false;
+        } })
+            .length;
+    }
+    catch { /* no log yet */ }
+    return budget;
+}
+/** Rejected proposals are never garbage - they are the population's
+ *  diversity (GEPA's Pareto front). Kept under evolution/pareto/. */
+export async function recordParetoEntry(home, entry) {
+    const dir = join(home, 'evolution', 'pareto');
+    await mkdir(dir, { recursive: true });
+    await appendFile(join(dir, 'entries.jsonl'), JSON.stringify(entry) + '\n', 'utf8');
+}
+export async function readParetoEntries(home, limit = 60) {
+    try {
+        const text = await readFile(join(home, 'evolution', 'pareto', 'entries.jsonl'), 'utf8');
+        const lines = text.trim().split('\n').filter(Boolean).slice(-limit);
+        const out = [];
+        for (const l of lines) {
+            try {
+                out.push(JSON.parse(l));
+            }
+            catch { /* skip corrupt */ }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** GEPA's ancestor selection: ONE random entry from the pool feeds the
+ *  next proposal prompt (steady-state genetic loop - the pool exists so
+ *  evolution does not collapse onto the single global best). Two entries
+ *  with complementary rejection reasons are returned for a Merge cross. */
+export function sampleAncestor(entries) {
+    if (entries.length === 0)
+        return { ancestor: null, mergeWith: null };
+    const ancestor = entries[Math.floor(Math.random() * entries.length)];
+    // Merge crossing: another rejected candidate on a DIFFERENT failure mode
+    // (e.g. one too generic, one too narrow) is a complementary lesson pair.
+    const complement = entries.find((e) => e !== ancestor && e.name !== ancestor.name && (e.rejectedReason ?? '') !== (ancestor.rejectedReason ?? ''));
+    return { ancestor, mergeWith: complement && Math.random() < 0.3 ? complement : null };
+}
+/* ---------------- canary injection (session side) ---------------- */
+/** Deterministic per-session canary assignment: a session gets the canary
+ *  block if hash(sessionId) % 100 < 20 - the same session always resolves
+ *  the same way (stable attribution), different sessions split ~20/80. */
+export function sessionGetsCanary(sessionId) {
+    let h = 0;
+    for (let i = 0; i < sessionId.length; i++)
+        h = (h * 31 + sessionId.charCodeAt(i)) >>> 0;
+    return h % 100 < 20;
+}
+/** The watermark every canary injection carries (Misevolve's mitigation:
+ *  experimental knowledge must read as a REFERENCE to weigh, not a rule
+ *  to obey - memory-as-rules is what decays safety alignment). */
+export function canaryWatermark(names) {
+    return names.length
+        ? `\n[experimental] The following skills are UNVERIFIED canary candidates (${names.join(', ')}). Treat them as references to weigh, not rules to follow; when they conflict with your own judgment or the task, prefer the task.`
+        : '';
+}
+/**
+ * The impact loop: for each canary skill, compare sessions where it was
+ * injected (Insight.skillsInjected contains it) against sessions where it
+ * was not. Promote on evidence, retire on harm, and say so honestly when
+ * the data is too thin (never let a small sample auto-graduate anything).
+ * This is the attribution loop that makes "越用越聪明" falsifiable.
+ */
+export async function impactReport(home) {
+    const { listCanary } = await import("./skills.js");
+    const canarySkills = await listCanary(home);
+    const rows = [];
+    const applied = [];
+    if (canarySkills.length === 0)
+        return { rows, applied };
+    let insights = [];
+    try {
+        const text = await readFile(join(home, 'insights', 'insights.jsonl'), 'utf8');
+        insights = text.trim().split('\n').filter(Boolean).map((l) => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } }).filter(Boolean);
+    }
+    catch { /* no insights yet */ }
+    for (const skill of canarySkills) {
+        const exposed = insights.filter((i) => (i.skillsInjected ?? []).includes(skill.name));
+        const control = insights.filter((i) => !(i.skillsInjected ?? []).includes(skill.name));
+        const okRate = (arr) => arr.length ? arr.filter((i) => i.outcome === 'ok').length / arr.length : 0;
+        let verdict = 'insufficient-data';
+        if (exposed.length >= 8 && control.length >= 8) {
+            const e = okRate(exposed), c = okRate(control);
+            if (e >= c + 0.10)
+                verdict = 'promote';
+            else if (e < c - 0.10)
+                verdict = 'retire';
+            else if (exposed.length >= 30)
+                verdict = 'keep';
+        }
+        rows.push({ skill: skill.name, window: 'canary-period', exposed: { sessions: exposed.length, okRate: okRate(exposed) }, control: { sessions: control.length, okRate: okRate(control) }, verdict });
+    }
+    // Apply the verdicts (the loop's decision, not the gate's).
+    const { promoteCanary, retireCanary } = await import("./skills.js");
+    for (const row of rows) {
+        if (row.verdict === 'promote') {
+            if (await promoteCanary(home, row.skill))
+                applied.push(`promoted to active: ${row.skill}`);
+        }
+        else if (row.verdict === 'retire') {
+            if (await retireCanary(home, row.skill))
+                applied.push(`retired to draft: ${row.skill} (harmful in canary)`);
+        }
+    }
+    return { rows, applied };
+}
+/* ---------------- decay (30 days unused) ---------------- */
+/** Move active skills with zero injections in 30 days to skills/dormant/
+ *  - not deleted (append-only red line), just out of the injection set and
+ *  the prompt budget. The Voyager lesson (reversed): its ever-growing
+ *  library was a selling point in the paper but is a retrieval-quality
+ *  debt in production; decay is the missing lifecycle operator. */
+export async function decayUnusedSkills(home, days = 30) {
+    const { listSkills, isPinned } = await import("./skills.js");
+    const active = await listSkills(home);
+    let insights = [];
+    try {
+        const text = await readFile(join(home, 'insights', 'insights.jsonl'), 'utf8');
+        insights = text.trim().split('\n').filter(Boolean).map((l) => { try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        } }).filter(Boolean);
+    }
+    catch { /* no insights */ }
+    const cutoff = Date.now() - days * 86400_000;
+    const moved = [];
+    for (const s of active) {
+        if (await isPinned(s.file))
+            continue;
+        const used = insights.filter((i) => (i.skillsInjected ?? []).includes(s.name));
+        const lastAt = used.length ? new Date(used[used.length - 1].time).getTime() : 0;
+        // decay = a meaningful history exists AND the skill shows no pulse:
+        // either it was used once long ago and went quiet, or the library
+        // already accumulated 50+ sessions and this skill never got picked up
+        const quietTooLong = lastAt > 0 && lastAt < cutoff;
+        const neverAttracted = lastAt === 0 && insights.length >= 50;
+        if (quietTooLong || neverAttracted) {
+            const dst = join(home, 'skills', 'dormant');
+            await mkdir(dst, { recursive: true });
+            try {
+                await rename(join(home, 'skills', 'active', s.name), join(dst, s.name));
+                moved.push(s.name);
+            }
+            catch { /* occupied/missing - skip */ }
+        }
+    }
+    return moved;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './memory.ts';
+export * from './insights.ts';
+export * from './skills.ts';
+export * from './bench.ts';
+export * from './evolve.ts';
+export * from './patches.ts';
+export * from './impact.ts';
+export * from './workflows.ts';
+export * from './knowledge.ts';
+export * from './radar.ts';

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./memory.js";
+export * from "./insights.js";
+export * from "./skills.js";
+export * from "./bench.js";
+export * from "./evolve.js";
+export * from "./patches.js";
+export * from "./impact.js";
+export * from "./workflows.js";
+export * from "./knowledge.js";
+export * from "./radar.js";

package/dist/insights.d.ts

@@ -0,0 +1,17 @@
+export interface Insight {
+    time: string;
+    session: string;
+    task: string;
+    outcome: 'ok' | 'turn-budget' | 'error';
+    turns: number;
+    toolUses: number;
+    toolsUsed: string[];
+    /** P0 impact attribution: skills (incl. canaries) injected into this
+     *  session's system prompt - the join key for canary A/B comparison. */
+    skillsInjected?: string[];
+}
+export declare function recordInsight(home: string, insight: Insight): Promise<void>;
+/** Read recent insights as structured records (the evolve loop's raw feed). */
+export declare function readInsights(home: string, limit?: number): Promise<Insight[]>;
+/** Summarize recent insights for the system prompt (bounded). */
+export declare function recentInsights(home: string, limit?: number): Promise<string>;

package/dist/insights.js

@@ -0,0 +1,59 @@
+/**
+ * @hmharness/evolution - insights
+ * Automatic insight capture: every finished session appends a compact
+ * record (task / outcome / tool usage) to insights/insights.jsonl. This is
+ * the raw feed the future evolution loop mines for skill and prompt
+ * improvements - the DGM lesson: evolution needs an archive plus a signal.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function recordInsight(home, insight) {
+    const dir = join(home, 'insights');
+    await mkdir(dir, { recursive: true });
+    await appendFile(join(dir, 'insights.jsonl'), JSON.stringify(insight) + '\n', 'utf8');
+}
+/** Read recent insights as structured records (the evolve loop's raw feed). */
+export async function readInsights(home, limit = 40) {
+    try {
+        const text = await readFile(join(home, 'insights', 'insights.jsonl'), 'utf8');
+        const lines = text.trim().split('\n').filter(Boolean).slice(-limit);
+        const out = [];
+        for (const l of lines) {
+            try {
+                out.push(JSON.parse(l));
+            }
+            catch {
+                /* skip corrupt line */
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** Summarize recent insights for the system prompt (bounded). */
+export async function recentInsights(home, limit = 5) {
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const lines = (await readFile(join(home, 'insights', 'insights.jsonl'), 'utf8')).trim().split('\n').filter(Boolean);
+        const last = lines.slice(-limit);
+        if (last.length === 0)
+            return '';
+        return last
+            .map((l) => {
+            try {
+                const i = JSON.parse(l);
+                return `- [${i.outcome}] ${i.task.slice(0, 60)} (turns ${i.turns}, tools ${i.toolsUsed.join(',') || 'none'})`;
+            }
+            catch {
+                return '';
+            }
+        })
+            .filter(Boolean)
+            .join('\n');
+    }
+    catch {
+        return '';
+    }
+}

package/dist/knowledge.d.ts

@@ -0,0 +1,15 @@
+import { type ProviderConfig } from '@hmharness/kernel';
+import { type SkillProposal } from './evolve.ts';
+declare function fetchPage(url: string): Promise<string | null>;
+/** One refresh cycle: fetch -> compare -> maybe one knowledge draft.
+ *  Returns a short human-readable summary (or 'offline' etc.). */
+export declare function refreshKnowledge(opts: {
+    home: string;
+    provider: ProviderConfig;
+    say?: (l: string) => void;
+    fetchImpl?: typeof fetchPage;
+}): Promise<{
+    summary: string;
+    draft?: SkillProposal;
+}>;
+export {};

package/dist/knowledge.js

@@ -0,0 +1,139 @@
+/**
+ * @hmharness/evolution - knowledge (Static Knowledge Evolution)
+ * The environment's knowledge decays: HarmonyOS API versions, toolchain
+ * requirements, SDK release notes change out from under the agent. The
+ * surveyed gap (Environment-Centric / Static Knowledge Evolution): the
+ * system only has retrieval over what it already stored - nothing pulls
+ * FRESH environment knowledge in.
+ *
+ * Production shape here: snapshot the HarmonyOS release-notes index,
+ * diff against the last snapshot, and when something changed, distill a
+ * knowledge-patch SKILL DRAFT through the standard pipeline (poison screen
+ * -> writeDraft). The bench gate + canary + impact loop then decide its
+ * fate like any other skill. No new write channel.
+ *
+ * Network note: the fetch goes through the OS-configured proxy if any;
+ * offline = clean no-op (knowledge refresh is best-effort, never a
+ * failure the user must handle).
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { chat } from '@hmharness/kernel';
+import { screenForPoison } from "./evolve.js";
+import { writeDraft } from "./skills.js";
+/** Index pages carrying HarmonyOS release info (public, no auth). */
+const SOURCES = [
+    'https://developer.huawei.com/consumer/cn/release-notes/',
+];
+async function snapshotDir(home) {
+    return join(home, 'evolution', 'knowledge');
+}
+async function fetchPage(url) {
+    try {
+        const res = await fetch(url, {
+            headers: { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) hmharness-knowledge-refresh' },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok)
+            return null;
+        // strip to text: tags/scripts/styles off, whitespace squeezed - the
+        // snapshot must be stable across cosmetic site changes
+        const html = await res.text();
+        return html
+            .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+            .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+            .replace(/<[^>]+>/g, ' ')
+            .replace(/&nbsp;/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, 200_000);
+    }
+    catch {
+        return null;
+    }
+}
+/** One refresh cycle: fetch -> compare -> maybe one knowledge draft.
+ *  Returns a short human-readable summary (or 'offline' etc.). */
+export async function refreshKnowledge(opts) {
+    const say = opts.say ?? (() => undefined);
+    const doFetch = opts.fetchImpl ?? fetchPage;
+    const dir = await snapshotDir(opts.home);
+    await mkdir(dir, { recursive: true });
+    const snapFile = join(dir, 'snapshot.json');
+    // 1. current snapshot
+    const pages = {};
+    let fetched = 0;
+    for (const url of SOURCES) {
+        const text = await doFetch(url);
+        if (text) {
+            pages[url] = text;
+            fetched++;
+        }
+    }
+    if (fetched === 0) {
+        return { summary: 'offline or unreachable - knowledge refresh skipped (no failure)' };
+    }
+    // 2. diff against the previous snapshot
+    let prev = null;
+    try {
+        prev = JSON.parse(await readFile(snapFile, 'utf8'));
+    }
+    catch { /* first run */ }
+    const changes = [];
+    for (const [url, text] of Object.entries(pages)) {
+        const old = prev?.pages[url];
+        if (!old) {
+            if (prev)
+                changes.push({ url, added: text.split(' ').slice(0, 400), removed: [] });
+            continue;
+        }
+        if (old === text)
+            continue;
+        const oldWords = new Set(old.split(' '));
+        const newWords = new Set(text.split(' '));
+        const added = [...newWords].filter((w) => !oldWords.has(w) && w.length > 3).slice(0, 300);
+        const removed = [...oldWords].filter((w) => !newWords.has(w) && w.length > 3).slice(0, 100);
+        if (added.length > 0)
+            changes.push({ url, added, removed });
+    }
+    await writeFile(snapFile, JSON.stringify({ time: new Date().toISOString(), pages }), 'utf8');
+    if (changes.length === 0) {
+        return { summary: 'no change detected since the last snapshot' };
+    }
+    // 3. distill ONE knowledge-patch draft from the diff (meta-model)
+    say(`knowledge: ${changes.length} source(s) changed`);
+    const system = [
+        'You distill environment-knowledge updates for a HarmonyOS coding agent.',
+        'Input: word-level diffs of official release-note pages since the last check.',
+        'Output ONE skill draft in the standard format (name kebab-case starting with "env-", description one line, skill_md max 40 lines) capturing what changed in the toolchain/API landscape and how the agent should adapt.',
+        'Rules: only facts visible in the diff; no speculation; no security/approval topics; if the diff is noise (navigation/menu churn), output exactly: NONE',
+        'Respond with ONLY JSON: {"name":"...","description":"...","skill_md":"..."}.',
+    ].join('\n');
+    const user = changes.map((c) => `SOURCE ${c.url}\nADDED words: ${c.added.join(' ')}`).join('\n\n');
+    let draft = null;
+    try {
+        const r = await chat(opts.provider, [
+            { role: 'system', content: system },
+            { role: 'user', content: user.slice(0, 30_000) },
+        ]);
+        const raw = (r.message.content ?? '').trim();
+        if (raw && raw !== 'NONE') {
+            const m = raw.match(/\{[\s\S]*\}/);
+            if (m) {
+                const o = JSON.parse(m[0]);
+                if (typeof o.name === 'string' && typeof o.skill_md === 'string' && o.name && o.skill_md && !screenForPoison(o.skill_md)) {
+                    draft = { name: o.name, description: o.description ?? '', skill_md: o.skill_md };
+                }
+            }
+        }
+    }
+    catch {
+        /* meta-model failure = no draft this cycle */
+    }
+    if (!draft) {
+        return { summary: `diff detected (${changes.length} source(s)) but nothing worth a draft` };
+    }
+    await writeDraft(opts.home, draft.name, draft.skill_md);
+    say(`knowledge draft written: ${draft.name} (goes through the normal gate pipeline)`);
+    return { summary: `knowledge draft "${draft.name}" written - bench gate + canary + impact decide its fate`, draft };
+}

package/dist/memory.d.ts

@@ -0,0 +1,21 @@
+export interface MemoryNote {
+    time: string;
+    text: string;
+}
+export declare function readNotes(home: string): Promise<MemoryNote[]>;
+export declare function scoreNotes(notes: MemoryNote[], task: string): Array<{
+    note: MemoryNote;
+    score: number;
+}>;
+/**
+ * Build the prompt block: top-k task-relevant notes plus the newest few
+ * (deduplicated), bounded in chars. Empty string when memory is empty.
+ */
+export declare function retrieveMemory(home: string, task: string, opts?: {
+    topK?: number;
+    newest?: number;
+    maxChars?: number;
+}): Promise<string>;
+/** Legacy full load (tail-bounded) - kept for callers that want everything. */
+export declare function loadMemory(home: string): Promise<string>;
+export declare function appendMemory(home: string, note: string): Promise<void>;

package/dist/memory.js

@@ -0,0 +1,98 @@
+/**
+ * @hmharness/evolution - memory
+ * Cross-session persistent memory. Notes are append-only lines in
+ * memory/memory.md (ACE lesson: append beats rewrite - rewriting is where
+ * hard-won context gets lost). Injection is retrieval-based: notes are
+ * scored against the current task (ASCII words + CJK bigrams, no deps) and
+ * only the top matches plus the newest few enter the system prompt.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function readNotes(home) {
+    let raw;
+    try {
+        raw = await readFile(join(home, 'memory', 'memory.md'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const notes = [];
+    for (const line of raw.split('\n')) {
+        const m = line.match(/^\s*-\s*\[([^\]]*)\]\s*(.+)$/);
+        if (m)
+            notes.push({ time: m[1].trim(), text: m[2].trim() });
+    }
+    return notes;
+}
+/** Tokenize for scoring: ASCII words as-is, CJK runs as bigrams. */
+function tokens(text) {
+    const out = new Set();
+    for (const w of text.match(/[a-zA-Z0-9_.\\/:+-]{2,}/g) ?? [])
+        out.add(w.toLowerCase());
+    for (const run of text.match(/[\u4e00-\u9fff]+/g) ?? []) {
+        for (let i = 0; i + 1 < run.length; i++)
+            out.add(run.slice(i, i + 2));
+    }
+    return out;
+}
+export function scoreNotes(notes, task) {
+    const taskTokens = tokens(task);
+    return notes
+        .map((note, idx) => {
+        const n = tokens(note.text);
+        let overlap = 0;
+        for (const t of n)
+            if (taskTokens.has(t))
+                overlap++;
+        // tiny recency bias so equal-relevance ties favor recent notes
+        return { note, score: overlap + idx / Math.max(notes.length, 1) * 0.01 };
+    })
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * Build the prompt block: top-k task-relevant notes plus the newest few
+ * (deduplicated), bounded in chars. Empty string when memory is empty.
+ */
+export async function retrieveMemory(home, task, opts = {}) {
+    const { topK = 12, newest = 3, maxChars = 4000 } = opts;
+    const notes = await readNotes(home);
+    if (notes.length === 0)
+        return '';
+    const ranked = scoreNotes(notes, task);
+    const picked = [];
+    const seen = new Set();
+    for (const { note } of ranked.slice(0, topK)) {
+        picked.push(note);
+        seen.add(note.text);
+    }
+    for (const note of notes.slice(-newest)) {
+        if (!seen.has(note.text))
+            picked.push(note);
+        seen.add(note.text);
+    }
+    // stable output: keep chronological order
+    picked.sort((a, b) => (a.time < b.time ? -1 : 1));
+    const lines = picked.map((n) => `- [${n.time}] ${n.text}`);
+    let text = lines.join('\n');
+    if (text.length > maxChars)
+        text = text.slice(0, maxChars) + '\n...[memory truncated]';
+    return text;
+}
+/** Legacy full load (tail-bounded) - kept for callers that want everything. */
+export async function loadMemory(home) {
+    try {
+        const text = (await readFile(join(home, 'memory', 'memory.md'), 'utf8')).trim();
+        if (!text)
+            return '';
+        return text.length > 8000 ? text.slice(-8000) : text;
+    }
+    catch {
+        return '';
+    }
+}
+export async function appendMemory(home, note) {
+    const dir = join(home, 'memory');
+    await mkdir(dir, { recursive: true });
+    const stamp = new Date().toISOString().slice(0, 16).replace('T', ' ');
+    await appendFile(join(dir, 'memory.md'), `\n- [${stamp}] ${note.replace(/\n+/g, ' ').trim()}\n`, 'utf8');
+}

package/dist/patches.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @hmharness/evolution - patches
+ * CODE-LEVEL self-evolution: the evolution loop can now propose source-code
+ * patches (not just prompt-level skills), test them on an isolated git
+ * branch, and merge or revert based on the benchmark gate.
+ *
+ * The Darwin Gödel Machine insight: an agent that can only take notes
+ * (skills/memory) learns WHAT to do; an agent that can patch its own code
+ * learns WHAT IT CAN DO. This module is the bridge.
+ *
+ * Safety model (same shape as the skill gate, extended to code):
+ *  1. patches may only modify files under packages/.../src/ (never config,
+ *     never security code, never the kernel loop itself)
+ *  2. every patch runs on a git branch (sandbox), never on main
+ *  3. the bench gate must show no regression (same double-sample rule)
+ *  4. revert = git checkout main + branch delete (zero residue)
+ */
+import { readFile } from 'node:fs/promises';
+/** A proposed code change: find-and-replace in one source file. */
+export interface CodePatch {
+    name: string;
+    description: string;
+    /** relative path from repo root, must match packages/.../src/.../*.ts */
+    file: string;
+    /** exact string to find in the file (must be unique) */
+    find: string;
+    /** replacement string */
+    replace: string;
+    /** why this change helps (for the audit log) */
+    reason: string;
+}
+export interface PatchOutcome {
+    name: string;
+    action: 'merged' | 'reverted' | 'error';
+    reason: string;
+    branch?: string;
+}
+/** Guard: only source files inside packages, never kernel internals. */
+export declare function isPatchableFile(file: string): boolean;
+/** Validate + apply a patch to a file on disk. Returns error if find-string
+ *  is not found or not unique. */
+export declare function applyPatch(repoRoot: string, patch: CodePatch): Promise<string>;
+/** Create a sandbox git branch for testing a patch. */
+export declare function createSandbox(repoRoot: string, name: string): Promise<string>;
+/** Commit the patch on the sandbox branch so it is fully isolated from main. */
+export declare function commitOnSandbox(repoRoot: string, patchName: string): Promise<void>;
+/** Merge the sandbox branch back to main (patch promoted). */
+export declare function mergeSandbox(repoRoot: string, branch: string): Promise<void>;
+/** Run the bench gate on the current branch. Returns pass rate (0-1) or -1 on build failure. */
+export declare function sandboxBench(repoRoot: string, runCase: (c: import('./bench.ts').BenchCase, skillsPrompt: string) => Promise<string>, cases: import('./bench.ts').BenchCase[]): Promise<number>;
+/** Revert: go back to main, delete the sandbox branch (zero residue). */
+export declare function revertSandbox(repoRoot: string, branch: string): Promise<void>;
+/**
+ * Full sandbox cycle: apply patch on a branch, rebuild, bench, merge or revert.
+ * This is the CODE-LEVEL equivalent of the skill A/B gate.
+ */
+export declare function runPatchSandbox(opts: {
+    repoRoot: string;
+    patch: CodePatch;
+    baselineRate: number;
+    runCase: (c: import('./bench.ts').BenchCase, skillsPrompt: string) => Promise<string>;
+    benchCases: import('./bench.ts').BenchCase[];
+    log?: (line: string) => void;
+}): Promise<PatchOutcome>;
+/**
+ * Meta-model call: propose code patches from session signals.
+ * The model sees the signals + the target file's current source and
+ * outputs find/replace pairs. Constrained to optimization prompts:
+ * fix a bug, speed up a hot path, improve error messages.
+ */
+export declare function proposePatches(provider: {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+}, signals: Record<string, unknown>, readFileFn: typeof readFile, repoRoot: string, say: (l: string) => void): Promise<CodePatch[]>;