@astralyn/pi 1.4.0 → 1.4.2

package/docs/bundled/extensions/cached-compaction.md

@@ -0,0 +1,35 @@
+# Cached compaction
+
+The bundled `cached-compaction` extension replaces summary generation for manual `/compact` and automatic threshold compaction. Pi still owns the cut point, session persistence, recent-message retention, and context rebuilding.
+
+Instead of flattening the older messages into a new summarizer prompt and truncating each tool result, the extension sends the current prepared conversation plus one user message asking for a structured checkpoint. This lets the provider reuse its prompt cache and lets the summary model read the complete tool output that was present in the conversation.
+
+Caching is an optimization, not a prerequisite. The extension does not estimate cache expiry or adapt requests to individual providers. A cold cache can make this request more expensive than native compaction, but produces the same kind of checkpoint without a separate provider-specific path.
+
+## Summary boundary
+
+The extension uses Pi's `firstKeptEntryId` unchanged. Because the summary model also sees the retained recent messages, its instruction quotes the first retained message as `<kept-start>` and explicitly excludes that message and everything after it from the summary. Repeated opening text is identified by its occurrence counting backward from the end. If no usable text or tool-call boundary exists, native compaction runs instead.
+
+The summary keeps Pi's Goal, Constraints & Preferences, Progress, Key Decisions, Next Steps, and Critical Context sections. Optional `/compact [instructions]` focus is appended to the instruction. Read and modified file lists are computed from session operations and previous compaction details rather than generated by the model.
+
+## Fallbacks
+
+- Overflow recovery always uses native compaction because the complete context has already exceeded the model window.
+- A missing boundary, request failure, empty summary, tool call, or output-length stop falls back to native compaction.
+- Cancelling the summary cancels that compaction without starting a second native summary request.
+- Branch summarization through `/tree` is unchanged.
+
+Native compaction accepts the same native file-list shape in extension-provided compaction details, so alternating between cached and native compaction does not reset file history.
+
+## Result card
+
+A successful cached-path compaction adds a persistent display-only card after the summary:
+
+```text
+Cached compaction · manual
+Cache 641.2k/648.8k (98.8%) · output 2.8k · 18.4s
+```
+
+Automatic compaction is labelled `automatic`. The cache figures are the response's actual `cacheRead` divided by `input + cacheRead + cacheWrite`; the card also shows output tokens and elapsed time. It contains no cost estimate and never enters model context. Native fallback adds no card.
+
+The extension registers no commands or settings.

package/docs/bundled/tool-presentation.md

@@ -39,23 +39,25 @@ The `Ctrl+B` background hint is not part of a tool row. Once a foreground manage
 
 The look is defined in one place, `src/modes/interactive/tool-view/style.ts`: the marker and rail glyphs, their colors, the spacing between blocks, and which tools fold their result. `FramedComponent` in the same file hangs a component's lines off the marker or the rail and derives the gutter width from the glyphs.
 
-`tool-view/tool-execution.ts` owns one call's lifecycle: pending, success and error states, expansion, image placement and Kitty conversion, and renderer disposal. `tool-view/chat.ts` owns the chat container that measures tool blocks for spacing and disposes rows when the chat clears. Extension tools and built-in tools use the same shell, so a third-party tool gets the same dot and rail without any change.
+The upstream `components/tool-execution.ts` owns one call's lifecycle: pending, success and error states, expansion, image placement and Kitty conversion, and renderer disposal. The bundled `tool-presentation` extension attaches a TUI-only shell through the existing tool renderer resolver; `tool-view/shell.ts` maps the visual policy to that shell. The old `tool-view/tool-execution.ts` path is only a compatibility adapter for direct source imports, not a second lifecycle implementation.
 
-Built-in renderers remain responsible for semantic content such as file paths, syntax highlighting, search results, Diff previews, and command output. They return plain components; the shell frames them.
+`tool-view/chat.ts` owns the chat container that measures tool blocks for spacing and disposes rows when the chat clears. It reads each row's gap policy: upstream rows keep one blank line, while the distribution shell uses the compact policy above. Extension tools and built-in tools use the same shell unless they explicitly own a self shell.
+
+Built-in renderers remain responsible for semantic content such as file paths, syntax highlighting, search results, Diff previews, and command output. They return plain components; the native component passes them to the shell without wrapping their renderer functions. HTML export uses only those renderers and ignores the TUI shell, so it retains its existing output. Disable `builtin:tool-presentation` (for example with `-builtin:tool-presentation` in extension settings) to use the upstream Box presentation instead.
 
 ## Renderer inheritance
 
 | Tool definition | Behavior |
 |---|---|
-| No `renderCall`/`renderResult` | Uses the native call and result fallback. |
-| Custom renderer with the default shell | Uses the native shell around the custom content. |
-| `renderShell: "self"` | Keeps complete ownership of the tool's layout. |
+| No `renderCall`/`renderResult` | Uses the active shell's call and result fallback. |
+| Custom renderer with the default shell | Uses the distribution shell around the custom content, or upstream Box when the extension is disabled. |
+| `renderShell: "self"` | Keeps complete ownership of the tool's layout; no distribution shell is attached. |
 
 Built-in tool definitions are also used when an extension overrides only one renderer slot. A custom call renderer can inherit the built-in result renderer, and vice versa. An extension that overrides a built-in tool with its own result renderer controls what that row shows, including when it is collapsed.
 
 The inherited Bash result renderer keeps its elapsed time even with a custom call renderer. Call and result renderers share `state`; a renderer that adds a `dispose()` callback must also call the previous callback so both renderers can release their resources.
 
