dsh-context-compression-improved 0.3.0 → 0.4.0-beta.1

package/packages/selector/lib/index.js

@@ -457,6 +457,232 @@ function restoreMethod(presets, snapshot) {
 //#region src/index.ts
 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"];
+function reviewPrunerOf(readService) {
+	const candidate = readService("toolResultPruner");
+	return typeof candidate?.listReviewProposals === "function" && typeof candidate?.decideReviewProposal === "function" ? candidate : void 0;
+}
+function sessionFor(readService, sessionId) {
+	const agents = readService("agents");
+	return typeof agents?.get === "function" ? agents.get(sessionId)?.session : void 0;
+}
+function reviewJson(res, status, body) {
+	const resTyped = res;
+	resTyped.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-cache"
+	});
+	resTyped.end(JSON.stringify(body));
+}
+function readRequestBody(req) {
+	return new Promise((resolve, reject) => {
+		const typed = req;
+		let data = "";
+		try {
+			typed.on?.("data", (chunk) => {
+				data += String(chunk ?? "");
+				if (data.length > 65536) {
+					data = "";
+					resolve("");
+				}
+			});
+			typed.on?.("end", () => resolve(data));
+			typed.on?.("error", reject);
+		} catch (error) {
+			reject(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+}
+/**
+* Serve the review pipeline's two HTTP routes (best effort, mirroring the
+* estimator-catalog registration):
+*
+* - `GET .../review-queue?sessionId=…` → the session's pending proposals with
+*   their benefit numbers. Sanitized by construction: the queue never holds
+*   message content, and the response carries ids/seqs/counts only (digests
+*   stay in the runtime — the client cannot need them).
+* - `POST .../review-decide` `{sessionId, proposalId, decision}` → one human
+*   decision. Invalid body → 400; unknown/not-pending proposal → 404; review
+*   mode off for the session → 503.
+*/
+function registerReviewQueueRoutes(ctx) {
+	const readService = (name) => {
+		try {
+			return ctx.get(name);
+		} catch {
+			return;
+		}
+	};
+	const log = (level, message, ...args) => {
+		console[level](message, ...args);
+	};
+	const registered = () => {
+		log("info", "context-compression review queue routes registered: %s / %s", REVIEW_QUEUE_ROUTES.join(", "), REVIEW_DECIDE_ROUTES.join(", "));
+	};
+	const getHandler = (req, res) => {
+		const pruner = reviewPrunerOf(readService);
+		if (pruner === void 0 || pruner.listAllReviewProposals === void 0) {
+			reviewJson(res, 503, {
+				ok: false,
+				error: "review pipeline unavailable"
+			});
+			return;
+		}
+		let sessionId = "";
+		try {
+			sessionId = new URL(String(req.url ?? ""), "http://localhost").searchParams.get("sessionId") ?? "";
+		} catch {
+			sessionId = "";
+		}
+		const sanitize = (sid, proposal) => ({
+			sessionId: sid,
+			id: proposal.id,
+			kind: proposal.kind,
+			items: proposal.items.map((item) => ({
+				seq: item.seq,
+				kind: item.kind,
+				component: item.component,
+				tokensBefore: item.tokensBefore,
+				tokensAfter: item.tokensAfter
+			})),
+			benefit: {
+				recoveredTokens: proposal.benefit.recoveredTokens,
+				penaltyTokens: proposal.benefit.penaltyTokens,
+				...proposal.benefit.paybackTurns === void 0 ? {} : { paybackTurns: proposal.benefit.paybackTurns },
+				...proposal.benefit.expectedSaving === void 0 ? {} : { expectedSaving: proposal.benefit.expectedSaving }
+			},
+			enqueuedTurn: proposal.enqueuedTurn,
+			lastTurnIndex: proposal.lastTurnIndex
+		});
+		if (sessionId === "") {
+			const pending = pruner.listAllReviewProposals().flatMap((entry) => entry.proposals.map((proposal) => sanitize(entry.sessionId, proposal)));
+			reviewJson(res, 200, {
+				ok: true,
+				total: pending.length,
+				pending
+			});
+			return;
+		}
+		const session = sessionFor(readService, sessionId);
+		if (session === void 0) {
+			reviewJson(res, 404, {
+				ok: false,
+				error: "unknown session"
+			});
+			return;
+		}
+		const pending = pruner.listReviewProposals(session).map((proposal) => sanitize(sessionId, proposal));
+		const summary = pruner.reviewSummary?.(session);
+		reviewJson(res, 200, {
+			ok: true,
+			sessionId,
+			total: pending.length,
+			pending,
+			...summary === void 0 ? {} : { summary }
+		});
+	};
+	const decideHandler = async (req, res) => {
+		const pruner = reviewPrunerOf(readService);
+		if (pruner === void 0) {
+			reviewJson(res, 503, {
+				ok: false,
+				error: "review pipeline unavailable"
+			});
+			return;
+		}
+		let body;
+		try {
+			body = JSON.parse(await readRequestBody(req));
+		} catch {
+			body = void 0;
+		}
+		if (typeof body !== "object" || body === null) {
+			reviewJson(res, 400, {
+				ok: false,
+				error: "invalid JSON body"
+			});
+			return;
+		}
+		const record = body;
+		if (typeof record.sessionId !== "string" || record.sessionId === "" || typeof record.proposalId !== "string" || record.proposalId === "") {
+			reviewJson(res, 400, {
+				ok: false,
+				error: "sessionId and proposalId are required"
+			});
+			return;
+		}
+		if (record.decision !== "approved" && record.decision !== "rejected" && record.decision !== "ignored") {
+			reviewJson(res, 400, {
+				ok: false,
+				error: "decision must be approved, rejected, or ignored"
+			});
+			return;
+		}
+		const session = sessionFor(readService, record.sessionId);
+		if (session === void 0) {
+			reviewJson(res, 404, {
+				ok: false,
+				error: "unknown session"
+			});
+			return;
+		}
+		const outcome = pruner.decideReviewProposal(session, record.proposalId, record.decision);
+		if (outcome === void 0) {
+			reviewJson(res, 503, {
+				ok: false,
+				error: "review mode is off for this session"
+			});
+			return;
+		}
+		if (!outcome.ok) {
+			reviewJson(res, 404, {
+				ok: false,
+				error: outcome.reason
+			});
+			return;
+		}
+		reviewJson(res, 200, {
+			ok: true,
+			sessionId: record.sessionId,
+			proposalId: record.proposalId,
+			decision: record.decision
+		});
+	};
+	const register = (webServer) => {
+		const disposers = [...[...REVIEW_QUEUE_ROUTES].map((path) => ({
+			path,
+			handler: getHandler
+		})), ...[...REVIEW_DECIDE_ROUTES].map((path) => ({
+			path,
+			handler: (req, res) => {
+				decideHandler(req, res);
+			}
+		}))].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.review routes");
+		registered();
+	};
+	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() — review routes not registered");
+			return;
+		}
+		register(webServer);
+	});
+	log("warn", "context-compression webServer not active yet — review routes pending: %s", REVIEW_QUEUE_ROUTES.join(", "));
+}
 /**
 * The one service the catalog route actually needs. `llm` and
 * `agentDefaultModel` are payload enrichment the handler resolves per request,
@@ -560,7 +786,8 @@ const SHARED_SETTINGS = Symbol.for("dsh-context-compression-improved/settings-re
 /** Loader validation for the standalone Bundle opt-in. */
 const Config = z.object({
 	presetOverlay: z.boolean().default(false),
-	estimatorCatalogRoute: z.boolean().default(false)
+	estimatorCatalogRoute: z.boolean().default(false),
+	reviewQueueRoute: z.boolean().default(false)
 });
 /** Register the persisted default read by the currently mounted root pruner. */
 function apply(ctx, config = {}) {
@@ -569,6 +796,7 @@ function apply(ctx, config = {}) {
 			acquireSettingsRegistration(settingsCtx);
 		});
 		if (config.estimatorCatalogRoute === true) registerEstimatorCatalogRoute(ctx);
+		if (config.reviewQueueRoute === true) registerReviewQueueRoutes(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,18 @@ interface PresetOptions {
   readonly estimator: {
     readonly mode: '' | 'host' | 'direct';
   };
+  /**
+   * Human-gated review pipeline (beta): edge/high-impact candidates queue for
+   * manual approval and execute in one merged batch at the next turn boundary
+   * instead of the automatic path (R4).
+   */
+  readonly reviewMode: boolean;
+  /** Turn-boundary patience: pending review proposals older than this many turns auto-expire (R4). */
+  readonly reviewTimeoutTurns: number;
+  /** Cache-hit discount rate α in the benefit model; expectedSaving = α·R·Ŝ − (1−α)·tail. */
+  readonly cacheHitDiscountAlpha: number;
+  /** Candidates whose tokenBefore reaches this threshold bypass payback triage and always enter review (R4). */
+  readonly reviewHighImpactTokens: number;
 }
 /** Common user-authored Custom stages shared by persisted policy versions. */
 interface CustomCompressionPolicyFields<HistoryPolicy> {
@@ -131,6 +143,11 @@ interface PresetOptionsSettings {
   readonly prefixStabilizer?: boolean;
   readonly readState?: boolean;
   readonly estimatorMode?: '' | 'host' | 'direct';
+  /** Review-mode overrides (beta); see PresetOptions.reviewMode. */
+  readonly reviewMode?: boolean;
+  readonly reviewTimeoutTurns?: number;
+  readonly cacheHitDiscountAlpha?: number;
+  readonly reviewHighImpactTokens?: number;
   /**
    * Estimator endpoint fields. Persisted-settings only: they never enter the
    * frozen CompressionPolicy, which is emitted verbatim by policy-resolved
@@ -310,7 +327,157 @@ interface EstimatorFailures {
   cooldownUntil: number;
 }
 //#endregion
+//#region src/runtime/tokenpilot/proposal.d.ts
+interface BenefitEstimate {
+  /** Net reclaimed tokens across the batch; may be ≤ 0 when a batch is not worth it. */
+  readonly recoveredTokens: number;
+  /** The one-time cache-refill penalty the merged mutation pays: (1−α)·tailTokens. */
+  readonly penaltyTokens: number;
+  /** Turns of discounted recovery needed to recoup the penalty; `undefined` when α·R ≤ 0. */
+  readonly paybackTurns?: number;
+  /** Discounted net benefit over the remaining session; omitted when Ŝ is unknown. */
+  readonly expectedSaving?: number;
+}
+/** Human-facing reduction kind carried by every review proposal. */
+type ProposalKind = 'estimator' | 'dedup' | 'read-state';
+/** One frozen item inside a review proposal: metadata and digest, never content. */
+interface ProposalItem {
+  readonly seq: number;
+  readonly component: string;
+  readonly kind: ProposalKind;
+  readonly tokensBefore: number;
+  readonly tokensAfter: number;
+  /** Content sha-256 frozen at enqueue time and re-checked at the apply point. */
+  readonly digest: string;
+}
+/** Proposal fields derivable at classification time; queue fields attach at enqueue. */
+interface ProposalSkeleton {
+  readonly id: string;
+  readonly kind: ProposalKind;
+  readonly items: readonly ProposalItem[];
+  readonly benefit: BenefitEstimate;
+}
+//#endregion
+//#region src/runtime/tokenpilot/review-queue.d.ts
+/** Human-side proposal status. */
+type ReviewProposalStatus = 'pending' | 'approved' | 'rejected' | 'ignored' | 'expired';
+/** Execution-side receipt built only from real mutation evidence (never estimated). */
+interface ReviewReceipt {
+  readonly status: 'applied' | 'deferred';
+  /** Reason code for deferred receipts, aligned with the upstream naming. */
+  readonly reasonCode?: string;
+  /** Predicted recovery from the benefit model at enqueue time. */
+  readonly estimatedTokens: number;
+  /** Measured recovery of the landed mutation; present only on applied. */
+  readonly appliedTokens?: number;
+  /** Canonical ISO timestamp of the execution evidence. */
+  readonly updatedAt: string;
+}
+/** One queued proposal: persisted metadata, never content. */
+interface ReviewProposalRecord {
+  readonly id: string;
+  readonly sessionId: string;
+  readonly kind: ProposalKind;
+  readonly items: readonly {
+    readonly seq: number;
+    readonly component: string;
+    readonly kind: ProposalKind;
+    readonly tokensBefore: number;
+    readonly tokensAfter: number;
+    readonly digest: string;
+  }[];
+  readonly benefit: {
+    readonly recoveredTokens: number;
+    readonly penaltyTokens: number;
+    readonly paybackTurns?: number;
+    readonly expectedSaving?: number;
+  };
+  status: ReviewProposalStatus;
+  readonly enqueuedTurn: number;
+  lastTurnIndex: number;
+}
+/** Whole-session record: one durable KV value per session. */
+interface ReviewSessionRecord {
+  readonly version: 1;
+  readonly proposals: readonly ReviewProposalRecord[];
+}
+/** A settled proposal: the live record plus its execution receipt. */
+interface ReviewReceiptRecord extends ReviewProposalRecord {
+  readonly receipt: ReviewReceipt;
+}
+/** Minimal KV face the queue persists through. */
+interface ReviewQueueStore {
+  load(sessionId: string): ReviewSessionRecord | undefined;
+  save(sessionId: string, record: ReviewSessionRecord): void;
+  /** Session ids with live records; optional (aggregate reads degrade to none). */
+  ids?(): readonly string[];
+}
+interface ReviewQueueOptions {
+  /** Pending proposals older than this many turns (since lastTurnIndex) expire. */
+  readonly timeoutTurns: number;
+}
+/** Decision outcomes for one decide call. */
+type DecideOutcome = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly reason: 'unknown-proposal' | 'not-pending';
+};
+declare class ReviewQueue {
+  private readonly store;
+  private readonly options;
+  constructor(store: ReviewQueueStore, options: ReviewQueueOptions);
+  /**
+   * Fail-open store access: a throwing seam must never break the compression
+   * pipeline. Reads degrade to "no stored record"; writes degrade to losing
+   * durability for that call (the store itself is expected to warn).
+   */
+  private safeLoad;
+  private safeSave;
+  private sessionRecord;
+  /**
+   * Queue one classified proposal. A repeated classification of the same
+   * content re-does nothing but refresh the patience clock, so re-enqueue
+   * cannot duplicate a live proposal.
+   * @returns `false` when an identical live proposal already exists.
+   */
+  enqueue(sessionId: string, skeleton: ProposalSkeleton, turnIndex: number): boolean;
+  /** Live pending proposals of one session, oldest enqueue first. */
+  listPending(sessionId: string): readonly ReviewProposalRecord[];
+  /** Approved proposals waiting for the next turn-boundary batch. */
+  listApproved(sessionId: string): readonly ReviewProposalRecord[];
+  /**
+   * Transition one pending proposal. Idempotent: deciding an unknown id or a
+   * non-pending proposal changes nothing and reports the miss.
+   */
+  decide(sessionId: string, id: string, decision: 'approved' | 'rejected' | 'ignored'): DecideOutcome;
+  /**
+   * Expire every pending proposal whose patience has run out at this turn
+   * boundary. Expired proposals are removed from the store (the summary view
+   * aggregates them from the audit log instead).
+   * @returns the expired proposals, for the caller's audit emission.
+   */
+  expireTurn(sessionId: string, turnIndex: number): readonly ReviewProposalRecord[];
+  /**
+   * Settle an approved proposal with its execution receipt and retire it from
+   * the live store. The caller is responsible for auditing the receipt; the
+   * queue only records which proposal left and why.
+   */
+  recordReceipt(sessionId: string, id: string, receipt: ReviewReceipt): ReviewReceiptRecord | undefined;
+}
+//#endregion
 //#region src/pruner/state.d.ts
+/** Four-state per-session outcome counters behind the floating-window summary row. */
+interface ReviewSessionSummary {
+  /** Rewrites that landed through the automatic path while review mode served this session. */
+  autoApplied: number;
+  /** Approved proposals whose merged batch executed with an applied receipt. */
+  reviewApplied: number;
+  /** Pending proposals that expired unhandled at a turn boundary. */
+  expired: number;
+  /** Approved proposals voided at the apply point (digest mismatch et al). */
+  voided: number;
+}
 /** Mutable per-session state bag used inside {@link ToolResultPruner}. */
 interface PrunerState {
   /** Resolved immutable deployment configuration. */
@@ -337,6 +504,20 @@ interface PrunerState {
   readonly tailTrimBoundaryAttempts: WeakMap<Session, object>;
   /** Last effective policy audit key emitted for each Session. */
   readonly policyResolutionAudits: WeakMap<Session, string>;
+  /**
+   * TokenPilot-inspired R4: shared review-queue store. Starts as the in-memory
+   * fail-open fallback; swapped to the storageDomain-backed adapter when (and
+   * if) that seam opens successfully.
+   */
+  reviewStore: ReviewQueueStore;
+  /** Per-session review queue carrying the frozen timeout policy. */
+  readonly reviewQueues: WeakMap<Session, ReviewQueue>;
+  /** Last observed turn index per Session: the monotonic clock for review expiries. */
+  readonly reviewClocks: WeakMap<Session, number>;
+  /** Estimator-reported remaining turns Ŝ per Session; advisory only. */
+  readonly estimatorRemainingTurns: WeakMap<Session, number>;
+  /** Four-state outcome counters per Session (floating-window summary row). */
+  readonly reviewSummaries: WeakMap<Session, ReviewSessionSummary>;
 }
 //#endregion
 //#region src/runtime/custom-policy.d.ts
@@ -621,6 +802,79 @@ declare class ToolResultPruner extends Service {
    * superseded classification.
    */
   private postflightEstimatorPass;
+  /**
+   * The per-session review queue, or `undefined` while review mode is off
+   * (every review path must then behave exactly like before).
+   */
+  private reviewQueueFor;
+  /**
+   * Monotonic per-session turn clock for review patience and expiry. Bumped by
+   * the agent loop payloads (`pre-step` / `turn-stopping`); passes without a
+   * turn coordinate reuse the last observed value.
+   */
+  private reviewClock;
+  private auditReviewOutcome;
+  /**
+   * Review-mode triage hook: classify one pass's planned replacements and
+   * withhold the review bucket from landing, enqueuing it for human approval
+   * instead. With review mode off (or nothing planned) this is the identity.
+   *
+   * The digest freezes each candidate's ORIGINAL surface content, so the apply
+   * point can prove "what is removed now is what was approved then".
+   */
+  private triageForReview;
+  /**
+   * Execute every approved proposal of one session as ONE merged replacement
+   * batch at the current turn boundary, following the upstream applied-receipt
+   * discipline: applied receipts are built only from real mutation evidence —
+   * estimates never cross into applied savings.
+   *
+   * Per proposal: every item's frozen digest is re-checked against the current
+   * surface content; any mismatch voids the whole proposal (deferred with a
+   * reason code) instead of deleting something the user never approved.
+   * Fail-open: any unexpected error only logs and leaves the queue intact.
+   */
+  applyApprovedProposals(session: Session): void;
+  /**
+   * Current surface content at one seq: the newest covering replacement's
+   * blocks when the seq was rewritten, otherwise the original event's blocks.
+   */
+  private surfaceContentAt;
+  /**
+   * The execution-point digest check: `undefined` when every item's frozen
+   * digest still matches the current surface content, otherwise the aligned
+   * reason code explaining the void.
+   */
+  private reviewProposalVoided;
+  private reviewSummaryFor;
+  /** Live pending review proposals of one session; empty when review mode is off. */
+  listReviewProposals(session: Session): readonly ReviewProposalRecord[];
+  /**
+   * Every session's live pending proposals, for the floating window's
+   * aggregate badge (the client carries no session id of its own).
+   */
+  listAllReviewProposals(): readonly {
+    readonly sessionId: string;
+    readonly proposals: readonly ReviewProposalRecord[];
+  }[];
+  /** Four-state outcome counters of one session (floating-window summary row). */
+  reviewSummary(session: Session): ReviewSessionSummary;
+  /**
+   * Record one human decision. Returns the outcome, or `undefined` when
+   * review mode is off for this session (the route maps that to 503).
+   */
+  decideReviewProposal(session: Session, proposalId: string, decision: 'approved' | 'rejected' | 'ignored'): {
+    ok: true;
+  } | {
+    ok: false;
+    reason: 'unknown-proposal' | 'not-pending';
+  } | undefined;
+  /**
+   * Expire stale pending proposals at one turn boundary and audit each.
+   * Public because tests drive it directly; the turn-stopping handler calls
+   * it with the loop's own turn index.
+   */
+  expireReviewProposals(session: Session, turnIndex?: number): readonly ReviewProposalRecord[];
   private activePolicy;
   private contextWindowForRequest;
   private runRequestBoundary;