pi-ui-extend 1.0.41 → 1.0.45

package/external/pi-tools-suite/src/dcp/protected-continuity.ts

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+
+import { planProspectiveTestOutputDelivery, parseTestBuildOutput } from "../context-gateway/test-output-parser.js";
+import { classifyShellCommand, shellCommandText } from "../shell-command-policy.js";
+import type { DcpConfig } from "./config.js";
+import {
+	isToolRecordPruningProtected,
+	isToolRecordProtectedByFilePattern,
+} from "./pruner-tools.js";
+import type { ToolRecord } from "./state.js";
+
+export type ToolContinuityMode = "none" | "digest" | "verbatim";
+
+export interface ToolContinuityDecision {
+	mode: ToolContinuityMode;
+	text?: string;
+	reason: string;
+}
+
+const SHELL_TOOLS = new Set(["bash", "shell", "powershell", "exec", "execute"]);
+const MAX_COMMAND_CHARS = 2_048;
+const MAX_ERROR_EXCERPT_CHARS = 2_048;
+const TEST_DIGEST_MAX_BYTES = 8_192;
+
+function normalizeToolName(name: string): string {
+	return name.trim().toLowerCase().replace(/[\s-]+/g, "_");
+}
+
+function stableDigest(text: string): string {
+	return createHash("sha256").update(text).digest("hex");
+}
+
+function renderedCommand(record: ToolRecord): string {
+	const command = shellCommandText(record.inputArgs);
+	if (!command) return "unavailable";
+	if (command.length <= MAX_COMMAND_CHARS) return command;
+	return `[command omitted: ${command.length} chars, sha256:${stableDigest(command)}]`;
+}
+
+function outputIdentity(output: string): string {
+	return `${Buffer.byteLength(output, "utf8")} bytes, sha256:${stableDigest(output)}`;
+}
+
+function boundedErrorExcerpt(output: string): string | undefined {
+	const lines = output.replace(/\r\n/g, "\n").split("\n").filter((line) => line.trim().length > 0);
+	const selected: string[] = [];
+	const seen = new Set<string>();
+	const add = (line: string) => {
+		if (seen.has(line)) return;
+		seen.add(line);
+		selected.push(line);
+	};
+	for (const line of lines) {
+		if (/\b(error|failed?|failure|exception|denied|not found|cannot|unable)\b/i.test(line)) add(line);
+	}
+	for (const line of lines.slice(-6)) add(line);
+	if (selected.length === 0) return undefined;
+	let text = selected.join("\n");
+	if (text.length > MAX_ERROR_EXCERPT_CHARS) text = text.slice(0, MAX_ERROR_EXCERPT_CHARS) + "\n[excerpt truncated]";
+	return text;
+}
+
+function shellDigest(record: ToolRecord, kind: "inspection" | "test-build", body?: string): string {
+	const output = record.outputText ?? "";
+	const lines = [
+		`### Tool continuity: ${record.toolName}`,
+		`Command: ${renderedCommand(record)}`,
+		`Classification: ${kind}`,
+		`Outcome: ${record.isError ? "error" : "success"}`,
+		`Raw output identity: ${outputIdentity(output)}`,
+	];
+	if (body) lines.push(body);
+	else if (record.isError) {
+		const excerpt = boundedErrorExcerpt(output);
+		if (excerpt) lines.push("Actionable error excerpt:", excerpt);
+	}
+	lines.push("Exact raw output is not retained in protected continuity; rerun the command only if exact text is needed.");
+	return lines.join("\n");
+}
+
+function verbatimToolText(record: ToolRecord): string | undefined {
+	const output = (record.outputText ?? "").trim();
+	return output ? `### Tool: ${record.toolName}\n${output}` : undefined;
+}
+
+function preferSmallerDigest(
+	record: ToolRecord,
+	reason: string,
+	digest: string,
+): ToolContinuityDecision {
+	const verbatim = verbatimToolText(record);
+	if (verbatim && digest.length >= verbatim.length) {
+		return { mode: "verbatim", reason: `${reason}-not-smaller`, text: verbatim };
+	}
+	return { mode: "digest", reason, text: digest };
+}
+
+function gatewayCompactRepresentation(record: ToolRecord): string | undefined {
+	const details = record.outputDetails;
+	if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
+	const marker = (details as Record<string, unknown>).contextGateway;
+	if (!marker || typeof marker !== "object" || Array.isArray(marker)) return undefined;
+	const value = marker as Record<string, unknown>;
+	if (value.version !== 1 || value.representation !== "test-build-compact") return undefined;
+	return record.outputText?.trim() || undefined;
+}
+
+/**
+ * Decide how much of a pruning-protected tool result must survive a compression
+ * roll-up. Pruning safety and continuity retention are deliberately separate:
+ * shell results remain protected from generic pruning, while proven read-only
+ * inspection and confidently parsed test/build output can keep only a bounded
+ * continuation digest.
+ */
+export function toolRecordContinuity(record: ToolRecord, config: DcpConfig): ToolContinuityDecision {
+	if (!isToolRecordPruningProtected(record, config)) return { mode: "none", reason: "not-pruning-protected" };
+	const normalized = normalizeToolName(record.toolName);
+	const output = record.outputText ?? "";
+	if (!SHELL_TOOLS.has(normalized)) {
+		return {
+			mode: "verbatim",
+			reason: "non-shell-protected-tool",
+			text: verbatimToolText(record),
+		};
+	}
+	if (isToolRecordProtectedByFilePattern(record, config)) {
+		return {
+			mode: "verbatim",
+			reason: "protected-file-pattern",
+			text: verbatimToolText(record),
+		};
+	}
+	const gatewayCompact = gatewayCompactRepresentation(record);
+	if (gatewayCompact) {
+		return {
+			mode: "verbatim",
+			reason: "gateway-compacted",
+			text: `### Tool: ${record.toolName}\n${gatewayCompact}`,
+		};
+	}
+
+	const classification = classifyShellCommand(record.inputArgs);
+	if (classification.kind === "inspection") {
+		return preferSmallerDigest(record, "read-only-inspection", shellDigest(record, "inspection"));
+	}
+	if (classification.kind === "test-build" && classification.scope === "simple") {
+		const parsed = parseTestBuildOutput({
+			text: output,
+			hostOutcome: record.isError ? "error" : "success",
+		});
+		const compact = planProspectiveTestOutputDelivery(parsed, TEST_DIGEST_MAX_BYTES, { commandScope: "simple" });
+		if (compact.decision === "compact-candidate" && compact.text) {
+			return preferSmallerDigest(
+				record,
+				"recognised-test-build",
+				shellDigest(record, "test-build", compact.text),
+			);
+		}
+		return {
+			mode: "verbatim",
+			reason: `test-build-${compact.reason}`,
+			text: verbatimToolText(record),
+		};
+	}
+
+	return {
+		mode: "verbatim",
+		reason: classification.kind === "mutation"
+			? "shell-mutation"
+			: classification.scope === "compound"
+				? "shell-compound"
+				: "shell-unknown",
+		text: verbatimToolText(record),
+	};
+}

