apex-code 0.5.0 → 0.5.2

package/dist/utils/zip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.js","sourceRoot":"","sources":["../../src/utils/zip.ts"],"names":[],"mappings":"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","sourcesContent":["import { writeFile } from \"node:fs/promises\";\nimport { crc32, deflateRawSync } from \"node:zlib\";\n\ninterface ZipEntry {\n\tname: string;\n\tdata: string | Uint8Array;\n}\n\nfunction dosDateTime(date: Date): { time: number; day: number } {\n\treturn {\n\t\ttime: (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1),\n\t\tday: ((Math.max(1980, date.getFullYear()) - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),\n\t};\n}\n\n/** Create the small, classic ZIP archives used by bug reports. */\nfunction createZipArchive(entries: readonly ZipEntry[]): Buffer {\n\tconst files: Buffer[] = [];\n\tconst directory: Buffer[] = [];\n\tconst { time, day } = dosDateTime(new Date());\n\tlet offset = 0;\n\n\tfor (const entry of entries) {\n\t\tconst name = Buffer.from(entry.name);\n\t\tconst data = typeof entry.data === \"string\" ? Buffer.from(entry.data) : Buffer.from(entry.data);\n\t\tconst compressed = deflateRawSync(data);\n\t\tconst checksum = crc32(data);\n\n\t\tconst local = Buffer.alloc(30);\n\t\tlocal.writeUInt32LE(0x04034b50, 0);\n\t\tlocal.writeUInt16LE(20, 4);\n\t\tlocal.writeUInt16LE(0x0800, 6);\n\t\tlocal.writeUInt16LE(8, 8);\n\t\tlocal.writeUInt16LE(time, 10);\n\t\tlocal.writeUInt16LE(day, 12);\n\t\tlocal.writeUInt32LE(checksum, 14);\n\t\tlocal.writeUInt32LE(compressed.length, 18);\n\t\tlocal.writeUInt32LE(data.length, 22);\n\t\tlocal.writeUInt16LE(name.length, 26);\n\n\t\tconst central = Buffer.alloc(46);\n\t\tcentral.writeUInt32LE(0x02014b50, 0);\n\t\tcentral.writeUInt16LE(20, 4);\n\t\tcentral.writeUInt16LE(20, 6);\n\t\tcentral.writeUInt16LE(0x0800, 8);\n\t\tcentral.writeUInt16LE(8, 10);\n\t\tcentral.writeUInt16LE(time, 12);\n\t\tcentral.writeUInt16LE(day, 14);\n\t\tcentral.writeUInt32LE(checksum, 16);\n\t\tcentral.writeUInt32LE(compressed.length, 20);\n\t\tcentral.writeUInt32LE(data.length, 24);\n\t\tcentral.writeUInt16LE(name.length, 28);\n\t\tcentral.writeUInt32LE(offset, 42);\n\n\t\tfiles.push(local, name, compressed);\n\t\tdirectory.push(central, name);\n\t\toffset += local.length + name.length + compressed.length;\n\t}\n\n\tconst centralDirectory = Buffer.concat(directory);\n\tconst end = Buffer.alloc(22);\n\tend.writeUInt32LE(0x06054b50, 0);\n\tend.writeUInt16LE(entries.length, 8);\n\tend.writeUInt16LE(entries.length, 10);\n\tend.writeUInt32LE(centralDirectory.length, 12);\n\tend.writeUInt32LE(offset, 16);\n\treturn Buffer.concat([...files, centralDirectory, end]);\n}\n\nexport function writeZipArchive(filePath: string, entries: readonly ZipEntry[]): Promise<void> {\n\treturn writeFile(filePath, createZipArchive(entries));\n}\n"]}

package/docs/cli-integration.md

