darwin-agents 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,111 @@
 
 ## [Unreleased]
 
+## [0.11.0] — 2026-07-09
+
+Two opt-in "budget discipline" knobs adapted from GEPA (verified against the
+DSPy GEPA API and the gepa-ai engine source) to Darwin's forever-online loop.
+The values mirror upstream's defaults; the mechanisms are Darwin's own
+adaptation. Default behaviour is unchanged with the flags off.
+
+### Added
+
+- **`skipPerfectFeedback`** (adapted from GEPA's `skip_perfect_score`,
+  `src/evolution/feedback-filter.ts`). Upstream skips a whole reflection
+  iteration when an entire sampled minibatch is perfect; Darwin generalizes it
+  to per-report filtering, which it can afford because the critic scores on real
+  runs are already paid for. A run that already scored a perfect critic score
+  carries no improvement gradient — its "nothing to fix" report only dilutes the
+  pool. When `true`, such reports are dropped from **both** the legacy optimizer
+  feedback (`getRecentFeedback`) and the GEPA reflective feedback
+  (`getReflectiveFeedback`); skipped items do not count toward the feedback
+  window, so it fills with actionable reports. `perfectFeedbackScore` (default
+  10, the critic-scale max) sets the threshold — lower it to also skip
+  near-perfect runs. A non-finite score is never treated as perfect, so a
+  genuinely broken run still surfaces. If every recent run is perfect the
+  reflective path falls back to the legacy stats optimizer and the legacy path
+  proceeds on aggregate stats (so the loop keeps exploring). With `useDemos` on,
+  perfect runs are still used — harvested as demonstrations. CLI: `--skip-perfect`
+  / `--no-skip-perfect`. Pure helpers (`isPerfectScore` /
+  `resolvePerfectFeedbackScore` / `filterPerfectFeedback`) are exported from the
+  package root.
+- **`maxMergeInvocations`** (adapted from GEPA's `max_merge_invocations`, default
+  5 upstream). A per-agent **lifetime** cap on merge-derived challengers,
+  persisted in `DarwinState.mergeInvocations` (a process-scoped counter would
+  reset every cron tick and never trigger). The GEPA paper leaves merge-budget
+  allocation as open research; the reason Darwin needs a cap is its own — an
+  uncapped `mergeEveryK` cadence would merge forever and crowd out reflective
+  exploration late in an agent's life. The count is the number of merge
+  challengers actually **created** — a merge that fails the alignment guard is
+  not counted (it consumed no A/B slot) — and is written **only when a cap is
+  set**, so an uncapped `useMerge` agent's persisted state is unchanged from
+  v0.10. Once the cap is reached the merge branch is skipped and the loop falls
+  back to the reflective path for the rest of the agent's life (the budget does
+  not re-arm). Only consulted when `useMerge` is on. Left unset it is uncapped
+  (v0.10 behaviour); set it to `5` to match GEPA's default. CLI: `--max-merge <n>`
+  (non-negative integer; `0` disables merge).
+
+### Notes
+
+- Both knobs flow through the existing override machinery
+  (`EvolutionConfigOverride` + `OVERRIDE_KEYS` + `resolveEvolutionConfig` +
+  `describeOverride`/`describeConfig`), so they are CLI-settable, persist across
+  processes, and CLI overrides win over persisted ones.
+- +24 tests (610 total, 609 pass / 1 pre-existing skip). `tsc`, `typecheck:tests`
+  and `build` clean. Default-path decisions unchanged; an uncapped agent writes
+  no new state.
+
+## [0.10.0] — 2026-07-03
+
+Two research-driven, opt-in evolution surfaces — a new challenger *source*
+(demo injection) and a new parent-*selection* strategy for the existing
+reflective challenger — both validated against the current state of the field
+(GEPA upstream docs, DSPy SIMBA) before a line was written. Default behaviour
+is byte-for-byte unchanged with the flags off.
+
+### Added
+
+- **SIMBA-style demo injection** (`src/evolution/demos.ts` + `evolution.useDemos`).
+  DSPy's SIMBA optimizer improves programs two ways: appending self-reflective
+  *rules* (Darwin's reflector already covers that ground) and appending
+  successful past examples as *demonstrations*. This release adapts the second
+  strategy to the online loop: on every `demoEveryK`-th evolution cycle (default
+  4) the loop harvests the agent's own highest-scoring past runs (score ≥
+  `demoScoreThreshold`, default 8; at most one demo per task type for
+  diversity; `maxDemos` cap, default 2) and appends them as a marker-delimited
+  "Demonstrations" section. The demo-augmented prompt is a normal challenger —
+  same alignment guard, same A/B test, same safety gate; if demos don't help
+  this agent, the incumbent wins. **Zero LLM cost** (pure selection +
+  rendering on data Darwin already persists), works with or without `useGepa`,
+  idempotent via `<!-- darwin:demos:start/end -->` markers (a later cycle
+  *refreshes* the section, never stacks a second one). Pure helpers
+  (`selectDemoCandidates` / `buildDemoSection` / `applyDemoSection` /
+  `stripDemoSection`) are exported from the package root. CLI: `--demos` /
+  `--no-demos`.
+
+- **Parent-selection strategies** (`src/evolution/selection.ts` +
+  `evolution.candidateSelection`) — GEPA `candidate_selection_strategy` parity
+  for the online loop. Historically the loop always reflected from the
+  currently-active prompt (a hill-climb that can sit on a local optimum).
+  Opt-in strategies pick the reflection parent from the agent's *scored
+  version history* instead: `'best'` (GEPA `current_best` — highest
+  scalarised composite), `'pareto'` (GEPA default — uniform sample from the
+  non-dominated front, keeping lineages alive that win on different
+  objectives), `'epsilon-greedy'` (explore with probability
+  `explorationEpsilon`, default 0.1, exploit otherwise). The RNG is
+  injectable via the new `DarwinLoopDeps.rng` for deterministic tests.
+  Precedence: `useCoverage` (GEPA Algorithm 2, the more specific selector)
+  wins when it finds a coverage parent. Only consulted when `useGepa` is on.
+  CLI: `--candidate-selection <active|best|pareto|epsilon-greedy>`.
+
+### Internal
+
+- `tryMergeVariant`'s version-history scoring extracted into a shared
+  `buildScoredHistory` (used by merge *and* parent selection) — behaviour
+  unchanged.
+- `package.json` now lists Claude (Anthropic) as a contributor — see the
+  README's new **Credits** section for how this project is actually built.
+
 ## [0.9.0] — 2026-06-21
 
 ### Added