package/external/pi-tools-suite/src/dcp/pruner-candidates.ts

@@ -102,8 +102,17 @@ export interface CompressionCandidateSelectionOptions {
   requiredSavingsTokens?: number;
   /** Conservative estimator margin added to the required source size. */
   estimatorMarginTokens?: number;
+  /**
+   * Whether an automatic candidate may fold already-compressed block
+   * placeholders into a new block. Capacity-recovery plans disable this so an
+   * economical existing summary is not expanded again while rescuing raw tail
+   * growth. Manual/non-pressure consolidation keeps the historical default.
+   */
+  allowCompressionBlocks?: boolean;
 }
 
+const MIN_AUTOMATIC_BLOCK_CONSOLIDATION = 8;
+
 function selectOldestSafePrefix(
   boundaries: CandidateBoundary[],
   state: DcpState,
@@ -176,7 +185,9 @@ export function detectCompressionCandidate(
   if (!settings.enabled) return null;
   if (contextPercent < settings.minContextPercent) return null;
 
-  const boundaries = buildCandidateBoundaries(messages, _state, { allowBlocks: true });
+  const boundaries = buildCandidateBoundaries(messages, _state, {
+    allowBlocks: options?.allowCompressionBlocks ?? true,
+  });
 
   if (boundaries.length < settings.minMessages) return null;
 
@@ -224,6 +235,83 @@ export function detectCompressionCandidate(
   };
 }
 
+/**
+ * Periodically fold a contiguous prefix of already-compressed summaries into
+ * one summary. Raw-tail recovery deliberately excludes bN blocks so it cannot
+ * recreate the incident's b1 -> b2 -> ... ladder; without a separate bounded
+ * consolidation step, however, a marathon turn can accumulate dozens of small
+ * active summaries until summary overhead itself fills the provider window.
+ *
+ * This detector is intentionally block-only: every selected boundary must be a
+ * synthetic block message and physically adjacent in the provider projection.
+ * Requiring a batch of blocks amortizes the intentional prefix rewrite and
+ * prevents one-old-summary-plus-a-tiny-tail recompression on every turn.
+ */
+export function detectCompressionBlockConsolidationCandidate(
+  messages: any[],
+  state: DcpState,
+  config: DcpConfig,
+  options?: CompressionCandidateSelectionOptions,
+): CompressionCandidate | null {
+  const settings = config.compress.autoCandidates;
+  const boundaries = buildCandidateBoundaries(messages, state, { allowBlocks: true });
+  const minimumBlocks = MIN_AUTOMATIC_BLOCK_CONSOLIDATION;
+  const requiredSavings = Math.max(0, Math.floor(options?.requiredSavingsTokens ?? 0));
+  const estimatorMargin = Math.max(0, Math.floor(options?.estimatorMarginTokens ?? 0));
+  const targetSourceTokens = Math.max(settings.minTokens, requiredSavings + estimatorMargin);
+
+  let run: CandidateBoundary[] = [];
+  const chooseRun = (candidateRun: CandidateBoundary[]): CandidateBoundary[] | null => {
+    if (candidateRun.length < minimumBlocks) return null;
+    let selectedTokens = 0;
+    let selectedEnd = minimumBlocks - 1;
+    for (let index = 0; index < candidateRun.length; index++) {
+      selectedTokens += candidateRun[index]!.tokenEstimate;
+      if (index + 1 >= minimumBlocks && selectedTokens >= targetSourceTokens) {
+        selectedEnd = index;
+        break;
+      }
+      selectedEnd = index;
+    }
+    return candidateRun.slice(0, Math.max(minimumBlocks, selectedEnd + 1));
+  };
+
+  for (const boundary of boundaries) {
+    const previous = run.at(-1);
+    const continuesBlockRun = boundary.blockId !== undefined &&
+      (!previous || boundary.messageIndex === previous.messageIndex + 1);
+    if (continuesBlockRun) {
+      run.push(boundary);
+      continue;
+    }
+    const selected = chooseRun(run);
+    if (selected) {
+      const estimatedTokens = selected.reduce((sum, item) => sum + item.tokenEstimate, 0);
+      return {
+        startId: selected[0]!.id,
+        endId: selected[selected.length - 1]!.id,
+        messageCount: selected.length,
+        estimatedTokens,
+        includedBlockIds: selected.map((item) => item.blockId!),
+        reason: `automatic block-only consolidation of ${selected.length} adjacent summaries`,
+      };
+    }
+    run = boundary.blockId !== undefined ? [boundary] : [];
+  }
+
+  const selected = chooseRun(run);
+  if (!selected) return null;
+  const estimatedTokens = selected.reduce((sum, item) => sum + item.tokenEstimate, 0);
+  return {
+    startId: selected[0]!.id,
+    endId: selected[selected.length - 1]!.id,
+    messageCount: selected.length,
+    estimatedTokens,
+    includedBlockIds: selected.map((item) => item.blockId!),
+    reason: `automatic block-only consolidation of ${selected.length} adjacent summaries`,
+  };
+}
+
 /**
  * Emergency-only range candidate for marathon turns.
  *
@@ -257,7 +345,9 @@ export function detectEmergencyCompressionCandidate(
   if (!emergencySettings.enabled) return null;
   if (contextPercent <= maxContextPercent) return null;
 
-  const boundaries = buildCandidateBoundaries(messages, state, { allowBlocks: true });
+  const boundaries = buildCandidateBoundaries(messages, state, {
+    allowBlocks: options?.allowCompressionBlocks ?? true,
+  });
   if (boundaries.length < settings.minMessages) return null;
 
   let latestUserIndex = -1;
@@ -453,5 +543,5 @@ export function formatMessageCompressionCandidateHint(candidates: MessageCompres
   const entries = candidates
     .map((candidate) => `${candidate.messageId} (${candidate.priority}, ${candidate.role}, ~${candidate.estimatedTokens} tokens)`)
     .join(", ");
-  return `\n\nSuggested individual message compression candidates: ${entries}. To compress individual messages, call \`compress\` with a \`messages\` array: { messageId, topic, summary }. Use this for large stale messages when a full range would be too broad.`;
+  return `\n\nSuggested individual message compression candidates: ${entries}. To compress individual messages, call \`compress\` with a \`messages\` array: { messageId, topic }. Omit \`summary\` to use the configured DCP summarizer; provide it only when parent-authored wording is required. Use message mode when a full range would be too broad.`;
 }

package/external/pi-tools-suite/src/dcp/pruner-message-ids.ts

@@ -113,9 +113,9 @@ function persistentMessageId(stableKey: string, state: DcpState): string {
 }
 
 function carrierSelfLabel(role: string): string {
-  if (role === "toolResult") return "this tool result";
-  if (role === "bashExecution") return "this bash result";
-  return "this user message";
+  if (role === "toolResult") return "t";
+  if (role === "bashExecution") return "x";
+  return "u";
 }
 
 function buildCarrierControlText(
@@ -125,15 +125,11 @@ function buildCarrierControlText(
   blockId: number | undefined,
 ): string {
   const assignments = [
-    ...precedingAssistantIds.map((id) => `${id}=preceding assistant message`),
+    ...precedingAssistantIds.map((id) => `${id}=a`),
     `${ownId}=${carrierSelfLabel(ownRole)}`,
   ];
-  return [
-    "<dcp-message-ids>",
-    `Stable DCP IDs (use with compress; do not quote/output): ${assignments.join("; ")}`,
-    ...(blockId === undefined ? [] : [`Active compressed block alias: b${blockId}`]),
-    "</dcp-message-ids>",
-  ].join("\n");
+  if (blockId !== undefined) assignments.push(`b${blockId}=b`);
+  return `<dcp-message-ids>${assignments.join(";")}</dcp-message-ids>`;
 }
 
 function appendControlToCarrier(message: any, controlText: string): void {

package/external/pi-tools-suite/src/dcp/pruner-nudge.ts

@@ -32,31 +32,51 @@ function nudgeTypeLabel(type: DcpNudgeType): string {
 
 function isRealAnchorCandidate(msg: any): boolean {
   const role = msg?.role ?? "";
-  if (role !== "user" && role !== "assistant") return false;
+  if (role !== "user" && role !== "toolResult") return false;
   return msg?._dcpOrigin !== "block" && msg?._dcpOrigin !== "dcp-control";
 }
 
-function findAnchorMessage(messages: any[]): { msg: any; index: number; stableId: string; timestamp: number; role: string } | null {
+function findAnchorMessage(messages: any[], freshToolResultIds?: ReadonlySet<string>): { msg: any; index: number; stableId: string; timestamp: number; role: string } | null {
   const stableKeys = stableMessageKeys(messages);
-  // A reminder may only be introduced on a fresh user tail. If assistant/tool
-  // traffic already follows that user message then it has already belonged to
-  // an earlier provider prefix; editing it now would invalidate that prefix.
+  // Only append to a fresh tail; never edit an earlier user/assistant prefix.
+  // Tool-result freshness requires a positive local lifecycle grant, not the
+  // absence of successful provider evidence (which is unknown after restart).
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];
     if (msg?._dcpOrigin === "dcp-control") continue;
-    if (msg?.role !== "user" || !isRealAnchorCandidate(msg) || !Number.isFinite(msg.timestamp)) return null;
+    if (!isRealAnchorCandidate(msg) || !Number.isFinite(msg.timestamp)) return null;
+    if (msg.role === "toolResult") {
+      if (!freshToolResultIds?.has(msg.toolCallId)) return null;
+      // A duplicate/reused call ID is not an unambiguous fresh carrier.
+      if (messages.filter((item) => item?.role === "toolResult" && item.toolCallId === msg.toolCallId).length !== 1) return null;
+    }
     return { msg, index: i, stableId: stableKeys[i]!, timestamp: msg.timestamp, role: msg.role };
   }
 
   return null;
 }
 
-export function hasCacheSafeNudgeCarrier(messages: any[]): boolean {
-  return findAnchorMessage(messages) !== null;
+export function hasCacheSafeNudgeCarrier(
+  messages: any[],
+  freshToolResultIds?: ReadonlySet<string>,
+  anchors: readonly DcpNudgeAnchor[] = [],
+): boolean {
+  if (findAnchorMessage(messages, freshToolResultIds) !== null) return true;
+  // A previously published reminder remains deliverable without editing its
+  // carrier. Losing the grant to create a NEW reminder on a provider attempt
+  // must not make retries bypass the completed-opportunity patience policy.
+  const stableKeys = stableMessageKeys(messages);
+  return anchors.some((anchor) => typeof anchor.renderedReminder === "string" &&
+    anchor.renderedReminder.length > 0 &&
+    messages.some((message, index) => anchorMatchesMessage(anchor, message, stableKeys[index]!)));
 }
 
 function anchorMatchesMessage(anchor: DcpNudgeAnchor, msg: any, stableKey: string): boolean {
-  if (anchor.anchorStableId && stableKey === anchor.anchorStableId) return true;
+  if (!isRealAnchorCandidate(msg) || msg.role !== anchor.anchorRole) return false;
+  if (anchor.anchorStableId) return stableKey === anchor.anchorStableId;
+  // Legacy user anchors may be timestamp-only. Tool anchors must never rebind
+  // to another parallel result that happens to share their timestamp.
+  if (msg.role === "toolResult") return false;
   return msg?.timestamp === anchor.anchorTimestamp;
 }
 
@@ -78,24 +98,8 @@ function appendTextToMessage(msg: any, text: string): void {
     return;
   }
 
-  const textBlock = { type: "text", text: suffix };
-  if (msg.role !== "assistant") {
-    msg.content = [...msg.content, textBlock];
-    return;
-  }
-
-  // Keep provider ordering constraints: assistant text must appear before
-  // toolCall blocks for models that enforce text/thinking/tool_use ordering.
-  const firstToolCallIdx = msg.content.findIndex((block: any) => block?.type === "toolCall");
-  if (firstToolCallIdx === -1) {
-    msg.content = [...msg.content, textBlock];
-  } else {
-    msg.content = [
-      ...msg.content.slice(0, firstToolCallIdx),
-      textBlock,
-      ...msg.content.slice(firstToolCallIdx),
-    ];
-  }
+  // Only user/tool-result carriers reach here. Assistant items are immutable.
+  msg.content = [...msg.content, { type: "text", text: suffix }];
 }
 
 function insertBeforeReminderClose(reminder: string, detail: string): string {
@@ -174,7 +178,7 @@ export function upsertNudgeAnchor(
   messages: any[],
   state: DcpState,
   type: DcpNudgeType,
-  options: { contextPercent?: number; renderedReminder?: string } = {},
+  options: { contextPercent?: number; renderedReminder?: string; freshToolResultIds?: ReadonlySet<string> } = {},
 ): { anchor: DcpNudgeAnchor | null; created: boolean; updated: boolean } {
   const stableKeys = stableMessageKeys(messages);
   let existing: DcpNudgeAnchor | null = null;
@@ -198,11 +202,10 @@ export function upsertNudgeAnchor(
     state.lastNudge = undefined;
   }
 
-  const target = findAnchorMessage(messages);
+  const target = findAnchorMessage(messages, options.freshToolResultIds);
   if (!target) {
-    // Mid-turn reminder creation is deliberately deferred rather than
-    // synthesizing an ephemeral tail message that would disappear on the next
-    // provider continuation and break prefix equality.
+    // No positively fresh carrier: do not synthesize a disappearing tail or
+    // reinterpret unknown historical exposure as permission to edit history.
     return { anchor: null, created: false, updated: false };
   }
 
@@ -263,7 +266,7 @@ export function applyAnchoredNudges(
   const reminder = selected.anchor.renderedReminder ?? render(selected.anchor);
   if (materializedReminder) selected.anchor.renderedReminder = reminder;
   const anchorMessage = messages[selected.index];
-  if (anchorMessage?.role !== "user") {
+  if (!isRealAnchorCandidate(anchorMessage)) {
     state.nudgeAnchors = [];
     state.lastNudge = undefined;
     return { rendered: false, stateChanged: true };

package/external/pi-tools-suite/src/dcp/pruner-tools.ts

@@ -83,7 +83,7 @@ function patternMatchesValue(pattern: string, value: string): boolean {
   return globToRegExp(normalizedPattern).test(normalizedValue);
 }
 
-function isProtectedByFilePattern(record: ToolRecord | undefined, config: DcpConfig): boolean {
+export function isToolRecordProtectedByFilePattern(record: ToolRecord | undefined, config: DcpConfig): boolean {
   if (!record || config.protectedFilePatterns.length === 0) return false;
   const values = collectStringValues(record.inputArgs);
   return values.some((value) =>
@@ -91,16 +91,19 @@ function isProtectedByFilePattern(record: ToolRecord | undefined, config: DcpCon
   );
 }
 
-export function isToolRecordProtected(
+export function isToolRecordPruningProtected(
   record: ToolRecord,
   config: DcpConfig,
   extraProtectedTools: string[] = [],
 ): boolean {
   const protectedTools = buildProtectedTools(config, extraProtectedTools);
   if (protectedTools.has(normalizeToolName(record.toolName))) return true;
-  return isProtectedByFilePattern(record, config);
+  return isToolRecordProtectedByFilePattern(record, config);
 }
 
+/** Backward-compatible name for callers that mean pruning protection. */
+export const isToolRecordProtected = isToolRecordPruningProtected;
+
 export function markToolPruned(
   state: DcpState,
   toolCallId: string,

package/external/pi-tools-suite/src/dcp/pruner.ts

@@ -30,6 +30,7 @@ export {
   markToolPruned,
 } from "./pruner-tools.js";
 export {
+  detectCompressionBlockConsolidationCandidate,
   detectCompressionCandidate,
   detectEmergencyCompressionCandidate,
   detectMessageCompressionCandidates,

package/external/pi-tools-suite/src/dcp/routine-pressure.ts

@@ -0,0 +1,86 @@
+import { canonicalMessageHash } from "./conversation-index.js";
+import type { CompressionBlock } from "./state.js";
+
+interface ProjectionFrame {
+  owner: string;
+  avoidedTokens: number;
+  blocks: string;
+}
+
+export interface RoutinePressureEstimate {
+  projectedTokens: number;
+  adjustmentTokens: number;
+}
+
+function usableUsage(message: any): boolean {
+  if (message?.role !== "assistant" || ["error", "aborted"].includes(message.stopReason)) return false;
+  const usage = message.usage;
+  if (!usage) return false;
+  const tokens = usage.totalTokens || [usage.input, usage.output, usage.cacheRead, usage.cacheWrite]
+    .reduce((sum, value) => sum + (typeof value === "number" && Number.isFinite(value) ? value : 0), 0);
+  return typeof tokens === "number" && Number.isFinite(tokens) && tokens > 0;
+}
+
+function blockVersion(blocks: readonly CompressionBlock[]): string {
+  return blocks.filter((block) => block.active).map((block) => block.id).join(",");
+}
+
+/**
+ * Runtime-only calibration for ROUTINE nudges, never a provider-send budget.
+ * The SDK's last assistant usage still includes history removed by a later DCP
+ * rewrite. Subtract only the additional locally measured raw/projected delta
+ * since that assistant's correlated request. This keeps provider overhead and
+ * tail growth, and avoids counting older compression twice. Uncorrelated usage
+ * and lifecycle changes fall back to the existing conservative estimate.
+ */
+export class RoutinePressureTracker {
+  private prepared: ProjectionFrame | undefined;
+  private pending: ProjectionFrame | undefined;
+  private sample: (ProjectionFrame & { hash: string; timestamp: unknown }) | undefined;
+
+  reset(): void {
+    this.prepared = undefined;
+    this.pending = undefined;
+    this.sample = undefined;
+  }
+
+  prepare(owner: string, rawTokens: number, projectedTokens: number, blocks: readonly CompressionBlock[]): void {
+    this.prepared = { owner, avoidedTokens: rawTokens - projectedTokens, blocks: blockVersion(blocks) };
+  }
+
+  beforeRequest(): void {
+    this.pending = this.prepared;
+  }
+
+  complete(message: any, correlated: boolean): void {
+    const pending = this.pending;
+    this.pending = undefined;
+    if (!usableUsage(message)) return;
+    this.sample = correlated && pending && typeof message.timestamp === "number" && Number.isFinite(message.timestamp)
+      ? { ...pending, hash: canonicalMessageHash(message), timestamp: message.timestamp }
+      : undefined;
+  }
+
+  estimate(owner: string, nativeTokens: number | null | undefined, raw: readonly any[],
+    rawTokens: number, projectedTokens: number, blocks: readonly CompressionBlock[]): RoutinePressureEstimate {
+    const fallback = Math.max(projectedTokens, nativeTokens ?? 0);
+    const unchanged = { projectedTokens: fallback, adjustmentTokens: 0 };
+    const sample = this.sample;
+    if (!sample || sample.owner !== owner || nativeTokens === null || nativeTokens === undefined) return unchanged;
+    const version = blockVersion(blocks);
+    if (!version || version === sample.blocks) return unchanged;
+    // Confirm the SDK is still based on this exact successful assistant, not
+    // an unrelated/new response, failed stream or a sample from another owner.
+    let latest: any;
+    for (let index = raw.length - 1; index >= 0; index--) {
+      if (usableUsage(raw[index])) {
+        latest = raw[index];
+        break;
+      }
+    }
+    if (!latest || latest.timestamp !== sample.timestamp || canonicalMessageHash(latest) !== sample.hash) return unchanged;
+    const newSavings = Math.max(0, rawTokens - projectedTokens - sample.avoidedTokens);
+    const adjusted = Math.max(projectedTokens, nativeTokens - newSavings);
+    return { projectedTokens: adjusted, adjustmentTokens: fallback - adjusted };
+  }
+}

package/external/pi-tools-suite/src/dcp/state.ts

@@ -153,6 +153,15 @@ export interface CompressionBlock {
   active: boolean
   /** Token estimate for the summary text itself */
   summaryTokenEstimate: number
+  /** One record per successful transaction (on its first block), never on retries.
+   * Optional for older journal blocks; absence means unmeasured, not zero gain. */
+  commitMetrics?: {
+    operationId: string
+    kind: "manual" | "auto" | "consolidation"
+    beforeTokens: number
+    afterTokens: number
+    netGainTokens: number
+  }
   /** Wall-clock time the block was created (Date.now()) */
   createdAt: number
   /** Older compression blocks subsumed by this block during roll-up. */

package/external/pi-tools-suite/src/dcp/statistics.d.ts

@@ -0,0 +1,8 @@
+export interface DcpStatisticsInput {
+  branch?: readonly any[];
+  model?: any;
+  usage?: any;
+  historyStatus?: "full" | "unavailable";
+}
+export function collectDcpStatistics(input: DcpStatisticsInput): any;
+export function formatDcpStatistics(input: DcpStatisticsInput): string;