@@ -0,0 +1,107 @@
+# CLI Integration
+
+By default, running `apex-code` opens the interactive terminal interface. When input or output is piped or redirected, Apex Code uses print mode instead. You can also select print, JSON, RPC, or ACP mode explicitly for scripts and applications.
+
+All five modes use the same agent, sessions, resources, and tools. The mode determines how input enters Apex Code, how output is exposed, and whether the process remains available for more commands.
+
+The SDK is not a CLI mode. It embeds the agent directly in a Node.js or Bun process. See the [SDK](sdk.md) when direct TypeScript access is preferable to a process boundary.
+
+## Choose a mode
+
+| Mode | Interface | Lifetime | Use it when |
+|---|---|---|---|
+| Interactive | Terminal UI | Until the user exits | A person is working with Apex Code directly |
+| Print | Final text on stdout | One invocation | A script needs the final assistant response |
+| JSON | JSONL events on stdout | One invocation | A process needs structured progress from a run |
+| RPC | JSONL commands, responses, and events | Long-lived | A process needs bidirectional control |
+| ACP | ACP v1 JSON-RPC on stdio | Long-lived | An ACP host needs to manage sessions and tool permissions |
+
+CLI options still select the working directory, model, tools, resources, and session persistence independently of the mode. See [Command Line](cli.md) for the complete startup options.
+
+## Print to stdout
+
+Print mode runs the supplied prompts, writes the final assistant text to stdout, and exits:
+
+```bash
+apex-code --print "Summarize the changes in this repository"
+```
+
+Use print mode when only the final text is needed, including command substitution, pipelines, and one-shot jobs. Intermediate events are not exposed.
+
+Print mode writes errors to stderr. A final assistant response with an `error` or `aborted` stop reason produces a nonzero exit status.
+
+When no mode is selected explicitly, non-TTY stdin or stdout also selects print mode. This allows piped input and output without adding `--print`.
+
+## Stream JSON events
+
+JSON mode writes a session header followed by agent and session events as newline-delimited JSON:
+
+```bash
+apex-code --mode json "Review this repository" > events.jsonl
+```
+
+This is structured event output, not a single JSON result or a constraint on the format of the model’s response.
+
+All prompts are supplied when the process starts. The process streams events for that run and then exits; it does not accept later commands.
+
+A failed or aborted assistant response appears in the event stream but does not by itself produce a nonzero exit status. Inspect the events when success or failure matters. Apex Code still exits nonzero if the invocation throws an error.
+
+Streaming `message_update` records contain deltas rather than a growing message snapshot. Assemble live output from the delta events, then replace it with the authoritative message from `message_end`.
+
+`agent_end` can be followed by automatic recovery or queued work. `agent_settled` marks the end of automatic work for the current run.
+
+Stdout is reserved for JSONL. Diagnostics and application logging are written to stderr. See [JSON Event Stream](json.md) for framing, event shapes, and reconstruction rules.
+
+## Control Apex Code with RPC
+
+RPC mode keeps Apex Code running while another process sends commands and receives responses and events:
+
+```bash
+apex-code --mode rpc --no-session
+```
+
+Commands are JSON objects written to stdin. Responses and events are JSON objects written to stdout. Every record occupies one line.
+
+Add an `id` to commands that need correlation. The matching response repeats that ID. Events generally have no command ID because they describe session activity rather than one request.
+
+A successful `prompt` response means the prompt was accepted, queued, or handled. It does not mean the run completed. Continue consuming events through `agent_settled` when completion matters.
+
+RPC commands can change models, inspect state, manage sessions, run shell commands, and answer extension UI requests.
+
+Extension dialogs form a request-response subprotocol. Other extension UI updates are notifications that a client may display or ignore. TUI-only extension capabilities are unavailable or degraded outside interactive mode.
+
+For Node.js or TypeScript integrations, prefer `RpcClient` from `@earendil-works/pi-coding-agent`. It starts an Apex Code RPC child process, correlates requests, exposes typed command methods, and delivers session events to listeners.
+
+The [RPC client example](../examples/rpc-client.ts) sends one prompt, streams text and tool activity, waits for `agent_settled`, and shuts down the child process. It is included in the repository’s TypeScript checks.
+
+`RpcClient.promptAndWait()` installs its event listener before sending the prompt, avoiding a race with fast completions. For separate operations, subscribe before calling `prompt()` and call `waitForIdle()` only while a run is active.
+
+The client requires a path to a runnable Apex Code CLI. The repository example points at `dist/cli.js`, so the package must be built before that example runs from a checkout.
+
+If you are building a client without `RpcClient`, start with [RPC Protocol](rpc.md), then use [RPC Commands](rpc-commands.md) and [JSON Event Stream](json.md) as the wire references.
+
+## Fork and rebrand Apex Code
+
+A source fork can change the CLI name and configuration directory through `package.json`:
+
+```json
+{
+  "piConfig": {
+    "name": "my-agent",
+    "configDir": ".my-agent"
+  }
+}
+```
+
+Change the top-level `bin` field to set the executable name. These settings affect the CLI banner, configuration paths, and derived environment variable names.
+
+## Examples and references
+
+- [RPC client](../examples/rpc-client.ts): typed Node.js integration
+- [RPC extension UI](../examples/rpc-extension-ui.ts): custom terminal client with extension dialogs
+- [Command Line](cli.md): startup options and mode selection
+- [JSON Event Stream](json.md): JSON event reference
+- [RPC Protocol](rpc.md): RPC lifecycle, framing, errors, and shutdown
+- [RPC Commands](rpc-commands.md): command and response reference
+- [RPC Extension UI](rpc-extension-ui.md): extension interaction subprotocol
+- [SDK examples](../examples/sdk/): in-process TypeScript integrations

