wotann 0.5.0

package/dist/evals/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared types for the evals subsystem:
+ *   - G-Eval (LLM-as-judge with chain-of-thought)
+ *   - Ragas (Retrieval-Augmented Generation Assessment)
+ *   - OWASP LLM Top 10 red-team harness
+ *
+ * Design rules:
+ *   - Every metric + attack requires a caller-injected LLM; nothing is
+ *     hardcoded to Claude/GPT/Gemini.
+ *   - Scores are always in a defined range (usually [0, 1]); out-of-range
+ *     values are clamped defensively.
+ *   - We distinguish "ran" from "passed" — a metric can score a response
+ *     low (valid result) vs. failing to score at all (unavailable judge).
+ *   - Attack corpora are plain data, not executable — they are prompts the
+ *     red-team harness feeds to the target system.
+ */
+/**
+ * Minimal LLM contract the evals subsystem needs. Callers inject any
+ * provider that satisfies this interface.
+ */
+export interface EvalLlm {
+    readonly query: (prompt: string) => Promise<string>;
+    /** Optional name used for audit logs. */
+    readonly name?: string;
+}
+export type GEvalScoreScale = 1 | 3 | 5 | 10;
+export type GEvalAggregator = "mean" | "min" | "max" | "weighted";
+export interface GEvalCriterion {
+    readonly name: string;
+    readonly description: string;
+    /** Integer score scale: 1..scoreScale. */
+    readonly scoreScale: GEvalScoreScale;
+    /** Optional weight used only by "weighted" aggregator. Default 1. */
+    readonly weight?: number;
+    /**
+     * Optional bullet-list of what each score on the scale means. If
+     * present we inject it into the judge prompt for better calibration.
+     */
+    readonly rubric?: readonly string[];
+}
+export interface GEvalRubric {
+    readonly criteria: readonly GEvalCriterion[];
+    readonly aggregator: GEvalAggregator;
+}
+export interface GEvalCriterionScore {
+    readonly criterion: string;
+    /** Raw score in [1, scoreScale]. NaN when judge failed. */
+    readonly score: number;
+    /** Normalized score in [0, 1]. */
+    readonly normalized: number;
+    /** Chain-of-thought reasoning the judge produced (truncated for storage). */
+    readonly reasoning: string;
+    /** True if the judge abstained (returned NaN / unparseable / timeout). */
+    readonly abstained: boolean;
+}
+export interface GEvalResult {
+    readonly scores: readonly GEvalCriterionScore[];
+    /** Aggregate of normalized scores. NaN if every criterion abstained. */
+    readonly aggregate: number;
+    /** Number of criteria that abstained. */
+    readonly abstentions: number;
+    /** Number of LLM calls made. */
+    readonly callsMade: number;
+}
+/**
+ * A single Ragas test case. We don't care where the retrieval came from —
+ * the question, the retrieved contexts, and the generated answer are all
+ * supplied. The metric then evaluates the answer against those.
+ */
+export interface RagasSample {
+    readonly question: string;
+    /** Retrieved passages the system used to answer the question. */
+    readonly contexts: readonly string[];
+    /** The system's generated answer. */
+    readonly answer: string;
+    /**
+     * Optional ground-truth answer. Required by `answer_correctness` but
+     * optional for faithfulness + context_precision.
+     */
+    readonly groundTruth?: string;
+}
+export type RagasMetricName = "faithfulness" | "answer_relevancy" | "context_precision" | "context_recall";
+export interface RagasMetricResult {
+    readonly metric: RagasMetricName;
+    /** Score in [0, 1]. NaN if the metric couldn't run. */
+    readonly score: number;
+    /** Per-metric detail (useful for debugging / audit). */
+    readonly details: Readonly<Record<string, unknown>>;
+    readonly abstained: boolean;
+}
+export interface RagasReport {
+    readonly metrics: readonly RagasMetricResult[];
+    /** Mean of the ran metrics (ignores abstentions). NaN if all abstained. */
+    readonly aggregate: number;
+    readonly callsMade: number;
+}
+/**
+ * OWASP LLM Top 10 categories (2023 draft kept stable here). Each
+ * category ships with a small hand-curated corpus of attack payloads.
+ * The red-team harness iterates each payload through the target system
+ * and records whether the system "blocked" (safe) or "complied"
+ * (unsafe).
+ */
+export type OwaspLlmCategory = "LLM01_PROMPT_INJECTION" | "LLM02_INSECURE_OUTPUT_HANDLING" | "LLM03_TRAINING_DATA_POISONING" | "LLM04_MODEL_DOS" | "LLM05_SUPPLY_CHAIN" | "LLM06_SENSITIVE_INFORMATION_DISCLOSURE" | "LLM07_INSECURE_PLUGIN_DESIGN" | "LLM08_EXCESSIVE_AGENCY" | "LLM09_OVERRELIANCE" | "LLM10_MODEL_THEFT";
+export interface AttackCase {
+    readonly id: string;
+    readonly category: OwaspLlmCategory;
+    /** The payload that gets sent to the target system. */
+    readonly payload: string;
+    /**
+     * A short string the attack is trying to elicit. If the target's
+     * response contains this substring (case-insensitive) we consider
+     * the attack successful.
+     */
+    readonly winCondition: string;
+    /**
+     * Optional description shown in audit logs.
+     */
+    readonly description?: string;
+}
+export interface AttackRunResult {
+    readonly case: AttackCase;
+    /** Target system's response (possibly truncated). */
+    readonly response: string;
+    /** True when the attack succeeded (target complied unsafely). */
+    readonly succeeded: boolean;
+    /** True when the target system emitted an explicit refusal. */
+    readonly blocked: boolean;
+    /** Optional error if the target errored out. */
+    readonly errorMessage?: string;
+    /** Wall-clock ms. */
+    readonly durationMs: number;
+}
+export interface RedTeamReport {
+    readonly category: OwaspLlmCategory;
+    readonly results: readonly AttackRunResult[];
+    readonly totalCases: number;
+    readonly successfulAttacks: number;
+    readonly blockedAttacks: number;
+    readonly errors: number;
+    /** successfulAttacks / totalCases (in [0, 1]). Higher = worse for target. */
+    readonly attackSuccessRate: number;
+}
+/**
+ * Clamp a score to [lo, hi]. NaN passes through unchanged so callers
+ * can detect abstention.
+ */
+export declare function clampScore(score: number, lo?: number, hi?: number): number;
+/**
+ * Normalize a raw score on scale [1, scaleMax] to [0, 1]. scaleMax=1
+ * always yields 0.5 (single-level scales are degenerate).
+ */
+export declare function normalizeOnScale(score: number, scaleMax: GEvalScoreScale): number;
+//# sourceMappingURL=types.d.ts.map

