@bastani/atomic 0.9.18 → 0.9.19-alpha.10

package/docs/background-tasks.md

@@ -0,0 +1,232 @@
+---
+title: "Background and parallel work"
+description: "Run subagents and shell tasks while continuing your conversation"
+---
+
+# Background tasks
+
+Background subagents keep working after the launch call returns. You can continue chatting without restarting them or keeping a task list open.
+
+In main chat and live workflow-stage chat, a compact indicator appears **below the prompt box and MCP status**, and above the workflow `BACKGROUND` widget when present:
+
+```text
+Tasks  2 local agents running · 1 queued · /tasks
+```
+
+It summarizes only active background agents and shells, including queued work, stopping tasks, and tasks needing attention. Completed, failed, and stopped tasks leave the footer immediately; when no background work is active, the indicator disappears. Results and failure details remain in completion cards and `/tasks`, so an old failure cannot keep the live indicator red. Running tasks do not expire merely because they are quiet.
+
+Run `/tasks` to open a compact inline picker in the editor slot, like `/workflow connect`, with the conversation still visible above it. Detail, transcript, input, and cancellation-confirmation pages use the full screen. Escape returns to the picker with the selected task preserved, then to chat. The command also appears in workflow-stage slash suggestions, including when skill commands are disabled. Foreground-only commands do not appear. Work that ran in the background stays available after completion or a later foreground wait. Updates never open the list automatically. Closing the inspector does not stop the tasks.
+
+Main and workflow-stage pickers use the same layout for empty and populated lists. Below the picker, the footer keeps that chat's resolved model and reasoning level, current folder and Git branch, and MCP status, including while its foreground turn streams. Each picker lists only its owner's tasks.
+
+Opening `/tasks` is navigation, not an approval request. It does not mark the agent blocked in Herdr or produce a "Main chat needs input" notice. A genuine main-chat question waiting behind the workflow graph still shows that notice until answered or the graph is hidden or closed. The inspector stays open until you close it, even when its tasks finish; task history is not deleted when the compact indicator disappears.
+
+## Choose how long to wait
+
+The agent can choose foreground-first or background observation for each authorized shell or subagent call. Choosing a mode does not require a separate user confirmation and does not relax tool permissions or task ownership.
+
+For ordinary shell commands, leave `wait` out rather than routinely requesting one-second waits. Short waits can background otherwise brief commands and add follow-up calls without speeding up execution. Use explicit background observation when you have independent work to do, and a short budget only when you need control back sooner. Explicit budgets remain supported on every platform.
+
+Keep immediately blocking work local unless a specialist, isolated context, or your explicit delegation request makes a subagent worthwhile. After spawning, continue independent work without duplicating the child's task. Wait when its result becomes a dependency; otherwise rely on completion notices rather than repeated short waits or status polls.
+
+| Call | Observation behavior |
+| --- | --- |
+| `bash` or `powershell` without `wait` | Waits for the owner's command observation budget, normally 10 seconds, then automatically returns if still running. |
+| `subagent` without `wait` | Returns after admission; the child runs in the background by default. |
+| Any of these tools with `wait: { kind: "background" }` | Explicitly returns after admission without waiting for execution to finish. |
+| Any of these tools with `wait: { kind: "foreground" }` | Waits for the owner's observation budget, normally 10 seconds for shells and 30 seconds for agents. |
+| Any of these tools with `wait: { kind: "foreground", budgetMs: 1000 }` | Waits up to one second, then automatically yields if the original task is still running. |
+
+If the task finishes during observation, the call returns its terminal result instead. Automatic backgrounding is **observation expiry**, not a slow-task failure, a restart, or a second execution. Use foreground-first observation for a dependency and background observation for independent work. If a dependency yields, wait for its actual completion before using the result.
+
+Shell `budgetMs` accepts finite non-negative milliseconds; zero means no observation delay. On command launches it belongs inside a foreground `wait`; existing-task `action: "wait"` calls take it at the top level. A trusted SDK host can override the usual budgets or select `tasks.wait.kind: "until-settled"`; omitted foreground budgets then wait until settlement. Explicit per-call budgets still take precedence.
+
+Native observation timers run independently of JavaScript. A zero-budget wait can already be backgrounded by the time a caller reads the next task snapshot, even before JavaScript awaits the result. Synchronous wait registration does not guarantee a visible foreground interval. The elapsed result still identifies the same wait and task; execution continues.
+
+## Background subagents
+
+Ask Atomic to delegate a bounded task:
+
+```text
+Have a codebase-analyzer trace the authentication flow in the background.
+Keep working with me here while it runs.
+```
+
+For tool callers, owner-bound launches default to background observation. Explicit examples:
+
+```ts
+subagent({
+  agent: "codebase-analyzer",
+  task: "Trace the authentication flow. Do not edit files.",
+  wait: { kind: "background" },
+})
+
+subagent({
+  tasks: [
+    { agent: "codebase-analyzer", task: "Trace request authentication." },
+    { agent: "codebase-pattern-finder", task: "Find authorization test patterns." },
+  ],
+  concurrency: 2,
+  wait: { kind: "background" },
+})
+```
+
+Parallel tasks have independent identities. Accepted work beyond the concurrency limit stays queued. Use `/agents` to browse available definitions before choosing an agent.
+
+Intercom communication does not cancel a parallel batch. A blocking ask or supervisor decision waits only in the requesting child and resumes that same execution after the matching reply. Sends and progress updates remain nonblocking. Foreground observations may yield so the parent can reply; execution concurrency, queued siblings, and task identities are preserved. Stop a selected task explicitly, or close its owner to cancel all owned work.
+
+A launch result says **Launched in background**. This records what happened at launch; it is not a permanently live status label. The below-prompt indicator and `/tasks` show the current state.
+
+### Waiting is not restarting
+
+When specialist delegation is useful and its result is needed next, use foreground observation:
+
+```ts
+subagent({
+  agent: "codebase-analyzer",
+  task: "Trace the authentication flow.",
+  wait: { kind: "foreground", budgetMs: 30000 },
+})
+```
+
+If that observation budget expires, the same child continues in the background. It is not an execution timeout. Observe the task ID returned by the original call:
+
+```ts
+subagent({ action: "wait", id: taskId })
+subagent({ action: "status", id: taskId })
+```
+
+Do not launch a duplicate just to retrieve its result. Use the task ID returned at launch. IDs are scoped to the session or workflow stage that owns them.
+
+Foreground subagent launches and explicit `action: "wait"` calls also yield when user steering or an Intercom ask/send is admitted to the waiting parent, in main chat or a live workflow stage. The message stays in the normal delivery queue so the parent can handle it and reply. This releases only observation: children keep running under the same task IDs, and other owners' waits are unaffected.
+
+### Completion messages
+
+Completion creates a shaded notification card in the owning chat without depending on a model reply. It uses the chat theme's card background and padding, with a colored outcome, the agent or shell name, and an available result preview:
+
+```text
+✓ Subagent codebase-analyzer completed: Trace the authentication flow.
+  Authentication starts in …
+/tasks to inspect
+```
+
+The parent model also receives the result context. The internal receipt stays in structured message details, rather than becoming raw JSON in chat. The same persisted completion identity handles delivery retries without relaunching the child. Workflow completions remain in their owning stage chat, not the main conversation.
+
+Stopping a subagent through `/tasks` (`x`, then `y`) also delivers a **stopped** card and stop context to the parent model. The notice arrives after termination is confirmed, not while the task is merely **Stopping**, and does not require a final response from the child. Cancelling queued work notifies without starting it. Repeated stop requests or late child results do not duplicate the notice or overwrite the recorded outcome; a task that finished before cancellation keeps its actual result. Closing the owning session or workflow stage still suppresses late notices.
+
+Restored completions may have only an outcome and task identity if the original live task or transcript is unavailable. Atomic does not invent missing output. Excerpts are bounded; inspect retained history for more detail.
+
+Long titles and previews are truncated or wrapped within the card width. Its background covers the ellipsis, expand hint, and trailing padding on every row.
+
+## Inspect tasks
+
+| View | Controls |
+| --- | --- |
+| Task list | Up/Down selects; Enter opens detail; Escape returns to chat. |
+| Task detail | Up/Down selects an action; Enter activates it; PageUp/PageDown scrolls the body. |
+| Transcript | Up/Down scrolls; PageUp/PageDown moves one viewport; PageUp at the top loads earlier history; Home/End jumps within loaded history. |
+| Go back | Left or Escape returns from transcript to detail, then from detail to the list. |
+| Stop | `x` requests cancellation; confirm with `y`, or keep running with `n` or Escape. |
+| Shell input | Select Input when offered; Enter sends the text plus a newline; Escape leaves input mode. |
+
+Configured task bindings take precedence over the default Left, page, and `x` shortcuts. Input mode receives ordinary typing, including `x`, without stopping the task. The footer shows the applicable controls.
+
+The list groups **Agents** and **Shells**, with counts and status symbols. Detail views pin identity, state, available metrics, and the selected action while their body scrolls. Missing metrics are omitted rather than displayed as zero. Recorded zero values remain visible.
+
+Agent rows and completion cards show the resolved model and reasoning setting, for example `openai-codex/gpt-6-astra · thinking medium`. These settings update on fallback and remain after completion. Foreground results retain the same metadata. Missing settings are not inferred from token counts; early launch receipts may not yet have a resolved model.
+
+Agent details include recent retained tool activity, the prompt, a latest-response preview, and error or attention information. Transcript inspection uses a dedicated scrolling view with a pinned title, line position, and controls, rather than nesting full chat components inside a detail box. It renders retained messages and tool results without hidden reasoning or inline images. Earlier pages do not jump back to the latest page when background activity arrives.
+
+An open live transcript updates directly from the child's session events, including streaming assistant text and partial/final tool results. Shell output refreshes on task state updates, including updates received during an earlier output read. You do not need to leave and reopen the transcript. Reading earlier retained pages keeps your position while the live tail continues updating.
+
+Shell details show the command, available exit information, and a bounded output tail. The preview shows up to ten wrapped lines from the retained 8 KiB tail. Output gaps and omitted earlier content are labelled. An empty output stream says **No output available**. Shell transcript inspection exposes the retained tail, not an invented agent conversation or an unlimited log viewer.
+
+### States
+
+| State | Meaning |
+| --- | --- |
+| Queued | Admitted, waiting for execution capacity. |
+| Running | Execution is live, including when the parent has stopped waiting. |
+| Input needed | An owned prompt needs attention. Open question is offered when a host route is available. |
+| Stopping | Cancellation was requested; termination has not yet settled. |
+| Completed | Execution finished successfully. |
+| Failed | Execution ended with an error. Details retain the error message. |
+| Stopped | Execution was cancelled. Completed work is not undone. |
+
+Completed, failed, and stopped tasks retain inspection but do not offer execution controls. **Foreground wait** observes a running task; it does not transfer ownership or create a second execution.
+
+## Background shells
+
+Top-level model `bash` calls on POSIX and native Windows, and `powershell` calls on native Windows, use the session's task owner. A long command can outlive its foreground observation budget and return a task ID while continuing to run. Its status then appears below the prompt and under **Shells** in `/tasks`. An explicit execution timeout still ends the command; it is separate from observation yielding.
+
+```ts
+// Ordinary commands use the owner's observation budget, normally 10 seconds.
+bash({ command: "npm run check" })
+
+// Background a build when you can do independent work while it runs.
+bash({ command: "npm run build", wait: { kind: "background" }, timeout: 600 })
+
+// Wait longer when the test result is needed next; execution timeout is separate.
+bash({ command: "npm test", wait: { kind: "foreground", budgetMs: 30000 }, timeout: 600 })
+```
+
+The shell execution timeout is separate: `timeout` is seconds and defaults to 300, with a maximum of 3600. It continues counting after backgrounding. Choose a timeout appropriate for the command; reducing `budgetMs` does not shorten or extend it. Use the returned task ID to inspect or stop the existing task through `/tasks`. Background completion notifies the parent automatically, so there is no need to launch the command again to collect its result.
+
+Observe an existing task without running its command again:
+
+```ts
+bash({ action: "wait", id: taskId })
+powershell({ action: "wait", id: taskId })
+```
+
+Use the original task ID from the same owning session or workflow stage. Omit `budgetMs` to use the owner's command observation policy, or pass `0` to poll. A wait returns retained output and a yielded or settled observation; settled results include available exit and failure details. While running, successive yielded waits advance through retained output in bounded pages, including after a session reload. A caught-up wait returns no output until more arrives. Settled waits return all retained output again, subject to labelled gaps and truncation, so they may repeat output you have already seen.
+
+Do not combine `action: "wait"` with `command`, `timeout`, `wait`, `env`, `cwd`, or `pty`. Existing-task waits require a supported task owner, even with custom execution adapters. Unknown or foreign IDs are rejected. Cancelling a wait or admitting user/Intercom messages releases observation only, not the command. Waiting never extends the original execution timeout or the owner's lifetime.
+
+### Stop a shell task from a tool call
+
+Use the `kill` tool with the exact task ID returned by `bash` or `powershell`, whether it launched explicitly in the background or automatically yielded:
+
+```ts
+kill({ id: taskId })
+```
+
+The same command works in main and workflow-stage chat. It selects the existing owned shell task; do not supply a process ID, shell name, or another owner's task ID. Unknown, malformed, foreign-owner, and subagent IDs are rejected. `/tasks` stop controls remain available.
+
+The response includes `taskId`, `decision`, `execution`, and `cleanup`. `cancellation-requested` means cancellation was requested, not that termination or cleanup has finished. A repeated call preserves that decision while reporting current state. `already-settled` means the task finished before cancellation and keeps its original outcome. Confirm `execution.kind: "settled"` and `cleanup.kind: "reaped"` before treating termination and cleanup as complete. Cleanup failures remain errors, not successful stops. Output and completion notifications remain available; killing a task does not erase its history.
+
+Shell completions use the same shaded card as subagents, with a retained output preview and available exit code. Nonzero shell exits are shown as failures even though the process itself reached a terminal state. Cancellation shows Stopped. The card and below-prompt count update in the owning main or workflow-stage chat.
+
+Native Windows owned shells use supervised pipes or ConPTY, with Job Object containment before execution resumes and confirmed cleanup. If containment cannot be established, launch is refused rather than falling back to unsupervised execution. The legacy Windows WSL `bash.exe` stdin transport remains unsupported for owned launch because Windows jobs cannot supervise Linux guest processes. Running Atomic inside WSL uses the normal POSIX/Bash path.
+
+Bash calls inside subagent sessions retain their existing execution paths. Without a supported task owner, explicit background requests are refused before execution; foreground calls wait for completion rather than automatically yielding. Custom operations adapters receive `wait` but must implement it themselves. External-terminal processes are not adopted into `/tasks`. A child's own tool use appears in that subagent's activity and transcript.
+
+## Lifetime and scope
+
+Background means independent of the current observation, not independent of its owner. **Pausing main chat** aborts the foreground turn only; its background agents and shells keep running. Detaching a workflow pane, ending a model turn, or closing `/tasks` also leaves owned background work alone.
+
+**Pausing a workflow stage** blocks new task launches immediately and cancels that stage generation's active and admitted queued agents and commands. Queued agents are cancelled before active cancellations free execution slots. Command setup already in flight may briefly start a shell during the pause transition; pause waits for those admissions, cancels the resulting shells, and confirms resource cleanup before completing. A successful pause leaves no owned active or queued executions. Cancellation or cleanup failures are reported instead of confirming pause. Main-chat tasks, sibling stages, and future stage generations are unaffected by a stage-scoped pause.
+
+Pause does not close the stage's message generation: queued user and Intercom messages remain held for resume. Resume permits fresh launches but never resurrects cancelled executions; retained task results remain inspectable. Closing a session or stage generation still cancels its remaining owned work. Explicit `/tasks` stop and declared execution timeouts remain separate controls.
+
+On native Windows, Suspend opens a PowerShell subshell rather than freezing Atomic. Exit the subshell to restore the same session; owned background tasks continue while it is open.
+
+Task inspection is owner-scoped. It is not a machine-wide process list. Switching sessions does not copy the previous session's task rows into the new one. Missing retained history is reported explicitly.
+
+Git branch watchers for alternate folders are shared by their chat footers and released when the last viewer closes or changes folders. Main chat and other open stage chats keep their live branch updates; closing `/tasks` alone leaves its chat footer active.
+
+## Task state and completion delivery
+
+Foreground and background describe observation, not different executions. Each admitted task keeps its identity and owning session as callers start or stop waiting. The native `wasBackground` field remains set after a designated wait yields, including after a later foreground wait or settlement.
+
+Execution outcome and resource cleanup are separate states. A terminal result does not by itself prove that resources were reaped. Cleanup failures remain explicit. Supervised shells retain output while running, and finish output draining as part of cleanup.
+
+Native integrations can use `TaskSupervisor.taskSettlement(task)` from `@bastani/atomic-natives` to retrieve an authentic terminal receipt without creating a new wait. This supports recovery when a bounded event journal no longer contains the completion event. Session-history completion intents and acknowledgements reuse the same identity when notification delivery is retried.
+
+UI previews are bounded and are not a substitute for retained output. Gaps and truncation are labelled; unavailable history is reported rather than reconstructed from activity counters.
+
+## Related documentation
+
+- [Subagents](/subagents) covers definitions, models, context, and delegation boundaries.
+- [Keybindings](/keybindings) covers task-action remapping.
+- [Workflows](/workflows) covers durable stage lifecycles.

