Session 类型与结果
Session 输入输出对象里最重要的字段和语义
SessionMessage、SessionMutation、SessionOrigin、Interaction 与 JSON 值等跨 package
数据协议统一从 @downcity/type 导入；AgentSession、Turn Handle 等 Agent 可执行契约从
@downcity/agent 导入。
最常见的输入输出对象有：
AgentSessionRemoteAgentSessionAgentSessionSetInputAgentSessionSetOptionsRemoteSessionSetInputAgentSessionStatusAgentSessionPromptInputAgentSessionStopResultAgentSessionTurnHandleAgentSessionTurnResultSessionMutationSessionMessageSessionInteractionRequestRespondSessionInteractionInputAgentSessionInfo
先按用途选择类型
| 你要做什么 | 应该消费的对象 |
|---|---|
| 首次加载、历史与重连恢复 | SessionMessagePage / SessionMessage |
| 实时文本、工具和标题 | SessionMutation |
| 等待一次执行结束 | AgentSessionTurnHandle / AgentSessionTurnResult |
| 展示或提交用户异步交互 | SessionInteractionRequest / SessionInteractionResult |
| 侧边栏与当前会话头部 | AgentSessionSummary / AgentSessionInfo |
| 运行状态与安全策略 | AgentSessionStatus |
AgentSessionStatus.security 同时提供 configured approval_mode 与检查点已经提交的
effective_approval_mode。两者不同时，配置仍在 Session Queue 中等待执行。
AgentSessionSetOptions 控制真实配置变化提交后的可观测输出：persist_action 决定是否写入包含 Action Part 的 Agent Message，publish_mutation 决定是否通过 Session 订阅发布对应 Message Mutation。两者均省略时保持默认的持久化与发布行为。
AgentSessionPromptInput
核心字段：
query
AgentSessionTurnHandle
核心字段：
idresultfinished
AgentSessionTurnResult
核心字段：
turn_idsuccesserrortext
text 用于简洁的最终结果。结构化 Assistant Message 只有一份 canonical 状态，
应通过 session.messages() 与 session.subscribe() 读取，不会在 Turn Result 中复制。
AgentSessionStopResult
核心字段：
stoppedturn_idcancelled_queued_promptsreason
session.stop() 会停止当前 turn，并取消尚未被当前 turn 吸收的排队 prompt。空闲时调用不会抛错，会返回 stopped: false 和 reason: "idle"。
深入阅读
- 输入与 Turn：输入格式、steering 与排队语义。
- Message 与 Part：持久化线性历史、revision 与分页。
- 实时订阅：八类 Mutation 与客户端合并规则。
- 用户异步交互：Session 级审批、问题与响应。
- Session 详情：摘要、标题与执行状态字段。