dsh-context-compression-improved 0.4.0 → 0.5.1

package/packages/selector/lib/index.js

@@ -1,4 +1,4 @@
-import { n as resolveReviewPruner, o as CONTEXT_COMPRESSION_SETTINGS_NAMESPACE, s as ContextCompressionSettingsSchema } from "./review-registry.js";
+import { d as ContextCompressionSettingsSchema, o as resolveReviewPruner, t as getAdvisorState, u as CONTEXT_COMPRESSION_SETTINGS_NAMESPACE } from "./advisor-state.js";
 import z from "@deepseek-ai/schemastery";
 import "@deepseek-ai/dsh-settings";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -118,6 +118,15 @@ function standingStampMsAtWindow(identity, windowIndex) {
 	const subSecond = parseInt(identity.slice(start + 8, start + STANDING_MTIME_WINDOW_HEX).padEnd(3, "0"), 16) % 1e3;
 	return seconds * 1e3 + subSecond;
 }
+/**
+* True for the filesystem errors a concurrent publish can raise on Windows:
+* `MoveFileEx` reports a lost race — or a reader holding the destination open —
+* as EPERM/EBUSY/EACCES, where POSIX `rename` simply replaces the destination.
+*/
+function isPublishRace(error) {
+	const code = error?.code;
+	return code === "EPERM" || code === "EBUSY" || code === "EACCES" || code === "EEXIST";
+}
 const COMPRESSION_IDS = /* @__PURE__ */ new Set([
 	"compaction",
 	"compaction-basic",
@@ -191,7 +200,7 @@ var PresetOverlayStore = class {
 			});
 			await chmod(staging, 384);
 			await this.disambiguateStamp(staging, identity);
-			await rename(staging, path);
+			await this.publish(staging, path);
 		} catch (error) {
 			try {
 				await rm(staging, { force: true });
@@ -203,6 +212,45 @@ var PresetOverlayStore = class {
 			path
 		};
 	}
+	/** In-flight publish chains, one per destination path. */
+	publishChains = /* @__PURE__ */ new Map();
+	/**
+	* Publish one stamped staging file to its final path, serialized per path.
+	*
+	* POSIX `rename` replaces an existing destination atomically, so concurrent
+	* composers of one identity are naturally idempotent there. Windows
+	* `MoveFileEx` instead fails the loser of that race with EPERM/EBUSY, which
+	* surfaced as `standingKeyFor()` throwing during concurrent composition.
+	* Every composer of one identity writes identical bytes and re-derives the
+	* same deterministic identity stamp, so a destination that already observes
+	* this staging file's {mtimeMs, size} key IS the intended end state: confirm
+	* it and treat the lost race as success. Every other outcome still throws, so
+	* a silently reused generation stays forbidden, and the caller still removes
+	* the staging file when this rejects.
+	*/
+	publish(staging, path) {
+		const tracked = (this.publishChains.get(path) ?? Promise.resolve()).catch(() => void 0).then(async () => {
+			try {
+				await rename(staging, path);
+				return;
+			} catch (error) {
+				if (!isPublishRace(error)) throw error;
+				try {
+					const intended = await this.metadataIo.read(staging);
+					const published = await this.metadataIo.read(path);
+					if (published.size === intended.size && Math.abs(published.mtimeMs - intended.mtimeMs) < 2) {
+						await rm(staging, { force: true });
+						return;
+					}
+				} catch {}
+				throw error;
+			}
+		}).finally(() => {
+			if (this.publishChains.get(path) === tracked) this.publishChains.delete(path);
+		});
+		this.publishChains.set(path, tracked);
+		return tracked;
+	}
 	/** Observed {mtimeMs,size} keys published by this store, per identity. */
 	standingKeys = /* @__PURE__ */ new Map();
 	/**
@@ -459,6 +507,7 @@ const CONTEXT_COMPRESSION_NAMESPACE = CONTEXT_COMPRESSION_SETTINGS_NAMESPACE;
 const ESTIMATOR_CATALOG_ROUTES = ["/endpoint/dsh-context-compression-improved/estimator-catalog", "/api/dsh-context-compression-improved/estimator-catalog"];
 const REVIEW_QUEUE_ROUTES = ["/endpoint/dsh-context-compression-improved/review-queue", "/api/dsh-context-compression-improved/review-queue"];
 const REVIEW_DECIDE_ROUTES = ["/endpoint/dsh-context-compression-improved/review-decide", "/api/dsh-context-compression-improved/review-decide"];
+const ADVISOR_REPORT_ROUTES = ["/endpoint/dsh-context-compression-improved/advisor-report", "/api/dsh-context-compression-improved/advisor-report"];
 /**
 * Resolve the review pipeline for the top-level routes.
 *
@@ -694,6 +743,102 @@ function registerReviewQueueRoutes(ctx) {
 	log("warn", "context-compression webServer not active yet — review routes pending: %s", REVIEW_QUEUE_ROUTES.join(", "));
 }
 /**
+* Serve the advisory advisor's read-only report route (same registration
+* skeleton as the review routes):
+*
+* `GET .../advisor-report?sessionId=…` → the session's prefix-decay figure,
+* the todolist-bound task summary, and the score distribution. Content-free
+* by construction: task semantics are LLM-derived summaries, never message
+* text, and no score reason or candidate preview is ever returned.
+* Unknown session → 404; no agents service → 503. A session whose advisor
+* never ran reports nulls and empty arrays, not an error.
+*/
+function registerAdvisorReportRoute(ctx) {
+	const readService = (name) => {
+		try {
+			return ctx.get(name);
+		} catch {
+			return;
+		}
+	};
+	const log = (level, message, ...args) => {
+		console[level](message, ...args);
+	};
+	const getHandler = (req, res) => {
+		if (typeof readService("agents")?.get !== "function") {
+			reviewJson(res, 503, {
+				ok: false,
+				error: "advisor report unavailable"
+			});
+			return;
+		}
+		let sessionId = "";
+		try {
+			sessionId = new URL(String(req.url ?? ""), "http://localhost").searchParams.get("sessionId") ?? "";
+		} catch {}
+		if (sessionId === "") {
+			reviewJson(res, 400, {
+				ok: false,
+				error: "sessionId is required"
+			});
+			return;
+		}
+		const session = sessionFor(readService, sessionId);
+		if (session === void 0) {
+			reviewJson(res, 404, {
+				ok: false,
+				error: "unknown session"
+			});
+			return;
+		}
+		const state = getAdvisorState(session);
+		reviewJson(res, 200, {
+			ok: true,
+			sessionId,
+			advisor: {
+				summary: state.summary ?? null,
+				decay: state.lastDecay?.decay ?? null,
+				weightedChars: state.lastDecay?.weightedChars ?? null,
+				decayTurn: state.lastDecay?.turn ?? null,
+				scores: [...state.scores].map(([seq, entry]) => ({
+					seq,
+					score: entry.score,
+					turn: entry.turn
+				})),
+				lowRelevanceSeqs: [...state.recertified.keys()]
+			}
+		});
+	};
+	const register = (webServer) => {
+		const disposers = [...ADVISOR_REPORT_ROUTES].map((path) => ({
+			path,
+			handler: getHandler
+		})).map((entry) => webServer.register({
+			kind: "exact",
+			path: entry.path,
+			handler: entry.handler
+		})).filter((off) => typeof off === "function");
+		ctx.effect(() => () => {
+			for (const off of disposers) off();
+		}, "contextCompressionSelector.advisor report route");
+		log("info", "context-compression advisor report route registered: %s", ADVISOR_REPORT_ROUTES.join(", "));
+	};
+	const active = asWebServer(readService("webServer"));
+	if (active !== void 0) {
+		register(active);
+		return;
+	}
+	ctx.inject(["webServer"], (injected) => {
+		const webServer = asWebServer(injected.webServer);
+		if (webServer === void 0) {
+			log("warn", "context-compression webServer exposes no register() — advisor report route not registered");
+			return;
+		}
+		register(webServer);
+	});
+	log("warn", "context-compression webServer not active yet — advisor report route pending: %s", ADVISOR_REPORT_ROUTES.join(", "));
+}
+/**
 * The one service the catalog route actually needs. `llm` and
 * `agentDefaultModel` are payload enrichment the handler resolves per request,
 * never reasons to withhold the route.
@@ -797,7 +942,8 @@ const SHARED_SETTINGS = Symbol.for("dsh-context-compression-improved/settings-re
 const Config = z.object({
 	presetOverlay: z.boolean().default(false),
 	estimatorCatalogRoute: z.boolean().default(false),
-	reviewQueueRoute: z.boolean().default(false)
+	reviewQueueRoute: z.boolean().default(false),
+	advisorReportRoute: z.boolean().default(false)
 });
 /** Register the persisted default read by the currently mounted root pruner. */
 function apply(ctx, config = {}) {
@@ -807,6 +953,7 @@ function apply(ctx, config = {}) {
 		});
 		if (config.estimatorCatalogRoute === true) registerEstimatorCatalogRoute(ctx);
 		if (config.reviewQueueRoute === true) registerReviewQueueRoutes(ctx);
+		if (config.advisorReportRoute === true) registerAdvisorReportRoute(ctx);
 		if (config.presetOverlay !== true) return;
 		ctx.inject(["agentPresets"], (presetsCtx) => {
 			const installation = decorateAgentPresets(presetsCtx.agentPresets, {

package/packages/selector/lib/pruner.d.ts

@@ -82,6 +82,20 @@ interface PresetOptions {
   readonly estimator: {
     readonly mode: '' | 'host' | 'direct';
   };
+  /**
+   * Advisory relevance advisor: statistics and suggestions only — every output
+   * (summaries, scores, decay, recertification) is observational and must never
+   * suppress, delay, or rewrite any reduction that would land. `''` (the
+   * default) keeps the advisor fully off.
+   */
+  readonly advisor: {
+    readonly mode: '' | 'host' | 'direct';
+    readonly timeoutMs: number;
+    readonly refreshTurns: number;
+    readonly scoreThreshold: number;
+    readonly sampleLimit: number;
+    readonly minTokens: number;
+  };
   /**
    * Human-gated review pipeline (beta): edge/high-impact candidates queue for
    * manual approval and execute in one merged batch at the next turn boundary
@@ -158,6 +172,13 @@ interface PresetOptionsSettings {
   readonly estimatorBaseUrl?: string;
   readonly estimatorApiKey?: string;
   readonly estimatorTimeoutMs?: number;
+  /** Advisory advisor channel; `''` (the default) keeps the advisor off. */
+  readonly advisorMode?: '' | 'host' | 'direct';
+  readonly advisorTimeoutMs?: number;
+  readonly advisorRefreshTurns?: number;
+  readonly advisorScoreThreshold?: number;
+  readonly advisorSampleLimit?: number;
+  readonly advisorMinTokens?: number;
 }
 /** Durable global preference exposed through `ctx.settings`. */
 interface ContextCompressionSettings {
@@ -336,6 +357,56 @@ interface PruneResult {
   readonly tokensRemoved: number;
 }
 //#endregion
+//#region src/runtime/tokenpilot/sidechannel.d.ts
+/** Audit record of one side-channel call (Phase 13). All fields optional-safe. */
+interface SideChannelAudit {
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  /** host|direct plus the resolved provider/model identity. */
+  readonly channel?: string;
+  /** L2 coverage: content shown N of node content total M. */
+  readonly coverage?: {
+    readonly shown: number;
+    readonly total: number;
+  };
+  readonly reason?: string;
+}
+interface SideChannelRequest {
+  readonly system: string;
+  readonly user: string;
+  readonly signal: AbortSignal;
+}
+/** One bound side channel. `ask` resolves `undefined` on ANY failure. */
+declare class SideChannel {
+  private readonly ctx;
+  private readonly options;
+  private readonly overrides?;
+  /**
+   * @param overrides - per-consumer overrides of the estimator-named options.
+   * The estimator itself never passes them (byte-identical behavior); the
+   * advisory advisor passes its own mode/timeout/output budget so both
+   * consumers share one transport without sharing one configuration.
+   */
+  constructor(ctx: Context, options: PresetOptionsSettings, overrides?: {
+    readonly mode?: "" | "host" | "direct";
+    readonly timeoutMs?: number;
+    readonly maxTokens?: number;
+  } | undefined);
+  private get mode();
+  get enabled(): boolean;
+  ask(request: SideChannelRequest): Promise<string | undefined>;
+  /** Failure-open wrapper that also records one audit record per call. */
+  askAudited(request: SideChannelRequest): Promise<{
+    text?: string;
+    audit: SideChannelAudit;
+  }>;
+  identity(): string | undefined;
+  /** Same host-route resolution as the estimator: explicit, then host default. */
+  private resolveHostRoute;
+  private askHost;
+  private askDirect;
+}
+//#endregion
 //#region src/runtime/tokenpilot/estimator.d.ts
 /** Per-session estimator failure bookkeeping for exponential backoff. */
 interface EstimatorFailures {
@@ -532,6 +603,8 @@ interface PrunerState {
   readonly reviewClocks: WeakMap<Session, number>;
   /** Estimator-reported remaining turns Ŝ per Session; advisory only. */
   readonly estimatorRemainingTurns: WeakMap<Session, number>;
+  /** Per-session advisor side channel, constructed once with the advisor overrides. */
+  readonly advisorChannels: WeakMap<Session, SideChannel>;
   /** Four-state outcome counters per Session (floating-window summary row). */
   readonly reviewSummaries: WeakMap<Session, ReviewSessionSummary>;
 }
@@ -847,6 +920,15 @@ declare class ToolResultPruner extends Service {
    * superseded classification.
    */
   private postflightEstimatorPass;
+  /**
+   * Advisory advisor pass at the turn boundary, strictly fire-and-forget.
+   * Produces todolist-bound tail-task summaries, incremental relevance
+   * scores, and a prefix-decay figure — all observational. Every short
+   * circuit below (mode off, re-entry, cooldown, no task semantics, no
+   * direct endpoint) returns without touching any state the pruning chain
+   * reads, so the default configuration adds exactly zero behavior.
+   */
+  private postflightAdvisorPass;
   /**
    * The per-session review queue, or `undefined` while review mode is off
    * (every review path must then behave exactly like before).