package/docs/cli.md

@@ -0,0 +1,269 @@
+<a id="cli-and-modes-reference"></a>
+
+# Command Line
+
+This page documents Apex Code's built-in command-line commands and options. Run `apex-code --help` or append `--help` to a command for the exact interface in your installed version. The top-level help also includes options registered by loaded extensions.
+
+```sh
+apex-code [options] [--] [@files...] [messages...]
+apex-code install <source> [options]
+apex-code remove <source> [options]
+apex-code uninstall <source> [options]
+apex-code update [target] [options]
+apex-code list
+apex-code config [options]
+apex-code auth <check|print-api-key|print-bearer-token> [options]
+```
+
+<a id="modes"></a>
+
+## Invocation and output
+
+```sh
+apex-code
+apex-code --print "Summarize this repository"
+git diff | apex-code --print "Review this change"
+apex-code --mode json "Inspect this repository" > events.jsonl
+```
+
+With terminal stdin and stdout, Apex Code opens the terminal UI unless `--print`, `--mode json`, or `--mode rpc` selects another interface. When either stream is redirected and neither JSON nor RPC mode is selected, Apex Code uses print mode. See [CLI Integration](cli-integration.md) for choosing between interactive, print, JSON, RPC, and SDK integration.
+
+| Input | Behavior |
+|---|---|
+| `message` | Provide an initial prompt |
+| `@path` | Include a text file or image in the first prompt |
+| Piped stdin | Prepend its contents to the first prompt |
+| `--` | Stop option parsing so a prompt can begin with `-` |
+
+Apex Code resolves `@path` from the current working directory. The working directory also controls project configuration, resource discovery, and session grouping.
+
+`--print` controls whether Apex Code runs once and exits. `--mode` selects the output interface. `--mode text` does not force one-shot execution when stdin and stdout are terminals; use `--print` for that behavior.
+
+| Option | Behavior |
+|---|---|
+| `-p`, `--print` | Run the supplied prompts, write the final assistant text to stdout, then exit |
+| `--mode text` | Select text output; still open the terminal UI when stdin and stdout are terminals |
+| `--mode json` | Run the supplied prompts, write JSONL events to stdout, then exit |
+| `--mode rpc` | Read JSONL commands from stdin and write responses and events to stdout until shutdown |
+| `--mode acp` | Run the ACP v1 agent protocol over newline-delimited JSON-RPC on stdin and stdout |
+| `--export <input> [output]` | Export a session file to HTML and exit; derive the destination when `output` is omitted |
+
+RPC mode rejects `@file` arguments. JSON and RPC modes reserve stdout for protocol records. See [JSON Event Stream](json.md) and [RPC Protocol](rpc.md).
+
+<a id="model-options"></a>
+
+## Models
+
+```sh
+apex-code --model sonnet:high
+```
+
+See [Choose a Model](models.md) for model selection and [Provider Authentication](providers.md) for credentials.
+
+- `--provider <name>`<br>
+  Restricts `--model` lookup to one provider.
+- `--model <pattern>`<br>
+  Selects by exact ID or fuzzy ID/name match. It accepts `provider/id` and an optional `:<thinking>` suffix.
+- `--api-key <key>`<br>
+  Uses a non-persistent API-key override. It requires a model selected through `--model` or `--models`.
+- `--thinking <level>`<br>
+  Sets `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. It overrides a `--model` suffix and is clamped to the model's capabilities.
+- `--models <patterns>`<br>
+  Sets a comma-separated scope for startup and cycling. It accepts exact IDs, fuzzy matches, case-insensitive globs, and optional `:<thinking>` suffixes.
+- `--list-models [search]`<br>
+  Lists available models, optionally filtered by a fuzzy search, then exits.
+
+<a id="session-options"></a>
+
+## Sessions
+
+```sh
+apex-code --continue
+```
+
+See [Sessions and Context](sessions.md) for resuming, forking, naming, and storing sessions.
+
+- `-c`, `--continue`<br>
+  Continues the most recent session for the current project.
+- `-r`, `--resume`<br>
+  Opens the session selector.
+- `--session <path|id>`<br>
+  Opens by file path, exact ID, or partial ID. Apex Code searches the current project first and offers to fork a cross-project match.
+- `--session-id <id>`<br>
+  Opens the exact project session ID or creates it if absent. IDs accept letters, numbers, `.`, `_`, and `-`.
+- `--fork <path|id>`<br>
+  Forks an existing session into a new session for the current project.
+- `--session-dir <dir>`<br>
+  Overrides storage and lookup. It takes precedence over `PI_CODING_AGENT_SESSION_DIR` and the `sessionDir` setting.
+- `--no-session`<br>
+  Uses an in-memory session that is not persisted.
+- `-n`, `--name <name>`<br>
+  Sets the session display name.
+
+Constraints:
+
+- Session IDs must start and end with a letter or number.
+- `--fork` cannot be combined with `--session`, `--continue`, `--resume`, or `--no-session`.
+- `--session-id` cannot be combined with `--session`, `--continue`, or `--resume`. Combine it with `--fork` to choose the new ID.
+
+<a id="tool-options"></a>
+
+## Tools
+
+```sh
+apex-code --tools read,grep,find,ls --print "Review this project"
+```
+
+See [Settings](settings.md#tools) for configuring the default tool selection.
+
+- `-t`, `--tools <list>`<br>
+  Replaces the default selection with a comma-separated allowlist of built-in, extension, or custom tools.
+- `-xt`, `--exclude-tools <list>`<br>
+  Disables comma-separated tool names after all other selection options.
+- `-nbt`, `--no-builtin-tools`<br>
+  Disables default built-in tools while retaining extension and custom tools.
+- `-nt`, `--no-tools`<br>
+  Starts with all built-in, extension, and custom tools disabled.
+
+Default enabled tools are `read`, `bash`, `edit`, and `write`, unless `defaultTools` changes them.
+
+| Built-in | Purpose |
+|---|---|
+| `read` | Read text files and supported images |
+| `bash` | Run shell commands |
+| `powershell` | Run PowerShell commands on Windows |
+| `edit` | Apply exact text replacements to an existing file |
+| `write` | Create or overwrite a file |
+| `grep` | Search file contents |
+| `find` | Find paths using glob patterns |
+| `ls` | List directory contents |
+
+<a id="resource-options"></a>
+
+## Resources
+
+```sh
+apex-code --extension ./review.ts
+```
+
+See [Configuration](configuration.md) for conventional directories and project trust, [Settings](settings.md#resources) for configured paths, and [Apex Code Packages](packages.md) for package sources.
+
+- `-e`, `--extension <path>`<br>
+  Loads an extension file or directory and is repeatable.
+- `-ne`, `--no-extensions`<br>
+  Disables discovered and configured extensions. Explicit `-e` paths still load.
+- `--skill <path>`<br>
+  Loads a skill file or directory and is repeatable.
+- `-ns`, `--no-skills`<br>
+  Disables discovered and configured skills. Explicit `--skill` paths still load.
+- `--prompt-template <path>`<br>
+  Loads a prompt-template file or directory and is repeatable.
+- `-np`, `--no-prompt-templates`<br>
+  Disables discovered and configured templates. Explicit `--prompt-template` paths still load.
+- `--theme <path>`<br>
+  Loads a theme file or directory and is repeatable.
+- `--use-theme <name[/name]>`<br>
+  Selects the initial interactive theme for this run.
+- `--no-themes`<br>
+  Disables discovered and configured themes. Explicit `--theme` paths still load.
+- `-nc`, `--no-context-files`<br>
+  Disables `AGENTS.md` and `CLAUDE.md` discovery.
+
+Resource paths apply only to the current process. Relative paths resolve from the current working directory.
+
+<a id="prompt-and-display-options"></a>
+
+## Prompts and process
+
+```sh
+apex-code --append-system-prompt ./instructions.md
+```
+
+See [Configuration](configuration.md) for saved configuration, [Security](security.md#understand-project-trust) for project trust, and [Environment Variables](environment-variables.md) for process controls.
+
+- `--system-prompt <text|path>`<br>
+  Replaces the default system prompt with text or the contents of an existing file.
+- `--append-system-prompt <text|path>`<br>
+  Appends text or an existing file to the system prompt and is repeatable.
+- `--tui-mode <mode>`<br>
+  Uses `regular` or `fullscreen` terminal mode.
+- `--verbose`<br>
+  Shows verbose interactive startup information, overriding `quietStartup`.
+- `-a`, `--approve`<br>
+  Trusts project-local configuration and resources for this process.
+- `-na`, `--no-approve`<br>
+  Ignores trust-gated project-local configuration and resources for this process.
+- `--offline`<br>
+  Disables automatic network activity, including model catalog refreshes. Equivalent to `PI_OFFLINE=1`.
+- `-h`, `--help`<br>
+  Shows help, including flags registered by loaded extensions, then exits.
+- `-v`, `--version`<br>
+  Shows the Apex Code version, then exits.
+
+Extensions may register additional long-form options. Unknown short options are rejected.
+
+## Package commands
+
+```sh
+apex-code install npm:@scope/package
+```
+
+See [Apex Code Packages](packages.md) for source formats, filtering, installation, and project scope.
+
+### Common tasks
+
+| Task | Command |
+|---|---|
+| Install a package | `apex-code install <source>` |
+| List configured packages | `apex-code list` |
+| Remove a package and its settings entry | `apex-code remove <source>` |
+| Configure which package resources load | `apex-code config` |
+
+Add `--local` or `-l` to `install`, `remove`, `uninstall`, or `config` to use project settings instead of global settings.
+
+### Update Apex Code or packages
+
+Running `apex-code update` without a target updates Apex Code itself.
+
+| Task | Command |
+|---|---|
+| Update Apex Code | `apex-code update` |
+| Update all installed packages | `apex-code update --extensions` |
+| Update one installed package | `apex-code update <source>` |
+| Refresh model catalogs | `apex-code update --models` |
+| Update Apex Code and all installed packages | `apex-code update --all` |
+
+Add `--force` to reinstall Apex Code when the selected update includes Apex Code.
+
+### Aliases and command options
+
+- `apex-code uninstall <source>` is an alias for `apex-code remove <source>`.
+- `apex-code update --self`, `apex-code update self`, and `apex-code update pi` are aliases for `apex-code update`.
+- `apex-code update --extension <source>` is an alias for `apex-code update <source>`.
+- `-a`, `--approve` trusts project-local files for one command. `-na`, `--no-approve` ignores trust-gated project-local files.
+- Append `-h` or `--help` to a command for its exact usage and option constraints.
+
+## Credential commands
+
+```sh
+apex-code auth check --provider openai --json
+```
+
+Authentication commands require `--provider <provider>` or `--model <model>`. See [Provider Authentication](providers.md) for supported methods.
+
+| Command | Description |
+|---|---|
+| `apex-code auth check` | Print `ready`, `not_ready`, or `invalid`; exit with status `0`, `1`, or `2`, respectively |
+| `apex-code auth print-api-key` | Print the resolved API key |
+| `apex-code auth print-bearer-token` | Print a resolved OAuth bearer token |
+
+| Option | Applies to | Description |
+|---|---|---|
+| `--provider <provider>` | All | Resolve credentials for a provider |
+| `--model <model>` | All | Resolve credentials from a model; may be combined with `--provider` |
+| `--json` | `auth check` | Write the structured result as JSON |
+| `--credentials` | `auth check` | Emit the resolved credential when ready |
+| `--no-refresh` | `auth check` | Do not refresh expired OAuth credentials; refresh is the default |
+| `--min-expiry <duration>` | `print-bearer-token` | Require remaining token lifetime using `ms`, `s`, `m`, or `h`, such as `30m` |
+
+Credential-printing commands write secrets to stdout.

package/docs/compaction.md

@@ -1,4 +1,4 @@
-# Compaction & Branch Summarization
+# Compaction Reference
 
 LLMs have limited context windows. When conversations grow too long, Apex Code uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
 
@@ -20,7 +20,7 @@ Apex Code has two summarization mechanisms:
 | Compaction | Context exceeds threshold, or `/compact` | Summarize old messages to free up context |
 | Branch summarization | `/tree` navigation | Preserve context when switching branches |
 
-Both use the same structured summary format and track file operations cumulatively. 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.
+Both use closely related structured formats and track file operations cumulatively. Summarization requests disable prompt-cache writes because these one-off prompts are unlikely to be reused.
 
 ## Compaction
 
@@ -36,17 +36,19 @@ By default, `reserveTokens` is 16384 tokens (configurable in `~/.apex-code/agent
 
 Apex Code checks this threshold after every completed tool batch that would otherwise start another provider request. If a long tool run crosses the threshold, it compacts at that safe boundary and resumes the unfinished run.
 
