dsh-continual-evolve 0.11.0 → 0.12.0

package/lib/notify.d.ts

@@ -1,48 +0,0 @@
-/**
- * Memory-extraction visibility: the extractor works in the background —
- * the user would never see a persisted entry or the token spend. This
- * module queues a short follow-up turn after an applied extraction moment
- * so the user SEES what was persisted, how to inspect it, and how to roll
- * it back.
- *
- * The receipt is a `continual-evolve`-sourced user message (`agent.followup`),
- * so it is rendered in the session transcript like any other input and the
- * agent answers with a one-line confirmation. It never fakes tool or assistant
- * events, so session replay, the ordered surface, and derived history stay
- * untouched: the receipt is a plain `user/message` carrying this plugin's own
- * source kind.
- *
- * Every mechanical property stays in code: the receipt text is built from the
- * applied refinement batches, never from model text.
- */
-import type { Context } from "@deepseek-ai/cordis";
-import type { Agent } from "@deepseek-ai/dsh-agent";
-import type { RefinementResult } from "./types.js";
-/** Unified extraction receipt: one shape for applied / declined / no-op. */
-export interface MemoryReceipt {
-    outcome: "applied" | "declined" | "noop";
-    /** Applied refinement batches (one per scope) for applied outcomes. */
-    results?: RefinementResult[];
-    /** Scopes the human explicitly declined. */
-    declinedScopes?: string[];
-    /** Extractor loop turns / manifest searches / wall time. */
-    turns: number;
-    searches: number;
-    durationMs: number;
-}
-/**
- * Compose the user-visible memory receipt from applied refinement batches
- * (never model text): every landed memory edit with its rollback command.
- * No-op and declined-only outcomes render one quiet line each — a foreground
- * notice for zero landed edits would be nagging, so callers only queue
- * follow-ups for applied outcomes.
- */
-export declare function buildMemoryReceipt(receipt: MemoryReceipt): string;
-/**
- * Queue the memory receipt follow-up. Same containment as the gate notice:
- * notification failure only logs. Callers gate on applied outcomes — no-op
- * and declined-only runs stay audit-only (reviews.jsonl) and never wake
- * the agent.
- */
-export declare function notifyMemoryExtraction(ctx: Context, agent: Agent, receipt: MemoryReceipt): void;
-//# sourceMappingURL=notify.d.ts.map

package/lib/notify.js

