dsh-continual-evolve 0.1.1 → 0.3.0

package/lib/evolve-event.d.ts

@@ -0,0 +1,38 @@
+import type { RefinementResult } from "./types.js";
+/** The structured event payload emitted after every successful refinement. */
+export interface EvolveCompleteEvent {
+    /** Event discriminator for consumers. */
+    type: "evolve_complete";
+    /** The refinement id (same as the result). */
+    refinementId: string;
+    /** One-line summary of the refinement. */
+    summary: string;
+    /** Number of edits that were actually applied. */
+    appliedEdits: number;
+    /** Number of edits that failed to apply. */
+    failedEdits: number;
+    /** Scope of the refinement ("local" or "global"). */
+    scope: string;
+    /** What triggered this refinement (e.g. "auto_review", "manual_plan", "manual_tool"). */
+    trigger: string;
+    /** Session id that owns the refinement (auto or manual). */
+    sessionId: string;
+    /** ISO timestamp. */
+    timestamp: string;
+    /** Per-edit summaries (kind + id + action) for consumers that want detail. */
+    edits: {
+        action: string;
+        kind: string;
+        id: string;
+        applied: boolean;
+    }[];
+}
+/** Build a structured evolve-complete event from a refinement result. */
+export declare function buildEvolveCompleteEvent(result: RefinementResult, trigger: string, sessionId: string): EvolveCompleteEvent;
+/**
+ * Emit an evolve_complete event to the reviews.jsonl audit trail. The event
+ * is JSONL-formatted (one line) so consumers can tail and parse it. This is
+ * a best-effort write — failure never blocks the refinement path.
+ */
+export declare function emitEvolveComplete(baseDir: string, event: EvolveCompleteEvent): void;
+//# sourceMappingURL=evolve-event.d.ts.map

package/lib/evolve-event.js

@@ -0,0 +1,49 @@
+/**
+ * Structured "evolve complete" events (gap C4): a durable, machine-readable
+ * record emitted after every successful refinement application — whether
+ * auto-gated or manual. Third-party consumers can observe these events via
+ * the plugin log (JSONL) and the reviews.jsonl audit trail.
+ *
+ * Design: prime-agent `/refine` emits `refine_complete{id,summary,
+ * appliedEdits,scope}` extension events. We follow the same pattern with
+ * added provenance (trigger, source) so consumers know WHY the refinement
+ * happened and WHO initiated it.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+/** Build a structured evolve-complete event from a refinement result. */
+export function buildEvolveCompleteEvent(result, trigger, sessionId) {
+    return {
+        type: "evolve_complete",
+        refinementId: result.id,
+        summary: result.summary,
+        appliedEdits: result.appliedEdits.filter((e) => e.applied).length,
+        failedEdits: result.appliedEdits.filter((e) => !e.applied).length,
+        scope: result.scope ?? "local",
+        trigger,
+        sessionId,
+        timestamp: new Date().toISOString(),
+        edits: result.appliedEdits.map((e) => ({
+            action: e.action,
+            kind: e.kind,
+            id: e.id,
+            applied: e.applied,
+        })),
+    };
+}
+/**
+ * Emit an evolve_complete event to the reviews.jsonl audit trail. The event
+ * is JSONL-formatted (one line) so consumers can tail and parse it. This is
+ * a best-effort write — failure never blocks the refinement path.
+ */
+export function emitEvolveComplete(baseDir, event) {
+    try {
+        const dir = join(baseDir, "evolve");
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, "reviews.jsonl"), `${JSON.stringify(event)}\n`, "utf8");
+    }
+    catch {
+        // Event emission is diagnostic; never interrupt the refinement path.
+    }
+}
+//# sourceMappingURL=evolve-event.js.map

package/lib/failures.d.ts