package/README.md

@@ -222,6 +222,76 @@ bias. With only one key they collapse onto a single family (note: `claude-cli`
 and `anthropic-api` are the *same* family) — Darwin now warns, and hard-fails
 under `DARWIN_REQUIRE_CROSS_FAMILY=1` for strict / CI setups.
 
+### Demo injection + parent selection (v0.10, opt-in)
+
+Two more challenger surfaces, both borrowed from the strongest ideas in the
+field and adapted to the online loop. Both are off by default.
+
+**Demo injection** (`useDemos`) is DSPy SIMBA's `append_a_demo` strategy: on
+every `demoEveryK`-th cycle (default 4) the loop harvests the agent's *own
+highest-scoring past runs* (score ≥ 8, one per task type, capped at
+`maxDemos`) and appends them to the prompt as a marker-delimited
+"Demonstrations" section. Zero LLM cost — pure selection over data Darwin
+already stores — and the demo-augmented prompt is a normal challenger: same
+alignment guard, same A/B test, same rollback. If showing the agent its own
+best work doesn't measurably help, the incumbent wins and nothing changes.
+
+**Parent selection** (`candidateSelection`) is GEPA's
+`candidate_selection_strategy`: instead of always mutating the currently-active
+prompt (a hill-climb), reflect from `'best'` (highest composite in the version
+history), `'pareto'` (uniform sample from the history's Pareto front — keeps
+lineages alive that win on *different* objectives), or `'epsilon-greedy'`
+(explore with probability `explorationEpsilon`). Requires `useGepa`.
+
+```typescript
+evolution: {
+  enabled: true,
+  useDemos: true,                    // SIMBA-style demos as a challenger source
+  demoEveryK: 4,                     // cadence (offset from mergeEveryK: 3)
+  maxDemos: 2,
+  useGepa: true,
+  candidateSelection: 'pareto',      // or 'best' | 'epsilon-greedy' | 'active'
+  explorationEpsilon: 0.1,           // only for 'epsilon-greedy'
+},
+```
+
+### Budget discipline (v0.11, opt-in)
+
+Two more knobs adapted from GEPA (the values mirror upstream; upstream ships
+both on, here they are off unless you turn them on).
+
+**Skip perfect feedback** (`skipPerfectFeedback`) adapts GEPA's
+`skip_perfect_score`. Upstream skips a whole reflection iteration when an entire
+sampled minibatch is perfect; Darwin generalizes it to per-report filtering,
+which it can afford because the critic scores on real runs are already paid for.
+A run that already scored a perfect critic score carries no improvement
+gradient, so its "nothing to fix" report just dilutes the pool. When on,
+perfect-score reports are dropped from *both* the legacy optimizer feedback and
+the GEPA reflection minibatch (lower `perfectFeedbackScore` from the default 10
+to also skip near-perfect runs). With `useDemos` on, those perfect runs still
+get used — harvested as demonstrations instead.
+
+**Merge budget** (`maxMergeInvocations`) adapts GEPA's `max_merge_invocations`
+(default 5 upstream): a per-agent *lifetime* cap on how many merge-derived
+challengers an agent may produce. The GEPA paper leaves merge-budget allocation
+as open research; the reason Darwin needs a cap is its own — an uncapped
+`mergeEveryK` cadence would merge forever, so late in an agent's life merges
+would crowd out the reflective exploration that finds genuinely new strategies.
+Once the cap is hit the loop falls back to the reflective path for good. Left
+unset it is uncapped (the v0.10 behaviour); set it to `5` to match GEPA's
+protective default.
+
+```typescript
+evolution: {
+  enabled: true,
+  useGepa: true,
+  skipPerfectFeedback: true,         // GEPA skip_perfect_score — focus feedback on failures
+  perfectFeedbackScore: 10,          // score (1-10) counted as "perfect" (default 10)
+  useMerge: true,
+  maxMergeInvocations: 5,            // GEPA max_merge_invocations — cap merge over the agent's life
+},
+```
+
 ## Built-in Agents
 
 | Agent | What it does | Needs |
