dsh-continual-evolve 0.10.6 → 0.12.0

package/lib/token-usage.js

@@ -1,211 +0,0 @@
-/**
- * Provider-reported token accounting for plugin-owned direct LLM calls.
- *
- * The review gate, planner, dedicated memory agent, wrap-up command, and
- * local-fate classifier all use the shared model-call boundary. These calls do
- * not belong to an Agent turn (they pass no sessionId), so the host session
- * token-meter cannot attribute them. This ledger records the exact
- * `TokenUsage` emitted by the adapter at the one shared stream boundary.
- *
- * Storage: `<baseDir>/evolve/token-usage.jsonl`. The file contains route and
- * count metadata only — never prompts, responses, or tool arguments — and is
- * trimmed to its dedicated retention budget after each synchronous append.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { EVOLVE_DIR, pruneJsonlFile } from "./store.js";
-const TOKEN_USAGE_FILE = "token-usage.jsonl";
-export const TOKEN_USAGE_LEDGER_VERSION = 1;
-/** Plugin-owned direct call paths represented in the ledger. */
-export const TOKEN_USAGE_PHASES = ["review", "memory", "planner", "wrapup", "fate"];
-/** Absolute path of the direct-call token ledger. */
-export function tokenUsagePath(baseDir) {
-    return join(baseDir, EVOLVE_DIR, TOKEN_USAGE_FILE);
-}
-/** Exact full-call total, with the old-peer fallback only when `totalTokens` is absent. */
-export function exactTokenTotal(usage) {
-    if (usage.totalTokens !== undefined)
-        return usage.totalTokens;
-    return usage.inputTokens + usage.outputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
-}
-/** Build the observer attached to one `streamText` call. Errors are diagnostic-only. */
-export function createTokenUsageObserver(target, phase, provider, model) {
-    return (observation) => {
-        try {
-            appendTokenUsage(target, {
-                version: TOKEN_USAGE_LEDGER_VERSION,
-                timestamp: new Date().toISOString(),
-                sessionId: target.sessionId,
-                phase,
-                provider,
-                model,
-                outcome: observation.outcome,
-                usageStatus: observation.usage ? "reported" : "missing",
-                ...(observation.usage ? { usage: observation.usage } : {}),
-                totalSource: observation.usage
-                    ? observation.usage.totalTokens !== undefined
-                        ? "provider"
-                        : "derived"
-                    : "unavailable",
-            });
-        }
-        catch (cause) {
-            target.onError?.(cause);
-        }
-    };
-}
-/**
- * Append one call and enforce the dedicated tail budget. Append + conditional
- * prune stay in one synchronous block, so concurrent async callers in one DSH
- * process cannot interleave the read/truncate/write. Multiple DSH processes
- * sharing one baseDir are outside the plugin's storage contract.
- */
-export function appendTokenUsage(target, record) {
-    if (!isTokenUsageRecord(record)) {
-        throw new Error("evolve: refusing to append an invalid token-usage record");
-    }
-    const dir = join(target.baseDir, EVOLVE_DIR);
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    writeFileSync(tokenUsagePath(target.baseDir), `${JSON.stringify(record)}\n`, {
-        encoding: "utf8",
-        flag: "a",
-        mode: 0o600,
-    });
-    pruneJsonlFile(tokenUsagePath(target.baseDir), target.retain);
-}
-/** Load valid records from the retained ledger; malformed lines never break `/evolve usage`. */
-export function loadTokenUsage(baseDir) {
-    const path = tokenUsagePath(baseDir);
-    if (!existsSync(path))
-        return { records: [], corruptLines: 0 };
-    let lines;
-    try {
-        lines = readFileSync(path, "utf8").split("\n");
-    }
-    catch {
-        return { records: [], corruptLines: 0 };
-    }
-    const records = [];
-    let corruptLines = 0;
-    for (const line of lines) {
-        if (line.trim().length === 0)
-            continue;
-        try {
-            const parsed = JSON.parse(line);
-            if (isTokenUsageRecord(parsed))
-                records.push(parsed);
-            else
-                corruptLines += 1;
-        }
-        catch {
-            corruptLines += 1;
-        }
-    }
-    return { records, corruptLines };
-}
-/** Sum exact provider-reported buckets without double-counting reasoning or cache fields. */
-export function aggregateTokenUsage(records) {
-    const totals = {
-        calls: records.length,
-        reportedCalls: 0,
-        missingUsageCalls: 0,
-        uncachedInputTokens: 0,
-        cacheReadTokens: 0,
-        cacheWriteTokens: 0,
-        outputTokens: 0,
-        reasoningTokens: 0,
-        totalTokens: 0,
-    };
-    for (const record of records) {
-        if (record.usageStatus === "missing" || !record.usage) {
-            totals.missingUsageCalls += 1;
-            continue;
-        }
-        totals.reportedCalls += 1;
-        totals.uncachedInputTokens += record.usage.inputTokens;
-        totals.cacheReadTokens += record.usage.cacheReadTokens ?? 0;
-        totals.cacheWriteTokens += record.usage.cacheWriteTokens ?? 0;
-        totals.outputTokens += record.usage.outputTokens;
-        totals.reasoningTokens += record.usage.reasoningTokens ?? 0;
-        totals.totalTokens += exactTokenTotal(record.usage);
-    }
-    return totals;
-}
-/** Render the human-facing direct-call ledger section. */
-export function renderTokenUsageReport(ledger, retain) {
-    const { records, corruptLines } = ledger;
-    if (records.length === 0) {
-        const corrupt = corruptLines > 0 ? ` ${corruptLines} corrupt line(s) ignored.` : "";
-        return [
-            `direct LLM token usage: no valid calls in the retained tail.${corrupt}`,
-            `window: last ${retain} call(s), not a lifetime total.`,
-            "scope: review/memory/planner/wrapup/fate only; host benchmark subagents, their agent-loop calls, and per-entry injection cost are excluded.",
-        ];
-    }
-    const totals = aggregateTokenUsage(records);
-    const lines = [
-        `direct LLM token usage: ${totals.calls} valid calls (${totals.reportedCalls} reported usage, ${totals.missingUsageCalls} missing)${corruptLines > 0 ? `; ${corruptLines} corrupt line(s) ignored` : ""}`,
-        `  uncached input: ${totals.uncachedInputTokens}`,
-        `  cache read:     ${totals.cacheReadTokens}`,
-        `  cache write:    ${totals.cacheWriteTokens}`,
-        `  output:         ${totals.outputTokens}`,
-        `  reasoning:      ${totals.reasoningTokens}${records.some((record) => record.usageStatus === "reported" && record.usage?.reasoningTokens === undefined) ? " (partial provider reports)" : ""}`,
-        `  exact total:    ${totals.totalTokens} (reported calls only)`,
-        `window: last ${retain} call(s), not a lifetime total.`,
-        "by phase:",
-    ];
-    for (const phase of TOKEN_USAGE_PHASES) {
-        const phaseRecords = records.filter((record) => record.phase === phase);
-        if (phaseRecords.length === 0)
-            continue;
-        const phaseTotals = aggregateTokenUsage(phaseRecords);
-        lines.push(`  ${phase.padEnd(7)} ${phaseTotals.calls} calls · ${phaseTotals.totalTokens} tokens`);
-    }
-    const last = records.at(-1);
-    if (last) {
-        const lastTotal = last.usage ? exactTokenTotal(last.usage) : "usage unavailable";
-        lines.push(`last: ${last.phase} ${last.provider}/${last.model} · ${last.outcome} · ${lastTotal} tokens · ${last.timestamp}`);
-    }
-    lines.push("scope: review/memory/planner/wrapup/fate only; host benchmark subagents, their agent-loop calls, and per-entry injection cost are excluded.");
-    return lines;
-}
-function isTokenUsageRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return false;
-    const record = value;
-    if (record["version"] !== TOKEN_USAGE_LEDGER_VERSION ||
-        typeof record["timestamp"] !== "string" ||
-        typeof record["sessionId"] !== "string" ||
-        typeof record["provider"] !== "string" ||
-        typeof record["model"] !== "string" ||
-        typeof record["outcome"] !== "string" ||
-        !TOKEN_USAGE_PHASES.includes(record["phase"]) ||
-        !["success", "max-tokens", "error", "aborted", "empty"].includes(record["outcome"]) ||
-        !["reported", "missing"].includes(record["usageStatus"]) ||
-        !["provider", "derived", "unavailable"].includes(record["totalSource"])) {
-        return false;
-    }
-    if (record["usageStatus"] === "missing") {
-        return record["usage"] === undefined && record["totalSource"] === "unavailable";
-    }
-    if (!isTokenUsage(record["usage"]))
-        return false;
-    const expectedSource = record["usage"]["totalTokens"] !== undefined ? "provider" : "derived";
-    return record["totalSource"] === expectedSource;
-}
-function isCount(value) {
-    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-function isTokenUsage(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        return false;
-    const usage = value;
-    if (!isCount(usage["inputTokens"]) || !isCount(usage["outputTokens"]))
-        return false;
-    for (const key of ["totalTokens", "cacheReadTokens", "cacheWriteTokens", "reasoningTokens"]) {
-        if (usage[key] !== undefined && !isCount(usage[key]))
-            return false;
-    }
-    return true;
-}
-//# sourceMappingURL=token-usage.js.map

package/lib/tool.d.ts

@@ -1,34 +0,0 @@
-/**
- * Model-facing evolve_* tools. The model supplies content; every guarantee
- * (validation, snapshot, versioning, history, rollback) is code-enforced in
- * the engine. `global: true` is required explicitly for cross-session edits.
- */
-import type { Context } from "@deepseek-ai/cordis";
-import type { RecordLanguagePreference } from "./record-language.js";
-import type { HarnessScope } from "./types.js";
-import type { EvolutionEngine } from "./service.js";
-/**
- * Accept the string form (`scope: "project"`) with the legacy boolean tool
- * parameter (`global: true`) as fallback. `scope` wins when both are given.
- */
-export declare function scopeOf(value: unknown, fallback: HarnessScope): HarnessScope;
-/**
- * Collect the target ids for an evolve_delete call: legacy single `id`
- * plus the batch `ids` array, de-duplicated in first-seen order. Throws
- * loudly when neither carries an id — a silent no-op delete would look
- * like success while deleting nothing.
- *
- * @throws when both `id` and `ids` are absent or empty.
- */
-export declare function collectDeleteIds(id: unknown, ids: unknown): string[];
-export interface ToolGateOptions {
-    requireGlobalApproval: boolean;
-    /**
-     * Plugin `recordLanguage` preference for the approval dialog copy;
-     * `auto`/absent defers to the durable client preference and the session's
-     * own user text (see `approval.ts`).
-     */
-    recordLanguage?: RecordLanguagePreference;
-}
-export declare function registerEvolveTools(ctx: Context, engine: EvolutionEngine, opts: ToolGateOptions): void;
-//# sourceMappingURL=tool.d.ts.map

package/lib/tool.js

@@ -1,320 +0,0 @@
-import { defineTool } from "@deepseek-ai/dsh-tools";
-import { MEMORY_TYPE_KEY } from "./types.js";
-import { projectKeyOf } from "./project.js";
-import { formatHarnessStateForPrompt } from "./render.js";
-import { requireGlobalApproval } from "./approval.js";
-import { CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry } from "./promotion.js";
-import { entrySourceOf } from "./source.js";
-import { formatRecallResult, recallMemories } from "./recall.js";
-import { getUsageCount, loadUsage } from "./usage.js";
-import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
-import { DEFAULT_REVIEWS_RETAIN } from "./store.js";
-const SCOPES = ["local", "project", "global"];
-/**
- * Accept the string form (`scope: "project"`) with the legacy boolean tool
- * parameter (`global: true`) as fallback. `scope` wins when both are given.
- */
-export function scopeOf(value, fallback) {
-    if (value === "global" || value === true) {
-        return "global";
-    }
-    if (value === "project") {
-        return "project";
-    }
-    return fallback;
-}
-/** The calling agent's session id; tools always run inside an agent scope. */
-function sessionIdOf(exec) {
-    return exec.agent?.id;
-}
-/**
- * Collect the target ids for an evolve_delete call: legacy single `id`
- * plus the batch `ids` array, de-duplicated in first-seen order. Throws
- * loudly when neither carries an id — a silent no-op delete would look
- * like success while deleting nothing.
- *
- * @throws when both `id` and `ids` are absent or empty.
- */
-export function collectDeleteIds(id, ids) {
-    const collected = [];
-    if (typeof id === "string" && id.length > 0)
-        collected.push(id);
-    if (Array.isArray(ids)) {
-        for (const item of ids) {
-            if (typeof item === "string" && item.length > 0 && !collected.includes(item)) {
-                collected.push(item);
-            }
-        }
-    }
-    if (collected.length === 0) {
-        throw new Error("evolve_delete requires id or a non-empty ids array");
-    }
-    return collected;
-}
-/**
- * The store id a scope reads/writes: session id for local, derived project
- * key for project, undefined for global. Throws for project when the
- * session cwd is unavailable — fail loud instead of writing local-by-mistake.
- */
-function storeIdFor(scope, exec) {
-    if (scope === "local") {
-        return sessionIdOf(exec);
-    }
-    if (scope === "project") {
-        const key = projectKeyOf(exec.agent);
-        if (!key) {
-            throw new Error("project scope needs the session cwd (unavailable for this agent) — use local or global instead");
-        }
-        return key;
-    }
-    return undefined;
-}
-/** Human-approval gate shared by global and project writes (both cross-session). */
-function needsApproval(scope) {
-    return scope === "global" || scope === "project";
-}
-/** Store label used in approval prompts. */
-function storeLabel(scope) {
-    return scope === "project" ? "本项目跨会话 store" : "跨会话全局 store";
-}
-function textResult(text) {
-    return { text };
-}
-export function registerEvolveTools(ctx, engine, opts) {
-    ctx.tools.register(defineTool({
-        name: "evolve_list",
-        description: "List the harness state (prompt notes, memories, skills, subagent specs) for one store.",
-        parameters: {
-            scope: {
-                type: "string",
-                enum: SCOPES,
-                description: "'local' (default), 'project', or 'global'.",
-            },
-        },
-        output: {
-            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        execute: async (args, exec) => {
-            const scope = scopeOf(args.scope, "local");
-            const state = engine.load(scope, storeIdFor(scope, exec));
-            const text = formatHarnessStateForPrompt(state);
-            // Append injection usage counts (gap B1).
-            const usage = loadUsage(engine.baseDir);
-            const usageLines = [];
-            for (const kind of Object.keys(state.entries)) {
-                for (const entry of Object.values(state.entries[kind])) {
-                    const count = getUsageCount(usage, kind, entry.id);
-                    if (count > 0) {
-                        usageLines.push(`${kind}:${entry.id} — injected ${count}×`);
-                    }
-                }
-            }
-            if (usageLines.length > 0) {
-                return textResult(`${text}\n\n# Injection Usage\n${usageLines.join("\n")}`);
-            }
-            return textResult(text);
-        },
-    }));
-    ctx.tools.register(defineTool({
-        name: "evolve_recall",
-        description: "Read-only targeted recall across the harness stores: filter by query, kind, scope, and memory type; returns full content with version, source, and staleness signals. Prefer this over evolve_list when looking for something specific.",
-        parameters: {
-            query: { type: "string", description: "Free-text relevance query. Empty → most-recently-updated first." },
-            kinds: {
-                type: "array",
-                items: { type: "string" },
-                description: "Entry kinds (default memory only).",
-            },
-            scopes: {
-                type: "array",
-                items: { type: "string" },
-                description: "Stores to search (default all three).",
-            },
-            memoryTypes: {
-                type: "array",
-                items: { type: "string" },
-                description: "Memory types: user, feedback, project, reference.",
-            },
-            limit: { type: "number", description: "Max hits (default 10, max 50)." },
-            includeArchived: { type: "boolean", description: "Include archived entries (default false)." },
-        },
-        output: {
-            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        execute: async (args, exec) => {
-            const result = recallMemories(engine, { sessionId: sessionIdOf(exec), projectKey: projectKeyOf(exec.agent) ?? undefined }, {
-                ...(typeof args.query === "string" ? { query: args.query } : {}),
-                ...(Array.isArray(args.kinds) ? { kinds: args.kinds } : {}),
-                ...(Array.isArray(args.scopes) ? { scopes: args.scopes } : {}),
-                ...(Array.isArray(args.memoryTypes) ? { memoryTypes: args.memoryTypes } : {}),
-                ...(typeof args.limit === "number" ? { limit: args.limit } : {}),
-                ...(typeof args.includeArchived === "boolean" ? { includeArchived: args.includeArchived } : {}),
-            });
-            return textResult(formatRecallResult(result, typeof args.query === "string" ? args.query : undefined));
-        },
-    }));
-    ctx.tools.register(defineTool({
-        name: "evolve_add",
-        description: "Create one harness entry (prompt/memory/skill/subagent). Snapshots, versioning, and audit are automatic.",
-        parameters: {
-            kind: { type: "string", enum: ["prompt", "memory", "skill", "subagent"], required: true, description: "Entry kind." },
-            title: { type: "string", required: true, description: "Stable title." },
-            content: { type: "string", required: true, description: "Entry body." },
-            path: { type: "string", description: "Optional grouping path." },
-            skill_kind: { type: "string", enum: ["executable", "guidance"], description: "Skills: executable (default, needs reference) or guidance (SKILL.md, no reference)." },
-            reference: { type: "object", additionalProperties: true, description: "Executable skills: {type:'python', import, callable}." },
-            arguments: { type: "object", additionalProperties: true, description: "Executable skills: accepted input contract." },
-            memoryType: { type: "string", enum: ["user", "feedback", "project", "reference"], description: "Required for memory (feedback/project need Why + How to apply)." },
-            scope: { type: "string", enum: SCOPES, description: "'local' (default), 'project', or 'global'." },
-            global: { type: "boolean", description: "Shorthand for scope='global' (requires human approval)." },
-        },
-        output: {
-            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        execute: async (args, exec) => {
-            const scope = scopeOf(args.scope ?? args.global, "local");
-            // Resolve first: a project scope without a session cwd fails
-            // here, before any human approval question is asked.
-            const storeId = storeIdFor(scope, exec);
-            if (needsApproval(scope) && opts.requireGlobalApproval) {
-                // Informed approval: surface a similarity hit against the
-                // target store BEFORE the human decides — the engine's
-                // write-time guard still has the final say.
-                const targetState = engine.load(scope, storeId);
-                const hit = mostSimilarEntry(Object.values(targetState.entries[args.kind]), args.title ?? "", args.content ?? "", CONFLICT_WARN_SCORE);
-                const conflictNote = hit ? ` ⚠️ ${buildConflictNotice(hit)}——建议改用 evolve_update` : "";
-                await requireGlobalApproval(ctx, exec.agent, exec.signal, `evolve_add ${args.kind} "${args.title}" → ${storeLabel(scope)}${conflictNote}`, opts.recordLanguage);
-            }
-            const edit = {
-                action: "create",
-                kind: args.kind,
-                title: args.title,
-                content: args.content,
-            };
-            if (args.path !== undefined)
-                edit.path = args.path;
-            if (args.skill_kind !== undefined)
-                edit.skill_kind = args.skill_kind;
-            if (args.reference !== undefined)
-                edit.reference = args.reference;
-            if (args.arguments !== undefined)
-                edit.arguments = args.arguments;
-            if (args.kind === "memory" && args.memoryType !== undefined) {
-                edit.metadata = { [MEMORY_TYPE_KEY]: args.memoryType };
-            }
-            return textResult(applyEditsText(engine, scope, storeId, [edit], exec.agent, sessionIdOf(exec)));
-        },
-    }));
-    ctx.tools.register(defineTool({
-        name: "evolve_update",
-        description: "Update one harness entry by id. Pass only the fields that change.",
-        parameters: {
-            kind: { type: "string", enum: ["prompt", "memory", "skill", "subagent"], required: true },
-            id: { type: "string", required: true, description: "Existing entry id." },
-            title: { type: "string" },
-            content: { type: "string" },
-            memoryType: { type: "string", enum: ["user", "feedback", "project", "reference"], description: "Memory: (re)classify the recall type." },
-            scope: { type: "string", enum: SCOPES, description: "'local' (default), 'project', or 'global'." },
-            global: { type: "boolean", description: "Shorthand for scope='global' (requires human approval)." },
-        },
-        output: {
-            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        execute: async (args, exec) => {
-            const scope = scopeOf(args.scope ?? args.global, "local");
-            const storeId = storeIdFor(scope, exec);
-            if (needsApproval(scope) && opts.requireGlobalApproval) {
-                await requireGlobalApproval(ctx, exec.agent, exec.signal, `evolve_update ${args.kind}:${args.id} → ${storeLabel(scope)}`, opts.recordLanguage);
-            }
-            const edit = { action: "update", kind: args.kind, id: args.id };
-            if (args.title !== undefined)
-                edit.title = args.title;
-            if (args.content !== undefined)
-                edit.content = args.content;
-            if (args.memoryType !== undefined)
-                edit.metadata = { [MEMORY_TYPE_KEY]: args.memoryType };
-            return textResult(applyEditsText(engine, scope, storeId, [edit], exec.agent, sessionIdOf(exec)));
-        },
-    }));
-    ctx.tools.register(defineTool({
-        name: "evolve_delete",
-        description: "Delete harness entries: `id` for one, `ids` for a batch (one refinement, one approval). Ids are addressed verbatim, scope-prefixed or not.",
-        parameters: {
-            kind: { type: "string", enum: ["prompt", "memory", "skill", "subagent"], required: true },
-            id: { type: "string", description: "One entry id (or use ids for a batch)." },
-            ids: {
-                type: "array",
-                items: { type: "string" },
-                description: "Entry ids for one batch delete.",
-            },
-            scope: { type: "string", enum: SCOPES, description: "'local' (default), 'project', or 'global'." },
-            global: { type: "boolean", description: "Shorthand for scope='global' (requires human approval)." },
-        },
-        output: {
-            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        execute: async (args, exec) => {
-            const scope = scopeOf(args.scope ?? args.global, "local");
-            const storeId = storeIdFor(scope, exec);
-            const ids = collectDeleteIds(args.id, args.ids);
-            if (needsApproval(scope) && opts.requireGlobalApproval) {
-                await requireGlobalApproval(ctx, exec.agent, exec.signal, `evolve_delete ${args.kind}:${ids.length > 1 ? `${ids.length} entries (${ids.join(", ")})` : ids[0]} → ${storeLabel(scope)}`, opts.recordLanguage);
-            }
-            const edits = ids.map((id) => ({ action: "delete", kind: args.kind, id }));
-            return textResult(applyEditsText(engine, scope, storeId, edits, exec.agent, sessionIdOf(exec)));
-        },
-    }));
-    ctx.tools.register(defineTool({
-        name: "evolve_rollback",
-        description: "Deterministically revert a previous refinement by its id (from evolve_list history or /evolve).",
-        parameters: {
-            refinementId: { type: "string", required: true, description: "Refinement id to roll back." },
-            scope: { type: "string", enum: SCOPES, description: "'local' (default), 'project', or 'global'." },
-            global: { type: "boolean", description: "Shorthand for scope='global'." },
-        },
-        output: {
-            schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true } } },
-            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
-        },
-        execute: async (args, exec) => {
-            const scope = scopeOf(args.scope ?? args.global, "local");
-            const result = engine.rollback(scope, storeIdFor(scope, exec), args.refinementId);
-            return textResult(`Rolled back ${result.rollbackOf ?? result.id}: ${result.appliedEdits.filter((e) => e.applied).length} edit(s) reverted.`);
-        },
-    }));
-}
-function applyEditsText(engine, scope, storeId, edits, agent, eventSessionId) {
-    const result = engine.apply(scope, storeId, {
-        summary: "Direct tool edit",
-        rationale: "Model-invoked single edit via evolve_* tool.",
-        expectedOutcome: "Entry is created, updated, or deleted as requested.",
-        edits,
-    }, agent
-        ? {
-            scope,
-            ...(entrySourceOf(agent, eventSessionId ?? storeId) ? { source: entrySourceOf(agent, eventSessionId ?? storeId) } : {}),
-        }
-        : { scope });
-    const applied = result.appliedEdits.filter((e) => e.applied);
-    const failed = result.appliedEdits.filter((e) => !e.applied);
-    // Gap C4: emit structured evolve_complete event for third-party consumers.
-    // The event keys on the live session (not the project store key).
-    const eventSession = eventSessionId ?? storeId;
-    if (applied.length > 0 && eventSession) {
-        emitEvolveComplete(engine.baseDir, buildEvolveCompleteEvent(result, "manual_tool", eventSession), engine.retention?.reviews ?? DEFAULT_REVIEWS_RETAIN);
-    }
-    const lines = [`refinement ${result.id}: ${applied.length} applied, ${failed.length} failed`];
-    for (const e of applied) {
-        lines.push(`- ${e.action} ${e.kind}:${e.id} (v${(e.after?.version ?? e.before?.version) ?? "?"})`);
-    }
-    for (const e of failed) {
-        lines.push(`- failed ${e.action} ${e.kind}:${e.id ?? "(computed)"} — ${e.error ?? "unknown error"}`);
-    }
-    return lines.join("\n");
-}
-//# sourceMappingURL=tool.js.map

package/lib/turn-snapshot.d.ts

@@ -1,72 +0,0 @@
-/**
- * Turn-boundary snapshots for the automatic review gate.
- *
- * The scheduler must see a bounded, mechanically filtered slice of the
- * current session, not a fresh full-history LLM request on every turn. This
- * module owns the snapshot boundary, cursor-compatible incremental rows, and
- * the cheap eligibility checks that run before any model call.
- */
-import type { Context } from "@deepseek-ai/cordis";
-import type { Agent } from "@deepseek-ai/dsh-agent";
-/** Why a scheduler snapshot was captured. */
-export type TurnSnapshotReason = "turn_snapshot" | "compact";
-/** Mechanical reasons a snapshot can be skipped without an LLM call. */
-export type SnapshotSkipReason = "no-new-events" | "internal-agent" | "direct-memory-write" | "no-user-prose";
-/** One immutable scheduler input. The cursor is a durable event boundary. */
-export interface TurnSnapshot {
-    readonly sessionId: string;
-    readonly projectKey?: string;
-    readonly turn: number;
-    readonly reason: TurnSnapshotReason;
-    readonly cursor: string;
-    readonly events: readonly unknown[];
-    readonly trajectory: string;
-    readonly userText: string;
-    readonly sourceSeqs: readonly number[];
-    readonly maxChars: number;
-    readonly minUserWords: number;
-    /** Cursor supplied by the shared scheduler before this snapshot selected events. */
-    readonly capturedAfterCursor?: string;
-    readonly eligible: boolean;
-    readonly skipReason?: SnapshotSkipReason;
-}
-/** Eligibility result kept separate so tests and future extractors share it. */
-export interface SnapshotEligibility {
-    readonly eligible: boolean;
-    readonly reason?: SnapshotSkipReason;
-    readonly userText: string;
-}
-/** ZCode's minimum user-prose threshold, counted as lexical words. */
-export declare const MEMORY_MIN_USER_WORDS = 3;
-/**
- * Capture the current durable surface and select only rows after `cursor`.
- * A seq-bearing session uses `seq:<n>`; older/test surfaces fall back to an
- * event-count cursor so the scheduler still has a deterministic boundary.
- */
-export declare function captureTurnSnapshot(ctx: Context, agent: Agent, opts: {
-    turn: number;
-    reason: TurnSnapshotReason;
-    cursor?: string;
-    maxChars: number;
-    minUserWords?: number;
-}): Promise<TurnSnapshot>;
-/**
- * Rebase one captured snapshot onto a phase-specific cursor while preserving
- * its outer boundary. The memory phase uses this after a downstream review or
- * fate failure: already-processed evidence is removed, but newly captured rows
- * remain available without moving the shared scheduler cursor backwards.
- */
-export declare function sliceTurnSnapshot(snapshot: TurnSnapshot, cursor: string): TurnSnapshot;
-/**
- * Decide whether the incremental rows deserve a model call. This intentionally
- * does not decide whether a fact is valuable; that remains the review model's
- * job. It only removes mechanical noise before the scheduler spends tokens.
- */
-export declare function evaluateSnapshotEligibility(events: readonly unknown[], internalAgent?: boolean, minUserWords?: number): SnapshotEligibility;
-/** True when an assistant row records an explicit evolve memory mutation. */
-export declare function containsDirectMemoryWrite(events: readonly unknown[]): boolean;
-/** Serialize only user/assistant text, retaining the bounded tail. */
-export declare function serializeSnapshotEvents(events: readonly unknown[], maxChars: number): string;
-/** A DSH subagent header is an internal source when its origin says so. */
-export declare function isInternalAgent(agent: Agent | undefined): boolean;
-//# sourceMappingURL=turn-snapshot.d.ts.map