Behaviour and default implementation for context compaction in Planck.Agent.

Behaviour

Use use Planck.Agent.Hooks.Compactor to implement a custom compaction strategy in a sidecar. Two callbacks are required, compact?/3 and compact/3; compact_timeout/0 has a default of 600000 ms.

defmodule MySidecar.Compactors.Builder do
  use Planck.Agent.Hooks.Compactor

  @impl true
  def compact?(identity, ai_context, _recent) do
    Planck.AI.Context.estimate_tokens(ai_context) >= identity.model.context_window * 0.8
  end

  @impl true
  def compact(_identity, _ai_context, recent, _args) do
    summary = Message.new({:custom, :summary}, [{:text, summarise(recent)}])
    kept    = Enum.take(recent, -5)
    {:compact, summary, kept}
  end

  @impl true
  def compact_timeout, do: 60_000
end

compact?/3 is checked first; compact/4 — the potentially slow part, an LLM call for the built-in strategy — is only ever called when it returns true. Splitting these means the dispatcher (compact/4 below), not each implementation, can wrap the slow part with a progress announcement correctly for any compactor, without needing to predict anything — see "Why a separate compact?/3, and why the dispatcher wraps compact/4" below.

Dispatch

Planck.Agent calls compact/4 before every LLM turn:

Hooks.Compactor.compact(identity, hooks, ai_context, recent, opts)

• identity — the identity of the agent.

• hooks — the hooks with the compactor.

• context — the Planck.AI.Context.t() built for recent (system prompt, tool schemas, and recent itself, already estimated as one whole — see Planck.AI.Context.estimate_tokens/1). Passed through rather than just recent alone so a custom compactor (typically running on a sidecar node, which has no other way to see the agent's system prompt or tool list) can make an informed decision too, not only the built-in one.

• recent — agent.context.messages since the last {:custom, :summary} checkpoint (or all of them, if there isn't one yet).

• opts — :on_compacting and :on_compacted, both zero-arity functions, both optional. :args — a map (default %{prompt: nil}) forwarded to the compactor's compact/4 callback as its 4th parameter; used by /compact [prompt] to steer the summarization. The dispatcher reads the bypass flag from args.force (true for /compact, false for auto-compaction) before forwarding. Called by this dispatch function, around compact/4 — never by a compact/4 implementation itself, which never receives opts at all. Planck.Agent supplies on_compacting/on_compacted so the UI can be told compaction is in progress without any compactor needing to know anything about Planck.Agent's own PubSub topics or event shapes.

• hooks.compactor set, hooks.sidecar_node: nil — calls module.compact?/3, then, only if that's true, module.compact/3, in-process.

• hooks.compactor set, hooks.sidecar_node set — calls the module on the remote node via RPC (same two-call shape); falls back to Default on :badrpc from either call.

Why a separate compact?/3, and why the dispatcher wraps compact/3

Planck.Agent calls this dispatcher on every turn, and can't know in advance whether a given call will actually compact — that decision belongs to the compactor, and for a custom one, its criteria are opaque to Planck.Agent entirely. Broadcasting "compacting" unconditionally around every call (clearing it right after) would flash it on every ordinary turn, not just the rare one that actually compacts. Predicting the outcome from Planck.Agent's side (e.g. reapplying the built-in ratio) would only be accurate for the built-in compactor. Splitting the decision (compact?/3, always cheap — no LLM call for the built-in strategy) from the work (compact/3, potentially slow) lets the dispatcher check the decision first and only announce progress around the part that's genuinely slow — accurate for any compactor, without Planck.Agent needing to predict anything or any compactor needing to call back into Planck.Agent itself.