dsh-continual-evolve 0.7.0 → 0.7.2

package/lib/llm-text.js

@@ -11,40 +11,57 @@ import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
  */
 export async function streamText(ctx, opts) {
     const assembler = new BlockAssembler();
-    for await (const chunk of ctx.llm.stream({
-        provider: opts.provider,
-        model: opts.model,
-        system: opts.system,
-        messages: [
-            createUserMessage({
-                content: [{ type: "text", text: opts.prompt }],
-                source: EVOLVE_MESSAGE_SOURCE,
-            }),
-        ],
-        reasoningEffort: ReasoningEffortId("off"),
-        maxTokens: opts.maxTokens ?? 8000,
-        ...(opts.signal ? { signal: opts.signal } : {}),
-    })) {
-        assembler.push(chunk);
+    let outcome = "error";
+    try {
+        for await (const chunk of ctx.llm.stream({
+            provider: opts.provider,
+            model: opts.model,
+            system: opts.system,
+            messages: [
+                ...(opts.prefixMessages ?? []),
+                createUserMessage({
+                    content: [{ type: "text", text: opts.prompt }],
+                    source: EVOLVE_MESSAGE_SOURCE,
+                }),
+            ],
+            reasoningEffort: ReasoningEffortId("off"),
+            maxTokens: opts.maxTokens ?? 8000,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        })) {
+            assembler.push(chunk);
+        }
+        const finish = assembler.finish;
+        if (finish.kind === "error") {
+            outcome = "error";
+            throw new Error(`evolve: LLM call failed: ${finish.failure?.message ?? "unknown"}`);
+        }
+        if (finish.kind === "aborted") {
+            outcome = "aborted";
+            throw new Error("evolve: LLM call aborted");
+        }
+        if (finish.kind === "max-tokens") {
+            outcome = "max-tokens";
+            throw new Error("evolve: LLM output budget exhausted (max-tokens)");
+        }
+        const text = assembler
+            .blocks()
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("\n");
+        if (text.length === 0) {
+            outcome = "empty";
+            throw new Error("evolve: LLM produced no text output");
+        }
+        outcome = "success";
+        return text;
     }
-    const finish = assembler.finish;
-    if (finish.kind === "error") {
-        throw new Error(`evolve: LLM call failed: ${finish.failure?.message ?? "unknown"}`);
+    finally {
+        try {
+            opts.onUsage?.({ ...(assembler.usage ? { usage: assembler.usage } : {}), outcome });
+        }
+        catch {
+            // Usage observation is diagnostic; its failure must not alter the model call.
+        }
     }
-    if (finish.kind === "aborted") {
-        throw new Error("evolve: LLM call aborted");
-    }
-    if (finish.kind === "max-tokens") {
-        throw new Error("evolve: LLM output budget exhausted (max-tokens)");
-    }
-    const text = assembler
-        .blocks()
-        .filter((block) => block.type === "text")
-        .map((block) => block.text)
-        .join("\n");
-    if (text.length === 0) {
-        throw new Error("evolve: LLM produced no text output");
-    }
-    return text;
 }
 //# sourceMappingURL=llm-text.js.map

package/lib/planner.d.ts

@@ -9,6 +9,8 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { HarnessState, RefinementProposal, RefinementResult } from "./types.js";
+import { type PrefixCacheOptions } from "./prefix-cache.js";
+import { type TokenUsageTarget } from "./token-usage.js";
 export declare const PLANNER_SYSTEM_PROMPT = "You are the /evolve continual harness subsystem.\n\nYour job is to improve the editable continual harness state. Instead of\nsummarizing the conversation you emit precise Create, Update, or Delete edits\nto reusable state: prompt notes, memories, skills, and subagent specs.\n\nRules:\n- The base system prompt is immutable and MUST NOT be rewritten (never edit id \"base_system_prompt\").\n- Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.\n- prompt = narrow behavioral policy addendums; memory = ONE FACT per entry, typed via metadata.memoryType\n-   (user = who the user is; feedback = a pitfall/correction or confirmed approach, MUST carry Why + How to apply;\n-   project = work goal/constraint not derivable from the repo; reference = URL/dashboard/ticket pointer).\n-   Memory rules: one fact per entry (title = one-line retrieval hook, content = the fact alone);\n-   never save what the repo already records (code structure, past fixes, git history, AGENTS.md) or what only\n-   matters to this conversation \u2014 save the non-obvious point instead; before creating, update the existing\n-   entry when one already covers the fact (creates carry metadata {memoryType} or they are rejected);\n-   skill = repeatable procedures (must carry a python reference {type:\"python\", import, callable}\n  and an arguments object); subagent = reusable delegation roles.\n- Skill entries are authored to the DSH skill quality standard\n  (skill-creator, distilled from the official deepseek-harness 11 skills;\n  the full facts are provided in the <skill_quality_standard> block below):\n  only for a REAL trigger scenario grounded in the trajectory\n  (who, in what real task, what signal) \u2014 never invent one to pad the store;\n  never duplicate the official 11 skills or existing entries; content is a\n  SKILL.md document (frontmatter routing with \"use when / do not use when\"\n  description, boundary declaration, prerequisites and exclusions, layered\n  information, verifiable completion criteria). Self-check every proposed\n  skill against the 7 structural features and state the result in its\n  reason field.\n- Repeated multi-step workflows (session start/end routines, recurring\n  wrap-up or handoff procedures) may be proposed as guidance skills:\n  kind=skill, skill_kind=\"guidance\", content = a SKILL.md document (no\n  python reference \u2014 executable skills keep requiring reference +\n  arguments). Only propose with repeated evidence in the trajectory, never\n  for one-off flows. Guidance skills materialize as discoverable SKILL.md\n  files under <skillsRoot>/<kebab-name>/SKILL.md and are always offered to\n  the user for a decision before they land.\n- Local edits are session-scoped; global edits persist across sessions.\n- Gap C2: EVERY edit MUST include a \"blastRadius\" field indicating how broadly\n  the edit applies: \"general\" (cross-project tactical rule, applies everywhere),\n  \"project\" (valid for the current project/repo), or \"session\" (one-off,\n  specific to this session's context). The review gate validates that\n  local-scope edits use \"session\" or \"project\", and global-scope edits use\n  \"general\" or \"project\". When in doubt, prefer narrower blast radius.\n- Ground every edit in evidence: the session trajectory (recent direct user\n  messages) is provided when available; prefer edits backed by it over\n  speculation, and never invent preferences the user did not express.\n- Stale entries (superseded by newer ones, never referenced in recent\n  trajectories, obsolete facts): propose action \"archive\" instead of\n  \"delete\" \u2014 archive hides the entry from injection while keeping its data\n  restorable; it requires only kind + id.\n- Output JSON only, exactly this shape:\n{\n  \"summary\": \"one sentence\",\n  \"rationale\": \"why these edits are justified by the evidence\",\n  \"expectedOutcome\": \"what should improve and how to validate it\",\n  \"edits\": [\n    {\n      \"action\": \"create|update|delete\",\n      \"kind\": \"prompt|memory|skill|subagent\",\n      \"id\": \"stable id for update/delete, optional for create\",\n      \"title\": \"required for create/update except delete\",\n      \"content\": \"required for create/update except delete\",\n      \"path\": \"optional grouping path\",\n      \"reference\": {\"type\":\"python\",\"import\":\"pkg.mod\",\"callable\":\"fn\"} ,\n      \"arguments\": {\"name\": {\"type\":\"string\",\"required\":true,\"description\":\"...\"}},\n      \"skill_kind\": \"executable|guidance (optional; skill kind only \u2014 guidance = SKILL.md document without reference)\",\n      \"metadata\": {},\n      \"reason\": \"why this edit is useful\",\n      \"blastRadius\": \"general|project|session\"\n    }\n  ]\n}";
 export interface PlanOptions {
     agent: Agent;
@@ -22,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
@@ -32,6 +39,16 @@ export interface PlanOptions {
     global?: boolean;
     signal?: AbortSignal;
     maxOutputTokens?: number;
+    /**
+     * Prefix-cache routing for the planning input. Route A prepends a
+     * session-derived message prefix and drops the auto-extracted
+     * trajectory block (an explicitly passed `trajectory` is always kept);
+     * Route B keeps the legacy flat-text input. Absent → auto-detect with
+     * the default budget.
+     */
+    prefixCache?: PrefixCacheOptions;
+    /** Direct-call token ledger destination; the planner phase is fixed by this module. */
+    tokenUsage?: TokenUsageTarget;
 }
 export declare function planWithLlm(ctx: Context, options: PlanOptions): Promise<RefinementProposal>;
 //# sourceMappingURL=planner.d.ts.map

package/lib/planner.js

@@ -1,8 +1,10 @@
 import { parseProposal } from "./plan.js";
 import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
-import { recentUserText } from "./inject.js";
+import { recentUserText, sessionEventsOf } from "./inject.js";
+import { buildPrefixMessages, detectPlannerRoute, resolvePrefixCache } from "./prefix-cache.js";
 import { skillQualityGuide } from "./skillquality.js";
 import { streamText } from "./llm-text.js";
+import { createTokenUsageObserver } from "./token-usage.js";
 export const PLANNER_SYSTEM_PROMPT = `You are the /evolve continual harness subsystem.
 
 Your job is to improve the editable continual harness state. Instead of
@@ -84,10 +86,22 @@ export async function planWithLlm(ctx, options) {
     const scopeInstruction = options.global
         ? "Requested scope: global. Only propose stable cross-session lessons, durable preferences, reusable skills/subagents, or explicitly project-qualified facts."
         : "Requested scope: local. Prefer session-scoped edits for current task progress; global entries are read-only context — do not propose update/delete for them.";
-    // Ground the plan in the caller's session: the trajectory block is the
-    // most recent direct user messages ("" when none qualify — the block is
-    // then omitted entirely, keeping an empty trajectory zero-cost).
-    const trajectory = options.trajectory ?? recentUserText(agent);
+    // Ground the plan in the caller's session: Route A carries the context
+    // 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 = options.trajectoryEvents ?? sessionEventsOf(agent);
+    const routing = resolvePrefixCache(options.prefixCache);
+    const route = detectPlannerRoute(events, routing.mode);
+    let prefixMessages = [];
+    if (route === "A") {
+        prefixMessages = buildPrefixMessages(events, {
+            ...(agent.options.provider ? { provider: agent.options.provider } : {}),
+            ...(agent.options.model ? { model: agent.options.model } : {}),
+            maxChars: routing.maxChars,
+        });
+    }
+    const trajectory = prefixMessages.length > 0 ? (options.trajectory ?? "") : (options.trajectory ?? recentUserText(agent));
     // The skill quality standard is always present: the skill-creator
     // template facts when installed, the builtin distilled guide otherwise
     // (~1KB — planning is low-frequency, and the standard keeps skill
@@ -111,6 +125,10 @@ export async function planWithLlm(ctx, options) {
         prompt: userPrompt,
         maxTokens: options.maxOutputTokens ?? 8000,
         signal: options.signal,
+        ...(prefixMessages.length > 0 ? { prefixMessages } : {}),
+        ...(options.tokenUsage
+            ? { onUsage: createTokenUsageObserver(options.tokenUsage, "planner", agent.options.provider, agent.options.model) }
+            : {}),
     });
     return parseProposal(text);
 }

package/lib/prefix-cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Prefix-cache-aware planning input routing (Route A/B).
+ *
+ * The planner and the review gate re-send session context on every call as
+ * flat text. On providers with prompt caching that context is re-billed at
+ * full price each time. Route A instead prepends session-derived messages —
+ * the same evidence in structured form, eligible for cache-read pricing —
+ * and drops the redundant flat trajectory block. Route B keeps the legacy
+ * flat-text input byte-for-byte.
+ *
+ * Adapted from dsh-continual-harness (Route A/B + cache-detect): this port
+ * deliberately does NOT reproduce the host loop's byte-identical cache key
+ * (no deriveMessages/tools/sessionId plumbing on this seam), so a hit needs
+ * a provider that keys on the message-prefix content. Sources are stamped
+ * honestly and every reduction is documented below.
+ */
+import { type AssistantMessage, type UserMessage } from "@deepseek-ai/dsh-llm";
+/** Planning input shape: A = session-derived message prefix, B = flat-text trajectory. */
+export type PlannerRoute = "A" | "B";
+/** Routing mode: auto-detect from cache evidence, always prefix, or never. */
+export type PlannerPrefixCacheMode = "auto" | "session" | "off";
+/** Per-call routing overrides; absent fields fall back to the resolved defaults. */
+export interface PrefixCacheOptions {
+    mode?: PlannerPrefixCacheMode;
+    maxChars?: number;
+}
+/** Default session-prefix budget for one Route A input, in characters. */
+export declare const DEFAULT_PREFIX_MAX_CHARS = 12000;
+/**
+ * Resolve per-call overrides against the defaults.
+ *
+ * @param opts - sparse per-call overrides.
+ * @returns the effective mode (default "auto") and char budget.
+ * @throws When maxChars is present but not a positive safe integer (fail loud on misconfiguration).
+ */
+export declare function resolvePrefixCache(opts?: PrefixCacheOptions): {
+    mode: PlannerPrefixCacheMode;
+    maxChars: number;
+};
+/**
+ * True when any assistant message in this session reported cache-read
+ * tokens — evidence the provider can serve a warm prefix.
+ *
+ * @param events - session log rows, newest last.
+ * @returns whether cache evidence exists (false on an empty/unreadable log).
+ */
+export declare function hasCacheEvidence(events: readonly unknown[]): boolean;
+/**
+ * Pick the planning input route for one call.
+ *
+ * @param events - session log rows, newest last.
+ * @param mode - routing mode (default "auto").
+ * @returns "A" when the session prefix should carry the context, else "B".
+ */
+export declare function detectPlannerRoute(events: readonly unknown[], mode?: PlannerPrefixCacheMode): PlannerRoute;
+/**
+ * Rebuild a tail-biased session prefix from the event log.
+ *
+ * Inclusion mirrors the trajectory grounding (only direct human `user`
+ * speech plus the model's own assistant text), so injected plugin context
+ * and tool results never echo back into the planning input. Whole messages
+ * are dropped oldest-first over budget; a single over-budget message keeps
+ * its tail.
+ *
+ * @param events - session log rows, newest last.
+ * @param opts - provider/model stamps the assistant messages (the calling
+ * agent's own route); maxChars caps the prefix (default {@link DEFAULT_PREFIX_MAX_CHARS}).
+ * @returns the prefix messages, oldest first ([] when nothing qualifies —
+ * callers fall back to Route B).
+ * @throws When assistant text exists but provider/model is missing (an
+ * assistant message cannot be honestly stamped without its route).
+ */
+export declare function buildPrefixMessages(events: readonly unknown[], opts: {
+    provider?: string;
+    model?: string;
+    maxChars?: number;
+}): (UserMessage | AssistantMessage)[];
+//# sourceMappingURL=prefix-cache.d.ts.map

package/lib/prefix-cache.js

@@ -0,0 +1,168 @@
+/**
+ * Prefix-cache-aware planning input routing (Route A/B).
+ *
+ * The planner and the review gate re-send session context on every call as
+ * flat text. On providers with prompt caching that context is re-billed at
+ * full price each time. Route A instead prepends session-derived messages —
+ * the same evidence in structured form, eligible for cache-read pricing —
+ * and drops the redundant flat trajectory block. Route B keeps the legacy
+ * flat-text input byte-for-byte.
+ *
+ * Adapted from dsh-continual-harness (Route A/B + cache-detect): this port
+ * deliberately does NOT reproduce the host loop's byte-identical cache key
+ * (no deriveMessages/tools/sessionId plumbing on this seam), so a hit needs
+ * a provider that keys on the message-prefix content. Sources are stamped
+ * honestly and every reduction is documented below.
+ */
+import { createAssistantMessage, createUserMessage } from "@deepseek-ai/dsh-llm";
+/** Default session-prefix budget for one Route A input, in characters. */
+export const DEFAULT_PREFIX_MAX_CHARS = 12000;
+/**
+ * Resolve per-call overrides against the defaults.
+ *
+ * @param opts - sparse per-call overrides.
+ * @returns the effective mode (default "auto") and char budget.
+ * @throws When maxChars is present but not a positive safe integer (fail loud on misconfiguration).
+ */
+export function resolvePrefixCache(opts) {
+    const mode = opts?.mode ?? "auto";
+    const maxChars = opts?.maxChars ?? DEFAULT_PREFIX_MAX_CHARS;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 1) {
+        throw new Error(`evolve: prefix-cache maxChars must be a positive integer, got ${String(opts?.maxChars)}`);
+    }
+    return { mode, maxChars };
+}
+/**
+ * True when any assistant message in this session reported cache-read
+ * tokens — evidence the provider can serve a warm prefix.
+ *
+ * @param events - session log rows, newest last.
+ * @returns whether cache evidence exists (false on an empty/unreadable log).
+ */
+export function hasCacheEvidence(events) {
+    for (const raw of events) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const event = raw;
+        if (event.type !== "assistant/message")
+            continue;
+        const read = event.data?.usage?.cacheReadTokens;
+        if (typeof read === "number" && read > 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Pick the planning input route for one call.
+ *
+ * @param events - session log rows, newest last.
+ * @param mode - routing mode (default "auto").
+ * @returns "A" when the session prefix should carry the context, else "B".
+ */
+export function detectPlannerRoute(events, mode) {
+    const resolved = mode ?? "auto";
+    if (resolved === "session")
+        return "A";
+    if (resolved === "off")
+        return "B";
+    return hasCacheEvidence(events) ? "A" : "B";
+}
+/**
+ * Extract one message's text without depending on the dsh-llm ContentBlock
+ * type: string blocks pass through, object blocks contribute their `text`
+ * field when present. Non-text blocks (tool calls, images) are dropped.
+ */
+function blockText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (typeof block === "string") {
+            parts.push(block);
+        }
+        else if (block !== null && typeof block === "object" && "text" in block && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+    }
+    return parts.filter((text) => text.length > 0).join(" ");
+}
+/**
+ * Rebuild a tail-biased session prefix from the event log.
+ *
+ * Inclusion mirrors the trajectory grounding (only direct human `user`
+ * speech plus the model's own assistant text), so injected plugin context
+ * and tool results never echo back into the planning input. Whole messages
+ * are dropped oldest-first over budget; a single over-budget message keeps
+ * its tail.
+ *
+ * @param events - session log rows, newest last.
+ * @param opts - provider/model stamps the assistant messages (the calling
+ * agent's own route); maxChars caps the prefix (default {@link DEFAULT_PREFIX_MAX_CHARS}).
+ * @returns the prefix messages, oldest first ([] when nothing qualifies —
+ * callers fall back to Route B).
+ * @throws When assistant text exists but provider/model is missing (an
+ * assistant message cannot be honestly stamped without its route).
+ */
+export function buildPrefixMessages(events, opts) {
+    const maxChars = opts.maxChars ?? DEFAULT_PREFIX_MAX_CHARS;
+    if (!Number.isSafeInteger(maxChars) || maxChars < 1) {
+        throw new Error(`evolve: prefix-cache maxChars must be a positive integer, got ${String(opts.maxChars)}`);
+    }
+    const pairs = [];
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const raw = events[i];
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const event = raw;
+        const isUser = event.type === "user/message";
+        const isAssistant = event.type === "assistant/message";
+        if (!isUser && !isAssistant)
+            continue;
+        if (isUser) {
+            const kind = event.data?.source?.kind;
+            if (kind !== undefined && kind !== "user")
+                continue;
+        }
+        const text = blockText(event.data?.content).trim();
+        if (text.length === 0)
+            continue;
+        pairs.push({ role: isUser ? "user" : "assistant", text });
+    }
+    if (pairs.length === 0)
+        return [];
+    // Collected newest-first; restore conversation order before budgeting.
+    pairs.reverse();
+    // Tail-biased budget: drop oldest whole messages over budget; a lone
+    // over-budget message keeps its tail.
+    let total = pairs.reduce((sum, pair) => sum + pair.text.length, 0);
+    while (pairs.length > 1 && total > maxChars) {
+        const dropped = pairs.shift();
+        total -= dropped?.text.length ?? 0;
+    }
+    const oldest = pairs[0];
+    if (oldest !== undefined && total > maxChars) {
+        oldest.text = oldest.text.slice(-maxChars);
+    }
+    const messages = [];
+    for (const pair of pairs) {
+        if (pair.role === "user") {
+            messages.push(createUserMessage({
+                source: { kind: "user" },
+                content: [{ type: "text", text: pair.text }],
+            }));
+        }
+        else {
+            if (!opts.provider || !opts.model) {
+                throw new Error("evolve: prefix-cache needs the agent provider/model to stamp assistant messages");
+            }
+            messages.push(createAssistantMessage({
+                source: { provider: opts.provider, model: opts.model },
+                content: [{ type: "text", text: pair.text }],
+            }));
+        }
+    }
+    return messages;
+}
+//# sourceMappingURL=prefix-cache.js.map

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

@@ -8,12 +8,14 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { HarnessState, RefinementResult } from "./types.js";
+import { type PrefixCacheOptions } from "./prefix-cache.js";
+import { type TokenUsageTarget } from "./token-usage.js";
 export interface AutoRefineReview {
     shouldRefine: boolean;
     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;
@@ -25,11 +27,22 @@ 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). */
     overrideProvider?: string;
     overrideModel?: string;
+    /**
+     * Prefix-cache routing for the gate input. Route A prepends a
+     * session-derived message prefix and drops the flat `<conversation>`
+     * block (same source, structured form); Route B keeps it. Absent →
+     * auto-detect with the default budget.
+     */
+    prefixCache?: PrefixCacheOptions;
+    /** Direct-call token ledger destination; the review phase is fixed by this module. */
+    tokenUsage?: TokenUsageTarget;
 }
 export declare const AUTO_REVIEW_SYSTEM_PROMPT = "You are the automatic /evolve review gate.\n\nDecide whether this checkpoint should run /evolve. Auto /evolve writes local\nharness state by default, so approve when the trajectory contains evidence\nuseful to this session's future turns: a repeated failure, a reusable tactic,\na repeated delegation role, a durable fact or preference, a user correction\nthat should persist, or a narrow behavioral policy.\n\nThe current harness state below includes GLOBAL entries (scope=global) plus\nthis session's local entries (scope=local). When a topic is already covered\nby a global entry, do NOT approve a local duplicate of it \u2014 decline and say\nin the rationale that the topic is already covered globally.\n\nReject one-off noise, unsupported hypotheses, transient tool outputs, and\nrequests that carry no reusable content.\n\nStale local entries (superseded, long-unused, obsolete facts) are a valid\nrefine target: approve with instructions naming the entry ids, and tell the\nplanner to archive them (archive hides from injection, data stays restorable)\nrather than delete.\n\nSkill-related trajectories (the evidence concerns creating or improving a\nskill entry) are judged against the DSH skill quality standard (skill-audit\ndimensions: frontmatter routing, the 7 structural features, paragraph\nskeleton, no duplication of the official 11 skills or covered skills).\nApprove only when the trajectory shows a REAL trigger scenario and the\nresulting skill would meet the standard; otherwise decline and say in the\nrationale what must improve \u2014 drafting follows skill-creator, and the\nplanner receives the standard as its <skill_quality_standard> block.\n\nRepeated multi-step workflows (session start/end routines, recurring\nwrap-up or handoff procedures) are a valid refine target: approve with\ninstructions telling the planner to propose a guidance skill (kind=skill,\nskill_kind=guidance \u2014 a SKILL.md document, no python reference). Only\npropose when the same workflow recurs in the trajectory \u2014 never for\none-off flows. Auto-created skills are always offered to the user for a\ndecision before they land; the gate never writes a skill silently.\n\nReturn JSON only:\n{\n  \"shouldRefine\": true|false,\n  \"rationale\": \"short reason\",\n  \"instructions\": \"optional concise instructions for /evolve if shouldRefine is true\"\n}";
 /** Parse the gate's JSON reply. */