Session

One conversation with the agent.

Class in muse_code

A session folds every server event into readable state — items, turns, session facts, pending approvals — and submits your side of the exchange. Get one from start_session or resume_session, then send_user_turn to talk, turn to follow a turn’s items to its outcome, and on_approval to answer permission requests.

Constructor

Session(session_id: str, durability: SessionDurabilityProfile, *, connection: Connection | None = None, discarded: DiscardedSessions | None = None, opening: SessionOpening | None = None)

Constructor parameters

Name	Type	Description
session_id		The server-named session id every event must carry.
durability		Whether this session survives its host. Required, not defaulted: it decides what happens to every in-flight item and command when the host dies, and a default would let a caller skip reading the handshake and silently inherit the wrong obligation. read_session_durability turns an InitializeResult into it.
connection		The wire seam the submit verbs author through. OPTIONAL because fold-only construction is a real current use: every transport-less arm in this package builds a Session with no host at all.
discarded		What an ephemeral host death already discarded, shared across the sessions ONE client opened. Omitted, this session remembers only its own discards.
opening		Set by MuseClient; see SessionOpening.

Properties

Property	Type	Description
durability	SessionDurabilityProfile	The profile this session discharges a host death under.
fold	SessionFoldView	The read view of the fold; events enter through apply so turn routing cannot be skipped (the mutators are off this surface).
pending	PendingCommandView[_I]	The set’s read/safe-drive view. The three mutators Session drives itself and the two re-exposed as session methods are hidden; drive those through this session’s verbs, which keep the submitter’s replay memory in step.
known_turn_count	int	How many turns this session has minted a handle for.

Methods

Method	Signature	Description
apply	apply(event: Mapping[str, Any]) -> SessionApplyOutcome[_I]	Fold one view event, then fan it out to the turn handles that want it.
on_gap_error	on_gap_error(handler: GapFillFailureHandler) -> None	Observe fills that did not complete. See MuseGapFillError.
turn	turn(turn_id: str) -> Turn	The handle for a turn, created on first mention from either side.
host_exited	host_exited(exit_notification: HostDeathNotification) -> HostDeathDischarge[_I]	A host process exited or the transport reached EOF; classify it, and discharge if the profile demands it.
send_user_turn	async send_user_turn(options: SendUserTurnOptions[_I]) -> Turn	Submit a user turn and hand back THIS session’s handle for the turn the ack named.
on_approval	on_approval(handler: ApprovalHandler) -> None	Answer approvals with handler. See ApprovalRouter.
on_approval_error	on_approval_error(handler: ApprovalFailureHandler) -> None	Observe round trips that did not complete. See ApprovalFailure.
stop_retrying	stop_retrying(command_id: str) -> PendingRetirement[_I] | None	Stop the retry loop for one entry and take its input back (“Abandoned”).
replay_answered	replay_answered(command_id: str, answer: ReplayAnswer[_I]) -> PendingRetirement[_I] | Literal['held']	Feed a consumer-driven replay’s answer through the live settlement rules. "held" means the answer settled nothing.
resolve_snapshot_join	async resolve_snapshot_join(facts: SnapshotJoinFacts) -> tuple[PendingRetirement[_I], ...]	Resolve a snapshot join by performing the I/O its plan demands: same-commandId resubmits FIRST, then the replays, then the reclaimed-signature verdict.
resolve_reconnect	async resolve_reconnect() -> tuple[PendingRetirement[_I], ...]	Resolve a reconnect with NO snapshot (the default cursor-resume path): replay each acked entry once, resubmit each unacked entry’s same commandId once.

Source

clients/sdk-py/src/muse_code/facade/session.py:356