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:

  • AgentSession
  • RemoteAgentSession
  • AgentSessionSetInput
  • AgentSessionSetOptions
  • RemoteSessionSetInput
  • AgentSessionStatus
  • AgentSessionPromptInput
  • AgentSessionTurnHandle
  • AgentSessionTurnResult
  • SessionMutation
  • SessionMessage
  • SessionInteractionRequest
  • RespondSessionInteractionInput
  • AgentSessionInfo

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 buildingObject to consume
Initial load, history, and reconnect recoverySessionMessagePage / SessionMessage
Live text, tools, and titleSessionMutation
Waiting for one execution to finishAgentSessionTurnHandle / AgentSessionTurnResult
Displaying or responding to user interactionSessionInteractionRequest / SessionInteractionResult
Sidebar and selected Session headerAgentSessionSummary / AgentSessionInfo
Runtime and security stateAgentSessionStatus

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; requires request_id.
  • abort_signal: cancels input reception before acceptance; stopping accepted work uses stop().

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:

  • id
  • result
  • finished

AgentSessionTurnResult

Core fields:

  • turn_id
  • success
  • error
  • text

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