@@ -0,0 +1,39 @@
+export interface FailureRecord {
+    /** When the failure was recorded (ISO). Unknown for aggregated benchmark cells without timestamps. */
+    timestamp?: string;
+    /** Where the failure came from: "review-gate" | "benchmark:<bid>:<caseId>". */
+    source: string;
+    /** Failure class (see classifyFailure). */
+    kind: string;
+    /** The original failure text (notes or rationale). */
+    message: string;
+}
+export interface FailureSummary {
+    total: number;
+    /** Count per failure class, sorted descending (most frequent first). */
+    byKind: Record<string, number>;
+    /** Count per source (gate vs benchmark:bid). */
+    bySource: Record<string, number>;
+}
+/**
+ * Classify a failure message by prefix rules. Deterministic and additive:
+ * unknown text falls into "other" so the summary never drops a failure.
+ */
+export declare function classifyFailure(message: string): string;
+/** Aggregate a record list into counts. Empty input yields an all-zero summary. */
+export declare function summarizeFailures(records: readonly FailureRecord[]): FailureSummary;
+/**
+ * Read failed review-gate records from `<baseDir>/evolve/reviews.jsonl`
+ * (outcome === "failed"). Tolerant of a missing/corrupt file.
+ */
+export declare function readReviewFailures(baseDir: string): FailureRecord[];
+/**
+ * Read failed cells from every benchmark scoreboard under
+ * `<baseDir>/evolve/benchmarks/<bid>/`. Tolerant of missing/corrupt data.
+ */
+export declare function readBenchmarkFailures(baseDir: string): FailureRecord[];
+/** Combine both sources into one summary. */
+export declare function collectFailureSummary(baseDir: string): FailureSummary;
+/** Human-readable report for the command line. */
+export declare function formatFailureSummary(summary: FailureSummary): string;
+//# sourceMappingURL=failures.d.ts.map

package/lib/failures.js