@@ -1,57 +0,0 @@
-import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
-/**
- * Compose the user-visible memory receipt from applied refinement batches
- * (never model text): every landed memory edit with its rollback command.
- * No-op and declined-only outcomes render one quiet line each — a foreground
- * notice for zero landed edits would be nagging, so callers only queue
- * follow-ups for applied outcomes.
- */
-export function buildMemoryReceipt(receipt) {
-    const seconds = (receipt.durationMs / 1000).toFixed(1);
-    const stats = `${receipt.turns} 轮推理 / ${receipt.searches} 次检索 / ${seconds}s`;
-    if (receipt.outcome === "noop") {
-        return `🧠 记忆提取：本轮无可沉淀的持久事实（no-op，${stats}），未写入任何条目。`;
-    }
-    const results = receipt.results ?? [];
-    const declinedScopes = receipt.declinedScopes ?? [];
-    if (receipt.outcome === "declined" || results.length === 0) {
-        const scopes = declinedScopes.join("、") || "持久化作用域";
-        return `🧠 记忆提取：${scopes}的写入未获批准，已跳过（${stats}），未写入任何条目。`;
-    }
-    const applied = results.flatMap((result) => result.appliedEdits.filter((edit) => edit.applied));
-    const lines = applied.slice(0, 12).map((edit) => `- 记忆「${edit.title ?? edit.id}」（${edit.id}）`);
-    if (applied.length > 12)
-        lines.push(`- …另有 ${applied.length - 12} 条（见 /evolve history）`);
-    const declined = declinedScopes.length > 0 ? `\n另有作用域${declinedScopes.join("、")}未经批准（已跳过）。` : "";
-    const rollbacks = [...new Set(results.map((result) => result.id))].map((id) => `/evolve rollback ${id}`).join("；");
-    return [
-        `🧠 记忆提取：本轮沉淀 ${applied.length} 条记忆（${results.length} 个作用域批次，${stats}）：`,
-        lines.length > 0 ? lines.join("\n") : "（无条目成功应用）",
-        declined,
-        `回看：/evolve recall <关键词>；回滚：${rollbacks}`,
-        "请用一句话简短确认即可，不要调用任何工具。",
-    ]
-        .filter((part) => part !== "")
-        .join("\n");
-}
-/**
- * Queue the memory receipt follow-up. Same containment as the gate notice:
- * notification failure only logs. Callers gate on applied outcomes — no-op
- * and declined-only runs stay audit-only (reviews.jsonl) and never wake
- * the agent.
- */
-export function notifyMemoryExtraction(ctx, agent, receipt) {
-    try {
-        agent.followup(createUserMessage({
-            content: [{ type: "text", text: buildMemoryReceipt(receipt) }],
-            source: EVOLVE_MESSAGE_SOURCE,
-        }));
-    }
-    catch (cause) {
-        ctx
-            .logger("continual-evolve")
-            .warn(`memory receipt notice failed for ${agent.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
-    }
-}
-//# sourceMappingURL=notify.js.map

package/lib/plan-command.d.ts

@@ -1,12 +0,0 @@
-/**
- * `/evolve plan` — the manual LLM planner path: propose edits against one
- * store with the main-session model, ask for approval on persistent scopes,
- * and apply with the normal baseline checks.
- */
-import type { Context } from "@deepseek-ai/cordis";
-import type { CommandInvocation } from "@deepseek-ai/dsh-commands";
-import type { HarnessScope } from "./types.js";
-import type { EvolutionEngine } from "./service.js";
-import { type CommandGateOptions, type CommandRuntimeOptions, type CommandTextResult } from "./command-util.js";
-export declare function executePlanCommand(ctx: Context, engine: EvolutionEngine, invocation: CommandInvocation, scope: HarnessScope, after: string[], opts: CommandGateOptions, runtime: CommandRuntimeOptions): Promise<CommandTextResult>;
-//# sourceMappingURL=plan-command.d.ts.map

package/lib/plan-command.js

@@ -1,38 +0,0 @@
-import { join } from "node:path";
-import { planWithLlm } from "./planner.js";
-import { requireGlobalApproval } from "./approval.js";
-import { entrySourceOf } from "./source.js";
-import { renderResult, storeIdForCommand, success } from "./command-util.js";
-export async function executePlanCommand(ctx, engine, invocation, scope, after, opts, runtime) {
-    const instructions = after.length > 0 ? after.join(" ") : undefined;
-    const sessionId = invocation.agent.id;
-    const state = engine.load(scope, storeIdForCommand(scope, invocation));
-    const history = engine.history(scope, storeIdForCommand(scope, invocation));
-    const proposal = await planWithLlm(ctx, {
-        agent: invocation.agent,
-        state,
-        history,
-        ...(instructions ? { instructions } : {}),
-        global: scope === "global",
-        signal: invocation.signal,
-        tokenUsage: {
-            baseDir: engine.baseDir,
-            sessionId,
-            retain: engine.retention.tokenUsage,
-            onError: (cause) => ctx.logger("continual-evolve").warn(`token-usage ledger failed for ${sessionId}: ${cause instanceof Error ? cause.message : String(cause)}`),
-        },
-        // skill-creator template facts (fallback: builtin guide).
-        skillsRoot: join(engine.baseDir, "skills"),
-    });
-    if ((scope === "global" || scope === "project") && opts.requireGlobalApproval && proposal.edits.length > 0) {
-        await requireGlobalApproval(ctx, invocation.agent, invocation.signal, `/evolve plan ${scope} 将应用 ${proposal.edits.length} 条编辑到${scope === "project" ? "本项目" : "跨会话"} store：${proposal.summary}`, runtime.recordLanguage);
-    }
-    const source = entrySourceOf(invocation.agent, sessionId);
-    const result = engine.apply(scope, storeIdForCommand(scope, invocation), proposal, {
-        scope,
-        baselineState: state,
-        ...(source ? { source } : {}),
-    });
-    return success(renderResult(result));
-}
-//# sourceMappingURL=plan-command.js.map

package/lib/plan.d.ts

@@ -1,16 +0,0 @@
-/**
- * Parsing helpers for the model-produced proposal JSON. A planner reply is
- * untrusted text: it may carry prose, a fenced block, or be truncated by an
- * exhausted output budget. These helpers recover the JSON object when
- * possible and name the cause (truncation vs malformed) when not.
- */
-import type { RefinementProposal } from "./types.js";
-/** True when the text ends mid-string or with unclosed brackets. */
-export declare function isIncompleteJson(candidate: string): boolean;
-/** Parse a JSON candidate, distinguishing truncation from malformation. */
-export declare function parseJsonCandidate(candidate: string): unknown;
-/** Recover a JSON object from raw model text. */
-export declare function extractJsonObject(text: string): unknown;
-/** Parse and shape a proposal, dropping non-object edits. */
-export declare function parseProposal(text: string): RefinementProposal;
-//# sourceMappingURL=plan.d.ts.map

package/lib/plan.js

@@ -1,126 +0,0 @@
-/** True when the text ends mid-string or with unclosed brackets. */
-export function isIncompleteJson(candidate) {
-    let depth = 0;
-    let inString = false;
-    let escaped = false;
-    for (const char of candidate) {
-        if (escaped) {
-            escaped = false;
-            continue;
-        }
-        if (inString) {
-            if (char === "\\")
-                escaped = true;
-            else if (char === '"')
-                inString = false;
-            continue;
-        }
-        if (char === '"')
-            inString = true;
-        else if (char === "{" || char === "[")
-            depth++;
-        else if (char === "}" || char === "]")
-            depth--;
-    }
-    return inString || depth > 0;
-}
-/** Parse a JSON candidate, distinguishing truncation from malformation. */
-export function parseJsonCandidate(candidate) {
-    try {
-        return JSON.parse(candidate);
-    }
-    catch (error) {
-        if (isIncompleteJson(candidate)) {
-            throw new Error("the model stopped before completing its JSON object (output budget exhausted?)");
-        }
-        throw new Error(`the model did not return valid JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-/** Recover a JSON object from raw model text. */
-export function extractJsonObject(text) {
-    const trimmed = text.trim();
-    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
-        return parseJsonCandidate(trimmed);
-    }
-    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (fenced) {
-        return parseJsonCandidate(fenced[1]?.trim() ?? "");
-    }
-    const start = trimmed.indexOf("{");
-    const end = trimmed.lastIndexOf("}");
-    if (start !== -1 && end > start) {
-        try {
-            return JSON.parse(trimmed.slice(start, end + 1));
-        }
-        catch {
-            return parseJsonCandidate(trimmed.slice(start));
-        }
-    }
-    if (isIncompleteJson(trimmed)) {
-        throw new Error("the model stopped before completing its JSON object (output budget exhausted?)");
-    }
-    throw new Error("the planner did not return a JSON object");
-}
-function asString(value) {
-    return typeof value === "string" ? value : undefined;
-}
-function asRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        return undefined;
-    }
-    return value;
-}
-/** Assign a string field only when it is present, honoring exactOptionalPropertyTypes. */
-function assignIfString(target, key, value) {
-    const str = asString(value);
-    if (str !== undefined) {
-        target[key] = str;
-    }
-}
-/** Parse and shape a proposal, dropping non-object edits. */
-export function parseProposal(text) {
-    const value = extractJsonObject(text);
-    const record = asRecord(value);
-    if (!record) {
-        throw new Error("the planner JSON must be an object");
-    }
-    const edits = [];
-    if (Array.isArray(record["edits"])) {
-        for (const raw of record["edits"]) {
-            const edit = asRecord(raw);
-            if (!edit)
-                continue;
-            const built = {
-                action: asString(edit["action"]),
-                kind: asString(edit["kind"]),
-            };
-            assignIfString(built, "id", edit["id"]);
-            assignIfString(built, "title", edit["title"]);
-            assignIfString(built, "content", edit["content"]);
-            assignIfString(built, "path", edit["path"]);
-            assignIfString(built, "reason", edit["reason"]);
-            // Gap C2: validate blastRadius values.
-            const br = asString(edit["blastRadius"]);
-            if (br === "general" || br === "project" || br === "session") {
-                built.blastRadius = br;
-            }
-            const reference = asRecord(edit["reference"]);
-            if (reference)
-                built.reference = reference;
-            const argumentsRecord = asRecord(edit["arguments"]);
-            if (argumentsRecord)
-                built.arguments = argumentsRecord;
-            const metadata = asRecord(edit["metadata"]);
-            if (metadata)
-                built.metadata = metadata;
-            edits.push(built);
-        }
-    }
-    return {
-        summary: asString(record["summary"]) ?? "Refined harness state",
-        rationale: asString(record["rationale"]) ?? "",
-        expectedOutcome: asString(record["expectedOutcome"]) ?? "",
-        edits,
-    };
-}
-//# sourceMappingURL=plan.js.map

