@bastani/atomic 0.8.27 → 0.8.28-alpha.2

package/docs/compaction.md

@@ -1,32 +1,54 @@
 # Compaction & Branch Summarization
 
-LLMs have limited context windows. When conversations grow too long, Atomic's default compaction path uses **Verbatim Compaction**: it deletes safe older transcript objects while preserving every retained object exactly as it was recorded. This page covers default auto/manual compaction, legacy summary compaction internals, and branch summarization.
+LLMs have limited context windows. When conversations grow too long, Atomic's compaction behavior uses **Verbatim Compaction**: it deletes safe older transcript objects while preserving every retained object exactly as it was recorded. This page covers default auto/manual compaction, how it compares to the retired legacy summary compaction, and branch summarization.
 
-Atomic's default compaction design and terminology are informed by Morph's Context Compaction work: [Morph's Context Compaction](https://www.morphllm.com/context-compaction). Atomic follows the same core idea that coding agents often benefit more from deleting low-signal context than from rewriting high-signal details like file paths, line numbers, commands, and error strings into a lossy summary.
+Atomic's compaction design and terminology are informed by Morph's Context Compaction work: [Morph's Context Compaction](https://www.morphllm.com/context-compaction). Atomic follows the same core idea that coding agents often benefit more from deleting low-signal context than from rewriting high-signal details like file paths, line numbers, commands, and error strings into a lossy summary.
 
 **Source files** ([atomic](https://github.com/bastani-inc/atomic)):
 
 - [`packages/coding-agent/src/core/compaction/context-compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/context-compaction.ts) - Verbatim Compaction planner, transcript tools, validation, and prompt
-- [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Legacy summary compaction logic and shared threshold helpers
 - [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
 - [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`ContextCompactionEntry`, `CompactionEntry`, `BranchSummaryEntry`) and active-context rebuild logic
+- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`ContextCompactionEntry`, `BranchSummaryEntry`) and active-context rebuild logic
 - [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
 
 For TypeScript definitions in your project, inspect `node_modules/@bastani/atomic/dist/`.
 
 ## Overview
 
-Atomic has three compaction/summarization mechanisms:
+Atomic has one context compaction behavior and one separate branch-summarization mechanism:
 
 | Mechanism | Trigger | Purpose |
 |-----------|---------|---------|
-| Verbatim Compaction (default context compaction) | Context exceeds threshold, context overflow, or `/compact` | Delete safe old transcript entries/content blocks while retaining surviving content verbatim |
-| Summary compaction internals | Legacy core APIs and legacy extension hooks | Summarize old messages into replacement context |
+| Verbatim Compaction (context compaction) | Context exceeds threshold, context overflow, or `/compact` | Delete safe old transcript entries/content blocks while retaining surviving content verbatim |
 | Branch summarization | `/tree` navigation | Preserve useful context when switching branches |
 
+Summary compaction — the earlier behavior that generated replacement prose — has been removed as an active runtime path. Historical JSONL lines with `type:"compaction"` remain readable on disk but are not injected into active LLM context. See [Legacy Summary Compaction (Retired)](#legacy-summary-compaction-retired) for a comparison and historical reference.
+
 `/compact` has no user-facing arguments. It uses a fixed internal prompt, transcript-bound inspection/deletion tools, local validation, and a `context_compaction` session entry. Auto-compaction uses the same deletion-only path.
 
+## Verbatim vs. Summary Compaction
+
+Atomic uses Verbatim Compaction as its sole compaction strategy. The following comparison explains why, and documents what legacy summary compaction used to do.
+
+| Property | Verbatim Compaction | Summary Compaction (retired) |
+|----------|---------------------|------------------------------|
+| Mechanism | Deletes entries/content blocks | Rewrites earlier context into new prose |
+| Surviving content | Exact original transcript content | Generated summary text |
+| File paths / commands / errors | Kept exact or deleted | Can be paraphrased or omitted |
+| Line numbers and stack traces | Kept exact or deleted | Can be distorted in summary |
+| Auditability | Deleted targets are listed and inspectable | Omission/paraphrase is hard to audit |
+| Recoverability | Pre-compaction backup snapshot; deleted targets listed in entry | Generated summary cannot be losslessly reversed |
+| Failure mode | Needed context may be deleted (mitigated by validation and backups) | Needed context may be silently distorted |
+| Atomic end state | **Canonical behavior** | **Removed runtime behavior** |
+
+Coding agents depend on exact file paths (`src/foo.ts:42`), exact commands (`npm run build`), exact error strings, and exact line numbers. A generated summary that says "an error occurred in the auth module" instead of recording the actual stack trace loses irreplaceable information. Deletion is honest: what remains is unchanged, and what was deleted is listed in an inspectable `context_compaction` entry.
+
+Deletion can still lose needed context. Atomic mitigates this with:
+- **Local validation**: Protected entries (user tasks, recent context, unresolved errors, failed commands) cannot be deleted in standard mode.
+- **Pre-compaction backups**: A `.compact.bak` snapshot is written before each compaction for persisted sessions.
+- **Auditable targets**: The `context_compaction` entry records every deleted entry/content-block ID.
+
 ## Default Context Compaction (Verbatim Compaction)
 
 ### What "Verbatim" Means
@@ -36,7 +58,7 @@ Verbatim Compaction never asks a model to rewrite the conversation for the main
 - **Whole entries** such as an old assistant message or obsolete tool result.
 - **Individual content blocks** inside a multi-block message, such as one stale tool call block while keeping other blocks.
 
-Atomic records those targets in an append-only `context_compaction` entry. When the active branch is rebuilt, Atomic filters the targeted objects out and reuses every retained entry/content block unchanged. There is no generated summary, no paraphrasing, and no replacement message inserted by default.
+Atomic records those targets in an append-only `context_compaction` entry. When the active branch is rebuilt, Atomic filters the targeted objects out and reuses every retained entry/content block unchanged. There is no generated summary, no paraphrasing, and no replacement message inserted.
 
 The raw session JSONL remains append-only. Deleted objects stay available in the stored session file and backup snapshot; they are only omitted from future active LLM context on that branch.
 
@@ -50,11 +72,34 @@ contextTokens > contextWindow - reserveTokens
 
 By default, `reserveTokens` is 16384 tokens. Configure it in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json`; legacy `.pi` paths are also supported. This leaves room for the LLM's response.
 
-You can also trigger compaction manually with `/compact`. Custom summary instructions are no longer accepted because default compaction is deletion-only and retained transcript content stays verbatim.
+You can also trigger compaction manually with `/compact`. Custom summary instructions are not accepted because Verbatim Compaction is deletion-only and retained transcript content stays verbatim.
 
 ### How It Works
 
-1. **Collect active branch context.** Atomic walks the current session branch, applies any earlier `context_compaction` logical deletions, and respects legacy summary-compaction boundaries if they exist.
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+flowchart TD
+    A["🗣 /compact · auto-threshold · auto-overflow"]
+    B["collect active branch context\napply prior context_compaction deletions"]
+    C["build compactable transcript\n(entry IDs · roles · token estimates · text)"]
+    D["mark protected context\n(user tasks · recent 5 entries · errors · failed commands)"]
+    E["write temporary transcript file\nsend manifest to planner"]
+    F["internal deletion planner\nfixed prompt · lowest thinking level"]
+    G["transcript-bound tools\ncontext_search · context_read · context_delete · context_grep_delete"]
+    H["validateContextDeletionRequest()\nlocal airlock: unknown · protected · orphaning · empty checks"]
+    I["write pre-compaction backup snapshot"]
+    J["appendContextCompaction()\ndeletedTargets · protectedEntryIds · stats · backupPath"]
+    K["buildSessionContext()\nfilter deleted targets · reuse survivors verbatim"]
+    L["emit session_compact event\nContextCompactionResult · contextCompactionEntry"]
+
+    A --> B --> C --> D --> E --> F
+    F <--> G
+    G --> H
+    H -->|validated| I --> J --> K --> L
+    H -->|rejected| F
+```
+
+1. **Collect active branch context.** Atomic walks the current session branch and applies any earlier `context_compaction` logical deletions.
 2. **Build a compactable transcript.** Each compactable entry includes a stable `entryId`, role, token estimate, full text, content-block indexes, tool-call IDs, and tool-result links.
 3. **Mark protected context.** Standard compaction protects user instructions, custom messages, branch/summary messages, the last five context-eligible entries, unresolved assistant/tool errors, and failed bash executions.
 4. **Write a temporary transcript file.** The compaction assistant receives a compact manifest plus the path to a JSONL transcript file. It should inspect with tools instead of loading the whole transcript into prompt context.
@@ -82,7 +127,7 @@ Tool calls are cumulative during one compaction run. The assistant can apply sev
 In standard mode, Atomic protects:
 
 - User messages and user-provided task context.
-- Custom messages, branch summaries, and existing summary-compaction messages.
+- Custom messages, branch summaries, and branch-summary context.
 - The last five context-eligible entries on the active branch.
 - Assistant messages whose stop reason is an error.
 - Tool results marked as errors.
@@ -172,111 +217,80 @@ No generated summary is inserted. Every surviving entry/content block is reused
 verbatim; deleted objects are simply omitted from the active LLM context.
 ```
 
-## Summary Compaction Internals
+## Extension Hooks for Compaction
 
-The older summarization pipeline still exists in the core compaction module and for legacy extension hook types, but `/compact` and auto-compaction no longer use it by default.
+Extensions can observe, cancel, or contribute exact deletion targets to the compaction pipeline. They cannot provide generated summaries.
 
-```text
-Before summary compaction:
+### session_before_compact
 
-  entry:  0     1     2     3      4     5     6      7      8     9
-        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┐
-        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
-        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
-                └────────┬───────┘ └──────────────┬──────────────┘
-               messagesToSummarize            kept messages
-                                   ↑
-                          firstKeptEntryId (entry 4)
+Fired before the internal deletion planner runs. Extensions can cancel compaction or provide their own validated deletion request.
 
-After compaction (new entry appended):
+```typescript
+pi.on("session_before_compact", async (event, ctx) => {
+  const { preparation, branchEntries, reason, mode, signal } = event;
 
-  entry:  0     1     2     3      4     5     6      7      8     9     10
-        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
-        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
-        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
-               └──────────┬──────┘ └──────────────────────┬───────────────────┘
-                 not sent to LLM                    sent to LLM
-                                                         ↑
-                                              starts from firstKeptEntryId
+  // preparation.transcript.entries - entries eligible for deletion
+  // preparation.transcript.protectedEntryIds - entries that cannot be deleted in standard mode
+  // preparation.transcript.tokensBefore - context token estimate before compaction
+  // branchEntries - all entries on current branch
+  // reason - "manual" | "threshold" | "overflow"
+  // mode - "standard" | "critical_overflow"
 
-What the LLM sees:
+  // Cancel compaction:
+  return { cancel: true };
 
-  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
-  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
-  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
-       ↑         ↑      └─────────────────┬────────────────┘
-    prompt   from cmp          messages from firstKeptEntryId
+  // Or provide a deletion request (Atomic validates it locally before persisting):
+  return {
+    deletionRequest: {
+      deletions: [
+        { kind: "entry", entryId: "abc123" },
+        { kind: "content_block", entryId: "def456", blockIndex: 2 },
+      ],
+    },
+  };
+});
 ```
 
-On repeated legacy summary compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Atomic also recalculates `tokensBefore` from the rebuilt session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced.
-
-### Split Turns
+If `{ cancel: true }` is returned, compaction aborts with a cancellation error. If `{ deletionRequest }` is returned, Atomic validates it through the same local airlock as model-proposed deletions — unknown IDs, protected targets, orphaning, and empty-context plans are rejected — and skips the internal planner. If nothing is returned, the internal planner runs normally.
 
-A "turn" starts with a user message and includes all assistant responses and tool calls until the next user message. The legacy summary pipeline normally cuts at turn boundaries.
+### session_compact
 
-When a single turn exceeds `keepRecentTokens`, the cut point lands mid-turn at an assistant message. This is a "split turn":
+Fired after compaction succeeds and the `context_compaction` entry is persisted.
 
-```text
-Split turn (one huge turn exceeds budget):
-
-  entry:  0     1     2      3     4      5      6     7      8
-        ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬──────┐
-        │ hdr │ usr │ ass │ tool │ ass │ tool │ tool │ ass │ tool │
-        └─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┴──────┘
-                ↑                                     ↑
-         turnStartIndex = 1                  firstKeptEntryId = 7
-                │                                     │
-                └──── turnPrefixMessages (1-6) ───────┘
-                                                      └── kept (7-8)
-
-  isSplitTurn = true
-  messagesToSummarize = []  (no complete turns before)
-  turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
+```typescript
+pi.on("session_compact", async (event, ctx) => {
+  // event.result - ContextCompactionResult
+  // event.contextCompactionEntry - the saved ContextCompactionEntry
+  // event.reason - "manual" | "threshold" | "overflow"
+  // event.fromExtension - true if extension provided the deletionRequest
+
+  const { result } = event;
+  ctx.ui.notify(
+    `Compaction: deleted ${result.stats.objectsDeleted} objects, ` +
+    `${result.stats.percentReduction}% token reduction`,
+    "info",
+  );
+});
 ```
 
-For split turns, Atomic generates two summaries and merges them:
-
-1. **History summary**: Previous context (if any)
-2. **Turn prefix summary**: The early part of the split turn
-
-### Cut Point Rules
-
-Valid legacy summary-compaction cut points are:
+### ctx.compact()
 
-- User messages
-- Assistant messages
-- BashExecution messages
-- Custom messages (custom_message, branch_summary)
-
-Never cut at tool results because they must stay with their tool call.
-
-### CompactionEntry Structure
-
-Defined in [`session-manager.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/session-manager.ts):
+Trigger Verbatim Compaction without awaiting completion. See [Extensions](/extensions) for full `ctx.compact()` documentation.
 
 ```typescript
-interface CompactionEntry<T = unknown> {
-  type: "compaction";
-  id: string;
-  parentId: string | null;
-  timestamp: string;  // ISO timestamp
-  summary: string;
-  firstKeptEntryId: string;
-  tokensBefore: number;
-  fromHook?: boolean;  // true if provided by extension (legacy field name)
-  details?: T;         // implementation-specific data
-}
-
-// Legacy summary compaction uses this for details (from compaction.ts):
-interface CompactionDetails {
-  readFiles: string[];
-  modifiedFiles: string[];
-}
+ctx.compact({
+  onComplete: (result) => {
+    ctx.ui.notify(`Compacted: deleted ${result.stats.objectsDeleted} objects`, "info");
+  },
+  onError: (error) => {
+    ctx.ui.notify(`Compaction failed: ${error.message}`, "error");
+  },
+});
 ```
 
-Extensions can store any JSON-serializable data in `details`. The legacy summary compaction pipeline tracks file operations, but custom extension implementations can use their own structure.
+`ctx.compact()` does not accept custom instructions. Verbatim Compaction uses a fixed internal prompt; no custom summary text can be injected.
 
-See [`prepareCompaction()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) for the implementation.
+See [examples/extensions/trigger-compact.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/trigger-compact.ts) for a full example.
 
 ## Branch Summarization
 
@@ -284,6 +298,8 @@ See [`prepareCompaction()`](https://github.com/bastani-inc/atomic/blob/main/pack
 
 When you use `/tree` to navigate to a different branch, Atomic offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
 
+Branch summarization is a separate mechanism from context compaction. It generates a summary of the abandoned branch path and injects it into the new branch position. This is appropriate here because the alternative (losing branch context entirely on navigation) is worse than a lossy summary.
+
 ### How It Works
 
 1. **Find common ancestor**: Deepest node shared by old and new positions
@@ -292,6 +308,20 @@ When you use `/tree` to navigate to a different branch, Atomic offers to summari
 4. **Generate summary**: Call LLM with structured format
 5. **Append entry**: Save `BranchSummaryEntry` at navigation point
 
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#f8f9fa','primaryTextColor':'#2c3e50','primaryBorderColor':'#4a5568','lineColor':'#4a90e2','secondaryColor':'#ffffff','tertiaryColor':'#e9ecef'}}}%%
+flowchart TD
+    A["user navigates /tree\nold leaf → new target"]
+    B["find common ancestor"]
+    C["collect abandoned branch entries\n(old leaf → common ancestor)"]
+    D["prepare with token budget\n(newest first)"]
+    E["generate branch summary\nLLM call · structured format"]
+    F["append BranchSummaryEntry\nat common ancestor or new target"]
+    G["navigate to new target\nbranch summary context carried forward"]
+
+    A --> B --> C --> D --> E --> F --> G
+```
+
 ```text
 Tree before navigation:
 
@@ -311,12 +341,12 @@ After navigation with summary:
 
 ### Cumulative File Tracking
 
-Legacy summary compaction and branch summarization track files cumulatively. When generating a summary, Atomic extracts file operations from:
+Branch summarization tracks files cumulatively. When generating a summary, Atomic extracts file operations from:
 
 - Tool calls in the messages being summarized
-- Previous compaction or branch summary `details` (if any)
+- Previous branch summary `details` (if any)
 
-This means file tracking accumulates across multiple summary compactions or nested branch summaries, preserving the full history of read and modified files.
+This means file tracking accumulates across nested branch summaries, preserving the full history of read and modified files.
 
 ### BranchSummaryEntry Structure
 
@@ -341,13 +371,13 @@ interface BranchSummaryDetails {
 }
 ```
 
-Same as legacy summary compaction, extensions can store custom data in `details`.
+Extensions can store custom data in `details`.
 
 See [`collectEntriesForBranchSummary()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) for the implementation.
 
-## Legacy Summary Format
+## Branch Summary Format
 
-Legacy summary compaction and branch summarization use the same structured format:
+Branch summarization uses a structured format:
 
 ```markdown
 ## Goal
@@ -385,9 +415,9 @@ path/to/changed.ts
 </modified-files>
 ```
 
-### Message Serialization
+### Message Serialization for Branch Summaries
 
-Before legacy summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+Before branch summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
 
 ```text
 [User]: What they said
@@ -399,81 +429,9 @@ Before legacy summarization, messages are serialized to text via [`serializeConv
 
 This prevents the model from treating it as a conversation to continue.
 
-Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated. This keeps summarization requests within reasonable token budgets, since tool results (especially from `read` and `bash`) are typically the largest contributors to context size.
+Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated.
 
-## Custom Summarization via Extensions
-
-Extensions can still customize the legacy summary compaction pipeline and branch summarization. Default `/compact` and auto-compaction use deletion-only Verbatim Compaction and do not call summary customization hooks. See [`extensions/types.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
-
-### session_before_compact
-
-Fired before legacy summary compaction. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
-
-```typescript
-pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation, branchEntries, customInstructions, signal } = event;
-
-  // preparation.messagesToSummarize - messages to summarize
-  // preparation.turnPrefixMessages - split turn prefix (if isSplitTurn)
-  // preparation.previousSummary - previous compaction summary
-  // preparation.fileOps - extracted file operations
-  // preparation.tokensBefore - context tokens before compaction
-  // preparation.firstKeptEntryId - where kept messages start
-  // preparation.settings - compaction settings
-
-  // branchEntries - all entries on current branch (for custom state)
-  // signal - AbortSignal (pass to LLM calls)
-
-  // Cancel:
-  return { cancel: true };
-
-  // Custom summary:
-  return {
-    compaction: {
-      summary: "Your summary...",
-      firstKeptEntryId: preparation.firstKeptEntryId,
-      tokensBefore: preparation.tokensBefore,
-      details: { /* custom data */ },
-    }
-  };
-});
-```
-
-#### Converting Messages to Text
-
-To generate a summary with your own model, convert messages to text using `serializeConversation`:
-
-```typescript
-import { convertToLlm, serializeConversation } from "@bastani/atomic";
-
-pi.on("session_before_compact", async (event, ctx) => {
-  const { preparation } = event;
-  
-  // Convert AgentMessage[] to Message[], then serialize to text
-  const conversationText = serializeConversation(
-    convertToLlm(preparation.messagesToSummarize)
-  );
-  // Returns:
-  // [User]: message text
-  // [Assistant thinking]: thinking content
-  // [Assistant]: response text
-  // [Assistant tool calls]: read(path="..."); bash(command="...")
-  // [Tool result]: output text
-
-  // Now send to your model for summarization
-  const summary = await myModel.summarize(conversationText);
-  
-  return {
-    compaction: {
-      summary,
-      firstKeptEntryId: preparation.firstKeptEntryId,
-      tokensBefore: preparation.tokensBefore,
-    }
-  };
-});
-```
-
-See [custom-compaction.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/custom-compaction.ts) for a complete example using a different model.
+## Extension Hooks for Branch Summarization
 
 ### session_before_tree
 
@@ -514,8 +472,7 @@ Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomi
 {
   "compaction": {
     "enabled": true,
-    "reserveTokens": 16384,
-    "keepRecentTokens": 20000
+    "reserveTokens": 16384
   }
 }
 ```
@@ -524,6 +481,78 @@ Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomi
 |---------|---------|-------------|
 | `enabled` | `true` | Enable automatic Verbatim Compaction. |
 | `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; auto-compaction starts when context usage exceeds `contextWindow - reserveTokens`. |
-| `keepRecentTokens` | `20000` | Legacy summary-compaction retained-token budget. Default Verbatim Compaction protects recent entries structurally instead of using this as a token cut point. |
 
 Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
+
+## Legacy Summary Compaction (Retired)
+
+Summary compaction — an earlier behavior that generated replacement prose for older context — has been removed as an active runtime path in Atomic. This section documents it for historical reference only.
+
+### What it did
+
+The summary compaction pipeline:
+1. Selected a cut point (user message boundary) called `firstKeptEntryId`.
+2. Passed all messages before that cut point to an LLM to generate a replacement summary.
+3. Appended a `CompactionEntry` with `type:"compaction"` to the session JSONL.
+4. When rebuilding active context, injected a `compactionSummary` message at the boundary.
+
+```text
+(Historical — no longer the active behavior)
+
+Before summary compaction:
+
+  entry:  0     1     2     3      4     5     6      7      8     9
+        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
+                └────────┬───────┘ └──────────────┬──────────────┘
+               messagesToSummarize            kept messages
+                                   ↑
+                          firstKeptEntryId (entry 4)
+
+After compaction (new entry appended):
+
+  entry:  0     1     2     3      4     5     6      7      8     9     10
+        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
+               └──────────┬──────┘ └──────────────────────┬───────────────────┘
+                 not sent to LLM                    sent to LLM
+                                                         ↑
+                                              starts from firstKeptEntryId
+
+What the LLM saw:
+
+  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
+  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
+  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
+       ↑         ↑      └─────────────────┬────────────────┘
+    prompt   from cmp          messages from firstKeptEntryId
+```
+
+### Why it was removed
+
+The core problem: a generated summary can paraphrase or omit exact file paths (`src/auth/middleware.ts:87`), commands (`npm run build -- --watch`), error strings, and line numbers. For coding agents, this loss of precision frequently causes confusion and regressions. Verbatim Compaction is honest: what remains is unchanged, and what was deleted is recorded.
+
+See [Verbatim vs. Summary Compaction](#verbatim-vs-summary-compaction) for the full comparison.
+
+### Historical entry types
+
+`type:"compaction"` JSONL lines may exist in sessions created before the removal. They remain readable on disk and visible in session exports, but Atomic does not inject them as active LLM context. If you encounter sessions with these entries, they are safe to leave in place.
+
+`type:"compaction"` entry structure (historical):
+```typescript
+interface CompactionEntry {
+  type: "compaction";
+  id: string;
+  parentId: string | null;
+  timestamp: string;
+  summary: string;           // generated replacement prose
+  firstKeptEntryId: string;  // cut point boundary
+  tokensBefore: number;
+  fromHook?: boolean;
+  details?: unknown;
+}
+```
+
+This entry type is no longer produced by Atomic. Extension hooks that returned `{ compaction: { summary, firstKeptEntryId, tokensBefore } }` no longer have effect; update extensions to use the new `{ cancel: true }` or `{ deletionRequest }` hook returns instead.

package/docs/containerization.md

@@ -0,0 +1,111 @@
+# Containerization
+
+Atomic runs with all permissions by default, but in some cases, you will want to have more control over what directories Atomic can write to and which accesses it has.
+
+There are two general options. You can either
+1. run the whole `atomic` process inside an isolated environment, or
+2. run `atomic` on the host and route tool execution into an isolated environment.
+
+## Choose a pattern
+
+| Pattern | What is isolated | Best for | Notes |
+| --- | --- | --- | --- |
+| OpenShell | Whole `atomic` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
+| Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | See [`examples/extensions/gondolin/`](https://github.com/bastani-inc/atomic/tree/main/packages/coding-agent/examples/extensions/gondolin). |
+| Plain Docker | Whole `atomic` process in a local container | Simple local isolation | Provider API keys enter the container. |
+
+Extensions run wherever the `atomic` process runs. If you run host `atomic` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
+
+## OpenShell
+
+Use [NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) when you want a policy-controlled sandbox with filesystem, process, network, credential, and inference controls.
+OpenShell can run sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway.
+
+Every sandbox requires an active gateway.
+Register and select one before creating a sandbox:
+
+```bash
+openshell gateway add <gateway-url> --name <name>
+openshell gateway select <name>
+```
+
+Launch `atomic` inside an OpenShell sandbox:
+
+```bash
+openshell sandbox create --name atomic-sandbox --from atomic -- atomic
+```
+
+In this pattern, the whole `atomic` process runs inside the sandbox.
+Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary.
+
+If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine.
+Clone the repository inside the sandbox or use OpenShell file transfer commands:
+
+```bash
+openshell sandbox upload atomic-sandbox ./repo /workspace
+openshell sandbox download atomic-sandbox /workspace/repo ./repo-out
+```
+
+OpenShell providers can keep raw model API keys outside the sandbox.
+When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream.
+Configure Atomic to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.
+
+## Gondolin
+
+[Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
+Use the [example extension](https://github.com/bastani-inc/atomic/tree/main/packages/coding-agent/examples/extensions/gondolin) when you want `atomic` on the host but all built-in tools routed into the VM.
+
+Setup:
+
+```bash
+cp -R packages/coding-agent/examples/extensions/gondolin ~/.atomic/agent/extensions/gondolin
+cd ~/.atomic/agent/extensions/gondolin
+npm install --ignore-scripts
+```
+
+Run from the project you want mounted:
+
+```bash
+cd /path/to/project
+atomic -e ~/.atomic/agent/extensions/gondolin
+```
+
+The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.
+User `!` commands are routed into the VM, as well.
+File changes under `/workspace` write through to the host.
+
+Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU (requires installation through your package manager).
+
+## Plain Docker
+
+Run the whole `atomic` process in Docker when you want the simplest local container boundary.
+
+`Dockerfile.atomic`:
+
+```dockerfile
+FROM node:24-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
+  && rm -rf /var/lib/apt/lists/*
+RUN npm install -g --ignore-scripts @bastani/atomic
+
+WORKDIR /workspace
+ENTRYPOINT ["atomic"]
+```
+
+Build and run:
+
+```bash
+docker build -t atomic-sandbox -f Dockerfile.atomic .
+
+docker run --rm -it \
+  -e ANTHROPIC_API_KEY \
+  -v "$PWD:/workspace" \
+  -v atomic-agent-home:/root/.atomic/agent \
+  atomic-sandbox
+```
+
+The `-v "$PWD:/workspace"` mounts your current directory into the container at /workspace such that reads and writes in `/workspace` inside Docker directly affect your host files, like in the Gondolin example.
+
+Use a named volume for `/root/.atomic/agent` if you want container-local settings and sessions. Mounting your host `~/.atomic/agent` exposes host auth and session files to the container.