act-types 0.7.0

Shared types and CBOR utilities for the ACT (Agent Component Tools) protocol
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

//! ACT-HTTP protocol types for request/response serialization.
//!
//! All types derive both `Serialize` and `Deserialize` so they can be used
//! by servers (act-host), clients (act-bridge), and SDKs alike.

use serde::{Deserialize, Serialize};
use serde_with::skip_serializing_none;

/// ACT-HTTP protocol version.
pub const PROTOCOL_VERSION: &str = "0.2";

/// HTTP header name for the protocol version.
pub const HEADER_PROTOCOL_VERSION: &str = "ACT-Protocol-Version";

/// Tool definition returned in `ListToolsResponse`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolDefinition {
    pub name: String,
    pub description: String,
    pub parameters_schema: serde_json::Value,
    pub metadata: Option<serde_json::Value>,
}

/// Response from `POST /tools`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListToolsResponse {
    pub tools: Vec<ToolDefinition>,
    pub metadata: Option<serde_json::Value>,
}

/// Request body for `POST /tools` and `QUERY /tools`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct MetadataRequest {
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// Request body for `POST /tools/{name}`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolCallRequest {
    pub arguments: serde_json::Value,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// A content part in a tool response.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ContentPart {
    pub data: serde_json::Value,
    #[serde(default)]
    pub mime_type: Option<String>,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// Response from `POST /tools/{name}`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolCallResponse {
    pub content: Vec<ContentPart>,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// Error object in error responses.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolError {
    pub kind: String,
    pub message: String,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// Wrapper for error responses (`{"error": ...}`).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ErrorResponse {
    pub error: ToolError,
}

/// Resource info returned by `POST /resources`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResourceInfo {
    pub uri: String,
    #[serde(default)]
    pub mime_type: Option<String>,
    pub description: String,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// Response from `POST /resources`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListResourcesResponse {
    pub resources: Vec<ResourceInfo>,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// Request body for `POST /sessions`. Per ACT-SESSIONS ยง6.2.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OpenSessionRequest {
    /// Component-defined open-session args. JSON object whose keys map
    /// 1:1 to `metadata` entries when sent across the WIT boundary.
    pub arguments: serde_json::Value,
    #[serde(default)]
    pub metadata: Option<serde_json::Value>,
}

/// Response body for `POST /sessions`.
#[skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OpenSessionResponse {
    pub id: String,
    /// Session-scoped metadata returned by the component.
    #[serde(default)]
    pub metadata: serde_json::Map<String, serde_json::Value>,
}

/// Map an ACT error kind to an HTTP status code per ACT-HTTP spec.
pub fn error_kind_to_status(kind: &str) -> u16 {
    use crate::constants::*;
    match kind {
        ERR_NOT_FOUND => 404,
        ERR_SESSION_NOT_FOUND => 404,
        ERR_INVALID_ARGS => 422,
        ERR_TIMEOUT => 504,
        ERR_CAPABILITY_DENIED => 403,
        _ => 500,
    }
}