package/lib/planner.d.ts

@@ -1,61 +0,0 @@
-/**
- * The LLM planning pass. Given the current harness state, refinement history,
- * and optional instructions, a direct model call produces a JSON proposal
- * which is parsed (truncation-aware) and validated by the pure core.
- *
- * The call routes through `ctx.llm` with the calling agent's own
- * provider/model so the plan uses the same model the session runs on.
- */
-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";
-import { type RecordLanguage } from "./record-language.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- Repeated evidence is mandatory for prompt/skill/subagent proposals: the same\n  pattern must recur at least twice in the trajectory. A single one-off\n  interaction never justifies a prompt, skill, or subagent edit \u2014 return an\n  empty edits array with a rationale instead. Session-scoped local prompt\n  landings converge on /evolve wrapup human review; the turn pipeline must\n  not silently persist one-off abstractions.\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;
-    history: readonly RefinementResult[];
-    instructions?: string;
-    /**
-     * Explicit session-trajectory text (recent direct user messages). When
-     * omitted, it is extracted from the agent's own session log via
-     * `recentUserText` — the same extraction the injection ranking uses — so
-     * 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
-     * skills are not installed, the builtin distilled quality guide is
-     * injected instead — the skill standard is always present.
-     */
-    skillsRoot?: string;
-    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;
-    /**
-     * Authoring language for the proposal. Absent → resolved per call
-     * (explicit config upstream, else durable client preference, else
-     * trajectory detection, else `en`).
-     */
-    language?: RecordLanguage;
-}
-export declare function planWithLlm(ctx: Context, options: PlanOptions): Promise<RefinementProposal>;
-//# sourceMappingURL=planner.d.ts.map

