darwin-agents 0.9.0 → 0.10.0

package/dist/src/evolution/demos.js

@@ -0,0 +1,196 @@
+/**
+ * Demo injection (v0.10.0) — SIMBA-style "append a demo" challenger source.
+ *
+ * DSPy's SIMBA optimizer (Stochastic Introspective Mini-Batch Ascent) improves
+ * programs through two complementary strategies: appending self-reflective
+ * RULES (Darwin's reflector already covers that ground) and appending
+ * successful past examples as DEMONSTRATIONS. This module is Darwin's
+ * adaptation of the second strategy to the online evolution loop:
+ *
+ *   1. Harvest the agent's own highest-scoring past runs from memory
+ *      (score ≥ threshold, successful, non-trivial output).
+ *   2. Prefer diversity: at most one demo per task type, best-scoring first.
+ *   3. Render them as a clearly-delimited "Demonstrations" section and
+ *      append it to (or refresh it inside) the current prompt.
+ *
+ * The demo-augmented prompt is a CHALLENGER like any other — it goes through
+ * the same alignment guard, the same A/B test, and the same safety gate as a
+ * reflective or merged mutation. If demos don't actually help this agent, the
+ * incumbent wins and nothing changes.
+ *
+ * Design notes:
+ *   - Zero LLM cost. Selection and rendering are pure string/array work on
+ *     data Darwin already persists (task, output, score, taskType). This makes
+ *     demos the cheapest challenger source in the loop.
+ *   - Idempotent via markers. The section is wrapped in
+ *     `<!-- darwin:demos:start/end -->` comments so a later demo cycle
+ *     REPLACES the previous section instead of stacking a second one, and
+ *     {@link stripDemoSection} can remove it cleanly.
+ *   - Demo text comes from the agent's OWN prior outputs (already produced
+ *     under this prompt lineage), not from an external input channel. Excerpts
+ *     are length-capped and fenced, but callers embedding third-party data in
+ *     tasks should be aware demos quote past tasks verbatim.
+ *   - Determinism. Given the same experiment list and options, selection and
+ *     rendering are fully deterministic (stable sort, no randomness) — the
+ *     loop's no-op check ("would this produce the same prompt?") stays cheap.
+ */
+// ─── Defaults & markers ─────────────────────────────────────────────────────
+export const DEFAULT_MAX_DEMOS = 2;
+export const DEFAULT_DEMO_SCORE_THRESHOLD = 8;
+export const DEFAULT_DEMO_MIN_OUTPUT_CHARS = 200;
+export const DEFAULT_DEMO_TASK_CHARS = 240;
+export const DEFAULT_DEMO_OUTPUT_CHARS = 900;
+/** Start marker — everything between the markers is Darwin-managed. */
+export const DEMO_SECTION_START = "<!-- darwin:demos:start -->";
+/** End marker. */
+export const DEMO_SECTION_END = "<!-- darwin:demos:end -->";
+const DEMO_SECTION_INTRO = "## Demonstrations\n" +
+    "The following are excerpts from this agent's own highest-rated past " +
+    "responses. Match their quality, depth and structure — do NOT copy their " +
+    "content or treat their subject matter as part of the current task.";
+// ─── Selection ──────────────────────────────────────────────────────────────
+/** Clamp helper: finite number ≥ min, else fallback. */
+function clampOption(value, min, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= min
+        ? Math.floor(value)
+        : fallback;
+}
+/**
+ * Harvest demo candidates from an agent's experiment history.
+ *
+ * Filter: successful runs with a critic score ≥ `scoreThreshold` and an
+ * output of at least `minOutputChars`. Diversity: at most ONE demo per task
+ * type (the best-scoring run of that type, recency as tie-break) so two demos
+ * never showcase the same narrow strength. Order: score descending, then
+ * most-recent first — fully deterministic.
+ */
+export function selectDemoCandidates(experiments, options = {}) {
+    const maxDemos = clampOption(options.maxDemos, 1, DEFAULT_MAX_DEMOS);
+    const threshold = typeof options.scoreThreshold === "number" && Number.isFinite(options.scoreThreshold)
+        ? options.scoreThreshold
+        : DEFAULT_DEMO_SCORE_THRESHOLD;
+    const minChars = clampOption(options.minOutputChars, 0, DEFAULT_DEMO_MIN_OUTPUT_CHARS);
+    const qualified = experiments.filter((exp) => {
+        if (!exp.success)
+            return false;
+        const score = exp.feedback?.score;
+        if (typeof score !== "number" || !Number.isFinite(score) || score < threshold)
+            return false;
+        const output = exp.output;
+        if (typeof output !== "string" || output.trim().length < minChars)
+            return false;
+        return typeof exp.task === "string" && exp.task.trim().length > 0;
+    });
+    // Best run per task type (score desc, then completedAt desc as tie-break).
+    const bestPerType = new Map();
+    for (const exp of qualified) {
+        const key = exp.taskType || "general";
+        const incumbent = bestPerType.get(key);
+        if (incumbent === undefined) {
+            bestPerType.set(key, exp);
+            continue;
+        }
+        const expScore = exp.feedback.score;
+        const incScore = incumbent.feedback.score;
+        if (expScore > incScore ||
+            (expScore === incScore && exp.completedAt > incumbent.completedAt)) {
+            bestPerType.set(key, exp);
+        }
+    }
+    const picked = [...bestPerType.values()].sort((a, b) => {
+        const scoreDelta = b.feedback.score - a.feedback.score;
+        if (scoreDelta !== 0)
+            return scoreDelta;
+        // Recency tie-break; ISO timestamps sort lexicographically.
+        if (a.completedAt < b.completedAt)
+            return 1;
+        if (a.completedAt > b.completedAt)
+            return -1;
+        return 0;
+    });
+    return picked.slice(0, maxDemos).map((exp) => ({
+        task: exp.task.trim(),
+        output: exp.output.trim(),
+        score: exp.feedback.score,
+        taskType: exp.taskType || "general",
+    }));
+}
+// ─── Rendering ──────────────────────────────────────────────────────────────
+/**
+ * Strip the demo-section marker literals out of quoted demo text. A past
+ * output that itself contains `<!-- darwin:demos:end -->` (e.g. an agent
+ * writing ABOUT Darwin) would otherwise plant an early end-marker inside the
+ * section — the next refresh cycle's lazy marker-to-marker match would then
+ * cut at the wrong span and leave half the old section dangling in the prompt.
+ */
+function stripMarkerLiterals(text) {
+    return text.split(DEMO_SECTION_START).join("").split(DEMO_SECTION_END).join("");
+}
+/** Truncate at the last sentence/newline boundary within `maxLength`. */
+function truncateAtSentenceBoundary(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    const truncated = text.slice(0, maxLength);
+    const lastPeriod = truncated.lastIndexOf(".");
+    const lastNewline = truncated.lastIndexOf("\n");
+    const cutPoint = Math.max(lastPeriod, lastNewline);
+    // Only honour the boundary when it keeps a meaningful chunk (> 40%).
+    const kept = cutPoint > maxLength * 0.4 ? truncated.slice(0, cutPoint + 1) : truncated;
+    return `${kept.trimEnd()} [...]`;
+}
+/**
+ * Render demo candidates as a marker-delimited prompt section.
+ *
+ * Returns an empty string for an empty demo list so callers can treat
+ * "nothing to inject" uniformly.
+ */
+export function buildDemoSection(demos, options = {}) {
+    if (demos.length === 0)
+        return "";
+    const maxTask = clampOption(options.maxTaskChars, 20, DEFAULT_DEMO_TASK_CHARS);
+    const maxOutput = clampOption(options.maxOutputChars, 80, DEFAULT_DEMO_OUTPUT_CHARS);
+    const blocks = demos.map((demo, i) => {
+        const task = truncateAtSentenceBoundary(stripMarkerLiterals(demo.task), maxTask);
+        const excerpt = truncateAtSentenceBoundary(stripMarkerLiterals(demo.output), maxOutput);
+        return (`### Demonstration ${i + 1} — task type "${demo.taskType}" (scored ${demo.score}/10)\n` +
+            `Task: ${task}\n` +
+            `Response excerpt:\n"""\n${excerpt}\n"""`);
+    });
+    return [DEMO_SECTION_START, DEMO_SECTION_INTRO, ...blocks, DEMO_SECTION_END].join("\n\n");
+}
+// ─── Application ────────────────────────────────────────────────────────────
+/** Regex matching one marker-delimited demo section (including markers). */
+const DEMO_SECTION_PATTERN = new RegExp(`${DEMO_SECTION_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${DEMO_SECTION_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+/**
+ * Apply a rendered demo section to a prompt.
+ *
+ * If the prompt already contains a marker-delimited demo section it is
+ * REPLACED in place (demos stay fresh, never stack); otherwise the section is
+ * appended after a blank line. An empty `section` returns the prompt with any
+ * existing demo section stripped — passing "no demos" acts as removal.
+ *
+ * The replacement uses a FUNCTION replacer: with a string replacer,
+ * `$&` / `$'` / `` $` `` / `$$` inside the section (an agent output quoting
+ * JS-regex or shell docs contains exactly these) would be interpreted as
+ * replacement patterns and garble the prompt on every refresh cycle.
+ */
+export function applyDemoSection(prompt, section) {
+    if (section === "")
+        return stripDemoSection(prompt);
+    if (DEMO_SECTION_PATTERN.test(prompt)) {
+        return prompt.replace(DEMO_SECTION_PATTERN, () => section);
+    }
+    const trimmed = prompt.replace(/\s+$/, "");
+    return `${trimmed}\n\n${section}`;
+}
+/**
+ * Remove the marker-delimited demo section (if any), collapsing the blank
+ * line that {@link applyDemoSection} inserted. Prompts without a section are
+ * returned unchanged.
+ */
+export function stripDemoSection(prompt) {
+    if (!DEMO_SECTION_PATTERN.test(prompt))
+        return prompt;
+    return prompt.replace(DEMO_SECTION_PATTERN, "").replace(/\n{3,}/g, "\n\n").replace(/\s+$/, "");
+}
+//# sourceMappingURL=demos.js.map

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

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

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

