@tangle-network/agent-eval 0.94.0 → 0.95.0

package/dist/campaign/presets/run-profile-matrix.d.ts

@@ -0,0 +1,151 @@
+/**
+ * `runProfileMatrix` — the missing keystone between `runAgentMatrix` and the
+ * backend-integrity guard.
+ *
+ * The gap it closes: `runAgentMatrix` is a topology-opaque scheduler whose
+ * cells return a bare `{ output, verdict, costUsd }` — no `tokenUsage`, not a
+ * `RunRecord`. `assertRealBackend` / `summarizeBackendIntegrity` key on
+ * `RunRecord.tokenUsage`, so they cannot run on a raw matrix result. Every
+ * consumer therefore hand-writes the same bridge: fan a profile × scenario
+ * cartesian, call dispatch, fabricate a `RunRecord` with token usage, thread it
+ * back, run the integrity guard. That hand-rolled bridge is exactly the pile of
+ * bespoke `eval:*` scripts the adoption skills keep trying (and failing) to
+ * forbid.
+ *
+ * `runProfileMatrix` IS that bridge, once:
+ *
+ *   - axis 3 (PROFILE) = `profiles: AgentProfile[]`
+ *   - axis 1 (PERSONA/SCENARIO) = `scenarios: Scenario[]` (each scenario carries
+ *     its persona; `personaOf` groups them for the `byPersona` pivot)
+ *   - the scoring axis = `judges`
+ *
+ * It runs `runCampaign` once per profile (reusing its seeds, reps, bootstrap
+ * CIs, resumability, and the `LabeledScenarioStore` capture flywheel), maps
+ * every cell to a validated `RunRecord` carrying the real `tokenUsage` the
+ * dispatch reported via `ctx.cost.observeTokens`, and runs `assertRealBackend`
+ * BY CONSTRUCTION before returning — so a stub-backend run fails loudly instead
+ * of reporting a clean 0/N leaderboard.
+ *
+ * Dispatch contract: a dispatch that calls an LLM MUST report usage via
+ * `ctx.cost.observeTokens({ input, output })` (and cost via `ctx.cost.observe`).
+ * A dispatch that reports zero tokens is indistinguishable from a stub and the
+ * integrity guard treats it as one.
+ */
+import { type AgentProfile } from '../../agent-profile';
+import { AgentEvalError } from '../../errors';
+import { type BackendIntegrityReport } from '../../integrity/backend-integrity';
+import { type RunRecord, type RunSplitTag } from '../../run-record';
+import type { CampaignStorage } from '../storage';
+import type { CampaignResult, DispatchContext, JudgeConfig, LabeledScenarioSource, LabeledScenarioStore, Scenario } from '../types';
+/** Thrown when the matrix is misconfigured (no profiles, a profile whose model
+ *  lacks a snapshot version, etc.). Distinct from `BackendIntegrityError`,
+ *  which signals a stub backend at run time. */
+export declare class ProfileMatrixError extends AgentEvalError {
+    constructor(message: string);
+}
+/** Dispatch for one cell: render `profile` against `scenario`, returning the
+ *  artifact the judges score. Report LLM usage via `ctx.cost.observeTokens`
+ *  and `ctx.cost.observe` — the integrity guard depends on it. */
+export type ProfileDispatchFn<TScenario extends Scenario, TArtifact> = (profile: AgentProfile, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+export interface RunProfileMatrixOptions<TScenario extends Scenario, TArtifact> {
+    /** Axis 3 — the agent-under-test configurations. Each is one column. */
+    profiles: AgentProfile[];
+    /** Axis 1 — the persona/scenario corpus, run against every profile. */
+    scenarios: TScenario[];
+    /** Renders one (profile, scenario) cell. */
+    dispatch: ProfileDispatchFn<TScenario, TArtifact>;
+    /** The scoring axis. */
+    judges?: JudgeConfig<TArtifact, TScenario>[];
+    /** Where each profile's campaign writes artifacts/traces. One subdir per
+     *  profile. */
+    runDir: string;
+    /** Git SHA the harness ran from — stamped onto every RunRecord (mandatory
+     *  for paper-grade records). */
+    commitSha: string;
+    /** Logical experiment id shared across the whole matrix so the promotion
+     *  gate can pair profiles on matched scenarios. Default: a hash of the
+     *  profile + scenario ids. */
+    experimentId?: string;
+    /** Which split these runs belong to. Default `'search'`. */
+    splitTag?: RunSplitTag;
+    /** Replicates per (profile, scenario) cell for CI bands. Default 1. */
+    reps?: number;
+    /** Campaign seed (per profile). Default 42. */
+    seed?: number;
+    /**
+     * Backend-integrity posture, enforced AFTER the matrix completes:
+     *   - `'assert'` (default) — throw `BackendIntegrityError` if the run was a
+     *     stub (and, with `allowMixed:false`, if it was mixed).
+     *   - `'warn'` — log the verdict but never throw.
+     *   - `'off'` — skip the guard entirely (only for offline/replay analysis).
+     */
+    integrity?: 'assert' | 'warn' | 'off';
+    /** Forwarded to `assertRealBackend`. Default true (tolerate partial 429
+     *  cascades); set false for strict CI gates. */
+    allowMixed?: boolean;
+    /** Max concurrent cells WITHIN each profile's campaign. Default 2.
+     *  Profiles run sequentially so the cost ceiling is honored deterministically. */
+    maxConcurrency?: number;
+    /** Cumulative USD cap per profile campaign. */
+    costCeiling?: number;
+    /** Capture flywheel — forwarded to each campaign. */
+    labeledStore?: LabeledScenarioStore | 'off';
+    captureSource?: LabeledScenarioSource;
+    /** Storage backend. Default `fsCampaignStorage`. Pass
+     *  `inMemoryCampaignStorage()` for edge/CF-Worker/test runs. */
+    storage?: CampaignStorage;
+    /** Test seam — override the wall clock. */
+    now?: () => Date;
+    /** Optional persona key per scenario — drives the `byPersona` pivot. When
+     *  unset, `byPersona` is omitted. */
+    personaOf?: (scenario: TScenario) => string;
+    /** Validate every produced RunRecord with `validateRunRecord` (fail-loud).
+     *  Default true — catches bad model snapshots and non-finite judge dims at
+     *  the boundary instead of letting them poison downstream analysis. */
+    validate?: boolean;
+    /** Corpus-by-default: derive the trajectory text (`prompt` + `completion`)
+     *  for each cell from its artifact + scenario. When set, every produced
+     *  record carries `prompt`/`completion` (a `CorpusRecord`) so the run's
+     *  graded trajectories can be appended to the durable RL corpus with no
+     *  side-channel — `appendToCorpus(result.records, path)`. Fail-soft: a
+     *  throwing or undefined-returning extractor just omits the text. */
+    corpusText?: (artifact: TArtifact, scenario: TScenario) => {
+        prompt: string;
+        completion: string;
+    } | undefined;
+}
+export interface ProfileSummary {
+    profileId: string;
+    profileHash: string;
+    model: string;
+    /** RunRecords produced for this profile (= scenarios × reps). */
+    records: number;
+    /** Mean composite across this profile's records. */
+    meanComposite: number;
+    totalCostUsd: number;
+    /** Per-profile integrity verdict — surfaces a single profile that ran stub
+     *  even when the matrix as a whole looks real. */
+    integrity: BackendIntegrityReport;
+}
+export interface ScenarioRollup {
+    meanComposite: number;
+    n: number;
+}
+export interface RunProfileMatrixResult<TArtifact, TScenario extends Scenario> {
+    matrixId: string;
+    experimentId: string;
+    /** One RunRecord per (profile, scenario, rep) cell — the integrity-checked,
+     *  paper-grade output. Feed straight into `analyzeRuns`, `HeldOutGate`,
+     *  scorecards, the hosted wire format. */
+    records: RunRecord[];
+    byProfile: Record<string, ProfileSummary>;
+    byScenario: Record<string, ScenarioRollup>;
+    /** Present only when `personaOf` was supplied. */
+    byPersona?: Record<string, ScenarioRollup>;
+    /** Whole-matrix integrity report (the one `integrity:'assert'` enforces). */
+    integrity: BackendIntegrityReport;
+    /** The raw per-profile campaign results, keyed by profile id. */
+    campaigns: Record<string, CampaignResult<TArtifact, TScenario>>;
+}
+export declare function runProfileMatrix<TScenario extends Scenario, TArtifact>(opts: RunProfileMatrixOptions<TScenario, TArtifact>): Promise<RunProfileMatrixResult<TArtifact, TScenario>>;
+//# sourceMappingURL=run-profile-matrix.d.ts.map

package/dist/campaign/presets/run-profile-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-profile-matrix.d.ts","sourceRoot":"","sources":["../../../src/campaign/presets/run-profile-matrix.ts"],"names":[],"mappings":"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"}

package/dist/campaign/presets/run-skill-opt.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `runSkillOpt` — the SkillOpt epoch hill-climb (Microsoft, arXiv:2605.23904).
+ * Unlike `runOptimization`'s population/promote-top-K search, SkillOpt is a
+ * sequential, held-out-gated hill-climb on ONE skill document:
+ *
+ *   each epoch:
+ *     1. reflect on the CURRENT surface's weakest TRAIN scenarios/dimensions
+ *        (never the held-out split — proposals must not see the acceptance axis)
+ *     2. propose ≤ `patchesPerEpoch` bounded patches (≤ `editBudget` ops each)
+ *     3. apply each; score the candidate on the HELD-OUT split
+ *     4. ACCEPT the first patch that STRICTLY improves the held-out composite;
+ *        otherwise push it to the rejected-edit buffer (fed back so the model
+ *        does not re-propose dead ends)
+ *     5. anneal the edit budget down after consecutive rejections (the
+ *        "textual learning rate" decay); refresh the slow-update meta note
+ *     6. stop at `maxEpochs` or after `patience` epochs with no acceptance
+ *
+ * The accept-only-if-held-out-improves rule is the same discipline as
+ * `HeldOutGate`/`defaultProductionGate`, applied per edit instead of once at
+ * the end — which is why the held-out composite is monotonically
+ * non-decreasing and a regression can never ship. `runCampaign` is the
+ * measurement; `applySkillPatch` applies the edits; `skillOptProposer` proposes
+ * them.
+ */
+import type { RejectedEdit, SkillOptProposer } from '../proposers/skill-opt';
+import { type RunCampaignOptions } from '../run-campaign';
+import type { DispatchContext, Scenario } from '../types';
+export interface RunSkillOptOptions<TScenario extends Scenario, TArtifact> extends Omit<RunCampaignOptions<TScenario, TArtifact>, 'dispatch' | 'scenarios'> {
+    /** The skill document being optimized. */
+    baselineSurface: string;
+    /** Dispatcher taking the CURRENT skill surface + scenario → artifact. */
+    dispatchWithSurface: (surface: string, scenario: TScenario, ctx: DispatchContext) => Promise<TArtifact>;
+    proposer: SkillOptProposer;
+    /** Scenarios the optimizer reflects on for evidence. MUST be disjoint from
+     *  `holdoutScenarios` — proposals never see the acceptance axis. */
+    trainScenarios: TScenario[];
+    /** Held-out scenarios. An edit is accepted ONLY if it strictly improves the
+     *  mean composite here. */
+    holdoutScenarios: TScenario[];
+    maxEpochs: number;
+    /** Candidate patches proposed per epoch. Default 2. */
+    patchesPerEpoch?: number;
+    /** Initial ops-per-patch cap (the textual learning rate). Default 3. */
+    editBudget?: number;
+    /** Strict acceptance margin: accept iff the held-out composite improves by
+     *  MORE than this. Default 0 (any strict improvement). */
+    minImprovement?: number;
+    /** Stop after this many consecutive epochs with no acceptance. Default =
+     *  `maxEpochs` (never early-stop). */
+    patience?: number;
+    /** Shrink the edit budget by 1 after 2 consecutive rejected epochs (min 1).
+     *  Default true. */
+    budgetAnneal?: boolean;
+    /** Cap on the rejected-edit buffer (most-recent kept). Default 12. */
+    rejectedBufferSize?: number;
+    /** Refresh the slow-update meta note every N epochs. Default 2. 0 disables. */
+    slowMetaEvery?: number;
+    /** Top-K weak scenarios/dimensions surfaced as evidence each epoch. Default 3. */
+    evidenceK?: number;
+    /** Abort signal forwarded to the patch-proposing LLM calls. */
+    signal?: AbortSignal;
+}
+export interface AcceptedEdit {
+    epoch: number;
+    label: string;
+    rationale: string;
+    /** Held-out composite improvement vs the surface before this edit. */
+    holdoutDelta: number;
+}
+export interface SkillOptEpochRecord {
+    epoch: number;
+    editBudget: number;
+    proposed: number;
+    /** The accepted edit this epoch, or null if every proposal was rejected. */
+    accepted: AcceptedEdit | null;
+    rejected: RejectedEdit[];
+    /** Held-out composite of the CURRENT surface at the END of the epoch. */
+    holdoutComposite: number;
+}
+export interface RunSkillOptResult {
+    winnerSurface: string;
+    baselineHoldoutComposite: number;
+    winnerHoldoutComposite: number;
+    /** `winnerHoldoutComposite - baselineHoldoutComposite` — monotonically ≥ 0
+     *  by construction (only strictly-improving edits are accepted). */
+    lift: number;
+    acceptedEdits: AcceptedEdit[];
+    rejectedEdits: RejectedEdit[];
+    epochsRun: number;
+    history: SkillOptEpochRecord[];
+    /** Total cost across every scoring campaign (train evidence + holdout
+     *  acceptance) the hill-climb ran. */
+    totalCostUsd: number;
+}
+export declare function runSkillOpt<TScenario extends Scenario, TArtifact>(opts: RunSkillOptOptions<TScenario, TArtifact>): Promise<RunSkillOptResult>;
+//# sourceMappingURL=run-skill-opt.d.ts.map

package/dist/campaign/presets/run-skill-opt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-skill-opt.d.ts","sourceRoot":"","sources":["../../../src/campaign/presets/run-skill-opt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9F,OAAO,EAAE,KAAK,kBAAkB,EAAe,MAAM,iBAAiB,CAAA;AAGtE,OAAO,KAAK,EAAkB,eAAe,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEzE,MAAM,WAAW,kBAAkB,CAAC,SAAS,SAAS,QAAQ,EAAE,SAAS,CACvE,SAAQ,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IAChF,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAA;IACvB,yEAAyE;IACzE,mBAAmB,EAAE,CACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,EACnB,GAAG,EAAE,eAAe,KACjB,OAAO,CAAC,SAAS,CAAC,CAAA;IACvB,QAAQ,EAAE,gBAAgB,CAAA;IAC1B;wEACoE;IACpE,cAAc,EAAE,SAAS,EAAE,CAAA;IAC3B;+BAC2B;IAC3B,gBAAgB,EAAE,SAAS,EAAE,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;8DAC0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;0CACsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;wBACoB;IACpB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAC7B,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,yEAAyE;IACzE,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAA;IACrB,wBAAwB,EAAE,MAAM,CAAA;IAChC,sBAAsB,EAAE,MAAM,CAAA;IAC9B;wEACoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,YAAY,EAAE,CAAA;IAC7B,aAAa,EAAE,YAAY,EAAE,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,mBAAmB,EAAE,CAAA;IAC9B;0CACsC;IACtC,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,wBAAsB,WAAW,CAAC,SAAS,SAAS,QAAQ,EAAE,SAAS,EACrE,IAAI,EAAE,kBAAkB,CAAC,SAAS,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC,iBAAiB,CAAC,CAqJ5B"}

package/dist/campaign/proposers/_findings-text.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared finding→text helpers for the curator-style proposers (`memoryCurationProposer`
+ * dedup-and-replace, `aceProposer` append-mostly). One copy so the two proposers
+ * extract lessons + normalize keys identically and cannot drift apart.
+ */
+import type { MutableSurface } from '../types';
+/** A finding can be a raw string or a structured analyst finding. Pulls the
+ *  most actionable text (recommended_action > claim > lesson > text > message). */
+export declare function findingToLesson(f: unknown): string | null;
+/** Normalize for dedup/idempotency: lowercase, collapse whitespace, strip
+ *  trailing punctuation. */
+export declare function normKey(s: string): string;
+/** Curator proposers are prompt-tier — they manage a text block in the surface.
+ *  A code-tier surface has no prompt to append to; fail loud rather than
+ *  silently coercing. */
+export declare function surfaceToText(surface: MutableSurface): string;
+/** Body text strictly between `startMarker` and `endMarker`; '' if absent. */
+export declare function extractBlockBody(text: string, startMarker: string, endMarker: string): string;
+/** Remove the delimited block (and surrounding trailing whitespace), trimmed,
+ *  so the caller can re-emit a fresh block. */
+export declare function stripBlock(text: string, startMarker: string, endMarker: string): string;
+//# sourceMappingURL=_findings-text.d.ts.map

package/dist/campaign/proposers/_findings-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_findings-text.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/_findings-text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE9C;mFACmF;AACnF,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAQzD;AAED;4BAC4B;AAC5B,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzC;AAED;;yBAEyB;AACzB,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAK7D;AAOD,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK7F;AAED;+CAC+C;AAC/C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKvF"}

package/dist/campaign/proposers/ace.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `aceProposer` — Agentic Context Engineering: an APPEND-MOSTLY curator, the
+ * deliberate contrast to `memoryCurationProposer`'s dedup-and-replace. ACE's
+ * thesis (arXiv:2510.04618) is that aggressively deduping/rewriting a context
+ * causes "context collapse" — hard-won specific lessons get summarized away. So
+ * the playbook GROWS by appending each generation's new lessons as provenance-
+ * tagged delta bullets; existing bullets are preserved verbatim, never merged.
+ *
+ * Each generation it:
+ *  1. reads the playbook block already in the parent surface (verbatim);
+ *  2. turns this generation's `findings` into lessons, keeping only the ones not
+ *     already present (idempotency — a recurring finding is not re-appended, but
+ *     a genuinely NEW lesson always is, even if similar to an old one);
+ *  3. appends the new lessons as `- [gN] <lesson>` deltas and re-emits the block.
+ *
+ * Bounded WITHOUT collapse: when the playbook exceeds `maxEntries`, the OLDEST
+ * deltas are evicted (FIFO) — recency is kept, but no two distinct lessons are
+ * ever merged into one. Deterministic (no LLM) so a lift is attributable to the
+ * accumulated lessons, not a rewrite's model noise.
+ *
+ * Fail-loud: with no new lesson this generation it returns NO candidate (the
+ * playbook is unchanged — nothing to propose), never a fabricated bullet.
+ */
+import type { SurfaceProposer } from '../types';
+export interface AceProposerOptions {
+    /** Max delta bullets retained in the playbook. On overflow the OLDEST are
+     *  evicted (FIFO) — never merged. Default 50 (ACE keeps a long context). */
+    maxEntries?: number;
+    /** Heading rendered above the bullets inside the block. */
+    sectionHeading?: string;
+}
+export declare function aceProposer(opts?: AceProposerOptions): SurfaceProposer;
+//# sourceMappingURL=ace.d.ts.map

package/dist/campaign/proposers/ace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ace.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/ace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,UAAU,CAAA;AAalF,MAAM,WAAW,kBAAkB;IACjC;gFAC4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAwBD,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,eAAe,CAgD1E"}

package/dist/campaign/proposers/ace.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ace.test.d.ts.map

package/dist/campaign/proposers/ace.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ace.test.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/ace.test.ts"],"names":[],"mappings":""}

package/dist/campaign/proposers/analysis-edit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared core for prompt-tier "analysis → one LLM edit" proposers. `haloProposer`
+ * and `traceAnalystProposer` differ ONLY in who produces the findings; the
+ * materialize-traces → apply-via-`APPLY_SYSTEM` → candidate pipeline is
+ * identical. Keeping it in one place IS the fairness contract their head-to-head
+ * (`compareProposers`) depends on — the apply step can no longer drift between the
+ * two engines being compared.
+ */
+import type { LlmClientOptions } from '../../llm-client';
+import type { ProposeContext, SurfaceProposer } from '../types';
+export declare const APPLY_SYSTEM = "You apply a trace-analysis report to an agent instruction prompt. Output ONLY the full revised prompt \u2014 no preamble, no commentary, no code fences. Make the minimal edits that address the report findings; preserve everything else verbatim.";
+/** Serialize a surface (string or structured) into prompt text. */
+export declare function surfaceToPromptText(surface: unknown): string;
+export interface AnalysisEditProposerOptions {
+    kind: string;
+    label: string;
+    baseUrl: string;
+    apiKey?: string;
+    applyModel: string;
+    fetchImpl?: LlmClientOptions['fetch'];
+    /** Resolve the OTLP traces (JSONL) for THIS generation. Empty → `noTracesError`. */
+    resolveTraces: (ctx: ProposeContext) => string | Promise<string>;
+    /** Produce the analysis REPORT string from the materialized trace file. Owns
+     *  its engine-specific failure + no-findings throws. */
+    analyze: (tracePath: string, ctx: ProposeContext) => Promise<string>;
+    noTracesError: string;
+    rationale: (report: string) => string;
+}
+/** Build a `SurfaceProposer` that runs `analyze` over the generation's OTLP
+ *  traces and applies the report to the surface via one identical LLM edit. */
+export declare function analysisEditProposer(opts: AnalysisEditProposerOptions): SurfaceProposer;
+//# sourceMappingURL=analysis-edit.d.ts.map

package/dist/campaign/proposers/analysis-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis-edit.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/analysis-edit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,OAAO,KAAK,EAAE,cAAc,EAAqB,eAAe,EAAE,MAAM,UAAU,CAAA;AAElF,eAAO,MAAM,YAAY,yPAC0N,CAAA;AAEnP,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE5D;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACrC,oFAAoF;IACpF,aAAa,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAChE;4DACwD;IACxD,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACpE,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;CACtC;AAED;+EAC+E;AAC/E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,eAAe,CAgCvF"}

package/dist/campaign/proposers/evolutionary.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `evolutionaryProposer` — adapts a stateless `Mutator` (population mutation:
+ * GEPA / AxGEPA / reflective-mutation) into a `SurfaceProposer`. This is
+ * the evolutionary strategy: each generation, mutate the current best surface
+ * into N candidates, measure, select. No generation memory beyond the current
+ * surface; the loop body handles ranking + promotion.
+ *
+ * The reflective alternative is agent-runtime's runtime proposer with a
+ * `reflectiveGenerator` / `agenticGenerator`: it reasons over the report +
+ * trace findings to propose targeted edits rather than blind mutations. Both
+ * conform to `SurfaceProposer`; the improvement loop is identical either way.
+ */
+import type { Mutator, SurfaceProposer } from '../types';
+export interface EvolutionaryProposerOptions<TFindings = unknown> {
+    mutator: Mutator<TFindings>;
+    /** External findings fed to the mutator each generation. Default: []. */
+    findings?: TFindings[];
+}
+export declare function evolutionaryProposer<TFindings = unknown>(opts: EvolutionaryProposerOptions<TFindings>): SurfaceProposer<TFindings>;
+//# sourceMappingURL=evolutionary.d.ts.map

package/dist/campaign/proposers/evolutionary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evolutionary.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/evolutionary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAExD,MAAM,WAAW,2BAA2B,CAAC,SAAS,GAAG,OAAO;IAC9D,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAA;CACvB;AAED,wBAAgB,oBAAoB,CAAC,SAAS,GAAG,OAAO,EACtD,IAAI,EAAE,2BAA2B,CAAC,SAAS,CAAC,GAC3C,eAAe,CAAC,SAAS,CAAC,CAY5B"}

package/dist/campaign/proposers/fapo.d.ts

@@ -0,0 +1,120 @@
+/**
+ * FAPO (Fully Autonomous Prompt Optimization) is an orchestration policy, not
+ * a new prompt mutation primitive. The paper's loop evaluates an inspectable
+ * workflow, attributes failures to an edit level, proposes ONE scoped change,
+ * reviews it, measures it, and escalates from prompt -> parameters -> structure
+ * only when prompt-level search is exhausted and attribution supports the
+ * higher-cost edit.
+ *
+ * This substrate proposer encodes that policy while keeping the edit generators
+ * pluggable:
+ *   - prompt: usually `gepaProposer`, `skillOptProposer`, or a runtime reflective proposer
+ *   - parameter: `parameterSweepProposer` or a caller-supplied config proposer
+ *   - structural: a caller-supplied code/worktree proposer from agent-runtime
+ *
+ * It deliberately does not import Claude Code, LangGraph, or Cisco's tenant
+ * runtime. agent-eval owns measurement and proposer contracts; runtime-shaped
+ * code generation stays downstream.
+ *
+ * Grounded sources:
+ *   - Kassianik et al., "FAPO: Fully Autonomous Prompt Optimization of
+ *     Multi-Step LLM Pipelines", arXiv:2606.19605v1.
+ *   - cisco-foundation-ai/fully-automated-prompt-optimization at
+ *     376b50c57d5e2423e5a5de46e0d315a761d272d8.
+ */
+import type { ProposeContext, ProposedCandidate, SurfaceProposer } from '../types';
+export type FapoOptimizationLevel = 'prompt' | 'parameter' | 'structural';
+export interface FapoScopeContract {
+    /** Levels the tenant/playbook allows. Defaults to the levels with proposers. */
+    allowedLevels?: readonly FapoOptimizationLevel[];
+    /** Explicitly forbidden levels; wins over `allowedLevels`. */
+    forbiddenLevels?: readonly FapoOptimizationLevel[];
+}
+export interface FapoFailureCluster {
+    label: string;
+    level: FapoOptimizationLevel;
+    count: number;
+    confidence?: 'high' | 'medium' | 'low';
+    suggestedFix?: string;
+    caseIds?: string[];
+}
+export interface FapoAttributionSignals {
+    counts: Record<FapoOptimizationLevel, number>;
+    clusters: FapoFailureCluster[];
+}
+export interface FapoReviewIssue {
+    checkName: string;
+    severity: 'block' | 'warn';
+    description: string;
+    location?: string;
+}
+export interface FapoReviewResult {
+    verdict: 'pass' | 'warn' | 'fail';
+    issues?: FapoReviewIssue[];
+    suggestions?: string[];
+}
+export interface FapoReviewInput<TFindings = unknown> {
+    level: FapoOptimizationLevel;
+    candidate: ProposedCandidate;
+    context: ProposeContext<TFindings>;
+    reason: string;
+}
+export interface FapoProposerOptions<TFindings = unknown> {
+    /** Level-specific candidate proposers. At least one is required. */
+    proposers?: Partial<Record<FapoOptimizationLevel, SurfaceProposer<TFindings>>>;
+    /** Convenience aliases for `proposers.<level>`. */
+    promptProposer?: SurfaceProposer<TFindings>;
+    parameterProposer?: SurfaceProposer<TFindings>;
+    structuralProposer?: SurfaceProposer<TFindings>;
+    /** Tenant/playbook-derived allowed and forbidden edit levels. */
+    scope?: FapoScopeContract;
+    /**
+     * Independent reviewer hook. Return `fail` to block a candidate before eval,
+     * mirroring FAPO's variant-reviewer phase.
+     */
+    reviewCandidate?: (input: FapoReviewInput<TFindings>) => Promise<FapoReviewResult>;
+    /**
+     * FAPO proposes one scoped change per cycle. Keep this at 1 unless you are
+     * intentionally relaxing the paper loop for a batch experiment.
+     */
+    proposalsPerCycle?: number;
+    /** Consecutive non-improving variants required before a level is exhausted. Default 3. */
+    plateauWindow?: number;
+    /** Distinct strategies required before declaring a plateau. Default 3. */
+    minDistinctStrategies?: number;
+    /** Candidate score delta needed to count as an improvement. Default 0. */
+    minImprovement?: number;
+    /** Paper-faithful default: try prompt edits before escalating. */
+    promptFirst?: boolean;
+    /** Paper-faithful default: try parameter/config edits before structural code edits. */
+    parameterBeforeStructural?: boolean;
+}
+/** Build a FAPO policy proposer from level-specific candidate generators. */
+export declare function fapoProposer<TFindings = unknown>(opts: FapoProposerOptions<TFindings>): SurfaceProposer<TFindings>;
+export declare function extractFapoAttributionSignals(findings: readonly unknown[]): FapoAttributionSignals;
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface ParameterChange {
+    path: string | readonly string[];
+    value: JsonValue;
+}
+export interface ParameterCandidate {
+    label: string;
+    rationale: string;
+    /** Deep-merged into the current JSON surface. */
+    patch?: Record<string, JsonValue>;
+    /** Dot-path writes, e.g. `{ path: 'retrieval.k', value: 10 }`. */
+    changes?: readonly ParameterChange[];
+}
+export interface ParameterSweepProposerOptions {
+    candidates: readonly ParameterCandidate[];
+    /** Optional parser for non-JSON config surface strings. */
+    parse?: (surface: string) => Record<string, JsonValue>;
+    /** Optional serializer for non-JSON config surface strings. */
+    stringify?: (config: Record<string, JsonValue>) => string;
+}
+/** Config/parameter-level proposer for FAPO's middle escalation level. */
+export declare function parameterSweepProposer(opts: ParameterSweepProposerOptions): SurfaceProposer;
+//# sourceMappingURL=fapo.d.ts.map

package/dist/campaign/proposers/fapo.d.ts.map

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

package/dist/campaign/proposers/gepa.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `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.
+ */
+import { type LlmClientOptions } from '../../llm-client';
+import type { SurfaceProposer } from '../types';
+export 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;
+}
+export 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;
+}
+export 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. */
+export 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. */
+export declare function countSentenceEdits(baseline: string, candidate: string): number;
+//# sourceMappingURL=gepa.d.ts.map

package/dist/campaign/proposers/gepa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gepa.d.ts","sourceRoot":"","sources":["../../../src/campaign/proposers/gepa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAW,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAOjE,OAAO,KAAK,EAAqC,eAAe,EAAE,MAAM,UAAU,CAAA;AA6BlF,MAAM,WAAW,uBAAuB;IACtC;;;;kDAI8C;IAC9C,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B;;;2EAGuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,GAAG,EAAE,gBAAgB,CAAA;IACrB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;+DAC2D;IAC3D,WAAW,CAAC,EAAE,uBAAuB,CAAA;IACrC;;;;;yCAKqC;IACrC,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;6DACyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAmHvE;AA2CD;wEACwE;AACxE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxD;AAED;;8EAE8E;AAC9E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAY9E"}