@astralyn/pi 0.82.6 → 0.83.0

package/docs/bundled/tool-presentation.md

@@ -6,17 +6,15 @@ The `@astralyn/pi` package uses Pi's native tool transcript presentation rather
 
 ```text
 ● ToolName(args)
-│ result
+│ first result line
+│ second result line
+│
+│ final result line
 ```
 
-States use the same shell:
+The dim result rail continues through every visual line; an empty output line renders as a bare `│`. Calls keep their status in the leading dot: warning while pending or running, green after success, and red after failure. For default-shell tools that are still running after two seconds, the shell adds a live result row such as `Running… (2.1s)` and removes it when the call settles. Tools with purpose-built progress UI can opt out through `rendersOwnProgress`; tools using `renderShell: "self"` continue to own their entire presentation.
 
-```text
-● ToolName(args)       completed call
-● ToolName Working...  pending call
-● ToolName(args)       failed call (error color)
-│ result               successful or failed output
-```
+Time-driven renderers use `renderRefreshIntervalMs` separately from `rendersOwnProgress`. The former periodically rebuilds call/result components only during the partial lifecycle; the latter only hides the generic `Running…` row. The native shell shares the shortest needed interval, constrains explicit intervals to 250ms–60s, and stops refreshing on final result, abort, disposal, session replacement, chat rebuild, or shutdown. Renderers compute elapsed/countdown values from absolute timestamps or deadlines, so a delayed repaint never changes the underlying wall-clock meaning.
 
 ## Implementation boundary
 
@@ -31,7 +29,7 @@ The native tool presentation owns:
 
 Built-in renderers remain responsible for semantic content such as file paths, syntax highlighting, search results, Diff previews, and command output. The outer shell is native so built-in tools, bundled extensions, and compatible third-party tools share the same presentation.
 
-Consecutive tools may opt into a shared collapsed group through `toolGroup`. Built-in `read` and `find` calls use the `explore` group, and the bundled `todo` tool uses the `todo` group: their call rows render as one compact run with a single leading gap, while `Ctrl+O` restores each tool's complete call and result. Collapsed Todo rows are result-aware: successful current snapshots summarize the completed operation (created ids, update/get status, list counts, deletion, or clear) rather than only its arguments. Failures include a sanitized reason capped at 120 characters; missing or unrecognized result details fall back safely to the call summary.
+Consecutive tools may opt into a shared collapsed group through `toolGroup`. Built-in `read`, `find`, `grep`, and `ls` calls use the `explore` group, and the bundled `todo` tool uses the `todo` group: their call rows render as one compact run with a single leading gap, while the configured expand-tools key (`Ctrl+O` by default) restores each tool's complete call and result. Collapsed Todo rows are result-aware: successful current snapshots summarize the completed operation, including task IDs and subjects for creation, rather than only its arguments. Failures include a sanitized reason capped at 120 characters; missing or unrecognized result details fall back safely to the call summary.
 
 ## Renderer inheritance
 
@@ -51,9 +49,10 @@ When no semantic renderer is available:
 
 - arguments are serialized into a bounded one-line summary;
 - output is collapsed to the most recent ten visual lines;
-- `Ctrl+O` expands the complete output;
+- a shared hint above the tail reports the number of hidden earlier lines and the configured expand key;
+- expanding restores the complete output;
 - historical tools that are no longer registered still receive the same shell;
-- failed calls use the error-colored bullet while result details keep the result bar.
+- failed calls use the error-colored bullet while result details keep the result rail.
 
 The fallback does not change tool schemas, execution logic, or result protocols.
 
@@ -62,15 +61,17 @@ The fallback does not change tool schemas, execution logic, or result protocols.
 The native path continues to preserve:
 
 - `read`, `bash`, `grep`, `find`, `ls`, `write`, and `edit` semantics;
-- faithful width-aware raw command previews for Bash;
-- running Bash duration after the two-second progress threshold, without a permanent completion timer;
-- Diff previews and first-change-line metadata for `edit`;
+- faithful width-aware raw command previews for Bash, with honest multi-line and width truncation markers;
+- shell-wide running duration after the two-second progress threshold, with lifecycle-safe refresh disposal and no permanent completion timer;
+- path links and consistent search flags/limits across built-in renderers;
+- Diff statistics plus a ten-line collapsed Diff preview for `edit`, with the complete Diff restored on expand;
 - syntax highlighting;
 - image output and Kitty conversion;
 - native collapsed/expanded handling;
-- custom UI explicitly using `renderShell: "self"`.
+- custom UI explicitly using `renderShell: "self"`;
+- independently refreshed custom elapsed time and retry countdowns without a duplicate generic progress row.
 
