darwin-agents 0.9.0 → 0.11.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;AAiBD;;;;;;;;;;;;;;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,CAoC7B;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,10 @@ const OVERRIDE_KEYS = [
     'paretoGate',
     'useCoverage',
     'reflectionModel',
+    'useDemos',
+    'candidateSelection',
+    'skipPerfectFeedback',
+    'maxMergeInvocations',
 ];
 /**
  * Resolve the effective {@link EvolutionConfig} for an agent: the static
@@ -65,11 +69,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,7 +99,15 @@ export function resolveEvolutionConfig(agent, state, cliOverride) {
                 if (key === 'reflectionModel') {
                     resolved.reflectionModel = value;
                 }
+                else if (key === 'candidateSelection') {
+                    resolved.candidateSelection = value;
+                }
+                else if (key === 'maxMergeInvocations') {
+                    resolved.maxMergeInvocations = value;
+                }
                 else {
+                    // Remaining override keys are all boolean flags (useGepa / useMerge /
+                    // paretoGate / useCoverage / useDemos / skipPerfectFeedback).
                     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/feedback-filter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Perfect-score feedback filtering (v0.11.0) — adapted from GEPA's
+ * `skip_perfect_score` for Darwin's online evolution loop.
+ *
+ * What upstream actually does (gepa-ai `reflective_mutation.py`): after
+ * sampling a minibatch and scoring the candidate on it, GEPA skips the WHOLE
+ * reflection iteration when EVERY minibatch score is perfect — it does not drop
+ * individual instances, and a perfect instance inside a mixed minibatch is kept
+ * (positive contrast for the reflector).
+ *
+ * Darwin generalizes this to per-report filtering, which upstream can't do
+ * cheaply but Darwin can: the critic scores on real runs are already paid for,
+ * so there is no eval-budget reason to keep perfect ("nothing to fix") reports
+ * in the pool the reflector / legacy optimizer learns from. Dropping them
+ * concentrates the feedback on runs that actually went wrong. (The perfect runs
+ * are not wasted — with `useDemos` they are harvested as demonstrations, so
+ * failures feed reflection and successes feed demos.)
+ *
+ * Purity: no I/O, no LLM calls, deterministic. The predicate is generic over
+ * any `{ score: number }` so both feedback assemblers in the loop
+ * (`getReflectiveFeedback` → `ReflectiveFeedback`, `getRecentFeedback` →
+ * built-inline) share one source of truth and cannot drift. The loop filters
+ * inline during the feedback-window fill (so skipped items don't count toward
+ * the window `limit`); `filterPerfectFeedback` is exported as a convenience for
+ * consumers assembling their own feedback lists.
+ */
+/**
+ * Critic scores are on the 1–10 scale (see `parse-score.ts`). The default
+ * perfect threshold is a literal top score — only 10/10 is skipped unless the
+ * caller lowers it.
+ */
+export declare const DEFAULT_PERFECT_FEEDBACK_SCORE = 10;
+/**
+ * Resolve a perfect-score threshold to a usable value: finite and within the
+ * critic 1–10 scale, else the default. A non-finite / out-of-range config
+ * value (hand-edited file, `NaN`) must never silently disable or invert the
+ * filter — it falls back to {@link DEFAULT_PERFECT_FEEDBACK_SCORE}.
+ */
+export declare function resolvePerfectFeedbackScore(value: number | undefined): number;
+/**
+ * True when a run's critic score is at or above the perfect threshold and so
+ * carries no improvement gradient. A non-finite score (missing / unparsed) is
+ * never "perfect" — it is kept so a genuinely broken run still surfaces to the
+ * optimizer rather than being silently dropped as if it were flawless.
+ */
+export declare function isPerfectScore(score: number, threshold: number): boolean;
+/**
+ * Drop perfect-score items from a feedback list. Generic over `{ score }` so
+ * the exact feedback shape is the caller's; order is preserved.
+ */
+export declare function filterPerfectFeedback<T extends {
+    score: number;
+}>(items: readonly T[], threshold: number): T[];
+//# sourceMappingURL=feedback-filter.d.ts.map

package/dist/src/evolution/feedback-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-filter.d.ts","sourceRoot":"","sources":["../../../src/evolution/feedback-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAGxE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAC/D,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,SAAS,EAAE,MAAM,GAChB,CAAC,EAAE,CAEL"}

package/dist/src/evolution/feedback-filter.js

