dsh-continual-evolve 0.7.0 → 0.7.1

package/lib/index.d.ts

@@ -18,6 +18,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     maxReviewInputChars: z<number, number, "defined">;
     /** Output budget for the cheap gate call. */
     reviewBudgetTokens: z<number, number, "defined">;
+    /**
+     * Planner prefix-cache routing for the gate and planner inputs: `auto`
+     * prepends a session-derived message prefix when the session shows
+     * cache-read evidence (dropping the redundant flat trajectory text),
+     * `session` always prefixes, `off` keeps the legacy flat-text input.
+     */
+    plannerPrefixCache: z<"session" | "off" | "auto", "session" | "off" | "auto", "defined">;
+    /** Session-prefix budget for Route A planning inputs, in characters. */
+    plannerPrefixMaxChars: z<number, number, "defined">;
     /** After an approved gate run with applied edits, queue a visible follow-up notice. */
     notifyOnAutoReview: z<boolean, boolean, "defined">;
     /** Cross-session (global) edits require an explicit human approval. */
@@ -74,6 +83,25 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     promotionMinChars: z<number, number, "defined">;
     /** Entry-directory lines injected per build before folding into a counter. */
     injectionDirectoryLines: z<number, number, "defined">;
+    /**
+     * Storage hygiene (#20): how much append-only past each write keeps.
+     * `snapshots` = full-state copies per store, `refinements` = tail lines
+     * per store history, `reviews` = tail lines of the shared audit trail,
+     * `tokenUsage` = tail lines of the direct-call token ledger.
+     * Absent fields fall back to the store defaults (20 / 500 / 500 / 500) —
+     * rollback needs recent snapshots, readers need a recent window.
+     */
+    historyRetain: z<Schemastery.ObjectS<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, "plain">;
 }>>, Schemastery.ObjectT<NoInfer<{
     /** Root for evolution stores; defaults to the resolved DSH home. */
     baseDir: z<string, string, "plain">;
@@ -87,6 +115,15 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     maxReviewInputChars: z<number, number, "defined">;
     /** Output budget for the cheap gate call. */
     reviewBudgetTokens: z<number, number, "defined">;
+    /**
+     * Planner prefix-cache routing for the gate and planner inputs: `auto`
+     * prepends a session-derived message prefix when the session shows
+     * cache-read evidence (dropping the redundant flat trajectory text),
+     * `session` always prefixes, `off` keeps the legacy flat-text input.
+     */
+    plannerPrefixCache: z<"session" | "off" | "auto", "session" | "off" | "auto", "defined">;
+    /** Session-prefix budget for Route A planning inputs, in characters. */
+    plannerPrefixMaxChars: z<number, number, "defined">;
     /** After an approved gate run with applied edits, queue a visible follow-up notice. */
     notifyOnAutoReview: z<boolean, boolean, "defined">;
     /** Cross-session (global) edits require an explicit human approval. */
@@ -143,6 +180,25 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     promotionMinChars: z<number, number, "defined">;
     /** Entry-directory lines injected per build before folding into a counter. */
     injectionDirectoryLines: z<number, number, "defined">;
+    /**
+     * Storage hygiene (#20): how much append-only past each write keeps.
+     * `snapshots` = full-state copies per store, `refinements` = tail lines
+     * per store history, `reviews` = tail lines of the shared audit trail,
+     * `tokenUsage` = tail lines of the direct-call token ledger.
+     * Absent fields fall back to the store defaults (20 / 500 / 500 / 500) —
+     * rollback needs recent snapshots, readers need a recent window.
+     */
+    historyRetain: z<Schemastery.ObjectS<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        snapshots: z<number, number, "plain">;
+        refinements: z<number, number, "plain">;
+        reviews: z<number, number, "plain">;
+        tokenUsage: z<number, number, "plain">;
+    }>>, "plain">;
 }>>, "plain">;
 /**
  * Structurally typed resolved config (loader passes the validated object).

package/lib/index.js

@@ -37,6 +37,15 @@ export const Config = z.object({
     maxReviewInputChars: z.natural().default(40000),
     /** Output budget for the cheap gate call. */
     reviewBudgetTokens: z.natural().default(4096),
+    /**
+     * Planner prefix-cache routing for the gate and planner inputs: `auto`
+     * prepends a session-derived message prefix when the session shows
+     * cache-read evidence (dropping the redundant flat trajectory text),
+     * `session` always prefixes, `off` keeps the legacy flat-text input.
+     */
+    plannerPrefixCache: z.union([z.const("auto"), z.const("session"), z.const("off")]).default("auto"),
+    /** Session-prefix budget for Route A planning inputs, in characters. */
+    plannerPrefixMaxChars: z.natural().default(12000),
     /** After an approved gate run with applied edits, queue a visible follow-up notice. */
     notifyOnAutoReview: z.boolean().default(true),
     /** Cross-session (global) edits require an explicit human approval. */
@@ -93,6 +102,20 @@ export const Config = z.object({
     promotionMinChars: z.natural().default(100),
     /** Entry-directory lines injected per build before folding into a counter. */
     injectionDirectoryLines: z.natural().default(15),
+    /**
+     * Storage hygiene (#20): how much append-only past each write keeps.
+     * `snapshots` = full-state copies per store, `refinements` = tail lines
+     * per store history, `reviews` = tail lines of the shared audit trail,
+     * `tokenUsage` = tail lines of the direct-call token ledger.
+     * Absent fields fall back to the store defaults (20 / 500 / 500 / 500) —
+     * rollback needs recent snapshots, readers need a recent window.
+     */
+    historyRetain: z.object({
+        snapshots: z.natural(),
+        refinements: z.natural(),
+        reviews: z.natural(),
+        tokenUsage: z.natural(),
+    }),
 });
 export function apply(ctx, config) {
     const baseDir = resolveDshHome(config.baseDir);
@@ -111,7 +134,7 @@ export function apply(ctx, config) {
                     .warn(`skill materialization failed for ${result.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
             }
         },
-    });
+    }, config.historyRetain ? { historyRetain: { ...config.historyRetain } } : {});
     ctx.provide(EVOLUTION_SERVICE, { engine, baseDir });
     ctx.systemPrompt.section({
         name: "tool:continual-evolve",
@@ -139,6 +162,7 @@ export function apply(ctx, config) {
         autoRollbackOnReject: config.autoRollbackOnReject ?? true,
         autoCase: config.autoCase ?? true,
         promotionPolicy,
+        ...(config.autoReview !== undefined ? { autoReview: config.autoReview } : {}),
     });
     // Plugin-owned file logging: every cordis log message lands in
     // <baseDir>/evolve/plugin.log regardless of how dsh web was launched —
@@ -165,7 +189,10 @@ export function apply(ctx, config) {
             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)`);
     }

package/lib/llm-text.d.ts

@@ -9,6 +9,16 @@
  * and JSON parsing.
  */
 import type { Context } from "@deepseek-ai/cordis";
+import { type Message, type TokenUsage } from "@deepseek-ai/dsh-llm";
+/** Terminal outcome of one shared direct LLM call. */
+export type StreamTextOutcome = "success" | "max-tokens" | "error" | "aborted" | "empty";
+/** Provider usage and terminal result observed after the stream settles. */
+export interface StreamTextObservation {
+    usage?: TokenUsage;
+    outcome: StreamTextOutcome;
+}
+/** Diagnostic observer invoked before streamText returns or throws. */
+export type StreamTextUsageObserver = (observation: StreamTextObservation) => void;
 export interface StreamTextOptions {
     provider: string;
     model: string;
@@ -16,6 +26,19 @@ export interface StreamTextOptions {
     prompt: string;
     maxTokens?: number;
     signal?: AbortSignal | undefined;
+    /**
+     * Route A session prefix: session-derived messages sent before the
+     * trailing caller message so providers with prompt caching can serve
+     * the shared context at cache-read price. Empty/omitted keeps the
+     * legacy single-message request.
+     */
+    prefixMessages?: readonly Message[];
+    /**
+     * Observe the provider-reported usage and terminal outcome after the
+     * stream settles. The callback runs before success/error return and is
+     * diagnostic-only: throwing from it never changes the model call result.
+     */
+    onUsage?: StreamTextUsageObserver;
 }
 /**
  * Stream a single-turn text completion through `ctx.llm`. Forces

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;
@@ -32,6 +34,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 = 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.d.ts

@@ -8,6 +8,8 @@
 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;
@@ -30,6 +32,15 @@ export interface ReviewOptions {
     /** 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. */