@knightcodeai/cli-linux-arm64 0.4.0 → 0.5.0

package/bin/CHANGELOG.md

@@ -0,0 +1,178 @@
+# @knightcodeai/cli
+
+## 0.5.0
+
+### Minor Changes
+
+- dafe408: A rebuilt agent core.
+
+  The agent loop, session storage, provider layer and terminal UI were all
+  replaced. What that buys:
+
+  - **A measured ~1,100-token floor** for the system prompt and tool definitions —
+    every request is smaller, on every model.
+  - **Real multi-provider support**: Anthropic, OpenAI/Codex, OpenRouter, Amazon
+    Bedrock, xAI, Kimi, GitHub Copilot, and any custom endpoint through
+    `models.json`. OAuth sign-in where the provider supports it, API keys
+    everywhere else.
+  - **Sessions you can leave and come back to**: resume, fork, branch, search, and
+    automatic compaction when a conversation outgrows the context window.
+  - **Extensions, skills and prompt templates**, discovered from the project or
+    installed globally.
+  - **Headless mode**: `--print` with `text`, `json` or `rpc` output, for scripting
+    and for driving KnightCode from another program.
+
+  Distribution is unchanged — a self-contained compiled binary per platform, no
+  Bun or Node needed at runtime.
+
+## 0.4.1
+
+### Patch Changes
+
+- 5ffa10b: Re-inject the current todo list after each tool round so the model's plan stays in context during long turns. Only fires when the list has unfinished items and has changed since the last round.
+
+## 0.4.0
+
+### Minor Changes
+
+- aa2645e: Harness reliability: safer edits and recovery from flaky model streams.
+
+  - **No blind or stale edits.** A file must be read before it can be edited, and an edit is rejected if the file changed on disk since that read — so a write can't silently clobber newer changes. The read state is rebuilt from the transcript, so it survives a session resume.
+  - **No accidental repeats.** Identical read-only tool calls in one round run once instead of duplicating, and the loop guard stops repeated identical calls sooner.
+  - **Auto-retry on flaky streams.** Transient stream failures and empty responses retry with exponential backoff (honoring `Retry-After`); cancelling mid-backoff no longer fires an extra model call.
+  - **Tool errors self-correct.** An invalid tool call no longer ends the turn — the model gets the error back and can fix it.
+  - **No misleading diffs.** An edit diff shows only after the edit actually applies; failed or rejected edits don't render one.
+
+## 0.3.1
+
+### Patch Changes
+
+- a2679c6: Fix the `/exit` command freezing the terminal in packaged builds. Process cleanup used `spawnSync(process.execPath, ["-e", ...])` as a sleep, but in a compiled standalone binary `process.execPath` is the CLI itself, so it relaunched the TUI and blocked forever. Replaced it with an in-process sleep and made exit terminate the process explicitly.
+
+## 0.3.0
+
+### Minor Changes
+
+- 9531729: Add automatic skill discovery, hot-reload, and path-scoped skills so installed skills surface and get loaded without having to be named explicitly.
+
+  ### Added
+  - **Skill auto-discovery.** Each turn a cheap side-query compares your request against the installed skills, surfaces the relevant ones, and directs the model to load them via the `Skill` tool before responding. Surfaced skills appear as a visible `↳ Relevant skills: …` line in the chat. Controlled by the `skills.autoDiscover` setting (on by default).
+  - **Skill hot-reload.** A file watcher picks up added, edited, or removed `SKILL.md` files mid-session, so changes take effect without restarting. Controlled by the `skills.hotReload` setting (on by default).
+  - **Path-scoped (conditional) skills.** A skill with a `paths` frontmatter glob is kept out of the always-on skill list and surfaces only when you edit a file matching its globs.
+
+  ### Changed
+  - The skill index injected into the system prompt is now size-bounded: descriptions are truncated to fit the budget and, in the extreme, the listing falls back to names only — but every skill name is always shown, so no installed skill becomes undiscoverable.
+
+## 0.2.1
+
+### Patch Changes
+
+- b529674: ### Added
+
+  Memory follow-ups: feed recent tool usage into the recall selector as an extra relevance signal, frame extraction's "new messages" window from a per-session cursor (so durable facts mentioned during gate-skipped turns are still reconsidered), and drain any in-flight memory extraction on `/exit` (bounded) so a save isn't dropped at shutdown.
+
+  ### Fixed
+
+  `Tab` mode cycle so it reaches `AUTO`: previously `Tab` only toggled between `BUILD` and `PLAN`, making `AUTO` selectable solely via the `/agents` dialog. `Tab` now cycles `BUILD → PLAN → AUTO → BUILD`.
+
+  ### Removed
+
+  Drop two unused dependencies from `@knightcodeai/cli`: `pretty-ms` (never imported) and `hono` (the toast provider's `useMemo` now imports from `react` instead of `hono/jsx`).
+
+- 23a8811: Refresh the supported model catalog: add newer free and paid OpenRouter models, repoint aliases to their successors, change the default model, and drop discontinued entries.
+
+  ### Added
+
+  Refresh the supported model catalog with new OpenRouter models: `nvidia/nemotron-3-ultra-550b-a55b:free` (Nemotron 3 Ultra 550B), `nex-agi/nex-n2-pro:free` (Nex N2 Pro), `qwen/qwen3.7-plus` (Qwen3.7 Plus), `z-ai/glm-5.2` (GLM 5.2), and `moonshotai/kimi-k2.7-code` (Kimi K2.7 Code). New `qwen` and `nex` model aliases accompany them.
+
+  ### Changed
+
+  Default model is now `nvidia/nemotron-3-ultra-550b-a55b:free` (was `z-ai/glm-4.5-air:free`). The `glm`, `kimi`, and `nemotron` aliases were repointed to their successor models (`z-ai/glm-5.2`, `moonshotai/kimi-k2.7-code`, `nvidia/nemotron-3-ultra-550b-a55b:free`), and the onboarding shortlist was updated to match the new catalog.
+
+  ### Removed
+
+  Drop discontinued/older version models: `z-ai/glm-4.5-air:free`, `deepseek/deepseek-v4-flash:free`, `z-ai/glm-5.1`, `moonshotai/kimi-k2.6`, and `nvidia/nemotron-3-super-120b-a12b:free`, along with their `glm_air` and `deepseek` aliases.
+
+- b529674: ### Added
+
+  Accurate per-session cost: enable OpenRouter usage accounting (`usage.include`) so each request returns its **actual** cost. The in-app `/cost` "Session cost" now sums real costs (correct for free/cached/uncurated models) and only falls back to the local price table when a message has no reported cost.
+
+  Session grouping on OpenRouter: send the session id as the `x-session-id` header so a session's requests are grouped in OpenRouter's logs (Sessions tab) and routed stickily to the same provider for better prompt-cache hits. Requests are also tagged with the session id via the `user` field for per-request "Client User ID" attribution.
+
+  ### Changed
+
+  OpenRouter app attribution: `HTTP-Referer` → `https://knightcode.raghavseth.in` and `X-Title` → `KnightCode` (was "KnightCode CLI").
+
+## 0.2.0
+
+### Minor Changes
+
+- f2846df: Standalone query engine, concurrent tool scheduler, and Apache-2.0 licensing.
+
+  This release replaces the React `useChat`-based chat harness with a dedicated,
+  framework-agnostic query engine, adds a concurrency-aware tool scheduler, and
+  hardens the interactive terminal experience. The project is now formally
+  licensed under Apache-2.0.
+
+  ### Added
+  - **Standalone query engine.** A new engine loop drives a turn end-to-end,
+    independent of the React render tree (`lib/engine/`). It owns engine event and
+    params types, a transcript-repair pass that resolves dangling/unresolved tool
+    calls, and tool-gating decisions backed by a loop guard to prevent runaway
+    tool cycles.
+  - **`useQueryEngine` hook.** A thin React hook that drives the engine loop and
+    replaces the previous `useChat` harness entirely.
+  - **Concurrency-aware tool scheduler.** Engine-owned scheduling policy runs tool
+    rounds with bounded concurrency. Introduces an engine `ToolHost` contract and a
+    hook adapter so the engine can execute tools without depending on the UI layer.
+  - **Cross-session project memory.** Durable, non-obvious facts are extracted
+    automatically after completed turns into a per-project store
+    (`~/.knightcode/projects/<cwd>/memory/`) with a `MEMORY.md` recall index.
+    Relevant memories are recalled into the system prompt, a consolidation
+    ("dream") pass merges and prunes the store, and a `Memory` tool lets the model
+    review, correct, or forget entries.
+  - **Per-row tool spinners.** Concurrently running tools each get their own inline
+    spinner instead of a single shared indicator.
+  - **`@`-mention path expansion.** Paths referenced with `@` in a prompt are
+    expanded into the model's context at submit time.
+  - **PostToolUse `systemMessage` surfacing.** Messages emitted by `PostToolUse`
+    hooks are now surfaced to callers.
+  - **Apache-2.0 license.** Added root `LICENSE` and `NOTICE` files and `license`
+    fields in the workspace and CLI `package.json`.
+
+  ### Changed
+  - Extracted `compactHistory` out of the old `use-chat` module and moved chat
+    message types into `lib/engine/messages`.
+  - Exposed a hook-free `executeRegisteredTool` for engine use.
+  - Unified all interactive prompts onto a single shared permission panel.
+  - Dropped the unused `sessionId` from `QueryParams`.
+  - Pointed repository URLs at the KnightCodeAI org and scoped the publish
+    workflow to publishable paths.
+
+  ### Fixed
+  - **Quit behaviour:** `/exit` is now the only way to quit; Ctrl+C never exits.
+  - **Permissions:** every confirm-gated tool now shows a permission prompt, and
+    every awaited tool decision is guaranteed a resolvable prompt; scoped the
+    always-allow sweep correctly.
+  - **Markdown rendering:** convert `<br>` to real line breaks in prose, expand
+    `<br>` table cells into continuation rows, and stop rendering literal `<br>`
+    tags.
+  - **Interrupts:** render the interrupted marker after the partial response, with
+    a plain interrupted notice (no emoji or completion verb); render interrupted
+    aborts and surface queued mid-turn submits.
+  - **History integrity:** stop schema-validating history and instead quarantine
+    invalid tool calls.
+  - **State sync:** synchronize message-ref writes, guard submit re-entry, persist
+    the final turn snapshot, queue mid-turn submits, clear finished todos, and only
+    clear the compacting state when it was actually set.
+  - Hardened file reads, question cancellation, and transcript text handling, plus
+    a sweep of code-review findings across the engine and UI.
+
+## 0.1.0
+
+### Minor Changes
+
+- 13af3df: Initial public release: `knightcode` ships as a self-contained compiled binary
+  (no Bun required) distributed via platform-specific npm packages, with a headless
+  `--version` and `doctor`, embedded database migrations, and a non-blocking update
+  check.

package/bin/README.md

@@ -0,0 +1,36 @@
+# @knightcodeai/cli
+
+`knightcode` — a local-first, bring-your-own-key AI coding CLI for your terminal.
+
+## Install
+
+```bash
+npm install -g @knightcodeai/cli
+```
+
+You don't need Bun — it's bundled into the platform binary. The small launcher
+(`bin/knightcode`) that spawns it runs on Node.js (>=18), which you already have
+if you installed with npm. The right platform binary installs automatically as
+an optional dependency.
+
+## Quick start
+
+```bash
+knightcode
+```
+
+On first run, set your OpenRouter API key from inside the app.
+
+## Configuration
+
+State lives in `~/.knightcode/` (sessions, settings, local SQLite database).
+
+| Command / env var | Effect |
+| ----------------- | ------ |
+| `knightcode --version` | Print the installed version |
+| `knightcode doctor` | Print diagnostics (config, database, API key, runtime) |
+| `KNIGHTCODE_NO_UPDATE_CHECK=1` | Disable the background update check |
+
+## Supported platforms
+
+Linux (x64, arm64), macOS (x64, arm64), Windows (x64).

package/bin/docs/compaction.md

@@ -0,0 +1,416 @@
+# Compaction & Branch Summarization
+
+LLMs have limited context windows. When conversations grow too long, KnightCode uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
+
+**Source files** ([knightcode](https://github.com/KnightCodeAI/knightcode)):
+- [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/KnightCodeAI/knightcode/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/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
+- [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/KnightCodeAI/knightcode/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/KnightCodeAI/knightcode/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/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/extensions/types.ts) - Extension event types
+
+For TypeScript definitions in your project, inspect `node_modules/@knightcodeai/cli/dist/`.
+
+## Overview
+
+KnightCode 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 `~/.knightcode/agent/settings.json` or `<project-dir>/.knightcode/settings.json`). This leaves room for the LLM's response.
+
+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 `~/.knightcode/agent/settings.json` or `<project-dir>/.knightcode/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. KnightCode 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, KnightCode 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/KnightCodeAI/knightcode/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/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) and [`compact()`](https://github.com/KnightCodeAI/knightcode/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, KnightCode 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, knightcode 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/KnightCodeAI/knightcode/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/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](https://github.com/KnightCodeAI/knightcode/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/KnightCodeAI/knightcode/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/KnightCodeAI/knightcode/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
+knightcode.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 - compaction settings
+
+  // 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 "@knightcodeai/cli";
+
+knightcode.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
+knightcode.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
+knightcode.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 `~/.knightcode/agent/settings.json` or `<project-dir>/.knightcode/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`.