-During a multi-turn agent run, Pi checks this threshold after tools finish and their results are appended, before starting the next assistant response. If the threshold is crossed, Pi 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. Pi also checks the threshold before a new user prompt and after a low-level agent run ends.
+During a multi-turn agent run, Apex Code checks the finalized session projection after tools finish and before it starts the next assistant response. If the threshold is crossed, it compacts during `prepareNextTurn` and polls steering before `turn_start`. It skips this check when the tool batch ends the run and no queued message needs a response. Apex Code also checks before a new user prompt and performs overflow recovery after the low-level run ends.
+
+A provider context-overflow error or an early final `stopReason: "length"` can select one compact-and-retry recovery attempt. Length responses with tool calls retain their synthetic failed tool results and follow the ordinary tool/queue scheduler rather than forcing the run to end.
 
 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 `~/.apex-code/agent/settings.json` or `<project-dir>/.apex-code/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
+1. **Find the cut point**: Walk backward through the finalized session projection and accumulate token estimates until you reach `keepRecentTokens`. The default is 20k tokens. Configure it in `~/.apex-code/agent/settings.json` or `<project-dir>/.apex-code/settings.json`.
+2. **Extract messages**: Collect projected messages from the previous kept boundary, or from the session start, up to the cut point.
+3. **Generate the summary**: Ask the model for a structured summary and include the previous summary when one exists.
+4. **Append the entry**: Save a `CompactionEntry` with the summary and `firstKeptEntryId`.
+5. **Rebuild the context**: Include the summary and projected messages from `firstKeptEntryId` onward.
 
 ```
 Before compaction:
