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

Behaviour

Use use Planck.Agent.Compactor to implement a custom compaction strategy. The only required callback is compact/2; compact_timeout/0 has a default implementation of 120000 ms.

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

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

  # Optional — override to declare a custom RPC timeout.
  @impl true
  def compact_timeout, do: 60_000
end

Building an on_compact function

build/2 is the single entry point for both the local LLM-based compactor and remote sidecar compactors. When sidecar_node: and compactor: options are absent it runs locally; when both are present it calls the remote module via :rpc.call/5 and falls back to the local compactor if the RPC fails.

# Local (default):
on_compact = Planck.Agent.Compactor.build(model)

# Remote sidecar:
on_compact = Planck.Agent.Compactor.build(model,
  sidecar_node: :planck_sidecar@localhost,
  compactor:    "MySidecar.Compactors.Builder"
  # The string is converted to the atom :"Elixir.MySidecar.Compactors.Builder"
  # before the RPC call. Always use the bare Elixir module name (no "Elixir." prefix).
)

Both return a fn messages -> closure of arity 1, as expected by Planck.Agent.

Compaction strategy (local default)

When triggered, the oldest messages (everything except the last keep_recent messages) are summarised into a single {:custom, :summary} message. On LLM failure the local compactor falls back to the original message list unchanged (:skip). On remote failure the local compactor is used as the fallback.