package/dist/evals/types.d.ts.map

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

package/dist/evals/types.js

@@ -0,0 +1,43 @@
+/**
+ * Shared types for the evals subsystem:
+ *   - G-Eval (LLM-as-judge with chain-of-thought)
+ *   - Ragas (Retrieval-Augmented Generation Assessment)
+ *   - OWASP LLM Top 10 red-team harness
+ *
+ * Design rules:
+ *   - Every metric + attack requires a caller-injected LLM; nothing is
+ *     hardcoded to Claude/GPT/Gemini.
+ *   - Scores are always in a defined range (usually [0, 1]); out-of-range
+ *     values are clamped defensively.
+ *   - We distinguish "ran" from "passed" — a metric can score a response
+ *     low (valid result) vs. failing to score at all (unavailable judge).
+ *   - Attack corpora are plain data, not executable — they are prompts the
+ *     red-team harness feeds to the target system.
+ */
+// ── Utility helpers ────────────────────────────
+/**
+ * Clamp a score to [lo, hi]. NaN passes through unchanged so callers
+ * can detect abstention.
+ */
+export function clampScore(score, lo = 0, hi = 1) {
+    if (Number.isNaN(score))
+        return NaN;
+    if (score < lo)
+        return lo;
+    if (score > hi)
+        return hi;
+    return score;
+}
+/**
+ * Normalize a raw score on scale [1, scaleMax] to [0, 1]. scaleMax=1
+ * always yields 0.5 (single-level scales are degenerate).
+ */
+export function normalizeOnScale(score, scaleMax) {
+    if (Number.isNaN(score))
+        return NaN;
+    if (scaleMax === 1)
+        return 0.5;
+    const clamped = Math.max(1, Math.min(scaleMax, score));
+    return (clamped - 1) / (scaleMax - 1);
+}
+//# sourceMappingURL=types.js.map

