dsh-context 0.63.0 → 0.65.0

package/lib/index.js

@@ -4,6 +4,7 @@ import { SessionLogOffset, deriveEventMessage, interruptedTurnClosers } from "@d
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, normalize, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { getHeapStatistics } from "node:v8";
 import z$1 from "@deepseek-ai/schemastery";
 import { randomUUID } from "node:crypto";
 //#region src/shared/providers.ts
@@ -2584,6 +2585,71 @@ function watchBalanceChannel(ctx) {
 	});
 }
 //#endregion
+//#region src/host/coldRead.ts
+/**
+* The host-wide cold-read governor (issue #121).
+*
+* Every cold read — the warm-up pass's per-session fold (backfill.ts) and
+* the detail route's cold rung (detail.ts) — materializes one session's
+* whole durable log: the persistence backend decodes every frame before it
+* can slice a single event, so a 10k-event session lands as a several-
+* hundred-MB object graph, and the harness pins its own floors on top (the
+* backend's two-entry decoded-log memo, the observation reader's five-entry
+* prepared-session cache). Those floors are the harness's to tune; what the
+* PLUGIN owns is how many of its cold reads run at once and whether a new
+* one starts on an already-hot heap. Before this gate the answer to both
+* was "unbounded": the dashboard's first open fires the corpus pass and the
+* session cards' / Agent network's per-session detail fan-out together, and
+* on a capped-heap host (an Electron main whose V8 ceiling cannot move)
+* that stacking was enough to push the process over its limit.
+*
+* The gate therefore admits one cold read at a time (FIFO) and only while
+* the heap leaves headroom for it. A skipped read never fails visibly: the
+* pass stops early (its folded rows persist; the rest refold on their next
+* live activity or a later process's pass) and the detail route answers its
+* typed null (the client keeps its last detail, the cards their no-data
+* note) — every degradation already designed, no functionality removed.
+*/
+/**
+* The high-water mark as a fraction of the process's own heap ceiling: a
+* cold read starts only below two-thirds full, leaving the top third for
+* the read itself plus the harness's floors. The ceiling is V8's real
+* limit, so every host class — a default-heap CLI, a capped Electron
+* main — gets its own mark from the same constant.
+*/
+const HIGH_WATER = 2 / 3;
+/** The process's own V8 reading. */
+function v8Reading() {
+	const stats = getHeapStatistics();
+	return {
+		used: stats.used_heap_size,
+		limit: stats.heap_size_limit
+	};
+}
+const noop = () => {};
+/**
+* One governor per host process, shared by both cold paths. `reading` is
+* injectable for tests; a throwing or garbage probe fails OPEN — the meter
+* must never block a read (the version probe's philosophy).
+*/
+function makeColdReadGate(reading = v8Reading) {
+	const clear = () => {
+		try {
+			const { used, limit } = reading();
+			if (!Number.isFinite(used) || !Number.isFinite(limit) || limit <= 0) return true;
+			return used < limit * HIGH_WATER;
+		} catch {
+			return true;
+		}
+	};
+	let tail = Promise.resolve();
+	return { admit(read) {
+		const run = tail.then(() => clear() ? read() : void 0);
+		tail = run.then(noop, noop);
+		return run;
+	} };
+}
+//#endregion
 //#region src/host/backfill.ts
 /** The plugin's warm-up trigger route, under the authenticated `/api` fence. */
 const BACKFILL_ROUTE = "/api/dsh-context/backfill";
