@m4ike1/ion-coding-agent 0.1.0

package/dist/utils/windows-self-update.js

@@ -0,0 +1,77 @@
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, toNamespacedPath } from "node:path";
+import { getCwdRelativePath } from "./paths.js";
+const QUARANTINE_DIR_NAME = ".ion-native-quarantine";
+function normalizePath(path) {
+    return toNamespacedPath(resolve(path));
+}
+function getQuarantineRoot(packageDir) {
+    let current = resolve(packageDir);
+    while (true) {
+        if (basename(current).toLowerCase() === "node_modules") {
+            return join(current, QUARANTINE_DIR_NAME);
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+function getLoadedSharedObjectsInPackageDir(packageDir) {
+    const sharedObjects = process.report.getReport().sharedObjects;
+    if (!Array.isArray(sharedObjects)) {
+        return [];
+    }
+    const root = normalizePath(packageDir).toLowerCase();
+    const seen = new Set();
+    const loadedFiles = [];
+    for (const value of sharedObjects) {
+        if (typeof value !== "string") {
+            continue;
+        }
+        const filePath = normalizePath(value);
+        const comparisonPath = filePath.toLowerCase();
+        if (getCwdRelativePath(comparisonPath, root) === undefined || seen.has(comparisonPath)) {
+            continue;
+        }
+        seen.add(comparisonPath);
+        loadedFiles.push(filePath);
+    }
+    return loadedFiles;
+}
+export function cleanupWindowsSelfUpdateQuarantine(packageDir) {
+    const quarantineRoot = getQuarantineRoot(packageDir);
+    if (!quarantineRoot) {
+        return;
+    }
+    try {
+        rmSync(quarantineRoot, { recursive: true, force: true });
+    }
+    catch {
+        // A previous ion process may still be exiting and holding a native addon.
+    }
+}
+export function quarantineWindowsNativeDependencies(packageDir) {
+    const resolvedPackageDir = normalizePath(packageDir);
+    const quarantineRoot = getQuarantineRoot(resolvedPackageDir);
+    if (!quarantineRoot) {
+        return;
+    }
+    const loadedFiles = getLoadedSharedObjectsInPackageDir(resolvedPackageDir);
+    if (loadedFiles.length === 0) {
+        return;
+    }
+    const quarantineRunDir = join(quarantineRoot, `${Date.now()}-${process.pid}-${randomUUID()}`);
+    for (const loadedFile of loadedFiles) {
+        if (!existsSync(loadedFile)) {
+            continue;
+        }
+        const quarantinePath = join(quarantineRunDir, relative(resolvedPackageDir, loadedFile));
+        mkdirSync(dirname(quarantinePath), { recursive: true });
+        renameSync(loadedFile, quarantinePath);
+        copyFileSync(quarantinePath, loadedFile);
+    }
+}
+//# sourceMappingURL=windows-self-update.js.map

package/dist/utils/windows-self-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-self-update.js","sourceRoot":"","sources":["../../src/utils/windows-self-update.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACzF,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAErD,SAAS,aAAa,CAAC,IAAY,EAAU;IAC5C,OAAO,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAAA,CACvC;AAED,SAAS,iBAAiB,CAAC,UAAkB,EAAsB;IAClE,IAAI,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC,OAAO,IAAI,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,cAAc,EAAE,CAAC;YACxD,OAAO,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACxB,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IAClB,CAAC;AAAA,CACD;AAED,SAAS,kCAAkC,CAAC,UAAkB,EAAY;IACzE,MAAM,aAAa,GAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAkC,CAAC,aAAa,CAAC;IAChG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,IAAI,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,SAAS;QACV,CAAC;QACD,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,cAAc,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC9C,IAAI,kBAAkB,CAAC,cAAc,EAAE,IAAI,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;YACxF,SAAS;QACV,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACzB,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,WAAW,CAAC;AAAA,CACnB;AAED,MAAM,UAAU,kCAAkC,CAAC,UAAkB,EAAQ;IAC5E,MAAM,cAAc,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACrD,IAAI,CAAC,cAAc,EAAE,CAAC;QACrB,OAAO;IACR,CAAC;IACD,IAAI,CAAC;QACJ,MAAM,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACR,0EAA0E;IAC3E,CAAC;AAAA,CACD;AAED,MAAM,UAAU,mCAAmC,CAAC,UAAkB,EAAQ;IAC7E,MAAM,kBAAkB,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACrD,MAAM,cAAc,GAAG,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;IAC7D,IAAI,CAAC,cAAc,EAAE,CAAC;QACrB,OAAO;IACR,CAAC;IAED,MAAM,WAAW,GAAG,kCAAkC,CAAC,kBAAkB,CAAC,CAAC;IAC3E,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO;IACR,CAAC;IAED,MAAM,gBAAgB,GAAG,IAAI,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,EAAE,CAAC,CAAC;IAC9F,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7B,SAAS;QACV,CAAC;QACD,MAAM,cAAc,GAAG,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC,CAAC;QACxF,SAAS,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,UAAU,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;QACvC,YAAY,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;AAAA,CACD","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { copyFileSync, existsSync, mkdirSync, renameSync, rmSync } from \"node:fs\";\nimport { basename, dirname, join, relative, resolve, toNamespacedPath } from \"node:path\";\nimport { getCwdRelativePath } from \"./paths.ts\";\n\nconst QUARANTINE_DIR_NAME = \".ion-native-quarantine\";\n\nfunction normalizePath(path: string): string {\n\treturn toNamespacedPath(resolve(path));\n}\n\nfunction getQuarantineRoot(packageDir: string): string | undefined {\n\tlet current = resolve(packageDir);\n\twhile (true) {\n\t\tif (basename(current).toLowerCase() === \"node_modules\") {\n\t\t\treturn join(current, QUARANTINE_DIR_NAME);\n\t\t}\n\t\tconst parent = dirname(current);\n\t\tif (parent === current) {\n\t\t\treturn undefined;\n\t\t}\n\t\tcurrent = parent;\n\t}\n}\n\nfunction getLoadedSharedObjectsInPackageDir(packageDir: string): string[] {\n\tconst sharedObjects = (process.report.getReport() as { sharedObjects?: unknown }).sharedObjects;\n\tif (!Array.isArray(sharedObjects)) {\n\t\treturn [];\n\t}\n\n\tconst root = normalizePath(packageDir).toLowerCase();\n\tconst seen = new Set<string>();\n\tconst loadedFiles: string[] = [];\n\tfor (const value of sharedObjects) {\n\t\tif (typeof value !== \"string\") {\n\t\t\tcontinue;\n\t\t}\n\t\tconst filePath = normalizePath(value);\n\t\tconst comparisonPath = filePath.toLowerCase();\n\t\tif (getCwdRelativePath(comparisonPath, root) === undefined || seen.has(comparisonPath)) {\n\t\t\tcontinue;\n\t\t}\n\t\tseen.add(comparisonPath);\n\t\tloadedFiles.push(filePath);\n\t}\n\treturn loadedFiles;\n}\n\nexport function cleanupWindowsSelfUpdateQuarantine(packageDir: string): void {\n\tconst quarantineRoot = getQuarantineRoot(packageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\ttry {\n\t\trmSync(quarantineRoot, { recursive: true, force: true });\n\t} catch {\n\t\t// A previous ion process may still be exiting and holding a native addon.\n\t}\n}\n\nexport function quarantineWindowsNativeDependencies(packageDir: string): void {\n\tconst resolvedPackageDir = normalizePath(packageDir);\n\tconst quarantineRoot = getQuarantineRoot(resolvedPackageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\n\tconst loadedFiles = getLoadedSharedObjectsInPackageDir(resolvedPackageDir);\n\tif (loadedFiles.length === 0) {\n\t\treturn;\n\t}\n\n\tconst quarantineRunDir = join(quarantineRoot, `${Date.now()}-${process.pid}-${randomUUID()}`);\n\tfor (const loadedFile of loadedFiles) {\n\t\tif (!existsSync(loadedFile)) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst quarantinePath = join(quarantineRunDir, relative(resolvedPackageDir, loadedFile));\n\t\tmkdirSync(dirname(quarantinePath), { recursive: true });\n\t\trenameSync(loadedFile, quarantinePath);\n\t\tcopyFileSync(quarantinePath, loadedFile);\n\t}\n}\n"]}

package/docs/browser-extension.md

@@ -0,0 +1,108 @@
+# Browser extension: design
+
+Status: **design only.** No extension code ships yet. See [Why there is no code](#why-there-is-no-code) before treating any of this as a plan to execute.
+
+## What it would do
+
+Capture the page you are looking at and hand it to ion, so that asking about "this" does not require you to switch windows, copy a URL, and describe what you saw.
+
+One flow, one direction:
+
+1. You click the toolbar button on a page.
+2. ion captures a bounded snapshot: URL, page title, selected text if any, and optionally readable text content of the main document.
+3. You choose a destination (clipboard, or a file you pick).
+4. You switch to ion and paste or reference it.
+
+The extension never talks to ion directly, never runs agent logic, and never receives model output.
+
+## Explicitly out of scope
+
+- **No page automation.** The extension does not click, type, scroll, or evaluate anything in the page. It is a reader, not a driver.
+- **No two-way bridge.** A version that lets ion act on the live page is a different product with a different threat model; see [Open questions](#open-questions).
+- **No background activity.** No content scripts on navigation, no timers, no service worker that wakes on a schedule. It runs when you click it, and not otherwise.
+- **No telemetry, no analytics, no update pings.**
+
+## Threat model
+
+The extension reads content from every site you visit, which makes it a high-value target. The design keeps the blast radius small by minimising authority rather than by trusting the code.
+
+### What it must never be able to do
+
+| Never | Why |
+|---|---|
+| Read a tab you are not looking at | `activeTab` is granted only on explicit click, for that tab only. No `tabs` permission, no host permissions. |
+| Read page content without a click | No declarative content scripts, no `content_scripts` match patterns. Injection happens on demand, in the active tab. |
+| Send data anywhere | No `host_permissions`, no `connect-src`. The manifest grants no network reach at all, so exfiltration is not a code-level possibility, it is a manifest-level impossibility. |
+| Load or evaluate remote code | MV3 forbids it. Also: no CDN imports, no dynamic `import()` of a URL, no remote WASM. |
+| Capture credentials | Never read `input` values, never read password fields, never read cookies or `localStorage`. Snapshot text comes from the rendered document, with form controls stripped. |
+| Survive the click | No persistent state, no queues, no background retry. If the capture fails, it fails. |
+
+### What it can do, and what that costs
+
+- **Reads the active tab's visible content** — that is the product. It is bounded to one tab, on click, and the content never leaves the machine.
+- **Writes to the clipboard** — requires the `clipboardWrite` permission. A write is user-visible and does not persist beyond the clipboard.
+- **Writes a file the user selects** — uses the file picker; no directory access, no overwrite without an explicit prompt.
+
+### Redaction
+
+Before a snapshot is shown or copied, strip:
+
+- values of `input`, `textarea`, `select`, and any `[contenteditable]` region
+- `autocomplete` and `data-*` attributes that routinely carry identifiers
+- anything matching common token shapes (long high-entropy strings, `Bearer ...`)
+
+Show the user the exact text that will be captured, and require a second action to copy it. Silent capture-and-send is the failure mode this design exists to prevent.
+
+## Handoff mechanism
+
+**Recommended: clipboard first.** Zero additional attack surface. ion already accepts pasted text, so the integration is a keystroke rather than a protocol.
+
+**Alternative: a localhost bridge.** ion runs a local HTTP endpoint; the extension POSTs the snapshot to it. This buys direct handoff but adds a local server, so it needs its own hardening: bind to loopback only, reject requests without a per-session token minted by ion, enforce an origin allowlist, cap body size, and refuse to bind if the port is already taken. A bridge also creates a CSRF surface: a malicious page must not be able to drive the extension into posting arbitrary content, so the extension must not accept page-initiated messages.
+
+Do not build the bridge until the clipboard path is proven insufficient.
+
+## Manifest shape
+
+MV3, deliberately minimal. Every entry here is a permission the design cannot remove.
+
+```jsonc
+{
+  "manifest_version": 3,
+  "name": "ion capture",
+  "version": "0.0.1",
+  "description": "Capture the current page and hand it to ion.",
+  "permissions": ["activeTab", "scripting", "clipboardWrite"],
+  "action": { "default_title": "Capture page for ion" },
+  "background": { "service_worker": "service-worker.js", "type": "module" },
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'self'; connect-src 'none'"
+  }
+}
+```
+
+Notes on what is absent and must stay absent:
+
+- no `host_permissions` (this is the one that would make the extension scary)
+- no `content_scripts` block
+- no `web_accessible_resources`
+- no `externally_connectable`
+- no `tabs`, no `storage`, no `history`, no `cookies`, no `webRequest`
+- `connect-src 'none'` is the belt-and-braces version of "this extension never talks to the network"
+
+Both Chrome and Firefox ship MV3; Firefox still requires `browser_specific_settings.gecko.id` for a signed build.
+
+## Open questions
+
+These need a decision before any code is written:
+
+1. **Snapshot depth.** Title + URL + selection only (safest), or readable main-content text as well (far more useful, much more sensitive)? Recommendation: start with the first, measure whether the second is actually needed.
+2. **Readability extraction.** No bundled readability library without a dependency review; a heuristic DOM walk is simpler but much worse. Recommendation: treat this as the main technical risk, not the security model.
+3. **Bridge, ever?** See above. Recommendation: no, until proven necessary.
+4. **Distribution.** Chrome Web Store, Firefox AMO, or sideloaded only. Affects review requirements and the update story.
+5. **Retention.** Is anything written to disk, and if so, where does the user delete it? Recommendation: write nothing by default; the clipboard is the store.
+
+## Why there is no code
+
+This repository has no browser extension test infrastructure and no way to exercise a real extension in CI. Shipping an untested extension that holds `activeTab` on every site you visit would be worse than shipping nothing: it would be installed on trust and fail quietly.
+
+The design is written down so the decision is reviewable. Implementation should follow a real browser being driven by hand, with the redaction and permission rules above treated as acceptance criteria rather than suggestions.

package/docs/compaction.md

@@ -0,0 +1,444 @@
+# Compaction & Branch Summarization
+
+LLMs have limited context windows. When conversations grow too long, Ion uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
+
+**Source files** ([ion](https://github.com/maikel/ion)):
+- [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Auto-compaction logic
+- [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
+- [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/maikel/ion/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/maikel/ion/blob/main/packages/coding-agent/src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
+- [`packages/coding-agent/src/core/extensions/types.ts`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
+
+For TypeScript definitions in your project, inspect `node_modules/@m4ike1/ion-coding-agent/dist/`.
+
+## Overview
+
+Ion has two summarization mechanisms:
+
+| Mechanism | Trigger | Purpose |
+|-----------|---------|---------|
+| 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. Compaction and branch-summary requests use fresh routing session IDs and, where supported by the provider, disable prompt-cache writes because these one-off prompts are unlikely to be reused.
+
+## Compaction
+
+### When It Triggers
+
+Auto-compaction triggers when:
+
+```
+contextTokens > contextWindow - reserveTokens
+```
+
+By default, `reserveTokens` is 16384 tokens (configurable in `~/.ion/agent/settings.json` or `<project-dir>/.ion/settings.json`). This leaves room for the LLM's response.
+
+During a multi-turn agent run, Ion checks this threshold after tools finish and their results are appended, before starting the next assistant response. If the threshold is crossed, Ion compacts inside the same agent run and resumes with the summary and retained messages. It skips this between-turn check when the completed tool batch terminates the run and no queued message requires another response. Ion also checks the threshold before a new user prompt and after a low-level agent run ends.
+
+You can also trigger manually with `:compact [instructions]`, where optional instructions focus the summary.
+
+### How It Works
+
+1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.ion/agent/settings.json` or `<project-dir>/.ion/settings.json`) is reached
+2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
+3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
+4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
+5. **Rebuilds context**: Session rebuilds the context for the next request, using summary + messages from `firstKeptEntryId` onwards
+
+```
+Before 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 sees:
+
+  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
+  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
+  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
+       ↑         ↑      └─────────────────┬────────────────┘
+    prompt   from cmp          messages from firstKeptEntryId
+```
+
+On repeated 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. Ion 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
+
+A "turn" starts with a user message and includes all assistant responses and tool calls until the next user message. Normally, compaction cuts at turn boundaries.
+
+When a single turn exceeds `keepRecentTokens`, the cut point lands mid-turn at an assistant message. This is a "split turn":
+
+```
+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]
+```
+
+For split turns, Ion 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 cut points are:
+- User messages
+- Assistant messages
+- BashExecution messages
+- Custom messages (custom_message, branch_summary)
+
+Never cut at tool results (they must stay with their tool call).
+
+### CompactionEntry Structure
+
+Defined in [`session-manager.ts`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/session-manager.ts):
+
+```typescript
+interface CompactionEntry<T = unknown> {
+  type: "compaction";
+  id: string;
+  parentId: string;
+  timestamp: number;
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  usage?: Usage;       // LLM usage that generated the summary
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
+  details?: T;         // implementation-specific data
+}
+
+// Default compaction uses this for details (from compaction.ts):
+interface CompactionDetails {
+  readFiles: string[];
+  modifiedFiles: string[];
+}
+```
+
+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/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) for the implementation. For direct programmatic summarization, `generateSummary()` returns the summary text and `generateSummaryWithUsage()` returns `{ text, usage }`.
+
+## Branch Summarization
+
+### When It Triggers
+
+When you use `:tree` to navigate to a different branch, Ion offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
+
+### How It Works
+
+1. **Find common ancestor**: Deepest node shared by old and new positions
+2. **Collect entries**: Walk from old leaf back to common ancestor
+3. **Prepare with budget**: Include messages up to token budget (newest first)
+4. **Generate summary**: Call LLM with structured format
+5. **Append entry**: Save `BranchSummaryEntry` at navigation point
+
+```
+Tree before navigation:
+
+         ┌─ B ─ C ─ D (old leaf, being abandoned)
+    A ───┤
+         └─ E ─ F (target)
+
+Common ancestor: A
+Entries to summarize: B, C, D
+
+After navigation with summary:
+
+         ┌─ B ─ C ─ D
+    A ───┤
+         └─ E ─ F ─ [summary of B,C,D] (new leaf)
+```
+
+### Cumulative File Tracking
+
+Both compaction and branch summarization track files cumulatively. When generating a summary, ion extracts file operations from:
+- Tool calls in the messages being summarized
+- Previous compaction or branch summary `details` (if any)
+
+This means file tracking accumulates across multiple compactions or nested branch summaries, preserving the full history of read and modified files.
+
+### BranchSummaryEntry Structure
+
+Defined in [`session-manager.ts`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/session-manager.ts):
+
+```typescript
+interface BranchSummaryEntry<T = unknown> {
+  type: "branch_summary";
+  id: string;
+  parentId: string;
+  timestamp: number;
+  summary: string;
+  fromId: string;      // Entry we navigated from
+  usage?: Usage;       // LLM usage that generated the summary
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
+  details?: T;         // implementation-specific data
+}
+
+// Default branch summarization uses this for details (from branch-summarization.ts):
+interface BranchSummaryDetails {
+  readFiles: string[];
+  modifiedFiles: string[];
+}
+```
+
+Same as compaction, extensions can store custom data in `details`.
+
+See [`collectEntriesForBranchSummary()`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) for the implementation.
+
+## Summary Format
+
+Both compaction and branch summarization use the same structured format:
+
+```markdown
+## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+- [Requirements mentioned by user]
+
+## Progress
+### Done
+- [x] [Completed tasks]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues, if any]
+
+## Key Decisions
+- **[Decision]**: [Rationale]
+
+## Next Steps
+1. [What should happen next]
+
+## Critical Context
+- [Data needed to continue]
+
+<read-files>
+path/to/file1.ts
+path/to/file2.ts
+</read-files>
+
+<modified-files>
+path/to/changed.ts
+</modified-files>
+```
+
+### Message Serialization
+
+Before summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+
+```
+[User]: What they said
+[Assistant thinking]: Internal reasoning
+[Assistant]: Response text
+[Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
+[Tool result]: Output from tool
+```
+
+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.
+
+## Custom Summarization via Extensions
+
+Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](https://github.com/maikel/ion/blob/main/packages/coding-agent/src/core/extensions/types.ts) for event type definitions.
+
+### session_before_compact
+
+Fired before auto-compaction or `:compact`. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
+
+```typescript
+ion.on("session_before_compact", async (event, ctx) => {
+  const { preparation, branchEntries, customInstructions, reason, willRetry, 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 - effective settings after applying model overrides
+
+  // branchEntries - all entries on current branch (for custom state)
+  // reason - "manual" (:compact), "threshold", or "overflow"
+  // willRetry - whether the aborted turn is retried after compaction (overflow recovery)
+  // signal - AbortSignal (pass to LLM calls)
+
+  // Cancel:
+  return { cancel: true };
+
+  // Custom summary:
+  return {
+    compaction: {
+      summary: "Your summary...",
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+      // usage: summaryResponse.usage, // Optional; included in session totals
+      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 "@m4ike1/ion-coding-agent";
+
+ion.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, usage } = await myModel.summarize(conversationText);
+  
+  return {
+    compaction: {
+      summary,
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+      usage,
+    }
+  };
+});
+```
+
+See [custom-compaction.ts](../examples/extensions/custom-compaction.ts) for a complete example using a different model.
+
+### session_compact_failed
+
+Fired when manual or automatic compaction fails or is aborted. This is useful for telemetry extensions that need to pair `session_before_compact` attempts with terminal outcomes.
+
+```typescript
+ion.on("session_compact_failed", async (event, ctx) => {
+  const { reason, errorMessage, aborted, willRetry, fromExtension } = event;
+  // reason - "manual" (:compact), "threshold", or "overflow"
+  // errorMessage - present for non-abort failures
+  // aborted - true for cancelled/aborted compactions
+  // willRetry - whether the aborted turn would have retried after compaction
+  // fromExtension - whether extension-provided compaction content was being used
+});
+```
+
+### session_before_tree
+
+Fired before `:tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
+
+```typescript
+ion.on("session_before_tree", async (event, ctx) => {
+  const { preparation, signal } = event;
+
+  // preparation.targetId - where we're navigating to
+  // preparation.oldLeafId - current position (being abandoned)
+  // preparation.commonAncestorId - shared ancestor
+  // preparation.entriesToSummarize - entries that would be summarized
+  // preparation.userWantsSummary - whether user chose to summarize
+
+  // Cancel navigation entirely:
+  return { cancel: true };
+
+  // Provide custom summary (only used if userWantsSummary is true):
+  if (preparation.userWantsSummary) {
+    return {
+      summary: {
+        summary: "Your summary...",
+        // usage: summaryResponse.usage, // Optional; included in session totals
+        details: { /* custom data */ },
+      }
+    };
+  }
+});
+```
+
+See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
+
+## Settings
+
+Configure compaction in `~/.ion/agent/settings.json` or `<project-dir>/.ion/settings.json`:
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | Enable auto-compaction |
+| `reserveTokens` | `16384` | Tokens to reserve for LLM response |
+| `keepRecentTokens` | `20000` | Recent tokens to keep (not summarized) |
+
+Disable auto-compaction with `"enabled": false`. You can still compact manually with `:compact`.
+
+### Per-model overrides
+
+Use `compaction.modelOverrides` to tune token budgets for different models:
+
+```json
+{
+  "compaction": {
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000,
+    "modelOverrides": {
+      "some-provider/big-model": {
+        "reserveTokens": 400000
+      }
+    }
+  }
+}
+```
+
+For a model with a 1M context window, this override triggers compaction above 600K tokens and keeps the ordinary 20000 recent tokens. Other models retain the ordinary 16384-token reserve. `reserveTokens` also influences summarization output limits, capped by the model's maximum output tokens; it is not solely a trigger threshold.
+
+Keys are exact, case-sensitive `provider/modelId` values, including any slashes within the model ID. Each `reserveTokens` and `keepRecentTokens` value falls back independently from the model override to the ordinary setting to the built-in default. Values must be non-negative safe integers. Invalid values in the matching model override produce an error when read; only omitted fields fall back to the ordinary setting. Model override entries must be objects. Invalid ordinary token settings produce an error when read, even if the active model has a valid override. Only omitted ordinary values use built-in defaults. `enabled` remains global, not model-specific.
+
+These resolved values are used for manual compaction, all automatic threshold checks, overflow recovery, and extension-visible `preparation.settings`. Model switches affect subsequent checks and compactions without changing ordinary settings. Compaction already in progress uses the model and settings captured for that operation. Branch summarization settings are unaffected.
+
+Overrides work in both global and project settings. The files merge recursively before lookup, so a global model-specific value beats a project-wide fallback; a project must override that model entry to change it. See [settings.md](settings.md#per-model-compaction-overrides) for details.