dsh-continual-evolve 0.6.1 → 0.7.1

package/lib/inject.d.ts

@@ -114,20 +114,42 @@ export declare function formatPromptEntriesSection(entries: readonly HarnessEntr
 export declare function formatSubagentSpecsSection(entries: readonly HarnessEntry[], query?: string): string;
 /**
  * Gap B3: a lightweight directory of ALL non-archived entries across all
- * kinds — one line per entry (`- [kind:id] title`), no content. This gives
- * the model a zero-cost overview of what exists so it can ask for full text
- * via `evolve_list` or `/evolve list`. The directory is appended after the
- * curated top-N injection sections and adds minimal tokens.
+ * kinds — one line per entry, no content. Memory lines carry their recall
+ * type (`- [memory:feedback:id] title`) so the model can judge relevance
+ * from the index alone. This gives the model a zero-cost overview of what
+ * exists so it can ask for full text via `evolve_list` or `/evolve list`.
+ * The directory is appended after the curated top-N injection sections and
+ * adds minimal tokens.
  *
  * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
- * lines (oldest-sorted stable order) with the remainder folded into a single
- * counter line — an uncapped directory across a polluted global store was
- * measured at ~2K chars of every build in every project.
+ * lines with the remainder folded into a single counter line — an uncapped
+ * directory across a polluted global store was measured at ~2K chars of
+ * every build in every project.
+ *
+ * 2026-09-23 relevance order: the directory is sorted by
+ * {@link rankEntries} against the assembly's relevance query, so the lines
+ * folded below the cap are the least relevant — not the dictionary tail.
  */
 export declare const DEFAULT_DIRECTORY_LINES = 15;
+/** One directory index line: memory lines carry their recall-type hook. */
+export declare function directoryLine(entry: HarnessEntry): string;
 export declare function formatEntriesDirectory(...kindEntries: readonly HarnessEntry[][]): string;
 /** {@link formatEntriesDirectory} with an explicit cap (configurable). */
 export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEntries: readonly HarnessEntry[][]): string;
+/**
+ * {@link formatEntriesDirectoryCapped} with a relevance query: entries are
+ * ordered by {@link rankEntries} (relevance first, then recency) so the cap
+ * folds the least relevant entries — never the dictionary tail. An empty
+ * query degrades to the valence/recency/stable order, still deterministic.
+ */
+export declare function formatEntriesDirectoryRanked(maxLines: number, query: string | undefined, ...kindEntries: readonly HarnessEntry[][]): string;
+/**
+ * The directory entries actually shown under the cap, in display order —
+ * the single source for both the rendered text and usage accounting (so a
+ * memory's injection IS its directory line even with the `:type` hook).
+ * Returns [] when the directory is suppressed or empty.
+ */
+export declare function rankedDirectoryEntries(maxLines: number, query: string | undefined, ...kindEntries: readonly HarnessEntry[][]): HarnessEntry[];
 /**
  * Walk the parent-session chain from `agent` upward and return the nearest
  * session whose local store is non-empty, if any. Children inherit their
@@ -138,19 +160,23 @@ export declare function formatEntriesDirectoryCapped(maxLines: number, ...kindEn
 export declare function nearestLocalStateWithEntries(engine: EvolutionEngine, agent: AgentLike): HarnessState | undefined;
 /**
  * Compose the full injected block for one assembling agent: global entries
- * merged with the nearest carrying local store (local wins on id collision).
+ * merged with this project's store (when the session cwd resolves one) and
+ * the nearest carrying local store (precedence global < project < local).
  * The optional `query` — when absent, derived from the agent's most recent
  * direct user messages — ranks which entries fill the per-kind cap
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
  *
- * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle);
+ * `opts.projectKey` pins the project layer explicitly (tests, tools) —
+ * otherwise it is derived from the agent's session cwd, best-effort.
  * Usage recording covers ALL kinds — memories and skills appear as directory
  * lines, prompts/subagents as content — and is deduped per session so the
  * counts read "how many sessions saw this", not "how many prompt builds".
  */
 export declare function entriesSectionText(engine: EvolutionEngine, agent: AgentLike | undefined, query?: string, opts?: {
     directoryLines?: number;
+    projectKey?: string;
 }): string;
 //# sourceMappingURL=inject.d.ts.map

