pi-condense 2.6.0 → 2.8.0

package/src/types.ts

@@ -87,6 +87,13 @@ export const CUSTOM_TYPE_CHAIN = "context-prune-chain";
  */
 export const CUSTOM_TYPE_DIAGNOSTIC = "context-prune-diagnostic";
 
+/**
+ * Per-flush-attempt observability record. Written once per non-concurrent
+ * flushPending invocation, regardless of outcome (including "empty" and
+ * "error"). Append-only log: never in LLM context, never reconstructed.
+ */
+export const CUSTOM_TYPE_FLUSH_METRICS = "context-prune-flush-metrics";
+
 export type DiagnosticKind = "unresolved-range" | "range-id-mismatch" | "orphan-sweep";
 
 export interface DiagnosticEntryData {
@@ -232,7 +239,8 @@ export const SUMMARIZER_MAX_TIMEOUT_PRESETS: { value: string; label: string }[]
 /**
  * Cycling presets for the `autoBudgetThreshold` setting (stored as strings;
  * the settings UI cycles string values). "0" is the disabled sentinel → null.
- * Other values are 0–1 fractions of the context window (e.g. "0.8" = flush at 80%).
+ * Other values are 0–1 fractions of the context window (e.g. "0.8" = flush at
+ * 80% of the window, or at MAX_BUDGET_WINDOW tokens, whichever comes first).
  */
 export const AUTO_BUDGET_PRESETS: { value: string; label: string }[] = [
   { value: "0", label: "Off (default)" },
@@ -380,10 +388,14 @@ export interface ContextPruneConfig {
   /**
    * Token-budget auto-flush trigger. A fraction in (0, 1] (a 0–1 share of the
    * context window, NOT a 0–100 percentage; e.g. 0.8 = flush at 80% of the
-   * window). When set, a flush of all pending batches is forced at the end of
-   * any tool-using turn once context usage (tokens / contextWindow) reaches the
-   * threshold — regardless of `pruneOn`. An ADDITIONAL trigger on top of
-   * `pruneOn`, not a replacement.
+   * window, capped at 300k tokens - see below). When set, a flush of all
+   * pending batches is forced at the end of
+   * any tool-using turn once context usage reaches `threshold * contextWindow`
+   * tokens OR 300,000 tokens (MAX_BUDGET_WINDOW in src/budget.ts), whichever
+   * comes first — regardless of `pruneOn`. The ceiling keeps the setting
+   * reachable on huge-window models, where 0.9 of 1M would mean 900k tokens; it
+   * never binds on a model advertising 300k or less. An ADDITIONAL trigger on
+   * top of `pruneOn`, not a replacement.
    *
    * null (default) = disabled, preserving pre-feature behavior. Out-of-range
    * values (<= 0 or > 1) normalize to null.
@@ -395,7 +407,11 @@ export interface ContextPruneConfig {
   spillPreviewBytes: number;
   /**
    * Per-turn usage-fraction increase (0–1) that forces a flush, independent of
-   * autoBudgetThreshold. null (default) = disabled. Out-of-range (<= 0 or > 1) normalizes to null.
+   * autoBudgetThreshold. The fraction is measured against the effective window
+   * `min(contextWindow, MAX_BUDGET_WINDOW)` (300_000), so the required growth is
+   * `delta * min(contextWindow, MAX_BUDGET_WINDOW)` tokens - e.g. 0.1 means +30k
+   * tokens in one turn on any model at or above 300k, and +20k on a 200k model.
+   * null (default) = disabled. Out-of-range (<= 0 or > 1) normalizes to null.
    */
   budgetTurnDelta: number | null;
 }
@@ -672,6 +688,30 @@ export interface SummaryMessageDetails {
   timestamp: number;
 }
 
+/** Snapshot of what the pruner cannot (yet) reclaim. All token values are Math.round(JSON-chars / 4). */
+export interface ContextMetricsSnapshot {
+  /** Est. tokens of thinking blocks retained in the trailing open segment. */
+  openCycleThinkingTokens: number;
+  /** max(largest closed chain, open segment) chars / total branch chars, 0-100. */
+  largestChainSharePct: number;
+  /** Est. tokens of summarization-eligible unsummarized toolResults after the frontier. */
+  frontierGapTokens: number;
+}
+
+export type FlushTrigger = "budget" | "delta" | "message-end" | "manual" | "rearmed";
+
+/** Payload of CUSTOM_TYPE_FLUSH_METRICS. */
+export interface FlushMetricsEntry {
+  ts: number;
+  trigger: FlushTrigger;
+  /** Batches after rescan+trim, before processing. */
+  capturedBatches: number;
+  processedBatches: number;
+  outcome: "summarized" | "skipped-oversized" | "skipped-deduped" | "skipped-trivial" | "empty" | "error";
+  /** Computed at flush ENTRY (pre-flush pressure). */
+  metrics: ContextMetricsSnapshot;
+}
+
 // ── Summarizer stats ────────────────────────────────────────────────────────
 
 /**
@@ -794,6 +834,8 @@ export interface FlushOptions {
    * the frontier. All pending batches are restored so the next flush can retry.
    */
   signal?: AbortSignal;
+  /** Which trigger initiated this flush. Defaults to "manual" when absent. */
+  trigger?: FlushTrigger;
   /**
    * The final text-only assistant message that triggered an agent-message flush.
    * pi emits `message_end` to extensions before persisting it to the session, so it