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 (its task obligation (c)). 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 pending 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 the protocol fills that did not complete. See MuseGapFillError.
turn	turn(turn_id: str) -> Turn[_I]	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 the protocol if the profile demands it.
send_user_turn	async send_user_turn(options: SendUserTurnOptions[_I]) -> Turn[_I]	Submit a user turn and hand back THIS session’s handle for the turn the ack named.
run	async run(prompt: RunInput, *, display_text: str | None = None, if_busy: IfBusy | None = None, reasoning_effort: ReasoningEffort | None = None, workspace_roots: List[str] | None = None, user_shell: TurnUserShell | None = None) -> RunResult	Run one turn to its end in a single call: submit prompt, wait for the server to end the turn, and return its outcome, final answer text, items and usage. Use send_user_turn to stream items or deltas as they arrive.
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.
answer_user_input	async answer_user_input(user_input_id: str, answers: Sequence[UserInputAnswer]) -> UserInputAnswerResult	Answer a question this session lists in fold.pending_user_inputs().
list_tasks	async list_tasks() -> TaskListResult	List this session’s live tasks (task/list).
list_skills	async list_skills() -> SkillListResult	List this session’s user-invocable skills (skill/list).
list_hooks	async list_hooks() -> HookListResult	List this session’s installed hook rows (hook/list).
pause_workflow	async pause_workflow(workflow_run_id: str) -> WorkflowControlResult	Pause a live workflow run (workflow/pause).
resume_workflow	async resume_workflow(workflow_run_id: str) -> WorkflowResumeResult	Resume a paused workflow run (workflow/resume).
request_recap	async request_recap() -> RecapRequestResult	Request a recap of this session (recap/request); admission only.
submit_feedback	async submit_feedback(input: FeedbackSubmitParams) -> FeedbackSubmitResult	Submit feedback about this session (feedback/submit).
open_side_chat	async open_side_chat() -> SessionSideChatResult	Open a side chat from this session (session/sideChat).
fork	async fork(*, cut_point: ForkCutPoint | None = None, exclude_items: bool | None = None) -> SessionForkResult	Fork this session into a new one (session/fork).
compact	async compact(*, turn_id: str | None = None) -> SessionCompactResult	Compact this session’s context (session/compact); admission only, or noop.
set_model	async set_model(model: ModelSelection) -> SessionSetModelResult	Select the model for later model calls (session/setModel).
set_reasoning_effort	async set_reasoning_effort(reasoning_effort: ReasoningEffort) -> SessionSetReasoningEffortResult	Set this session’s standing reasoning effort (session/setReasoningEffort).
set_approval_mode	async set_approval_mode(mode: ApprovalMode) -> SessionSetApprovalModeResult	Select one of the host’s preconfigured approval modes (session/setApprovalMode).
rename	async rename(name: str) -> SessionRenameResult	Set or change this session’s stored name (session/rename).
leave	async leave(*, stop: bool | None = None) -> SessionLeaveResult	Release this session from the host (session/leave).
send_subagent_message	async send_subagent_message(subagent_id: str, body: str) -> CommandAcceptedResult	Queue a note into a running subagent (subagent/sendMessage).
followup_subagent_task	async followup_subagent_task(subagent_id: str, body: str) -> CommandAcceptedResult	Queue a follow-up task for a subagent (subagent/followupTask).
interrupt_subagent	async interrupt_subagent(subagent_id: str, *, reason: str | None = None) -> CommandAcceptedResult	Ask a subagent to yield at its next boundary (subagent/interrupt).
stop_subagent	async stop_subagent(subagent_id: str, *, reason: str | None = None) -> CommandAcceptedResult	Stop a running subagent (subagent/stop).
resume_subagent	async resume_subagent(subagent_id: str) -> CommandAcceptedResult	Resume a paused or recoverable subagent (subagent/resume).
reopen_subagent	async reopen_subagent(subagent_id: str) -> CommandAcceptedResult	Reopen a stopped or closed subagent (subagent/reopen).
close_subagent	async close_subagent(subagent_id: str, *, reason: str | None = None) -> CommandAcceptedResult	Close a subagent as its owner (subagent/close).
read_subagent_result	async read_subagent_result(subagent_id: str) -> CommandAcceptedResult	Consume a subagent’s ready result (subagent/readResult).
list_plugins	async list_plugins() -> PluginListResult	List this session’s installed plugins (plugin/list); a query, like list_tasks.
install_plugin	async install_plugin(target: PluginInstallTarget) -> PluginInstallResult	Install one plugin from a marketplace or a host folder (plugin/install).
set_skill_activation	async set_skill_activation(*, selector: str, scope: SkillActivationScope, activation: SkillActivationState) -> SkillSetActivationResult	Turn one skill on or off in one scope (skill/setActivation).
stop_retrying	stop_retrying(command_id: str) -> PendingRetirement[_I] | None	Stop the pending retry loop for one entry and take its input back.
replay_answered	replay_answered(command_id: str, answer: ReplayAnswer[_I]) -> PendingRetirement[_I] | Literal['held']	Feed a consumer-driven replay’s answer through the live pending 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:490