wotann 0.5.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../src/evolution/optimizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,EAAmB,gBAAgB,EAAoB,MAAM,gBAAgB,CAAC;AACrF,OAAO,EACL,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CACtD;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClE;IACE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC5C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAMlE,wBAAsB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0IzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,cAAc,CAOhD;AAED,sGAAsG;AACtG,wBAAgB,iBAAiB,IAAI,gBAAgB,CAMpD"}

package/dist/evolution/optimizer.js

@@ -0,0 +1,170 @@
+/**
+ * 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 { proposeMutations, buildMutationPrompt, assembleVariant, } from "./mutator.js";
+import { validateConstraints, exposesSecret } from "./constraints.js";
+import { evaluateVariant } from "./evaluator.js";
+const DEFAULT_GENERATIONS = 3;
+const DEFAULT_VARIANTS = 4;
+const DEFAULT_SURVIVORS = 2;
+export async function runOptimization(opts) {
+    const generations = opts.generations ?? DEFAULT_GENERATIONS;
+    const variantsPerGen = opts.variantsPerGeneration ?? DEFAULT_VARIANTS;
+    const survivors = opts.survivorsPerGeneration ?? DEFAULT_SURVIVORS;
+    const budget = opts.maxBudgetUsd ?? 10;
+    const notes = [];
+    // 1. Score baseline.
+    const baselineVariant = {
+        id: "baseline",
+        content: opts.baseline,
+        parentId: null,
+        generation: 0,
+        mutationReasoning: "(baseline)",
+    };
+    const baselineEval = await evaluateVariant({
+        caller: opts.evaluate,
+        examples: opts.examples,
+        variant: baselineVariant,
+    });
+    let totalCost = baselineEval.aggregate.cost;
+    const scoredBaseline = { ...baselineVariant, score: baselineEval.aggregate.score };
+    opts.onProgress?.({ type: "baseline-scored", score: scoredBaseline.score ?? 0 });
+    let parents = [scoredBaseline];
+    let bestSoFar = scoredBaseline;
+    // 2. Generations.
+    for (let g = 1; g <= generations; g++) {
+        if (totalCost >= budget) {
+            notes.push(`Budget ($${budget}) exhausted before generation ${g}.`);
+            opts.onProgress?.({ type: "budget-exhausted", spent: totalCost });
+            break;
+        }
+        opts.onProgress?.({ type: "generation-start", generation: g });
+        const proposals = [];
+        for (const parent of parents) {
+            proposals.push(...proposeMutations({
+                target: opts.target,
+                traceExcerpts: [],
+                recentFailures: opts.recentFailures ?? [],
+                currentScore: parent.score ?? 0,
+                strategy: opts.strategy ?? "random",
+                maxLength: 15_000,
+            }, variantsPerGen));
+        }
+        const generationVariants = [];
+        for (const proposal of proposals) {
+            if (totalCost >= budget)
+                break;
+            const parent = parents[0] ?? scoredBaseline;
+            const prompt = buildMutationPrompt(parent.content, proposal, opts.target);
+            let mutated;
+            try {
+                mutated = await opts.mutate(prompt);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                notes.push(`Mutation call failed for ${proposal.id}: ${msg}`);
+                continue;
+            }
+            totalCost += mutated.costUsd;
+            const variant = assembleVariant({
+                parentId: parent.id,
+                generation: g,
+                proposal,
+                llmOutput: mutated.text,
+            });
+            const constraints = validateConstraints(opts.target, variant.content);
+            if (!constraints.passed) {
+                opts.onProgress?.({
+                    type: "variant-rejected",
+                    variantId: variant.id,
+                    violations: constraints.violations,
+                });
+                continue;
+            }
+            if (exposesSecret(variant.content)) {
+                opts.onProgress?.({
+                    type: "variant-rejected",
+                    variantId: variant.id,
+                    violations: ["Variant appears to contain a secret-like token"],
+                });
+                continue;
+            }
+            const evalRes = await evaluateVariant({
+                caller: opts.evaluate,
+                examples: opts.examples,
+                variant,
+            });
+            totalCost += evalRes.aggregate.cost;
+            const scored = { ...variant, score: evalRes.aggregate.score };
+            opts.onProgress?.({
+                type: "variant-evaluated",
+                generation: g,
+                variantId: scored.id,
+                score: scored.score ?? 0,
+                cost: evalRes.aggregate.cost,
+            });
+            generationVariants.push(scored);
+            if ((scored.score ?? 0) > (bestSoFar.score ?? 0)) {
+                bestSoFar = scored;
+            }
+        }
+        if (generationVariants.length === 0) {
+            notes.push(`Generation ${g}: no surviving variants.`);
+            continue;
+        }
+        parents = generationVariants
+            .slice()
+            .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+            .slice(0, survivors);
+    }
+    const baselineScore = scoredBaseline.score ?? 0;
+    const bestScore = bestSoFar.score ?? 0;
+    const improvementPct = baselineScore > 0 ? ((bestScore - baselineScore) / baselineScore) * 100 : 0;
+    return {
+        target: opts.target,
+        baselineScore,
+        bestScore,
+        bestVariantId: bestSoFar.id,
+        generations,
+        totalVariants: 1, // baseline counted; per-generation count is implicit in notes/onProgress
+        totalCostUsd: totalCost,
+        winnerContent: bestSoFar.content,
+        improvementPct,
+        notes,
+    };
+}
+/**
+ * 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 function makeStubMutator() {
+    return async (prompt) => {
+        // Extract <BASELINE>..</BASELINE>
+        const match = prompt.match(/<BASELINE>([\s\S]*?)<\/BASELINE>/);
+        const baseline = match?.[1] ?? "";
+        return { text: baseline + "\n\n[mutated stub]", costUsd: 0 };
+    };
+}
+/** Test helper: deterministic evaluator that scores against expected via Jaccard on the raw input. */
+export function makeStubEvaluator() {
+    return async ({ input }) => ({
+        text: input + " ok",
+        costUsd: 0,
+        latencyMs: 1,
+    });
+}
+//# sourceMappingURL=optimizer.js.map

