act_types/
http.rs

1//! ACT-HTTP protocol types for request/response serialization.
2//!
3//! All types derive both `Serialize` and `Deserialize` so they can be used
4//! by servers (act-host), clients (act-bridge), and SDKs alike.
5
6use serde::{Deserialize, Serialize};
7use serde_with::skip_serializing_none;
8
9/// ACT-HTTP protocol version.
10pub const PROTOCOL_VERSION: &str = "0.2";
11
12/// HTTP header name for the protocol version.
13pub const HEADER_PROTOCOL_VERSION: &str = "ACT-Protocol-Version";
14
15/// Tool definition returned in `ListToolsResponse`.
16#[skip_serializing_none]
17#[derive(Debug, Clone, Serialize, Deserialize)]
18pub struct ToolDefinition {
19    pub name: String,
20    pub description: String,
21    pub parameters_schema: serde_json::Value,
22    pub metadata: Option<serde_json::Value>,
23}
24
25/// Response from `POST /tools`.
26#[skip_serializing_none]
27#[derive(Debug, Clone, Serialize, Deserialize)]
28pub struct ListToolsResponse {
29    pub tools: Vec<ToolDefinition>,
30    pub metadata: Option<serde_json::Value>,
31}
32
33/// Request body for `POST /tools` and `QUERY /tools`.
34#[skip_serializing_none]
35#[derive(Debug, Clone, Serialize, Deserialize, Default)]
36pub struct MetadataRequest {
37    #[serde(default)]
38    pub metadata: Option<serde_json::Value>,
39}
40
41/// Request body for `POST /tools/{name}`.
42#[skip_serializing_none]
43#[derive(Debug, Clone, Serialize, Deserialize)]
44pub struct ToolCallRequest {
45    pub arguments: serde_json::Value,
46    #[serde(default)]
47    pub metadata: Option<serde_json::Value>,
48}
49
50/// A content part in a tool response.
51#[skip_serializing_none]
52#[derive(Debug, Clone, Serialize, Deserialize)]
53pub struct ContentPart {
54    pub data: serde_json::Value,
55    #[serde(default)]
56    pub mime_type: Option<String>,
57    #[serde(default)]
58    pub metadata: Option<serde_json::Value>,
59}
60
61/// Response from `POST /tools/{name}`.
62#[skip_serializing_none]
63#[derive(Debug, Clone, Serialize, Deserialize)]
64pub struct ToolCallResponse {
65    pub content: Vec<ContentPart>,
66    #[serde(default)]
67    pub metadata: Option<serde_json::Value>,
68}
69
70/// Error object in error responses.
71#[skip_serializing_none]
72#[derive(Debug, Clone, Serialize, Deserialize)]
73pub struct ToolError {
74    pub kind: String,
75    pub message: String,
76    #[serde(default)]
77    pub metadata: Option<serde_json::Value>,
78}
79
80/// Wrapper for error responses (`{"error": ...}`).
81#[derive(Debug, Clone, Serialize, Deserialize)]
82pub struct ErrorResponse {
83    pub error: ToolError,
84}
85
86/// Resource info returned by `POST /resources`.
87#[skip_serializing_none]
88#[derive(Debug, Clone, Serialize, Deserialize)]
89pub struct ResourceInfo {
90    pub uri: String,
91    #[serde(default)]
92    pub mime_type: Option<String>,
93    pub description: String,
94    #[serde(default)]
95    pub metadata: Option<serde_json::Value>,
96}
97
98/// Response from `POST /resources`.
99#[skip_serializing_none]
100#[derive(Debug, Clone, Serialize, Deserialize)]
101pub struct ListResourcesResponse {
102    pub resources: Vec<ResourceInfo>,
103    #[serde(default)]
104    pub metadata: Option<serde_json::Value>,
105}
106
107/// Request body for `POST /sessions`. Per ACT-SESSIONS §6.2.
108#[skip_serializing_none]
109#[derive(Debug, Clone, Serialize, Deserialize)]
110pub struct OpenSessionRequest {
111    /// Component-defined open-session args. JSON object whose keys map
112    /// 1:1 to `metadata` entries when sent across the WIT boundary.
113    pub arguments: serde_json::Value,
114    #[serde(default)]
115    pub metadata: Option<serde_json::Value>,
116}
117
118/// Response body for `POST /sessions`.
119#[skip_serializing_none]
120#[derive(Debug, Clone, Serialize, Deserialize)]
121pub struct OpenSessionResponse {
122    pub id: String,
123    /// Session-scoped metadata returned by the component.
124    #[serde(default)]
125    pub metadata: serde_json::Map<String, serde_json::Value>,
126}
127
128/// Map an ACT error kind to an HTTP status code per ACT-HTTP spec.
129pub fn error_kind_to_status(kind: &str) -> u16 {
130    use crate::constants::*;
131    match kind {
132        ERR_NOT_FOUND => 404,
133        ERR_SESSION_NOT_FOUND => 404,
134        ERR_INVALID_ARGS => 422,
135        ERR_TIMEOUT => 504,
136        ERR_CAPABILITY_DENIED => 403,
137        _ => 500,
138    }
139}
act_types/http.rs

act_types/
http.rs
