dsh-continual-evolve 0.6.1 → 0.7.1

package/lib/store.js

@@ -4,20 +4,49 @@
  * Layout (self-contained under the DSH home; no dependency on session
  * persistence internals):
  *
- *   <dshHome>/evolve/global/harness_state.json    cross-session store
+ *   <dshHome>/evolve/global/harness_state.json    cross-project store
  *   <dshHome>/evolve/global/refinements.jsonl     applied results (rollback source)
- *   <dshHome>/evolve/local/<sessionId>/...        per-session store
+ *   <dshHome>/evolve/projects/<slug-hash>/...     per-project store
+ *   <dshHome>/evolve/local/<sessionId>/...        per-session staging store
  *
  * Snapshot discipline is code-enforced: before any mutating apply, the
  * pre-apply state is copied to `snapshots/<refinementId>.json`. The model has
  * no way to skip it — it runs inside the service, not in a prompt.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { sanitizeProjectKey } from "./project.js";
 import { stateFilePath } from "./state.js";
 export const EVOLVE_DIR = "evolve";
+/**
+ * Storage-hygiene defaults (#20): history used to grow append-only without
+ * bound (dozens of full-state snapshot copies, unbounded JSONL). Retention
+ * is count-based and generous — rollback only ever needs recent snapshots
+ * and readers (`failures.ts` over reviews) need a working window, not the
+ * full past. Tunable via the `historyRetain` plugin config.
+ */
+export const DEFAULT_SNAPSHOT_RETAIN = 20;
+export const DEFAULT_REFINEMENTS_RETAIN = 500;
+export const DEFAULT_REVIEWS_RETAIN = 500;
+export const DEFAULT_TOKEN_USAGE_RETAIN = 500;
+/** Defaults applied for absent / non-positive retention fields (fail loud never: clamp, don't throw). */
+export function resolveHistoryRetention(raw) {
+    const pick = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+    return {
+        snapshots: pick(raw?.snapshots, DEFAULT_SNAPSHOT_RETAIN),
+        refinements: pick(raw?.refinements, DEFAULT_REFINEMENTS_RETAIN),
+        reviews: pick(raw?.reviews, DEFAULT_REVIEWS_RETAIN),
+        tokenUsage: pick(raw?.tokenUsage, DEFAULT_TOKEN_USAGE_RETAIN),
+    };
+}
+/**
+ * Resolve store paths for a scope. For `project` the `sessionId` parameter
+ * carries the project key (see {@link resolveProjectKey} in project.ts) —
+ * it is sanitized to a single path segment so an externally supplied key
+ * can never traverse out of `evolve/projects/`.
+ */
 export function storePaths(baseDir, scope, sessionId) {
-    const scopeDir = scope === "global" ? "global" : join("local", sessionId ?? "anonymous");
+    const scopeDir = scope === "global" ? "global" : scope === "project" ? join("projects", sanitizeProjectKey(sessionId ?? "project")) : join("local", sessionId ?? "anonymous");
     const stateDir = join(baseDir, EVOLVE_DIR, scopeDir);
     return {
         stateDir,
@@ -41,6 +70,72 @@ export function appendResult(paths, result) {
     mkdirSync(paths.stateDir, { recursive: true });
     writeFileSync(paths.resultsPath, `${JSON.stringify(result)}\n`, { encoding: "utf8", flag: "a" });
 }
+/**
+ * Prune a store's snapshots to the newest `retain` files (by mtime, oldest
+ * first). Best-effort: a missing directory or an unlink failure never breaks
+ * the apply path — the next apply retries.
+ */
+export function pruneSnapshots(snapshotsDir, retain) {
+    const keep = Math.floor(retain);
+    if (!(keep > 0) || !existsSync(snapshotsDir))
+        return;
+    let files;
+    try {
+        files = readdirSync(snapshotsDir).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return; // unreadable directory — leave it for the next attempt
+    }
+    if (files.length <= keep)
+        return;
+    const withTime = [];
+    for (const file of files) {
+        try {
+            withTime.push({ file, mtime: statSync(join(snapshotsDir, file)).mtimeMs });
+        }
+        catch {
+            // unstatable file — keep it rather than delete blindly
+        }
+    }
+    withTime.sort((a, b) => a.mtime - b.mtime);
+    for (const victim of withTime.slice(0, Math.max(0, withTime.length - keep))) {
+        try {
+            unlinkSync(join(snapshotsDir, victim.file));
+        }
+        catch {
+            // one bad unlink must not stop the sweep or the apply path
+        }
+    }
+}
+/**
+ * Truncate a JSONL file to its last `retain` non-empty lines. No-op when the
+ * file is missing or already within budget — the common case costs one
+ * read and no write.
+ */
+export function pruneJsonlFile(path, retain) {
+    const keep = Math.floor(retain);
+    if (!(keep > 0) || !existsSync(path))
+        return;
+    let lines;
+    try {
+        lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
+    }
+    catch {
+        return; // unreadable file — leave it for the next attempt
+    }
+    if (lines.length <= keep)
+        return;
+    try {
+        writeFileSync(path, `${lines.slice(-keep).join("\n")}\n`, "utf8");
+    }
+    catch {
+        // truncation failure must not break the write path that called it
+    }
+}
+/** Reviews audit-trail path shared by the gate, fate, and tool events. */
+export function reviewsPath(baseDir) {
+    return join(baseDir, EVOLVE_DIR, "reviews.jsonl");
+}
 /** Read the applied results history; malformed lines are skipped, never fatal. */
 export function loadResults(paths) {
     if (!existsSync(paths.resultsPath)) {

package/lib/token-usage.d.ts

@@ -0,0 +1,68 @@
+import type { TokenUsage } from "@deepseek-ai/dsh-llm";
+import type { StreamTextObservation, StreamTextUsageObserver } from "./llm-text.js";
+export declare const TOKEN_USAGE_LEDGER_VERSION = 1;
+/** Plugin-owned direct call paths represented in the ledger. */
+export declare const TOKEN_USAGE_PHASES: readonly ["review", "planner", "wrapup", "fate"];
+export type TokenUsagePhase = (typeof TOKEN_USAGE_PHASES)[number];
+/** Whether the provider supplied a usage sample; missing is never treated as zero. */
+export type TokenUsageStatus = "reported" | "missing";
+/** How the exact full-call total was obtained. */
+export type TokenTotalSource = "provider" | "derived" | "unavailable";
+/** One retained direct-call observation. */
+export interface TokenUsageRecord {
+    version: typeof TOKEN_USAGE_LEDGER_VERSION;
+    timestamp: string;
+    sessionId: string;
+    phase: TokenUsagePhase;
+    provider: string;
+    model: string;
+    outcome: StreamTextObservation["outcome"];
+    usageStatus: TokenUsageStatus;
+    /** Absent exactly when {@link usageStatus} is `missing`. */
+    usage?: TokenUsage;
+    totalSource: TokenTotalSource;
+}
+/** Caller-owned destination and failure hook; phase/provider/model are supplied by the call site. */
+export interface TokenUsageTarget {
+    baseDir: string;
+    sessionId: string;
+    retain: number;
+    onError?: (cause: unknown) => void;
+}
+/** Loaded retained window plus corrupt-line count for honest coverage reporting. */
+export interface LoadedTokenUsage {
+    records: TokenUsageRecord[];
+    corruptLines: number;
+}
+/** Aggregate provider-reported buckets over a retained ledger window. */
+export interface TokenUsageTotals {
+    calls: number;
+    reportedCalls: number;
+    missingUsageCalls: number;
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    totalTokens: number;
+}
+/** Absolute path of the direct-call token ledger. */
+export declare function tokenUsagePath(baseDir: string): string;
+/** Exact full-call total, with the old-peer fallback only when `totalTokens` is absent. */
+export declare function exactTokenTotal(usage: TokenUsage): number;
+/** Build the observer attached to one `streamText` call. Errors are diagnostic-only. */
+export declare function createTokenUsageObserver(target: TokenUsageTarget, phase: TokenUsagePhase, provider: string, model: string): StreamTextUsageObserver;
+/**
+ * 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 declare function appendTokenUsage(target: TokenUsageTarget, record: TokenUsageRecord): void;
+/** Load valid records from the retained ledger; malformed lines never break `/evolve usage`. */
+export declare function loadTokenUsage(baseDir: string): LoadedTokenUsage;
+/** Sum exact provider-reported buckets without double-counting reasoning or cache fields. */
+export declare function aggregateTokenUsage(records: readonly TokenUsageRecord[]): TokenUsageTotals;
+/** Render the human-facing direct-call ledger section. */
+export declare function renderTokenUsageReport(ledger: LoadedTokenUsage, retain: number): string[];
+//# sourceMappingURL=token-usage.d.ts.map

package/lib/token-usage.js

@@ -0,0 +1,211 @@
+/**
+ * Provider-reported token accounting for plugin-owned direct LLM calls.
+ *
+ * The review gate, planner, wrap-up command, and local-fate classifier all use
+ * the shared `streamText` helper. 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 instead.
+ *
+ * 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", "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/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/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

@@ -6,8 +6,20 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { HarnessScope } from "./types.js";
 import type { EvolutionEngine } from "./service.js";
-/** Accept both the boolean tool parameter (`global: true`) and the string form. */
+/**
+ * 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;
 }