@tangle-network/agent-eval 0.94.0 → 0.95.1

package/dist/{control-D6qwHXIR.d.ts → control-Doncu-B_.d.ts}

@@ -3,7 +3,7 @@ import { C as ControlEvalResult, a as ControlRunResult, h as ControlRuntimeConfi
 import { T as TraceEmitter } from './emitter-C2rqGH_l.js';
 import { F as FailureClass } from './schema-m0gsnbt3.js';
 import { T as TraceStore } from './store-BcFXE6LG.js';
-import { a as RunSplitTag, b as RunTokenUsage, R as RunRecord } from './run-record-e7vj1uZQ.js';
+import { a as RunSplitTag, b as RunTokenUsage, R as RunRecord } from './run-record-CP2ObebC.js';
 
 interface ActionExecutionPolicy {
     allowedTypes?: string[];
@@ -52,7 +52,7 @@ interface ControlRunToRunRecordOptions extends RunEvidenceMetadata {
  * release gates, optimizer tables, and research reports.
  *
  * The control loop owns live execution evidence. The caller still supplies the
- * experimental cell metadata because prompt/config hashes, split assignment,
+ * experiment-cell metadata because prompt/config hashes, split assignment,
  * model snapshot, and commit SHA are product/harness concerns.
  */
 declare function controlRunToRunRecord<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(run: ControlRunResult<TState, TAction, TActionResult, TEval>, options: ControlRunToRunRecordOptions): RunRecord;

package/dist/control.d.ts

@@ -1,4 +1,4 @@
-export { A as ActionExecutionPolicy, a as ActionPolicyDecision, C as ControlRunToRunRecordOptions, e as ProposeReviewConfig, f as ProposeReviewControlAction, g as ProposeReviewControlConfig, h as ProposeReviewControlResult, i as ProposeReviewControlState, j as ProposeReviewReport, p as RunEvidenceMetadata, s as controlRunToRunRecord, u as evaluateActionPolicy, x as runProposeReview, y as runProposeReviewAsControlLoop, z as scoreFromEvals } from './control-D6qwHXIR.js';
+export { A as ActionExecutionPolicy, a as ActionPolicyDecision, C as ControlRunToRunRecordOptions, e as ProposeReviewConfig, f as ProposeReviewControlAction, g as ProposeReviewControlConfig, h as ProposeReviewControlResult, i as ProposeReviewControlState, j as ProposeReviewReport, p as RunEvidenceMetadata, s as controlRunToRunRecord, u as evaluateActionPolicy, x as runProposeReview, y as runProposeReviewAsControlLoop, z as scoreFromEvals } from './control-Doncu-B_.js';
 export { c as ControlActionFailureMode, d as ControlActionOutcome, e as ControlBudget, f as ControlContext, g as ControlDecision, C as ControlEvalResult, a as ControlRunResult, h as ControlRuntimeConfig, i as ControlRuntimeError, j as ControlSeverity, b as ControlStep, k as ControlStopPolicies, S as StopDecision, l as allCriticalPassed, o as objectiveEval, r as runAgentControlLoop, s as stopOnNoProgress, m as stopOnRepeatedAction, n as subjectiveEval } from './control-runtime-Acf9CGhw.js';
 import './feedback-trajectory-BxY0cKfs.js';
 import './dataset-BbGkaN2I.js';
@@ -6,4 +6,5 @@ import './errors-CzMUYo7b.js';
 import './emitter-C2rqGH_l.js';
 import './schema-m0gsnbt3.js';
 import './store-BcFXE6LG.js';
-import './run-record-e7vj1uZQ.js';
+import './run-record-CP2ObebC.js';
+import '@tangle-network/agent-interface';

package/dist/control.js

@@ -4,7 +4,7 @@ import {
   runProposeReview,
   runProposeReviewAsControlLoop,
   scoreFromEvals
-} from "./chunk-E4GH6USR.js";
+} from "./chunk-NZEQVRH5.js";
 import {
   allCriticalPassed,
   objectiveEval,
@@ -13,7 +13,7 @@ import {
   stopOnRepeatedAction,
   subjectiveEval
 } from "./chunk-YEHAEDUD.js";
-import "./chunk-KWRRMR3J.js";
+import "./chunk-LO6IOIJ2.js";
 import "./chunk-TVVP3ZZQ.js";
 import "./chunk-VSMTAMNK.js";
 import "./chunk-3BFEG2F6.js";

package/dist/{corpus-B8A4BDR3.d.ts → corpus-D4YW9UoJ.d.ts}

@@ -1,4 +1,4 @@
-import { R as RunRecord, a as RunSplitTag } from './run-record-e7vj1uZQ.js';
+import { R as RunRecord, a as RunSplitTag } from './run-record-CP2ObebC.js';
 import { S as Span } from './schema-m0gsnbt3.js';
 import { T as TraceStore } from './store-BcFXE6LG.js';
 

package/dist/{default-registry-6dhErQbs.d.ts → default-registry-GyE8X5SP.d.ts}

@@ -1,6 +1,6 @@
 import { AxAIService } from '@ax-llm/ax';
-import { T as TraceAnalystKindSpec } from './kind-factory-0BhLSI27.js';
-import { A as Analyst, a as AnalystContext, b as AnalystRunSummary, c as AnalystFinding, d as AnalystRunResult, C as ChatClient, e as AnalystRunInputs, f as AnalystRunEvent } from './types-Ce17tDlG.js';
+import { T as TraceAnalystKindSpec } from './kind-factory-X3eDYbKn.js';
+import { A as Analyst, a as AnalystContext, b as AnalystRunSummary, c as AnalystFinding, d as AnalystRunResult, C as ChatClient, e as AnalystRunInputs, f as AnalystRunEvent } from './types-B5x54y6n.js';
 
 /**
  * AnalystRegistry — orchestrate N analysts against one run.
@@ -152,4 +152,4 @@ interface DefaultAnalystRegistryOptions {
 }
 declare function buildDefaultAnalystRegistry(opts?: DefaultAnalystRegistryOptions): AnalystRegistry;
 
-export { AnalystRegistry as A, type BudgetPolicy as B, type DefaultAnalystRegistryOptions as D, type RegistryRunOpts as R, type AnalystHooks as a, buildDefaultAnalystRegistry as b, type AnalystRegistryOptions as c };
+export { AnalystRegistry as A, type BudgetPolicy as B, type DefaultAnalystRegistryOptions as D, type RegistryRunOpts as R, type AnalystHooks as a, type AnalystRegistryOptions as b, buildDefaultAnalystRegistry as c };

package/dist/diagnose.d.ts

@@ -3,9 +3,9 @@ export { c as CounterfactualContext, d as CounterfactualResult } from './counter
 import { S as Span } from './schema-m0gsnbt3.js';
 import { T as TraceStore } from './store-BcFXE6LG.js';
 import { a as TrajectoryStep, T as Trajectory } from './trajectory-2TkpSEVh.js';
-import { h as AnalystSeverity, c as AnalystFinding } from './types-Ce17tDlG.js';
-import { C as CorpusRecord } from './corpus-B8A4BDR3.js';
-import { R as RunRecord } from './run-record-e7vj1uZQ.js';
+import { h as AnalystSeverity, c as AnalystFinding } from './types-B5x54y6n.js';
+import { C as CorpusRecord } from './corpus-D4YW9UoJ.js';
+import { R as RunRecord } from './run-record-CP2ObebC.js';
 import './emitter-C2rqGH_l.js';
 import './store-C1YxJDEK.js';
 import './types-C7DGg5ex.js';
@@ -13,6 +13,7 @@ import '@tangle-network/tcloud';
 import './llm-client-Bj7g0rqu.js';
 import './errors-CzMUYo7b.js';
 import './raw-provider-sink-C46HDghv.js';
+import '@tangle-network/agent-interface';
 
 /**
  * Causal sweep — WHY did this run fail?

package/dist/diagnose.js

@@ -13,7 +13,7 @@ import {
 } from "./chunk-56GC6VYO.js";
 import {
   validateRunRecord
-} from "./chunk-KWRRMR3J.js";
+} from "./chunk-LO6IOIJ2.js";
 import "./chunk-TVVP3ZZQ.js";
 import "./chunk-VSMTAMNK.js";
 import {

package/dist/{run-improvement-loop-DBahB8Ax.d.ts → gepa-C1NCIZ9o.d.ts}

@@ -1,96 +1,7 @@
+import { S as Scenario, C as CampaignResult, l as GateResult, D as DispatchFn, a as JudgeConfig, L as LabeledScenarioStore, i as CampaignTraceWriter, n as GenerationRecord, M as MutableSurface, P as ParetoParent, c as SurfaceProposer, G as Gate } from './types-DQRY8ZT-.js';
 import { L as LlmClientOptions } from './llm-client-Bj7g0rqu.js';
-import { I as ImprovementDriver, S as Scenario, g as CampaignResult, k as GateResult, D as DispatchFn, a as JudgeConfig, L as LabeledScenarioStore, h as CampaignTraceWriter, m as GenerationRecord, M as MutableSurface, P as ParetoParent, G as Gate } from './types-BU-7W85F.js';
 
 /**
- * @experimental
- *
- * `gepaDriver` — a reflective `ImprovementDriver` for prompt-tier surfaces.
- * Each generation it reflects on the prior best candidate's per-scenario
- * scores + weakest dimensions, asks an LLM to propose targeted rewrites of
- * the current surface, and returns them as the next population.
- *
- * Maps onto the GEPA paper (Agrawal et al., arXiv:2507.19457):
- *   - *Reflection*: each generation reflects on the best parent's weakest
- *     dimensions + per-scenario top/bottom scores to propose targeted rewrites.
- *   - *Pareto frontier*: `runOptimization` maintains the non-dominated set of
- *     surfaces across generations (per-scenario objective vectors) and supplies
- *     it as `ctx.paretoParents`. A surface uniquely best on one hard scenario
- *     survives even when its mean composite is lower.
- *   - *Combine complementary lessons*: when the frontier has >1 member, the
- *     first population slot is a merge of those parents' strengths (one LLM
- *     call citing each parent's winning scenarios). Toggle via `combineParents`.
- * Dominance is computed by the package-canonical `paretoFrontier` (`pareto.ts`).
- *
- * Optional `constraints` move structured-doc guards into the driver
- * (preserve H2 section headings, cap sentence-level edits) — useful when
- * the surface IS a structured procedure like a SKILL.md / runbook /
- * judge rubric. When `constraints` is omitted, behavior is unchanged.
- *
- * The driver is surface-agnostic — any string surface in any consumer opts
- * in by selecting it. Reuses the generic reflection primitive
- * (`buildReflectionPrompt` / `parseReflectionResponse`) and the router client.
- *
- * Earns its keep where there is real per-instance signal (which the
- * dimensional + per-scenario evidence + the `LabeledScenarioStore` flywheel
- * now provide). For thin-signal surfaces it degrades to plain reflection.
- * On generation 0 (no history) it reflects on the current surface against
- * the mutation primitives alone.
- */
-
-interface GepaDriverConstraints {
-    /** H2 section headings that MUST appear unchanged in every candidate.
-     *  When set, the driver auto-detects current H2s if this is empty AND
-     *  rejects any candidate that drops or renames a preserved heading.
-     *  Use when the surface is a structured doc (SKILL.md, runbook,
-     *  sectioned system prompt, judge rubric). */
-    preserveSections?: string[];
-    /** Maximum sentence-level edits per candidate vs the parent surface.
-     *  Rejection threshold = maxSentenceEdits × 2 (counts adds + removes).
-     *  Inspired by SkillOpt's edit-budget as a "textual learning rate."
-     *  Cap prevents an LLM rewrite from overwriting useful prior rules. */
-    maxSentenceEdits?: number;
-}
-interface GepaDriverOptions {
-    /** Router transport (apiKey/baseUrl). */
-    llm: LlmClientOptions;
-    /** Model that performs the reflection. */
-    model: string;
-    /** What is being optimized — appears in the reflection prompt for orientation. */
-    target: string;
-    /** Surface-specific mutation levers offered to the model. */
-    mutationPrimitives?: string[];
-    /** Top/bottom scenarios surfaced as evidence each generation. Default 3. */
-    evidenceK?: number;
-    /** Reflection sampling temperature. Default 0.7. */
-    temperature?: number;
-    /** Reflection max tokens. Default 6000. */
-    maxTokens?: number;
-    /** Structured-doc constraints. Candidates violating any are rejected
-     *  post-parse and dropped from the returned population. */
-    constraints?: GepaDriverConstraints;
-    /** GEPA combine-complementary-lessons: when the loop supplies a Pareto
-     *  frontier of >1 non-dominated parents (`ctx.paretoParents`), spend one
-     *  slot of the population on a merge of their strengths. Default `true` —
-     *  this is the GEPA-faithful behavior; the merge only fires once the
-     *  frontier has more than one member (generation ≥ 1). Set `false` for
-     *  pure single-parent reflection. */
-    combineParents?: boolean;
-    /** Cap on how many frontier parents feed one combine prompt (highest
-     *  composite first), to bound prompt size. Default 4. */
-    combineMaxParents?: number;
-}
-declare function gepaDriver(opts: GepaDriverOptions): ImprovementDriver;
-/** Extract H2 headings (`## Foo`) from a markdown surface. Exported for
- *  consumers building custom mutators that share the same invariant. */
-declare function extractH2Sections(text: string): string[];
-/** Sentence-level edit distance — count distinct add/remove ops between
- *  two surfaces via a normalised line-by-line set diff. Treats trivial
- *  whitespace as identical. Exported for tests + consumer-side validators. */
-declare function countSentenceEdits(baseline: string, candidate: string): number;
-
-/**
- * @experimental
- *
  * `openAutoPr` — thin shell-out helper for the `runImprovementLoop` preset's
  * `autoOnPromote: 'pr'` mode. Substitutes for the per-product PR-opening
  * code consumers duplicated 4 times. The PR body includes the campaign's
@@ -137,8 +48,6 @@ interface OpenAutoPrResult {
 declare function openAutoPr<TArtifact, TScenario extends Scenario>(options: OpenAutoPrOptions<TArtifact, TScenario>): OpenAutoPrResult;
 
 /**
- * @experimental
- *
  * `CampaignStorage` — the filesystem seam `runCampaign` writes through
  * (run/cell dirs, the resumability cache, per-cell artifacts, trace spans).
  *
@@ -177,8 +86,6 @@ declare function fsCampaignStorage(): CampaignStorage;
 declare function inMemoryCampaignStorage(): CampaignStorage;
 
 /**
- * @experimental
- *
  * `runCampaign` — Pass A substrate primitive. ONE function that orchestrates
  * scenarios → dispatch → artifacts → judges → aggregates, with full
  * reproducibility (seed + manifest hash), cell-level resumability, bootstrap
@@ -268,51 +175,47 @@ interface RunCampaignOptions<TScenario extends Scenario, TArtifact> {
 declare function runCampaign<TScenario extends Scenario, TArtifact>(opts: RunCampaignOptions<TScenario, TArtifact>): Promise<CampaignResult<TArtifact, TScenario>>;
 
 /**
- * @experimental
- *
  * `runOptimization` — the improvement loop body. Runs N generations: the
- * `ImprovementDriver` proposes K candidate surfaces per generation, each
+ * `SurfaceProposer` proposes K candidate surfaces per generation, each
  * candidate runs a campaign (the measurement), top-scoring promote to the
- * next generation. Driver-agnostic — the same loop runs an evolutionary
- * population mutator (`evolutionaryDriver`) or agent-runtime's
- * `improvementDriver` (reflective / agentic generators); they differ only in
- * how `propose()` picks candidates.
+ * next generation. Proposer-agnostic — the same loop runs an evolutionary
+ * population mutator (`evolutionaryProposer`) or any reflective / agentic
+ * proposer; they differ only in how `propose()` picks candidates.
  *
  * This is `runLoop`'s shape (plan → measure → decide) specialized to surface
- * improvement: `driver.propose` = plan, `runCampaign` = the measurement (which
- * runs the worker behind `dispatch`), the mean-composite ranking = the
- * validator, `driver.decide` = the stop check.
+ * improvement: `proposer.propose` = plan, `runCampaign` = the measurement
+ * (which runs the worker behind `dispatch`), the mean-composite ranking = the
+ * validator, `proposer.decide` = the stop check.
  *
  * The gated-promotion shell (`runImprovementLoop`) wraps this with a holdout
  * re-score + release gate + optional PR.
  */
 
-interface RunOptimizationOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'dispatch'> {
+interface RunOptimizationBaseOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'dispatch'> {
     /** Initial mutable surface (typically system prompt or addendum). */
     baselineSurface: MutableSurface;
     /** Dispatcher that takes the CURRENT surface + scenario → artifact. */
     dispatchWithSurface: (surface: MutableSurface, scenario: TScenario, ctx: Parameters<RunCampaignOptions<TScenario, TArtifact>['dispatch']>[1]) => Promise<TArtifact>;
-    /** The improvement strategy. Wrap a population `Mutator` via
-     *  `evolutionaryDriver({ mutator })`, or pass agent-runtime's
-     *  `improvementDriver` (reflective / agentic generators). */
-    driver: ImprovementDriver;
+    /** The candidate-generation strategy. Wrap a population `Mutator` via
+     *  `evolutionaryProposer({ mutator })`, or pass any reflective / agentic
+     *  proposer that implements `SurfaceProposer`. */
+    proposer: SurfaceProposer;
     populationSize: number;
     maxGenerations: number;
     /** How many top-scoring candidates carry to the next generation. Default 2. */
     promoteTopK?: number;
-    /** DEPTH knob forwarded to the driver's `propose()` — max iterations the
+    /** DEPTH knob forwarded to the proposer's `propose()` — max iterations the
      *  agentic generator may take per candidate. */
     maxImprovementShots?: number;
-    /** Phase-2 research report forwarded to `propose()` (analyst findings +
-     *  diff). Opaque here; the driver types it. */
+    /** Optional analysis report forwarded to `propose()`. Opaque here; the
+     *  proposer types it. */
     report?: unknown;
     /** Structured findings forwarded to `propose()` as `ctx.findings`. A
-     *  findings producer (trace-analyst registry, HALO) emits these from the
-     *  generation's traces; findings-grounded drivers (`improvementDriver`,
-     *  `memoryCurationDriver`, `traceAnalystDriver`) consume them. Opaque here;
-     *  the driver types its `TFindings`. Empty when no producer is wired. */
+     *  findings producer emits these from the
+     *  generation's traces; findings-grounded proposers consume them. Opaque here;
+     *  the proposer types its `TFindings`. Empty when no producer is wired. */
     findings?: unknown[];
-    /** Per-generation findings producer — the EYES→HANDS loop closure. After each
+    /** Per-generation findings producer. After each
      *  generation's candidates are scored, this is called with that generation's
      *  results; whatever it returns REPLACES `ctx.findings` for the NEXT
      *  generation's `propose()`, so the diagnosis is refreshed each round instead
@@ -331,6 +234,7 @@ interface RunOptimizationOptions<TScenario extends Scenario, TArtifact> extends
         history: GenerationRecord[];
     }) => Promise<unknown[]>;
 }
+type RunOptimizationOptions<TScenario extends Scenario, TArtifact> = RunOptimizationBaseOptions<TScenario, TArtifact>;
 interface RunOptimizationResult<TArtifact, TScenario extends Scenario> {
     generations: Array<{
         record: GenerationRecord;
@@ -342,11 +246,11 @@ interface RunOptimizationResult<TArtifact, TScenario extends Scenario> {
     }>;
     winnerSurface: MutableSurface;
     winnerSurfaceHash: string;
-    /** Driver label for the promoted surface. Present when the winning
-     *  candidate came from a `ProposedCandidate` (a reflective driver);
+    /** Proposer label for the promoted surface. Present when the winning
+     *  candidate came from a `ProposedCandidate` (a reflective proposer);
      *  absent when the winner is the baseline or a bare-surface mutator. */
     winnerLabel?: string;
-    /** Driver rationale for the promoted surface — the "because Z" that
+    /** Proposer rationale for the promoted surface — the "because Z" that
      *  motivated the winning change. Survives to `SelfImproveResult` and the
      *  emitted provenance record. Absent when the winner is the baseline. */
     winnerRationale?: string;
@@ -362,15 +266,13 @@ declare function runOptimization<TScenario extends Scenario, TArtifact>(opts: Ru
 declare function surfaceHash(surface: MutableSurface): string;
 
 /**
- * @experimental
- *
  * `runImprovementLoop` — the gated-promotion shell around the improvement
- * loop body (`runOptimization`). Drives candidate surfaces via the
- * `ImprovementDriver`, re-scores the winner against the baseline on a
+ * loop body (`runOptimization`). Proposes candidate surfaces via the
+ * `SurfaceProposer`, re-scores the winner against the baseline on a
  * holdout set, runs the release gate, and optionally opens a PR.
  *
  * Role vocabulary (see docs/design/loop-taxonomy.md):
- *   - DRIVER     = the `ImprovementDriver` (evolutionary GEPA mutator OR
+ *   - PROPOSER   = the `SurfaceProposer` (evolutionary GEPA mutator OR
  *                  reflective analyst). Proposes candidate SURFACES — the
  *                  worker's system prompt / tool config — NOT conversation
  *                  turns.
@@ -380,16 +282,16 @@ declare function surfaceHash(surface: MutableSurface): string;
  *                  topology-opaque `dispatch` seam — never referenced here.
  *
  * Distinct from `runLoop` in `@tangle-network/agent-runtime`, which is the
- * INNER conversation loop (driver↔workers in a sandbox). `runImprovementLoop`
+ * INNER conversation loop (execution driver ↔ workers in a sandbox). `runImprovementLoop`
  * is the OUTER loop: it improves the surface that those workers run.
  *
  * Hard-refuses unsafe configurations:
- *   - `tracing: 'off'` when a driver is wired (improvement is unattributable)
+ *   - `tracing: 'off'` when a proposer is wired (improvement is unattributable)
  *   - `autoOnPromote: 'config'` — DEFERRED to Pass B; v0.40 only ships
  *     `'pr'` and `'none'`.
  */
 
-interface RunImprovementLoopOptions<TScenario extends Scenario, TArtifact> extends RunOptimizationOptions<TScenario, TArtifact> {
+type RunImprovementLoopOptions<TScenario extends Scenario, TArtifact> = RunOptimizationOptions<TScenario, TArtifact> & {
     /** Holdout scenarios kept OUT of the training optimization pool — used
      *  ONLY to score baseline vs winner for the gate. */
     holdoutScenarios: TScenario[];
@@ -409,7 +311,7 @@ interface RunImprovementLoopOptions<TScenario extends Scenario, TArtifact> exten
     /** Optional render override — substrate writes a diff-shaped surface; pass
      *  a function to format the promoted surface differently. */
     renderPromotedDiff?: (winnerSurface: MutableSurface, baselineSurface: MutableSurface) => string;
-}
+};
 interface RunImprovementLoopResult<TArtifact, TScenario extends Scenario> extends RunOptimizationResult<TArtifact, TScenario> {
     baselineOnHoldout: CampaignResult<TArtifact, TScenario>;
     winnerOnHoldout: CampaignResult<TArtifact, TScenario>;
@@ -424,4 +326,89 @@ interface RunImprovementLoopResult<TArtifact, TScenario extends Scenario> extend
 declare function runImprovementLoop<TScenario extends Scenario, TArtifact>(opts: RunImprovementLoopOptions<TScenario, TArtifact>): Promise<RunImprovementLoopResult<TArtifact, TScenario>>;
 declare function defaultRenderDiff(winnerSurface: MutableSurface, baselineSurface: MutableSurface): string;
 
-export { type CampaignStorage as C, type GepaDriverOptions as G, type OpenAutoPrOptions as O, type RunOptimizationOptions as R, type RunImprovementLoopResult as a, type RunCampaignOptions as b, type RunImprovementLoopOptions as c, runImprovementLoop as d, type GepaDriverConstraints as e, fsCampaignStorage as f, gepaDriver as g, type OpenAutoPrResult as h, inMemoryCampaignStorage as i, type RunOptimizationResult as j, countSentenceEdits as k, defaultRenderDiff as l, extractH2Sections as m, runOptimization as n, openAutoPr as o, runCampaign as r, surfaceHash as s };
+/**
+ * `gepaProposer` — a reflective `SurfaceProposer` for prompt-tier surfaces.
+ * Each generation it reflects on the prior best candidate's per-scenario
+ * scores + weakest dimensions, asks an LLM to propose targeted rewrites of
+ * the current surface, and returns them as the next population.
+ *
+ * Maps onto the GEPA paper (Agrawal et al., arXiv:2507.19457):
+ *   - *Reflection*: each generation reflects on the best parent's weakest
+ *     dimensions + per-scenario top/bottom scores to propose targeted rewrites.
+ *   - *Pareto frontier*: `runOptimization` maintains the non-dominated set of
+ *     surfaces across generations (per-scenario objective vectors) and supplies
+ *     it as `ctx.paretoParents`. A surface uniquely best on one hard scenario
+ *     survives even when its mean composite is lower.
+ *   - *Combine complementary lessons*: when the frontier has >1 member, the
+ *     first population slot is a merge of those parents' strengths (one LLM
+ *     call citing each parent's winning scenarios). Toggle via `combineParents`.
+ * Dominance is computed by the package-canonical `paretoFrontier` (`pareto.ts`).
+ *
+ * Optional `constraints` move structured-doc guards into the proposer
+ * (preserve H2 section headings, cap sentence-level edits) — useful when
+ * the surface IS a structured procedure like a SKILL.md / runbook /
+ * judge rubric. When `constraints` is omitted, behavior is unchanged.
+ *
+ * The proposer is surface-agnostic — any string surface in any consumer opts
+ * in by selecting it. Reuses the generic reflection primitive
+ * (`buildReflectionPrompt` / `parseReflectionResponse`) and the router client.
+ *
+ * Earns its keep where there is real per-instance signal (which the
+ * dimensional + per-scenario evidence + the `LabeledScenarioStore` flywheel
+ * now provide). For thin-signal surfaces it degrades to plain reflection.
+ * On generation 0 (no history) it reflects on the current surface against
+ * the mutation primitives alone.
+ */
+
+interface GepaProposerConstraints {
+    /** H2 section headings that MUST appear unchanged in every candidate.
+     *  When set, the proposer auto-detects current H2s if this is empty AND
+     *  rejects any candidate that drops or renames a preserved heading.
+     *  Use when the surface is a structured doc (SKILL.md, runbook,
+     *  sectioned system prompt, judge rubric). */
+    preserveSections?: string[];
+    /** Maximum sentence-level edits per candidate vs the parent surface.
+     *  Rejection threshold = maxSentenceEdits × 2 (counts adds + removes).
+     *  Inspired by SkillOpt's edit-budget as a "textual learning rate."
+     *  Cap prevents an LLM rewrite from overwriting useful prior rules. */
+    maxSentenceEdits?: number;
+}
+interface GepaProposerOptions {
+    /** Router transport (apiKey/baseUrl). */
+    llm: LlmClientOptions;
+    /** Model that performs the reflection. */
+    model: string;
+    /** What is being optimized — appears in the reflection prompt for orientation. */
+    target: string;
+    /** Surface-specific mutation levers offered to the model. */
+    mutationPrimitives?: string[];
+    /** Top/bottom scenarios surfaced as evidence each generation. Default 3. */
+    evidenceK?: number;
+    /** Reflection sampling temperature. Default 0.7. */
+    temperature?: number;
+    /** Reflection max tokens. Default 6000. */
+    maxTokens?: number;
+    /** Structured-doc constraints. Candidates violating any are rejected
+     *  post-parse and dropped from the returned population. */
+    constraints?: GepaProposerConstraints;
+    /** GEPA combine-complementary-lessons: when the loop supplies a Pareto
+     *  frontier of >1 non-dominated parents (`ctx.paretoParents`), spend one
+     *  slot of the population on a merge of their strengths. Default `true` —
+     *  this is the GEPA-faithful behavior; the merge only fires once the
+     *  frontier has more than one member (generation ≥ 1). Set `false` for
+     *  pure single-parent reflection. */
+    combineParents?: boolean;
+    /** Cap on how many frontier parents feed one combine prompt (highest
+     *  composite first), to bound prompt size. Default 4. */
+    combineMaxParents?: number;
+}
+declare function gepaProposer(opts: GepaProposerOptions): SurfaceProposer;
+/** Extract H2 headings (`## Foo`) from a markdown surface. Exported for
+ *  consumers building custom mutators that share the same invariant. */
+declare function extractH2Sections(text: string): string[];
+/** Sentence-level edit distance — count distinct add/remove ops between
+ *  two surfaces via a normalised line-by-line set diff. Treats trivial
+ *  whitespace as identical. Exported for tests + consumer-side validators. */
+declare function countSentenceEdits(baseline: string, candidate: string): number;
+
+export { type CampaignStorage as C, type GepaProposerOptions as G, type OpenAutoPrOptions as O, type RunOptimizationOptions as R, type RunImprovementLoopResult as a, type RunCampaignOptions as b, type RunImprovementLoopOptions as c, runImprovementLoop as d, type GepaProposerConstraints as e, fsCampaignStorage as f, gepaProposer as g, type OpenAutoPrResult as h, inMemoryCampaignStorage as i, type RunOptimizationResult as j, countSentenceEdits as k, defaultRenderDiff as l, extractH2Sections as m, runOptimization as n, openAutoPr as o, runCampaign as r, surfaceHash as s };

package/dist/hosted/index.d.ts

@@ -1,9 +1,10 @@
-import { M as MutableSurface, c as GateDecision } from '../types-BU-7W85F.js';
-import { I as InsightReport } from '../insight-report-DWl3z9tl.js';
-import '../run-record-e7vj1uZQ.js';
+import { M as MutableSurface, d as GateDecision } from '../types-DQRY8ZT-.js';
+import { I as InsightReport } from '../insight-report-BnRjTibG.js';
+import '../run-record-CP2ObebC.js';
+import '@tangle-network/agent-interface';
 import '../errors-CzMUYo7b.js';
 import '../schema-m0gsnbt3.js';
-import '../summary-report-BDOFevaT.js';
+import '../summary-report-CInXwsza.js';
 import '../failure-cluster-DH9Flgcf.js';
 import '../store-BcFXE6LG.js';
 import '../judge-calibration-0p2QcWNE.js';

package/dist/{index-Bx3gZ8xl.d.ts → index-_Y4oNOOb.d.ts}

@@ -1,4 +1,4 @@
-import { a as RunSplitTag } from './run-record-e7vj1uZQ.js';
+import { a as RunSplitTag } from './run-record-CP2ObebC.js';
 
 /**
  * Shared types for the reference benchmark wrappers under