dsh-continual-evolve 0.7.2 → 0.7.3

package/lib/memory-agent.js

@@ -0,0 +1,535 @@
+import { createAssistantMessage, createToolResultMessage, createUserMessage, } from "@deepseek-ai/dsh-llm";
+import { requestScopeApproval } from "./approval.js";
+import { streamModelTurn } from "./llm-text.js";
+import { EVOLVE_MESSAGE_SOURCE } from "./message-source.js";
+import { extractJsonObject, parseJsonCandidate } from "./plan.js";
+import { buildPrefixMessages, detectPlannerRoute, resolvePrefixCache } from "./prefix-cache.js";
+import { compactText } from "./render.js";
+import { buildConflictNotice, CONFLICT_WARN_SCORE, mostSimilarEntry } from "./promotion.js";
+import { EvolutionApplyPostCommitError } from "./service.js";
+import { tokenize } from "./search.js";
+import { createTokenUsageObserver } from "./token-usage.js";
+import { isArchived, isMemoryType, MEMORY_TYPE_KEY, slug } from "./types.js";
+import { validateBlastRadiusScope, validateEdit } from "./validate.js";
+/** ZCode parity: the extractor may inspect memory and propose at most five times. */
+export const MEMORY_AGENT_MAX_TURNS = 5;
+/** Bound one proposal so approval text and engine compensation stay reviewable. */
+export const MEMORY_AGENT_MAX_EDITS = 20;
+/** The complete tool-name allowlist exposed by the memory agent. */
+export const MEMORY_AGENT_TOOL_NAMES = ["memory_search", "memory_propose"];
+/** Provider-facing schemas for the closed memory-only tool set. */
+export const MEMORY_AGENT_TOOL_SCHEMAS = [
+    {
+        name: "memory_search",
+        description: "Read full content from the frozen memory manifest. This is the only data-reading tool available to the memory extractor.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                query: { type: "string", description: "Keywords, title text, scope:id, or content terms to retrieve." },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "memory_propose",
+        description: "Finish extraction with one auditable memory-only proposal. An empty edits array is a valid no-op.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                summary: { type: "string" },
+                rationale: { type: "string" },
+                expectedOutcome: { type: "string" },
+                edits: {
+                    type: "array",
+                    maxItems: MEMORY_AGENT_MAX_EDITS,
+                    items: {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            action: { type: "string", enum: ["create", "update", "delete", "archive"] },
+                            kind: { type: "string", enum: ["memory"] },
+                            targetScope: { type: "string", enum: ["local", "project", "global"] },
+                            blastRadius: { type: "string", enum: ["general", "project", "session"] },
+                            id: { type: "string", pattern: "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$" },
+                            title: { type: "string" },
+                            content: { type: "string" },
+                            path: { type: "string" },
+                            metadata: {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: { memoryType: { type: "string", enum: ["user", "feedback", "project", "reference"] } },
+                            },
+                            reason: { type: "string" },
+                        },
+                        required: ["action", "kind", "targetScope", "blastRadius"],
+                    },
+                },
+            },
+            required: ["summary", "rationale", "expectedOutcome", "edits"],
+        },
+    },
+];
+/** Instructions for the dedicated loop; model text is always untrusted. */
+export const MEMORY_AGENT_SYSTEM_PROMPT = `You are the dedicated background memory extraction agent for a continual-evolution harness.
+
+You receive only an incremental conversation checkpoint and a frozen manifest of existing memory entries. Your entire job is to decide whether this checkpoint contains a durable fact worth remembering. Never propose prompt notes, skills, subagent specs, code changes, or general conversation summaries.
+
+Rules:
+- Use memory_search before creating when the manifest may already cover the topic. Update an existing entry instead of creating a near-duplicate.
+- Every memory entry contains exactly one fact. Classify it with metadata.memoryType = user | feedback | project | reference.
+- feedback and project memories must state the fact, Why it matters, and How to apply it next time.
+- Never invent a user preference. Ground every proposal in the supplied conversation evidence and existing memory.
+- Every edit must have kind=memory, an explicit targetScope, and a coherent blastRadius.
+- targetScope=local is session staging. project persists within the current repository. global persists across projects. project/global require human approval before application.
+- update/delete/archive must name an existing id from the same targetScope. Prefer archive over delete when the fact is obsolete but should remain restorable.
+- You cannot read or write source files, call agents, use MCP, use the network, or mutate the harness directly. memory_propose is the only finish tool and never writes state itself.
+- If no durable memory is justified, call memory_propose with edits=[].
+- Always finish by calling memory_propose. Do not return unproposed prose.`;
+/** Build the frozen memory manifest from a merged harness view. */
+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);
+}
+/**
+ * Run the dedicated loop against a frozen manifest.
+ *
+ * @throws On provider failure, abort, malformed tool arguments, policy denial,
+ * a non-memory proposal, or exhaustion of the bounded internal turn budget.
+ */
+export async function runMemoryAgent(ctx, options) {
+    const events = options.trajectoryEvents ?? [];
+    const routing = resolvePrefixCache(options.prefixCache);
+    const route = detectPlannerRoute(events, routing.mode);
+    const prefixMessages = route === "A"
+        ? buildPrefixMessages(events, { provider: options.provider, model: options.model, maxChars: routing.maxChars })
+        : [];
+    const conversation = prefixMessages.length > 0 ? "" : `<conversation>\n${options.trajectory}\n</conversation>`;
+    const prompt = [
+        `<memory_manifest>\n${formatMemoryManifest(options.manifest)}\n</memory_manifest>`,
+        conversation,
+        "Search before deciding, then call memory_propose with the complete memory-only proposal. Empty edits is a valid no-op.",
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    const messages = [
+        ...prefixMessages,
+        createUserMessage({
+            content: [{ type: "text", text: prompt }],
+            source: EVOLVE_MESSAGE_SOURCE,
+        }),
+    ];
+    let searches = 0;
+    for (let turn = 1; turn <= MEMORY_AGENT_MAX_TURNS; turn += 1) {
+        options.signal?.throwIfAborted();
+        const blocks = await streamModelTurn(ctx, {
+            provider: options.provider,
+            model: options.model,
+            system: MEMORY_AGENT_SYSTEM_PROMPT,
+            messages,
+            tools: MEMORY_AGENT_TOOL_SCHEMAS,
+            requireTextOrToolCall: true,
+            maxTokens: options.maxOutputTokens ?? 4096,
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(options.tokenUsage
+                ? { onUsage: createTokenUsageObserver(options.tokenUsage, "memory", options.provider, options.model) }
+                : {}),
+        });
+        const hasText = blocks.some((block) => block.type === "text" && block.text.length > 0);
+        const hasToolCall = blocks.some((block) => block.type === "tool-call");
+        if (!hasText && !hasToolCall)
+            throw new Error("memory agent produced no model output");
+        messages.push(createAssistantMessage({
+            content: blocks,
+            source: { provider: options.provider, model: options.model },
+        }));
+        const toolCalls = blocks.filter((block) => block.type === "tool-call");
+        if (toolCalls.length === 0) {
+            const text = textOf(blocks);
+            return {
+                proposal: parseMemoryExtractionProposal(extractJsonObject(text), options.manifest),
+                turns: turn,
+                searches,
+            };
+        }
+        let proposal;
+        for (const call of toolCalls) {
+            const execution = executeMemoryTool(call, options.manifest);
+            if (call.name === "memory_search")
+                searches += 1;
+            proposal ??= execution.proposal;
+            messages.push(createToolResultMessage({
+                callId: call.id,
+                content: [{ type: "text", text: execution.text }],
+                isError: execution.isError,
+            }));
+        }
+        if (proposal)
+            return { proposal, turns: turn, searches };
+    }
+    throw new Error(`memory agent exhausted ${MEMORY_AGENT_MAX_TURNS} internal turns without a valid proposal`);
+}
+/** Strictly parse and policy-check the structured `memory_propose` payload. */
+export function parseMemoryExtractionProposal(value, manifest) {
+    const record = asRecord(value);
+    if (!record)
+        throw new Error("memory proposal must be an object");
+    const summary = requiredString(record["summary"], "summary");
+    const rationale = requiredString(record["rationale"], "rationale");
+    const expectedOutcome = requiredString(record["expectedOutcome"], "expectedOutcome");
+    if (!Array.isArray(record["edits"]))
+        throw new Error("memory proposal edits must be an array");
+    if (record["edits"].length > MEMORY_AGENT_MAX_EDITS) {
+        throw new Error(`memory proposal exceeds ${MEMORY_AGENT_MAX_EDITS} edits`);
+    }
+    const byScopeId = new Map(manifest.map((entry) => [`${entry.scope}:${entry.id}`, entry]));
+    const edits = record["edits"].map((raw, index) => parseScopedMemoryEdit(raw, index, byScopeId));
+    return { summary, rationale, expectedOutcome, edits };
+}
+/**
+ * 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 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));
+        if (decisionKey !== undefined)
+            options.onScopeDecision?.(decisionKey, approved);
+        if (approved === "approved")
+            approvedScopes.add(scope);
+        else
+            declinedScopes.push(scope);
+    }
+    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 executeMemoryTool(call, manifest) {
+    if (!MEMORY_AGENT_TOOL_NAMES.includes(call.name)) {
+        return { text: `tool denied: only ${MEMORY_AGENT_TOOL_NAMES.join(" and ")} are available`, isError: true };
+    }
+    try {
+        const args = parseJsonCandidate(call.arguments.trim() || "{}");
+        if (call.name === "memory_search") {
+            const record = asRecord(args);
+            const query = record ? requiredString(record["query"], "query") : "";
+            const matches = searchMemoryManifest(manifest, query).map(manifestResult);
+            return { text: JSON.stringify({ matches }), isError: false };
+        }
+        return { proposal: parseMemoryExtractionProposal(args, manifest), text: JSON.stringify({ accepted: true }), isError: false };
+    }
+    catch (cause) {
+        return {
+            text: `tool error: ${cause instanceof Error ? cause.message : String(cause)}`,
+            isError: true,
+        };
+    }
+}
+function parseScopedMemoryEdit(raw, index, byScopeId) {
+    const record = asRecord(raw);
+    if (!record)
+        throw new Error(`memory edit ${index} must be an object`);
+    const action = requiredString(record["action"], `edits[${index}].action`);
+    if (!isOneOf(action, ["create", "update", "delete", "archive"])) {
+        throw new Error(`memory edit ${index} has unsupported action ${action}`);
+    }
+    if (record["kind"] !== "memory")
+        throw new Error(`memory edit ${index} must have kind=memory`);
+    const targetScope = requiredString(record["targetScope"], `edits[${index}].targetScope`);
+    if (!isOneOf(targetScope, ["local", "project", "global"])) {
+        throw new Error(`memory edit ${index} has unsupported targetScope ${targetScope}`);
+    }
+    const blastRadius = requiredString(record["blastRadius"], `edits[${index}].blastRadius`);
+    if (!isOneOf(blastRadius, ["general", "project", "session"])) {
+        throw new Error(`memory edit ${index} has unsupported blastRadius ${blastRadius}`);
+    }
+    const blastError = validateBlastRadiusScope(targetScope, blastRadius);
+    if (blastError)
+        throw new Error(`memory edit ${index}: ${blastError}`);
+    if (record["reference"] !== undefined || record["arguments"] !== undefined || record["skill_kind"] !== undefined) {
+        throw new Error(`memory edit ${index} cannot carry skill-only fields`);
+    }
+    const edit = {
+        action,
+        kind: "memory",
+        targetScope,
+        blastRadius,
+    };
+    for (const field of ["id", "title", "content", "path", "reason"]) {
+        const fieldValue = record[field];
+        if (fieldValue !== undefined) {
+            if (typeof fieldValue !== "string")
+                throw new Error(`memory edit ${index}.${field} must be a string`);
+            edit[field] = fieldValue;
+        }
+    }
+    if (record["metadata"] !== undefined) {
+        const metadata = asRecord(record["metadata"]);
+        if (!metadata)
+            throw new Error(`memory edit ${index}.metadata must be an object`);
+        const unexpected = Object.keys(metadata).filter((key) => key !== MEMORY_TYPE_KEY);
+        if (unexpected.length > 0) {
+            throw new Error(`memory edit ${index}.metadata contains engine-owned or unsupported keys: ${unexpected.join(", ")}`);
+        }
+        edit.metadata = { ...metadata };
+    }
+    if (action === "create" && edit.id && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(edit.id)) {
+        throw new Error(`memory edit ${index}.id contains unsupported identifier characters`);
+    }
+    const before = edit.id ? byScopeId.get(`${targetScope}:${edit.id}`) : undefined;
+    if (action !== "create" && !before) {
+        throw new Error(`memory edit ${index} ${action} target does not exist in ${targetScope}: ${edit.id ?? "(missing id)"}`);
+    }
+    if (action === "create" && edit.id && before) {
+        throw new Error(`memory edit ${index} create duplicates ${targetScope}:${edit.id}; use update instead`);
+    }
+    const validationError = validateEdit(edit, edit.id ?? slug(edit.title ?? "memory", "memory"), targetScope, before);
+    if (validationError)
+        throw new Error(`memory edit ${index}: ${validationError}`);
+    return edit;
+}
+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;
+}
+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}`;
+}
+function textOf(blocks) {
+    return blocks
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+}
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function requiredString(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${field} must be a non-empty string`);
+    return value;
+}
+function isOneOf(value, values) {
+    return values.includes(value);
+}
+//# sourceMappingURL=memory-agent.js.map

package/lib/review-scheduler.d.ts

@@ -1,12 +1,13 @@
 /**
- * Serial latest-pending scheduler for automatic review snapshots.
+ * Serial latest-boundary scheduler for automatic memory+review snapshots.
  *
- * This is the DSH equivalent of ZCode's memory extraction scheduler: one
- * runner per session, at most one running snapshot, and one replaceable
- * pending snapshot while the runner is busy. A cursor advances only after a
- * successful or no-op execution; errors and aborts leave it untouched so the
- * next snapshot retries the same durable boundary.
+ * One runner exists per session. A burst is coalesced by durable cursor rather
+ * than promise arrival: once multiple pending captures settle, the highest
+ * 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 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. */
@@ -20,7 +21,7 @@ export interface ReviewScheduler<TSnapshot> {
     drain(): Promise<void>;
     /** Last successfully processed or skipped snapshot boundary. */
     getCursor(): string | undefined;
-    /** Whether a run or a replaceable pending snapshot exists. */
+    /** Whether a run or a pending acquisition exists. */
     hasPendingWork(): boolean;
     /** Submit a snapshot (or an async acquisition) without blocking the caller. */
     schedule(snapshot: TSnapshot | Promise<TSnapshot>): void;
@@ -28,7 +29,7 @@ export interface ReviewScheduler<TSnapshot> {
     shutdown(): void;
 }
 /**
- * Create a scheduler with ZCode-compatible coalescing and cursor semantics.
+ * Create a scheduler with ZCode-compatible serial/coalescing semantics.
  *
  * @param execute - one serial extraction/review operation
  * @param cursorOf - extracts the durable boundary from a snapshot