wotann 0.5.0 → 0.5.39

package/dist/cli/commands/evolve.js

@@ -0,0 +1,336 @@
+/**
+ * `wotann evolve` — user-facing subcommand surface for the evolution
+ * subsystem (`src/evolution/` Optimizer/Mutator/Evaluator).
+ *
+ * The evolution pipeline runs inside the daemon via `learning/dream-runner.ts`.
+ * This handler exposes a thin, read-only-by-default CLI veneer so users can
+ * inspect runs, replay the optimizer one generation at a time, and review
+ * the constraint guards without poking at internal state files.
+ *
+ * Pure handler — returns `{ success, lines, error? }` so the CLI shell
+ * (src/index.ts) decides exit codes and how to print. Mirrors the
+ * intent.ts pattern; no process.exit, no chalk, no console.*.
+ *
+ * Subcommands:
+ *   status        Show last evolution run timestamp, last fitness score,
+ *                 current generation, mutation count. Reads from
+ *                 `<wotannDir>/evolution-state.json` (canonical state file
+ *                 — the dream-runner is the writer; we are the reader).
+ *   history [N]   Print the last N evolution generations from
+ *                 `<wotannDir>/evolution-log.jsonl` (the audit log that
+ *                 `learning/self-evolution.ts` already appends to). Default
+ *                 N = 10.
+ *   run           Invoke the Optimizer end-to-end through
+ *                 `src/evolution/runner.evolveSkill` — the same public
+ *                 entry-point the daemon uses. Surfaces progress as lines.
+ *   constraints   List the FORBIDDEN_TOKENS + size caps from
+ *                 `src/evolution/constraints.ts` so the user can audit the
+ *                 guardrails before a long run.
+ *
+ * WOTANN quality bars:
+ *  - QB #6 honest failures: every read error surfaces verbatim. No
+ *    "everything-OK fallthrough" when state files are corrupt.
+ *  - QB #7 per-call state: a fresh wotannDir read per call — no module-
+ *    level caching. Tests can mutate the directory between calls.
+ *  - QB #11 scope-bounded: writes only happen via the existing module
+ *    APIs (Optimizer's onProgress, the runner's archive logic). We do
+ *    NOT introduce a parallel state writer here.
+ *  - QB #14 commit-claim verification: this handler dispatches the
+ *    real `evolveSkill` for `run`, NOT a re-implementation. The
+ *    user can confirm it's the same code-path the daemon uses.
+ *  - QB #20 zombie-instance check: the `run` action takes injectable
+ *    `mutate`/`evaluate` callers so tests can wire to stubs without
+ *    instantiating provider clients.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const STATE_FILE = "evolution-state.json";
+const LOG_FILE = "evolution-log.jsonl";
+// Mirror of constants in src/evolution/constraints.ts. Duplicated as
+// read-only references so the CLI can surface them without importing
+// the validator (which would force a runtime dependency on the
+// evolution module for a pure-display action).
+const FORBIDDEN_TOKENS = ["TODO", "FIXME", "XXX", "<placeholder>"];
+const MAX_SKILL_BYTES = 15_360;
+const MAX_TOOL_DESC_BYTES = 500;
+// ── Entry point ───────────────────────────────────────────────────────────
+export async function runEvolveCommand(opts) {
+    switch (opts.action) {
+        case "status":
+            return handleStatus(opts);
+        case "history":
+            return handleHistory(opts);
+        case "constraints":
+            return handleConstraints(opts);
+        case "run":
+            return handleRun(opts);
+        default: {
+            const exhaustive = opts.action;
+            return {
+                success: false,
+                action: opts.action,
+                lines: [],
+                error: `unknown action: ${String(exhaustive)}`,
+            };
+        }
+    }
+}
+// ── status ────────────────────────────────────────────────────────────────
+function handleStatus(opts) {
+    const path = join(opts.wotannDir, STATE_FILE);
+    if (!existsSync(path)) {
+        return {
+            success: true,
+            action: "status",
+            lines: ["Evolution status: no evolution runs yet", `  state file: ${path} (not found)`],
+        };
+    }
+    let state;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        state = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            success: false,
+            action: "status",
+            lines: [],
+            error: `failed to read state file ${path}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const lines = [];
+    lines.push("Evolution status:");
+    lines.push(`  last run         : ${state.lastRunIso ?? "(unknown)"}`);
+    lines.push(`  last fitness     : ${typeof state.lastFitness === "number" ? state.lastFitness.toFixed(3) : "(none)"}`);
+    lines.push(`  current generation: ${typeof state.currentGeneration === "number" ? String(state.currentGeneration) : "0"}`);
+    lines.push(`  mutations applied : ${typeof state.mutationCount === "number" ? String(state.mutationCount) : "0"}`);
+    if (state.bestVariantId) {
+        lines.push(`  best variant     : ${state.bestVariantId}`);
+    }
+    return { success: true, action: "status", lines };
+}
+// ── history ───────────────────────────────────────────────────────────────
+function handleHistory(opts) {
+    const limit = opts.limit ?? 10;
+    if (!Number.isFinite(limit) || limit <= 0) {
+        return {
+            success: false,
+            action: "history",
+            lines: [],
+            error: `invalid limit: ${String(opts.limit)} (must be a positive integer)`,
+        };
+    }
+    const path = join(opts.wotannDir, LOG_FILE);
+    if (!existsSync(path)) {
+        return {
+            success: true,
+            action: "history",
+            lines: ["Evolution history: no generations recorded yet", `  log file: ${path} (not found)`],
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        return {
+            success: false,
+            action: "history",
+            lines: [],
+            error: `failed to read log file ${path}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const rows = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            rows.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip corrupt rows rather than fail the whole listing — the
+            // log file is append-only and a partially-written final line
+            // is the normal failure mode after a crash mid-write.
+        }
+    }
+    if (rows.length === 0) {
+        return {
+            success: true,
+            action: "history",
+            lines: ["Evolution history: no generations recorded yet"],
+        };
+    }
+    // Show the most recent N (tail of the log)
+    const tail = rows.slice(-limit).reverse();
+    const lines = [];
+    lines.push(`Evolution history (last ${tail.length} of ${rows.length}):`);
+    for (const row of tail) {
+        const gen = typeof row.generation === "number" ? `gen ${row.generation}` : (row.event ?? row.type ?? "?");
+        const score = typeof row.score === "number"
+            ? `score=${row.score.toFixed(3)}`
+            : row.description
+                ? `(${row.description.slice(0, 60)})`
+                : "score=?";
+        const muts = typeof row.mutationCount === "number" ? `mutations=${row.mutationCount}` : "";
+        const accepted = typeof row.accepted === "boolean" ? (row.accepted ? "ACCEPTED" : "rejected") : "";
+        const ts = typeof row.timestamp === "number" ? new Date(row.timestamp).toISOString() : "";
+        lines.push(`  - ${[ts, gen, score, muts, accepted].filter((s) => s.length > 0).join("  ")}`.trimEnd());
+    }
+    return { success: true, action: "history", lines };
+}
+// ── constraints ───────────────────────────────────────────────────────────
+function handleConstraints(_opts) {
+    const lines = [];
+    lines.push("Evolution constraint guards (src/evolution/constraints.ts):");
+    lines.push("");
+    lines.push("  Size caps:");
+    lines.push(`    skill files       ≤ ${MAX_SKILL_BYTES} bytes`);
+    lines.push(`    tool descriptions ≤ ${MAX_TOOL_DESC_BYTES} bytes`);
+    lines.push("");
+    lines.push("  Forbidden tokens (variant rejected if any appear verbatim):");
+    for (const tok of FORBIDDEN_TOKENS) {
+        lines.push(`    - ${tok}`);
+    }
+    lines.push("");
+    lines.push("  Structural rules:");
+    lines.push("    - skill files MUST start with --- (YAML frontmatter)");
+    lines.push("    - skill files MUST keep a `name:` frontmatter field");
+    lines.push("    - variant content MUST NOT be empty");
+    lines.push("    - variant MUST NOT contain secret-shaped tokens (sk-... / api_key=...)");
+    return { success: true, action: "constraints", lines };
+}
+// ── run ───────────────────────────────────────────────────────────────────
+async function handleRun(opts) {
+    if (!opts.skillPath) {
+        return {
+            success: false,
+            action: "run",
+            lines: [],
+            error: "run requires --skillPath pointing at the skill file to evolve",
+        };
+    }
+    if (!existsSync(opts.skillPath)) {
+        return {
+            success: false,
+            action: "run",
+            lines: [],
+            error: `skill not found: ${opts.skillPath}`,
+        };
+    }
+    let mutate = opts.mutate;
+    let evaluate = opts.evaluate;
+    if (!mutate || !evaluate) {
+        if (opts.requireInjected === true) {
+            return {
+                success: false,
+                action: "run",
+                lines: [],
+                error: "run requires injected mutate + evaluate callers (use stubs in tests, real providers in production)",
+            };
+        }
+        // Auto-inject stub callers — preserves the legacy
+        // `wotann evolve <skillPath>` UX where users could run the
+        // optimizer without programmatically wiring provider calls.
+        const stubMod = await import("../../evolution/optimizer.js");
+        mutate = mutate ?? stubMod.makeStubMutator();
+        evaluate = evaluate ?? stubMod.makeStubEvaluator();
+    }
+    const generations = opts.generations ?? 1;
+    // population is the optimizer's variantsPerGeneration knob.
+    const variantsPerGeneration = opts.population;
+    const targetFitness = opts.targetFitness;
+    // Load the public entry-point lazily so the module's typecheck cost
+    // doesn't drag in optimizer's transitive deps for status/history/constraints.
+    const runnerMod = await import("../../evolution/runner.js");
+    const { evolveSkill, buildSyntheticExamples } = runnerMod;
+    const baseline = readFileSync(opts.skillPath, "utf-8");
+    const examples = buildSyntheticExamples(baseline);
+    const progress = [];
+    // We can't pass onProgress through `evolveSkill` directly (the runner
+    // doesn't surface it), so we call `runOptimization` instead when the
+    // caller wants progress lines. For the standard path we still go
+    // through `evolveSkill` so the archive logic stays consistent.
+    const useDirectOptimizer = variantsPerGeneration !== undefined;
+    let summary;
+    try {
+        if (useDirectOptimizer) {
+            const optimizerMod = await import("../../evolution/optimizer.js");
+            const skillName = baseline.match(/^name:\s*(\S.*)$/m)?.[1]?.trim() ?? opts.skillPath;
+            summary = await optimizerMod.runOptimization({
+                target: { kind: "skill", path: opts.skillPath, name: skillName },
+                baseline,
+                examples,
+                mutate,
+                evaluate,
+                generations,
+                ...(variantsPerGeneration !== undefined ? { variantsPerGeneration } : {}),
+                onProgress: (ev) => {
+                    progress.push(formatProgress(ev));
+                },
+            });
+        }
+        else {
+            summary = await evolveSkill({
+                skillPath: opts.skillPath,
+                examples,
+                mutate,
+                evaluate,
+                generations,
+                write: Boolean(opts.write),
+            });
+        }
+    }
+    catch (err) {
+        return {
+            success: false,
+            action: "run",
+            lines: progress,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    const lines = [];
+    for (const p of progress)
+        lines.push(p);
+    lines.push("");
+    lines.push(`Evolution complete for ${opts.skillPath}`);
+    lines.push(`  baseline score : ${summary.baselineScore.toFixed(3)}`);
+    lines.push(`  best score     : ${summary.bestScore.toFixed(3)}`);
+    lines.push(`  improvement    : ${summary.improvementPct.toFixed(1)}%`);
+    lines.push(`  generations    : ${summary.generations}`);
+    lines.push(`  best variant   : ${summary.bestVariantId}`);
+    lines.push(`  cost (USD)     : $${summary.totalCostUsd.toFixed(4)}`);
+    if (typeof targetFitness === "number" &&
+        Number.isFinite(targetFitness) &&
+        summary.bestScore >= targetFitness) {
+        lines.push(`  ✓ target fitness ${targetFitness.toFixed(3)} reached`);
+    }
+    else if (typeof targetFitness === "number" && Number.isFinite(targetFitness)) {
+        lines.push(`  · target fitness ${targetFitness.toFixed(3)} NOT reached`);
+    }
+    if (summary.notes.length > 0) {
+        lines.push("  notes:");
+        for (const n of summary.notes)
+            lines.push(`    - ${n}`);
+    }
+    return { success: true, action: "run", lines };
+}
+function formatProgress(ev) {
+    switch (ev.type) {
+        case "baseline-scored":
+            return `  · baseline scored: ${ev.score.toFixed(3)}`;
+        case "generation-start":
+            return `  · generation ${ev.generation} starting`;
+        case "variant-evaluated":
+            return `  · gen ${ev.generation} variant ${ev.variantId} score=${ev.score.toFixed(3)} cost=$${ev.cost.toFixed(4)}`;
+        case "variant-rejected":
+            return `  · variant ${ev.variantId} rejected: ${ev.violations.join(", ")}`;
+        case "budget-exhausted":
+            return `  · budget exhausted at $${ev.spent.toFixed(4)}`;
+        default: {
+            const _exhaustive = ev;
+            return `  · unknown event: ${JSON.stringify(_exhaustive)}`;
+        }
+    }
+}
+//# sourceMappingURL=evolve.js.map

package/dist/cli/commands/evolve.js.map

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

package/dist/cli/commands/learning.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `wotann learning` — read-only CLI surface over the learning subsystem.
+ *
+ * The learning pipeline (src/learning/, ~5920 LOC) runs inside the
+ * KairosDaemon and accumulates state in two places:
+ *
+ *   1. SQLite (`<wotannDir>/memory.db`)
+ *      - `memory_entries` rows where `block_type='patterns'`  (PatternCrystallizer)
+ *      - `decision_log`   rows                                 (DecisionLedger)
+ *      - `memory_entries` rows where `block_type='cases'`      (cross-session lessons mirror)
+ *
+ *   2. Filesystem (`<wotannDir>/`)
+ *      - `.dreams/*.json`   per-phase artefacts (daemon)
+ *      - `dreams/*.json`    per-phase artefacts (dream-runner)
+ *      - `DREAMS.md`        human-readable diary
+ *      - `LESSONS.md`       accumulated gotchas (loadable via dream-runner)
+ *      - `decisions.json`   ledger snapshot (when persistToDisk was called)
+ *
+ * This handler is INTENTIONALLY decoupled from KairosDaemon / WotannRuntime:
+ *   - opening the daemon would spin up provider clients, hooks, schedulers.
+ *   - the CLI must stay snappy and not race the live daemon for locks.
+ *
+ * Pure handler — returns a `LearningCommandResult` with `lines` for the
+ * caller (`src/index.ts`) to print. No process.exit, no console.* writes.
+ *
+ * WOTANN quality bars honoured:
+ *   - QB #6  honest failures: missing DB / dir → empty-state lines, never throw.
+ *   - QB #7  per-call state: a fresh SQLite handle per call; closed before return.
+ *   - QB #11 scope-bounded: only reads .wotann; never writes.
+ *   - QB #13 strict equality for action dispatch (no string-includes drift).
+ */
+export type LearningAction = "dreams" | "patterns" | "decisions" | "lessons" | "stats";
+export interface LearningCommandOptions {
+    readonly action: LearningAction;
+    /**
+     * The WOTANN data directory to read from. Production wires this to
+     * `resolveWotannHome()`; tests pass a tmpdir. The handler treats the
+     * directory as opaque — it may or may not exist.
+     */
+    readonly wotannDir: string;
+    /**
+     * Maximum number of rows to return per listing. Defaults to 50.
+     * Used to keep the terminal output bounded.
+     */
+    readonly limit?: number;
+}
+export interface LearningCommandResult {
+    readonly success: boolean;
+    readonly action: LearningAction;
+    readonly lines: readonly string[];
+    readonly error?: string;
+}
+export declare function runLearningCommand(options: LearningCommandOptions): Promise<LearningCommandResult>;
+//# sourceMappingURL=learning.d.ts.map

package/dist/cli/commands/learning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/learning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAQH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AASD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAsBhC"}