package/dist/evolution/optimizer.js.map

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

package/dist/evolution/runner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Runner — high-level facade that wires the optimizer to the configured
+ * provider and the project's skill files / trace history.
+ *
+ * Most users invoke evolution via `wotann evolve <skill>`. The CLI
+ * imports this module and calls `evolveSkill()`. We keep this layer
+ * thin so the CLI's UX changes (table formatting, progress bars,
+ * confirmation prompts) don't churn the optimizer.
+ */
+import { MutationCaller } from "./optimizer.js";
+import { EvaluationCaller } from "./evaluator.js";
+import { EvolveExample, OptimizeRunSummary } from "./types.js";
+export interface EvolveSkillArgs {
+    readonly skillPath: string;
+    readonly examples: ReadonlyArray<EvolveExample>;
+    readonly mutate: MutationCaller;
+    readonly evaluate: EvaluationCaller;
+    readonly recentFailures?: ReadonlyArray<string>;
+    readonly write?: boolean;
+    readonly generations?: number;
+}
+export declare function evolveSkill(args: EvolveSkillArgs): Promise<OptimizeRunSummary>;
+/**
+ * Build a synthetic evaluation set from a skill's frontmatter
+ * description + triggers. Used when the user passes `--eval-source
+ * synthetic`. Real-data eval comes from session DB queries; this is
+ * the day-1 fallback so `wotann evolve` works on a fresh install.
+ */
+export declare function buildSyntheticExamples(skillContent: string): ReadonlyArray<EvolveExample>;
+//# sourceMappingURL=runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/evolution/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAmB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuBpF;AAOD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CAAC,aAAa,CAAC,CAuBzF"}

package/dist/evolution/runner.js

