# Compaction pipeline (v0.4)

When the conversation's estimated tokens crosses `compact_at` (default
60% of the provider's `max_tokens`), the loop runs the compaction
pipeline before the next iteration.

The default pipeline mirrors Claude Code's five-layer design from the
[paper](https://arxiv.org/abs/2604.14228): cheap deterministic stages
run first, the expensive LLM-summary stage runs only when those
couldn't get the conversation under target.

```
state.messages
  ↓
[BudgetReduction] → drop oversized tool-result bodies
  ↓
[Snip]            → drop stale tool-result bodies (already integrated)
  ↓
[Microcompact]    → collapse runs of 3+ adjacent same-tool results
  ↓
[ContextCollapse] → non-destructive view-time projection
  ↓
[Summary]         → LLM summary of the middle of history
  ↓
state.messages (or state.meta[:compact_view])
```

Each stage is a module implementing `ExAthena.Compactor.Stage` with
`compact_stage/2` and `name/0`. The pipeline orchestrator
(`ExAthena.Compactor.Pipeline`) walks the list with `Enum.reduce_while`
and short-circuits once estimated tokens fall below target. Every
stage runs inside its own
`[:ex_athena, :compaction, <:stage_name>, :start | :stop]` telemetry
span.

## Built-in stages

### `Compactors.BudgetReduction`

Cheap, deterministic. For each tool-result message whose content
exceeds `:per_tool_result_max_chars` (default 16k), replace the body
with `[truncated; full=N chars; ref=<id>]` and persist the original
to `state.meta[:tool_result_archive]` keyed by `ref`.

This single stage often gets the conversation under target on its own
when one outlier tool produced a giant response (a `Read` of a 100KB
file, a `Bash` `grep` over a huge tree).

### `Compactors.Snip`

Cheap, deterministic. Drops stale tool-result bodies older than
`:snip_age_iterations` turns (default 4) whose paired assistant turn
already happened. Each is replaced with a `<snipped: stale tool-result
for call <id>>` marker — pairing-by-id stays intact.

Memory + skill messages and the live suffix are never touched.

### `Compactors.Microcompact`

Medium cost, deterministic. Runs of 3+ adjacent tool-result messages
collapse into a single elided summary tagged `name: "microcompact"`.
The summary lists each call's id + first 200 chars of its result.

### `Compactors.ContextCollapse`

Medium cost, *non-destructive*. Builds a projected message list for
the *next* request only — the authoritative `state.messages` is never
mutated. The projection collapses two patterns:

- **Superseded reads**: a `Read` whose file was later edited collapses
  to a `<read superseded by later edit: <path>>` stub.
- **Repeated identical tool calls**: same tool name + same args
  consecutive (skip-tool-results-aware) get a `(repeat)` marker on the
  follow-up call.

Stored at `state.meta[:compact_view]`. Resume / replay / rewind read
the original `state.messages`, so they stay correct.

### `Compactors.Summary`

Expensive — runs an LLM call. The middle of the message list is
summarised into a single assistant message tagged `name:
"compactor_summary"`. Cost counts against the run's budget. Only fires
when the deterministic stages couldn't get the conversation under
target.

## Reactive recovery

When a mode returns `{:error, :error_prompt_too_long}` (e.g. the
provider explicitly said "context too long"), the loop runs the
pipeline with `force: true` — every stage attempts compaction
unconditionally, regardless of estimated tokens. The same iteration is
then retried once. If still over (or compaction itself errors), the
run terminates with a typed `:error_prompt_too_long` capacity
termination (PR0 finish-reason).

Gated by `:reactive_compact` (default `true`):

```elixir
ExAthena.run("explore the repo", reactive_compact: false)  # opt out
```

## Configuration

### Per-call

```elixir
ExAthena.run("…",
  compact_at: 0.5,                  # trigger at 50% instead of 60%
  per_tool_result_max_chars: 8_000,
  snip_age_iterations: 8,
  microcompact_run_threshold: 5,
  compaction_pipeline: [
    ExAthena.Compactors.BudgetReduction,
    ExAthena.Compactors.Summary    # skip the others
  ])
```

### Global

```elixir
config :ex_athena, :compactor,
  compact_at: 0.6,
  pinned_prefix_count: 1,
  live_suffix_count: 6,
  per_tool_result_max_chars: 16_000,
  snip_age_iterations: 4
```

### Custom stages

Implement `ExAthena.Compactor.Stage`:

```elixir
defmodule MyApp.Compactors.DropImages do
  @behaviour ExAthena.Compactor.Stage

  @impl true
  def name, do: :drop_images

  @impl true
  def compact_stage(%ExAthena.Loop.State{} = state, estimate) do
    new_messages =
      Enum.map(state.messages, fn
        %{role: :user, content: content} = msg when is_binary(content) ->
          if String.contains?(content, "<image>"),
            do: %{msg | content: "<image elided>"},
            else: msg

        msg ->
          msg
      end)

    if new_messages == state.messages do
      :skip
    else
      {:ok,
       %{state | messages: new_messages},
       %{estimate | tokens: ExAthena.Compactor.estimate_tokens(new_messages)}}
    end
  end
end

ExAthena.run("...",
  compaction_pipeline: [
    MyApp.Compactors.DropImages,
    ExAthena.Compactors.BudgetReduction,
    ExAthena.Compactors.Summary
  ])
```

Stages should be **idempotent** — the reactive-recovery path may run
the pipeline a second time with `force: true`. Returning `:skip` on a
second pass is the canonical way to be idempotent.

## Hooks

- `:PreCompact` — fires before the pipeline runs at all.
- `:PreCompactStage` — fires before each individual stage. Payload:
  `%{stage: atom(), estimate: %{tokens, max_tokens}}`.
- `:PostCompact` — fires after a successful compaction. Payload:
  `%{metadata: %{before, after, dropped_count, stages_applied, reason}}`.

## Pinning rules

The compactor never drops:

- Messages in the **pinned prefix** — `:pinned_prefix_count` slots
  (default 1) at the front, *plus* any memory + pre-loaded skill
  messages (PR1).
- Messages in the **live suffix** — `:live_suffix_count` slots
  (default 6) at the tail.

Memory + skill messages tagged `name: "memory"` / `name: "skill:<name>"`
are pinned by default. Hosts can pin custom messages by extending
`pinned_prefix_count`.

## See also

- [`ExAthena.Compactor.Pipeline`](https://hexdocs.pm/ex_athena/ExAthena.Compactor.Pipeline.html)
- [`ExAthena.Compactor.Stage`](https://hexdocs.pm/ex_athena/ExAthena.Compactor.Stage.html)
- [Hooks reference](hooks_reference.md) — `PreCompact*` / `PostCompact`
  payload shapes.
- [Memory + skills](memory_and_skills.md) — what gets pinned.