abyss_plugin_protocol/inspection.rs
1//! Request-only Agent inspection values exchanged on a broker plugin session.
2
3use serde::{Deserialize, Serialize};
4use serde_json::Value;
5
6use crate::event::{Conversation, EventPurpose, ImageAttachment, LlmProvider};
7
8/// Capabilities selected by a plugin for this connection.
9#[derive(Debug, Clone, Copy, PartialEq, Deserialize, Serialize)]
10#[serde(rename_all = "snake_case")]
11#[non_exhaustive]
12pub enum PluginCapability {
13 /// Receive the existing observation event stream.
14 AgentEvents,
15 /// Decide on complete plaintext requests before forwarding.
16 AgentRequest,
17}
18
19/// Complete decoded bytes, without a lossy UTF-8 conversion.
20#[derive(Debug, Deserialize, Serialize)]
21#[serde(tag = "encoding", content = "content", rename_all = "snake_case")]
22#[non_exhaustive]
23pub enum DecodedContent {
24 /// UTF-8 text, including JSON and unknown text protocols.
25 Utf8(String),
26 /// Base64 of a binary payload.
27 Base64(String),
28}
29
30/// Result of projecting a decoded request onto known Agent protocols.
31#[derive(Debug, Deserialize, Serialize)]
32#[serde(rename_all = "snake_case")]
33#[non_exhaustive]
34pub enum RequestParsingStatus {
35 /// Recognized protocol with a decoded JSON request.
36 Parsed,
37 /// No known protocol matched; complete content remains available.
38 UnknownProtocol,
39 /// A known protocol did not contain a valid JSON request.
40 InvalidPayload,
41}
42
43/// Reassembled WebSocket payload type, independent of content encoding.
44#[derive(Debug, Deserialize, Serialize)]
45#[serde(rename_all = "snake_case")]
46#[non_exhaustive]
47pub enum RequestMessageType {
48 Text,
49 Binary,
50}
51
52/// Source metadata supplied by the ingress; explicit proxy clients have none.
53#[derive(Debug, Deserialize, Serialize)]
54#[serde(deny_unknown_fields)]
55pub struct RequestSourceProcess {
56 /// OS process identifier.
57 pub pid: Option<u32>,
58 /// OS process incarnation identifier.
59 pub pid_version: Option<u32>,
60 /// Process name.
61 pub name: Option<String>,
62 /// Executable path.
63 pub executable_path: Option<String>,
64 /// Platform application identity.
65 pub application_id: Option<String>,
66 /// Runtime entry script path.
67 pub entry_point: Option<String>,
68 /// Working directory.
69 pub working_directory: Option<String>,
70}
71
72/// Request-side Harness recognition and declarations, independent of audit policy.
73#[derive(Debug, Deserialize, Serialize)]
74#[serde(deny_unknown_fields)]
75pub struct RequestHarness {
76 /// Recognized Harness name.
77 pub id: String,
78 /// Recognized version.
79 pub version: Option<String>,
80 /// Root user turn declared by the client, including for subagent requests.
81 pub turn_id: Option<String>,
82 /// Subagent identity explicitly declared by this client.
83 pub subagent_id: Option<String>,
84 /// Subagent that spawned this one, if declared.
85 pub parent_subagent_id: Option<String>,
86 /// Declared request purpose.
87 pub purpose: Option<EventPurpose>,
88}
89
90/// Request-only model projection. Response IDs, output and usage are not invented.
91#[derive(Debug, Deserialize, Serialize)]
92#[serde(deny_unknown_fields)]
93pub struct AgentRequestProjection {
94 /// Known wire dialect.
95 pub protocol: String,
96 /// Provider resolved from request routing.
97 pub provider: LlmProvider,
98 /// Model requested by the caller.
99 pub model: Option<String>,
100 /// Ordered protocol entries, including instructions, tool calls and results.
101 pub conversation: Conversation,
102 /// Embedded image content; referenced attachments remain in the original JSON.
103 pub attachments: Vec<ImageAttachment>,
104 /// Provider tool definitions, retaining provider-specific schemas.
105 pub tools: Option<Value>,
106 /// Response that this request continues, if declared.
107 pub previous_response_id: Option<String>,
108}
109
110/// Complete decision context for one HTTP request or client WebSocket data message.
111#[derive(Debug, Deserialize, Serialize)]
112#[serde(deny_unknown_fields)]
113pub struct AgentRequestContext {
114 /// Stable physical flow identity.
115 pub flow_id: String,
116 /// Unique request/message correlation identity.
117 pub request_id: String,
118 /// Transport ingress source label.
119 pub ingress: String,
120 /// Platform process identity, when available.
121 pub source_process: Option<RequestSourceProcess>,
122 /// Original destination address.
123 pub destination: String,
124 /// Destination host recovered by ingress.
125 pub destination_host: Option<String>,
126 /// TLS SNI, when present.
127 pub server_name: Option<String>,
128 /// Request authority.
129 pub authority: Option<String>,
130 /// Credential-free next-hop proxy authority.
131 pub proxy_endpoint: Option<String>,
132 /// HTTP request or upgrade method.
133 pub method: String,
134 /// HTTP path and query.
135 pub path: String,
136 /// Whether content is a complete WebSocket data message.
137 pub websocket: bool,
138 /// HTTP request number (1) or client data-message number within this flow.
139 pub sequence: u64,
140 /// Original WebSocket type; null for HTTP, including upgrade requests.
141 pub message_type: Option<RequestMessageType>,
142 /// Headers as name/value pairs, preserving duplicates. Headers recognized by
143 /// the MITM credential-header predicate are omitted.
144 pub headers: Vec<(String, String)>,
145 /// Complete decoded content.
146 pub body: DecodedContent,
147 /// Complete parsed JSON when present, including unrecognized fields.
148 pub json: Option<Value>,
149 /// Projection outcome, also supplied for unknown requests.
150 pub parsing_status: RequestParsingStatus,
151 /// Available request-side Harness identity and declarations.
152 pub harness: Option<RequestHarness>,
153 /// Known Agent request projection.
154 pub agent: Option<AgentRequestProjection>,
155}
156
157/// Plugin reply correlated to one inspection on this connection.
158#[derive(Debug, Deserialize, Serialize)]
159#[serde(deny_unknown_fields)]
160pub struct InspectResponse {
161 /// Broker request identifier from the inspection context.
162 pub request_id: String,
163 /// Whether this plugin permits forwarding.
164 pub allow: bool,
165 /// Safe client-facing reason. Must not echo sensitive request content.
166 pub reason: Option<String>,
167}
168
169/// Decision returned by SDK request handlers.
170#[derive(Debug)]
171#[non_exhaustive]
172pub enum RequestDecision {
173 /// Permit this request.
174 Allow,
175 /// Reject this request with a safe explanation.
176 Block(String),
177}
178
179impl RequestDecision {
180 /// Encodes a handler decision for its original request.
181 #[must_use]
182 pub fn into_response(self, request_id: String) -> InspectResponse {
183 let (allow, reason) = match self {
184 Self::Allow => (true, None),
185 Self::Block(reason) => (false, Some(reason)),
186 };
187 InspectResponse {
188 request_id,
189 allow,
190 reason,
191 }
192 }
193}