Session

One conversation with the agent.

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 MuseClient.startSession or resumeSession, then sendUserTurn to talk, turn to follow a turn’s items to its outcome, and onApproval to answer permission requests.

Properties

Property	Type	Stability	Presence	Description
opening	SessionOpening | undefined		required	See SessionOpening. Absent when the caller built this directly.
sessionId	string		required
durability	SessionDurabilityProfile		required
fold	SessionFoldView		required	Read-only; events enter through apply so turn routing cannot be skipped.
pending	PendingCommandView<I>		required	The set, minus the three mutators Session drives itself.

Methods

Method	Signature	Stability	Description
constructor	new Session(options: SessionOptions)
answerUserInput	answerUserInput(userInputId: string, answers: readonly UserInputAnswer[]): Promise<UserInputAnswerResult>		Answer a question this session lists in fold.pendingUserInputs(): sends userInput/answer with one answer per question and resolves with the host’s admission. The question leaves the pending list only when the server’s userInput/settled arrives.
apply	apply(event: ViewEvent): SessionApplyOutcome<I>		Fold one view event, then fan it out to the turn handles that want it.
apply	apply(event: object): SessionApplyOutcome<I>		Fold one view event, then fan it out to the turn handles that want it.
closeSubagent	closeSubagent(subagentId: string, options?: SubagentReasonOptions): Promise<CommandAcceptedResult>		Close a subagent as its owner (subagent/close).
compact	compact(options?: Readonly<Omit<SessionCompactParams, "commandId" | "sessionId">>): Promise<SessionCompactResult>		Compact this session’s context (session/compact); admission only, or noop.
followupSubagentTask	followupSubagentTask(subagentId: string, body: string): Promise<CommandAcceptedResult>		Queue a follow-up task for a subagent (subagent/followupTask).
fork	fork(options?: Readonly<Omit<SessionForkParams, "commandId" | "sessionId">>): Promise<SessionForkResult>		Fork this session into a new one (session/fork). Returns the wire result for the new session; opening a wired Session for it stays the caller’s composition, as with openSideChat.
hostExited	hostExited(exit: HostDeathNotification): HostDeathDischarge<I>		A host process exited. Classify it, and discharge if the profile demands it.
installPlugin	installPlugin(target: PluginInstallTarget): Promise<PluginInstallResult>		Install one plugin from a marketplace or a host folder (plugin/install).
interruptSubagent	interruptSubagent(subagentId: string, options?: SubagentReasonOptions): Promise<CommandAcceptedResult>		Ask a subagent to yield at its next boundary (subagent/interrupt).
leave	leave(options?: Readonly<Omit<SessionLeaveParams, "commandId" | "sessionId">>): Promise<SessionLeaveResult>		Release this session from the host (session/leave); stop: true also cancels unfinished work. Admission only: the host reports the release later as session/leaveCompleted.
listHooks	listHooks(): Promise<HookListResult>		List this session’s installed hook rows (hook/list).
listPlugins	listPlugins(): Promise<PluginListResult>		List this session’s installed plugins (plugin/list); a query, like listTasks.
listSkills	listSkills(): Promise<SkillListResult>		List this session’s user-invocable skills (skill/list).
listTasks	listTasks(): Promise<TaskListResult>		List this session’s live background and foreground tasks (task/list).
onApproval	onApproval(handler: ApprovalHandler): void		Answer approvals with handler. See ApprovalRouter.
onApprovalError	onApprovalError(handler: ApprovalFailureHandler): void		Observe round trips that did not complete. See ApprovalFailure.
onGapError	onGapError(handler: GapFillFailureHandler): void		Observe fills that did not complete. See MuseGapFillError.
openSideChat	openSideChat(): Promise<SessionSideChatResult>		Open a side chat from this session (session/sideChat). Returns the wire result; opening a wired Session for the new side session is the caller’s composition, as with a directly built Session.
pauseWorkflow	pauseWorkflow(workflowRunId: string): Promise<WorkflowControlResult>		Pause a live workflow run (workflow/pause).
readSubagentResult	readSubagentResult(subagentId: string): Promise<CommandAcceptedResult>		Consume a subagent’s ready result (subagent/readResult).
rename	rename(name: string): Promise<SessionRenameResult>		Set or change this session’s stored name (session/rename).
reopenSubagent	reopenSubagent(subagentId: string): Promise<CommandAcceptedResult>		Reopen a stopped or closed subagent (subagent/reopen).
replayAnswered	replayAnswered(commandId: string, answer: ReplayAnswer): "held" | PendingRetirement<I>		Feed a consumer-driven replay’s answer through the live settlement rules. Wrapped for the same replay-memory bookkeeping as stopRetrying; "held" means the answer settled nothing and the entry stays.
requestRecap	requestRecap(): Promise<RecapRequestResult>		Request a recap of this session (recap/request); admission only.
resolveReconnect	resolveReconnect(): Promise<readonly PendingRetirement<I>[]>		Resolve a reconnect with NO snapshot (history.mode: "none", the default cursor-resume path). Reconnect itself is the trigger: replay each acked entry once, resubmit each unacked entry’s SAME commandId once.
resolveSnapshotJoin	resolveSnapshotJoin(facts: SnapshotJoinFacts): Promise<readonly 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.
resumeSubagent	resumeSubagent(subagentId: string): Promise<CommandAcceptedResult>		Resume a paused or recoverable subagent (subagent/resume).
resumeWorkflow	resumeWorkflow(workflowRunId: string): Promise<WorkflowResumeResult>		Resume a paused workflow run (workflow/resume).
run	run(input: string | readonly TurnInputPart[], options?: RunOptions): Promise<RunResult>		Run one turn to its end in a single call: submit input (a string is one text part), wait for the server to end the turn, and resolve its outcome, final answer text, items and usage. Pass options.signal to stop the turn; see RunOptions. Use sendUserTurn to stream items or deltas as they arrive.
sendSubagentMessage	sendSubagentMessage(subagentId: string, body: string): Promise<CommandAcceptedResult>		Queue a note into a running subagent (subagent/sendMessage).
sendUserTurn	sendUserTurn(options: SendUserTurnOptions<I>): Promise<Turn<I>>		Submit a user turn and hand back THIS session’s handle for the turn the ack named.
setApprovalMode	setApprovalMode(mode: ApprovalMode): Promise<SessionSetApprovalModeResult>		Select one of the host’s preconfigured approval modes (session/setApprovalMode).
setModel	setModel(model: ModelSelection): Promise<SessionSetModelResult>		Select the model for later model calls (session/setModel).
setReasoningEffort	setReasoningEffort(reasoningEffort: ReasoningEffort): Promise<SessionSetReasoningEffortResult>		Set this session’s standing reasoning effort (session/setReasoningEffort).
setSkillActivation	setSkillActivation(options: Readonly<Omit<SkillSetActivationParams, "commandId" | "sessionId">>): Promise<SkillSetActivationResult>		Turn one skill on or off in one scope (skill/setActivation).
stopRetrying	stopRetrying(commandId: string): PendingRetirement<I> | undefined		Stop the retry loop for one entry and take its input back (“Abandoned”).
stopSubagent	stopSubagent(subagentId: string, options?: SubagentReasonOptions): Promise<CommandAcceptedResult>		Stop a running subagent (subagent/stop).
submitFeedback	submitFeedback(input: Omit<FeedbackSubmitParams, "sessionId">): Promise<FeedbackSubmitResult>		Submit feedback about this session (feedback/submit). The host serves it only when the spawn requested the feedback capability (requestedCapabilities: ["feedback"]) and install policy allows it; without that grant the host refuses the command.
turn	turn(turnId: string): Turn<I>		The handle for a turn, created on first mention from either side. A turn the fold has already settled returns its settled handle, so a wait registered late resolves instead of hanging on an event that has passed.

Source

clients/sdk-ts/src/facade/session.ts:358

{
  "kind": "Class",
  "canonicalPath": "Session"
}