pi-midcompact 0.3.0 → 0.5.0

package/src/state.ts

@@ -1,4 +1,16 @@
-import type { CompressionState, DraftPlan, SessionEntryLike, TransactionState } from "./types.js";
+// Persistence boundary. Owns restoration of CompressionState, TransactionState,
+// and DraftPlan from the session branch. Provides backward-compatible defaults
+// so old v1 state (without startMode) restores without migration. The runtime
+// planning lock is not persisted here; it lives only in memory.
+
+import type {
+  CompressionState,
+  DraftPlan,
+  DraftRange,
+  SessionEntryLike,
+  StartMode,
+  TransactionState,
+} from "./types.js";
 
 export const STATE_ENTRY = "midcompact-state";
 export const TXN_ENTRY = "midcompact-transaction";
@@ -12,6 +24,11 @@ export function emptyCompressionState(): CompressionState {
   return { version: 1, createdAt: new Date().toISOString(), blocks: [] };
 }
 
+/** Default routing for transactions persisted before startMode existed. */
+export function defaultStartMode(mode: StartMode | undefined): StartMode {
+  return mode ?? "agent";
+}
+
 export function restoreCompressionState(entries: readonly unknown[]): CompressionState | undefined {
   let latest: CompressionState | undefined;
   for (const raw of entries) {
@@ -22,7 +39,10 @@ export function restoreCompressionState(entries: readonly unknown[]): Compressio
   return latest;
 }
 
-export function restoreTransaction(entries: readonly unknown[]): { transaction?: TransactionState; draft?: DraftPlan } {
+export function restoreTransaction(entries: readonly unknown[]): {
+  transaction?: TransactionState;
+  draft?: DraftPlan;
+} {
   let transaction: TransactionState | undefined;
   let draft: DraftPlan | undefined;
   for (const raw of entries) {
@@ -62,3 +82,20 @@ function isDraft(value: unknown): value is DraftPlan {
   const plan = value as Record<string, unknown>;
   return plan.version === 1 && typeof plan.transactionId === "string" && typeof plan.revision === "number" && Array.isArray(plan.ranges);
 }
+
+/**
+ * An old DraftRange may lack the factual char/image fields. Coerce to the
+ * current shape so callers always see the new fields; missing values default to
+ * 0 and are recomputed by the next mutation.
+ */
+export function coerceDraftRange(range: DraftRange): DraftRange {
+  return {
+    ...range,
+    originalContentChars: typeof range.originalContentChars === "number" ? range.originalContentChars : 0,
+    originalImageCount: typeof range.originalImageCount === "number" ? range.originalImageCount : 0,
+    originalImagePayloadBytes: typeof range.originalImagePayloadBytes === "number" ? range.originalImagePayloadBytes : 0,
+    replacementContentChars: typeof range.replacementContentChars === "number" ? range.replacementContentChars : 0,
+    originalApproxTokens: typeof range.originalApproxTokens === "number" ? range.originalApproxTokens : 0,
+    compressedApproxTokens: typeof range.compressedApproxTokens === "number" ? range.compressedApproxTokens : 0,
+  };
+}

package/src/telemetry.ts

@@ -1,12 +1,16 @@
+// Telemetry presentation. Owns Pi-reported usage formatting and factual
+// char/image aggregation. Agent-facing output no longer presents local
+// character-count-derived token estimates or projected token percentages as
+// authoritative figures. Legacy approximate-token fields remain computable for
+// backward-compatible readers but are not shown in new Agent-facing output.
+
 import type { ContextUsageSnapshot, DraftPlan, DraftTelemetry, TransactionState } from "./types.js";
 
-interface ContextUsageLike {
+export function snapshotContextUsage(usage: {
   tokens: number | null;
   contextWindow: number;
   percent: number | null;
-}
-
-export function snapshotContextUsage(usage: ContextUsageLike | undefined): ContextUsageSnapshot | undefined {
+} | undefined): ContextUsageSnapshot | undefined {
   if (!usage || !Number.isFinite(usage.contextWindow) || usage.contextWindow <= 0) return undefined;
   return {
     tokens: typeof usage.tokens === "number" && Number.isFinite(usage.tokens) ? Math.max(0, Math.round(usage.tokens)) : null,
@@ -16,8 +20,28 @@ export function snapshotContextUsage(usage: ContextUsageLike | undefined): Conte
   };
 }
 
-export function draftTelemetry(transaction: TransactionState | undefined, draft: DraftPlan | undefined): DraftTelemetry {
+/**
+ * Build draft telemetry. The factual char/image fields are authoritative for
+ * new output; legacy approximate-token fields are kept only for old readers.
+ */
+export function draftTelemetry(
+  transaction: TransactionState | undefined,
+  draft: DraftPlan | undefined,
+): DraftTelemetry {
   const ranges = draft?.ranges ?? [];
+  let selectedOriginalContentChars = 0;
+  let selectedReplacementContentChars = 0;
+  let selectedImageCount = 0;
+  let selectedImagePayloadBytes = 0;
+  let pendingSummaryCount = 0;
+  for (const range of ranges) {
+    selectedOriginalContentChars += range.originalContentChars;
+    selectedReplacementContentChars += range.replacementContentChars;
+    selectedImageCount += range.originalImageCount;
+    selectedImagePayloadBytes += range.originalImagePayloadBytes;
+    if (range.summary.trim().length === 0) pendingSummaryCount += 1;
+  }
+  // Legacy approximate-token sums, kept for backward-compatible readers only.
   const selectedOriginalApproxTokens = ranges.reduce((sum, range) => sum + range.originalApproxTokens, 0);
   const selectedCompressedApproxTokens = ranges.reduce((sum, range) => sum + range.compressedApproxTokens, 0);
   const estimatedSavedTokens = Math.max(0, selectedOriginalApproxTokens - selectedCompressedApproxTokens);
@@ -29,9 +53,16 @@ export function draftTelemetry(transaction: TransactionState | undefined, draft:
     ? null
     : (projectedTokens / contextWindow) * 100;
   return {
-    anchorTokens,
+    anchorUsage: transaction?.anchorUsage,
     contextWindow,
+    anchorTokens,
     anchorPercent,
+    selectedOriginalContentChars,
+    selectedReplacementContentChars,
+    selectedImageCount,
+    selectedImagePayloadBytes,
+    rangeCount: ranges.length,
+    pendingSummaryCount,
     selectedOriginalApproxTokens,
     selectedCompressedApproxTokens,
     estimatedSavedTokens,
@@ -53,25 +84,24 @@ export function formatPercent(percent: number | null, approximate = false): stri
   return `${approximate ? "~" : ""}${trim(percent)}%`;
 }
 
+/**
+ * Agent-facing awareness summary. Presents Pi-reported usage (labelled as such)
+ * and factual char/image stats only. No local token-savings or projected-token-
+ * percentage claims.
+ */
 export function formatTelemetry(telemetry: DraftTelemetry): string {
-  const lines = ["Context awareness (informational, not a target):"];
-  if (telemetry.contextWindow !== null) {
+  const lines = ["Context awareness (Pi reported; informational, not a target):"];
+  const usage = telemetry.anchorUsage;
+  if (usage?.contextWindow) {
     lines.push(
-      `anchor: ${formatTokenCount(telemetry.anchorTokens)} / ${formatTokenCount(telemetry.contextWindow)} (${formatPercent(telemetry.anchorPercent)})`,
+      `anchor: ${formatTokenCount(usage.tokens)} / ${formatTokenCount(usage.contextWindow)} (${formatPercent(usage.percent)}) [Pi reported]`,
     );
   } else {
-    lines.push("anchor: Pi context usage unavailable");
+    lines.push("anchor: Pi context usage unavailable [Pi reported; not derived from local char counts].");
   }
   lines.push(
-    `draft selection: ~${formatTokenCount(telemetry.selectedOriginalApproxTokens)} → ~${formatTokenCount(telemetry.selectedCompressedApproxTokens)} (save ~${formatTokenCount(telemetry.estimatedSavedTokens)})`,
+    `draft: ${telemetry.rangeCount} range(s) · ${telemetry.selectedOriginalContentChars} → ${telemetry.selectedReplacementContentChars} content chars · ${telemetry.selectedImageCount} images (${telemetry.selectedImagePayloadBytes} payload bytes) · ${telemetry.pendingSummaryCount} pending summary`,
   );
-  if (telemetry.contextWindow !== null && telemetry.projectedTokens !== null) {
-    lines.push(
-      `projected if committed now: ~${formatTokenCount(telemetry.projectedTokens)} / ${formatTokenCount(telemetry.contextWindow)} (${formatPercent(telemetry.projectedPercent, true)})`,
-    );
-  } else {
-    lines.push("projected total: unavailable until Pi reports anchor usage");
-  }
   return lines.join("\n");
 }
 

package/src/types.ts

@@ -1,3 +1,6 @@
+// Shared data contracts. This module defines structures only; it owns no
+// metric, grouping, selection, or persistence rules.
+
 export interface MessageLike {
   role: string;
   content?: unknown;
@@ -9,6 +12,7 @@ export interface MessageLike {
   command?: string;
   output?: string;
   summary?: string;
+  display?: boolean;
 }
 
 export interface SessionEntryLike {
@@ -36,6 +40,26 @@ export type AtomKind =
   | "orphan_tool_result"
   | "other";
 
+/** Factual measurement of a single image content part. */
+export interface ImageFact {
+  /** Sequence within the owning message. */
+  index: number;
+  mimeType: string;
+  /** Decoded base64 payload length in bytes. */
+  payloadBytes: number;
+  /** Pixel dimensions when reliably readable; absent otherwise. */
+  width?: number;
+  height?: number;
+}
+
+/** Factual content statistics for a message, atom, group, or range. */
+export interface ContentMetrics {
+  /** Unicode code point count of visible content text fields. */
+  contentChars: number;
+  imageCount: number;
+  images: ImageFact[];
+}
+
 export interface Atom {
   ref: string;
   index: number;
@@ -45,6 +69,9 @@ export interface Atom {
   messageKeys: string[];
   preview: string;
   fullText: string;
+  /** Factual content metrics aggregated across this atom's messages. */
+  metrics: ContentMetrics;
+  /** @deprecated legacy approximate token estimate; kept for old readers, not authoritative. */
   approxTokens: number;
   compressible: boolean;
   protocolClosed: boolean;
@@ -67,7 +94,17 @@ export interface CompressionBlock {
   entryIds: string[];
   messageKeys: string[];
   createdAt: string;
+  /** Factual original content chars replaced by this block. */
+  originalContentChars: number;
+  /** Factual image count in the original range. */
+  originalImageCount: number;
+  /** Factual decoded image payload bytes in the original range. */
+  originalImagePayloadBytes: number;
+  /** Factual replacement message content chars (midcompact wrapper + summary). */
+  replacementContentChars: number;
+  /** @deprecated legacy approximate token estimate; kept for old readers, not authoritative. */
   originalApproxTokens: number;
+  /** @deprecated legacy approximate token estimate; kept for old readers, not authoritative. */
   compressedApproxTokens: number;
 }
 
@@ -76,10 +113,16 @@ export interface CommitStats {
   committedAt: string;
   addedBlockIds: string[];
   addedRangeCount: number;
+  /** Factual totals for the committed ranges. */
+  selectedOriginalContentChars: number;
+  selectedReplacementContentChars: number;
+  selectedImageCount: number;
+  selectedImagePayloadBytes: number;
+  anchorUsage?: ContextUsageSnapshot;
+  /** @deprecated legacy approximate token fields; kept for old readers, not authoritative. */
   selectedOriginalApproxTokens: number;
   selectedCompressedApproxTokens: number;
   estimatedSavedTokens: number;
-  anchorUsage?: ContextUsageSnapshot;
   projectedTokens: number | null;
   projectedPercent: number | null;
 }
@@ -99,10 +142,19 @@ export interface DraftRange {
   startIndex: number;
   endIndex: number;
   topic?: string;
+  /** Empty until a summary is written; a range with empty summary is "pending". */
   summary: string;
   entryIds: string[];
   messageKeys: string[];
+  /** Factual original content chars in this range. */
+  originalContentChars: number;
+  originalImageCount: number;
+  originalImagePayloadBytes: number;
+  /** Factual replacement message content chars (wrapper + summary). */
+  replacementContentChars: number;
+  /** @deprecated legacy approximate token estimate; kept for old readers, not authoritative. */
   originalApproxTokens: number;
+  /** @deprecated legacy approximate token estimate; kept for old readers, not authoritative. */
   compressedApproxTokens: number;
   startPreview: string;
   endPreview: string;
@@ -115,19 +167,56 @@ export interface DraftPlan {
   ranges: DraftRange[];
 }
 
+/** How a transaction's initial DraftPlan editing is routed. Informational only; */
+/** both routes operate on the same DraftPlan and do not freeze boundaries. */
+export type StartMode = "agent" | "user";
+
 export interface TransactionState {
   version: 1;
   id: string;
   anchorEntryId: string;
   startedAt: string;
+  /** Initial routing chosen at start: Agent-first prompt or User-first UI. */
+  startMode?: StartMode;
   /** Frozen awareness captured when /midcompact starts; informational, never a target. */
   anchorUsage?: ContextUsageSnapshot;
 }
 
+/** Who currently holds the runtime mutex over DraftPlan edits. Not persisted. */
+export type PlanningLockOwner = "agent" | "ui";
+
+/** A requested atom span that may cross KEEP/protected atoms; fed into selection normalization. */
+export interface SelectionSpan {
+  startRef: string;
+  endRef: string;
+}
+
+/** A finalized ordinary span after KEEP/protected subtraction. */
+export interface OrdinarySpan {
+  startRef: string;
+  endRef: string;
+  startIndex: number;
+  endIndex: number;
+}
+
 export interface DraftTelemetry {
-  anchorTokens: number | null;
+  /** Pi-reported usage at the frozen anchor; informational. */
+  anchorUsage?: ContextUsageSnapshot;
+  /** @deprecated Pi-reported anchor context window; use anchorUsage. Kept for UI readers. */
   contextWindow: number | null;
+  /** @deprecated Pi-reported anchor tokens; use anchorUsage. Kept for UI readers. */
+  anchorTokens: number | null;
+  /** @deprecated Pi-reported anchor percent; use anchorUsage. Kept for UI readers. */
   anchorPercent: number | null;
+  /** Factual selected metrics. */
+  selectedOriginalContentChars: number;
+  selectedReplacementContentChars: number;
+  selectedImageCount: number;
+  selectedImagePayloadBytes: number;
+  rangeCount: number;
+  /** Ranges still awaiting a non-empty summary. */
+  pendingSummaryCount: number;
+  /** @deprecated legacy approximate token fields; kept for old readers, not authoritative. */
   selectedOriginalApproxTokens: number;
   selectedCompressedApproxTokens: number;
   estimatedSavedTokens: number;
@@ -145,6 +234,56 @@ export interface LocateQuery {
   detail?: "brief" | "full";
 }
 
+export interface InventoryQuery {
+  pageSize?: number;
+  cursor?: string;
+}
+
+export interface InventoryGroup {
+  ref: string;
+  label: string;
+  isPrefix: boolean;
+  startAtomRef: string;
+  endAtomRef: string;
+  atomCount: number;
+  messageCount: number;
+  contentChars: number;
+  imageCount: number;
+  imagePayloadBytes: number;
+  imageMimeTypes: string[];
+  protectedAtomCount: number;
+  compressibleAtomCount: number;
+}
+
+export interface InventoryTotals {
+  atomCount: number;
+  messageCount: number;
+  contentChars: number;
+  imageCount: number;
+  imagePayloadBytes: number;
+  groupCount: number;
+  protectedAtomCount: number;
+  compressibleAtomCount: number;
+}
+
+export interface InventoryPiUsage {
+  available: boolean;
+  contextWindow: number | null;
+  tokens: number | null;
+  percent: number | null;
+  /** Provenance label, e.g. "Pi reported at anchor start". */
+  provenance: string;
+}
+
+export interface InventoryPage {
+  anchor: { transactionId: string; anchorEntryId: string };
+  piUsage: InventoryPiUsage;
+  totals: InventoryTotals;
+  groups: InventoryGroup[];
+  nextCursor: string | null;
+  pageSize: number;
+}
+
 export type ReviewAction =
   | { action: "close" }
   | { action: "edit-summary"; draftId: string }