@@ -465,6 +535,10 @@ darwin run writer "Explain consensus" --gepa --pareto-gate
 | `--pareto-gate` / `--no-pareto-gate` | Reject an A/B winner that regressed on any objective |
 | `--coverage` / `--no-coverage` | Pick the reflection parent by per-task-type coverage breadth (GEPA Algorithm 2) |
 | `--reflection-model <id>` | Use a stronger model for GEPA reflection (the documented leverage point) |
+| `--demos` / `--no-demos` | SIMBA-style demo injection: the agent's best past runs as a challenger (v0.10) |
+| `--candidate-selection <s>` | Reflection parent strategy: `active` \| `best` \| `pareto` \| `epsilon-greedy` (v0.10) |
+| `--skip-perfect` / `--no-skip-perfect` | Drop perfect-score runs from optimizer feedback — GEPA `skip_perfect_score` (v0.11) |
+| `--max-merge <n>` | Lifetime cap on merge-derived challengers — GEPA `max_merge_invocations` (v0.11) |
 
 All default to **off** — the baseline single-objective evolution loop is
 unchanged unless you opt in.
@@ -526,6 +600,19 @@ The safety gate prevents regressions. If a new variant scores >20% lower, Darwin
 
 PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Credits
+
+Darwin is pair-built by a human and an AI, and we think that should be said
+plainly rather than hidden. Matthias Meyer (StudioMeyer) sets direction, makes
+the calls and reviews everything; most of the code is written by
+[Claude](https://www.anthropic.com/claude) — currently **Claude Fable 5** —
+working from research against the primary sources (the GEPA paper and
+reference implementation, DSPy, the MCP spec) and gated by multi-agent code
+review plus this repo's own test suite before anything ships. Claude is listed
+as a contributor in `package.json`, and the commits it co-writes carry a
+`Co-Authored-By` trailer. A framework about agents that improve themselves,
+built with an agent — we find that fitting.
+
 ## About StudioMeyer
 
 [StudioMeyer](https://studiomeyer.io) is an AI and design studio based in Palma de Mallorca, working with clients worldwide. We build custom websites and AI infrastructure for small and medium businesses. Production stack on Claude Agent SDK, MCP and n8n, with Sentry, Langfuse and LangGraph for observability and an in-house guard layer.

package/dist/src/cli/evolution-flags.d.ts

@@ -12,6 +12,10 @@
  *   --pareto-gate / --no-pareto-gate
  *   --coverage / --no-coverage
  *   --reflection-model <model-id>
+ *   --demos / --no-demos                                       (v0.10.0)
+ *   --candidate-selection <active|best|pareto|epsilon-greedy>  (v0.10.0)
+ *   --skip-perfect / --no-skip-perfect                         (v0.11.0)
+ *   --max-merge <n>                                            (v0.11.0)
  */
 import type { EvolutionConfigOverride } from '../types.js';
 /** True when `arg` is one of the evolution-config flags this module handles. */

package/dist/src/cli/evolution-flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evolution-flags.d.ts","sourceRoot":"","sources":["../../../src/cli/evolution-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAe1D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,uBAAuB,GAC9B,MAAM,CAmCR;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IACzD,QAAQ,EAAE,uBAAuB,CAAC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAaA;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAQ9E"}
+{"version":3,"file":"evolution-flags.d.ts","sourceRoot":"","sources":["../../../src/cli/evolution-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAU3D,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAqB1D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,uBAAuB,GAC9B,MAAM,CAoFR;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IACzD,QAAQ,EAAE,uBAAuB,CAAC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAaA;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAY9E"}

package/dist/src/cli/evolution-flags.js

@@ -12,7 +12,18 @@
  *   --pareto-gate / --no-pareto-gate
  *   --coverage / --no-coverage
  *   --reflection-model <model-id>
+ *   --demos / --no-demos                                       (v0.10.0)
+ *   --candidate-selection <active|best|pareto|epsilon-greedy>  (v0.10.0)
+ *   --skip-perfect / --no-skip-perfect                         (v0.11.0)
+ *   --max-merge <n>                                            (v0.11.0)
  */
+/** Valid values for `--candidate-selection` (v0.10.0). */
+const CANDIDATE_SELECTION_VALUES = new Set([
+    'active',
+    'best',
+    'pareto',
+    'epsilon-greedy',
+]);
 /** True when `arg` is one of the evolution-config flags this module handles. */
 export function isEvolutionConfigFlag(arg) {
     switch (arg) {
@@ -25,6 +36,12 @@ export function isEvolutionConfigFlag(arg) {
         case '--coverage':
         case '--no-coverage':
         case '--reflection-model':
+        case '--demos':
+        case '--no-demos':
+        case '--candidate-selection':
+        case '--skip-perfect':
+        case '--no-skip-perfect':
+        case '--max-merge':
             return true;
         default:
             return false;
@@ -70,6 +87,53 @@ export function applyEvolutionFlag(arg, nextArg, target) {
                 return 1;
             }
             return 0;
+        case '--demos':
+            target.useDemos = true;
+            return 0;
+        case '--no-demos':
+            target.useDemos = false;
+            return 0;
+        case '--candidate-selection':
+            // Value is consumed either way (it was clearly meant as this flag's
+            // argument); it is only APPLIED when it names a known strategy — an
+            // unknown value warns instead of silently persisting a config the loop
+            // would then silently treat as 'active'.
+            if (nextArg !== undefined) {
+                if (CANDIDATE_SELECTION_VALUES.has(nextArg)) {
+                    target.candidateSelection = nextArg;
+                }
+                else {
+                    console.warn(`[darwin] --candidate-selection "${nextArg}" is not one of: ${[...CANDIDATE_SELECTION_VALUES].join(', ')} — ignored.`);
+                }
+                return 1;
+            }
+            return 0;
+        case '--skip-perfect':
+            target.skipPerfectFeedback = true;
+            return 0;
+        case '--no-skip-perfect':
+            target.skipPerfectFeedback = false;
+            return 0;
+        case '--max-merge': {
+            // A missing value (end of argv) or a following FLAG (`--max-merge
+            // --force`) is a missing value, not this flag's argument — warn and do
+            // NOT consume the next token, so a following action flag still runs.
+            if (nextArg === undefined || nextArg.startsWith('--')) {
+                console.warn('[darwin] --max-merge needs a non-negative integer value — ignored.');
+                return 0;
+            }
+            // Strict non-negative-integer match rejects '', ' ', '-3', '2.5', '0x10',
+            // '1e3', 'abc' (Number() would coerce several of those, e.g. Number('')
+            // === 0, silently disabling merge for the agent's life). The value token
+            // is consumed either way — it was clearly meant as this flag's argument.
+            if (/^\d+$/.test(nextArg.trim())) {
+                target.maxMergeInvocations = Number(nextArg.trim());
+            }
+            else {
+                console.warn(`[darwin] --max-merge "${nextArg}" is not a non-negative integer — ignored.`);
+            }
+            return 1;
+        }
         default:
             return 0;
     }
@@ -101,6 +165,10 @@ export function hasAnyEvolutionFlag(override) {
         override.useMerge !== undefined ||
         override.paretoGate !== undefined ||
         override.useCoverage !== undefined ||
-        override.reflectionModel !== undefined);
+        override.reflectionModel !== undefined ||
+        override.useDemos !== undefined ||
+        override.candidateSelection !== undefined ||
+        override.skipPerfectFeedback !== undefined ||
+        override.maxMergeInvocations !== undefined);
 }
 //# sourceMappingURL=evolution-flags.js.map

package/dist/src/cli/evolution-flags.js.map

@@ -1 +1 @@
-{"version":3,"file":"evolution-flags.js","sourceRoot":"","sources":["../../../src/cli/evolution-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,gFAAgF;AAChF,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,WAAW,CAAC;QACjB,KAAK,SAAS,CAAC;QACf,KAAK,YAAY,CAAC;QAClB,KAAK,eAAe,CAAC;QACrB,KAAK,kBAAkB,CAAC;QACxB,KAAK,YAAY,CAAC;QAClB,KAAK,eAAe,CAAC;QACrB,KAAK,oBAAoB;YACvB,OAAO,IAAI,CAAC;QACd;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,OAA2B,EAC3B,MAA+B;IAE/B,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,QAAQ;YACX,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;YACtB,OAAO,CAAC,CAAC;QACX,KAAK,WAAW;YACd,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,KAAK,SAAS;YACZ,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,KAAK,YAAY;YACf,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC;YACxB,OAAO,CAAC,CAAC;QACX,KAAK,eAAe;YAClB,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;YACzB,OAAO,CAAC,CAAC;QACX,KAAK,kBAAkB;YACrB,MAAM,CAAC,UAAU,GAAG,KAAK,CAAC;YAC1B,OAAO,CAAC,CAAC;QACX,KAAK,YAAY;YACf,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC;YAC1B,OAAO,CAAC,CAAC;QACX,KAAK,eAAe;YAClB,MAAM,CAAC,WAAW,GAAG,KAAK,CAAC;YAC3B,OAAO,CAAC,CAAC;QACX,KAAK,oBAAoB;YACvB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,CAAC,eAAe,GAAG,OAAO,CAAC;gBACjC,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,CAAC,CAAC;QACX;YACE,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAc;IAItD,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,qBAAqB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YAChE,CAAC,IAAI,QAAQ,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,mBAAmB,CAAC,QAAiC;IACnE,OAAO,CACL,QAAQ,CAAC,OAAO,KAAK,SAAS;QAC9B,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAC/B,QAAQ,CAAC,UAAU,KAAK,SAAS;QACjC,QAAQ,CAAC,WAAW,KAAK,SAAS;QAClC,QAAQ,CAAC,eAAe,KAAK,SAAS,CACvC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"evolution-flags.js","sourceRoot":"","sources":["../../../src/cli/evolution-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,0DAA0D;AAC1D,MAAM,0BAA0B,GAAwB,IAAI,GAAG,CAAC;IAC9D,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,gBAAgB;CACjB,CAAC,CAAC;AAEH,gFAAgF;AAChF,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,WAAW,CAAC;QACjB,KAAK,SAAS,CAAC;QACf,KAAK,YAAY,CAAC;QAClB,KAAK,eAAe,CAAC;QACrB,KAAK,kBAAkB,CAAC;QACxB,KAAK,YAAY,CAAC;QAClB,KAAK,eAAe,CAAC;QACrB,KAAK,oBAAoB,CAAC;QAC1B,KAAK,SAAS,CAAC;QACf,KAAK,YAAY,CAAC;QAClB,KAAK,uBAAuB,CAAC;QAC7B,KAAK,gBAAgB,CAAC;QACtB,KAAK,mBAAmB,CAAC;QACzB,KAAK,aAAa;YAChB,OAAO,IAAI,CAAC;QACd;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,OAA2B,EAC3B,MAA+B;IAE/B,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,QAAQ;YACX,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;YACtB,OAAO,CAAC,CAAC;QACX,KAAK,WAAW;YACd,MAAM,CAAC,OAAO,GAAG,KAAK,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,KAAK,SAAS;YACZ,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,KAAK,YAAY;YACf,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC;YACxB,OAAO,CAAC,CAAC;QACX,KAAK,eAAe;YAClB,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC;YACzB,OAAO,CAAC,CAAC;QACX,KAAK,kBAAkB;YACrB,MAAM,CAAC,UAAU,GAAG,KAAK,CAAC;YAC1B,OAAO,CAAC,CAAC;QACX,KAAK,YAAY;YACf,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC;YAC1B,OAAO,CAAC,CAAC;QACX,KAAK,eAAe;YAClB,MAAM,CAAC,WAAW,GAAG,KAAK,CAAC;YAC3B,OAAO,CAAC,CAAC;QACX,KAAK,oBAAoB;YACvB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,CAAC,eAAe,GAAG,OAAO,CAAC;gBACjC,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,CAAC,CAAC;QACX,KAAK,SAAS;YACZ,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,KAAK,YAAY;YACf,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC;YACxB,OAAO,CAAC,CAAC;QACX,KAAK,uBAAuB;YAC1B,oEAAoE;YACpE,oEAAoE;YACpE,uEAAuE;YACvE,yCAAyC;YACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,IAAI,0BAA0B,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC5C,MAAM,CAAC,kBAAkB,GAAG,OAAwD,CAAC;gBACvF,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,IAAI,CACV,mCAAmC,OAAO,oBAAoB,CAAC,GAAG,0BAA0B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CACtH,CAAC;gBACJ,CAAC;gBACD,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,CAAC,CAAC;QACX,KAAK,gBAAgB;YACnB,MAAM,CAAC,mBAAmB,GAAG,IAAI,CAAC;YAClC,OAAO,CAAC,CAAC;QACX,KAAK,mBAAmB;YACtB,MAAM,CAAC,mBAAmB,GAAG,KAAK,CAAC;YACnC,OAAO,CAAC,CAAC;QACX,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,kEAAkE;YAClE,uEAAuE;YACvE,qEAAqE;YACrE,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC,oEAAoE,CAAC,CAAC;gBACnF,OAAO,CAAC,CAAC;YACX,CAAC;YACD,0EAA0E;YAC1E,wEAAwE;YACxE,yEAAyE;YACzE,yEAAyE;YACzE,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;gBACjC,MAAM,CAAC,mBAAmB,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YACtD,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CACV,yBAAyB,OAAO,4CAA4C,CAC7E,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QACD;YACE,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAc;IAItD,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,qBAAqB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YAChE,CAAC,IAAI,QAAQ,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,mBAAmB,CAAC,QAAiC;IACnE,OAAO,CACL,QAAQ,CAAC,OAAO,KAAK,SAAS;QAC9B,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAC/B,QAAQ,CAAC,UAAU,KAAK,SAAS;QACjC,QAAQ,CAAC,WAAW,KAAK,SAAS;QAClC,QAAQ,CAAC,eAAe,KAAK,SAAS;QACtC,QAAQ,CAAC,QAAQ,KAAK,SAAS;QAC/B,QAAQ,CAAC,kBAAkB,KAAK,SAAS;QACzC,QAAQ,CAAC,mBAAmB,KAAK,SAAS;QAC1C,QAAQ,CAAC,mBAAmB,KAAK,SAAS,CAC3C,CAAC;AACJ,CAAC"}

package/dist/src/cli/evolve.d.ts

@@ -17,6 +17,10 @@
  *   --pareto-gate / --no-pareto-gate   multi-objective A/B activation gate
  *   --coverage / --no-coverage    instance-wise coverage selection
  *   --reflection-model <id>       stronger reflection model for GEPA
+ *   --demos / --no-demos          SIMBA-style demo injection (v0.10)
+ *   --candidate-selection <s>     reflection parent: active|best|pareto|epsilon-greedy
+ *   --skip-perfect / --no-skip-perfect   drop perfect-score runs from optimizer feedback (v0.11)
+ *   --max-merge <n>               lifetime cap on merge-derived challengers (v0.11)
  */
 export declare function evolveCommand(args: string[]): Promise<void>;
 //# sourceMappingURL=evolve.d.ts.map

package/dist/src/cli/evolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evolve.d.ts","sourceRoot":"","sources":["../../../src/cli/evolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAeH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkGjE"}
+{"version":3,"file":"evolve.d.ts","sourceRoot":"","sources":["../../../src/cli/evolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAeH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkGjE"}

package/dist/src/cli/evolve.js

@@ -17,6 +17,10 @@
  *   --pareto-gate / --no-pareto-gate   multi-objective A/B activation gate
  *   --coverage / --no-coverage    instance-wise coverage selection
  *   --reflection-model <id>       stronger reflection model for GEPA
+ *   --demos / --no-demos          SIMBA-style demo injection (v0.10)
+ *   --candidate-selection <s>     reflection parent: active|best|pareto|epsilon-greedy
+ *   --skip-perfect / --no-skip-perfect   drop perfect-score runs from optimizer feedback (v0.11)
+ *   --max-merge <n>               lifetime cap on merge-derived challengers (v0.11)
  */
 import { createMemory } from '../memory/index.js';
 import { loadConfig } from '../core/agent.js';
@@ -135,6 +139,14 @@ function describeOverride(o) {
         parts.push(`coverage=${o.useCoverage}`);
     if (o.reflectionModel !== undefined)
         parts.push(`reflectionModel=${o.reflectionModel}`);
+    if (o.useDemos !== undefined)
+        parts.push(`demos=${o.useDemos}`);
+    if (o.candidateSelection !== undefined)
+        parts.push(`candidateSelection=${o.candidateSelection}`);
+    if (o.skipPerfectFeedback !== undefined)
+        parts.push(`skipPerfect=${o.skipPerfectFeedback}`);
+    if (o.maxMergeInvocations !== undefined)
+        parts.push(`maxMerge=${o.maxMergeInvocations}`);
     return parts.length > 0 ? parts.join(', ') : '(none)';
 }
 /** One-line summary of the effective advanced config for the status view. */
@@ -146,9 +158,18 @@ function describeConfig(evo) {
         `merge=${evo.useMerge ?? false}`,
         `paretoGate=${evo.paretoGate ?? false}`,
         `coverage=${evo.useCoverage ?? false}`,
+        `demos=${evo.useDemos ?? false}`,
+        `skipPerfect=${evo.skipPerfectFeedback ?? false}`,
     ];
     if (evo.reflectionModel)
         parts.push(`reflectionModel=${evo.reflectionModel}`);
+    if (evo.candidateSelection && evo.candidateSelection !== 'active') {
+        parts.push(`candidateSelection=${evo.candidateSelection}`);
+    }
+    // maxMerge is genuinely optional (unset = uncapped), so it is shown only when
+    // set — unlike the always-shown booleans above.
+    if (evo.maxMergeInvocations !== undefined)
+        parts.push(`maxMerge=${evo.maxMergeInvocations}`);
     return parts.join(', ');
 }
 //# sourceMappingURL=evolve.js.map

package/dist/src/cli/evolve.js.map

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

package/dist/src/cli/index.js

@@ -59,6 +59,8 @@ const HELP = `
     --pareto-gate / --no-pareto-gate   multi-objective A/B activation gate
     --coverage / --no-coverage    instance-wise coverage selection
     --reflection-model <id>       stronger reflection model for GEPA
+    --demos / --no-demos          SIMBA-style demo injection (v0.10)
+    --candidate-selection <s>     reflection parent: active|best|pareto|epsilon-greedy
 `;
 async function main() {
     const args = process.argv.slice(2);

package/dist/src/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CZ,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC;QACH,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,KAAK;gBACR,MAAM,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,MAAM;gBACT,MAAM,WAAW,EAAE,CAAC;gBACpB,MAAM;YACR;gBACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;gBAC7C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CZ,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IAExB,IAAI,CAAC;QACH,QAAQ,OAAO,EAAE,CAAC;YAChB,KAAK,KAAK;gBACR,MAAM,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,MAAM;gBACT,MAAM,WAAW,EAAE,CAAC;gBACpB,MAAM;YACR;gBACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;gBAC7C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

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

@@ -0,0 +1,128 @@
+/**
+ * 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.
+ */
+import type { DarwinExperiment } from "../types.js";
+/** One harvested demonstration, ready for rendering. */
+export interface DemoCandidate {
+    /** The task the agent was given. */
+    task: string;
+    /** The agent's (high-scoring) output. */
+    output: string;
+    /** Critic score (1-10) that qualified this run as a demo. */
+    score: number;
+    /** Task category the run was classified under. */
+    taskType: string;
+}
+/** Options for {@link selectDemoCandidates}. */
+export interface DemoSelectionOptions {
+    /**
+     * Maximum number of demos to keep (default {@link DEFAULT_MAX_DEMOS}).
+     * SIMBA defaults to 4 per predictor; Darwin defaults lower (2) because the
+     * online loop appends demos to a single system prompt and prompt length
+     * correlates NEGATIVELY with reliability (documented v2-prompt incident).
+     */
+    maxDemos?: number;
+    /**
+     * Minimum critic score for a run to qualify (default
+     * {@link DEFAULT_DEMO_SCORE_THRESHOLD}). Mirrors the closed-loop feedback
+     * convention where ≥ 8 marks a high-quality pattern.
+     */
+    scoreThreshold?: number;
+    /**
+     * Minimum output length (chars) for a run to qualify (default
+     * {@link DEFAULT_DEMO_MIN_OUTPUT_CHARS}). Filters out degenerate/truncated
+     * outputs that scored well on a technicality.
+     */
+    minOutputChars?: number;
+}
+/** Options for {@link buildDemoSection}. */
+export interface DemoRenderOptions {
+    /** Cap on the quoted task text, chars (default {@link DEFAULT_DEMO_TASK_CHARS}). */
+    maxTaskChars?: number;
+    /**
+     * Cap on each quoted output excerpt, chars (default
+     * {@link DEFAULT_DEMO_OUTPUT_CHARS}). Truncation prefers a sentence/newline
+     * boundary, same policy as the reflector's output cleaning.
+     */
+    maxOutputChars?: number;
+}
+export declare const DEFAULT_MAX_DEMOS = 2;
+export declare const DEFAULT_DEMO_SCORE_THRESHOLD = 8;
+export declare const DEFAULT_DEMO_MIN_OUTPUT_CHARS = 200;
+export declare const DEFAULT_DEMO_TASK_CHARS = 240;
+export declare const DEFAULT_DEMO_OUTPUT_CHARS = 900;
+/** Start marker — everything between the markers is Darwin-managed. */
+export declare const DEMO_SECTION_START = "<!-- darwin:demos:start -->";
+/** End marker. */
+export declare const DEMO_SECTION_END = "<!-- darwin:demos:end -->";
+/**
+ * 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 declare function selectDemoCandidates(experiments: ReadonlyArray<DarwinExperiment>, options?: DemoSelectionOptions): DemoCandidate[];
+/**
+ * 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 declare function buildDemoSection(demos: ReadonlyArray<DemoCandidate>, options?: DemoRenderOptions): string;
+/**
+ * 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 declare function applyDemoSection(prompt: string, section: string): string;
+/**
+ * Remove the marker-delimited demo section (if any), collapsing the blank
+ * line that {@link applyDemoSection} inserted. Prompts without a section are
+ * returned unchanged.
+ */
+export declare function stripDemoSection(prompt: string): string;
+//# sourceMappingURL=demos.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"demos.d.ts","sourceRoot":"","sources":["../../../src/evolution/demos.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,gCAAgC,CAAC;AAChE,kBAAkB;AAClB,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAiB5D;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAAC,EAC5C,OAAO,GAAE,oBAAyB,GACjC,aAAa,EAAE,CAmDjB;AA2BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,EACnC,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAgBR;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGvD"}