@@ -0,0 +1,170 @@
+/**
+ * Failure-signature aggregation (gap R/D1 — observation stage): turn the
+ * free-text failure records the system already produces (review-gate failures
+ * in reviews.jsonl, failed cells in benchmark scoreboards) into a structured
+ * count by failure CLASS. This is deliberately NOT the full failure-signature
+ * Refiner from gap D1 — no routing, no policy — it is the data layer that
+ * lets a later patch decide whether a given failure class recurs often enough
+ * to deserve one.
+ *
+ * Classes are extracted with pure prefix rules (see classifyFailure), so the
+ * aggregation is deterministic and unit-testable: the same failure text
+ * always lands in the same class.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Classify a failure message by prefix rules. Deterministic and additive:
+ * unknown text falls into "other" so the summary never drops a failure.
+ */
+export function classifyFailure(message) {
+    const text = (message ?? "").trim();
+    const lower = text.toLowerCase();
+    if (lower.includes("rubric decrypt failed"))
+        return "rubric-decrypt";
+    if (lower.includes("materials changed"))
+        return "material-drift";
+    if (lower.includes("executor failed") || lower.includes("executor stopped"))
+        return "executor";
+    if (lower.includes("reviewer failed") || lower.includes("reviewer stopped"))
+        return "reviewer";
+    if (lower.includes("fate assessment error"))
+        return "fate-assessor";
+    if (lower.includes("trajectory unavailable"))
+        return "trajectory";
+    if (lower.includes("output budget exhausted") || lower.includes("max-tokens"))
+        return "max-tokens";
+    if (lower.includes("llm call aborted") || lower.includes("aborted"))
+        return "aborted";
+    if (lower.includes("llm call failed"))
+        return "llm";
+    if (lower.includes("gate error"))
+        return "gate";
+    if (lower.includes("casecheck") || lower.includes("case check"))
+        return "casecheck";
+    return "other";
+}
+/** Aggregate a record list into counts. Empty input yields an all-zero summary. */
+export function summarizeFailures(records) {
+    const byKind = {};
+    const bySource = {};
+    for (const record of records) {
+        byKind[record.kind] = (byKind[record.kind] ?? 0) + 1;
+        bySource[record.source] = (bySource[record.source] ?? 0) + 1;
+    }
+    return {
+        total: records.length,
+        byKind: Object.fromEntries(Object.entries(byKind).sort((a, b) => b[1] - a[1])),
+        bySource: Object.fromEntries(Object.entries(bySource).sort((a, b) => b[1] - a[1])),
+    };
+}
+/**
+ * Read failed review-gate records from `<baseDir>/evolve/reviews.jsonl`
+ * (outcome === "failed"). Tolerant of a missing/corrupt file.
+ */
+export function readReviewFailures(baseDir) {
+    const path = join(baseDir, "evolve", "reviews.jsonl");
+    if (!existsSync(path))
+        return [];
+    const records = [];
+    try {
+        for (const line of readFileSync(path, "utf8").split("\n")) {
+            if (line.trim().length === 0)
+                continue;
+            try {
+                const raw = JSON.parse(line);
+                if (raw.outcome !== "failed" || !raw.rationale)
+                    continue;
+                records.push({
+                    ...(raw.timestamp ? { timestamp: raw.timestamp } : {}),
+                    source: `review-gate${raw.reason ? `:${raw.reason}` : ""}`,
+                    kind: classifyFailure(raw.rationale),
+                    message: raw.rationale,
+                });
+            }
+            catch {
+                // skip malformed lines — the audit file must never break reporting
+            }
+        }
+    }
+    catch {
+        return [];
+    }
+    return records;
+}
+/**
+ * Read failed cells from every benchmark scoreboard under
+ * `<baseDir>/evolve/benchmarks/<bid>/`. Tolerant of missing/corrupt data.
+ */
+export function readBenchmarkFailures(baseDir) {
+    const root = join(baseDir, "evolve", "benchmarks");
+    if (!existsSync(root))
+        return [];
+    const records = [];
+    let bids;
+    try {
+        bids = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    for (const bid of bids) {
+        const boardPath = join(root, bid, "scoreboard.json");
+        if (!existsSync(boardPath))
+            continue;
+        let board;
+        try {
+            board = JSON.parse(readFileSync(boardPath, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const cellLists = [];
+        if (board.reference?.cells)
+            cellLists.push({ label: "reference", cells: board.reference.cells });
+        for (const entry of board.candidates ?? []) {
+            if (entry.cells)
+                cellLists.push({ label: entry.label ?? "candidate", cells: entry.cells });
+        }
+        for (const list of cellLists) {
+            for (const cell of list.cells) {
+                const c = cell;
+                if (c.status !== "failed" || !c.notes)
+                    continue;
+                records.push({
+                    source: `benchmark:${bid}:${c.caseId ?? "?"}`,
+                    kind: classifyFailure(c.notes),
+                    message: c.notes,
+                });
+            }
+        }
+    }
+    return records;
+}
+/** Combine both sources into one summary. */
+export function collectFailureSummary(baseDir) {
+    return summarizeFailures([...readReviewFailures(baseDir), ...readBenchmarkFailures(baseDir)]);
+}
+/** Human-readable report for the command line. */
+export function formatFailureSummary(summary) {
+    const lines = [`failure summary: ${summary.total} total`];
+    const kinds = Object.entries(summary.byKind);
+    if (kinds.length > 0) {
+        lines.push("by class:");
+        for (const [kind, count] of kinds) {
+            lines.push(`  ${kind}: ${count}`);
+        }
+    }
+    else {
+        lines.push("by class: (none)");
+    }
+    const sources = Object.entries(summary.bySource);
+    if (sources.length > 0) {
+        lines.push("by source:");
+        for (const [source, count] of sources) {
+            lines.push(`  ${source}: ${count}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=failures.js.map

package/lib/fate.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Gate local-fate dimension (#11 P2): the automatic review gate also decides
+ * what happens to a session's local entries while the session is STILL
+ * running — not only at wrap-up.
+ *
+ * Local entries default to orphans: a later session (not on the parentSession
+ * chain) never sees them, and nothing promotes or archives them — the
+ * exploration results effectively "die" with the session. This module gives
+ * the gate its own fate cadence on top of the existing review:
+ *
+ * - `promote` → the entry moves into the global store. The global store is a
+ *   governed resource: the user is consulted FIRST (the consultSkillEdits
+ *   pattern — never written silently), with a cooldown after a decline.
+ * - `archive` → hidden from injection (data stays restorable). Archives that
+ *   would bury possibly-reusable content (not covered globally AND distilled
+ *   from real user messages) ask the user first; covered/operational entries
+ *   archive silently, exactly like the wrap-up command does.
+ * - `keep` → nothing.
+ *
+ * At compaction the gate NEVER opens a dialog (the agent is mid-compaction):
+ * only deterministic silent archives apply, everything governed is deferred
+ * with an audit record pointing at `/evolve wrapup`.
+ *
+ * Division of labor is the same as wrap-up: the mechanical audit proposes
+ * (listLocalCandidates + coverage guards), the LLM classifies
+ * (assessLocalEntries), the user approves, the code applies deterministically
+ * (wholePromoteProposals / splitPromoteProposals — the SAME edits the wrap-up
+ * command applies). Every decision lands in reviews.jsonl via the gate's
+ * record callback.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { HarnessState, RefinementResult } from "./types.js";
+import type { EvolutionEngine } from "./service.js";
+import type { AutoRefineReason } from "./review.js";
+import type { AutoReviewConfig, GateState, ReviewRecord } from "./auto.js";
+import { type WrapupCandidate, type WrapupItem } from "./wrapup.js";
+/** Turns a declined local-fate proposal stays silent before being offered again. */
+export declare const FATE_CONSULT_COOLDOWN_TURNS = 10;
+/** What the gate decided to do with the session's local entries. */
+export interface FatePlan {
+    candidates: readonly WrapupCandidate[];
+    /** Whole promotions that passed the deterministic global-coverage guard. */
+    promotable: WrapupItem[];
+    /** Split promotions (archive + cleaned promote payload) that passed the guard. */
+    splits: {
+        item: WrapupItem;
+        candidate: WrapupCandidate;
+    }[];
+    /** Archives that may proceed silently (covered globally / no real distillation source). */
+    silentArchives: WrapupItem[];
+    /** Archives that must ask the user first (uncovered + real source). */
+    reviewArchives: WrapupItem[];
+    /** Promotes blocked by the deterministic guard, with why. */
+    skipped: {
+        key: string;
+        reason: string;
+    }[];
+    /** Split promotions blocked by the deterministic guard, with why. */
+    splitSkipped: {
+        key: string;
+        reason: string;
+    }[];
+}
+/**
+ * Partition an assessed wrap-up classification into concrete fate actions,
+ * re-running the deterministic guards against the LIVE global store (state
+ * may have changed while the LLM call was in flight). Pure and unit-tested;
+ * mirrors the partition step of the wrap-up command.
+ */
+export declare function planLocalFates(items: readonly WrapupItem[], candidates: readonly WrapupCandidate[], globalState: HarnessState): FatePlan;
+/**
+ * The cooldown key of a candidate set: the sorted `kind:id` list. The set is
+ * the unit of consultation — a declined proposal is not offered again within
+ * the cooldown window, and a changed set (new entries appeared) starts a
+ * fresh consultation.
+ */
+export declare function fateSetKey(candidates: readonly WrapupCandidate[]): string;
+/**
+ * Whether the local-fate dimension is due for this gate run. Turn-interval
+ * gates respect the fate cadence (an independent counter — goal-driven
+ * sessions run the review EVERY round, the fate assessment must not);
+ * compaction is unconditional: experiences about to be summarized away get
+ * their fate check regardless. Goal-blocked assessments are unconditional
+ * here too — the gate's own streak counter (auto.ts runGoalBlockedFate)
+ * already gates their frequency, so the cadence must not re-block them.
+ */
+export declare function fateCadenceDue(state: GateState, reason: AutoRefineReason, intervalTurns: number): boolean;
+export interface FateConsultResult {
+    approved: boolean;
+    asked: boolean;
+    reason: "nothing-to-ask" | "consented" | "declined" | "cooldown" | "unavailable" | "error";
+}
+/**
+ * Ask the user whether to execute the gate's local-fate proposal. ONE dialog
+ * covers every governed action (promotes, split promotions, review-required
+ * archives) — the gate never spams questions. Conservative on every edge:
+ * no question service → not approved; the question call fails → not approved;
+ * the same candidate set was declined within the cooldown → not asked again.
+ * A decline records the cooldown (the consultSkillEdits pattern).
+ */
+export declare function consultLocalFates(ctx: Context, agent: Agent, plan: FatePlan, gate: GateState): Promise<FateConsultResult>;
+export type FateApplyMode = "full" | "silent-only";
+export interface FateApplyResult {
+    /** Human-readable lines of what was applied (for the notice and the audit record). */
+    applied: string[];
+    /** Every refinement result produced, for rollback discovery. */
+    results: RefinementResult[];
+}
+/**
+ * Deterministically apply the fate plan. `"full"` applies everything
+ * (promotes, splits, silent + review archives); `"silent-only"` applies only
+ * the deterministic silent archives (the compaction path — nothing governed).
+ * Promotes go through the SAME proposals as the wrap-up command
+ * (wholePromoteProposals / splitPromoteProposals), so both paths write
+ * identical global entries and local retirement stamps.
+ */
+export declare function applyLocalFates(engine: EvolutionEngine, sessionId: string, plan: FatePlan, localState: HarnessState, mode: FateApplyMode): FateApplyResult;
+/**
+ * The gate's local-fate phase. Runs after the review phase on every gate
+ * trigger (turn_interval / compact), subject to cadence and cooldown. All
+ * failures are contained and recorded — a broken fate dimension never
+ * disturbs the agent loop.
+ */
+export declare function runLocalFatePhase(ctx: Context, engine: EvolutionEngine, agent: Agent, config: AutoReviewConfig, state: GateState, reason: AutoRefineReason, record: (entry: Omit<ReviewRecord, "timestamp">) => void): Promise<void>;
+/** The user-visible notice after the gate applied local-fate actions. */
+export declare function buildFateNotice(applied: readonly string[]): string;
+//# sourceMappingURL=fate.d.ts.map