package/lib/planner.js

@@ -1,144 +0,0 @@
-import { parseProposal } from "./plan.js";
-import { formatHarnessStateForPrompt, historyForPrompt } from "./render.js";
-import { recentUserText, sessionEventsOf } from "./inject.js";
-import { buildPrefixMessages, detectPlannerRoute, resolvePrefixCache } from "./prefix-cache.js";
-import { skillQualityGuide } from "./skillquality.js";
-import { asLlmSessionId, streamText } from "./llm-text.js";
-import { createTokenUsageObserver } from "./token-usage.js";
-import { recordLanguageInstruction, resolveRecordLanguage } from "./record-language.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
-summarizing the conversation you emit precise Create, Update, or Delete edits
-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.
-- Repeated evidence is mandatory for prompt/skill/subagent proposals: the same
-  pattern must recur at least twice in the trajectory. A single one-off
-  interaction never justifies a prompt, skill, or subagent edit — return an
-  empty edits array with a rationale instead. Session-scoped local prompt
-  landings converge on /evolve wrapup human review; the turn pipeline must
-  not silently persist one-off abstractions.
-- 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;
-  the full facts are provided in the <skill_quality_standard> block below):
-  only for a REAL trigger scenario grounded in the trajectory
-  (who, in what real task, what signal) — never invent one to pad the store;
-  never duplicate the official 11 skills or existing entries; content is a
-  SKILL.md document (frontmatter routing with "use when / do not use when"
-  description, boundary declaration, prerequisites and exclusions, layered
-  information, verifiable completion criteria). Self-check every proposed
-  skill against the 7 structural features and state the result in its
-  reason field.
-- Repeated multi-step workflows (session start/end routines, recurring
-  wrap-up or handoff procedures) may be proposed as guidance skills:
-  kind=skill, skill_kind="guidance", content = a SKILL.md document (no
-  python reference — executable skills keep requiring reference +
-  arguments). Only propose with repeated evidence in the trajectory, never
-  for one-off flows. Guidance skills materialize as discoverable SKILL.md
-  files under <skillsRoot>/<kebab-name>/SKILL.md and are always offered to
-  the user for a decision before they land.
-- Local edits are session-scoped; global edits persist across sessions.
-- Gap C2: EVERY edit MUST include a "blastRadius" field indicating how broadly
-  the edit applies: "general" (cross-project tactical rule, applies everywhere),
-  "project" (valid for the current project/repo), or "session" (one-off,
-  specific to this session's context). The review gate validates that
-  local-scope edits use "session" or "project", and global-scope edits use
-  "general" or "project". When in doubt, prefer narrower blast radius.
-- Ground every edit in evidence: the session trajectory (recent direct user
-  messages) is provided when available; prefer edits backed by it over
-  speculation, and never invent preferences the user did not express.
-- Stale entries (superseded by newer ones, never referenced in recent
-  trajectories, obsolete facts): propose action "archive" instead of
-  "delete" — archive hides the entry from injection while keeping its data
-  restorable; it requires only kind + id.
-- Output JSON only, exactly this shape:
-{
-  "summary": "one sentence",
-  "rationale": "why these edits are justified by the evidence",
-  "expectedOutcome": "what should improve and how to validate it",
-  "edits": [
-    {
-      "action": "create|update|delete",
-      "kind": "prompt|memory|skill|subagent",
-      "id": "stable id for update/delete, optional for create",
-      "title": "required for create/update except delete",
-      "content": "required for create/update except delete",
-      "path": "optional grouping path",
-      "reference": {"type":"python","import":"pkg.mod","callable":"fn"} ,
-      "arguments": {"name": {"type":"string","required":true,"description":"..."}},
-      "skill_kind": "executable|guidance (optional; skill kind only — guidance = SKILL.md document without reference)",
-      "metadata": {},
-      "reason": "why this edit is useful",
-      "blastRadius": "general|project|session"
-    }
-  ]
-}`;
-export async function planWithLlm(ctx, options) {
-    const { agent, state, history } = options;
-    if (!agent.options.provider || !agent.options.model) {
-        throw new Error("evolve: the calling agent has no provider/model route to plan with");
-    }
-    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. Propose session-scoped edits only when the trajectory shows repeated evidence (>=2 occurrences of the same pattern); a single one-off interaction returns an empty edits array. Global entries are read-only context — do not propose update/delete for them.";
-    // 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));
-    const language = options.language ?? resolveRecordLanguage({ ctx, trajectoryText: trajectory });
-    // 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
-    // proposals from drifting off the quality bar).
-    const qualityGuide = skillQualityGuide(options.skillsRoot);
-    const userPrompt = [
-        `<current_harness_state>\n${formatHarnessStateForPrompt(state)}\n</current_harness_state>`,
-        `<refinement_history>\n${historyForPrompt(history)}\n</refinement_history>`,
-        `<scope_policy>\n${scopeInstruction}\n</scope_policy>`,
-        trajectory ? `<session_trajectory>\n${trajectory}\n</session_trajectory>` : "",
-        `<skill_quality_standard>\n${qualityGuide.text}\n</skill_quality_standard>`,
-        options.instructions ? `<user_instructions>\n${options.instructions}\n</user_instructions>` : "",
-        "Return only JSON edits. If no useful edit is justified, return an empty edits array with a rationale.",
-    ]
-        .filter(Boolean)
-        .join("\n\n");
-    const text = await streamText(ctx, {
-        provider: agent.options.provider,
-        model: agent.options.model,
-        sessionId: asLlmSessionId(agent.id),
-        system: `${PLANNER_SYSTEM_PROMPT}\n\n${recordLanguageInstruction(language)}`,
-        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);
-}
-//# sourceMappingURL=planner.js.map

package/lib/pool.d.ts

@@ -1,7 +0,0 @@
-/**
- * Bounded-concurrency map: run async workers over items with at most
- * `concurrency` in flight. Used by the evaluation matrix so case × run units
- * execute in parallel without unbounded subagent fan-out.
- */
-export declare function mapPool<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
-//# sourceMappingURL=pool.d.ts.map

package/lib/pool.js

@@ -1,25 +0,0 @@
-/**
- * Bounded-concurrency map: run async workers over items with at most
- * `concurrency` in flight. Used by the evaluation matrix so case × run units
- * execute in parallel without unbounded subagent fan-out.
- */
-export async function mapPool(items, concurrency, worker) {
-    if (items.length === 0) {
-        return [];
-    }
-    const results = new Array(items.length);
-    const limit = Math.max(1, Math.min(concurrency, items.length));
-    let next = 0;
-    async function runner() {
-        while (true) {
-            const index = next;
-            next += 1;
-            if (index >= items.length)
-                return;
-            results[index] = await worker(items[index], index);
-        }
-    }
-    await Promise.all(Array.from({ length: limit }, () => runner()));
-    return results;
-}
-//# sourceMappingURL=pool.js.map

package/lib/prefix-cache.d.ts

@@ -1,79 +0,0 @@
-/**
- * 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 } from "./types.js";
-import type { PlannerPrefixCacheMode } from "./types.js";
-/** 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