@@ -80,16 +82,33 @@ What the LLM sees:
     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. Apex Code 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.
+On repeated compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`). If that entry is missing from the path, compaction starts after the previous compaction. A retain-none compaction records its own ID as `firstKeptEntryId`, so the next pass starts after that entry. These rules preserve messages that survived an earlier compaction.
+
+Apex Code recalculates `tokensBefore` from the rebuilt, context-edited session projection before it writes the new `CompactionEntry`. Omitted raw entries remain stored, but they do not affect cut selection, summaries, checkpoints, or token estimates.
+
+### Overflow and length recovery ordering
+
+Recovery preserves the event order. The completed attempt remains visible to `turn_end` and `agent_end`. The session then repairs persisted model context before it retries:
+
+```text
+persist final assistant response
+→ extension/public turn_end
+→ extension/public agent_end
+→ append context_edit omissions for the selected attempt
+→ for overflow/length: run session_before_compact and append compaction on success
+→ start the retry as a fresh run
+```
+
+If recovery compaction fails or is cancelled, Apex Code keeps the omission edits, appends no compaction, and schedules no internal retry. Steering and follow-up queues keep their normal behavior. `agent_before_settle` sees the repaired projection. Raw transcript history, exports, billing totals, and history-search extensions can still inspect the omitted attempt.
 
-### Split Turns
+### Split user-message spans
 
-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.
+A user-message span starts with a user message and includes all turns until the next user message. Normally, compaction cuts at user-message boundaries.
 
-When a single turn exceeds `keepRecentTokens`, the cut point lands mid-turn at an assistant message. This is a "split turn":
+When one user-message span exceeds `keepRecentTokens`, the cut point lands within that span at an assistant message. This is a split user-message span:
 
 ```