@@ -0,0 +1,67 @@
+/**
+ * Runner — high-level facade that wires the optimizer to the configured
+ * provider and the project's skill files / trace history.
+ *
+ * Most users invoke evolution via `wotann evolve <skill>`. The CLI
+ * imports this module and calls `evolveSkill()`. We keep this layer
+ * thin so the CLI's UX changes (table formatting, progress bars,
+ * confirmation prompts) don't churn the optimizer.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolveWotannHomeSubdir } from "../utils/wotann-home.js";
+import { runOptimization } from "./optimizer.js";
+export async function evolveSkill(args) {
+    const baseline = readFileSync(args.skillPath, "utf8");
+    const skillName = extractSkillName(baseline) ?? args.skillPath;
+    const summary = await runOptimization({
+        target: { kind: "skill", path: args.skillPath, name: skillName },
+        baseline,
+        examples: args.examples,
+        mutate: args.mutate,
+        evaluate: args.evaluate,
+        recentFailures: args.recentFailures ?? [],
+        strategy: args.recentFailures && args.recentFailures.length > 0 ? "reflective" : "random",
+        generations: args.generations,
+    });
+    if (args.write && summary.bestScore > summary.baselineScore) {
+        const archive = resolveWotannHomeSubdir("evolution-archive");
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const archiveName = `${stamp}-${skillName}.md`;
+        writeFileSync(`${archive}/${archiveName}`, baseline, { encoding: "utf8", mode: 0o600 });
+        writeFileSync(args.skillPath, summary.winnerContent, "utf8");
+    }
+    return summary;
+}
+function extractSkillName(content) {
+    const match = content.match(/^name:\s*(\S.*)$/m);
+    return match?.[1]?.trim() ?? null;
+}
+/**
+ * Build a synthetic evaluation set from a skill's frontmatter
+ * description + triggers. Used when the user passes `--eval-source
+ * synthetic`. Real-data eval comes from session DB queries; this is
+ * the day-1 fallback so `wotann evolve` works on a fresh install.
+ */
+export function buildSyntheticExamples(skillContent) {
+    const triggerLine = skillContent.match(/^triggers:\s*$([\s\S]*?)(?:^---|^[a-zA-Z])/m)?.[1] ?? "";
+    const triggers = triggerLine
+        .split("\n")
+        .map((l) => l.replace(/^\s*-\s*/, "").trim())
+        .filter((l) => l.length > 0);
+    const description = skillContent.match(/^description:\s*(.+?)(?:\n[a-zA-Z])/ms)?.[1]?.trim() ?? "";
+    if (triggers.length === 0) {
+        return [
+            {
+                id: "synthetic-1",
+                input: description.slice(0, 200),
+                expectedOutcome: "Skill applied successfully without violations.",
+            },
+        ];
+    }
+    return triggers.slice(0, 5).map((t, i) => ({
+        id: `synthetic-${i}`,
+        input: t,
+        expectedOutcome: description.slice(0, 200),
+    }));
+}
+//# sourceMappingURL=runner.js.map