package/lib/inject.js

@@ -1,5 +1,6 @@
-import { isArchived, VALENCE_NEGATIVE_KEY } from "./types.js";
+import { MEMORY_TYPE_KEY, isArchived, isMemoryType, VALENCE_NEGATIVE_KEY } from "./types.js";
 import { mergeHarnessStates } from "./state.js";
+import { projectKeyOf } from "./project.js";
 import { entryLine } from "./render.js";
 import { recordInjection } from "./usage.js";
 import { buildRelevanceIndex, relevanceScore, tokenize } from "./search.js";
@@ -214,27 +215,81 @@ export function formatSubagentSpecsSection(entries, query) {
 }
 /**
  * Gap B3: a lightweight directory of ALL non-archived entries across all
- * kinds — one line per entry (`- [kind:id] title`), no content. This gives
- * the model a zero-cost overview of what exists so it can ask for full text
- * via `evolve_list` or `/evolve list`. The directory is appended after the
- * curated top-N injection sections and adds minimal tokens.
+ * kinds — one line per entry, no content. Memory lines carry their recall
+ * type (`- [memory:feedback:id] title`) so the model can judge relevance
+ * from the index alone. This gives the model a zero-cost overview of what
+ * exists so it can ask for full text via `evolve_list` or `/evolve list`.
+ * The directory is appended after the curated top-N injection sections and
+ * adds minimal tokens.
  *
  * 2026-08-22 throttle: the directory is CAPPED at {@link DEFAULT_DIRECTORY_LINES}
- * lines (oldest-sorted stable order) with the remainder folded into a single
- * counter line — an uncapped directory across a polluted global store was
- * measured at ~2K chars of every build in every project.
+ * lines with the remainder folded into a single counter line — an uncapped
+ * directory across a polluted global store was measured at ~2K chars of
+ * every build in every project.
+ *
+ * 2026-09-23 relevance order: the directory is sorted by
+ * {@link rankEntries} against the assembly's relevance query, so the lines
+ * folded below the cap are the least relevant — not the dictionary tail.
  */
 export const DEFAULT_DIRECTORY_LINES = 15;
