Behaviour and default implementation for conversation persistence in Planck.Agent.

Behaviour

Use use Planck.Agent.Hooks.Persistence to implement a custom persistence backend, in a sidecar or directly in your own app. Six callbacks are required — the first five are agent-scoped (an agent only ever touches its own history); the sixth, load_session_messages/2, is session-scoped, for callers outside any agent process that need every agent's history in one session, in original insertion order (e.g. a chat UI listing a whole conversation, orchestrator and workers together).

defmodule MyApp.Persistence.Postgres do
  use Planck.Agent.Hooks.Persistence

  @impl true
  def persist_message(session_id, agent_id, message) do
    # write `message`, return it with its own row id set on `message.id`
  end

  @impl true
  def persist_usage(session_id, agent_id, usage), do: :ok

  @impl true
  def load_messages(session_id, agent_id, opts) do
    # return {:ok, [Message.t()]} in insertion order, or :error
  end

  @impl true
  def flush_unpersisted(session_id, agent_id, messages) do
    # write any of `messages` not yet persisted; :flushed | :noop
  end

  @impl true
  def truncate_after(session_id, message_id), do: :ok

  @impl true
  def load_session_messages(session_id, opts) do
    # return {:ok, [session_row()]} for every agent in the session,
    # interleaved by insertion order, or :error
  end
end

Dispatch

Planck.Agent calls the first five (never the concrete Planck.Agent.Session/SessionStore modules directly) anywhere it needs to touch storage:

Hooks.Persistence.persist_message(state.persistence, state.session_id, state.id, msg, state.sidecar_node)

load_session_messages/2 is never called by Planck.Agent itself — it exists for a caller like planck_headless (which knows a session's resolved persistence module from the team that materialized it) to hand a UI a cross-agent history without going through any single agent process, so it works for closed sessions too:

Hooks.Persistence.load_session_messages(module, session_id, sidecar_node)

Ephemeral agents (session_id: nil) never reach a persistence module at all — every agent-scoped dispatcher function no-ops before dispatching, the same way Planck.Agent.SessionStore does today.

• module: nil — uses Planck.Agent.Hooks.Persistence.Default, the built-in SQLite-backed strategy (Planck.Agent.Session/SessionStore, wrapped to satisfy this behaviour). Not special-cased beyond this: Default satisfies the same behaviour a custom module would.
• module set, sidecar_node: nil — calls the resolved module in-process.
• module set, sidecar_node set — calls the module on the remote node via RPC; falls back to Default on :badrpc from any of the six calls.

The default RPC timeout is 5000 ms; override persistence_timeout/0 to declare a custom expected latency.