package/dist/evolution/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/evolution/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAkB,MAAM,gBAAgB,CAAC;AAcjE,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAqB;IACrD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,gBAAgB,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC;IAC/D,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC;QACpC,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;QAChE,QAAQ;QACR,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,EAAE;QACzC,QAAQ,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ;QACzF,WAAW,EAAE,IAAI,CAAC,WAAW;KAC9B,CAAC,CAAC;IAEH,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;QAC5D,MAAM,OAAO,GAAG,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAC7D,MAAM,WAAW,GAAG,GAAG,KAAK,IAAI,SAAS,KAAK,CAAC;QAC/C,aAAa,CAAC,GAAG,OAAO,IAAI,WAAW,EAAE,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACxF,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACjD,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAAoB;IACzD,MAAM,WAAW,GAAG,YAAY,CAAC,KAAK,CAAC,6CAA6C,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjG,MAAM,QAAQ,GAAG,WAAW;SACzB,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SAC5C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,MAAM,WAAW,GACf,YAAY,CAAC,KAAK,CAAC,uCAAuC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAEjF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL;gBACE,EAAE,EAAE,aAAa;gBACjB,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;gBAChC,eAAe,EAAE,gDAAgD;aAClE;SACF,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACzC,EAAE,EAAE,aAAa,CAAC,EAAE;QACpB,KAAK,EAAE,CAAC;QACR,eAAe,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;KAC3C,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/evolution/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Type definitions for the WOTANN evolution pipeline (hermes-self-evolution port).
+ *
+ * Why a separate file: the optimizer, mutator, evaluator, and CLI all
+ * share these types but have orthogonal responsibilities. Keeping the
+ * type surface here avoids circular imports.
+ */
+export type EvolveTarget = {
+    readonly kind: "skill";
+    readonly path: string;
+    readonly name: string;
+} | {
+    readonly kind: "prompt-section";
+    readonly path: string;
+    readonly section: string;
+} | {
+    readonly kind: "tool-description";
+    readonly toolName: string;
+    readonly current: string;
+};
+export interface EvolveExample {
+    readonly id: string;
+    readonly input: string;
+    readonly expectedOutcome: string;
+    /** Optional ground truth — e.g. a list of tool calls the agent should produce. */
+    readonly expectedActions?: ReadonlyArray<string>;
+}
+export interface EvalResult {
+    readonly exampleId: string;
+    readonly variantId: string;
+    readonly score: number;
+    readonly cost: number;
+    readonly latencyMs: number;
+    readonly notes: string;
+}
+export interface Variant {
+    readonly id: string;
+    readonly content: string;
+    readonly parentId: string | null;
+    readonly generation: number;
+    readonly mutationReasoning: string;
+    readonly score?: number;
+}
+export interface OptimizeRunSummary {
+    readonly target: EvolveTarget;
+    readonly baselineScore: number;
+    readonly bestScore: number;
+    readonly bestVariantId: string;
+    readonly generations: number;
+    readonly totalVariants: number;
+    readonly totalCostUsd: number;
+    readonly winnerContent: string;
+    readonly improvementPct: number;
+    readonly notes: ReadonlyArray<string>;
+}
+/**
+ * Mutation strategy. The "reflective" strategy reads execution traces
+ * from prior runs and proposes targeted edits ("the last failure was
+ * because step 3 was unclear — rewrite it to ..."). The "random"
+ * strategy is a fallback that tweaks formatting / phrasing without
+ * trace context — used when there's no trace history yet.
+ */
+export type MutationStrategy = "reflective" | "random";
+export interface MutationContext {
+    readonly target: EvolveTarget;
+    readonly traceExcerpts: ReadonlyArray<string>;
+    readonly recentFailures: ReadonlyArray<string>;
+    readonly currentScore: number;
+    readonly strategy: MutationStrategy;
+    readonly maxLength: number;
+}
+export interface ConstraintReport {
+    readonly passed: boolean;
+    readonly violations: ReadonlyArray<string>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/evolution/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpF;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,kFAAkF;IAClF,QAAQ,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC5C"}

package/dist/evolution/types.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for the WOTANN evolution pipeline (hermes-self-evolution port).
+ *
+ * Why a separate file: the optimizer, mutator, evaluator, and CLI all
+ * share these types but have orthogonal responsibilities. Keeping the
+ * type surface here avoids circular imports.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/evolution/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/evolution/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/exploit/mythos-scaffold.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Mythos Scaffold — Claude Mythos 4-step exploit-research pattern.
+ *
+ * FROM CLAUDE MYTHOS (Anthropic, Project Glasswing consortium, 2026-04-07):
+ *   Mythos scored 181/181 on Firefox JS exploit generation (Opus 4.6 scored
+ *   2 over several hundred attempts) by running each security task through a
+ *   strict 4-phase scaffold. The scaffold prevents the common failure mode of
+ *   "plausible-sounding solution without verification" on CTF/security tasks.
+ *
+ * SOURCE (WOTANN research docs):
+ *   docs/internal/RESEARCH_CLOSED_SOURCE_COMPETITORS_DEEP.md §4.4
+ *   docs/internal/RESEARCH_USER_NAMED_COMPETITORS.md §2.4
+ *
+ * THE FOUR PHASES (linear, not parallel):
+ *   1. HYPOTHESIS   — Model reads code, forms explicit claim about a
+ *      potential vulnerability or failure mode.
+ *   2. CONFIRM      — Gather evidence (inspect code, trace data flow, read
+ *      output) that validates the hypothesis.
+ *   3. EXPLOIT      — Construct a minimal reproduction / PoC that
+ *      demonstrates the flaw.
+ *   4. VALIDATE     — Verify the exploit triggers the expected failure mode
+ *      and document impact (ideally with a fresh-context second pass).
+ *
+ * DESIGN (matches P1-B4 PreCompletionVerifier):
+ *   - Provider-agnostic via injected LlmQuery (same shape as CoVe & B4).
+ *   - Per-session state only: construct a new instance per task; no
+ *     module-global accumulation (QB #7).
+ *   - Honest failures (QB #6): a FailedPhase carries a reason object, we do
+ *     NOT silently pass through.
+ *   - Linear progression: if phase N fails, phases N+1..4 are not reached;
+ *     the agent is asked to reformulate phase N.
+ *   - `run(taskSpec)` returns a MythosReport with one PhaseArtifact per
+ *     phase that actually ran.
+ *   - Reformulation API: `retryPhase()` lets the caller re-run just the
+ *     failed phase with a revised input, preserving earlier artifacts.
+ *
+ * RELATIONSHIP TO EXISTING CODE:
+ *   - pre-completion-verifier.ts (P1-B4) runs a 4-perspective LLM review in
+ *     PARALLEL on a completed task — generic pre-completion check.
+ *   - THIS FILE runs a 4-phase LINEAR scaffold for SECURITY RESEARCH tasks.
+ *     Different failure mode, different domain. They coexist.
+ *
+ * NOT WIRED INTO RUNTIME BY THIS TASK (per allow-list): a consumer will
+ * construct `new MythosScaffold({llmQuery: runtimeQuery})` and call `.run()`.
+ */
+/**
+ * Provider-agnostic LLM call shape. Matches pre-completion-verifier.ts and
+ * chain-of-verification.ts so callers can reuse the same binding.
+ */
+export type LlmQuery = (prompt: string, options?: {
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+}) => Promise<string>;
+/** The four phases, in fixed execution order. */
+export declare const MYTHOS_PHASES: readonly ["hypothesis", "confirm", "exploit", "validate"];
+export type MythosPhase = (typeof MYTHOS_PHASES)[number];
+/**
+ * A structured failure reason for a phase that did not pass. Carries the
+ * honest reason so the caller can build a reformulation request. Never an
+ * empty object — at minimum `.kind` is populated.
+ */
+export interface FailedPhaseReason {
+    /** Category of failure. */
+    readonly kind: "verdict_fail" | "parse_failure" | "provider_error" | "empty_response";
+    /** Short human-readable description. */
+    readonly message: string;
+    /** Optional detail — e.g. parser exception message or raw provider error. */
+    readonly detail?: string;
+}
+/**
+ * Structured failure artifact for the exploit phase specifically. Surfaced
+ * as `FailedExploit` per the task spec so callers can pattern-match on it.
+ */
+export interface FailedExploit {
+    readonly phase: "exploit";
+    readonly reason: FailedPhaseReason;
+    /** What evidence was required but missing (e.g. "no PoC code block"). */
+    readonly missing: readonly string[];
+    /** Raw provider response so callers can diagnose. */
+    readonly raw: string;
+}
+/**
+ * Artifact for a phase that actually ran. Preserves the evidence and the
+ * verdict so later phases and the final report can reference it.
+ */
+export interface PhaseArtifact {
+    readonly phase: MythosPhase;
+    /** Phase outcome. */
+    readonly status: "pass" | "fail";
+    /**
+     * The structured content the phase produced:
+     *   - hypothesis: the vulnerability claim
+     *   - confirm:    the evidence validating the hypothesis
+     *   - exploit:    the PoC / reproduction steps
+     *   - validate:   the impact assessment
+     */
+    readonly content: string;
+    /** Raw provider response (trimmed). Useful for diagnostics. */
+    readonly raw: string;
+    /** Populated when status === "fail". */
+    readonly reason?: FailedPhaseReason;
+    /** Elapsed ms for this phase. */
+    readonly durationMs: number;
+}
+/** The final Mythos report covering all phases that ran. */
+export interface MythosReport {
+    /**
+     * Overall verdict. "pass" iff all 4 phases passed. "fail" when any phase
+     * failed (progression halted at that phase).
+     */
+    readonly status: "pass" | "fail";
+    /**
+     * Phase artifacts in execution order. Length <= 4. A failed phase is the
+     * last entry; later phases were not reached.
+     */
+    readonly phases: readonly PhaseArtifact[];
+    /**
+     * Convenience getters — undefined for phases that did not run.
+     */
+    readonly hypothesis?: PhaseArtifact;
+    readonly confirmation?: PhaseArtifact;
+    readonly exploit?: PhaseArtifact;
+    readonly validation?: PhaseArtifact;
+    /** Total wall-clock ms across all phases that ran. */
+    readonly totalDurationMs: number;
+    /**
+     * The phase that halted progression, if any. Undefined on full pass.
+     * Caller should re-run this phase via `retryPhase()` after reformulation.
+     */
+    readonly haltedAt?: MythosPhase;
+}
+/** Input describing the security-research task the scaffold operates on. */
+export interface TaskSpec {
+    /** Plain-English statement of what we're investigating. Required. */
+    readonly task: string;
+    /**
+     * Target artefact under investigation — source file, binary, repo path,
+     * URL, etc. Typically pasted into phase-1 prompt. Optional.
+     */
+    readonly target?: string;
+    /**
+     * Optional prior context (CVE notes, prior exploit attempts, sandbox
+     * transcript, etc.) available to every phase.
+     */
+    readonly context?: string;
+}
+/** Per-instance configuration. Matches P1-B4's PreCompletionVerifierConfig. */
+export interface MythosScaffoldConfig {
+    /** Injected LLM query function. Required. */
+    readonly llmQuery: LlmQuery;
+    /**
+     * When true, `run()` short-circuits into a bypass report (useful for
+     * benchmark runs where the scaffold should be measured in isolation).
+     */
+    readonly skipMythosScaffold?: boolean;
+    /** Temperature for the phase calls. Default 0 for deterministic output. */
+    readonly temperature?: number;
+    /** Max tokens per phase response. Default 1536 (exploits can be longer). */
+    readonly maxTokens?: number;
+}
+interface ParsedPhase {
+    readonly verdict: "pass" | "fail";
+    readonly content: string;
+    readonly missing: readonly string[];
+}
+/**
+ * Parse a phase response into a structured verdict. Strategy mirrors
+ * pre-completion-verifier: first try JSON, then regex fallback, then throw
+ * so the caller honestly reports a parse failure.
+ *
+ * Exported for tests.
+ */
+export declare function parsePhaseResponse(raw: string): ParsedPhase;
+/**
+ * MythosScaffold — runs a 4-phase linear exploit-research scaffold.
+ *
+ * Per-session state only. Construct a new instance per task. Carries no
+ * cross-session accumulation.
+ */
+export declare class MythosScaffold {
+    private readonly llmQuery;
+    private readonly bypass;
+    private readonly temperature;
+    private readonly maxTokens;
+    /** Per-instance diagnostic counter. */
+    private runCount;
+    constructor(config: MythosScaffoldConfig);
+    /**
+     * Run all 4 phases linearly against the task spec. Halts at the first
+     * failed phase and returns a report with phases up to (and including)
+     * the failure.
+     */
+    run(spec: TaskSpec): Promise<MythosReport>;
+    /**
+     * Re-run a single phase (typically the one that halted progression) with
+     * a revised task spec (reformulation). Preserves `priorArtifacts` — the
+     * phases that already passed — and appends the re-run result.
+     *
+     * Returns a MythosReport reflecting the updated state. If the re-run
+     * passes, the caller may chain further phases by calling `continueFrom()`.
+     */
+    retryPhase(phase: MythosPhase, spec: TaskSpec, priorArtifacts: readonly PhaseArtifact[]): Promise<MythosReport>;
+    /**
+     * Continue from an existing set of passing artifacts, running any phases
+     * that have not yet executed. Used after a successful `retryPhase()` to
+     * finish the chain.
+     */
+    continueFrom(spec: TaskSpec, priorArtifacts: readonly PhaseArtifact[]): Promise<MythosReport>;
+    /** Diagnostic: how many phase executions this instance has run. */
+    getRunCount(): number;
+    /** Whether this instance was constructed with bypass mode. */
+    isBypassed(): boolean;
+    private runPhase;
+    private assembleReport;
+    private buildBypassReport;
+}
+/**
+ * Narrow a failed PhaseArtifact for the `exploit` phase into the structured
+ * `FailedExploit` shape described in the task spec. Returns null if the
+ * artifact is not a failed exploit.
+ */
+export declare function toFailedExploit(artifact: PhaseArtifact | undefined): FailedExploit | null;
+/**
+ * Format a MythosReport as an agent-readable message. The runtime can
+ * inject this into the conversation after each run so the agent knows
+ * exactly where it stands.
+ */
+export declare function formatMythosReport(report: MythosReport): string;
+export {};
+//# sourceMappingURL=mythos-scaffold.d.ts.map

package/dist/exploit/mythos-scaffold.d.ts.map

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