SessionAdapter

def initial_state(self, metadata: SessionMetadata) -> AdapterState:
    """Empty state for a fresh session."""
    ...

def fold(self, envelope: Envelope, state: AdapterState) -> AdapterState:
    """Append ``envelope`` into the derived state. Pure function.

    Called once per WAL append by the hub. Must be deterministic so
    ``Hub.hydrate()`` can re-fold from disk.
    """
    ...

def validate_create(self, metadata: SessionMetadata) -> None:
    """Raise on invalid creation (bad participant count, missing knobs, ...)."""
    ...

def validate_send(
    self,
    metadata: SessionMetadata,
    envelope: Envelope,
    state: AdapterState,
) -> None:
    """Raise if this envelope is not allowed by the protocol at this point.

    Receives state BEFORE ``fold(envelope, ...)`` runs.
    """
    ...

def on_accepted(
    self,
    metadata: SessionMetadata,
    envelope: Envelope,
    state: AdapterState,
) -> AdapterResult:
    """Decide post-accept transitions.

    Receives state AFTER ``fold(envelope, ...)`` has run.
    """
    ...

def default_view_policy(
    self,
    metadata: SessionMetadata,
    participant_id: str,
) -> ViewPolicy:
    """Per-participant default projection for this session type."""
    ...

def extract_turn_input(self, envelope: Envelope) -> "str | Input | list[Input] | None":
    """Decode an inbound substantive envelope into the input the
    next speaker's LLM should receive on its turn.

    Return ``None`` (or empty string) for envelopes this adapter
    doesn't act on — the handler will skip the round.

    The default behaviour (``default_extract_turn_input``) handles
    ``EV_TEXT``. Adapters that emit additional substantive event
    types (e.g. ``EV_PACKET`` for the workflow adapter) override
    to decode those.
    """
    ...

def build_round_envelope(
    self,
    metadata: SessionMetadata,
    sender_id: str,
    reply: "AgentReply",
    events: "list[BaseEvent]",
    state: AdapterState,
    hub: "Hub",
) -> Envelope | None:
    """Build the envelope that captures one ``Agent.ask`` round.

    Called by the handler after ``Agent.ask`` returns. Adapters
    encode the round result into the envelope shape they expect:
    the default (``default_build_round_envelope``) emits
    ``EV_TEXT(reply.body)`` if non-empty, else ``None`` (silent
    round, no envelope posted).

    Returning ``None`` means "this round produced nothing worth
    recording" — the caller skips the post.
    """
    ...

def render_envelope(self, envelope: Envelope) -> str | None:
    """Project ``envelope`` to its LLM-visible string for view policies.

    Called by ``ViewPolicy.project`` once per envelope in the WAL
    slice the participant should see. Adapters that emit only
    ``EV_TEXT`` delegate to ``default_render_envelope``; adapters
    with richer round-end shapes (e.g. ``WorkflowAdapter`` with
    ``EV_PACKET``) handle their own types and fall through to
    the default for the universal cases.

    Returning ``None`` means "skip this envelope in the projection"
    (non-substantive event types, malformed payload, etc.).
    """
    ...