package/docs/build.md

@@ -0,0 +1,51 @@
+---
+title: Build with Atomic
+description: Extend Atomic with skills, subagents, intercom, workflows, extensions, prompt templates, themes, packages, custom models and providers, and programmatic integrations.
+---
+
+# Build with Atomic
+
+Build covers everything you add to Atomic: customization mechanisms that change how a session behaves, and programmatic interfaces that embed Atomic in your own software.
+
+If you have not run Atomic yet, start at the [Quickstart](/quickstart). If you are looking for an exact contract rather than a way to build something, go to the [Reference index](/reference).
+
+## Choose the lightest mechanism
+
+Work down this list and stop at the first mechanism that solves your problem.
+
+1. [Prompt templates](/prompt-templates) — reusable prompts that expand from a slash command. No code.
+2. [Skills](/skills) — on-demand instructions the agent loads when a task matches. Markdown plus optional scripts.
+3. [Subagents](/subagents) — delegate a focused, bounded task to a child agent.
+4. [Intercom](/intercom) — coordinate several sessions on one machine.
+5. [Workflows](/workflows) — multi-stage, resumable engineering loops with gates and artifacts.
+6. [Extensions](/extensions) — TypeScript that adds tools, commands, events, and custom UI when nothing lighter fits.
+7. [Atomic packages](/packages) — bundle and distribute the result.
+
+## Change the model layer
+
+- [Custom models](/models) — add model entries for a supported provider API.
+- [Custom providers](/custom-provider) — implement a provider API or OAuth flow Atomic does not ship.
+- [Themes](/themes) — restyle the terminal interface.
+
+## Embed Atomic in your own software
+
+[Programmatic use](/programmatic) compares JSON mode, RPC, and the SDK, and links each one to its protocol or API reference.
+
+## Customization
+
+- [Extensions](/extensions) - TypeScript modules for tools, commands, events, and custom UI.
+- [Skills](/skills) - Agent Skills for reusable on-demand capabilities.
+- [Subagents](/subagents) - focused child agents for research, analysis, debugging, cleanup, and review compositions.
+- [Workflows](/workflows) - executable engineering loops with tracked stages, artifacts, gates, and resumable runs.
+- [Prompt templates](/prompt-templates) - reusable prompts that expand from slash commands.
+- [Themes](/themes) - built-in and custom terminal themes.
+- [Atomic packages](/packages) - bundle and share extensions, skills, prompts, and themes.
+- [Custom models](/models) - add model entries for supported provider APIs.
+- [Custom providers](/custom-provider) - implement custom APIs and OAuth flows.
+
+## Programmatic usage
+
+- [SDK](/sdk) - embed Atomic in Node.js applications.
+- [RPC mode](/rpc) - integrate over stdin/stdout JSONL.
+- [JSON event stream mode](/json) - print mode with structured events.
+- [TUI components](/tui) - build custom terminal UI for extensions.