@@ -0,0 +1,65 @@
+/**
+ * Perfect-score feedback filtering (v0.11.0) — adapted from GEPA's
+ * `skip_perfect_score` for Darwin's online evolution loop.
+ *
+ * What upstream actually does (gepa-ai `reflective_mutation.py`): after
+ * sampling a minibatch and scoring the candidate on it, GEPA skips the WHOLE
+ * reflection iteration when EVERY minibatch score is perfect — it does not drop
+ * individual instances, and a perfect instance inside a mixed minibatch is kept
+ * (positive contrast for the reflector).
+ *
+ * Darwin generalizes this to per-report filtering, which upstream can't do
+ * cheaply but Darwin can: the critic scores on real runs are already paid for,
+ * so there is no eval-budget reason to keep perfect ("nothing to fix") reports
+ * in the pool the reflector / legacy optimizer learns from. Dropping them
+ * concentrates the feedback on runs that actually went wrong. (The perfect runs
+ * are not wasted — with `useDemos` they are harvested as demonstrations, so
+ * failures feed reflection and successes feed demos.)
+ *
+ * Purity: no I/O, no LLM calls, deterministic. The predicate is generic over
+ * any `{ score: number }` so both feedback assemblers in the loop
+ * (`getReflectiveFeedback` → `ReflectiveFeedback`, `getRecentFeedback` →
+ * built-inline) share one source of truth and cannot drift. The loop filters
+ * inline during the feedback-window fill (so skipped items don't count toward
+ * the window `limit`); `filterPerfectFeedback` is exported as a convenience for
+ * consumers assembling their own feedback lists.
+ */
+/**
+ * Critic scores are on the 1–10 scale (see `parse-score.ts`). The default
+ * perfect threshold is a literal top score — only 10/10 is skipped unless the
+ * caller lowers it.
+ */
+export const DEFAULT_PERFECT_FEEDBACK_SCORE = 10;
+/**
+ * Resolve a perfect-score threshold to a usable value: finite and within the
+ * critic 1–10 scale, else the default. A non-finite / out-of-range config
+ * value (hand-edited file, `NaN`) must never silently disable or invert the
+ * filter — it falls back to {@link DEFAULT_PERFECT_FEEDBACK_SCORE}.
+ */
+export function resolvePerfectFeedbackScore(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return DEFAULT_PERFECT_FEEDBACK_SCORE;
+    }
+    if (value < 1 || value > 10)
+        return DEFAULT_PERFECT_FEEDBACK_SCORE;
+    return value;
+}
+/**
+ * True when a run's critic score is at or above the perfect threshold and so
+ * carries no improvement gradient. A non-finite score (missing / unparsed) is
+ * never "perfect" — it is kept so a genuinely broken run still surfaces to the
+ * optimizer rather than being silently dropped as if it were flawless.
+ */
+export function isPerfectScore(score, threshold) {
+    if (!Number.isFinite(score))
+        return false;
+    return score >= threshold;
+}
+/**
+ * Drop perfect-score items from a feedback list. Generic over `{ score }` so
+ * the exact feedback shape is the caller's; order is preserved.
+ */
+export function filterPerfectFeedback(items, threshold) {
+    return items.filter((item) => !isPerfectScore(item.score, threshold));
+}
+//# sourceMappingURL=feedback-filter.js.map

package/dist/src/evolution/feedback-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-filter.js","sourceRoot":"","sources":["../../../src/evolution/feedback-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAyB;IACnE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,8BAA8B,CAAC;IACxC,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,8BAA8B,CAAC;IACnE,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,SAAiB;IAC7D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,KAAK,IAAI,SAAS,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAmB,EACnB,SAAiB;IAEjB,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;AACxE,CAAC"}

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.
@@ -140,6 +148,12 @@ export declare class DarwinLoop {
      * from loadExperiments(), so we just filter for ones with feedback.
      */
     private getRecentFeedback;
+    /**
+     * v0.11.0 — Resolved perfect-score threshold for {@link
+     * EvolutionConfig.skipPerfectFeedback} (finite, within the critic 1–10
+     * scale, else default 10).
+     */
+    private perfectFeedbackScore;
     /**
      * v0.6.0 — Generate the next prompt variant via the GEPA reflective path.
      *
@@ -173,6 +187,62 @@ export declare class DarwinLoop {
      * v0.7.0 — Merge cadence (every K-th cycle). Default 3, clamped ≥ 1.
      */
     private mergeEveryK;
+    /**
+     * v0.11.0 — Resolved lifetime merge cap (GEPA `max_merge_invocations`), or
+     * `null` when uncapped. A non-finite / negative value is treated as "no cap"
+     * rather than silently disabling merge; a non-integer cap is floored (mirrors
+     * `mergeEveryK`) so a hand-edited `2.5` behaves as 2, not 3.
+     */
+    private mergeCap;
+    /**
+     * v0.11.0 — Lifetime merge budget check (GEPA `max_merge_invocations`).
+     * Returns `true` (merge may fire) when no cap is configured, or when the
+     * per-agent count of merge-derived challengers is still below the cap.
+     */
+    private mergeBudgetAvailable;
+    /**
+     * v0.11.0 — Increment this agent's lifetime merge-invocation count. Called
+     * once per merge challenger that passes the alignment guard and is carried
+     * into an A/B test, and ONLY when a cap is configured — an uncapped useMerge
+     * agent never writes the counter, so its persisted state is unchanged from
+     * v0.10. Initialises the map lazily for state rows that predate the field.
+     *
+     * The check (`mergeBudgetAvailable`) and this increment are separate state
+     * reads, so two cycles running concurrently for the SAME agent could each
+     * observe `used = cap-1` and overshoot by one. The overshoot is bounded by
+     * the concurrency and sits inside the pre-existing concurrent-A/B-start
+     * envelope (afterRun's "an A/B test is already running" guard is likewise
+     * check-then-act) — acceptable for a soft lifetime budget, not a hard limit.
+     */
+    private recordMergeInvocation;
+    /**
+     * 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;AAQ9G,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;IAqB/B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;;;;;;;;;;;;;;;;OAiBG;YACW,mBAAmB;IAyHjC;;;;;;;;OAQG;YACW,iBAAiB;IAa/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAMhB;;;;OAIG;YACW,oBAAoB;IAQlC;;;;;;;;;;;;;OAaG;YACW,qBAAqB;IASnC;;;;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;IA4BnC;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAKvB;;;OAGG;YACW,mBAAmB;IAiDjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}