agent-composer 0.1.0

package/dist/evolve/budget.d.ts

@@ -0,0 +1,23 @@
+export interface EvolveBudgetConfig {
+    maxCalls: number;
+    maxUsd: number;
+}
+export declare const DEFAULT_EVOLVE_BUDGET: EvolveBudgetConfig;
+export declare class EvolveBudgetExceededError extends Error {
+    constructor(reason: string);
+}
+export interface EvolveBudgetStats {
+    calls: number;
+    usd: number;
+}
+export declare class EvolveBudgetGuard {
+    private readonly config;
+    private _calls;
+    private _usd;
+    constructor(config: EvolveBudgetConfig);
+    /** Record a completed call and its measured USD cost. Throws on cap. */
+    spent(usdCost: number): void;
+    get stats(): EvolveBudgetStats;
+    get remaining(): EvolveBudgetStats;
+    exhausted(): boolean;
+}

package/dist/evolve/budget.js

@@ -0,0 +1,55 @@
+// Wave 3 Step 2 — per-/evolve-session BudgetGuard.
+//
+// Distinct from the Wave 2 per-eval BudgetGuard (tests/eval/budget.ts):
+// that one caps a single eval run; this one caps the whole evolve loop
+// (~100 eval calls + ~30 reflection calls ≈ $3.50, capped at $4.00).
+//
+// Reflection LM is GLM 5.1: $0.98 in / $3.08 out per MTok.
+export const DEFAULT_EVOLVE_BUDGET = {
+    maxCalls: 100,
+    maxUsd: 4.0,
+};
+export class EvolveBudgetExceededError extends Error {
+    constructor(reason) {
+        super(`Evolve budget exceeded: ${reason}`);
+        this.name = "EvolveBudgetExceededError";
+    }
+}
+export class EvolveBudgetGuard {
+    config;
+    _calls = 0;
+    _usd = 0;
+    constructor(config) {
+        this.config = config;
+        if (config.maxCalls <= 0)
+            throw new Error("EvolveBudgetGuard: maxCalls must be positive");
+        if (config.maxUsd <= 0)
+            throw new Error("EvolveBudgetGuard: maxUsd must be positive");
+    }
+    /** Record a completed call and its measured USD cost. Throws on cap. */
+    spent(usdCost) {
+        if (usdCost < 0)
+            throw new Error("EvolveBudgetGuard.spent: usdCost must be >= 0");
+        this._calls += 1;
+        if (this._calls > this.config.maxCalls) {
+            throw new EvolveBudgetExceededError(`call cap ${this.config.maxCalls} (this would be call #${this._calls})`);
+        }
+        this._usd += usdCost;
+        if (this._usd > this.config.maxUsd) {
+            throw new EvolveBudgetExceededError(`USD cap $${this.config.maxUsd.toFixed(2)} (now $${this._usd.toFixed(4)})`);
+        }
+    }
+    get stats() {
+        return { calls: this._calls, usd: this._usd };
+    }
+    get remaining() {
+        return {
+            calls: this.config.maxCalls - this._calls,
+            usd: this.config.maxUsd - this._usd,
+        };
+    }
+    exhausted() {
+        return this._calls >= this.config.maxCalls || this._usd >= this.config.maxUsd;
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/evolve/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/evolve/budget.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,EAAE;AACF,2DAA2D;AAO3D,MAAM,CAAC,MAAM,qBAAqB,GAAuB;IACvD,QAAQ,EAAE,GAAG;IACb,MAAM,EAAE,GAAG;CACZ,CAAC;AAEF,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,MAAc;QACxB,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAOD,MAAM,OAAO,iBAAiB;IAIC;IAHrB,MAAM,GAAG,CAAC,CAAC;IACX,IAAI,GAAG,CAAC,CAAC;IAEjB,YAA6B,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;QACrD,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC1F,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACxF,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,OAAe;QACnB,IAAI,OAAO,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QAClF,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACjB,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvC,MAAM,IAAI,yBAAyB,CACjC,YAAY,IAAI,CAAC,MAAM,CAAC,QAAQ,yBAAyB,IAAI,CAAC,MAAM,GAAG,CACxE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC;QACrB,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnC,MAAM,IAAI,yBAAyB,CACjC,YAAY,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,KAAK;QACP,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAChD,CAAC;IAED,IAAI,SAAS;QACX,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM;YACzC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI;SACpC,CAAC;IACJ,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAChF,CAAC;CACF"}

package/dist/evolve/lengthPenalty.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_LAMBDA = 0.001;
+export declare function estimateTokens(text: string): number;
+export declare function lengthPenalty(skill: string, lambda?: number): number;

package/dist/evolve/lengthPenalty.js

@@ -0,0 +1,30 @@
+// Wave 3 Step 2 — length penalty for bloat-drift control.
+//
+// score_adjusted = score_raw − λ · tokens(skill)
+//
+// Replaces the `remove_bloat` operator (excluded — 0% keep-rate per
+// Karpathy data). λ default 0.001 means a 1000-token skill loses 1
+// score point versus a 0-token skill — large enough to overcome
+// noise, small enough to keep useful additions.
+//
+// Token estimator is intentionally crude (whitespace + bullets);
+// the metric only needs to be monotonic in skill length to gate
+// bloat — exact tiktoken counts add a dep for no gain here.
+export const DEFAULT_LAMBDA = 0.001;
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return text
+        .split(/\s+|[-*]\s+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0).length;
+}
+export function lengthPenalty(skill, lambda = DEFAULT_LAMBDA) {
+    if (lambda < 0) {
+        throw new Error(`lengthPenalty: lambda must be >= 0, got ${lambda}`);
+    }
+    if (!skill)
+        return 0;
+    return -lambda * estimateTokens(skill);
+}
+//# sourceMappingURL=lengthPenalty.js.map

package/dist/evolve/lengthPenalty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lengthPenalty.js","sourceRoot":"","sources":["../../src/evolve/lengthPenalty.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,oEAAoE;AACpE,mEAAmE;AACnE,gEAAgE;AAChE,gDAAgD;AAChD,EAAE;AACF,iEAAiE;AACjE,gEAAgE;AAChE,4DAA4D;AAE5D,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AAEpC,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,IAAI;SACR,KAAK,CAAC,aAAa,CAAC;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,SAAiB,cAAc;IAC1E,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,OAAO,CAAC,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC"}

package/dist/evolve/operators.d.ts

@@ -0,0 +1,24 @@
+export interface OperatorContext {
+    counterexample?: string;
+    constraint?: string;
+    negativeExample?: string;
+    /** GEPA reflection LM callback. Returns rewritten skill text. */
+    reflect?: (text: string, ctx: OperatorContext) => Promise<string>;
+    /** Preflight ecosystem snapshot, surfaced into reflect prompt by runner. */
+    currentEcosystem?: string;
+}
+export interface OperatorMeta {
+    name: string;
+    /** Empirical keep-rate from Karpathy autoresearch dataset. */
+    keepRate: number;
+    apply: (skill: string, ctx: OperatorContext) => Promise<string>;
+}
+export declare function addCounterexample(skill: string, ctx: OperatorContext): string;
+export declare function tightenLanguage(skill: string, _ctx: OperatorContext): string;
+export declare function addConstraint(skill: string, ctx: OperatorContext): string;
+export declare function addNegativeExample(skill: string, ctx: OperatorContext): string;
+export declare function reflectAndRewrite(skill: string, ctx: OperatorContext): Promise<string>;
+export declare const OPERATORS: ReadonlyArray<OperatorMeta>;
+export declare function pickOperator(index: number): OperatorMeta;
+export declare const OPERATOR_BY_CLI_NAME: Readonly<Record<string, OperatorMeta>>;
+export declare const VALID_OPERATOR_CLI_NAMES: ReadonlyArray<string>;

package/dist/evolve/operators.js

@@ -0,0 +1,110 @@
+// Wave 3 Step 2 — mutation operators for self-evolve loop.
+//
+// 5 operators kept (Karpathy autoresearch empirical keep-rates):
+//   add_counterexample   100%
+//   tighten_language      67%
+//   add_constraint        50%
+//   add_negative_example  50%
+//   reflect_and_rewrite   GEPA core
+//
+// Skipped: restructure + remove_bloat (both 0% keep-rate). Bloat drift
+// is countered by lengthPenalty.ts, not by a remove_bloat operator.
+const HEDGES = /\b(probably|maybe|perhaps|might|consider(?:ing)?|kind of|sort of)\b\s*/gi;
+const SOFT_SUBJECT = /\b(you should|you could|you might|you can)\s+/gi;
+export function addCounterexample(skill, ctx) {
+    const ex = ctx.counterexample?.trim();
+    if (!ex)
+        return skill;
+    const header = "## Counterexamples";
+    if (skill.includes(header)) {
+        return skill.replace(header, `${header}\n\n- ${ex}\n`).replace(/\n\n- ${ex}\n\n/, `\n\n- ${ex}\n`);
+    }
+    const sep = skill.endsWith("\n") ? "\n" : "\n\n";
+    return `${skill}${sep}${header}\n\n- ${ex}\n`;
+}
+export function tightenLanguage(skill, _ctx) {
+    HEDGES.lastIndex = 0;
+    SOFT_SUBJECT.lastIndex = 0;
+    if (!HEDGES.test(skill) && !SOFT_SUBJECT.test(skill)) {
+        HEDGES.lastIndex = 0;
+        SOFT_SUBJECT.lastIndex = 0;
+        return skill;
+    }
+    HEDGES.lastIndex = 0;
+    SOFT_SUBJECT.lastIndex = 0;
+    return skill
+        .replace(SOFT_SUBJECT, "")
+        .replace(HEDGES, "")
+        .replace(/[ \t]+/g, " ")
+        .replace(/ ([.,;:])/g, "$1")
+        .trim();
+}
+export function addConstraint(skill, ctx) {
+    const c = ctx.constraint?.trim();
+    if (!c)
+        return skill;
+    const header = "## Constraints";
+    const line = `- ${c}`;
+    if (skill.includes(header)) {
+        if (skill.includes(line))
+            return skill;
+        return skill.replace(header, `${header}\n\n${line}`);
+    }
+    const sep = skill.endsWith("\n") ? "\n" : "\n\n";
+    return `${skill}${sep}${header}\n\n${line}\n`;
+}
+export function addNegativeExample(skill, ctx) {
+    const ne = ctx.negativeExample?.trim();
+    if (!ne)
+        return skill;
+    const line = `DO NOT ${ne}`;
+    if (skill.includes(line))
+        return skill;
+    const sep = skill.endsWith("\n") ? "\n" : "\n\n";
+    return `${skill}${sep}${line}\n`;
+}
+export async function reflectAndRewrite(skill, ctx) {
+    if (!ctx.reflect)
+        return skill;
+    return ctx.reflect(skill, ctx);
+}
+export const OPERATORS = [
+    {
+        name: "add_counterexample",
+        keepRate: 1.0,
+        apply: async (s, c) => addCounterexample(s, c),
+    },
+    {
+        name: "tighten_language",
+        keepRate: 0.67,
+        apply: async (s, c) => tightenLanguage(s, c),
+    },
+    {
+        name: "add_constraint",
+        keepRate: 0.5,
+        apply: async (s, c) => addConstraint(s, c),
+    },
+    {
+        name: "add_negative_example",
+        keepRate: 0.5,
+        apply: async (s, c) => addNegativeExample(s, c),
+    },
+    {
+        name: "reflect_and_rewrite",
+        keepRate: 0.0, // GEPA core; keep-rate measured live, not pre-seeded.
+        apply: reflectAndRewrite,
+    },
+];
+export function pickOperator(index) {
+    if (index < 0 || !Number.isInteger(index)) {
+        throw new Error(`pickOperator: index must be non-negative integer, got ${index}`);
+    }
+    return OPERATORS[index % OPERATORS.length];
+}
+// CLI-facing lookup: snake_case op.name → camelCase key (e.g. "tighten_language" → "tightenLanguage").
+export const OPERATOR_BY_CLI_NAME = Object.fromEntries(OPERATORS.map((op) => {
+    const camel = op.name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    return [camel, op];
+}));
+export const VALID_OPERATOR_CLI_NAMES = Object.keys(OPERATOR_BY_CLI_NAME);
+//# sourceMappingURL=operators.js.map

package/dist/evolve/operators.js.map

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

package/dist/evolve/pareto.d.ts

@@ -0,0 +1,24 @@
+export interface CI {
+    lower: number;
+    upper: number;
+}
+export declare function mean(xs: ReadonlyArray<number>): number;
+export declare function stdDev(xs: ReadonlyArray<number>): number;
+export declare function ci95(xs: ReadonlyArray<number>): CI;
+export declare function wilcoxonSignedRankP(parent: ReadonlyArray<number>, candidate: ReadonlyArray<number>): number;
+export interface BeatsResult {
+    beats: boolean;
+    reason: string;
+    parentMean: number;
+    candidateMean: number;
+    wilcoxonP?: number;
+    parentCI?: CI;
+    candidateCI?: CI;
+}
+export interface BeatsOptions {
+    parentTokens?: number;
+    candidateTokens?: number;
+    /** Wilcoxon p-value threshold. Locked: 0.1 per handoff. */
+    pThreshold?: number;
+}
+export declare function candidateBeatsParent(parentScores: ReadonlyArray<number>, candidateScores: ReadonlyArray<number>, opts?: BeatsOptions): BeatsResult;

package/dist/evolve/pareto.js

@@ -0,0 +1,153 @@
+// Wave 3 Step 2 — variance handling for candidate selection.
+//
+// Per locked design:
+//   - temperature=0, N=3-5 re-runs on candidates that beat parent
+//   - accept iff non-overlapping 95% CIs OR paired Wilcoxon p<0.1
+//   - Occam tiebreak: on numerical tie, shorter prompt wins.
+//
+// Wilcoxon is the small-sample non-parametric paired test. We compute
+// the two-sided p-value via a normal-approx of the signed-rank
+// statistic with continuity correction — good enough for N=3..20.
+// At very small N (≤5) the normal approx is loose; runner falls back
+// on the CI check, so loose p is OK here.
+export function mean(xs) {
+    if (xs.length === 0)
+        return 0;
+    return xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+export function stdDev(xs) {
+    if (xs.length < 2)
+        return 0;
+    const m = mean(xs);
+    const ssq = xs.reduce((acc, x) => acc + (x - m) ** 2, 0);
+    return Math.sqrt(ssq / (xs.length - 1));
+}
+export function ci95(xs) {
+    if (xs.length === 0)
+        return { lower: 0, upper: 0 };
+    if (xs.length === 1)
+        return { lower: xs[0], upper: xs[0] };
+    const m = mean(xs);
+    const se = stdDev(xs) / Math.sqrt(xs.length);
+    // 1.96 z-score; we don't bother with t-table at N≥3
+    const half = 1.96 * se;
+    return { lower: m - half, upper: m + half };
+}
+function rankWithTies(absDiffs) {
+    const indexed = absDiffs.map((v, i) => ({ v, i }));
+    indexed.sort((a, b) => a.v - b.v);
+    const ranks = new Array(absDiffs.length).fill(0);
+    let i = 0;
+    while (i < indexed.length) {
+        let j = i;
+        while (j + 1 < indexed.length && indexed[j + 1].v === indexed[i].v)
+            j++;
+        const avg = (i + j) / 2 + 1; // 1-indexed average rank
+        for (let k = i; k <= j; k++)
+            ranks[indexed[k].i] = avg;
+        i = j + 1;
+    }
+    return ranks;
+}
+function normalCdf(z) {
+    // Abramowitz & Stegun 7.1.26 approximation
+    const t = 1 / (1 + 0.2316419 * Math.abs(z));
+    const d = 0.39894228 * Math.exp(-(z * z) / 2);
+    const p = d *
+        t *
+        (0.31938153 +
+            t *
+                (-0.356563782 +
+                    t * (1.781477937 + t * (-1.821255978 + t * 1.330274429))));
+    return z > 0 ? 1 - p : p;
+}
+export function wilcoxonSignedRankP(parent, candidate) {
+    if (parent.length !== candidate.length) {
+        throw new Error("wilcoxonSignedRankP: paired samples must have equal length");
+    }
+    const diffs = [];
+    for (let i = 0; i < parent.length; i++) {
+        const d = candidate[i] - parent[i];
+        if (d !== 0)
+            diffs.push(d);
+    }
+    if (diffs.length === 0)
+        return 1;
+    const ranks = rankWithTies(diffs.map(Math.abs));
+    const wPlus = ranks.reduce((acc, r, i) => acc + (diffs[i] > 0 ? r : 0), 0);
+    const wMinus = ranks.reduce((acc, r, i) => acc + (diffs[i] < 0 ? r : 0), 0);
+    const w = Math.min(wPlus, wMinus);
+    const n = diffs.length;
+    const mu = (n * (n + 1)) / 4;
+    const sigma = Math.sqrt((n * (n + 1) * (2 * n + 1)) / 24);
+    if (sigma === 0)
+        return 1;
+    const z = (w - mu + 0.5) / sigma; // continuity correction
+    return 2 * normalCdf(-Math.abs(z));
+}
+export function candidateBeatsParent(parentScores, candidateScores, opts = {}) {
+    const pMean = parentScores.length ? mean(parentScores) : 0;
+    const cMean = candidateScores.length ? mean(candidateScores) : 0;
+    // Empty-side guard: cannot promote a candidate that has no evaluable scores
+    // (all task evals failed asymmetrically). Refuse rather than crash on
+    // downstream stats. Parent-empty is similarly meaningless.
+    if (parentScores.length === 0 || candidateScores.length === 0) {
+        return {
+            beats: false,
+            reason: `inconclusive — empty score array (parent=${parentScores.length}, candidate=${candidateScores.length})`,
+            parentMean: pMean,
+            candidateMean: cMean,
+        };
+    }
+    const pCI = ci95(parentScores);
+    const cCI = ci95(candidateScores);
+    const pThresh = opts.pThreshold ?? 0.1;
+    // CI disjoint and candidate higher → win.
+    if (cCI.lower > pCI.upper) {
+        return {
+            beats: true,
+            reason: "non-overlapping 95% CIs (candidate higher)",
+            parentMean: pMean,
+            candidateMean: cMean,
+            parentCI: pCI,
+            candidateCI: cCI,
+        };
+    }
+    // Wilcoxon — only meaningful if candidate mean ≥ parent AND arrays are
+    // paired (equal length). When real-eval evaluator hits asymmetric per-task
+    // failures (e.g. one task crashed on the candidate side but not the parent),
+    // skip the paired stat and let the next gate (Occam tiebreak / no-op) decide.
+    if (cMean > pMean && parentScores.length === candidateScores.length && parentScores.length >= 2) {
+        const p = wilcoxonSignedRankP(parentScores, candidateScores);
+        if (p < pThresh) {
+            return {
+                beats: true,
+                reason: `Wilcoxon p=${p.toFixed(3)} < ${pThresh}`,
+                parentMean: pMean,
+                candidateMean: cMean,
+                wilcoxonP: p,
+            };
+        }
+    }
+    // Occam tiebreak — strict tie on means + shorter prompt → win.
+    if (cMean === pMean &&
+        opts.parentTokens !== undefined &&
+        opts.candidateTokens !== undefined &&
+        opts.candidateTokens < opts.parentTokens) {
+        return {
+            beats: true,
+            reason: "Occam tiebreak: shorter prompt at equal score",
+            parentMean: pMean,
+            candidateMean: cMean,
+        };
+    }
+    return {
+        beats: false,
+        reason: "no significant improvement",
+        parentMean: pMean,
+        candidateMean: cMean,
+        parentCI: pCI,
+        candidateCI: cCI,
+    };
+}
+//# sourceMappingURL=pareto.js.map

package/dist/evolve/pareto.js.map

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

package/dist/evolve/plateau.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_PLATEAU_ROUNDS = 5;
+export declare const DEFAULT_MIN_DELTA = 0.01;
+export interface PlateauConfig {
+    rounds?: number;
+    minDelta?: number;
+}
+export declare class PlateauDetector {
+    private readonly rounds;
+    private readonly minDelta;
+    private last;
+    private flat;
+    constructor(cfg?: PlateauConfig);
+    observe(score: number): void;
+    get consecutiveFlatRounds(): number;
+    shouldStop(): boolean;
+    /** Final gate — runner calls this with the N=3 re-run survival flag. */
+    terminate(reSurvived: boolean): boolean;
+}

package/dist/evolve/plateau.js

@@ -0,0 +1,45 @@
+// Wave 3 Step 2 — plateau-stop detector for the evolve loop.
+//
+// Locked rule: stop after `rounds` consecutive holdout observations
+// that fail to improve by `minDelta`. Defaults: 5 rounds × 0.01 delta.
+// Termination additionally requires `reSurvived` — an N=3 re-run on
+// the best candidate must survive — so the runner gets a second
+// sanity check before declaring done.
+export const DEFAULT_PLATEAU_ROUNDS = 5;
+export const DEFAULT_MIN_DELTA = 0.01;
+export class PlateauDetector {
+    rounds;
+    minDelta;
+    last = null;
+    flat = 0;
+    constructor(cfg = {}) {
+        this.rounds = cfg.rounds ?? DEFAULT_PLATEAU_ROUNDS;
+        this.minDelta = cfg.minDelta ?? DEFAULT_MIN_DELTA;
+    }
+    observe(score) {
+        if (this.last === null) {
+            this.last = score;
+            this.flat = 0;
+            return;
+        }
+        const delta = score - this.last;
+        if (delta >= this.minDelta) {
+            this.flat = 0;
+        }
+        else {
+            this.flat += 1;
+        }
+        this.last = score;
+    }
+    get consecutiveFlatRounds() {
+        return this.flat;
+    }
+    shouldStop() {
+        return this.flat >= this.rounds;
+    }
+    /** Final gate — runner calls this with the N=3 re-run survival flag. */
+    terminate(reSurvived) {
+        return this.shouldStop() && reSurvived;
+    }
+}
+//# sourceMappingURL=plateau.js.map

package/dist/evolve/plateau.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plateau.js","sourceRoot":"","sources":["../../src/evolve/plateau.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,oEAAoE;AACpE,gEAAgE;AAChE,sCAAsC;AAEtC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACxC,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAOtC,MAAM,OAAO,eAAe;IACT,MAAM,CAAS;IACf,QAAQ,CAAS;IAC1B,IAAI,GAAkB,IAAI,CAAC;IAC3B,IAAI,GAAG,CAAC,CAAC;IAEjB,YAAY,MAAqB,EAAE;QACjC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,sBAAsB,CAAC;QACnD,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACpD,CAAC;IAED,OAAO,CAAC,KAAa;QACnB,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;YAClB,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;YACd,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC;QAChC,IAAI,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3B,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,qBAAqB;QACvB,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC;IAClC,CAAC;IAED,wEAAwE;IACxE,SAAS,CAAC,UAAmB;QAC3B,OAAO,IAAI,CAAC,UAAU,EAAE,IAAI,UAAU,CAAC;IACzC,CAAC;CACF"}

package/dist/evolve/postflight.d.ts

@@ -0,0 +1,12 @@
+import type { IProvider } from "../providers/IProvider.js";
+export interface PostflightInput {
+    ecosystem: string;
+    candidate: string;
+}
+export interface Verdict {
+    accept: boolean;
+    reason: string;
+}
+export declare function buildPostflightPrompt(input: PostflightInput): string;
+export declare function parseVerdict(reply: string): Verdict;
+export declare function runPostflight(provider: IProvider, input: PostflightInput): Promise<Verdict>;

package/dist/evolve/postflight.js

@@ -0,0 +1,61 @@
+// Wave 3 Step 2 — postflight candidate validation via `agy` CLI.
+//
+// Runs AFTER the evolve loop picks a winning candidate. Asks the
+// research LM (Gemini 3.1 via agy) to check the candidate against
+// the preflight ecosystem snapshot, looking for references to
+// deprecated APIs or now-stale best practices.
+//
+// Fail-safe: any non-ACCEPT (ambiguous reply, provider error, missing
+// verdict) is treated as REJECT. The /evolve command keeps the prior
+// `*.candidate.md` for manual review rather than promoting a maybe-bad
+// candidate.
+import { s2DenyPrefilter } from "./s2-deny.js";
+export function buildPostflightPrompt(input) {
+    return [
+        "You are a postflight validator. Decide whether a self-evolved skill",
+        "candidate is safe to promote, given the current ecosystem snapshot.",
+        "",
+        "## Ecosystem snapshot",
+        input.ecosystem || "(none — preflight failed)",
+        "",
+        "## Candidate skill",
+        input.candidate,
+        "",
+        "Reject if the candidate references APIs / patterns the snapshot",
+        "lists as deprecated or removed. Otherwise accept.",
+        "",
+        "Reply with the FIRST line being exactly `VERDICT: ACCEPT` or",
+        "`VERDICT: REJECT`. Next line(s): one-sentence reason.",
+    ].join("\n");
+}
+const VERDICT_RE = /^\s*VERDICT:\s*(ACCEPT|REJECT)\b/im;
+export function parseVerdict(reply) {
+    const m = reply.match(VERDICT_RE);
+    if (!m)
+        return { accept: false, reason: "no verdict marker in reply (fail-safe REJECT)" };
+    const accept = m[1].toUpperCase() === "ACCEPT";
+    const reason = reply.replace(VERDICT_RE, "").trim() || (accept ? "no reason given" : "rejected");
+    return { accept, reason };
+}
+export async function runPostflight(provider, input) {
+    // ADR 0003 S2: deterministic deny-pattern prefilter runs BEFORE the LLM
+    // researcher. Short-circuits on any escalation primitive or boundary-
+    // bypass directive — the LLM cannot be prompt-injected to accept these
+    // because the LLM is never called on these candidates.
+    const s2 = s2DenyPrefilter(input.candidate);
+    if (!s2.allowed) {
+        return { accept: false, reason: s2.reason ?? "S2 deny-pattern matched" };
+    }
+    const prompt = buildPostflightPrompt(input);
+    try {
+        const out = await provider.execute({ prompt });
+        return parseVerdict(out.text);
+    }
+    catch (err) {
+        return {
+            accept: false,
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=postflight.js.map

package/dist/evolve/postflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postflight.js","sourceRoot":"","sources":["../../src/evolve/postflight.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,iEAAiE;AACjE,kEAAkE;AAClE,8DAA8D;AAC9D,+CAA+C;AAC/C,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,uEAAuE;AACvE,aAAa;AAGb,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAY/C,MAAM,UAAU,qBAAqB,CAAC,KAAsB;IAC1D,OAAO;QACL,qEAAqE;QACrE,qEAAqE;QACrE,EAAE;QACF,uBAAuB;QACvB,KAAK,CAAC,SAAS,IAAI,2BAA2B;QAC9C,EAAE;QACF,oBAAoB;QACpB,KAAK,CAAC,SAAS;QACf,EAAE;QACF,iEAAiE;QACjE,mDAAmD;QACnD,EAAE;QACF,8DAA8D;QAC9D,uDAAuD;KACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,GAAG,oCAAoC,CAAC;AAExD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,+CAA+C,EAAE,CAAC;IAC1F,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC;IAChD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IACjG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAmB,EACnB,KAAsB;IAEtB,wEAAwE;IACxE,sEAAsE;IACtE,uEAAuE;IACvE,uDAAuD;IACvD,MAAM,EAAE,GAAG,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC;QAChB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,IAAI,yBAAyB,EAAE,CAAC;IAC3E,CAAC;IACD,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/C,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACzD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/evolve/preflight.d.ts

@@ -0,0 +1,13 @@
+import type { IProvider } from "../providers/IProvider.js";
+export interface PreflightInput {
+    skillDomain: string;
+    lastEvolveDate?: string;
+}
+export interface PreflightSnapshot {
+    text: string;
+    prompt: string;
+    fetchedAt: string;
+    error?: string;
+}
+export declare function buildPreflightPrompt(input: PreflightInput): string;
+export declare function runPreflight(provider: IProvider, input: PreflightInput): Promise<PreflightSnapshot>;