pi-midcompact 0.2.1

package/src/telemetry.ts

@@ -0,0 +1,81 @@
+import type { ContextUsageSnapshot, DraftPlan, DraftTelemetry, TransactionState } from "./types.js";
+
+interface ContextUsageLike {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+}
+
+export function snapshotContextUsage(usage: ContextUsageLike | 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,
+    contextWindow: Math.max(1, Math.round(usage.contextWindow)),
+    percent: typeof usage.percent === "number" && Number.isFinite(usage.percent) ? usage.percent : null,
+    capturedAt: new Date().toISOString(),
+  };
+}
+
+export function draftTelemetry(transaction: TransactionState | undefined, draft: DraftPlan | undefined): DraftTelemetry {
+  const ranges = draft?.ranges ?? [];
+  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);
+  const anchorTokens = transaction?.anchorUsage?.tokens ?? null;
+  const contextWindow = transaction?.anchorUsage?.contextWindow ?? null;
+  const anchorPercent = transaction?.anchorUsage?.percent ?? null;
+  const projectedTokens = anchorTokens === null ? null : Math.max(0, anchorTokens - estimatedSavedTokens);
+  const projectedPercent = projectedTokens === null || contextWindow === null || contextWindow <= 0
+    ? null
+    : (projectedTokens / contextWindow) * 100;
+  return {
+    anchorTokens,
+    contextWindow,
+    anchorPercent,
+    selectedOriginalApproxTokens,
+    selectedCompressedApproxTokens,
+    estimatedSavedTokens,
+    projectedTokens,
+    projectedPercent,
+  };
+}
+
+export function formatTokenCount(tokens: number | null): string {
+  if (tokens === null || !Number.isFinite(tokens)) return "?";
+  const abs = Math.abs(tokens);
+  if (abs >= 1_000_000) return `${trim(tokens / 1_000_000)}M`;
+  if (abs >= 1_000) return `${trim(tokens / 1_000)}k`;
+  return String(Math.round(tokens));
+}
+
+export function formatPercent(percent: number | null, approximate = false): string {
+  if (percent === null || !Number.isFinite(percent)) return "?";
+  return `${approximate ? "~" : ""}${trim(percent)}%`;
+}
+
+export function formatTelemetry(telemetry: DraftTelemetry): string {
+  const lines = ["Context awareness (informational, not a target):"];
+  if (telemetry.contextWindow !== null) {
+    lines.push(
+      `anchor: ${formatTokenCount(telemetry.anchorTokens)} / ${formatTokenCount(telemetry.contextWindow)} (${formatPercent(telemetry.anchorPercent)})`,
+    );
+  } else {
+    lines.push("anchor: Pi context usage unavailable");
+  }
+  lines.push(
+    `draft selection: ~${formatTokenCount(telemetry.selectedOriginalApproxTokens)} → ~${formatTokenCount(telemetry.selectedCompressedApproxTokens)} (save ~${formatTokenCount(telemetry.estimatedSavedTokens)})`,
+  );
+  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");
+}
+
+function trim(value: number): string {
+  const rounded = Math.round(value * 10) / 10;
+  return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+export interface MessageLike {
+  role: string;
+  content?: unknown;
+  timestamp?: number;
+  toolCallId?: string;
+  toolName?: string;
+  customType?: string;
+  details?: unknown;
+  command?: string;
+  output?: string;
+  summary?: string;
+}
+
+export interface SessionEntryLike {
+  id: string;
+  parentId?: string | null;
+  type: string;
+  customType?: string;
+  data?: unknown;
+  message?: MessageLike;
+}
+
+export interface MessageRef {
+  message: MessageLike;
+  key: string;
+  entryId?: string;
+}
+
+export type AtomKind =
+  | "user"
+  | "assistant"
+  | "tool_exchange"
+  | "bash"
+  | "compressed"
+  | "custom"
+  | "orphan_tool_result"
+  | "other";
+
+export interface Atom {
+  ref: string;
+  index: number;
+  kind: AtomKind;
+  messages: MessageRef[];
+  entryIds: string[];
+  messageKeys: string[];
+  preview: string;
+  fullText: string;
+  approxTokens: number;
+  compressible: boolean;
+  protocolClosed: boolean;
+  toolNames: string[];
+  roles: string[];
+  compressedBlockId?: string;
+}
+
+export interface ContextUsageSnapshot {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+  capturedAt: string;
+}
+
+export interface CompressionBlock {
+  id: string;
+  topic?: string;
+  summary: string;
+  entryIds: string[];
+  messageKeys: string[];
+  createdAt: string;
+  originalApproxTokens: number;
+  compressedApproxTokens: number;
+}
+
+export interface CommitStats {
+  transactionId: string;
+  committedAt: string;
+  addedBlockIds: string[];
+  addedRangeCount: number;
+  selectedOriginalApproxTokens: number;
+  selectedCompressedApproxTokens: number;
+  estimatedSavedTokens: number;
+  anchorUsage?: ContextUsageSnapshot;
+  projectedTokens: number | null;
+  projectedPercent: number | null;
+}
+
+export interface CompressionState {
+  /** State format stays v1 for backward compatibility with v0.1.x sessions. */
+  version: 1;
+  createdAt: string;
+  blocks: CompressionBlock[];
+  lastCommit?: CommitStats;
+}
+
+export interface DraftRange {
+  id: string;
+  startRef: string;
+  endRef: string;
+  startIndex: number;
+  endIndex: number;
+  topic?: string;
+  summary: string;
+  entryIds: string[];
+  messageKeys: string[];
+  originalApproxTokens: number;
+  compressedApproxTokens: number;
+  startPreview: string;
+  endPreview: string;
+}
+
+export interface DraftPlan {
+  version: 1;
+  transactionId: string;
+  revision: number;
+  ranges: DraftRange[];
+}
+
+export interface TransactionState {
+  version: 1;
+  id: string;
+  anchorEntryId: string;
+  startedAt: string;
+  /** Frozen awareness captured when /midcompact starts; informational, never a target. */
+  anchorUsage?: ContextUsageSnapshot;
+}
+
+export interface DraftTelemetry {
+  anchorTokens: number | null;
+  contextWindow: number | null;
+  anchorPercent: number | null;
+  selectedOriginalApproxTokens: number;
+  selectedCompressedApproxTokens: number;
+  estimatedSavedTokens: number;
+  projectedTokens: number | null;
+  projectedPercent: number | null;
+}
+
+export interface LocateQuery {
+  ref?: string;
+  pattern?: string;
+  source?: "any" | "user" | "assistant" | "tool_call" | "tool_result";
+  toolName?: string;
+  direction?: "oldest" | "newest";
+  limit?: number;
+  detail?: "brief" | "full";
+}
+
+export type ReviewAction =
+  | { action: "close" }
+  | { action: "edit-summary"; draftId: string }
+  | { action: "edit-topic"; draftId: string }
+  | { action: "remove"; draftId: string };