@@ -39,11 +39,11 @@ export declare function setEvolutionEnabled(memory: MemoryProvider, agentName: s
  * ({@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.
+ * Only the advanced flags in {@link OVERRIDE_KEYS} 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`.

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

@@ -1 +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"}
+{"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;AAeD;;;;;;;;;;;;;;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,CAgC7B;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

@@ -58,6 +58,8 @@ const OVERRIDE_KEYS = [
     'paretoGate',
     'useCoverage',
     'reflectionModel',
+    'useDemos',
+    'candidateSelection',
 ];
 /**
  * Resolve the effective {@link EvolutionConfig} for an agent: the static
@@ -65,11 +67,11 @@ const OVERRIDE_KEYS = [
  * ({@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.
+ * Only the advanced flags in {@link OVERRIDE_KEYS} 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`.
@@ -95,6 +97,9 @@ export function resolveEvolutionConfig(agent, state, cliOverride) {
                 if (key === 'reflectionModel') {
                     resolved.reflectionModel = value;
                 }
+                else if (key === 'candidateSelection') {
+                    resolved.candidateSelection = value;
+                }
                 else {
                     resolved[key] = value;
                 }

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

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

@@ -58,6 +58,13 @@ interface DarwinLoopDeps {
      * (only used when `embed` is set). Default 0.82.
      */
     alignmentSimilarityThreshold?: number;
+    /**
+     * v0.10.0 — Random source in [0, 1) for the stochastic parent-selection
+     * strategies (`candidateSelection: 'pareto' | 'epsilon-greedy'`). Injected
+     * for deterministic tests; default `Math.random`. Never consulted on the
+     * default `'active'` path.
+     */
+    rng?: () => number;
 }
 export declare class DarwinLoop {
     private memory;
@@ -70,6 +77,7 @@ export declare class DarwinLoop {
     private gepa?;
     private embed?;
     private alignmentSimilarityThreshold?;
+    private rng?;
     constructor(deps: DarwinLoopDeps);
     /**
      * Called AFTER every agent run. Drives the evolution cycle.
@@ -173,6 +181,34 @@ export declare class DarwinLoop {
      * v0.7.0 — Merge cadence (every K-th cycle). Default 3, clamped ≥ 1.
      */
     private mergeEveryK;
+    /**
+     * v0.10.0 — Demo-injection cadence (every K-th cycle). Default 4, clamped
+     * ≥ 1. Deliberately offset from the merge default (3) so the two
+     * non-reflective challenger sources don't collide on the same cycles.
+     */
+    private demoEveryK;
+    /**
+     * v0.10.0 — Build a SIMBA-style demo challenger: current prompt + a
+     * marker-delimited "Demonstrations" section harvested from this agent's
+     * highest-scoring past runs. Pure selection + rendering — no LLM call.
+     *
+     * Returns `null` (→ caller falls through to GEPA/legacy generation) when
+     * no run qualifies (score/threshold/length filters) or when the rendered
+     * demo set is byte-identical to what the prompt already carries — an A/B
+     * test of a version against itself would be pointless.
+     */
+    private tryDemoVariant;
+    /**
+     * v0.10.0 — Scored version history for parent selection AND merge: every
+     * prompt version that has text and at least one run's worth of averaged
+     * metrics, as {@link ScoredVariant}s. One getAverageMetrics
+     * (→ loadExperiments) call per version. O(N) backend round-trips, but N is
+     * the agent's prompt-version count (≤ ~20 in practice) and this only runs
+     * on selection/merge cadences, so it is cheap — same pattern handleABTest
+     * already uses for the Pareto gate. (Extracted from tryMergeVariant,
+     * behaviour unchanged.)
+     */
+    private buildScoredHistory;
     /**
      * v0.7.0 — GEPA system-aware MERGE (paper Appendix-D). Builds scored
      * variants from this agent's prompt-version history (each version's prompt

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

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../../src/evolution/loop.ts"],"names":[],"mappings":"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"}
+{"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;AAO9G,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;IACtC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;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;IAC9C,OAAO,CAAC,GAAG,CAAC,CAAe;gBAEf,IAAI,EAAE,cAAc;IAchC;;;;;;;;;;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;YA8ItB,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;IAkHjC;;;;;;;;OAQG;YACW,iBAAiB;IAa/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAMlB;;;;;;;;;OASG;YACW,cAAc;IAa5B;;;;;;;;;OASG;YACW,kBAAkB;IAYhC;;;;;;;;;;;;OAYG;YACW,eAAe;IAgC7B;;;;;;;;;;;;;;;;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"}

package/dist/src/evolution/loop.js

@@ -13,6 +13,8 @@ import { notifyABTestComplete, notifyEvolutionStarted, notifyRollback } from './
 import { epochShuffledMinibatch } from './optimizer-gepa.js';
 import { checkAlignmentPreservation, checkAlignmentPreservationSemantic } from './alignment.js';
 import { dominatesEpsilon, paretoSelect, DARWIN_DEFAULT_OBJECTIVES } from './pareto.js';
+import { selectDemoCandidates, buildDemoSection, applyDemoSection } from './demos.js';
+import { selectParentVariant } from './selection.js';
 // ─── Validation Constants ─────────────────────────────
 /** Default minimum output length (overridden by agent.evolution.minOutputLength) */
 const DEFAULT_MIN_VALID_OUTPUT = 2000;
@@ -30,6 +32,7 @@ export class DarwinLoop {
     gepa;
     embed;
     alignmentSimilarityThreshold;
+    rng;
     constructor(deps) {
         this.memory = deps.memory;
         this.tracker = deps.tracker;
@@ -41,6 +44,7 @@ export class DarwinLoop {
         this.gepa = deps.gepa;
         this.embed = deps.embed;
         this.alignmentSimilarityThreshold = deps.alignmentSimilarityThreshold;
+        this.rng = deps.rng;
     }
     /**
      * Called AFTER every agent run. Drives the evolution cycle.
@@ -250,7 +254,33 @@ export class DarwinLoop {
         // optimizer so the loop never stalls.
         let newPromptText = null;
         let generatedBy = 'legacy';
-        if (this.agent?.evolution?.useGepa === true && this.gepa) {
+        // ── v0.10.0: SIMBA-style demo injection (opt-in, zero LLM cost) ──
+        // On every demoEveryK-th cycle, build a challenger by appending (or
+        // refreshing) a "Demonstrations" section harvested from the agent's own
+        // highest-scoring past runs. Independent of useGepa — no reflector is
+        // involved. The demo prompt runs the same alignment guard and enters the
+        // same A/B test as any mutation; when demos don't help, the incumbent
+        // wins. When the demo set is unchanged since the last injection the path
+        // yields no challenger (no-op) and falls through to GEPA/legacy.
+        if (this.agent?.evolution?.useDemos === true) {
+            const epoch = this.versionInt(activePrompt.version);
+            if (epoch > 0 && epoch % this.demoEveryK() === 0) {
+                const demoPrompt = await this.tryDemoVariant(agent, activePrompt.promptText);
+                if (demoPrompt !== null) {
+                    const guarded = await this.runAlignmentGuard(activePrompt.promptText, demoPrompt);
+                    if (guarded !== null) {
+                        newPromptText = guarded;
+                        generatedBy = 'demos';
+                    }
+                    else {
+                        // Mirrors the merge-path breadcrumb: a consistently guard-failing
+                        // demo section should be visible, not silently skipped forever.
+                        console.warn(`[darwin] demo variant for "${agent}" failed the alignment guard, falling through.`);
+                    }
+                }
+            }
+        }
+        if (newPromptText === null && this.agent?.evolution?.useGepa === true && this.gepa) {
             // Epoch = the integer of the active prompt version (v1→1, v12→12). It
             // advances by one each evolution cycle, so the epoch-shuffled minibatch
             // rotates which feedback subset the reflector sees per cycle, and the
@@ -273,10 +303,11 @@ export class DarwinLoop {
             promptText: newPromptText,
             createdAt: new Date().toISOString(),
             parentVersion: activePrompt.version,
-            // Only tag the change reason with the generator when GEPA was opted in —
-            // keeps the stored `changeReason` byte-for-byte identical for legacy-only
+            // Only tag the change reason with the generator when a non-legacy
+            // challenger source was opted in (GEPA v0.6.0 / demos v0.10.0) — keeps
+            // the stored `changeReason` byte-for-byte identical for legacy-only
             // agents (v0.6.0 review Finding 8).
-            changeReason: this.agent?.evolution?.useGepa
+            changeReason: this.agent?.evolution?.useGepa || this.agent?.evolution?.useDemos
                 ? `[${generatedBy}] ${this.buildChangeReason(detectedPatterns)}`
                 : this.buildChangeReason(detectedPatterns),
             active: false, // Not active yet — going into A/B test
@@ -305,7 +336,9 @@ export class DarwinLoop {
         result.promptEvolved = true;
         result.abTestStarted = true;
         result.newVersion = newVersion;
-        const genLabel = this.agent?.evolution?.useGepa ? ` via ${generatedBy}` : '';
+        const genLabel = this.agent?.evolution?.useGepa || this.agent?.evolution?.useDemos
+            ? ` via ${generatedBy}`
+            : '';
         result.message = `New prompt ${newVersion} generated${genLabel}. A/B test started: ${activePrompt.version} vs ${newVersion} (minRuns: ${dynamicMinRuns}).`;
         // Notify via Telegram (non-blocking)
         notifyEvolutionStarted(this.notifications, agent, activePrompt.version, newVersion, this.buildChangeReason(detectedPatterns)).catch(() => { });
@@ -554,10 +587,31 @@ export class DarwinLoop {
         // currently-active prompt. Falls back to the active prompt when fewer than
         // two versions carry per-task-type data (selectCoverageParent → null).
         let parentPrompt = currentPrompt;
+        let parentChosen = false;
         if (this.agent?.evolution?.useCoverage === true) {
             const coverageParent = await this.selectCoverageParent(agentName);
             if (coverageParent !== null) {
                 parentPrompt = coverageParent;
+                parentChosen = true;
+            }
+        }
+        // v0.10.0: GEPA candidate_selection_strategy parity (opt-in via
+        // evolution.candidateSelection). Pick the reflection parent from the
+        // agent's SCORED version history — 'best' (current_best), 'pareto'
+        // (uniform sample from the non-dominated front), or 'epsilon-greedy'
+        // (explore/exploit). Coverage selection (the more specific GEPA
+        // Algorithm 2 selector) takes precedence when it found a parent; this
+        // strategy is the fallback for that cycle. 'active'/unset keeps the
+        // historical reflect-from-active-prompt behaviour byte-for-byte.
+        const strategy = this.agent?.evolution?.candidateSelection;
+        if (!parentChosen && strategy !== undefined && strategy !== 'active') {
+            const scored = await this.buildScoredHistory(agentName);
+            const chosen = selectParentVariant(scored, strategy, {
+                epsilon: this.agent?.evolution?.explorationEpsilon,
+                rng: this.rng,
+            });
+            if (chosen !== null) {
+                parentPrompt = chosen.prompt;
             }
         }
         // v0.7.0: pull the configurable feedback window (default 15, was 5).
@@ -625,6 +679,64 @@ export class DarwinLoop {
             return Math.floor(k);
         return 3;
     }
+    /**
+     * v0.10.0 — Demo-injection cadence (every K-th cycle). Default 4, clamped
+     * ≥ 1. Deliberately offset from the merge default (3) so the two
+     * non-reflective challenger sources don't collide on the same cycles.
+     */
+    demoEveryK() {
+        const k = this.agent?.evolution?.demoEveryK;
+        if (typeof k === 'number' && Number.isFinite(k) && k >= 1)
+            return Math.floor(k);
+        return 4;
+    }
+    /**
+     * v0.10.0 — Build a SIMBA-style demo challenger: current prompt + a
+     * marker-delimited "Demonstrations" section harvested from this agent's
+     * highest-scoring past runs. Pure selection + rendering — no LLM call.
+     *
+     * Returns `null` (→ caller falls through to GEPA/legacy generation) when
+     * no run qualifies (score/threshold/length filters) or when the rendered
+     * demo set is byte-identical to what the prompt already carries — an A/B
+     * test of a version against itself would be pointless.
+     */
+    async tryDemoVariant(agentName, currentPrompt) {
+        const experiments = await this.memory.loadExperiments(agentName);
+        const demos = selectDemoCandidates(experiments, {
+            maxDemos: this.agent?.evolution?.maxDemos,
+            scoreThreshold: this.agent?.evolution?.demoScoreThreshold,
+        });
+        if (demos.length === 0)
+            return null;
+        const section = buildDemoSection(demos);
+        const withDemos = applyDemoSection(currentPrompt, section);
+        if (withDemos === currentPrompt)
+            return null;
+        return withDemos;
+    }
+    /**
+     * v0.10.0 — Scored version history for parent selection AND merge: every
+     * prompt version that has text and at least one run's worth of averaged
+     * metrics, as {@link ScoredVariant}s. One getAverageMetrics
+     * (→ loadExperiments) call per version. O(N) backend round-trips, but N is
+     * the agent's prompt-version count (≤ ~20 in practice) and this only runs
+     * on selection/merge cadences, so it is cheap — same pattern handleABTest
+     * already uses for the Pareto gate. (Extracted from tryMergeVariant,
+     * behaviour unchanged.)
+     */
+    async buildScoredHistory(agentName) {
+        const versions = await this.memory.getAllPromptVersions(agentName);
+        const scored = [];
+        for (const v of versions) {
+            if (!v.promptText)
+                continue;
+            const metrics = await this.tracker.getAverageMetrics(agentName, v.version);
+            if (Object.keys(metrics).length === 0)
+                continue; // no runs for this version
+            scored.push({ id: v.version, prompt: v.promptText, metrics });
+        }
+        return scored;
+    }
     /**
      * v0.7.0 — GEPA system-aware MERGE (paper Appendix-D). Builds scored
      * variants from this agent's prompt-version history (each version's prompt
@@ -641,20 +753,7 @@ export class DarwinLoop {
     async tryMergeVariant(agentName) {
         if (!this.gepa)
             return null;
-        const versions = await this.memory.getAllPromptVersions(agentName);
-        const scored = [];
-        // One getAverageMetrics (→ loadExperiments) call per version. O(N) backend
-        // round-trips, but N is the agent's prompt-version count (≤ ~20 in
-        // practice) and this only runs on the merge cadence, so it is cheap — same
-        // pattern handleABTest already uses for the Pareto gate.
-        for (const v of versions) {
-            if (!v.promptText)
-                continue;
-            const metrics = await this.tracker.getAverageMetrics(agentName, v.version);
-            if (Object.keys(metrics).length === 0)
-                continue; // no runs for this version
-            scored.push({ id: v.version, prompt: v.promptText, metrics });
-        }
+        const scored = await this.buildScoredHistory(agentName);
         if (scored.length < 2)
             return null; // need two parents to merge
         // Two best Pareto-front members (distinct versions, scalarised tie-break).