Session Types and Results
The most important fields and meanings in Session input and output objects
Session Types and Results
Import cross-package data protocols such as SessionMessage, SessionMutation, SessionOrigin,
interactions, and JSON values from @downcity/type. Import executable Agent contracts such as
AgentSession and Turn handles from @downcity/agent.
The most common input and output objects are:
AgentSessionRemoteAgentSessionAgentSessionSetInputAgentSessionSetOptionsRemoteSessionSetInputAgentSessionStatusAgentSessionPromptInputAgentSessionTurnHandleAgentSessionTurnResultSessionMutationSessionMessageSessionInteractionRequestRespondSessionInteractionInputAgentSessionInfo
Choose types by job
| What you are building | Object to consume |
|---|---|
| Initial load, history, and reconnect recovery | SessionMessagePage / SessionMessage |
| Live text, tools, and title | SessionMutation |
| Waiting for one execution to finish | AgentSessionTurnHandle / AgentSessionTurnResult |
| Displaying or responding to user interaction | SessionInteractionRequest / SessionInteractionResult |
| Sidebar and selected Session header | AgentSessionSummary / AgentSessionInfo |
| Runtime and security state | AgentSessionStatus |
AgentSessionStatus.security exposes both the configured approval_mode and the checkpoint-committed
effective_approval_mode. When they differ, the configuration is still waiting in the Session Queue.
AgentSessionSetOptions controls observability after a real configuration change commits. persist_action decides whether to write an Agent Message containing an Action Part, while publish_mutation decides whether to publish its Message Mutation to Session subscribers. Omitting both preserves the default persistence and publication behavior.
AgentSessionPromptInput
Core field:
query
AgentSessionTurnHandle
Core fields:
idresultfinished
AgentSessionTurnResult
Core fields:
turn_idsuccesserrortext
Use text for a compact final result. There is one canonical structured Assistant Message;
read it through session.messages() and session.subscribe() instead of a duplicate Turn result.
Further reading
- Prompts and Turns: input shapes, steering, and queue semantics.
- Messages and Parts: persisted linear history, revisions, and pagination.
- Live subscriptions: eight Mutation variants and client merge rules.
- Asynchronous user interactions: approvals, questions, and responses.
- Session details: summary, title, and execution-state fields.