Skip to main content

graphrt_wasm/
abi.rs

1//! Wire format exchanged with guest modules (ABI version 1).
2//!
3//! # Guest exports
4//!
5//! | Export | Signature | Purpose |
6//! | --- | --- | --- |
7//! | `memory` | memory | Linear memory used for all buffers. |
8//! | `graphrt_abi_version` | `() -> i32` | Must return [`ABI_VERSION`]. |
9//! | `graphrt_alloc` | `(len: i32) -> i32` | Allocate `len` bytes for a host-written buffer. |
10//! | `graphrt_describe` | `() -> i64` | Packed `(ptr << 32) \| len` of a [`Manifest`] JSON. |
11//! | `graphrt_run` | `(ptr: i32, len: i32) -> i64` | Run one node: reads a [`RunRequest`] JSON, returns a packed [`RunResponse`] JSON. |
12//!
13//! # Host imports (module `graphrt`)
14//!
15//! | Import | Signature | Purpose |
16//! | --- | --- | --- |
17//! | `log` | `(level: i32, ptr: i32, len: i32)` | UTF-8 log line; level 0=trace .. 4=error. |
18//! | `chunk` | `(field_ptr: i32, field_len: i32, ptr: i32, len: i32)` | Stream text for output `field`. |
19//! | `progress` | `(name_ptr: i32, name_len: i32, ptr: i32, len: i32)` | Structured progress, JSON payload. |
20//!
21//! Guests may import any subset of these; importing anything else fails at load.
22
23use graphrt_core::catalog::NodeDescriptor;
24use graphrt_core::indexmap::IndexMap;
25use serde::{Deserialize, Serialize};
26
27/// ABI version implemented by this host.
28pub const ABI_VERSION: i32 = 1;
29
30/// Module providing host imports.
31pub const HOST_MODULE: &str = "graphrt";
32
33/// What a guest module offers.
34#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
35pub struct Manifest {
36    /// Plugin name, e.g. `text-tools`.
37    pub name: String,
38    #[serde(default)]
39    pub version: String,
40    #[serde(default)]
41    pub description: String,
42    /// Node kinds implemented by the module.
43    pub nodes: Vec<NodeDescriptor>,
44}
45
46/// Input for one node run.
47#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
48pub struct RunRequest {
49    /// Node kind being run (one module may implement several).
50    pub kind: String,
51    /// Workflow node id.
52    pub node_id: String,
53    /// Node config with `{{#..#}}` placeholders resolved and `*selector` keys
54    /// accompanied by `<key>_value`.
55    pub config: serde_json::Value,
56    /// 1-based attempt number.
57    pub attempt: u32,
58    /// Present when resuming after the node paused.
59    #[serde(default, skip_serializing_if = "Option::is_none")]
60    pub resume: Option<ResumeData>,
61}
62
63/// Resume data handed back to a guest that paused.
64#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
65pub struct ResumeData {
66    pub state: serde_json::Value,
67    #[serde(default)]
68    pub input: serde_json::Value,
69}
70
71/// Guest result. Exactly one of `outputs`, `pause` or `error` is expected;
72/// a response with `error` or `pause` set is treated as such even if `outputs` is present.
73#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
74pub struct RunResponse {
75    #[serde(default)]
76    pub outputs: Option<IndexMap<String, serde_json::Value>>,
77    /// Selected handle for branching nodes.
78    #[serde(default)]
79    pub branch: Option<String>,
80    #[serde(default)]
81    pub usage: Option<UsageData>,
82    #[serde(default)]
83    pub metadata: Option<IndexMap<String, serde_json::Value>>,
84    #[serde(default)]
85    pub pause: Option<PauseData>,
86    #[serde(default)]
87    pub error: Option<ErrorData>,
88}
89
90/// Token usage reported by a guest (e.g. one that proxies a model via the host in future ABIs).
91#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
92pub struct UsageData {
93    #[serde(default)]
94    pub prompt_tokens: u64,
95    #[serde(default)]
96    pub completion_tokens: u64,
97    #[serde(default)]
98    pub total_tokens: u64,
99}
100
101/// Pause request from a guest.
102#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
103pub struct PauseData {
104    pub kind: String,
105    #[serde(default)]
106    pub data: serde_json::Value,
107    #[serde(default)]
108    pub state: serde_json::Value,
109}
110
111/// Error reported by a guest.
112#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
113pub struct ErrorData {
114    #[serde(default = "default_error_kind")]
115    pub kind: String,
116    pub message: String,
117    #[serde(default)]
118    pub retryable: bool,
119}
120
121fn default_error_kind() -> String {
122    "plugin_error".to_owned()
123}
124
125/// Split a packed `(ptr << 32) | len` return value.
126pub fn unpack(packed: i64) -> (u32, u32) {
127    let bits = u64::from_ne_bytes(packed.to_ne_bytes());
128    let ptr = u32::try_from(bits >> 32).unwrap_or(u32::MAX);
129    let len = u32::try_from(bits & 0xffff_ffff).unwrap_or(u32::MAX);
130    (ptr, len)
131}
132
133/// Pack a pointer and length the way guests return them.
134pub fn pack(ptr: u32, len: u32) -> i64 {
135    let bits = (u64::from(ptr) << 32) | u64::from(len);
136    i64::from_ne_bytes(bits.to_ne_bytes())
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142
143    #[test]
144    fn pack_roundtrip() {
145        for (p, l) in [(0, 0), (1, 2), (u32::MAX, 7), (65536, u32::MAX)] {
146            assert_eq!(unpack(pack(p, l)), (p, l));
147        }
148    }
149
150    #[test]
151    fn response_defaults() {
152        let r: RunResponse = serde_json::from_str(r#"{"error":{"message":"boom"}}"#).unwrap();
153        let e = r.error.unwrap();
154        assert_eq!(e.kind, "plugin_error");
155        assert!(!e.retryable);
156    }
157}