-Split turn (one huge turn exceeds budget):
+Split user-message span (one span exceeds budget):
 
   entry:  0     1     2      3     4      5      6     7      8
         ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬──────┐
@@ -102,13 +121,13 @@ Split turn (one huge turn exceeds budget):
                                                       └── kept (7-8)
 
   isSplitTurn = true
-  messagesToSummarize = []  (no complete turns before)
+  messagesToSummarize = []  (no earlier user-message spans)
   turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
 ```
 
 For split turns, Apex Code generates two summaries and merges them:
 1. **History summary**: Previous context (if any)
-2. **Turn prefix summary**: The early part of the split turn
+2. **User-message-span prefix summary**: The early part of the split user-message span
 
 ### Cut Point Rules
 
@@ -120,6 +139,8 @@ Valid cut points are:
 
 Never cut at tool results (they must stay with their tool call).
 
+Preparation advances the kept boundary into a context-invisible suffix only when that suffix contains an omitted assistant attempt and no unomitted context-producing entries. Recovery `context_edit` omissions satisfy this rule; intrinsically context-invisible metadata may coexist with them. Metadata alone and newly appended custom messages do not move the cut. A replacement edit affecting the candidate input or summarized prefix also blocks advancement because the omitted assistant answered the pre-edit input; replacements of suffix entries that are ultimately omitted remain safe. This allows an over-budget recovered input to be summarized while retaining the edits that keep the abandoned attempt omitted, without making bookkeeping change whether new model input is preserved verbatim.
+
 ### CompactionEntry Structure
 
 Defined in [`session-manager.ts`](https://github.com/Fchery87/apex-code/blob/main/packages/coding-agent/src/core/session-manager.ts):
@@ -128,8 +149,8 @@ Defined in [`session-manager.ts`](https://github.com/Fchery87/apex-code/blob/mai
 interface CompactionEntry<T = unknown> {
   type: "compaction";
   id: string;
-  parentId: string;
-  timestamp: number;
+  parentId: string | null;
+  timestamp: string;
   summary: string;
   firstKeptEntryId: string;
   tokensBefore: number;
@@ -186,7 +207,7 @@ Both compaction and branch summarization track files cumulatively. When generati
 - 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.
+File tracking therefore accumulates across default compactions and nested default branch summaries. Pi does not automatically carry file lists from extension-generated summaries whose `fromHook` field is `true`; extensions manage their own `details` format.
 
 ### BranchSummaryEntry Structure
 
@@ -196,8 +217,8 @@ Defined in [`session-manager.ts`](https://github.com/Fchery87/apex-code/blob/mai
 interface BranchSummaryEntry<T = unknown> {
   type: "branch_summary";
   id: string;
-  parentId: string;
-  timestamp: number;
+  parentId: string | null;
+  timestamp: string;
   summary: string;
   fromId: string;      // Entry we navigated from
   usage?: Usage;       // LLM usage that generated the summary
@@ -218,7 +239,9 @@ See [`collectEntriesForBranchSummary()`](https://github.com/Fchery87/apex-code/b
 
 ## Summary Format
 
-Both compaction and branch summarization use the same structured format:
+Both formats include Goal, Constraints & Preferences, Progress, Key Decisions, and Next Steps. Compaction summaries also include Critical Context. Branch summaries stop after Next Steps. Pi appends file lists to either format when relevant.
+
+Compaction summaries use this format:
 
 ```markdown
 ## Goal