package/docs/changelog.mdx

@@ -7,9 +7,9 @@ description: "What's new in Atomic"
 
 ## Pi 0.83.0 parity
 
-- **One door prints a stored credential.** `atomic auth print-api-key --model <model>` and `atomic auth print-bearer-token --model <model>` hand a configured credential to an external client. The credential is all that reaches stdout — warnings, provider selection, refresh notices, and help go to stderr — `--model` is required, and each failure has its own exit code, with stdout empty on every non-zero exit. `--min-expiry` accepts `ms`, `s`, `m`, or `h`, defaults to `30m`, and is a usage error on `print-api-key`, which has no expiry to wait for. See [Usage](/usage#credential-commands) and [Security](/security#credential-export).
-- **Extensions can read the session's model scope.** `ctx.scopedModels` reports the models scoped to the current session — the set `/scoped-models` shows — resolved at access time and correct under the isolated engine. It reports the scope and cannot widen it: the accessor is read-only, and every read hands back a frozen copy of the array, its entries, and their models, so neither pushing an entry nor swapping one in place reaches the session. `ScopedModel` and `ExtensionScopedModels` are exported so an extension can name what it read. See [Extensions](/extensions#ctxmodelregistry--ctxmodel--ctxscopedmodels).
-- **An unrecognised stop reason is now an error.** A provider that ends a turn with a terminal reason the mapping does not know surfaces a provider error naming the raw value instead of an ordinary successful stop, so a new truncation or safety signal is visible rather than silent. Streaming partials carry the new `pending` reason until the terminal event replaces it; a stream that ends still `pending` is an error. See [Providers](/providers#stop-reasons) and [Custom Providers](/custom-provider#stop-reasons).
+- **One door prints a stored credential.** `atomic auth print-api-key --model <model>` and `atomic auth print-bearer-token --model <model>` hand a configured credential to an external client. The credential is all that reaches stdout — warnings, provider selection, refresh notices, and help go to stderr — `--model` is required, and each failure has its own exit code, with stdout empty on every non-zero exit. `--min-expiry` accepts `ms`, `s`, `m`, or `h`, defaults to `30m`, and is a usage error on `print-api-key`, which has no expiry to wait for. See [Usage](/reference/cli#credential-commands) and [Security](/security#credential-export).
+- **Extensions can read the session's model scope.** `ctx.scopedModels` reports the models scoped to the current session — the set `/scoped-models` shows — resolved at access time and correct under the isolated engine. It reports the scope and cannot widen it: the accessor is read-only, and every read hands back a frozen copy of the array, its entries, and their models, so neither pushing an entry nor swapping one in place reaches the session. `ScopedModel` and `ExtensionScopedModels` are exported so an extension can name what it read. See [Extensions](/extensions/api-reference#ctx-modelregistry-/-ctx-model-/-ctx-scopedmodels).
+- **An unrecognised stop reason is now an error.** A provider that ends a turn with a terminal reason the mapping does not know surfaces a provider error naming the raw value instead of an ordinary successful stop, so a new truncation or safety signal is visible rather than silent. Streaming partials carry the new `pending` reason until the terminal event replaces it; a stream that ends still `pending` is an error. See [Providers](/providers/reference#stop-reasons) and [Custom Providers](/custom-provider/streaming#stop-reasons).
 - **OAuth tokens refresh before they expire.** A stored token with under five minutes of validity left is refreshed rather than used, so a long turn does not start on a credential that dies mid-request. The refresh runs under the `auth.json` lock and re-checks expiry inside it, so concurrent sessions sharing one credential file refresh it once between them. See [Providers](/providers#token-refresh).
 - **Remote OpenRouter logins have a way through.** When the browser cannot reach the loopback callback — over SSH, or on a headless host — the OpenRouter login accepts the final redirect URL, or the authorization code alone, pasted into the prompt. See [Providers](/providers#subscriptions).
 
@@ -18,10 +18,10 @@ description: "What's new in Atomic"
 
 ## Pi 0.82.1 parity
 
-- **Constrained tool sampling is public end to end.** Extensions and SDK tools can request strict JSON Schema (`prefer` or `require`) or OpenAI Lark/regex grammars. Atomic preserves exact optional-property identity during public inspection, and typed RPC model listings expose all four enforcement flags through optional `ModelInfo.compat`. Unsupported models never claim required enforcement. See [Extensions](/extensions#constrained-sampling), [Models](/models#constrained-tool-sampling), and [RPC](/rpc#get_available_models).
-- **Authentication and flagship catalogs expanded.** `/login openrouter` uses provider-owned browser PKCE with optional key minting, `/login kimi-coding` uses device authorization with automatic refresh, and isolated engine-only extension OAuth now supports safe descriptor discovery, correlated UI callbacks/cancellation, transactional engine persistence/refresh/rollback/logout, and no credential or executable-function transport. Intentional Escape/Ctrl+C/native-abort cancellation is quiet; genuine provider, network, token, storage, and refresh failures remain visible. Claude Opus 5 is available through Anthropic and Bedrock, while bearer-only `ANTHROPIC_AUTH_TOKEN` remains selectable across normal and isolated/RPC catalogs without emitting an API key or `x-api-key`. See [Providers](/providers) and [Custom Providers](/custom-provider#oauth-support).
-- **Catalogs and model configuration stay resilient.** Remote catalogs use ETag revalidation and accept empty `304` responses, newer bundled data beats stale overlays, and a validated persisted llama.cpp catalog remains selectable when the first online refresh after restart fails while Atomic still reports the original error; a later success replaces it. Opening `/model` reloads layered legacy `.pi` then primary `.atomic` configuration. See [Models](/models#catalog-freshness-and-precedence) and [llama.cpp](/llama-cpp).
-- **Bash integrations are session-aware and stream precisely.** Bash commands receive Atomic and exact Pi session/model environment aliases; unsaved sessions omit the file path. Direct RPC bash streams request-correlated stdout/stderr deltas, targeted/legacy cancellation, one terminal response, and exactly-once starting-session persistence across new/switch/import/fork/clone replacement; RPC shutdown drains active owners. See [Environment Variables](/environment-variables#bash-and-powershell-session-environment) and [RPC](/rpc#bash).
+- **Constrained tool sampling is public end to end.** Extensions and SDK tools can request strict JSON Schema (`prefer` or `require`) or OpenAI Lark/regex grammars. Atomic preserves exact optional-property identity during public inspection, and typed RPC model listings expose all four enforcement flags through optional `ModelInfo.compat`. Unsupported models never claim required enforcement. See [Extensions](/extensions/authoring#constrained-sampling), [Models](/models/reference#constrained-tool-sampling), and [RPC](/rpc/protocol#get_available_models).
+- **Authentication and flagship catalogs expanded.** `/login openrouter` uses provider-owned browser PKCE with optional key minting, `/login kimi-coding` uses device authorization with automatic refresh, and isolated engine-only extension OAuth now supports safe descriptor discovery, correlated UI callbacks/cancellation, transactional engine persistence/refresh/rollback/logout, and no credential or executable-function transport. Intentional Escape/Ctrl+C/native-abort cancellation is quiet; genuine provider, network, token, storage, and refresh failures remain visible. Claude Opus 5 is available through Anthropic and Bedrock, while bearer-only `ANTHROPIC_AUTH_TOKEN` remains selectable across normal and isolated/RPC catalogs without emitting an API key or `x-api-key`. See [Providers](/providers) and [Custom Providers](/custom-provider/oauth#oauth-support).
+- **Catalogs and model configuration stay resilient.** Remote catalogs use ETag revalidation and accept empty `304` responses, newer bundled data beats stale overlays, and a validated persisted llama.cpp catalog remains selectable when the first online refresh after restart fails while Atomic still reports the original error; a later success replaces it. Opening `/model` reloads layered legacy `.pi` then primary `.atomic` configuration. See [Models](/models/reference#catalog-freshness-and-precedence) and [llama.cpp](/llama-cpp).
+- **Bash integrations are session-aware and stream precisely.** Bash commands receive Atomic and exact Pi session/model environment aliases; unsaved sessions omit the file path. Direct RPC bash streams request-correlated stdout/stderr deltas, targeted/legacy cancellation, one terminal response, and exactly-once starting-session persistence across new/switch/import/fork/clone replacement; RPC shutdown drains active owners. See [Environment Variables](/environment-variables#bash-and-powershell-session-environment) and [RPC](/rpc/protocol#bash).
 - **Coding-agent parity fixes landed.** Custom message renderers receive `outputPad` in normal and isolated rendering; summaries use fresh routing IDs without prompt-cache writes; complete literal IDs win before thinking-suffix/glob parsing; unavailable scoped entries remain removable; shared async Ctrl+G editing uses a private exact `prompt.md`, configured/environment/platform precedence, and recursive cleanup across main and extension editors; `/copy` falls back after `wl-copy` failure; explicit update checks bypass startup-skip settings; configured agent directories own TUI logs; and context discovery ignores directories named like context files.
 
 </Update>
@@ -42,7 +42,7 @@ See [SDK](/sdk) and [Custom providers](/custom-provider).
 
 - **Synced through upstream Pi 0.80.6.** Atomic and its bundled extensions now use the 0.80.6 Pi runtime packages, including signed empty Anthropic thinking preservation, request-wide GPT-5.4/5.5 long-context pricing, and corrected GPT-5.6 catalog/backend metadata.
 - **Model controls are current.** Atomic accepts `max` wherever the active model advertises it, applies the active agent directory's single `models.json` overrides to matching extension-registered models and built-ins, and falls back instead of synthesizing removed catalog IDs on resume. See [Models](/models).
-- **Custom pricing tiers are preserved.** Custom `models.json` entries and extension providers can declare complete request-wide `cost.tiers`; matching `modelOverrides` can update scalar rates without losing inherited tiers or replace/clear the tier array explicitly. See [Models](/models#request-wide-cost-tiers) and [Custom Providers](/custom-provider#usage-and-cost).
+- **Custom pricing tiers are preserved.** Custom `models.json` entries and extension providers can declare complete request-wide `cost.tiers`; matching `modelOverrides` can update scalar rates without losing inherited tiers or replace/clear the tier array explicitly. See [Models](/models/reference#request-wide-cost-tiers) and [Custom Providers](/custom-provider/streaming#usage-and-cost).
 - **Safer session and tool behavior.** Invalid explicit bash timeouts fail instead of being clamped; missing exact session IDs warn before creation; lax null or omitted message content is normalized; auth writes surface persistence failures; Windows context traversal terminates at drive roots; and duplicate fork selections are ignored. See [Tools](/tools) and [Usage](/usage).
 - **More reliable streaming and binaries.** Visible custom messages stay before the live assistant row, standalone Linux clipboard reads can fall back to xclip with correctly packaged native bindings, caller-relative `TMPDIR` paths work from external directories, and `--skip-deps` tolerates a missing optional clipboard wrapper.
 

package/docs/compaction/reference.md

@@ -0,0 +1,267 @@
+---
+title: Compaction reference
+sidebarTitle: "Compaction internals"
+description: Compaction parameters, persistence, extension hooks, formats, settings, and historical formats.
+---
+
+# Compaction reference
+
+## Parameters
+
+The effective parameters appear in extension events and successful results:
+
+| Parameter | Default | Meaning |
+|---|---:|---|
+| `compression_ratio` | `0.5` | Fraction of compactable **lines to keep**, not a token ratio |
+| `preserve_recent` | `2` | Exact number of newest context-visible messages protected client-side |
+| `query` | Last visible user message | Relevance focus for deciding which older lines to retain |
+
+`preserve_recent` counts context-visible messages without aligning the boundary to a user turn. An assistant message or tool result may therefore begin the kept tail. Because such a tail can start or end mid-turn, the kept messages are not replayed as structured message blocks: they are serialized with the same transcript grammar as the compacted region and appended to the end of the boundary string, so the whole boundary reaches the provider as one message. Serialization of the kept tail is lossless — tool results keep their full text instead of being truncated at 16k characters, and images stay attached as image blocks rather than becoming `[image]` markers — so protected content is preserved, not merely summarized. A value of `0` protects no messages and makes the entire active transcript compactable. If `query` is absent, Atomic derives it from the last visible user message.
+
+One consequence is worth stating for Claude models that sign their reasoning. Because the kept tail is serialized into the boundary string rather than replayed as structured assistant messages, no `thinking` or `redacted_thinking` block survives a compaction boundary. Compaction therefore **intentionally resets the signed reasoning chain**: reasoning produced before a boundary is not carried across it. This is deliberate, and it is the first of the two remedies Anthropic documents for keep-tail compaction — carry the text and tool calls across, leave the thinking blocks behind — reached structurally rather than by a stripping pass. The tail's own content is unaffected: text, tool calls, and tool results cross the boundary losslessly. See [Preserved thinking and model switches](/models/reference#preserved-thinking-and-model-switches) for how Atomic handles prefix changes *between* boundaries, which is a separate mechanism.
+
+The query is used whole and is never truncated. This matters for structured prompts: a truncated query would make section order the retention policy, because only the leading section could influence what the planner kept, and a constraint stated later in the prompt could not. Long queries are safe — an oversized planner request surfaces as an explicit provider-overflow failure rather than silent truncation — but `keepContext` tags, not query length, are the way to guarantee a span survives.
+
+Configure defaults in `~/.atomic/agent/settings.json` or `.atomic/settings.json`:
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "compression_ratio": 0.5,
+    "preserve_recent": 2,
+    "query": "optional focus"
+  }
+}
+```
+
+`reserveTokens` controls the automatic threshold that decides when compaction runs; it is not converted into a classifier line ratio. Manual calls can pass parameter overrides through the SDK.
+
+### Per-model budgets
+
+Use `compaction.modelOverrides` to set `reserveTokens` and/or `preserve_recent` for an exact `"provider/modelId"` key. For example:
+
+```json
+{
+  "compaction": {
+    "reserveTokens": 16384,
+    "preserve_recent": 2,
+    "modelOverrides": {
+      "anthropic/claude-sonnet-4-5": { "reserveTokens": 32768, "preserve_recent": 4 }
+    }
+  }
+}
+```
+
+Each field falls back independently to the ordinary setting, then its built-in default. Keys are case-sensitive and do not support wildcards or reasoning suffixes. Both fields require non-negative safe integers. The active session model selects the budgets for manual, automatic, overflow, and post-tool compaction; switching models changes the next resolution, while borrowing a fallback planner does not. Explicit manual parameters take precedence over resolved defaults.
+
+Atomic intentionally differs from upstream pi: the recent-history override is an exact message count (`preserve_recent`), not a token budget (`keepRecentTokens`). Verbatim line reconstruction, `compression_ratio`, and `query` are unchanged; the latter two and `enabled` remain ordinary settings. See [Settings](/settings#compaction) for merge and validation details.
+
+## Persistence and resume
+
+A successful run appends the existing pi-style `type:"compaction"` entry shape:
+
+```json
+{
+  "type": "compaction",
+  "id": "c1",
+  "parentId": "m9",
+  "timestamp": "2026-07-13T10:00:00.000Z",
+  "summary": "[User]: fix the failing test\n(filtered 42 lines)\n[Assistant]: Fixed.",
+  "firstKeptEntryId": "m7",
+  "tokensBefore": 51234,
+  "details": {
+    "strategy": "verbatim-lines",
+    "promptVersion": 3,
+    "rung": "planned",
+    "parameters": {"compression_ratio": 0.5, "preserve_recent": 2, "query": "fix the failing test"},
+    "stats": {"linesBefore": 812, "linesDeleted": 417, "linesKept": 395, "rangeCount": 63, "tokensBefore": 51234, "tokensAfter": 24980, "percentReduction": 51.2}
+  }
+}
+```
+
+`details.rung` is one of `"planned"` (a model ranked the lines — the session model **or** a borrowed fallback, including silent partial recovery), `"extension"` (a `session_before_compact` override), or `"fresh"` (the compactable conversation was discarded and a new context window started). `details.plannerModel` is present **only** when a borrowed fallback model ranked the lines:
+
+```json
+"details": {
+  "strategy": "verbatim-lines",
+  "promptVersion": 3,
+  "rung": "planned",
+  "plannerModel": {"provider": "openai", "id": "gpt-5.1", "thinkingLevel": "high"}
+}
+```
+
+There is no format-version bump and no new entry type. Both `"fresh"` and `plannerModel` are additive: they are absent on every existing entry and on any compaction that used the session model, so old readers are unaffected. A `"fresh"` boundary that had to drop the `preserve_recent` tail persists `firstKeptEntryId: null`.
+
+A `compaction` entry is active only when `details.strategy === "verbatim-lines"`. On rebuild, Atomic emits one visible custom-role boundary message: the durable `summary` with the kept tail—the entries from `firstKeptEntryId` up to the boundary—serialized and concatenated onto its end. The tail is never restored as separate assistant/tool-result blocks, so a tail that starts or ends mid-turn cannot produce out-of-order provider blocks; images inside the tail ride along as image blocks on that same boundary message. When no pre-boundary context-visible message is retained—such as with `preserve_recent: 0`—`firstKeptEntryId` is `null` and the boundary carries the `summary` alone. Messages appended after the boundary are always replayed as real messages. The boundary is converted to a user-role provider message and shown in the TUI as a collapsible compaction card.
+
+Resume does not rerun planning or re-derive deletions: the exact compacted string and nullable tail boundary are already in JSONL. Existing records with a string `firstKeptEntryId` keep their original resume behavior. Legacy `context_compaction` logical-deletion records and old `compaction` summary records without the discriminator are inert archival data. Their historical omissions are not reapplied when an old session resumes.
+
+## Extension hooks
+
+### `session_before_compact`
+
+Extensions may cancel or provide a complete replacement for the prepared region:
+
+```typescript
+pi.on("session_before_compact", async (event) => {
+  const { reason, parameters, preparation, branchEntries, signal } = event;
+  if (signal.aborted) return { cancel: true };
+
+  // Optional offline override. It must contain non-whitespace text.
+  if (reason === "manual" && branchEntries.length > 100) {
+    return { compactedText: preparation.region.lines.slice(0, 40).join("\n") };
+  }
+});
+```
+
+`preparation` is a deep-frozen clone. An override changes only the compacted region text; Atomic retains the prepared boundary and persists the supplied text verbatim. Empty/whitespace text is rejected. The override path does not require provider credentials.
+
+### `session_compact`
+
+After persistence, Atomic emits an observe-only event:
+
+```typescript
+pi.on("session_compact", async (event) => {
+  console.log(event.result.rung, event.result.stats);   // rung: "planned" | "extension" | "fresh"
+  console.log(event.result.plannerModel);               // set only when a fallback model was borrowed
+  console.log(event.compactionEntry.details.strategy);  // "verbatim-lines"
+  console.log(event.fromExtension);
+});
+```
+
+Observer errors are isolated and cannot roll back the already-persisted boundary.
+
+### `session_compact_failed`
+
+A failed or cancelled manual, threshold, or overflow compaction emits an observe-only failure event:
+
+```typescript
+pi.on("session_compact_failed", async (event) => {
+  console.log(event.reason, event.errorMessage);
+  console.log(event.aborted, event.willRetry, event.fromExtension);
+});
+```
+
+`errorMessage` is absent for cancellation. `fromExtension` identifies failures after a `session_before_compact` handler supplied replacement text; no compaction boundary is persisted.
+
+## Branch Summary Format
+
+Branch summarization uses a 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 for Branch Summaries
+
+Before branch summarization, messages are serialized to text via [`serializeConversation()`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/core/compaction/utils.ts):
+
+```text
+[User]: What they said
+[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.
+
+## Extension Hooks for Branch Summarization
+
+### session_before_tree
+
+Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
+
+```typescript
+pi.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...",
+        details: { /* custom data */ },
+      }
+    };
+  }
+});
+```
+
+See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
+
+## Settings
+
+Configure compaction in `~/.atomic/agent/settings.json` or `<project-dir>/.atomic/settings.json` (legacy `.pi` paths are also supported):
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | Enable automatic Verbatim Compaction. |
+| `reserveTokens` | `16384` | Tokens to reserve for the next LLM response; threshold auto-compaction starts when completed-response usage or a prospective post-tool context exceeds the model's effective input budget minus this reserve. It is an **input-side** reserve only and never caps planner output. |
+
+Compaction has no configuration key of its own for fallback borrowing: it reuses `settings.fallbackModels`, the same ordered `provider/model[:thinkingLevel]` list that main-chat model fallback walks. With no `fallbackModels` configured, compaction behaves as before: one planner model, then either an honest failure (recoverable) or a fresh context window (load-bearing).
+
+Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
+
+## Historical formats
+
+Two old formats remain parseable but inactive:
+
+- `type:"context_compaction"` records store logical entry/content-block deletion targets from older versions. Those records are inert, so content they once hid can re-enter context when an old session resumes.
+- `type:"compaction"` without `details.strategy: "verbatim-lines"` stored generated summary prose. Those records also remain inert.
+
+Both are distinguished from active boundaries by the discriminated `details` on the shared `CompactionEntry` shape; the session format version is the same for all of them.