dsh-continual-evolve 0.10.6 → 0.11.0

package/lib/memory-apply.js

@@ -0,0 +1,202 @@
+import { MEMORY_TYPE_KEY } from "./types.js";
+import { requestScopeApproval } from "./approval.js";
+import { fingerprintMemoryBatch, isDeclinedRepeat, loadDeclinedMemory, recordDeclinedMemory, } from "./declines.js";
+import { compactText } from "./render.js";
+import { buildConflictNotice, CONFLICT_WARN_SCORE, mostSimilarEntry } from "./promotion.js";
+import { EvolutionApplyPostCommitError } from "./service.js";
+/**
+ * Render the authoritative persistent-scope diff shown to the human. Model
+ * prose is retained only as an explicitly untrusted summary; actions, targets,
+ * content previews, memory types, and conflict warnings come from code.
+ */
+export function renderMemoryApprovalDetails(proposal, scope, state, maxChars = 6000) {
+    const edits = proposal.edits.filter((candidate) => candidate.targetScope === scope);
+    const details = edits.map((edit) => {
+        const before = edit.id ? state.entries.memory[edit.id] : undefined;
+        const title = edit.title ?? before?.title ?? "(existing title unchanged)";
+        const path = edit.path ?? before?.path ?? "(path unchanged)";
+        const content = edit.content ?? (edit.action === "update" ? "(content unchanged)" : "(no content field)");
+        const type = edit.metadata?.[MEMORY_TYPE_KEY] ?? before?.metadata[MEMORY_TYPE_KEY] ?? "untyped";
+        const candidates = Object.values(state.entries.memory).filter((entry) => entry.id !== edit.id);
+        const hit = edit.action === "create" || edit.action === "update"
+            ? mostSimilarEntry(candidates, edit.title ?? before?.title ?? "", edit.content ?? before?.content ?? "", CONFLICT_WARN_SCORE)
+            : undefined;
+        const conflict = hit ? `; conflict: ${compactText(buildConflictNotice(hit), 120)}` : "";
+        const targetId = edit.id === undefined ? "(new)" : JSON.stringify(edit.id);
+        return {
+            target: `- ${edit.action} ${scope}:${targetId} — ${compactText(title, 80)}`,
+            detail: `  path=${compactText(path, 60)}; memoryType=${String(type)}; content=${compactText(content, 100)}${conflict}`,
+        };
+    });
+    let titleLimit = 80;
+    let targets = details.map((detail) => detail.target.replace(/ — .*$/, ` — ${compactText(detail.target.split(" — ")[1] ?? "", titleLimit)}`));
+    let base = ["edits to approve:", ...targets].join("\n");
+    while (base.length > maxChars && titleLimit > 20) {
+        titleLimit = Math.floor(titleLimit / 2);
+        targets = details.map((detail) => `- ${detail.target.split(" — ")[0]} — ${compactText(detail.target.split(" — ")[1] ?? "", titleLimit)}`);
+        base = ["edits to approve:", ...targets].join("\n");
+    }
+    if (base.length > maxChars)
+        throw new Error(`memory approval diff exceeds ${maxChars} characters`);
+    const output = [base];
+    const summary = `model summary (untrusted): ${compactText(proposal.summary, 180)}`;
+    if ([...output, summary].join("\n").length <= maxChars)
+        output.push(summary);
+    for (const detail of details) {
+        const line = detail.detail;
+        if ([...output, line].join("\n").length <= maxChars)
+            output.push(line);
+    }
+    if ([...output, "  (additional previews omitted; every target is listed above)"].join("\n").length <= maxChars) {
+        output.push("  (additional previews omitted; every target is listed above)");
+    }
+    return output.join("\n");
+}
+function memoryScopeDecisionKey(cursor, scope, edits) {
+    return `${cursor}:${scope}:${JSON.stringify(edits.map(stripTargetScope))}`;
+}
+class MemoryApplyBatchError extends Error {
+    result;
+    scope;
+    storeId;
+    constructor(message, result, scope, storeId) {
+        super(message);
+        this.result = result;
+        this.scope = scope;
+        this.storeId = storeId;
+    }
+}
+/**
+ * Apply one accepted proposal through the only mutation engine. All persistent
+ * approvals are resolved before the first write, so an unavailable approval
+ * boundary cannot leave a partially applied batch. Explicit rejection is a
+ * no-op for that scope; service/question failures remain retryable errors.
+ */
+export async function applyMemoryExtractionProposal(ctx, engine, proposal, options) {
+    const scopeOrder = ["local", "project", "global"];
+    const editsByScope = new Map();
+    for (const scope of scopeOrder) {
+        const edits = proposal.edits.filter((edit) => edit.targetScope === scope);
+        if (edits.length > 0)
+            editsByScope.set(scope, edits);
+    }
+    if (editsByScope.has("project") && !options.projectKey) {
+        throw new Error("memory agent cannot target project scope without a resolved project key");
+    }
+    const approvedScopes = new Set();
+    const declinedScopes = [];
+    for (const scope of ["project", "global"]) {
+        if (!editsByScope.has(scope))
+            continue;
+        if (!options.requireApproval) {
+            approvedScopes.add(scope);
+            continue;
+        }
+        const baseline = options.baselines[scope];
+        if (!baseline)
+            throw new Error(`memory agent has no ${scope} baseline`);
+        const scopeEdits = proposal.edits.filter((edit) => edit.targetScope === scope);
+        const fingerprint = fingerprintMemoryBatch(scope, scopeEdits);
+        if (isDeclinedRepeat(loadDeclinedMemory(engine.baseDir), scope, fingerprint)) {
+            ctx.logger("continual-evolve").info(`memory ${scope} proposal repeat-suppressed (declined before, no popup)`);
+            declinedScopes.push(scope);
+            continue;
+        }
+        const decisionKey = options.decisionCursor === undefined
+            ? undefined
+            : memoryScopeDecisionKey(options.decisionCursor, scope, proposal.edits.filter((edit) => edit.targetScope === scope));
+        const previous = decisionKey === undefined ? undefined : options.scopeDecisions?.[decisionKey];
+        if (previous === "approved") {
+            approvedScopes.add(scope);
+            continue;
+        }
+        if (previous === "declined") {
+            declinedScopes.push(scope);
+            continue;
+        }
+        const approved = await requestScopeApproval(ctx, options.agent, options.signal, scope, renderMemoryApprovalDetails(proposal, scope, baseline), options.recordLanguage);
+        if (decisionKey !== undefined)
+            options.onScopeDecision?.(decisionKey, approved);
+        if (approved === "approved")
+            approvedScopes.add(scope);
+        else {
+            declinedScopes.push(scope);
+            try {
+                recordDeclinedMemory(engine.baseDir, scope, scopeEdits, compactText(scopeEdits[0]?.title ?? proposal.summary, 120));
+            }
+            catch (error) {
+                ctx.logger("continual-evolve").warn(`declined-memory ledger write failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    const results = [];
+    const applied = [];
+    try {
+        for (const scope of scopeOrder) {
+            const edits = editsByScope.get(scope);
+            if (!edits)
+                continue;
+            if (scope !== "local" && !approvedScopes.has(scope))
+                continue;
+            options.signal?.throwIfAborted();
+            const storeId = scope === "local" ? options.agent.id : scope === "project" ? options.projectKey : undefined;
+            const baseline = options.baselines[scope];
+            if (!baseline)
+                throw new Error(`memory agent has no ${scope} baseline`);
+            const result = engine.apply(scope, storeId, {
+                summary: proposal.summary,
+                rationale: proposal.rationale,
+                expectedOutcome: proposal.expectedOutcome,
+                edits: prepareMemoryEdits(edits, baseline),
+            }, {
+                scope,
+                baselineState: baseline,
+                ...(options.source ? { source: options.source } : {}),
+            });
+            const failed = result.appliedEdits.filter((edit) => !edit.applied);
+            if (failed.length > 0) {
+                throw new MemoryApplyBatchError(`${scope} batch ${result.id} left ${failed.length} edit(s) unapplied: ${failed.map((edit) => edit.error ?? "unknown").join("; ")}`, result, scope, storeId);
+            }
+            results.push(result);
+            applied.push({ scope, storeId, result });
+        }
+        return { results, declinedScopes };
+    }
+    catch (cause) {
+        const attempted = [...applied];
+        if (cause instanceof MemoryApplyBatchError && cause.result && cause.scope) {
+            attempted.push({ scope: cause.scope, storeId: cause.storeId, result: cause.result });
+        }
+        else if (cause instanceof EvolutionApplyPostCommitError) {
+            attempted.push({ scope: cause.scope, storeId: cause.storeId, result: cause.result });
+        }
+        const rollbackErrors = [];
+        for (const item of attempted.reverse()) {
+            try {
+                const rollback = engine.rollbackResult(item.scope, item.storeId, item.result);
+                const failed = rollback.appliedEdits.filter((edit) => !edit.applied);
+                if (failed.length > 0)
+                    rollbackErrors.push(`${item.scope}:${item.result.id} left ${failed.length} rollback edit(s) unapplied`);
+            }
+            catch (rollbackCause) {
+                rollbackErrors.push(`${item.scope}:${item.result.id} rollback failed: ${rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause)}`);
+            }
+        }
+        const suffix = rollbackErrors.length > 0 ? `; compensation errors: ${rollbackErrors.join("; ")}` : "; prior memory writes were rolled back";
+        throw new Error(`memory agent apply failed: ${cause instanceof Error ? cause.message : String(cause)}${suffix}`);
+    }
+}
+function prepareMemoryEdits(edits, baseline) {
+    return edits.map((edit) => {
+        const plain = stripTargetScope(edit);
+        if (plain.action !== "update" || plain.metadata === undefined || plain.id === undefined)
+            return plain;
+        const before = baseline.entries.memory[plain.id];
+        return before ? { ...plain, metadata: { ...before.metadata, ...plain.metadata } } : plain;
+    });
+}
+function stripTargetScope(edit) {
+    const { targetScope: _targetScope, ...plain } = edit;
+    return plain;
+}
+//# sourceMappingURL=memory-apply.js.map

package/lib/memory-manifest.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The frozen memory manifest: a deterministic snapshot view of every live
+ * memory entry the extractor may see, plus its bounded serialization and
+ * manifest-scoped search. Pure functions over harness state.
+ */
+import type { HarnessEntry, HarnessState } from "./types.js";
+/** One manifest row is exactly one live memory entry. */
+export type MemoryManifestEntry = HarnessEntry;
+export declare function buildMemoryManifest(state: HarnessState): MemoryManifestEntry[];
+/** Render a bounded manifest index; full bodies remain available through memory_search. */
+export declare function formatMemoryManifest(entries: readonly MemoryManifestEntry[], maxChars?: number): string;
+/** Rank frozen manifest entries with CJK-aware token overlap and stable tie-breaking. */
+export declare function searchMemoryManifest(entries: readonly MemoryManifestEntry[], query: string, maxResults?: number): MemoryManifestEntry[];
+/** Inputs for one bounded background memory extraction loop. */
+export declare function manifestResult(entry: MemoryManifestEntry): Record<string, unknown>;
+//# sourceMappingURL=memory-manifest.d.ts.map

package/lib/memory-manifest.js

@@ -0,0 +1,70 @@
+import { isArchived, isMemoryType, MEMORY_TYPE_KEY } from "./types.js";
+import { tokenize } from "./search.js";
+import { compactText } from "./render.js";
+export function buildMemoryManifest(state) {
+    return Object.values(state.entries.memory)
+        .map((entry) => ({ ...entry, metadata: { ...entry.metadata }, reference: {}, arguments: {} }))
+        .sort((a, b) => manifestOrder(a).localeCompare(manifestOrder(b), "en"));
+}
+/** Render a bounded manifest index; full bodies remain available through memory_search. */
+export function formatMemoryManifest(entries, maxChars = 8000) {
+    if (entries.length === 0)
+        return "No saved memory entries yet.";
+    const lines = [];
+    let used = 0;
+    for (const entry of entries) {
+        const type = isMemoryType(entry.metadata[MEMORY_TYPE_KEY]) ? entry.metadata[MEMORY_TYPE_KEY] : "untyped";
+        const archived = isArchived(entry) ? ", archived" : "";
+        const line = `- [${entry.scope}:${entry.id}] ${entry.title} (memoryType=${type}, path=${entry.path}${archived}): ${compactText(entry.content, 240)}`;
+        if (used + line.length + 1 > maxChars)
+            break;
+        lines.push(line);
+        used += line.length + 1;
+    }
+    const omitted = entries.length - lines.length;
+    if (omitted > 0)
+        lines.push(`- +${omitted} more entries; use memory_search with a narrower query.`);
+    return lines.join("\n");
+}
+/** Rank frozen manifest entries with CJK-aware token overlap and stable tie-breaking. */
+export function searchMemoryManifest(entries, query, maxResults = 8) {
+    const queryTokens = new Set(tokenize(query));
+    if (queryTokens.size === 0)
+        return [];
+    return entries
+        .map((entry) => {
+        const title = tokenize(entry.title);
+        const body = tokenize(`${entry.content} ${entry.path} ${String(entry.metadata[MEMORY_TYPE_KEY] ?? "")}`);
+        let score = 0;
+        for (const token of queryTokens) {
+            if (title.includes(token))
+                score += 2;
+            if (body.includes(token))
+                score += 1;
+        }
+        if (`${entry.scope}:${entry.id}`.toLowerCase() === query.trim().toLowerCase())
+            score += 100;
+        return { entry, score };
+    })
+        .filter((hit) => hit.score > 0)
+        .sort((a, b) => b.score - a.score || manifestOrder(a.entry).localeCompare(manifestOrder(b.entry), "en"))
+        .slice(0, maxResults)
+        .map((hit) => hit.entry);
+}
+/** Inputs for one bounded background memory extraction loop. */
+export function manifestResult(entry) {
+    return {
+        scope: entry.scope,
+        id: entry.id,
+        title: entry.title,
+        content: entry.content,
+        path: entry.path,
+        memoryType: entry.metadata[MEMORY_TYPE_KEY],
+        archived: isArchived(entry),
+    };
+}
+function manifestOrder(entry) {
+    const scope = entry.scope === "global" ? "0" : entry.scope === "project" ? "1" : "2";
+    return `${scope}:${entry.id}:${entry.title}`;
+}
+//# sourceMappingURL=memory-manifest.js.map

package/lib/mount-command.js

@@ -1,5 +1,5 @@
 import { loadLedger, mountSkill, unmountSkill } from "./mount.js";
-import { stripAngleBrackets } from "./command.js";
+import { stripAngleBrackets } from "./command-util.js";
 function success(text) {
     return { kind: "success", text };
 }

package/lib/notify.d.ts

@@ -1,34 +1,23 @@
 /**
- * Auto-review visibility: the gate used to work fully in the background —
- * the user never saw a decision, a persisted entry, or the token spend. This
- * module queues a short follow-up turn after an approved gate run so the
- * user SEES what was persisted, how to inspect it, and how to roll it back.
+ * 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 notice is a `continual-evolve`-sourced user message (`agent.followup`),
+ * 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 notice is a plain `user/message` carrying this plugin's own
+ * untouched: the receipt is a plain `user/message` carrying this plugin's own
  * source kind.
  *
- * Every mechanical property stays in code: the notice text is built from the
- * applied refinement result, never from model text.
+ * 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";
-/**
- * Compose the user-visible gate notice from an applied refinement result.
- * Lists every successfully applied edit (kind + title + id) and the rollback
- * command; failed edits are summarized in one line so nothing is hidden.
- */
-export declare function buildGateNotice(result: RefinementResult, turnsSinceLastReview: number): string;
-/**
- * Queue the follow-up notice turn for the agent. Failure is contained: a
- * broken notification must never break the gate path that already recorded
- * the decision in reviews.jsonl.
- */
-export declare function notifyAutoReview(ctx: Context, agent: Agent, result: RefinementResult, turnsSinceLastReview: number): void;
 /** Unified extraction receipt: one shape for applied / declined / no-op. */
 export interface MemoryReceipt {
     outcome: "applied" | "declined" | "noop";

package/lib/notify.js

@@ -1,45 +1,5 @@
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
-/**
- * Compose the user-visible gate notice from an applied refinement result.
- * Lists every successfully applied edit (kind + title + id) and the rollback
- * command; failed edits are summarized in one line so nothing is hidden.
- */
-export function buildGateNotice(result, turnsSinceLastReview) {
-    const applied = result.appliedEdits.filter((edit) => edit.applied);
-    const failed = result.appliedEdits.filter((edit) => !edit.applied);
-    const kindLabel = { prompt: "提示词", memory: "记忆", skill: "技能", subagent: "子代理" };
-    const lines = applied.map((edit) => `- ${kindLabel[edit.kind] ?? edit.kind}「${edit.title ?? edit.id}」（${edit.id}）`);
-    const linesText = lines.length > 0 ? lines.join("\n") : "（无条目成功应用）";
-    const failedText = failed.length > 0 ? `\n另有 ${failed.length} 条编辑未应用。` : "";
-    return [
-        `🔎 自动进化门禁：会话第 ${turnsSinceLastReview} 回合检查完成，本次沉淀 ${applied.length} 条条目：`,
-        linesText,
-        failedText,
-        `查看全部条目：/evolve list；回滚本次沉淀：/evolve rollback ${result.id}`,
-        "请用一句话简短确认即可，不要调用任何工具。",
-    ]
-        .filter((part) => part !== "")
-        .join("\n");
-}
-/**
- * Queue the follow-up notice turn for the agent. Failure is contained: a
- * broken notification must never break the gate path that already recorded
- * the decision in reviews.jsonl.
- */
-export function notifyAutoReview(ctx, agent, result, turnsSinceLastReview) {
-    try {
-        agent.followup(createUserMessage({
-            content: [{ type: "text", text: buildGateNotice(result, turnsSinceLastReview) }],
-            source: EVOLVE_MESSAGE_SOURCE,
-        }));
-    }
-    catch (cause) {
-        ctx
-            .logger("continual-evolve")
-            .warn(`auto-review notice failed for ${agent.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
-    }
-}
 /**
  * Compose the user-visible memory receipt from applied refinement batches
  * (never model text): every landed memory edit with its rollback command.

package/lib/plan-command.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `/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

@@ -0,0 +1,38 @@
+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/prefix-cache.d.ts

@@ -18,7 +18,8 @@ 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";
+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;

package/lib/review-scheduler.d.ts

@@ -7,7 +7,6 @@
  * errors, aborts, and stale boundaries leave it unchanged.
  */
 /** Compare two scheduler cursors; undefined means the cursor families differ. */
-export declare function compareReviewCursors(left: string, right: string): number | undefined;
 /** Terminal state of one scheduled snapshot. */
 export type ReviewSchedulerStatus = "success" | "no-op" | "error" | "aborted";
 /** A scheduler execution receives the exact snapshot and its owner signal. */
@@ -35,4 +34,5 @@ export interface ReviewScheduler<TSnapshot> {
  * @param cursorOf - extracts the durable boundary from a snapshot
  */
 export declare function createReviewScheduler<TSnapshot>(execute: (input: ReviewSchedulerExecution<TSnapshot>) => Promise<ReviewSchedulerStatus>, cursorOf: (snapshot: TSnapshot) => string | undefined): ReviewScheduler<TSnapshot>;
+export { compareReviewCursors } from "./turn-snapshot.js";
 //# sourceMappingURL=review-scheduler.d.ts.map

package/lib/review-scheduler.js

@@ -6,16 +6,6 @@
  * comparable boundary runs first. A cursor advances only after success/no-op;
  * errors, aborts, and stale boundaries leave it unchanged.
  */
-/** Compare two scheduler cursors; undefined means the cursor families differ. */
-export function compareReviewCursors(left, right) {
-    if (left === right)
-        return 0;
-    const leftMatch = /^(seq|index):(\d+)$/.exec(left);
-    const rightMatch = /^(seq|index):(\d+)$/.exec(right);
-    if (!leftMatch || !rightMatch || leftMatch[1] !== rightMatch[1])
-        return undefined;
-    return Number(leftMatch[2]) - Number(rightMatch[2]);
-}
 /** Bound unresolved acquisitions; actual auto capture is serialized per session. */
 const MAX_PENDING_ACQUISITIONS = 16;
 /**
@@ -188,4 +178,6 @@ function waitForSnapshotAcquisitionOrShutdown(acquisition, signal) {
         });
     });
 }
+export { compareReviewCursors } from "./turn-snapshot.js";
+import { compareReviewCursors } from "./turn-snapshot.js";
 //# sourceMappingURL=review-scheduler.js.map

package/lib/runtime-commands.d.ts

@@ -0,0 +1,14 @@
+import type { EvolutionEngine } from "./service.js";
+import { type CommandRuntimeOptions, type CommandTextResult } from "./command-util.js";
+/** `/evolve pause|resume` — the runtime switch is independent of registration. */
+export declare function executePauseResumeCommand(engine: EvolutionEngine, sub: "pause" | "resume", runtime: CommandRuntimeOptions): CommandTextResult;
+/** `/evolve status` — listener wiring plus per-store entry counts and retention. */
+export declare function executeStatusCommand(engine: EvolutionEngine, sessionId: string, projectKey: string | undefined, runtime: CommandRuntimeOptions): CommandTextResult;
+/**
+ * `/evolve usage` — injection counts per entry across the stores the human
+ * can see (global + this session + this project), plus the exact direct-call
+ * token report. Counts are per-session since the v2 usage shape — "in how
+ * many sessions did this entry surface".
+ */
+export declare function executeUsageCommand(engine: EvolutionEngine, sessionId: string, projectKey: string | undefined): CommandTextResult;
+//# sourceMappingURL=runtime-commands.d.ts.map

package/lib/runtime-commands.js

@@ -0,0 +1,115 @@
+import { loadUsage, getUsageCount } from "./usage.js";
+import { loadGateRuntime, saveGateRuntime } from "./runtime.js";
+import { loadTokenUsage, renderTokenUsageReport } from "./token-usage.js";
+import { success } from "./command-util.js";
+/** `/evolve pause|resume` — the runtime switch is independent of registration. */
+export function executePauseResumeCommand(engine, sub, runtime) {
+    const pausing = sub === "pause";
+    const defaultEnabled = runtime.autoReview ?? false;
+    const current = loadGateRuntime(engine.baseDir, defaultEnabled);
+    if (pausing && current.paused) {
+        return success("automatic Memory Agent is already paused (no change).");
+    }
+    if (!pausing && current.enabled && !current.paused) {
+        return success("automatic Memory Agent is already running (no change).");
+    }
+    saveGateRuntime(engine.baseDir, pausing, pausing ? current.enabled : true);
+    return success(pausing
+        ? "automatic Memory Agent paused: no automatic memory extraction calls until /evolve resume. Manual evolve_* tools and /evolve commands keep working."
+        : "automatic Memory Agent resumed: extraction moments (compaction / goal-blocked / session-close drain) are live again.");
+}
+/** `/evolve status` — listener wiring plus per-store entry counts and retention. */
+export function executeStatusCommand(engine, sessionId, projectKey, runtime) {
+    const configuredDefault = runtime.autoReview === undefined ? "unknown" : runtime.autoReview ? "on" : "off";
+    const current = loadGateRuntime(engine.baseDir, runtime.autoReview ?? false);
+    const effective = current.paused
+        ? "PAUSED (resume with /evolve resume)"
+        : current.enabled
+            ? "Memory Agent running"
+            : "Memory Agent off (enable with /evolve resume)";
+    const gateLine = `gate: moment-driven Memory Agent listener registered · config default ${configuredDefault} · runtime ${effective}`;
+    const countEntries = (state) => Object.values(state.entries).reduce((n, byKind) => n + Object.keys(byKind).length, 0);
+    const lines = [gateLine];
+    lines.push(`stores: global ${countEntries(engine.load("global", undefined))} entries · local(${sessionId}) ${countEntries(engine.load("local", sessionId))} entries`);
+    if (projectKey) {
+        try {
+            lines[lines.length - 1] += ` · project ${countEntries(engine.load("project", projectKey))} entries`;
+        }
+        catch {
+            lines[lines.length - 1] += " · project (unavailable)";
+        }
+    }
+    const retention = engine.retention;
+    if (retention) {
+        lines.push(`retention: snapshots ${retention.snapshots} · refinements ${retention.refinements} · reviews ${retention.reviews} · token usage ${retention.tokenUsage} (historyRetain)`);
+    }
+    return success(lines.join("\n"));
+}
+/**
+ * `/evolve usage` — injection counts per entry across the stores the human
+ * can see (global + this session + this project), plus the exact direct-call
+ * token report. Counts are per-session since the v2 usage shape — "in how
+ * many sessions did this entry surface".
+ */
+export function executeUsageCommand(engine, sessionId, projectKey) {
+    const store = loadUsage(engine.baseDir);
+    const rows = [];
+    const seen = new Set();
+    const collect = (state) => {
+        for (const kind of Object.keys(state.entries)) {
+            for (const entry of Object.values(state.entries[kind])) {
+                const key = `${kind}:${entry.id}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const count = getUsageCount(store, kind, entry.id);
+                rows.push({
+                    key,
+                    title: entry.title,
+                    count,
+                    ...(store.lastSession?.[`${kind}:${entry.id}`] ? { lastSession: store.lastSession[`${kind}:${entry.id}`] } : {}),
+                });
+            }
+        }
+    };
+    collect(engine.load("global", undefined));
+    collect(engine.load("local", sessionId));
+    if (projectKey) {
+        try {
+            collect(engine.load("project", projectKey));
+        }
+        catch {
+            // project store unavailable here — global+local still report
+        }
+    }
+    const liveKeys = new Set(rows.map((r) => r.key));
+    const orphaned = Object.keys(store.counts).filter((k) => !liveKeys.has(k)).length;
+    const total = rows.reduce((n, r) => n + r.count, 0);
+    const injected = rows.filter((r) => r.count > 0).sort((a, b) => b.count - a.count || (a.key < b.key ? -1 : 1));
+    const stale = rows.filter((r) => r.count === 0).sort((a, b) => (a.key < b.key ? -1 : 1));
+    const lines = [`injected entries: ${total} injections across ${injected.length} of ${rows.length} stored entries${orphaned > 0 ? ` (+${orphaned} historical key(s) for deleted entries)` : ""}`];
+    if (injected.length > 0) {
+        lines.push("injected (top 15):");
+        for (const row of injected.slice(0, 15)) {
+            lines.push(`  ${row.key} — ${row.count}× · ${row.title}${row.lastSession ? ` (last in ${row.lastSession})` : ""}`);
+        }
+        if (injected.length > 15) {
+            lines.push(`  … and ${injected.length - 15} more`);
+        }
+    }
+    else {
+        lines.push("injected: (none yet — nothing has surfaced into a session prompt)");
+    }
+    if (stale.length > 0) {
+        lines.push(`never injected (${stale.length}):`);
+        for (const row of stale.slice(0, 20)) {
+            lines.push(`  ${row.key} · ${row.title}`);
+        }
+        if (stale.length > 20) {
+            lines.push(`  … and ${stale.length - 20} more`);
+        }
+    }
+    lines.push("", ...renderTokenUsageReport(loadTokenUsage(engine.baseDir), engine.retention.tokenUsage));
+    return success(lines.join("\n"));
+}
+//# sourceMappingURL=runtime-commands.js.map