@@ -285,12 +308,12 @@ pi.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.turnPrefixMessages - user-message-span 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
+  // preparation.settings - effective settings after applying model overrides
 
   // branchEntries - all entries on current branch (for custom state)
   // reason - "manual" (/compact), "threshold", or "overflow"
@@ -359,7 +382,7 @@ pi.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
+  // aborted - true for canceled/aborted compactions
   // willRetry - whether the aborted turn would have retried after compaction
   // fromExtension - whether extension-provided compaction content was being used
 });
@@ -418,3 +441,29 @@ Configure compaction in `~/.apex-code/agent/settings.json` or `<project-dir>/.ap
 | `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](settings.md#per-model-compaction-overrides) for details.

package/docs/configuration.md

@@ -0,0 +1,45 @@
+# Configuration
+
+Apex Code supports user-level and project configuration. User-level configuration lives in the agent directory, which defaults to `~/.apex-code/agent`. Project configuration lives in `.apex-code` under the working directory and loads after [project trust](security.md#understand-project-trust) is granted. The only exception is `sessionDir`, which Apex Code reads before resolving trust so it can locate sessions.
+
+In interactive mode, use `/settings` to change common preferences. For other options, ask Apex Code to update the configuration or edit the relevant files directly. Run `/reload` after manually changing settings, keybindings, instructions, or resources.
+
+## Agent directory
+
+The agent directory is shown as `<agent-dir>` below. Set its location with the `APEX_CODE_CODING_AGENT_DIR` environment variable or the SDK's [`agentDir`](sdk.md) option.
+
+| Path | Responsibility |
+|---|---|
+| `<agent-dir>/settings.json` | User-level [settings](settings.md), including preferences, defaults, resource paths, and Apex Code package declarations. |
+| `<agent-dir>/keybindings.json` | Custom terminal UI and application [keybindings](keybindings.md). |
+| `<agent-dir>/models.json` | [Compatible endpoints, models, and model overrides](models.md#configure-a-compatible-endpoint). |
+| `<agent-dir>/auth.json` | Saved API keys and OAuth credentials. |
+| `<agent-dir>/AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, or `CLAUDE.MD` | User instructions applied across working directories. |
+| `<agent-dir>/SYSTEM.md` | Replaces Apex Code’s default system prompt. |
+| `<agent-dir>/APPEND_SYSTEM.md` | Adds instructions to Apex Code’s system prompt. |
+| `<agent-dir>/extensions/` | User [extensions](extensions.md). |
+| `<agent-dir>/skills/` | User [skills](skills.md) and supporting files. |
+| `<agent-dir>/prompts/` | User [prompt templates](prompt-templates.md) exposed as slash commands. |
+| `<agent-dir>/themes/` | User [theme](themes.md) files. |
+
+## Project `.apex-code` directory
+
+| Path | Responsibility |
+|---|---|
+| `.apex-code/settings.json` | Project-level [settings](settings.md), resource paths, and Apex Code package declarations. |
+| `.apex-code/SYSTEM.md` | Replaces the system prompt for the project. |
+| `.apex-code/APPEND_SYSTEM.md` | Adds project-specific instructions to the system prompt. |
+| `.apex-code/extensions/` | Project extensions. |
+| `.apex-code/skills/` | Project skills and supporting files. |
+| `.apex-code/prompts/` | Project prompt templates exposed as slash commands. |
+| `.apex-code/themes/` | Project theme files. |
+
+For `SYSTEM.md` and `APPEND_SYSTEM.md`, the trusted project file takes precedence over the corresponding agent-directory file. Files with the same name are not combined.
+
+## Context files
+
+Context files are separate from project `.apex-code` configuration. Apex Code loads them from the agent directory, the working directory, and its parent directories. A context file applies whenever Apex Code runs in its directory or anywhere below it.
+
+An `AGENTS.override.md` replaces `AGENTS.md` or `CLAUDE.md` only in the same directory. It does not suppress context files from the agent directory or other directories.
+
+Context-file discovery does not require project trust.