dsh-continual-evolve 0.7.1 → 0.7.2

package/lib/index.js

@@ -3,9 +3,9 @@
  *
  * Mounts the evolution engine, registers the model-facing evolve_* tools,
  * the human-facing /evolve command, the system-prompt guidance section, and
- * (opt-in) the automatic review gate that runs the planner on a turn
- * interval. Store roots default under the resolved DSH home; a deployment
- * may override `baseDir` in the plugin config.
+ * the automatic review gate. The listener is always registered, while its
+ * effective state is controlled by the runtime switch. Successful turns feed
+ * incremental snapshots through a per-session serial scheduler.
  */
 import { join } from "node:path";
 import z from "@deepseek-ai/schemastery";
@@ -29,9 +29,9 @@ export const Config = z.object({
     baseDir: z.string(),
     /** System-prompt section order for the evolution guidance. */
     sectionOrder: z.natural().default(118),
-    /** Enable the automatic review gate (off by default: it costs model calls). */
+    /** Initial automatic-review default when no runtime switch exists (off by default: it costs model calls). */
     autoReview: z.boolean().default(false),
-    /** Gate runs when this many turns have passed since the last review. */
+    /** Legacy/local-fate cadence fallback; successful-turn review is snapshot-driven. */
     reviewIntervalTurns: z.natural().default(6),
     /** Trajectory slice handed to the gate, in characters. */
     maxReviewInputChars: z.natural().default(40000),
@@ -177,25 +177,28 @@ export function apply(ctx, config) {
     void restoreMounted(ctx, baseDir).catch((cause) => {
         ctx.logger("continual-evolve").warn(`mount restore failed: ${cause instanceof Error ? cause.message : String(cause)}`);
     });
-    if (config.autoReview) {
-        registerAutoReview(ctx, engine, {
-            intervalTurns: config.reviewIntervalTurns ?? 6,
-            maxInputChars: config.maxReviewInputChars ?? 40000,
-            budgetTokens: config.reviewBudgetTokens ?? 4096,
-            notifyOnAutoReview: config.notifyOnAutoReview ?? true,
-            localFate: config.localFate ?? true,
-            fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
-            goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
-            promotionPolicy,
-            autoCase: config.autoCase ?? true,
-            rubricKey,
-            ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
-            ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
-            ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
-            ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
-        });
-        ctx.logger("continual-evolve").info(`continual-evolve auto-review enabled (every ${config.reviewIntervalTurns ?? 6} turns; local-fate ${config.localFate ?? true ? "on" : "off"} every ${config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6} turns)`);
-    }
+    // The listener is always registered. `autoReview` is only the initial
+    // runtime default; `/evolve resume` can enable it without a profile edit
+    // or process restart, while manual tools and commands stay independent.
+    registerAutoReview(ctx, engine, {
+        intervalTurns: config.reviewIntervalTurns ?? 6,
+        enabledByDefault: config.autoReview ?? false,
+        maxInputChars: config.maxReviewInputChars ?? 40000,
+        budgetTokens: config.reviewBudgetTokens ?? 4096,
+        notifyOnAutoReview: config.notifyOnAutoReview ?? true,
+        localFate: config.localFate ?? true,
+        fateIntervalTurns: config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6,
+        goalBlockedWrapupTurns: config.goalBlockedWrapupTurns ?? 3,
+        promotionPolicy,
+        autoCase: config.autoCase ?? true,
+        rubricKey,
+        ...(config.historyRetain?.reviews !== undefined ? { reviewsRetain: config.historyRetain.reviews } : {}),
+        ...(config.reviewModel ? { reviewModel: config.reviewModel } : {}),
+        ...(config.plannerPrefixCache ? { prefixCacheMode: config.plannerPrefixCache } : {}),
+        ...(config.plannerPrefixMaxChars !== undefined ? { prefixMaxChars: config.plannerPrefixMaxChars } : {}),
+    });
+    const runtimeDefault = config.autoReview ?? false;
+    ctx.logger("continual-evolve").info(`continual-evolve auto-review registered (default ${runtimeDefault ? "on" : "off"}; successful-turn snapshots; local-fate ${config.localFate ?? true ? "on" : "off"} every ${config.fateIntervalTurns ?? config.reviewIntervalTurns ?? 6} turns)`);
     ctx.logger("continual-evolve").info(`continual-evolve mounted (baseDir=${baseDir})`);
 }
 //# sourceMappingURL=index.js.map

package/lib/planner.d.ts

@@ -24,6 +24,11 @@ export interface PlanOptions {
      * every planning call is grounded in what the user actually said.
      */
     trajectory?: string;
+    /**
+     * Explicit session-trajectory rows for prefix-cache Route A. When supplied,
+     * the planner sees only the scheduler snapshot rather than the full session.
+     */
+    trajectoryEvents?: readonly unknown[];
     /**
      * Skills root to read the skill-creator template facts from
      * (`<root>/skill-creator/references/template.md`). When omitted or the

package/lib/planner.js

@@ -90,7 +90,7 @@ export async function planWithLlm(ctx, options) {
     // as a session-derived message prefix (cache-eligible on providers with
     // prompt caching) and drops the auto-extracted trajectory block; Route B
     // keeps the legacy flat-text block. An empty prefix falls back to B.
-    const events = sessionEventsOf(agent);
+    const events = options.trajectoryEvents ?? sessionEventsOf(agent);
     const routing = resolvePrefixCache(options.prefixCache);
     const route = detectPlannerRoute(events, routing.mode);
     let prefixMessages = [];

package/lib/review-scheduler.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Serial latest-pending scheduler for automatic review snapshots.
+ *
+ * This is the DSH equivalent of ZCode's memory extraction scheduler: one
+ * runner per session, at most one running snapshot, and one replaceable
+ * pending snapshot while the runner is busy. A cursor advances only after a
+ * successful or no-op execution; errors and aborts leave it untouched so the
+ * next snapshot retries the same durable boundary.
+ */
+/** Terminal state of one scheduled snapshot. */
+export type ReviewSchedulerStatus = "success" | "no-op" | "error" | "aborted";
+/** A scheduler execution receives the exact snapshot and its owner signal. */
+export interface ReviewSchedulerExecution<TSnapshot> {
+    readonly snapshot: TSnapshot;
+    readonly signal: AbortSignal;
+}
+/** Public scheduler surface used by the auto-review driver and tests. */
+export interface ReviewScheduler<TSnapshot> {
+    /** Wait until the current run and all coalesced pending work settle. */
+    drain(): Promise<void>;
+    /** Last successfully processed or skipped snapshot boundary. */
+    getCursor(): string | undefined;
+    /** Whether a run or a replaceable pending snapshot exists. */
+    hasPendingWork(): boolean;
+    /** Submit a snapshot (or an async acquisition) without blocking the caller. */
+    schedule(snapshot: TSnapshot | Promise<TSnapshot>): void;
+    /** Abort the owner signal, drop pending work, and make later schedules no-ops. */
+    shutdown(): void;
+}
+/**
+ * Create a scheduler with ZCode-compatible coalescing and cursor semantics.
+ *
+ * @param execute - one serial extraction/review operation
+ * @param cursorOf - extracts the durable boundary from a snapshot
+ */
+export declare function createReviewScheduler<TSnapshot>(execute: (input: ReviewSchedulerExecution<TSnapshot>) => Promise<ReviewSchedulerStatus>, cursorOf: (snapshot: TSnapshot) => string | undefined): ReviewScheduler<TSnapshot>;
+//# sourceMappingURL=review-scheduler.d.ts.map

package/lib/review-scheduler.js

@@ -0,0 +1,110 @@
+/**
+ * Serial latest-pending scheduler for automatic review snapshots.
+ *
+ * This is the DSH equivalent of ZCode's memory extraction scheduler: one
+ * runner per session, at most one running snapshot, and one replaceable
+ * pending snapshot while the runner is busy. A cursor advances only after a
+ * successful or no-op execution; errors and aborts leave it untouched so the
+ * next snapshot retries the same durable boundary.
+ */
+/**
+ * Create a scheduler with ZCode-compatible coalescing and cursor semantics.
+ *
+ * @param execute - one serial extraction/review operation
+ * @param cursorOf - extracts the durable boundary from a snapshot
+ */
+export function createReviewScheduler(execute, cursorOf) {
+    let cursor;
+    let latestPending;
+    let running;
+    let shuttingDown = false;
+    const shutdownController = new AbortController();
+    const processSnapshot = async (snapshot) => {
+        if (shuttingDown || shutdownController.signal.aborted)
+            return;
+        let status;
+        try {
+            status = await execute({ snapshot, signal: shutdownController.signal });
+        }
+        catch {
+            // A failed acquisition/extraction is deliberately contained. The
+            // cursor remains unchanged and the next snapshot retries it.
+            return;
+        }
+        if (!shuttingDown && (status === "success" || status === "no-op")) {
+            cursor = cursorOf(snapshot);
+        }
+    };
+    const run = async (first) => {
+        try {
+            let current = first;
+            while (current && !shuttingDown) {
+                const acquisition = await waitForSnapshotAcquisitionOrShutdown(current, shutdownController.signal);
+                if (acquisition.status === "shutdown" || shuttingDown)
+                    break;
+                if (acquisition.status === "acquired") {
+                    await processSnapshot(acquisition.snapshot);
+                }
+                current = shuttingDown ? undefined : latestPending;
+                latestPending = undefined;
+            }
+        }
+        finally {
+            if (shuttingDown)
+                latestPending = undefined;
+            running = undefined;
+        }
+    };
+    return {
+        async drain() {
+            while (running) {
+                await running;
+            }
+        },
+        getCursor() {
+            return cursor;
+        },
+        hasPendingWork() {
+            return running !== undefined || latestPending !== undefined;
+        },
+        schedule(snapshot) {
+            if (shuttingDown)
+                return;
+            const acquisition = acquireSnapshot(snapshot);
+            if (running) {
+                // Replace, never queue: a burst of turns contributes one latest
+                // boundary and the next extraction consumes all intervening rows.
+                latestPending = acquisition;
+                return;
+            }
+            running = run(acquisition);
+        },
+        shutdown() {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            latestPending = undefined;
+            shutdownController.abort();
+        },
+    };
+}
+function acquireSnapshot(snapshot) {
+    return Promise.resolve(snapshot).then((value) => ({ status: "acquired", snapshot: value }), () => ({ status: "error" }));
+}
+function waitForSnapshotAcquisitionOrShutdown(acquisition, signal) {
+    if (signal.aborted)
+        return Promise.resolve({ status: "shutdown" });
+    return new Promise((resolve) => {
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            cleanup();
+            resolve({ status: "shutdown" });
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        void acquisition.then((result) => {
+            cleanup();
+            resolve(result);
+        });
+    });
+}
+//# sourceMappingURL=review-scheduler.js.map

package/lib/review.d.ts

@@ -15,7 +15,7 @@ export interface AutoRefineReview {
     rationale: string;
     instructions?: string;
 }
-export type AutoRefineReason = "turn_interval" | "compact" | "goal_blocked";
+export type AutoRefineReason = "turn_snapshot" | "turn_interval" | "compact" | "goal_blocked";
 export interface AutoRefineReviewContext {
     reason: AutoRefineReason;
     turnsSinceLastReview: number;
@@ -27,6 +27,8 @@ export interface ReviewOptions {
     context: AutoRefineReviewContext;
     /** Serialized trajectory text; when absent the gate is skipped by the caller. */
     trajectory?: string;
+    /** Incremental surface rows captured for this turn snapshot. */
+    trajectoryEvents?: readonly unknown[];
     signal?: AbortSignal;
     budgetTokens?: number;
     /** Gap C1: optional provider/model override for the review gate (cheaper model). */

package/lib/review.js

@@ -101,7 +101,7 @@ export async function reviewAutoRefine(ctx, options) {
     }
     // Route A carries the judged conversation as a session-derived message
     // prefix and drops the flat block; an empty prefix falls back to B.
-    const events = sessionEventsOf(agent);
+    const events = options.trajectoryEvents ?? sessionEventsOf(agent);
     const routing = resolvePrefixCache(options.prefixCache);
     const route = detectPlannerRoute(events, routing.mode);
     let prefixMessages = [];

package/lib/runtime.d.ts

@@ -1,6 +1,9 @@
+/** On-disk runtime gate state. Version 2 adds an explicit enable bit. */
 export interface GateRuntime {
-    version: 1;
-    /** True while the human paused the automatic review gate. */
+    version: 2;
+    /** Whether the human has enabled automatic review. */
+    enabled: boolean;
+    /** Whether the human has explicitly paused automatic review. */
     paused: boolean;
     /** ISO timestamp of the last pause/resume write. */
     updatedAt: string;
@@ -8,17 +11,14 @@ export interface GateRuntime {
 /** Full path of the runtime switch file. */
 export declare function runtimePath(baseDir: string): string;
 /**
- * Load the runtime switch; fail open to "running" on any unreadable or
- * malformed content (called on every gate trigger, so it must never throw
- * for a bad file).
+ * Load the runtime switch. Missing, malformed, or legacy content uses the
+ * supplied configured default and never throws; this is a trigger-path read.
  */
-export declare function loadGateRuntime(baseDir: string): GateRuntime;
-/**
- * Persist the pause switch atomically (temp file + rename). Never throws
- * for a bad file — callers (pause/resume commands) surface real IO errors
- * through the command's own error path instead.
- */
-export declare function saveGateRuntime(baseDir: string, paused: boolean): string;
-/** True while the human paused the automatic review gate (fail-open). */
+export declare function loadGateRuntime(baseDir: string, defaultEnabled?: boolean): GateRuntime;
+/** Persist the runtime switch atomically (temp file + rename). */
+export declare function saveGateRuntime(baseDir: string, paused: boolean, enabled?: boolean): string;
+/** True while the human paused the automatic review gate. */
 export declare function isGatePaused(baseDir: string): boolean;
+/** Effective automatic-review state, including the explicit enable bit. */
+export declare function isGateEnabled(baseDir: string, defaultEnabled?: boolean): boolean;
 //# sourceMappingURL=runtime.d.ts.map

package/lib/runtime.js

@@ -1,18 +1,15 @@
 /**
- * Runtime gate switch (#21 P2): a tiny human-owned file that pauses the
- * automatic review gate without touching the plugin config or restarting.
+ * Runtime gate switch: a small human-owned file that enables or pauses the
+ * automatic review listener without editing the profile or restarting DSH.
  *
- * - file: `<baseDir>/evolve/runtime.json` (`{version, paused, updatedAt}`)
- * - `/evolve pause` sets paused, `/evolve resume` clears it, `/evolve
- *   status` shows it alongside the static patch config.
- * - the gate consults it on every trigger (turn-interval AND compaction)
- *   and stays dormant while paused — manual tools/commands keep working.
- * - fail-open: a missing or corrupt file means "running". Pausing is the
- *   exceptional state; a broken file must never silently wedge the gate
- *   shut (the next save rewrites it cleanly).
+ * - file: `<baseDir>/evolve/runtime.json` (`{version: 2, enabled, paused, updatedAt}`)
+ * - the file is consulted at every trigger and before scheduler execution;
+ * - `/evolve pause` sets `paused`, `/evolve resume` sets `enabled=true` and
+ *   clears the pause, while manual tools and commands remain independent;
+ * - a missing or malformed file uses the caller's configured default. A
+ *   legacy v1 `{paused}` file is readable and preserves its pause state.
  */
-import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { EVOLVE_DIR } from "./store.js";
@@ -21,57 +18,54 @@ const RUNTIME_FILE = "runtime.json";
 export function runtimePath(baseDir) {
     return join(baseDir, EVOLVE_DIR, RUNTIME_FILE);
 }
-function running() {
-    return { version: 1, paused: false, updatedAt: new Date(0).toISOString() };
+function state(enabled, paused) {
+    return { version: 2, enabled, paused, updatedAt: new Date(0).toISOString() };
 }
 /**
- * Load the runtime switch; fail open to "running" on any unreadable or
- * malformed content (called on every gate trigger, so it must never throw
- * for a bad file).
+ * Load the runtime switch. Missing, malformed, or legacy content uses the
+ * supplied configured default and never throws; this is a trigger-path read.
  */
-export function loadGateRuntime(baseDir) {
+export function loadGateRuntime(baseDir, defaultEnabled = false) {
     const path = runtimePath(baseDir);
-    if (!existsSync(path)) {
-        return running();
-    }
+    if (!existsSync(path))
+        return state(defaultEnabled, false);
     try {
         const raw = JSON.parse(readFileSync(path, "utf8"));
-        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-            return running();
-        }
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return state(defaultEnabled, false);
         const record = raw;
+        const paused = record["paused"] === true;
+        // v1 had no enable bit. Its only meaningful state was pause, so retain
+        // the configured default when it is not paused.
+        const enabled = typeof record["enabled"] === "boolean" ? record["enabled"] : defaultEnabled;
         return {
-            version: 1,
-            paused: record["paused"] === true,
+            version: 2,
+            enabled,
+            paused,
             updatedAt: typeof record["updatedAt"] === "string" ? record["updatedAt"] : new Date(0).toISOString(),
         };
     }
     catch {
-        return running();
+        return state(defaultEnabled, false);
     }
 }
-/**
- * Persist the pause switch atomically (temp file + rename). Never throws
- * for a bad file — callers (pause/resume commands) surface real IO errors
- * through the command's own error path instead.
- */
-export function saveGateRuntime(baseDir, paused) {
+/** Persist the runtime switch atomically (temp file + rename). */
+export function saveGateRuntime(baseDir, paused, enabled = true) {
     const path = runtimePath(baseDir);
     mkdirSync(join(baseDir, EVOLVE_DIR), { recursive: true });
     const tempPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    const payload = { version: 1, paused, updatedAt: new Date().toISOString() };
+    const payload = { version: 2, enabled, paused, updatedAt: new Date().toISOString() };
     writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
     try {
         renameSync(tempPath, path);
     }
     finally {
-        if (existsSync(tempPath)) {
+        if (existsSync(tempPath))
             unlinkSync(tempPath);
-        }
     }
     return path;
 }
-/** True while the human paused the automatic review gate (fail-open). */
+/** True while the human paused the automatic review gate. */
 export function isGatePaused(baseDir) {
     try {
         return loadGateRuntime(baseDir).paused;
@@ -80,4 +74,14 @@ export function isGatePaused(baseDir) {
         return false;
     }
 }
+/** Effective automatic-review state, including the explicit enable bit. */
+export function isGateEnabled(baseDir, defaultEnabled = false) {
+    try {
+        const current = loadGateRuntime(baseDir, defaultEnabled);
+        return current.enabled && !current.paused;
+    }
+    catch {
+        return defaultEnabled;
+    }
+}
 //# sourceMappingURL=runtime.js.map

package/lib/turn-snapshot.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Turn-boundary snapshots for the automatic review gate.
+ *
+ * The scheduler must see a bounded, mechanically filtered slice of the
+ * current session, not a fresh full-history LLM request on every turn. This
+ * module owns the snapshot boundary, cursor-compatible incremental rows, and
+ * the cheap eligibility checks that run before any model call.
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+/** Why a scheduler snapshot was captured. */
+export type TurnSnapshotReason = "turn_snapshot" | "compact";
+/** Mechanical reasons a snapshot can be skipped without an LLM call. */
+export type SnapshotSkipReason = "no-new-events" | "internal-agent" | "direct-memory-write" | "no-user-prose";
+/** One immutable scheduler input. The cursor is a durable event boundary. */
+export interface TurnSnapshot {
+    readonly sessionId: string;
+    readonly projectKey?: string;
+    readonly turn: number;
+    readonly reason: TurnSnapshotReason;
+    readonly cursor: string;
+    readonly events: readonly unknown[];
+    readonly trajectory: string;
+    readonly userText: string;
+    readonly sourceSeqs: readonly number[];
+    readonly eligible: boolean;
+    readonly skipReason?: SnapshotSkipReason;
+}
+/** Eligibility result kept separate so tests and future extractors share it. */
+export interface SnapshotEligibility {
+    readonly eligible: boolean;
+    readonly reason?: SnapshotSkipReason;
+    readonly userText: string;
+}
+/**
+ * Capture the current durable surface and select only rows after `cursor`.
+ * A seq-bearing session uses `seq:<n>`; older/test surfaces fall back to an
+ * event-count cursor so the scheduler still has a deterministic boundary.
+ */
+export declare function captureTurnSnapshot(ctx: Context, agent: Agent, opts: {
+    turn: number;
+    reason: TurnSnapshotReason;
+    cursor?: string;
+    maxChars: number;
+}): Promise<TurnSnapshot>;
+/**
+ * Decide whether the incremental rows deserve a model call. This intentionally
+ * does not decide whether a fact is valuable; that remains the review model's
+ * job. It only removes mechanical noise before the scheduler spends tokens.
+ */
+export declare function evaluateSnapshotEligibility(events: readonly unknown[], internalAgent?: boolean): SnapshotEligibility;
+/** True when an assistant row records an explicit evolve memory mutation. */
+export declare function containsDirectMemoryWrite(events: readonly unknown[]): boolean;
+/** Serialize only user/assistant text, retaining the bounded tail. */
+export declare function serializeSnapshotEvents(events: readonly unknown[], maxChars: number): string;
+/** A DSH subagent header is an internal source when its origin says so. */
+export declare function isInternalAgent(agent: Agent | undefined): boolean;
+//# sourceMappingURL=turn-snapshot.d.ts.map