@@ -2702,9 +2768,12 @@ function messageOf(error) {
 * when the dashboard first opens; the cold-path faces compose `launch`.
 * Either half may land first; the first request after both launches the one
 * pass, and every later request is a no-op. Returns the deferred injects'
-* disposer (abort on unload).
+* disposer (abort on unload). Every cold read runs through the shared
+* host-wide gate (coldRead.ts): one read at a time, and the pass stops
+* early when the gate skips under heap pressure — folded rows persist and
+* every remaining session keeps its on-demand refold paths.
 */
-function watchActivityBackfill(ctx) {
+function watchActivityBackfill(ctx, coldReads = makeColdReadGate()) {
 	let requested = false;
 	let started = false;
 	let launch = null;
@@ -2752,6 +2821,7 @@ function watchActivityBackfill(ctx) {
 			if (!Array.isArray(listed)) return;
 			let folded = 0;
 			let refused = 0;
+			let paused = false;
 			for (const record of listed) {
 				if (abort.signal.aborted) return;
 				const header = headerOf(record);
@@ -2759,8 +2829,14 @@ function watchActivityBackfill(ctx) {
 				if (isLive(sessions, header.id)) continue;
 				if (servesRows(cache, header)) continue;
 				try {
-					const log = await readColdLog(persistence, header.id, abort.signal);
-					cache.coldSnapshot(log.header, log.inheritedEventCount, log.events);
+					if (await coldReads.admit(async () => {
+						const log = await readColdLog(persistence, header.id, abort.signal);
+						cache.coldSnapshot(log.header, log.inheritedEventCount, log.events);
+						return true;
+					}) === void 0) {
+						paused = true;
+						break;
+					}
 					folded++;
 				} catch (error) {
 					if (isUnsupportedFormat(error)) {
@@ -2771,6 +2847,7 @@ function watchActivityBackfill(ctx) {
 				await new Promise((resolve) => setTimeout(resolve, YIELD_MS));
 			}
 			if (folded > 0) ctx.logger.info(`dsh-context: projection rows backfilled for ${folded} session(s)`);
+			if (paused) ctx.logger.info("dsh-context: projection backfill stopped early under heap pressure (remaining sessions refold on their next live activity)");
 			if (refused > 0) ctx.logger.info(`dsh-context: projection backfill skipped ${refused} session(s) (legacy log format is not migratable; sources left unchanged)`);
 		};
 		launch = () => {
@@ -2893,7 +2970,7 @@ function failure(code, message) {
 * registration rides the injected fiber: either service unloading withdraws
 * the route and closes the gate.
 */
-function watchDetailChannel(ctx, bounds) {
+function watchDetailChannel(ctx, bounds, coldReads = makeColdReadGate()) {
 	const gate = { live: false };
 	ctx.inject(["connection", "sessions"], (c) => {
 		const connection = c.get("connection");
@@ -2930,22 +3007,21 @@ function watchDetailChannel(ctx, bounds) {
 					ok: true,
 					value: null
 				});
-				const observation = await observe(sessionId, { projectionMode: "none" });
-				const events = observation?.events;
-				if (!Array.isArray(events)) return reply({
-					ok: true,
-					value: null
-				});
-				let state = createTimelineState();
-				try {
-					for (const ev of events) state = applyTimeline(state, ev, bounds);
-				} finally {
-					const dispose = observation?.[Symbol.dispose];
-					if (typeof dispose === "function") dispose.call(observation);
-				}
 				return reply({
 					ok: true,
-					value: buildTimelineDetail(state, bounds)
+					value: await coldReads.admit(async () => {
+						const observation = await observe(sessionId, { projectionMode: "none" });
+						const events = observation?.events;
+						if (!Array.isArray(events)) return null;
+						let state = createTimelineState();
+						try {
+							for (const ev of events) state = applyTimeline(state, ev, bounds);
+						} finally {
+							const dispose = observation?.[Symbol.dispose];
+							if (typeof dispose === "function") dispose.call(observation);
+						}
+						return buildTimelineDetail(state, bounds);
+					}) ?? null
 				});
 			} catch (err) {
 				return failure("gateway/internal", err instanceof Error ? err.message : String(err));
@@ -3912,11 +3988,12 @@ function apply(ctx, config) {
 	}
 	const attribution = createToolAttribution(ctx);
 	watchStepIdentity(ctx);
-	const gate = watchDetailChannel(ctx, resolveBounds(config));
+	const coldReads = makeColdReadGate();
+	const gate = watchDetailChannel(ctx, resolveBounds(config), coldReads);
 	ctx.sessionProjections.register(createContextTimelineDefinition(config, () => gate.live));
 	ctx.sessionProjections.register(createContextHeadersDefinition((name) => attribution.ownerOf(name)));
 	ctx.sessionProjections.register(createContextActivityDefinition());
-	watchActivityBackfill(ctx);
+	watchActivityBackfill(ctx, coldReads);
 	installSettings(ctx);
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context",
-  "version": "0.63.0",
+  "version": "0.65.0",
   "description": "A DeepSeek Harness plugin for context insight and management, with context dashboard and context command, for understanding how the context is made of, and how it evolves.",
   "icon": "icon.svg",
   "author": "bowenliang123",