-Renderer failures fall back to native generic output rather than breaking the transcript.
+Renderer failures fall back to the active shell's generic output rather than breaking the transcript; without a distribution shell, the upstream generic fallback is used.
 
 ## Generic fallback
 
@@ -89,7 +91,7 @@ The package does not use:
 
 - prototype patching of `ToolExecutionComponent` from an extension;
 - same-name re-registration to replace built-in tools;
-- a global renderer registry exposed through Extension API;
+- a second global renderer registry exposed through Extension API;
 - a restored `tools-view` extension;
 - forced decoration of third-party tools that explicitly own their shell;
 - merging consecutive calls into a collapsed group, or a shell-level progress row.

package/docs/compaction.md

@@ -17,7 +17,7 @@ Pi has two summarization mechanisms:
 | Compaction | Context exceeds threshold, or `/compact` | Summarize old messages to free up context |
 | Branch summarization | `/tree` navigation | Preserve context when switching branches |
 
-Both use the same structured summary format and track file operations cumulatively. Summarization requests disable prompt-cache writes because these one-off prompts are unlikely to be reused.
+Both use the same structured summary format and track file operations cumulatively. Native summarization requests disable prompt-cache writes because these one-off prompts are unlikely to be reused. The bundled [Cached compaction](bundled/extensions/cached-compaction.md) extension instead summarizes the prepared conversation directly for manual and threshold compaction, allowing provider prompt-cache reuse; overflow recovery and failed cached-path attempts retain the native behavior.
 
 ## Compaction
 

package/docs/docs.json

@@ -72,6 +72,10 @@
           "title": "BTW",
           "path": "bundled/extensions/btw.md"
         },
+        {
+          "title": "Cached compaction",
+          "path": "bundled/extensions/cached-compaction.md"
+        },
         {
           "title": "DeepWiki",
           "path": "bundled/extensions/deepwiki.md"

package/docs/extensions.md

@@ -2531,7 +2531,7 @@ export default function (pi: ExtensionAPI) {
 
 Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API.
 
-By default, tool output is wrapped in Pi's native call/result shell, which owns the status dot, result rail, spacing between consecutive tool rows, and fallback rendering. A defined `renderCall` or `renderResult` must return a `Component`. If a slot renderer is not defined, the shell uses fallback rendering for that slot. Return content without leading padding: the shell trims leading blank result lines and adds no blank line between consecutive tool rows.
+By default, tool output is wrapped in the active call/result shell, which owns the status dot, result rail, spacing between consecutive tool rows, and fallback rendering. The bundled `tool-presentation` extension supplies the distribution's compact shell; disabling `builtin:tool-presentation` restores the upstream Box shell. A defined `renderCall` or `renderResult` must return a `Component`. If a slot renderer is not defined, the shell uses fallback rendering for that slot. Return content without leading padding: the compact shell trims leading blank result lines and adds no blank line between consecutive single-line tool rows.
 
 Set `renderShell: "self"` when the tool should render its own shell instead of using the native shell. This is useful for tools that need complete control over framing or background behavior, for example large previews that must stay visually stable after the tool settles.
 
@@ -3345,6 +3345,8 @@ A tool that reaches other tools declares which ones a call may reach with `reach
 
 `pi.registerToolRenderer((toolName, next) => renderers)` chooses `renderCall`, `renderResult`, and `renderShell` for calls to any tool, including tools that are not registered yet, such as MCP tools in a resumed session. Resolvers run in extension load order. `next()` returns the remaining resolvers' result or the registered tool's renderers, so `next() ?? mine` supplies a fallback. Interactive transcripts and HTML exports both use these resolvers.
 
+A resolver can also attach an optional `shell` (`ToolExecutionShell`) for TUI-only framing, fallbacks, and row spacing. The native tool component consumes it after the renderers return their components, so `lastComponent` reuse and renderer ownership are preserved. HTML export ignores `shell`; it never changes tool execution or the model-facing tool declaration. An explicit `renderShell: "self"` always remains tool-owned and is not wrapped by a distribution shell.
+
 ### MCP servers
 
 `pi.registerMcpServer(name, config)` adds an MCP server for the current session. `config` has the shape of an `mcpServers` entry in [`mcp.json`](mcp.md): `command`, `args`, `env`, and `cwd` for stdio servers, `url`, `headers`, and `oauth` for HTTP servers, plus `exposure`, `toolExposure`, `description`, `enabled`, and `timeout`.

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
 	"name": "@astralyn/pi",
-	"version": "1.4.0",
+	"version": "1.4.2",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@astralyn/pi",
-			"version": "1.4.0",
+			"version": "1.4.2",
 			"license": "MIT",
 			"dependencies": {
 				"@earendil-works/pi-agent-core": "1.4.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@astralyn/pi",
-	"version": "1.4.0",
+	"version": "1.4.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {