darwin-agents 0.7.1 → 0.9.0

package/dist/src/evolution/canary.js

@@ -0,0 +1,244 @@
+/**
+ * Validate-by-Reproduce drift-detection canary (Phase 2 A5).
+ *
+ * The A/B safety gate guards prompt *quality* — it catches a new prompt version
+ * that scores worse. But an agent can drift WITHOUT its quality score moving: a
+ * model update, an MCP tool breaking, or a prompt evolution's side-effect can
+ * change *how* the agent gets to the answer (different tools, more turns, more
+ * errors) while the final score stays flat. Vadim Nicolai's production write-up
+ * captures it: "the agent still sounds fluent, but the trajectory is longer and
+ * the tool-calls more repetitive."
+ *
+ * This module compares an agent's recent execution *trajectories* against a
+ * frozen baseline and flags behavioural drift. It is the read side of the
+ * trajectory capture shipped in A1 (`ExecutionTrace`).
+ *
+ * ── Method (grounded in 2026 agent-eval practice) ──
+ * Exact-hash equivalence is the wrong tool — LLM runs are non-deterministic, so
+ * an exact trajectory hash drifts every single run. Instead we use the same
+ * deterministic, tolerance-based metrics the field settled on (LangChain's
+ * `agentevals`, Vertex AI trajectory metrics, Galileo):
+ *
+ *   1. **Unordered tool-set Jaccard** — `|A∩B| / |A∪B|` over tool *names*.
+ *      Catches new/missing tools regardless of order. Primary signal.
+ *   2. **Ordered tool-sequence similarity** — normalised Levenshtein over the
+ *      tool-name sequence. Catches re-ordering / repetition.
+ *   3. **Turn-count ratio** — `candidate.turns / baseline.turns`. A ratio > 1.5
+ *      is the canonical "agent is grinding" symptom.
+ *   4. **Error-rate delta** — error spikes are the most reliable tool-break tell.
+ *
+ * We deliberately do NOT compare tool *arguments* (LLM-variable → noise) or
+ * output length (verbosity swings without drift). We keep zero hard deps: these
+ * metrics are ~a dozen lines each, so `agentevals` stays an inspiration, not a
+ * dependency — Darwin's whole point is a pure, injectable core.
+ *
+ * ── Sampling ──
+ * A single failing run is noise, not drift. The canary needs a *pattern*:
+ * evaluate several same-version runs and alert only when ≥ N of them drift
+ * (default 2). Three candidate runs per week is the field's rule of thumb.
+ *
+ * ── Baseline staleness (the load-bearing footgun) ──
+ * A baseline is only meaningful against runs of the SAME prompt version. When a
+ * prompt evolves, the new version *should* behave differently — comparing it to
+ * the old baseline would fire a false alarm on every intentional improvement.
+ * `runCanaryOverExperiments` therefore baselines strictly within the active
+ * prompt version: after an evolution the canary reports `insufficient-data`
+ * (re-baseline in progress) rather than screaming drift.
+ *
+ * Everything here is pure and deterministic. Side-effects (loading experiments,
+ * printing, alerting) live in the CLI command and in private cron wiring.
+ */
+// ─── Trajectory signature extraction ───────────────────────
+/** The ordered sequence of tool names exactly as they fired. */
+export function toolSequence(trace) {
+    // `?? []` is defensive against trajectories deserialised from older DB rows:
+    // a NULL JSONB/TEXT column can yield null at runtime despite the non-optional
+    // type, and a drift check must degrade gracefully rather than throw.
+    return (trace.toolCalls ?? []).map((c) => c.tool);
+}
+/** The set of distinct tool names used (order-independent). */
+export function toolSet(trace) {
+    return new Set(toolSequence(trace));
+}
+/**
+ * Error rate of a run: (tool-call errors + turn-level errors) normalised by the
+ * turn count. Uses `max(1, turnCount)` so a zero-turn trace can't divide by zero.
+ */
+export function errorRate(trace) {
+    const toolErrors = (trace.toolCalls ?? []).filter((c) => c.outcome === 'error').length;
+    const turnErrors = (trace.errors ?? []).length;
+    return (toolErrors + turnErrors) / Math.max(1, trace.turnCount ?? 0);
+}
+// ─── Pure similarity metrics ────────────────────────────────
+/**
+ * Jaccard similarity of two string sets: `|A∩B| / |A∪B|`.
+ * 1 = identical, 0 = disjoint. Two empty sets are defined as 1 (both used no
+ * tools → identical behaviour, not drift).
+ */
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const x of a)
+        if (b.has(x))
+            intersection++;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 1 : intersection / union;
+}
+/**
+ * Normalised Levenshtein similarity over two token sequences:
+ * `1 - editDistance / max(len)`. 1 = identical order, 0 = fully different.
+ * Two empty sequences are defined as 1.
+ */
+export function sequenceSimilarity(a, b) {
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    return 1 - levenshtein(a, b) / maxLen;
+}
+/** Iterative Levenshtein edit distance over token arrays. O(n·m) time, O(min) space. */
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    let curr = new Array(n + 1).fill(0);
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // deletion
+            curr[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+const DEFAULT_THRESHOLDS = {
+    minToolJaccard: 0.7,
+    minSequenceSimilarity: 0.6,
+    maxTurnRatio: 1.5,
+    maxErrorRateIncrease: 0.2,
+};
+/**
+ * Compare one candidate trajectory against a baseline across all four
+ * dimensions. Pure. Missing thresholds fall back to {@link DEFAULT_THRESHOLDS}.
+ */
+export function compareTrajectory(candidate, baseline, thresholds = {}) {
+    const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+    const toolJaccard = jaccard(toolSet(candidate), toolSet(baseline));
+    const seqSim = sequenceSimilarity(toolSequence(candidate), toolSequence(baseline));
+    const baseTurns = Math.max(1, baseline.turnCount ?? 0);
+    const turnRatio = (candidate.turnCount ?? 0) / baseTurns;
+    const errorRateDelta = errorRate(candidate) - errorRate(baseline);
+    const reasons = [];
+    if (toolJaccard < t.minToolJaccard) {
+        reasons.push(`tool-set drift (Jaccard ${fmt(toolJaccard)} < ${t.minToolJaccard})`);
+    }
+    if (seqSim < t.minSequenceSimilarity) {
+        reasons.push(`tool-order drift (similarity ${fmt(seqSim)} < ${t.minSequenceSimilarity})`);
+    }
+    if (turnRatio > t.maxTurnRatio) {
+        reasons.push(`turn inflation (ratio ${fmt(turnRatio)} > ${t.maxTurnRatio})`);
+    }
+    if (errorRateDelta > t.maxErrorRateIncrease) {
+        reasons.push(`error-rate spike (+${fmt(errorRateDelta)} > ${t.maxErrorRateIncrease})`);
+    }
+    return {
+        toolJaccard,
+        sequenceSimilarity: seqSim,
+        turnRatio,
+        errorRateDelta,
+        drifted: reasons.length > 0,
+        reasons,
+    };
+}
+/**
+ * Evaluate a set of candidate trajectories against one baseline. Pure.
+ * An empty candidate set yields `total: 0`, `alert: false`.
+ */
+export function evaluateCanary(candidates, baseline, opts = {}) {
+    const minDriftedToAlert = clampPositiveInt(opts.minDriftedToAlert, 2);
+    const comparisons = candidates.map((c) => compareTrajectory(c, baseline, opts.thresholds));
+    const driftedCount = comparisons.filter((c) => c.drifted).length;
+    const reasons = Array.from(new Set(comparisons.filter((c) => c.drifted).flatMap((c) => c.reasons)));
+    return {
+        total: comparisons.length,
+        driftedCount,
+        alert: driftedCount >= minDriftedToAlert,
+        medianToolJaccard: median(comparisons.map((c) => c.toolJaccard)),
+        medianTurnRatio: median(comparisons.map((c) => c.turnRatio)),
+        comparisons,
+        reasons,
+    };
+}
+/**
+ * Run a canary over an agent's stored experiments. Pure: takes the experiments
+ * and the active prompt version, returns a report. The caller supplies the data
+ * (e.g. `memory.loadExperiments` + `memory.getActivePrompt`).
+ *
+ * Baseline policy: among experiments carrying a trajectory for the ACTIVE prompt
+ * version, the earliest (by `startedAt`) is the frozen reference; every later
+ * same-version run is a candidate. Restricting to the active version is what
+ * prevents false alarms right after an intentional prompt evolution.
+ */
+export function runCanaryOverExperiments(agentName, experiments, activeVersion, opts = {}) {
+    const minCandidates = clampPositiveInt(opts.minCandidates, 3);
+    // Only v1 trajectories are comparable. The ExecutionTrace forward-compat
+    // contract (types.ts) requires consumers to skip unknown schema versions
+    // rather than mis-score them, so a future v2 trace is treated as not-capturable.
+    const withTrace = experiments.filter((e) => e.trajectory != null && e.trajectory.version === 1);
+    if (withTrace.length === 0) {
+        return report(agentName, activeVersion, null, 0, null, 'no-trajectory', 'No comparable (v1) trajectories captured yet — enable trace capture to run the canary.');
+    }
+    if (!activeVersion) {
+        return report(agentName, activeVersion, null, 0, null, 'insufficient-data', 'No active prompt version resolved for this agent.');
+    }
+    // Baseline strictly within the active version (staleness guard).
+    const sameVersion = withTrace
+        .filter((e) => e.promptVersion === activeVersion)
+        // Lexicographic order on ISO-8601 strings == chronological, without
+        // locale-dependent collation surprises (assumes consistent UTC timestamps).
+        .sort((a, b) => (a.startedAt < b.startedAt ? -1 : a.startedAt > b.startedAt ? 1 : 0));
+    if (sameVersion.length === 0) {
+        return report(agentName, activeVersion, null, 0, null, 'insufficient-data', `Active version ${activeVersion} has no trajectories yet (${withTrace.length} on older versions) — re-baseline in progress.`);
+    }
+    const [baseline, ...candidates] = sameVersion;
+    if (candidates.length < minCandidates) {
+        return report(agentName, activeVersion, baseline.id, candidates.length, null, 'insufficient-data', `Only ${candidates.length} candidate run(s) on ${activeVersion}; need ${minCandidates} for a verdict.`);
+    }
+    const result = evaluateCanary(candidates.map((c) => c.trajectory), baseline.trajectory, opts);
+    const status = result.alert ? 'drift' : 'ok';
+    const message = result.alert
+        ? `Behavioural drift on ${agentName}/${activeVersion}: ${result.driftedCount}/${result.total} runs drifted — ${result.reasons.join('; ')}`
+        : `Stable: ${result.total} runs on ${activeVersion}, ${result.driftedCount} drifted (median tool-Jaccard ${fmt(result.medianToolJaccard)}).`;
+    return report(agentName, activeVersion, baseline.id, candidates.length, result, status, message);
+}
+// ─── Small pure helpers ─────────────────────────────────────
+function report(agentName, promptVersion, baselineId, evaluated, result, status, message) {
+    return { agentName, promptVersion, baselineId, evaluated, result, status, message };
+}
+/** Median of a numeric array. Empty array → 0. Does not mutate the input. */
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+/** Coerce to a positive integer, falling back to `fallback` for NaN/≤0/non-finite. */
+function clampPositiveInt(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    const n = Math.floor(value);
+    return n > 0 ? n : fallback;
+}
+/** Format a ratio/score to 2 dp for messages. */
+function fmt(n) {
+    return n.toFixed(2);
+}
+//# sourceMappingURL=canary.js.map

package/dist/src/evolution/canary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canary.js","sourceRoot":"","sources":["../../../src/evolution/canary.ts"],"names":[],"mappings":"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"}

package/dist/src/evolution/critic-families.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cross-family critic diversity check.
+ *
+ * LLM-as-judge bias is materially reduced when the critics that score an
+ * agent's output come from more than one model *family* (e.g. GPT + Claude):
+ * different training pipelines carry different blind spots, so a disagreement
+ * between families is a stronger quality signal than agreement within one.
+ *
+ * Darwin's `resolveCriticProviders` already spreads critics across families
+ * WHEN the provider keys are present — but when only one provider is
+ * configured, all three critics silently collapse onto a single family and the
+ * diversity guarantee is gone with no signal to the operator. This module makes
+ * that observable (warn by default) and enforceable (opt-in, env-gated).
+ *
+ * Important nuance: `claude-cli` and `anthropic-api` are the SAME family (both
+ * Anthropic); they differ only in latency. Real family diversity needs a
+ * non-Anthropic provider key (OpenAI, Ollama, …). The check therefore keys on
+ * the model *family*, never on the provider label.
+ */
+/** Minimal shape needed from a resolved critic provider entry. */
+export interface CriticFamilyInfo {
+    /** Model family — e.g. 'anthropic', 'openai', 'ollama'. */
+    family: string;
+}
+export interface CrossFamilyCheck {
+    /** Distinct, non-empty families across all critics, sorted alphabetically. */
+    families: string[];
+    /** Number of distinct families. */
+    count: number;
+    /**
+     * True when every critic shares a single family (judge bias unmitigated).
+     * A degenerate empty critic map is also reported as single-family — it is
+     * not a diversity win.
+     */
+    singleFamily: boolean;
+}
+/**
+ * Count the distinct model families across a resolved critic-provider map.
+ * Pure and deterministic. Blank / non-string families are ignored so a
+ * mis-populated entry can never inflate the diversity count.
+ */
+export declare function checkCriticFamilies(providers: Record<string, CriticFamilyInfo>): CrossFamilyCheck;
+/**
+ * Whether cross-family critics are *required* (hard fail) rather than merely
+ * recommended (warn). Gated by `DARWIN_REQUIRE_CROSS_FAMILY` so CI can enforce
+ * it without changing the default developer experience.
+ */
+export declare function crossFamilyRequired(env?: NodeJS.ProcessEnv): boolean;
+/** Operator-facing message when the critics collapse onto one family. */
+export declare function singleFamilyHint(check: CrossFamilyCheck): string;
+//# sourceMappingURL=critic-families.d.ts.map

package/dist/src/evolution/critic-families.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"critic-families.d.ts","sourceRoot":"","sources":["../../../src/evolution/critic-families.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAC1C,gBAAgB,CAclB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGjF;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOhE"}

package/dist/src/evolution/critic-families.js

@@ -0,0 +1,51 @@
+/**
+ * Cross-family critic diversity check.
+ *
+ * LLM-as-judge bias is materially reduced when the critics that score an
+ * agent's output come from more than one model *family* (e.g. GPT + Claude):
+ * different training pipelines carry different blind spots, so a disagreement
+ * between families is a stronger quality signal than agreement within one.
+ *
+ * Darwin's `resolveCriticProviders` already spreads critics across families
+ * WHEN the provider keys are present — but when only one provider is
+ * configured, all three critics silently collapse onto a single family and the
+ * diversity guarantee is gone with no signal to the operator. This module makes
+ * that observable (warn by default) and enforceable (opt-in, env-gated).
+ *
+ * Important nuance: `claude-cli` and `anthropic-api` are the SAME family (both
+ * Anthropic); they differ only in latency. Real family diversity needs a
+ * non-Anthropic provider key (OpenAI, Ollama, …). The check therefore keys on
+ * the model *family*, never on the provider label.
+ */
+/**
+ * Count the distinct model families across a resolved critic-provider map.
+ * Pure and deterministic. Blank / non-string families are ignored so a
+ * mis-populated entry can never inflate the diversity count.
+ */
+export function checkCriticFamilies(providers) {
+    const families = Array.from(new Set(Object.values(providers)
+        .map((p) => (typeof p?.family === 'string' ? p.family.trim().toLowerCase() : ''))
+        .filter((f) => f.length > 0))).sort();
+    return {
+        families,
+        count: families.length,
+        singleFamily: families.length < 2,
+    };
+}
+/**
+ * Whether cross-family critics are *required* (hard fail) rather than merely
+ * recommended (warn). Gated by `DARWIN_REQUIRE_CROSS_FAMILY` so CI can enforce
+ * it without changing the default developer experience.
+ */
+export function crossFamilyRequired(env = process.env) {
+    const v = env.DARWIN_REQUIRE_CROSS_FAMILY;
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/** Operator-facing message when the critics collapse onto one family. */
+export function singleFamilyHint(check) {
+    const fam = check.families[0] ?? 'unknown';
+    return (`All critics run on one model family (${fam}). ` +
+        `Cross-family critique reduces LLM-as-judge bias — set OPENAI_API_KEY ` +
+        `(or another non-Anthropic provider key) so a second family scores in parallel.`);
+}
+//# sourceMappingURL=critic-families.js.map

package/dist/src/evolution/critic-families.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"critic-families.js","sourceRoot":"","sources":["../../../src/evolution/critic-families.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqBH;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA2C;IAE3C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CACzB,IAAI,GAAG,CACL,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SAChF,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAC/B,CACF,CAAC,IAAI,EAAE,CAAC;IAET,OAAO;QACL,QAAQ;QACR,KAAK,EAAE,QAAQ,CAAC,MAAM;QACtB,YAAY,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC;KAClC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,MAAM,CAAC,GAAG,GAAG,CAAC,2BAA2B,CAAC;IAC1C,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,CAAC;AAClD,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,KAAuB;IACtD,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;IAC3C,OAAO,CACL,wCAAwC,GAAG,KAAK;QAChD,uEAAuE;QACvE,gFAAgF,CACjF,CAAC;AACJ,CAAC"}

package/dist/src/evolution/enabled-state.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Darwin — Persisted Evolution Enable/Disable State
+ *
+ * `darwin evolve <agent> --enable|--disable` used to mutate the in-memory
+ * agent singleton (`agent.evolution.enabled = true`) and never persist it,
+ * so the flag was lost the moment the process exited — and `darwin run`
+ * then read the STATIC source default again. This module makes the toggle
+ * durable by recording it in {@link DarwinState.evolutionEnabled} (the same
+ * JSON state blob every backend already round-trips) and resolving the
+ * effective value with the persisted override winning over the static
+ * default.
+ */
+import type { AgentDefinition, DarwinState, EvolutionConfig, EvolutionConfigOverride, MemoryProvider } from '../types.js';
+/**
+ * The effective "is evolution enabled for this agent" decision.
+ *
+ * Resolution order:
+ *   1. A persisted override in `state.evolutionEnabled[agentName]` (set by
+ *      `darwin evolve --enable/--disable`) — wins when present.
+ *   2. The agent definition's static `evolution.enabled` default.
+ *   3. `false` when the agent has no `evolution` block at all.
+ *
+ * Read defensively: state written before the `evolutionEnabled` field
+ * existed simply lacks the key, in which case rule 1 is skipped and the
+ * static default applies — so old installs keep their previous behaviour.
+ */
+export declare function resolveEvolutionEnabled(agent: AgentDefinition, state: Pick<DarwinState, 'evolutionEnabled'>): boolean;
+/**
+ * Persist the enable/disable override for an agent atomically.
+ *
+ * Uses {@link MemoryProvider.updateState} so a concurrent writer cannot lose
+ * the update, and initialises the `evolutionEnabled` map lazily for state
+ * rows that predate the field.
+ */
+export declare function setEvolutionEnabled(memory: MemoryProvider, agentName: string, enabled: boolean): Promise<void>;
+/**
+ * Resolve the effective {@link EvolutionConfig} for an agent: the static
+ * definition's `evolution` block with any persisted override
+ * ({@link DarwinState.evolutionConfigOverrides}) merged ON TOP, then any
+ * in-this-process CLI override merged last (e.g. `darwin run … --gepa`).
+ *
+ * Only the five advanced flags are overridable; every other field
+ * (`enabled`, `metrics`, `minRuns`, …) is taken verbatim from the static
+ * config. Returns `undefined` when the agent has no `evolution` block AND no
+ * persisted/CLI override would create one — overriding a flag on an agent that
+ * never opted into evolution is meaningless.
+ *
+ * Read defensively: undefined override values are skipped so they never clobber
+ * a static default with `undefined`.
+ */
+export declare function resolveEvolutionConfig(agent: AgentDefinition, state: Pick<DarwinState, 'evolutionConfigOverrides'>, cliOverride?: EvolutionConfigOverride): EvolutionConfig | undefined;
+/**
+ * Persist advanced-config overrides for an agent atomically, merging the given
+ * partial into any existing override map (so toggling `--gepa` does not wipe a
+ * previously-set `--reflection-model`). Initialises the map lazily for state
+ * rows that predate the field.
+ */
+export declare function setEvolutionConfigOverrides(memory: MemoryProvider, agentName: string, partial: EvolutionConfigOverride): Promise<void>;
+//# sourceMappingURL=enabled-state.d.ts.map

package/dist/src/evolution/enabled-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enabled-state.d.ts","sourceRoot":"","sources":["../../../src/evolution/enabled-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,eAAe,EACf,uBAAuB,EACvB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,kBAAkB,CAAC,GAC3C,OAAO,CAUT;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAQf;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,0BAA0B,CAAC,EACpD,WAAW,CAAC,EAAE,uBAAuB,GACpC,eAAe,GAAG,SAAS,CA8B7B;AAED;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/src/evolution/enabled-state.js

@@ -0,0 +1,122 @@
+/**
+ * Darwin — Persisted Evolution Enable/Disable State
+ *
+ * `darwin evolve <agent> --enable|--disable` used to mutate the in-memory
+ * agent singleton (`agent.evolution.enabled = true`) and never persist it,
+ * so the flag was lost the moment the process exited — and `darwin run`
+ * then read the STATIC source default again. This module makes the toggle
+ * durable by recording it in {@link DarwinState.evolutionEnabled} (the same
+ * JSON state blob every backend already round-trips) and resolving the
+ * effective value with the persisted override winning over the static
+ * default.
+ */
+/**
+ * The effective "is evolution enabled for this agent" decision.
+ *
+ * Resolution order:
+ *   1. A persisted override in `state.evolutionEnabled[agentName]` (set by
+ *      `darwin evolve --enable/--disable`) — wins when present.
+ *   2. The agent definition's static `evolution.enabled` default.
+ *   3. `false` when the agent has no `evolution` block at all.
+ *
+ * Read defensively: state written before the `evolutionEnabled` field
+ * existed simply lacks the key, in which case rule 1 is skipped and the
+ * static default applies — so old installs keep their previous behaviour.
+ */
+export function resolveEvolutionEnabled(agent, state) {
+    const persisted = state.evolutionEnabled?.[agent.name];
+    if (typeof persisted === 'boolean') {
+        // A persisted `true` only takes effect when the agent actually carries an
+        // `evolution` config block — the run/critic loop needs an evaluator and
+        // metrics to act on. Enabling an agent that has no evolution config is a
+        // no-op (returns false), not a crash. A persisted `false` always disables.
+        return persisted && agent.evolution !== undefined;
+    }
+    return agent.evolution?.enabled ?? false;
+}
+/**
+ * Persist the enable/disable override for an agent atomically.
+ *
+ * Uses {@link MemoryProvider.updateState} so a concurrent writer cannot lose
+ * the update, and initialises the `evolutionEnabled` map lazily for state
+ * rows that predate the field.
+ */
+export async function setEvolutionEnabled(memory, agentName, enabled) {
+    await memory.updateState((state) => {
+        if (!state.evolutionEnabled) {
+            state.evolutionEnabled = {};
+        }
+        state.evolutionEnabled[agentName] = enabled;
+        return state;
+    });
+}
+// ─── Advanced evolution-config overrides (useGepa / useMerge / …) ───
+/** The keys the CLI is allowed to override + persist. */
+const OVERRIDE_KEYS = [
+    'useGepa',
+    'useMerge',
+    'paretoGate',
+    'useCoverage',
+    'reflectionModel',
+];
+/**
+ * Resolve the effective {@link EvolutionConfig} for an agent: the static
+ * definition's `evolution` block with any persisted override
+ * ({@link DarwinState.evolutionConfigOverrides}) merged ON TOP, then any
+ * in-this-process CLI override merged last (e.g. `darwin run … --gepa`).
+ *
+ * Only the five advanced flags are overridable; every other field
+ * (`enabled`, `metrics`, `minRuns`, …) is taken verbatim from the static
+ * config. Returns `undefined` when the agent has no `evolution` block AND no
+ * persisted/CLI override would create one — overriding a flag on an agent that
+ * never opted into evolution is meaningless.
+ *
+ * Read defensively: undefined override values are skipped so they never clobber
+ * a static default with `undefined`.
+ */
+export function resolveEvolutionConfig(agent, state, cliOverride) {
+    const persisted = state.evolutionConfigOverrides?.[agent.name];
+    const base = agent.evolution;
+    if (!base && !persisted && !cliOverride) {
+        return undefined;
+    }
+    // Start from the static config (or a disabled stub when the only reason we
+    // are here is an override — the loop still gates on `enabled`, which stays
+    // false unless the static config or the separate enable-toggle turns it on).
+    const resolved = base ? { ...base } : { enabled: false };
+    for (const layer of [persisted, cliOverride]) {
+        if (!layer)
+            continue;
+        for (const key of OVERRIDE_KEYS) {
+            const value = layer[key];
+            if (value !== undefined) {
+                // Each key is assigned to its own matching field — typed per-key to
+                // keep `any` out of the codebase.
+                if (key === 'reflectionModel') {
+                    resolved.reflectionModel = value;
+                }
+                else {
+                    resolved[key] = value;
+                }
+            }
+        }
+    }
+    return resolved;
+}
+/**
+ * Persist advanced-config overrides for an agent atomically, merging the given
+ * partial into any existing override map (so toggling `--gepa` does not wipe a
+ * previously-set `--reflection-model`). Initialises the map lazily for state
+ * rows that predate the field.
+ */
+export async function setEvolutionConfigOverrides(memory, agentName, partial) {
+    await memory.updateState((state) => {
+        if (!state.evolutionConfigOverrides) {
+            state.evolutionConfigOverrides = {};
+        }
+        const existing = state.evolutionConfigOverrides[agentName] ?? {};
+        state.evolutionConfigOverrides[agentName] = { ...existing, ...partial };
+        return state;
+    });
+}
+//# sourceMappingURL=enabled-state.js.map

package/dist/src/evolution/enabled-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enabled-state.js","sourceRoot":"","sources":["../../../src/evolution/enabled-state.ts"],"names":[],"mappings":"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"}

package/dist/src/evolution/loop.d.ts

@@ -83,6 +83,34 @@ export declare class DarwinLoop {
      *   5. Evolution trigger (if enough data and no active test)
      */
     afterRun(experiment: DarwinExperiment): Promise<EvolutionResult>;
+    /**
+     * Manual / on-demand evolution trigger — the engine behind
+     * `darwin evolve <agent> --force`.
+     *
+     * Runs the SAME variant-generation + A/B-start path as the automatic loop's
+     * Step 5, but WITHOUT the "enough runs / actionable patterns / data-quality"
+     * gates. Use it to deliberately kick off an optimisation from the current
+     * best prompt using the experiments collected so far, instead of waiting for
+     * the loop to decide on its own.
+     *
+     * It still refuses the cases where evolution is genuinely impossible or
+     * unsafe:
+     *   - no active prompt seeded yet (nothing to mutate from),
+     *   - no recorded experiments (the optimizer has nothing to learn from),
+     *   - an A/B test already running (can't start a second concurrent test).
+     *
+     * Patterns are still DETECTED (so the change reason and the GEPA/legacy
+     * feedback are meaningful) — they are simply not used as a gate.
+     */
+    forceEvolve(agentName: string): Promise<EvolutionResult>;
+    /**
+     * Shared tail of the evolution cycle: generate one challenger prompt (GEPA
+     * reflective path when opted in, else the legacy meta-prompt optimizer),
+     * persist it as a new version, and start an A/B test against the incumbent.
+     * Called by both the gated automatic loop ({@link afterRun}) and the
+     * on-demand {@link forceEvolve}. Mutates and returns the passed `result`.
+     */
+    private generateAndStartABTest;
     private handleABTest;
     /**
      * Roll back to the last known good prompt version.
@@ -159,6 +187,24 @@ export declare class DarwinLoop {
      * runs {@link runAlignmentGuard} on it.
      */
     private tryMergeVariant;
+    /**
+     * v0.7.0 — GEPA Algorithm 2 instance-wise coverage selection.
+     *
+     * Builds a {@link ScoredVariant} per RUN prompt-version (its averaged
+     * objective vector + its per-task-type composite map from {@link
+     * ExperimentTracker.getPerKeyScoresByCategory}), then asks the
+     * {@link GepaOptimizer#nextGeneration} coverage path to pick the survivor
+     * that wins on the MOST DIFFERENT task types. Returns that survivor's prompt
+     * text — the version to reflect the next challenger from.
+     *
+     * Returns `null` (→ caller reflects from the active prompt as before) when no
+     * optimizer is wired or fewer than two versions carry per-task-type data —
+     * coverage selection is meaningless with a single covered version. This is
+     * the ONLINE adaptation: it selects the reflection PARENT among already-run
+     * versions by their real per-task-type scores. (Per-challenger coverage of
+     * unrun candidates needs the offline scored-pool path and is out of scope.)
+     */
+    private selectCoverageParent;
     /**
      * v0.6.0 — Build GEPA {@link ReflectiveFeedback} from the most recent
      * experiments that carry critic feedback. Each becomes a (variantId,

package/dist/src/evolution/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../../src/evolution/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,qBAAqB,CAAC;AAGxE,OAAO,EAAkE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAK9G,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,aAAa,EAAE,CAAC;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;CACvC;AAYD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,IAAI,CAAC,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAC,CAAU;IACxB,OAAO,CAAC,4BAA4B,CAAC,CAAS;gBAElC,IAAI,EAAE,cAAc;IAahC;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;YA0PxD,YAAY;IAwJ1B;;;OAGG;YACW,QAAQ;IA8BtB;;OAEG;YACW,eAAe;IAe7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;;;OAMG;YACW,iBAAiB;IAe/B;;;;;;;;;;;;;;;;;OAiBG;YACW,mBAAmB;IA8EjC;;;;;;;;OAQG;YACW,iBAAiB;IAa/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;;;;;;;;OAYG;YACW,eAAe;IA2C7B;;;;;;OAMG;YACW,qBAAqB;IAsBnC;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAKvB;;;OAGG;YACW,mBAAmB;IAiDjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../../src/evolution/loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAoB,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,qBAAqB,CAAC;AAGxE,OAAO,EAAkE,KAAK,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAK9G,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,aAAa,EAAE,CAAC;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,UAAU,cAAc;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;CACvC;AAYD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,IAAI,CAAC,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAC,CAAU;IACxB,OAAO,CAAC,4BAA4B,CAAC,CAAS;gBAElC,IAAI,EAAE,cAAc;IAahC;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAuJtE;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAqC9D;;;;;;OAMG;YACW,sBAAsB;YA8GtB,YAAY;IAwJ1B;;;OAGG;YACW,QAAQ;IA8BtB;;OAEG;YACW,eAAe;IAe7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAKlB;;;;;;OAMG;YACW,iBAAiB;IAe/B;;;;;;;;;;;;;;;;;OAiBG;YACW,mBAAmB;IA4FjC;;;;;;;;OAQG;YACW,iBAAiB;IAa/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;;;;;;;;OAYG;YACW,eAAe;IA2C7B;;;;;;;;;;;;;;;;OAgBG;YACW,oBAAoB;IAyBlC;;;;;;OAMG;YACW,qBAAqB;IAsBnC;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAKvB;;;OAGG;YACW,mBAAmB;IAiDjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}