-`edit` now uses the native outer shell while keeping its asynchronous Diff preview and final Diff result.
+Built-in result truncation hints share the same `… (N earlier/more lines, … to expand)` language and correct singular/plural forms. `edit` uses the native outer shell while keeping its asynchronous Diff preview and final Diff result.
 
 ## Deliberately rejected approaches
 

package/docs/compaction.md

@@ -2,14 +2,11 @@
 
 LLMs have limited context windows. When conversations grow too long, pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
 
-**Source files** ([ming-kang/pi](https://github.com/ming-kang/pi)):
-- [`src/core/compaction/compaction.ts`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/compaction.ts) - Auto-compaction logic
-- [`src/core/compaction/branch-summarization.ts`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts) - Branch summarization
-- [`src/core/compaction/utils.ts`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
-- [`src/core/session-manager.ts`](https://github.com/ming-kang/pi/blob/main/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
-- [`src/core/extensions/types.ts`](https://github.com/ming-kang/pi/blob/main/src/core/extensions/types.ts) - Extension event types
+## Public API
 
-For TypeScript definitions in your project, inspect `node_modules/@astralyn/pi/dist/`.
+Programmatic compaction helpers are exported by [`@astralyn/pi`](https://www.npmjs.com/package/@astralyn/pi): `compact`, `generateSummary`, `generateSummaryWithUsage`, `collectEntriesForBranchSummary`, `prepareBranchEntries`, `generateBranchSummary`, and `serializeConversation`.
+
+`CompactionEntry` and `BranchSummaryEntry` are public types; see [Session Format](session-format.md) for their persisted JSONL representation. For extension lifecycle events, see [compaction events](extensions.md#session_before_compact--session_compact) and [tree events](extensions.md#session_before_tree--session_tree).
 
 ## Overview
 
@@ -34,7 +31,7 @@ contextTokens > contextWindow - reserveTokens
 
 By default, `reserveTokens` is 16384 tokens (configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`). This leaves room for the LLM's response.
 
-During an active tool-calling run, Pi evaluates this threshold after each complete tool batch, including the newly appended tool results, and before another provider request. If compaction succeeds, Pi rebuilds the context and continues the same agent run without inserting a continuation prompt. If compaction is cancelled, fails, has no safe cut point, or leaves the estimated retained context above the threshold, Pi fails closed before queue polling or another provider request. Because the upstream stateful Agent does not expose its low-level graceful turn-stop hook, this exceptional path ends with an explicit error/aborted assistant lifecycle; the preceding `compaction_end` event contains the underlying warning or failure.
+During an active tool-calling run, Pi evaluates this threshold after each complete tool batch, including the newly appended tool results, and before another provider request. If compaction succeeds, Pi rebuilds the context and continues the same agent run without inserting a continuation prompt. A voluntary `session_before_compact` cancellation at `timing: "midTurn"` lets that run continue and suppresses further mid-turn compaction checks for the rest of the run. An abort, compaction failure, no safe cut point, or retained context that remains above the threshold fails closed before queue polling or another provider request. Cancellations at other timings likewise leave over-threshold context to fail closed before the next request. Because the upstream stateful Agent does not expose its low-level graceful turn-stop hook, a fail-closed path ends with an explicit error/aborted assistant lifecycle; the preceding `compaction_end` event contains the underlying warning or failure.
 
 This between-tool-batch trigger is separate from **split-turn compaction** below: the trigger determines *when* compaction runs, while split-turn support determines *where* a very long turn can be cut.
 
@@ -124,14 +121,14 @@ Never cut at tool results (they must stay with their tool call).
 
 ### CompactionEntry Structure
 
-Defined in [`session-manager.ts`](https://github.com/ming-kang/pi/blob/main/src/core/session-manager.ts):
+The public `CompactionEntry` type is documented in [Session Format](session-format.md):
 
 ```typescript
 interface CompactionEntry<T = unknown> {
   type: "compaction";
   id: string;
-  parentId: string;
-  timestamp: number;
+  parentId: string | null;
+  timestamp: string;
   summary: string;
   firstKeptEntryId: string;
   tokensBefore: number;
@@ -140,7 +137,7 @@ interface CompactionEntry<T = unknown> {
   details?: T;         // implementation-specific data
 }
 
-// Default compaction uses this for details (from compaction.ts):
+// Default compaction uses this for details:
 interface CompactionDetails {
   readFiles: string[];
   modifiedFiles: string[];
@@ -149,7 +146,7 @@ interface CompactionDetails {
 
 Extensions can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom extension implementations can use their own structure. Generated and extension-provided summaries store their LLM `usage` when available so session totals include summarization work.
 
-See [`prepareCompaction()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/compaction.ts) for the implementation. For direct programmatic summarization, `generateSummary()` returns the summary text and `generateSummaryWithUsage()` returns `{ text, usage }`.
+Pi uses an internal preparation step before `compact()`. For direct programmatic summarization, `generateSummary()` returns the summary text and `generateSummaryWithUsage()` returns `{ text, usage }`.
 
 ## Branch Summarization
 
@@ -177,9 +174,9 @@ Entries to summarize: B, C, D
 
 After navigation with summary:
 
-         ┌─ B ─ C ─ D ─ [summary of B,C,D]
+         ┌─ B ─ C ─ D (old leaf, abandoned)
     A ───┤
-         └─ E ─ F (new leaf)
+         └─ E ─ F ─ [summary of B,C,D] (new leaf)
 ```
 
 ### Cumulative File Tracking
@@ -192,14 +189,14 @@ This means file tracking accumulates across multiple compactions or nested branc
 
 ### BranchSummaryEntry Structure
 
-Defined in [`session-manager.ts`](https://github.com/ming-kang/pi/blob/main/src/core/session-manager.ts):
+The public `BranchSummaryEntry` type is documented in [Session Format](session-format.md):
 
 ```typescript
 interface BranchSummaryEntry<T = unknown> {
   type: "branch_summary";
   id: string;
-  parentId: string;
-  timestamp: number;
+  parentId: string | null;
+  timestamp: string;
   summary: string;
   fromId: string;      // Entry we navigated from
   usage?: Usage;       // LLM usage that generated the summary
@@ -207,7 +204,7 @@ interface BranchSummaryEntry<T = unknown> {
   details?: T;         // implementation-specific data
 }
 
-// Default branch summarization uses this for details (from branch-summarization.ts):
+// Default branch summarization uses this for details:
 interface BranchSummaryDetails {
   readFiles: string[];
   modifiedFiles: string[];
@@ -216,7 +213,7 @@ interface BranchSummaryDetails {
 
 Same as compaction, extensions can store custom data in `details`.
 
-See [`collectEntriesForBranchSummary()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/branch-summarization.ts) for the implementation.
+For programmatic branch summarization, use `collectEntriesForBranchSummary()`, `prepareBranchEntries()`, and `generateBranchSummary()`.
 
 ## Summary Format
 
@@ -260,7 +257,7 @@ path/to/changed.ts
 
 ### Message Serialization
 
-Before summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/ming-kang/pi/blob/main/src/core/compaction/utils.ts):
+Before summarization, the exported `serializeConversation()` function serializes messages to text:
 
 ```
 [User]: What they said
@@ -276,11 +273,11 @@ Tool results are truncated to 2000 characters during serialization. Content beyo
 
 ## Custom Summarization via Extensions
 
-Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/ming-kang/pi/blob/main/src/core/extensions/types.ts) for event type definitions.
+Extensions can intercept and customize both compaction and branch summarization. See [compaction events](extensions.md#session_before_compact--session_compact) and [tree events](extensions.md#session_before_tree--session_tree).
 
 ### session_before_compact
 
-Fired before auto-compaction or `/compact`. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
+Fired before auto-compaction or `/compact`. Can cancel or provide custom summary. See `SessionBeforeCompactEvent`.
 
 ```typescript
 pi.on("session_before_compact", async (event, ctx) => {
@@ -300,10 +297,10 @@ pi.on("session_before_compact", async (event, ctx) => {
   // willRetry - whether overflow recovery intends to retry if compaction produces a safe retained context
   // signal - AbortSignal (pass to LLM calls)
 
-  // Cancel. Consequences depend on timing: a "midTurn" cancel skips compaction
-  // for the rest of the run and the run continues at your risk of overflowing;
-  // other timings leave the over-threshold context to fail closed before the
-  // next provider request.
+  // A voluntary cancel at timing "midTurn" continues the current run and skips
+  // further mid-turn checks. An abort, failure, no safe cut, or unsafe retained
+  // context fails closed; at other timings, over-threshold context also fails
+  // closed before the next provider request.
   return { cancel: true };
 
   // Custom summary:
@@ -358,7 +355,7 @@ See [custom-compaction.ts](../examples/extensions/custom-compaction.ts) for a co
 
 ### session_before_tree
 
-Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
+Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary. See `SessionBeforeTreeEvent`.
 
 ```typescript
 pi.on("session_before_tree", async (event, ctx) => {
@@ -386,8 +383,6 @@ pi.on("session_before_tree", async (event, ctx) => {
 });
 ```
 
-See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
-
 ## Settings
 
 Configure compaction in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`: