Session Types and Results
The most important fields and meanings in Session input and output objects
Import cross-package data protocols such as SessionMessage, SessionMutation, SessionDescriptor,
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
AgentSessionSetInput contains only model and security. workspace_id is immutable persisted ownership determined at creation; workspace is the same-ID execution resource restored by the host. Missing resources do not clear ownership.
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.
Session identity and purpose
AgentSession, AgentSessionSummary and AgentSessionInfo expose top-level id, type, kind, and optional parent. A summary belongs to the Agent collection that returned it. type is chat or work; kind is a custom non-empty string. Creation defaults to work/work and accepts these fields directly.
SessionDescriptor is a shared interface for these creation fields. Parent references, message references and tool contexts use explicit agent_id and session_id to identify another object.
AgentSessionPromptInput
Core fields:
query: new text or content parts.request_id: optional stable identifier for idempotent submission.actor: trusted caller identity; defaults to the local user. Session and runtime actors must be explicit.powers: caller Powers installed when starting a Turn; descriptors are persisted for recovery checks.callback: a registered completion callback with JSON data; requiresrequest_id.abort_signal: cancels input reception before acceptance; stopping accepted work usesstop().
Only human input creates a SessionUserMessage. Automated prompts and background results create SessionAgentInputPart within the current Agent Message, without closing its writer. Runtime request meta belongs to that individual input Part.
SessionInputContent carries input_id, kind, content: SessionModelUserContent[], optional source: { tool_call_id?, turn_id? }, and optional meta. The canonical SessionAgentInputPart adds type: "input", part_id, sequence, optional step_id, and created_at. Input IDs support idempotency independently of Message IDs. Interactions belong to SessionAgentToolPart.interactions.
SessionViewContent contains type: "view", the provider power_id, schema_version, data, and fallback_text. SessionAgentViewPart adds the canonical Part identity and optional source_tool_call_id. The browser renderer consumes it through the view slot; views continues to declare independent business pages.
SessionAgentMessage.stable_part_sequence is the persisted, monotonic watermark of immutable committed Parts. Complete Step and input commits advance it; summary boundaries respect complete Step units, unfinished Tool/Action barriers, and the latest retained request unit.
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.