-/** How many of the variadic arrays are content-section kinds (prompt, subagent). */
+/** One directory index line: memory lines carry their recall-type hook. */
+export function directoryLine(entry) {
+    if (entry.kind === "memory") {
+        const type = entry.metadata[MEMORY_TYPE_KEY];
+        const hook = isMemoryType(type) ? `:${type}` : "";
+        return `- [memory${hook}:${entry.id}] ${entry.title}`;
+    }
+    return `- [${entry.kind}:${entry.id}] ${entry.title}`;
+}
+/** Positional contract for the directory variadics: the first two arrays
+ * must be the content-section kinds (prompt, subagent) — the redundancy
+ * check counts exactly those as already visible. Callers pass
+ * (prompt, subagent, memory, skill); any other order miscounts. */
 const CONTENT_SECTION_KINDS = 2;
 export function formatEntriesDirectory(...kindEntries) {
     return formatEntriesDirectoryCapped(DEFAULT_DIRECTORY_LINES, ...kindEntries);
 }
 /** {@link formatEntriesDirectory} with an explicit cap (configurable). */
 export function formatEntriesDirectoryCapped(maxLines, ...kindEntries) {
+    return formatEntriesDirectoryRanked(maxLines, undefined, ...kindEntries);
+}
+/**
+ * {@link formatEntriesDirectoryCapped} with a relevance query: entries are
+ * ordered by {@link rankEntries} (relevance first, then recency) so the cap
+ * folds the least relevant entries — never the dictionary tail. An empty
+ * query degrades to the valence/recency/stable order, still deterministic.
+ */
+export function formatEntriesDirectoryRanked(maxLines, query, ...kindEntries) {
+    const total = kindEntries.flat().filter((e) => !isArchived(e)).length;
+    if (total === 0) {
+        return "";
+    }
+    // Suppressed (every entry already content-visible) renders as "" — the
+    // prompt renderer then drops the section entirely.
+    const shown = rankedDirectoryEntries(maxLines, query, ...kindEntries);
+    if (shown.length === 0) {
+        return "";
+    }
+    const lines = ["# Continual Harness — Entry Directory", "All entries (use evolve_list for full text of any entry):"];
+    for (const entry of shown) {
+        lines.push(directoryLine(entry));
+    }
+    const hidden = total - shown.length;
+    if (hidden > 0) {
+        lines.push(`- …and ${hidden} more entries (evolve_list for the full index)`);
+    }
+    return lines.join("\n");
+}
+/**
+ * The directory entries actually shown under the cap, in display order —
+ * the single source for both the rendered text and usage accounting (so a
+ * memory's injection IS its directory line even with the `:type` hook).
+ * Returns [] when the directory is suppressed or empty.
+ */
+export function rankedDirectoryEntries(maxLines, query, ...kindEntries) {
     const allEntries = kindEntries.flat().filter((e) => !isArchived(e));
     if (allEntries.length === 0) {
-        return "";
+        return [];
     }
     // Skip the directory only when EVERY entry is already content-visible.
     // Only the first two arrays (prompt, subagent) have curated sections —
@@ -245,19 +300,9 @@ export function formatEntriesDirectoryCapped(maxLines, ...kindEntries) {
         .slice(0, CONTENT_SECTION_KINDS)
         .reduce((sum, entries) => sum + Math.min(entries.filter((e) => !isArchived(e)).length, MAX_INJECTED_ENTRIES_PER_KIND), 0);
     if (allEntries.length <= contentVisible) {
-        return "";
-    }
-    const sorted = [...allEntries].sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
-    const lines = ["# Continual Harness — Entry Directory", "All entries (use evolve_list for full text of any entry):"];
-    const shown = sorted.slice(0, Math.max(maxLines, 1));
-    for (const entry of shown) {
-        lines.push(`- [${entry.kind}:${entry.id}] ${entry.title}`);
-    }
-    const hidden = sorted.length - shown.length;
-    if (hidden > 0) {
-        lines.push(`- …and ${hidden} more entries (evolve_list for the full index)`);
+        return [];
     }
-    return lines.join("\n");
+    return rankEntries(allEntries, query).slice(0, Math.max(maxLines, 1));
 }
 /**
  * Walk the parent-session chain from `agent` upward and return the nearest
@@ -281,14 +326,17 @@ export function nearestLocalStateWithEntries(engine, agent) {
 }
 /**
  * Compose the full injected block for one assembling agent: global entries
- * merged with the nearest carrying local store (local wins on id collision).
+ * merged with this project's store (when the session cwd resolves one) and
+ * the nearest carrying local store (precedence global < project < local).
  * The optional `query` — when absent, derived from the agent's most recent
  * direct user messages — ranks which entries fill the per-kind cap
  * (relevance first, then recency; see {@link rankEntries}). Returns "" when
  * nothing is injectable — the prompt renderer then drops the section, so an
  * empty store adds zero tokens to every assembly.
  *
- * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle).
+ * `opts.directoryLines` caps the entry-directory index (2026-08-22 throttle);
+ * `opts.projectKey` pins the project layer explicitly (tests, tools) —
+ * otherwise it is derived from the agent's session cwd, best-effort.
  * Usage recording covers ALL kinds — memories and skills appear as directory
  * lines, prompts/subagents as content — and is deduped per session so the
  * counts read "how many sessions saw this", not "how many prompt builds".
@@ -298,8 +346,10 @@ export function entriesSectionText(engine, agent, query, opts) {
         return "";
     }
     const globalState = engine.load("global", undefined);
+    const projectKey = opts?.projectKey ?? projectKeyOf(agent);
+    const projectState = projectKey ? engine.load("project", projectKey) : undefined;
     const localState = nearestLocalStateWithEntries(engine, agent);
-    const merged = localState ? mergeHarnessStates(globalState, localState) : globalState;
+    const merged = mergeHarnessStates(globalState, localState, projectState ? { projectState } : undefined);
     const promptEntries = Object.values(merged.entries.prompt);
     const subagentEntries = Object.values(merged.entries.subagent);
     const relevanceQuery = (query ?? recentUserText(agent)).trim();
@@ -318,18 +368,18 @@ export function entriesSectionText(engine, agent, query, opts) {
     }
     // Gap B3: lightweight directory of ALL entries (id+title, one line each).
     // Zero-cost index so the model knows what exists and can ask for full text.
-    const directoryText = formatEntriesDirectoryCapped(opts?.directoryLines ?? DEFAULT_DIRECTORY_LINES, Object.values(merged.entries.prompt), Object.values(merged.entries.memory), Object.values(merged.entries.skill), Object.values(merged.entries.subagent));
+    const directoryLines = opts?.directoryLines ?? DEFAULT_DIRECTORY_LINES;
+    const promptKind = Object.values(merged.entries.prompt);
+    const subagentKind = Object.values(merged.entries.subagent);
+    const memoryKind = Object.values(merged.entries.memory);
+    const skillKind = Object.values(merged.entries.skill);
+    const directoryText = formatEntriesDirectoryRanked(directoryLines, relevanceQuery, promptKind, subagentKind, memoryKind, skillKind);
     // Directory-visible keys count too: a memory's injection IS its directory
-    // line. Set semantics keep content-injected entries single-counted.
-    for (const kind of ["prompt", "memory", "skill", "subagent"]) {
-        for (const entry of Object.values(merged.entries[kind])) {
-            if (isArchived(entry))
-                continue;
-            const key = `${kind}:${entry.id}`;
-            if (injectedKeys.has(key) || directoryText.includes(`[${key}]`)) {
-                injectedKeys.add(key);
-            }
-        }
+    // line. Set semantics keep content-injected entries single-counted. Keys
+    // come from the single display-ordered source (type hooks included), not
+    // substring matching on the rendered text.
+    for (const entry of rankedDirectoryEntries(directoryLines, relevanceQuery, promptKind, subagentKind, memoryKind, skillKind)) {
+        injectedKeys.add(`${entry.kind}:${entry.id}`);
     }
     // Record usage durably (best-effort: failure never blocks injection).
     // Deduped per session — see recordInjection.

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,7 +9,9 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { HarnessState, RefinementProposal, RefinementResult } from "./types.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 = durable facts/preferences/failures;\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}";
+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;
     state: HarnessState;
@@ -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
@@ -12,8 +14,14 @@ to reusable state: prompt notes, memories, skills, and subagent specs.
 Rules:
 - The base system prompt is immutable and MUST NOT be rewritten (never edit id "base_system_prompt").
 - Prefer small evidence-backed edits. If no useful edit is justified, return an empty edits array.
-- prompt = narrow behavioral policy addendums; memory = durable facts/preferences/failures;
-  skill = repeatable procedures (must carry a python reference {type:"python", import, callable}
+- prompt = narrow behavioral policy addendums; memory = ONE FACT per entry, typed via metadata.memoryType
+-   (user = who the user is; feedback = a pitfall/correction or confirmed approach, MUST carry Why + How to apply;
+-   project = work goal/constraint not derivable from the repo; reference = URL/dashboard/ticket pointer).
+-   Memory rules: one fact per entry (title = one-line retrieval hook, content = the fact alone);
+-   never save what the repo already records (code structure, past fixes, git history, AGENTS.md) or what only
+-   matters to this conversation — save the non-obvious point instead; before creating, update the existing
+-   entry when one already covers the fact (creates carry metadata {memoryType} or they are rejected);
+-   skill = repeatable procedures (must carry a python reference {type:"python", import, callable}
   and an arguments object); subagent = reusable delegation roles.
 - Skill entries are authored to the DSH skill quality standard
   (skill-creator, distilled from the official deepseek-harness 11 skills;
@@ -78,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
@@ -105,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