Skip to main content

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}