package/dist/evals/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/evals/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAsKH,kDAAkD;AAElD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC;IACtD,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,EAAE,CAAC;IAC1B,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,EAAE,CAAC;IAC1B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,QAAyB;IACvE,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACpC,IAAI,QAAQ,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/evolution/constraints.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Constraint validators for evolved variants.
+ *
+ * Every variant must pass these gates before becoming eligible to
+ * replace its parent. Mirrors the "Guardrails" section of
+ * research/hermes-agent-self-evolution/PLAN.md but adapted for WOTANN's
+ * naming conventions and skill file shape.
+ */
+import { ConstraintReport, EvolveTarget } from "./types.js";
+export declare function validateConstraints(target: EvolveTarget, candidateContent: string): ConstraintReport;
+export declare function exposesSecret(content: string): boolean;
+//# sourceMappingURL=constraints.d.ts.map

package/dist/evolution/constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../../src/evolution/constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAO5D,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,gBAAgB,EAAE,MAAM,GACvB,gBAAgB,CAmClB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/evolution/constraints.js

@@ -0,0 +1,45 @@
+/**
+ * Constraint validators for evolved variants.
+ *
+ * Every variant must pass these gates before becoming eligible to
+ * replace its parent. Mirrors the "Guardrails" section of
+ * research/hermes-agent-self-evolution/PLAN.md but adapted for WOTANN's
+ * naming conventions and skill file shape.
+ */
+const MAX_SKILL_BYTES = 15_360; // 15 KB — matches hermes constraint
+const MAX_TOOL_DESC_BYTES = 500;
+const FORBIDDEN_TOKENS = ["TODO", "FIXME", "XXX", "<placeholder>"];
+export function validateConstraints(target, candidateContent) {
+    const violations = [];
+    // 1. Size limits
+    const sizeBytes = Buffer.byteLength(candidateContent, "utf8");
+    if (target.kind === "skill" && sizeBytes > MAX_SKILL_BYTES) {
+        violations.push(`Skill exceeds ${MAX_SKILL_BYTES}-byte cap (got ${sizeBytes})`);
+    }
+    if (target.kind === "tool-description" && sizeBytes > MAX_TOOL_DESC_BYTES) {
+        violations.push(`Tool description exceeds ${MAX_TOOL_DESC_BYTES}-byte cap (got ${sizeBytes})`);
+    }
+    // 2. Forbidden placeholder tokens
+    for (const tok of FORBIDDEN_TOKENS) {
+        if (candidateContent.includes(tok)) {
+            violations.push(`Contains forbidden token "${tok}"`);
+        }
+    }
+    // 3. Skill files must keep their YAML frontmatter intact
+    if (target.kind === "skill" && !candidateContent.startsWith("---")) {
+        violations.push("Skill file lost YAML frontmatter (must start with ---)");
+    }
+    // 4. No empty content
+    if (candidateContent.trim().length === 0) {
+        violations.push("Variant content is empty");
+    }
+    // 5. Skill files must keep a `name:` field in frontmatter
+    if (target.kind === "skill" && !/^name:\s*\S+/m.test(candidateContent)) {
+        violations.push("Skill file lost `name:` frontmatter field");
+    }
+    return { passed: violations.length === 0, violations };
+}
+export function exposesSecret(content) {
+    return /(?:sk-[A-Za-z0-9_-]{20,}|api[_-]?key\s*[:=]\s*["']?[A-Za-z0-9_-]{20,})/i.test(content);
+}
+//# sourceMappingURL=constraints.js.map

package/dist/evolution/constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.js","sourceRoot":"","sources":["../../src/evolution/constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,eAAe,GAAG,MAAM,CAAC,CAAC,oCAAoC;AACpE,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,MAAM,gBAAgB,GAA0B,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC;AAE1F,MAAM,UAAU,mBAAmB,CACjC,MAAoB,EACpB,gBAAwB;IAExB,MAAM,UAAU,GAAa,EAAE,CAAC;IAEhC,iBAAiB;IACjB,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,SAAS,GAAG,eAAe,EAAE,CAAC;QAC3D,UAAU,CAAC,IAAI,CAAC,iBAAiB,eAAe,kBAAkB,SAAS,GAAG,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,kBAAkB,IAAI,SAAS,GAAG,mBAAmB,EAAE,CAAC;QAC1E,UAAU,CAAC,IAAI,CAAC,4BAA4B,mBAAmB,kBAAkB,SAAS,GAAG,CAAC,CAAC;IACjG,CAAC;IAED,kCAAkC;IAClC,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,IAAI,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,UAAU,CAAC,IAAI,CAAC,6BAA6B,GAAG,GAAG,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,yDAAyD;IACzD,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACnE,UAAU,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IAC5E,CAAC;IAED,sBAAsB;IACtB,IAAI,gBAAgB,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,UAAU,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAED,0DAA0D;IAC1D,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACvE,UAAU,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,yEAAyE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACjG,CAAC"}

package/dist/evolution/evaluator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Evaluator — scores a variant against a small dataset.
+ *
+ * Scoring strategy:
+ *   - For each example, send the variant + input to the configured
+ *     provider and capture the response.
+ *   - Compute a similarity score against the expected outcome using
+ *     a simple token-overlap heuristic (Jaccard on sentence-cased
+ *     tokens). The heuristic intentionally does NOT call back into the
+ *     LLM as a judge — that would inflate cost and create circular
+ *     evaluation. For higher-fidelity eval, the user can swap in a
+ *     custom scorer at the CLI level.
+ *   - Aggregate scores across examples; weight by example priority
+ *     (defaults to 1.0).
+ *
+ * Cost & latency are tracked per-example so the optimizer can pick a
+ * variant that's better but not pareto-dominated by speed/cost.
+ */
+import { EvalResult, EvolveExample, Variant } from "./types.js";
+export interface ProviderInvocation {
+    readonly variantContent: string;
+    readonly input: string;
+}
+export interface ProviderResponse {
+    readonly text: string;
+    readonly costUsd: number;
+    readonly latencyMs: number;
+}
+export type EvaluationCaller = (inv: ProviderInvocation) => Promise<ProviderResponse>;
+export interface EvaluatorOptions {
+    readonly caller: EvaluationCaller;
+    readonly examples: ReadonlyArray<EvolveExample>;
+    readonly variant: Variant;
+    readonly weight?: (exampleId: string) => number;
+}
+export declare function evaluateVariant(opts: EvaluatorOptions): Promise<{
+    readonly results: ReadonlyArray<EvalResult>;
+    readonly aggregate: {
+        readonly score: number;
+        readonly cost: number;
+    };
+}>;
+export declare function tokenize(s: string): ReadonlyArray<string>;
+export declare function jaccardScore(predicted: string, expected: string): number;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/evolution/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/evolution/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;CACjD;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC;IACrE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE,CAAC,CA+CD;AA2BD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAMzD;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQxE"}

package/dist/evolution/evaluator.js

@@ -0,0 +1,109 @@
+/**
+ * Evaluator — scores a variant against a small dataset.
+ *
+ * Scoring strategy:
+ *   - For each example, send the variant + input to the configured
+ *     provider and capture the response.
+ *   - Compute a similarity score against the expected outcome using
+ *     a simple token-overlap heuristic (Jaccard on sentence-cased
+ *     tokens). The heuristic intentionally does NOT call back into the
+ *     LLM as a judge — that would inflate cost and create circular
+ *     evaluation. For higher-fidelity eval, the user can swap in a
+ *     custom scorer at the CLI level.
+ *   - Aggregate scores across examples; weight by example priority
+ *     (defaults to 1.0).
+ *
+ * Cost & latency are tracked per-example so the optimizer can pick a
+ * variant that's better but not pareto-dominated by speed/cost.
+ */
+export async function evaluateVariant(opts) {
+    const results = [];
+    let totalCost = 0;
+    let weightedScore = 0;
+    let totalWeight = 0;
+    for (const example of opts.examples) {
+        const w = opts.weight ? opts.weight(example.id) : 1;
+        const t0 = Date.now();
+        let response;
+        try {
+            response = await opts.caller({
+                variantContent: opts.variant.content,
+                input: example.input,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({
+                exampleId: example.id,
+                variantId: opts.variant.id,
+                score: 0,
+                cost: 0,
+                latencyMs: Date.now() - t0,
+                notes: `caller threw: ${message}`,
+            });
+            totalWeight += w;
+            continue;
+        }
+        const score = jaccardScore(response.text, example.expectedOutcome);
+        results.push({
+            exampleId: example.id,
+            variantId: opts.variant.id,
+            score,
+            cost: response.costUsd,
+            latencyMs: response.latencyMs,
+            notes: "",
+        });
+        totalCost += response.costUsd;
+        weightedScore += score * w;
+        totalWeight += w;
+    }
+    const aggregate = {
+        score: totalWeight > 0 ? weightedScore / totalWeight : 0,
+        cost: totalCost,
+    };
+    return { results, aggregate };
+}
+const STOP = new Set([
+    "the",
+    "a",
+    "an",
+    "is",
+    "are",
+    "was",
+    "were",
+    "and",
+    "or",
+    "of",
+    "to",
+    "in",
+    "for",
+    "on",
+    "with",
+    "this",
+    "that",
+    "be",
+    "by",
+    "as",
+    "at",
+    "it",
+]);
+export function tokenize(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 1 && !STOP.has(t));
+}
+export function jaccardScore(predicted, expected) {
+    const a = new Set(tokenize(predicted));
+    const b = new Set(tokenize(expected));
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersect = 0;
+    for (const t of a)
+        if (b.has(t))
+            intersect++;
+    const union = a.size + b.size - intersect;
+    return union === 0 ? 0 : intersect / union;
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/evolution/evaluator.js.map

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

package/dist/evolution/mutator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Mutator — generates candidate variants from a baseline.
+ *
+ * Two strategies:
+ *
+ *   "reflective" — read recent execution traces (failure modes,
+ *   recurring corrections, abandoned tool sequences) and propose a
+ *   targeted edit to the baseline that addresses one specific failure
+ *   pattern. This is the GEPA-style mutation strategy.
+ *
+ *   "random" — generate variants by tweaking formatting or rephrasing
+ *   without consulting traces. Used as a fallback when there are
+ *   fewer than 3 trace examples to ground reflection in.
+ *
+ * The mutator does NOT call the LLM directly — it returns a list of
+ * MutationProposal objects that the optimizer turns into candidates by
+ * dispatching to whichever provider is configured. This keeps the
+ * mutator unit-testable without mocking provider clients.
+ */
+import { Variant, MutationContext, EvolveTarget } from "./types.js";
+export interface MutationProposal {
+    readonly id: string;
+    readonly diffHint: string;
+    readonly rationale: string;
+}
+export declare function proposeMutations(ctx: MutationContext, count: number): ReadonlyArray<MutationProposal>;
+export declare function buildMutationPrompt(baseline: string, proposal: MutationProposal, target: EvolveTarget): string;
+/**
+ * Pure-function variant assembler used in tests. Takes a baseline +
+ * the LLM's proposed text and produces a Variant struct.
+ */
+export declare function assembleVariant(args: {
+    parentId: string | null;
+    generation: number;
+    proposal: MutationProposal;
+    llmOutput: string;
+}): Variant;
+//# sourceMappingURL=mutator.d.ts.map

package/dist/evolution/mutator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutator.d.ts","sourceRoot":"","sources":["../../src/evolution/mutator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,MAAM,GACZ,aAAa,CAAC,gBAAgB,CAAC,CAyCjC;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,YAAY,GACnB,MAAM,CAwBR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAQV"}

package/dist/evolution/mutator.js

@@ -0,0 +1,97 @@
+/**
+ * Mutator — generates candidate variants from a baseline.
+ *
+ * Two strategies:
+ *
+ *   "reflective" — read recent execution traces (failure modes,
+ *   recurring corrections, abandoned tool sequences) and propose a
+ *   targeted edit to the baseline that addresses one specific failure
+ *   pattern. This is the GEPA-style mutation strategy.
+ *
+ *   "random" — generate variants by tweaking formatting or rephrasing
+ *   without consulting traces. Used as a fallback when there are
+ *   fewer than 3 trace examples to ground reflection in.
+ *
+ * The mutator does NOT call the LLM directly — it returns a list of
+ * MutationProposal objects that the optimizer turns into candidates by
+ * dispatching to whichever provider is configured. This keeps the
+ * mutator unit-testable without mocking provider clients.
+ */
+export function proposeMutations(ctx, count) {
+    const proposals = [];
+    const seedRoot = `mut-${Date.now().toString(36)}`;
+    if (ctx.strategy === "reflective" && ctx.recentFailures.length > 0) {
+        for (let i = 0; i < count; i++) {
+            const failure = ctx.recentFailures[i % ctx.recentFailures.length] ?? "(unknown failure)";
+            proposals.push({
+                id: `${seedRoot}-r${i}`,
+                diffHint: `Address recurring failure: ${failure.slice(0, 200)}`,
+                rationale: failure,
+            });
+        }
+        return proposals;
+    }
+    // Random strategy: generic tweaks
+    const tweaks = [
+        ["clarify-purpose", "Make the skill's first paragraph more specific about WHEN to use it"],
+        ["add-counter-example", "Add a 'do NOT use when' counter-example to the description"],
+        ["tighten-steps", "Tighten step descriptions — remove filler words, lead with verbs"],
+        ["concrete-example", "Replace one abstract directive with a concrete code-style example"],
+        ["explicit-stops", "Add explicit STOP markers where the agent should pause for the user"],
+        ["error-path", "Document one common failure path and how to recover"],
+        [
+            "preconditions",
+            "Add a 'preconditions checked' section listing what must be true before running",
+        ],
+        ["invariants", "Document one invariant that must hold across the skill's operations"],
+    ];
+    for (let i = 0; i < count; i++) {
+        const tweak = tweaks[i % tweaks.length];
+        if (!tweak)
+            continue;
+        const [hint, rationale] = tweak;
+        proposals.push({
+            id: `${seedRoot}-t${i}`,
+            diffHint: hint,
+            rationale,
+        });
+    }
+    return proposals;
+}
+export function buildMutationPrompt(baseline, proposal, target) {
+    const targetDesc = target.kind === "skill"
+        ? `skill file "${target.name}" at ${target.path}`
+        : target.kind === "prompt-section"
+            ? `prompt section "${target.section}" in ${target.path}`
+            : `tool description for "${target.toolName}"`;
+    return [
+        `You are evolving a ${targetDesc}. The current version is shown between <BASELINE> tags.`,
+        "",
+        `Apply this targeted improvement: ${proposal.diffHint}`,
+        `Rationale: ${proposal.rationale}`,
+        "",
+        "Constraints:",
+        "- Preserve the file's overall structure (frontmatter, headers).",
+        "- Only output the FULL updated content, no commentary.",
+        "- Do not introduce TODO/FIXME placeholders.",
+        "- Stay under 15,000 bytes for skill files.",
+        "",
+        "<BASELINE>",
+        baseline,
+        "</BASELINE>",
+    ].join("\n");
+}
+/**
+ * Pure-function variant assembler used in tests. Takes a baseline +
+ * the LLM's proposed text and produces a Variant struct.
+ */
+export function assembleVariant(args) {
+    return {
+        id: args.proposal.id,
+        content: args.llmOutput.trim(),
+        parentId: args.parentId,
+        generation: args.generation,
+        mutationReasoning: args.proposal.rationale,
+    };
+}
+//# sourceMappingURL=mutator.js.map

package/dist/evolution/mutator.js.map

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

package/dist/evolution/optimizer.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Optimizer — runs the evolutionary loop:
+ *
+ *   1. Score the baseline against the eval set.
+ *   2. For each generation:
+ *      a. propose N mutations
+ *      b. apply each mutation by calling the mutate caller (LLM)
+ *      c. validate constraints (size, no-TODO, secret-free)
+ *      d. evaluate each surviving variant
+ *      e. select the top-K survivors via Pareto front
+ *   3. Return the OptimizeRunSummary with the winner.
+ *
+ * The optimizer is fully orthogonal to the WOTANN provider stack: the
+ * caller passes in `mutate` and `evaluate` callables, so tests can use
+ * deterministic fakes.
+ */
+import { EvaluationCaller } from "./evaluator.js";
+import { EvolveExample, EvolveTarget, MutationStrategy, OptimizeRunSummary } from "./types.js";
+export interface MutationCaller {
+    (prompt: string): Promise<{
+        readonly text: string;
+        readonly costUsd: number;
+    }>;
+}
+export interface OptimizerOptions {
+    readonly target: EvolveTarget;
+    readonly baseline: string;
+    readonly examples: ReadonlyArray<EvolveExample>;
+    readonly mutate: MutationCaller;
+    readonly evaluate: EvaluationCaller;
+    readonly generations?: number;
+    readonly variantsPerGeneration?: number;
+    readonly survivorsPerGeneration?: number;
+    readonly strategy?: MutationStrategy;
+    readonly recentFailures?: ReadonlyArray<string>;
+    readonly maxBudgetUsd?: number;
+    readonly onProgress?: (event: ProgressEvent) => void;
+}
+export type ProgressEvent = {
+    readonly type: "baseline-scored";
+    readonly score: number;
+} | {
+    readonly type: "generation-start";
+    readonly generation: number;
+} | {
+    readonly type: "variant-evaluated";
+    readonly generation: number;
+    readonly variantId: string;
+    readonly score: number;
+    readonly cost: number;
+} | {
+    readonly type: "variant-rejected";
+    readonly variantId: string;
+    readonly violations: ReadonlyArray<string>;
+} | {
+    readonly type: "budget-exhausted";
+    readonly spent: number;
+};
+export declare function runOptimization(opts: OptimizerOptions): Promise<OptimizeRunSummary>;
+/**
+ * Test helper: a deterministic mutation caller that just returns the
+ * baseline with the proposal's diffHint appended. Useful for unit
+ * tests that don't want to mock a real provider.
+ */
+export declare function makeStubMutator(): MutationCaller;
+/** Test helper: deterministic evaluator that scores against expected via Jaccard on the raw input. */
+export declare function makeStubEvaluator(): EvaluationCaller;
+//# sourceMappingURL=optimizer.d.ts.map