objectiveai_sdk/client_objectiveai_mcp/server_response/payload.rs
1use schemars::JsonSchema;
2use serde::{Deserialize, Serialize};
3
4/// Tagged union of every reply the CLI can send back to the API in
5/// answer to a [`super::super::server_request::Payload`]. Variant
6/// names pair 1:1 with the request side; the typed `result` /
7/// `error` shape per JSON-RPC method is captured in
8/// [`JsonRpcResult`].
9///
10/// MCP-routed variants echo `mcp_kind` on the variant itself
11/// (lets the API sanity-check routing). Non-MCP variants
12/// (`ReadMessageQueue` / `ClearMessageQueue`) don't carry
13/// `mcp_kind` — they never had one to echo. Use
14/// [`Payload::mcp_kind`] to retrieve it generically.
15#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
16#[schemars(rename = "client_objectiveai_mcp.server_response.Payload")]
17#[serde(tag = "type", rename_all = "snake_case")]
18pub enum Payload {
19 /// Reply to
20 /// [`super::super::server_request::Payload::Initialize`]. On
21 /// success carries the upstream MCP session id the API stamps
22 /// onto its outbound `Mcp-Session-Id` response header so the
23 /// proxy adopts it. On failure (dial or aggregate-build error)
24 /// carries a JSON-RPC error envelope the API translates into its
25 /// own outbound error.
26 #[schemars(title = "Initialize")]
27 Initialize {
28 mcp_kind: super::super::McpKind,
29 #[serde(flatten)]
30 result: JsonRpcResult<InitializeReply>,
31 },
32
33 /// Reply to [`super::super::server_request::Payload::ToolsList`].
34 #[schemars(title = "ToolsList")]
35 ToolsList {
36 mcp_kind: super::super::McpKind,
37 #[serde(flatten)]
38 result: JsonRpcResult<crate::mcp::tool::ListToolsResult>,
39 },
40
41 /// Reply to [`super::super::server_request::Payload::ToolsCall`].
42 #[schemars(title = "ToolsCall")]
43 ToolsCall {
44 mcp_kind: super::super::McpKind,
45 #[serde(flatten)]
46 result: JsonRpcResult<crate::mcp::tool::CallToolResult>,
47 },
48
49 /// Reply to
50 /// [`super::super::server_request::Payload::ResourcesList`].
51 #[schemars(title = "ResourcesList")]
52 ResourcesList {
53 mcp_kind: super::super::McpKind,
54 #[serde(flatten)]
55 result: JsonRpcResult<crate::mcp::resource::ListResourcesResult>,
56 },
57
58 /// Reply to
59 /// [`super::super::server_request::Payload::ResourcesRead`].
60 #[schemars(title = "ResourcesRead")]
61 ResourcesRead {
62 mcp_kind: super::super::McpKind,
63 #[serde(flatten)]
64 result: JsonRpcResult<crate::mcp::resource::ReadResourceResult>,
65 },
66
67 /// Acknowledges
68 /// [`super::super::server_request::Payload::SessionTerminate`].
69 /// On success carries the unit value (no body); on failure
70 /// carries the upstream-delete error so the proxy sees a
71 /// non-2xx and can retry.
72 #[schemars(title = "SessionTerminate")]
73 SessionTerminate {
74 mcp_kind: super::super::McpKind,
75 #[serde(flatten)]
76 result: JsonRpcResult<()>,
77 },
78
79 /// Reply to
80 /// [`super::super::server_request::Payload::ReadMessageQueue`].
81 /// On success carries every matching queue row's id + body in
82 /// oldest-first order; on failure surfaces the local storage
83 /// error so the API can decide whether to retry. Non-MCP — no
84 /// `mcp_kind` to echo.
85 #[schemars(title = "ReadMessageQueue")]
86 ReadMessageQueue(JsonRpcResult<ReadMessageQueueResult>),
87
88 /// Reply to
89 /// [`super::super::server_request::Payload::Retrieve`]. Carries the
90 /// resolved definition (or `None` if not found) on success, or the
91 /// client's local storage error. Non-MCP — no `mcp_kind`.
92 #[schemars(title = "Retrieve")]
93 Retrieve(JsonRpcResult<super::super::retrieve::Response>),
94}
95
96impl Payload {
97 /// Which CLI-hosted MCP server produced this reply. `Some` for
98 /// MCP-routed variants (echoes the request's `mcp_kind`); `None`
99 /// for `ReadMessageQueue`.
100 pub fn mcp_kind(&self) -> Option<super::super::McpKind> {
101 match self {
102 Payload::Initialize { mcp_kind, .. }
103 | Payload::ToolsList { mcp_kind, .. }
104 | Payload::ToolsCall { mcp_kind, .. }
105 | Payload::ResourcesList { mcp_kind, .. }
106 | Payload::ResourcesRead { mcp_kind, .. }
107 | Payload::SessionTerminate { mcp_kind, .. } => Some(mcp_kind.clone()),
108 Payload::ReadMessageQueue(_) | Payload::Retrieve(_) => None,
109 }
110 }
111}
112
113/// Successful payload for [`Payload::ReadMessageQueue`].
114///
115/// One [`ReadMessageQueueRow`] per consumed `message_queue` row,
116/// in oldest-first id order. Each row's `content_ids` are the
117/// `message_queue_contents.id`s for that row's slots; the row's
118/// `rich_content` is the CLI's reconstructed payload for that
119/// row alone (no cross-row separator splicing — callers join if
120/// they want a unified User message).
121///
122/// Two consumers:
123/// - **Startup snapshot** (`run_agent_loop`): joins every row's
124/// parts with `"\n\n"` separators, flattens `content_ids`, and
125/// stamps the result onto the first
126/// `AssistantResponseChunk.request_message_ids`.
127/// - **`ApiQueueDelegate`** (`agents logs read subscribe`-style
128/// per-tool-response delivery): keeps rows separate so each
129/// gets converted to its own `Vec<ContentBlock>` and surfaces
130/// row-by-row on tool responses.
131///
132/// The downstream LogWriter resolves each id's kind at write
133/// time (SQL CASE against `message_queue_contents.kind`) to
134/// dispatch the right `logs.message_table` variant — kinds don't
135/// need to ride on the wire.
136#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
137#[schemars(rename = "client_objectiveai_mcp.server_response.ReadMessageQueueResult")]
138pub struct ReadMessageQueueResult {
139 pub rows: Vec<ReadMessageQueueRow>,
140}
141
142/// One queued row's payload + its content-slot ids.
143#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
144#[schemars(rename = "client_objectiveai_mcp.server_response.ReadMessageQueueRow")]
145pub struct ReadMessageQueueRow {
146 /// `message_queue_contents.id` of every slot in this row, in
147 /// part order. Matches `rich_content`'s part count 1:1.
148 pub content_ids: Vec<i64>,
149 /// The row's content as the CLI reconstructed it.
150 pub rich_content: crate::agent::completions::message::RichContent,
151}
152
153/// The successful `Initialize` payload — the upstream's verbatim
154/// `InitializeResult` plus the native `Mcp-Session-Id` the CLI got
155/// back from dialing the actual MCP server. The API forwards both
156/// to the proxy: the result as the JSON-RPC body, the session id as
157/// the `Mcp-Session-Id` response header. The CLI is a pure medium —
158/// it doesn't synthesize capabilities, doesn't name itself, doesn't
159/// pin a protocol version. Whatever the upstream MCP advertised is
160/// what the proxy sees.
161#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
162#[schemars(rename = "client_objectiveai_mcp.server_response.InitializeReply")]
163pub struct InitializeReply {
164 /// Upstream's native `Mcp-Session-Id`. One per CLI-hosted MCP
165 /// server — no aggregation, no encoding.
166 pub mcp_session_id: String,
167 /// The upstream's verbatim `InitializeResult` (capabilities,
168 /// server info, protocol version). Returned as-is to the proxy.
169 pub result: crate::mcp::initialize_result::InitializeResult,
170}
171
172/// JSON-RPC result/error shape for every typed method. Mirrors
173/// the wire shape upstream MCP servers return (`{result: …}` on
174/// success, `{error: {code, message, data?}}` on failure) but typed
175/// at the SDK level instead of buried inside a `serde_json::Value`.
176#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
177#[schemars(rename = "client_objectiveai_mcp.server_response.JsonRpcResult.{R}", bound = "R: JsonSchema")]
178#[serde(tag = "kind", rename_all = "snake_case")]
179pub enum JsonRpcResult<R> {
180 /// Method returned a typed result.
181 #[schemars(title = "Ok")]
182 Ok { result: R },
183 /// Method returned a JSON-RPC error envelope.
184 #[schemars(title = "Err")]
185 Err {
186 code: i64,
187 message: String,
188 #[serde(default, skip_serializing_if = "Option::is_none")]
189 #[schemars(extend("omitempty" = true))]
190 data: Option<serde_json::Value>,
191 },
192}