@callback consumer(conn()) :: pid() | nil

The linked process consuming the stream on conn's behalf, if any. nil when there is no live consumer (e.g. :request_response, or a not-yet-consolidated resume).

@callback kickoff_input(opts :: keyword()) :: input()

Input that kicks off the conversation (the initial user message).

@callback normalize([event()]) :: ReqManagedAgents.TurnResult.t()

Fold a turn's accumulated events into the canonical turn outcome (carries raw events).

@callback open(opts :: keyword(), subscriber :: pid()) :: {:ok, conn()} | {:error, term()}

Establish the connection/session; for :streaming, open the event stream to subscriber.

@callback pending_tool_uses([event()]) :: [ReqManagedAgents.ToolUse.t()]

Optional — recover unanswered custom tool uses from events (the session's full accumulated raw event history, oldest first).

A requires_action turn's per-batch normalize/1 can resolve to zero custom_tool_uses when the ids its own stop condition references live in an EARLIER, already-processed batch (the referencing idle and the tool uses it names don't always land in the same batch). When that happens, Session calls this callback instead of driving an empty resume — implement it the same way reconnect/3 recovers unanswered tool calls across a stream drop (e.g. via ReqManagedAgents.Consolidate.unanswered_tool_uses/1). Return [] when nothing is recoverable; Session then surfaces a loud protocol-state error rather than ever POSTing an empty events list.

Every use returned here is re-run at-least-once: Session re-invokes ReqManagedAgents.Handler.handle_tool_call/3 (or /4) for it regardless of whether that tool_use id was already dispatched earlier in the session — see ReqManagedAgents.Handler's moduledoc.

@callback poll_turn(conn(), input()) :: {:ok, [event()], conn()} | {:error, term()}

:request_response only — run one turn synchronously: send input, return the turn's events.

@callback provision(spec(), opts :: keyword()) :: {:ok, handle()} | {:error, term()}

Create (or look up) the provider-side agent resource for spec; return a durable handle.

@callback push_input(conn(), input()) :: :ok | {:error, term()}

:streaming only — post input; events arrive asynchronously at the subscriber.

@callback reconnect(conn(), subscriber :: pid(), seen :: MapSet.t()) ::
  {:ok, conn(), [ReqManagedAgents.ToolUse.t()], MapSet.t()} | {:error, term()}

:streaming only — after a stream drop, re-open the stream (delivering to subscriber) and return any unanswered tool calls to re-drive locally, plus the grown seen set.

@callback ref(conn()) :: reference() | nil

The live stream's tag conn carries, if any — Session matches inbound {:managed_agents, ref, _} messages against it. nil for a :request_response conn or a :streaming conn with no stream open yet (e.g. a not-yet-consolidated resume).

@callback resume_input(
  tool_uses :: [ReqManagedAgents.ToolUse.t()],
  results :: [ReqManagedAgents.ToolResult.t()]
) :: input()

Input that resumes the loop after local tools ran (the mode's resume contract).

@callback resumed?(conn()) :: boolean()

Whether open/2 consolidated an EXISTING session into conn (a resume) rather than creating a fresh one. Gates Session's reattach behavior (#66).

@callback session_id(conn()) :: String.t() | nil

The provider-side session id conn carries, if any (Session surfaces it in SessionResult/SessionInfo; nil when the concept doesn't apply).

@callback supports_outcomes?() :: boolean()

Optional — true when the provider natively honors the :outcome kickoff (user.define_outcome).

@callback teardown(handle(), opts :: keyword()) :: :ok | {:error, term()}

Delete the provider-side resource named by handle. opts carries the client / test seam.

@callback text_delta(event()) :: String.t() | nil

Optional — map ONE raw event to a normalized text chunk, or nil.

When implemented, the Session emits %{"type" => "rma.text_delta", "text" => chunk} through handle_event immediately after forwarding the raw event (additive normalization: alongside, never instead of, the raw event; never stored in SessionResult.events). Chunk granularity is whatever the provider's wire exposes — true streaming deltas on AgentCore (contentBlockDelta), whole message blocks on Claude Managed Agents (agent.message).

@callback turn_boundary?(event()) :: boolean()

:streaming only — does this event close a turn (so accumulated events form one)?

@callback user_input(text :: String.t()) :: input()

Input for a follow-up user message into a running session.