dsh-continual-evolve 0.7.0 → 0.7.2

package/lib/tool.d.ts

@@ -11,6 +11,15 @@ import type { EvolutionEngine } from "./service.js";
  * 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;
 }

package/lib/tool.js

@@ -7,6 +7,7 @@ import { CONFLICT_WARN_SCORE, buildConflictNotice, mostSimilarEntry } from "./pr
 import { entrySourceOf } from "./source.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
@@ -25,6 +26,30 @@ export function scopeOf(value, fallback) {
 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
@@ -177,10 +202,15 @@ export function registerEvolveTools(ctx, engine, opts) {
     }));
     ctx.tools.register(defineTool({
         name: "evolve_delete",
-        description: "Delete one harness entry by id.",
+        description: "Delete harness entries by id. Pass `id` for one entry or `ids` for several — a batch lands as one refinement behind one approval. Literal ids win: entries whose stored id itself carries a scope-like prefix (e.g. a legacy `local:…` id) are addressed verbatim.",
         parameters: {
             kind: { type: "string", enum: ["prompt", "memory", "skill", "subagent"], required: true },
-            id: { type: "string", required: true },
+            id: { type: "string", description: "Existing entry id (single delete; combine with ids or use ids for a batch)." },
+            ids: {
+                type: "array",
+                items: { type: "string" },
+                description: "Existing entry ids for one batch delete (one refinement, one approval).",
+            },
             scope: { type: "string", enum: SCOPES, description: "Target store: 'local' (default), 'project', or 'global'. Wins over the legacy global flag." },
             global: { type: "boolean", description: "Set true to edit the cross-session store (requires human approval)." },
         },
@@ -191,11 +221,12 @@ export function registerEvolveTools(ctx, engine, opts) {
         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}:${args.id} → ${storeLabel(scope)}`);
+                await requireGlobalApproval(ctx, exec.agent, exec.signal, `evolve_delete ${args.kind}:${ids.length > 1 ? `${ids.length} entries (${ids.join(", ")})` : ids[0]} → ${storeLabel(scope)}`);
             }
-            const edit = { action: "delete", kind: args.kind, id: args.id };
-            return textResult(applyEditsText(engine, scope, storeId, [edit], exec.agent, sessionIdOf(exec)));
+            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({
@@ -235,7 +266,7 @@ function applyEditsText(engine, scope, storeId, edits, agent, eventSessionId) {
     // 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));
+        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) {

package/lib/turn-snapshot.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 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;
+}
+/**
+ * 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;
+}): Promise<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): 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

package/lib/turn-snapshot.js

@@ -0,0 +1,188 @@
+import { sessionEventsOf } from "./inject.js";
+import { projectKeyOf } from "./project.js";
+/**
+ * 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 async function captureTurnSnapshot(ctx, agent, opts) {
+    const allEvents = await readSurface(ctx, agent);
+    const cursor = boundaryCursor(allEvents);
+    const events = eventsAfterCursor(allEvents, opts.cursor);
+    const eligibility = evaluateSnapshotEligibility(events, isInternalAgent(agent));
+    const projectKey = projectKeyOf(agent);
+    return {
+        sessionId: agent.id,
+        ...(projectKey ? { projectKey } : {}),
+        turn: opts.turn,
+        reason: opts.reason,
+        cursor,
+        events,
+        trajectory: eligibility.eligible ? serializeSnapshotEvents(events, opts.maxChars) : "",
+        userText: eligibility.userText,
+        sourceSeqs: directUserSeqs(events),
+        eligible: eligibility.eligible,
+        ...(eligibility.reason ? { skipReason: eligibility.reason } : {}),
+    };
+}
+/**
+ * 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 function evaluateSnapshotEligibility(events, internalAgent = false) {
+    if (internalAgent)
+        return { eligible: false, reason: "internal-agent", userText: "" };
+    if (events.length === 0)
+        return { eligible: false, reason: "no-new-events", userText: "" };
+    if (containsDirectMemoryWrite(events))
+        return { eligible: false, reason: "direct-memory-write", userText: "" };
+    const userText = directUserText(events);
+    if (userText.length < 3)
+        return { eligible: false, reason: "no-user-prose", userText };
+    return { eligible: true, userText };
+}
+/** True when an assistant row records an explicit evolve memory mutation. */
+export function containsDirectMemoryWrite(events) {
+    for (const event of events) {
+        if (!event || typeof event !== "object")
+            continue;
+        const row = event;
+        if (row.type === "tool/call" || row.type === "tool-call") {
+            if (isMemoryMutationName(readNestedString(row.data, ["name", "tool", "toolName"])))
+                return true;
+        }
+        if (row.type === "assistant/message" && containsMemoryMutationName(row.data))
+            return true;
+    }
+    return false;
+}
+/** Serialize only user/assistant text, retaining the bounded tail. */
+export function serializeSnapshotEvents(events, maxChars) {
+    const lines = [];
+    for (const raw of events) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const event = raw;
+        if (event.type === "user/message" && !isDirectUserEvent(raw))
+            continue;
+        const role = event.type === "user/message" ? "user" : event.type === "assistant/message" ? "assistant" : null;
+        if (role === null)
+            continue;
+        const text = contentText(event.data?.content).trim();
+        if (text.length > 0)
+            lines.push(`${role}: ${text}`);
+    }
+    const joined = lines.join("\n");
+    return joined.length <= maxChars ? joined : joined.slice(-maxChars);
+}
+/** A DSH subagent header is an internal source when its origin says so. */
+export function isInternalAgent(agent) {
+    const header = agent?.session?.header;
+    return header?.origin === "subagent" || header?.origin === "internal" || header?.isSubagent === true;
+}
+async function readSurface(ctx, agent) {
+    const reader = ctx.sessionQuery;
+    if (reader) {
+        const snapshot = await reader.readSurface(agent.id);
+        return Array.isArray(snapshot.events) ? snapshot.events : [];
+    }
+    return sessionEventsOf(agent);
+}
+function boundaryCursor(events) {
+    const seqs = events.map(eventSeq).filter((seq) => seq !== undefined);
+    return seqs.length > 0 ? `seq:${Math.max(...seqs)}` : `index:${events.length}`;
+}
+function eventsAfterCursor(events, cursor) {
+    if (cursor === undefined)
+        return events;
+    if (cursor.startsWith("seq:")) {
+        const boundary = Number(cursor.slice(4));
+        if (!Number.isFinite(boundary))
+            return events;
+        return events.filter((event) => {
+            const seq = eventSeq(event);
+            return seq === undefined || seq > boundary;
+        });
+    }
+    if (cursor.startsWith("index:")) {
+        const boundary = Number(cursor.slice(6));
+        return Number.isInteger(boundary) && boundary >= 0 ? events.slice(boundary) : events;
+    }
+    return events;
+}
+function directUserText(events) {
+    return events
+        .filter(isDirectUserEvent)
+        .map((event) => contentText(event.data?.content).trim())
+        .filter(Boolean)
+        .join("\n");
+}
+function directUserSeqs(events) {
+    return events
+        .filter(isDirectUserEvent)
+        .map(eventSeq)
+        .filter((seq) => seq !== undefined);
+}
+function isDirectUserEvent(event) {
+    if (!event || typeof event !== "object")
+        return false;
+    const row = event;
+    if (row.type !== "user/message")
+        return false;
+    if (row.data?.visibility === "model-only")
+        return false;
+    if (row.data?.source?.synthetic === true)
+        return false;
+    if (row.data?.source?.kind !== undefined && row.data.source.kind !== "user")
+        return false;
+    return contentText(row.data?.content).trim().length > 0;
+}
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => {
+        if (typeof block === "string")
+            return block;
+        if (!block || typeof block !== "object")
+            return "";
+        const value = block;
+        if (value.synthetic === true || value.ignored === true || (value.type !== undefined && value.type !== "text"))
+            return "";
+        return typeof value.text === "string" ? value.text : "";
+    })
+        .filter(Boolean)
+        .join(" ");
+}
+function eventSeq(event) {
+    if (!event || typeof event !== "object")
+        return undefined;
+    const seq = event.seq;
+    return typeof seq === "number" && Number.isInteger(seq) ? seq : undefined;
+}
+function containsMemoryMutationName(value) {
+    if (typeof value === "string")
+        return isMemoryMutationName(value);
+    if (Array.isArray(value))
+        return value.some(containsMemoryMutationName);
+    if (!value || typeof value !== "object")
+        return false;
+    return Object.values(value).some(containsMemoryMutationName);
+}
+function isMemoryMutationName(value) {
+    return value === "evolve_add" || value === "evolve_update" || value === "evolve_delete";
+}
+function readNestedString(value, keys) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const row = value;
+    for (const key of keys) {
+        if (typeof row[key] === "string")
+            return row[key];
+    }
+    return undefined;
+}
+//# sourceMappingURL=turn-snapshot.js.map

package/lib/wrapup-command.js

@@ -13,7 +13,16 @@ export async function executeWrapupCommand(ctx, engine, invocation, policy = DEF
         return success(`(nothing to wrap up: ${sessionId}'s local store has no active, un-promoted entries — use /evolve list to inspect it)`);
     }
     // 1. Classify: the model judges each audited candidate's fate.
-    const assessment = await assessLocalEntries(ctx, invocation.agent, candidates, { signal: invocation.signal });
+    const assessment = await assessLocalEntries(ctx, invocation.agent, candidates, {
+        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)}`),
+        },
+        tokenUsagePhase: "wrapup",
+    });
     const byKey = new Map(candidates.map((candidate) => [candidateKey(candidate.kind, candidate.id), candidate]));
     // 2. Partition by action. Deterministic guards re-check the LIVE global
     //    store right before anything lands (state may have changed mid-call).

package/lib/wrapup.d.ts

@@ -21,6 +21,7 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { HarnessEntry, HarnessState, RefinementKind, RefinementProposal } from "./types.js";
+import { type TokenUsageTarget } from "./token-usage.js";
 import { type PromotionPolicy } from "./promotion.js";
 /** What should happen to one local entry at session end. */
 export type WrapupVerdict = "promote" | "archive" | "keep";
@@ -238,6 +239,10 @@ export interface AssessOptions {
     maxOutputTokens?: number;
     /** Abort signal forwarded to the model call. */
     signal?: AbortSignal;
+    /** Direct-call token ledger destination; phase is selected by the caller. */
+    tokenUsage?: TokenUsageTarget;
+    /** Ledger phase for this classifier call (manual wrapup or automatic fate). */
+    tokenUsagePhase?: "wrapup" | "fate";
 }
 /**
  * Ask the model to classify the audited local candidates. Routes through the

package/lib/wrapup.js

@@ -4,6 +4,7 @@ import { extractJsonObject } from "./plan.js";
 import { compactText } from "./render.js";
 import { streamText } from "./llm-text.js";
 import { getUsageCount, loadUsage } from "./usage.js";
+import { createTokenUsageObserver } from "./token-usage.js";
 import { recencyScore } from "./inject.js";
 import { DEFAULT_PROMOTION_POLICY, mostSimilarGlobalEntry, projectScopedReason, secretLeakReason } from "./promotion.js";
 export function candidateKey(kind, id) {
@@ -525,6 +526,11 @@ export async function assessLocalEntries(ctx, agent, candidates, options = {}) {
         prompt: userPrompt,
         maxTokens: options.maxOutputTokens ?? 4096,
         signal: options.signal,
+        ...(options.tokenUsage
+            ? {
+                onUsage: createTokenUsageObserver(options.tokenUsage, options.tokenUsagePhase ?? "wrapup", agent.options.provider, agent.options.model),
+            }
+            : {}),
     });
     return parseWrapupAssessment(text, candidates);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-continual-evolve",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Continual self-evolution plugin for DeepSeek Harness: versioned, auditable, rollback-safe harness state (prompt notes, memories, skills, subagent specs) refined from session trajectories.",
   "license": "MIT",
   "repository": {