Skip to main content

graphrt_plugin_sdk/
lib.rs

1//! # graphrt-plugin-sdk
2//!
3//! Write graphrt plugins in Rust. A plugin is a small executable that serves
4//! node kinds (and optionally tools) over the graphrt plugin protocol
5//! (newline-delimited JSON-RPC 2.0 on stdin/stdout).
6//!
7//! ```no_run
8//! use graphrt_plugin_sdk::{Plugin, RunResult};
9//!
10//! #[tokio::main(flavor = "current_thread")]
11//! async fn main() -> std::io::Result<()> {
12//!     Plugin::new("acme")
13//!         .node("acme.len", |ctx, req| async move {
14//!             let text = req.config["text"].as_str().unwrap_or_default().to_owned();
15//!             ctx.chunk("log", "counting...");
16//!             Ok(RunResult::new().output("length", text.chars().count()))
17//!         })
18//!         .serve_stdio()
19//!         .await
20//! }
21//! ```
22//!
23//! Pair the executable with a `graphrt-plugin.json` manifest (see the graphrt
24//! plugin documentation). Never print to stdout yourself: it carries the protocol.
25//! Use [`RunCtx::log`] or stderr instead.
26
27use std::collections::HashMap;
28use std::fmt;
29use std::future::Future;
30use std::pin::Pin;
31use std::sync::atomic::{AtomicBool, Ordering};
32use std::sync::{Arc, Mutex};
33
34use serde::Serialize;
35use serde_json::{Map, Value, json};
36use tokio::io::{AsyncBufReadExt, AsyncRead, AsyncWrite, AsyncWriteExt, BufReader};
37use tokio::sync::{Notify, mpsc};
38
39/// Protocol version implemented by this SDK.
40pub const PROTOCOL_VERSION: u32 = 1;
41
42/// Largest accepted incoming message.
43pub const MAX_MESSAGE_BYTES: usize = 16 * 1024 * 1024;
44
45type BoxFuture<T> = Pin<Box<dyn Future<Output = T> + Send + 'static>>;
46type NodeHandler = Arc<dyn Fn(RunCtx, RunRequest) -> BoxFuture<Result<Outcome, PluginError>> + Send + Sync>;
47type ToolHandler = Arc<dyn Fn(ToolCall) -> BoxFuture<Result<ToolResult, PluginError>> + Send + Sync>;
48
49/// A `node.run` request.
50#[derive(Clone, Debug, PartialEq)]
51pub struct RunRequest {
52    pub request_id: String,
53    /// Node kind being run.
54    pub kind: String,
55    /// Id of the node in the workflow.
56    pub node_id: String,
57    /// 1-based attempt number (increments on retries).
58    pub attempt: u32,
59    /// Node configuration with variables already resolved by the host.
60    pub config: Value,
61    /// Present when the node resumes after pausing.
62    pub resume: Option<Resume>,
63}
64
65/// Resume data for a node that paused.
66#[derive(Clone, Debug, PartialEq)]
67pub struct Resume {
68    /// The state returned with [`Outcome::Pause`].
69    pub state: Value,
70    /// Host-supplied input (e.g. a submitted form), `null` if none.
71    pub input: Value,
72}
73
74/// Successful node result.
75#[derive(Clone, Debug, Default, PartialEq, Serialize)]
76pub struct RunResult {
77    pub outputs: Map<String, Value>,
78    #[serde(skip_serializing_if = "Option::is_none")]
79    pub branch: Option<String>,
80    #[serde(skip_serializing_if = "Vec::is_empty")]
81    pub writes: Vec<Value>,
82    #[serde(skip_serializing_if = "Option::is_none")]
83    pub usage: Option<Value>,
84    #[serde(skip_serializing_if = "Map::is_empty")]
85    pub metadata: Map<String, Value>,
86}
87
88impl RunResult {
89    pub fn new() -> Self {
90        Self::default()
91    }
92
93    /// Add an output. Values that fail to serialize become `null`.
94    pub fn output(mut self, name: impl Into<String>, value: impl Serialize) -> Self {
95        self.outputs.insert(name.into(), serde_json::to_value(value).unwrap_or(Value::Null));
96        self
97    }
98
99    /// Select an outgoing branch handle (for nodes declaring handles).
100    pub fn branch(mut self, handle: impl Into<String>) -> Self {
101        self.branch = Some(handle.into());
102        self
103    }
104
105    /// Write a variable outside the node's outputs, e.g. `["conversation", "topic"]`.
106    pub fn write(mut self, selector: &[&str], value: impl Serialize) -> Self {
107        let value = serde_json::to_value(value).unwrap_or(Value::Null);
108        self.writes.push(json!({"selector": selector, "value": value}));
109        self
110    }
111
112    /// Report token usage.
113    pub fn usage(mut self, prompt_tokens: u64, completion_tokens: u64) -> Self {
114        self.usage = Some(json!({
115            "prompt_tokens": prompt_tokens,
116            "completion_tokens": completion_tokens,
117            "total_tokens": prompt_tokens.saturating_add(completion_tokens),
118        }));
119        self
120    }
121
122    /// Attach observability metadata.
123    pub fn meta(mut self, key: impl Into<String>, value: impl Serialize) -> Self {
124        self.metadata.insert(key.into(), serde_json::to_value(value).unwrap_or(Value::Null));
125        self
126    }
127}
128
129/// What a node handler returns.
130#[derive(Clone, Debug, PartialEq)]
131pub enum Outcome {
132    Done(RunResult),
133    /// Pause the run; the node is called again with [`RunRequest::resume`].
134    Pause {
135        kind: String,
136        data: Value,
137        state: Value,
138    },
139}
140
141impl From<RunResult> for Outcome {
142    fn from(r: RunResult) -> Self {
143        Outcome::Done(r)
144    }
145}
146
147impl Outcome {
148    /// Pause with a kind (e.g. `approval`), data shown to the host, and private state.
149    pub fn pause(kind: impl Into<String>, data: impl Serialize, state: impl Serialize) -> Self {
150        Outcome::Pause {
151            kind: kind.into(),
152            data: serde_json::to_value(data).unwrap_or(Value::Null),
153            state: serde_json::to_value(state).unwrap_or(Value::Null),
154        }
155    }
156}
157
158/// An error reported to the host.
159#[derive(Clone, Debug, PartialEq)]
160pub struct PluginError {
161    /// Error category (becomes the node error type).
162    pub kind: String,
163    pub message: String,
164    /// Whether the host may retry.
165    pub retryable: bool,
166    pub retry_after_ms: Option<u64>,
167}
168
169impl PluginError {
170    /// A non-retryable error.
171    pub fn new(kind: impl Into<String>, message: impl Into<String>) -> Self {
172        Self { kind: kind.into(), message: message.into(), retryable: false, retry_after_ms: None }
173    }
174
175    /// A retryable error.
176    pub fn retryable(kind: impl Into<String>, message: impl Into<String>) -> Self {
177        Self { retryable: true, ..Self::new(kind, message) }
178    }
179
180    pub fn retry_after(mut self, ms: u64) -> Self {
181        self.retry_after_ms = Some(ms);
182        self
183    }
184
185    /// Invalid configuration or input.
186    pub fn invalid_input(message: impl Into<String>) -> Self {
187        Self::new("invalid_input", message)
188    }
189}
190
191impl fmt::Display for PluginError {
192    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
193        write!(f, "{}: {}", self.kind, self.message)
194    }
195}
196
197impl std::error::Error for PluginError {}
198
199/// A `tool.call` request.
200#[derive(Clone, Debug, PartialEq)]
201pub struct ToolCall {
202    pub name: String,
203    pub arguments: Value,
204}
205
206/// A tool result.
207#[derive(Clone, Debug, Default, PartialEq, Serialize)]
208pub struct ToolResult {
209    pub text: String,
210    #[serde(skip_serializing_if = "Value::is_null")]
211    pub data: Value,
212    pub is_error: bool,
213    /// Images shown to the model (at most 4; png, jpeg, webp or gif; 5 MiB
214    /// each). Dropped with a note in `text` when the host does not support them.
215    #[serde(skip_serializing_if = "Vec::is_empty")]
216    pub images: Vec<ToolImage>,
217}
218
219/// An image in a tool result.
220#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
221#[serde(untagged)]
222pub enum ToolImage {
223    /// Inline bytes, base64 encoded (standard alphabet).
224    Base64 { media_type: String, data_base64: String },
225    /// A remote `https://` image.
226    Url { url: String },
227}
228
229/// Feature the host lists in `initialize` when `tool.call` results may carry images.
230pub const TOOL_IMAGES_FEATURE: &str = "tool_images";
231
232impl ToolResult {
233    pub fn text(text: impl Into<String>) -> Self {
234        Self { text: text.into(), ..Self::default() }
235    }
236
237    pub fn error(text: impl Into<String>) -> Self {
238        Self { text: text.into(), is_error: true, ..Self::default() }
239    }
240
241    /// Attach an inline image (`media_type` such as `image/png`, data in base64).
242    pub fn with_image_base64(mut self, media_type: impl Into<String>, data_base64: impl Into<String>) -> Self {
243        self.images.push(ToolImage::Base64 { media_type: media_type.into(), data_base64: data_base64.into() });
244        self
245    }
246
247    /// Attach a remote `https://` image.
248    pub fn with_image_url(mut self, url: impl Into<String>) -> Self {
249        self.images.push(ToolImage::Url { url: url.into() });
250        self
251    }
252
253    /// For hosts that did not announce [`TOOL_IMAGES_FEATURE`]: drop the
254    /// images and say so in the text, so older hosts still accept the result.
255    fn without_unsupported_images(mut self, host_supports_images: bool) -> Self {
256        if host_supports_images || self.images.is_empty() {
257            return self;
258        }
259        let count = std::mem::take(&mut self.images).len();
260        let note = format!("[{count} image(s) omitted: the graphrt host does not support image tool results]");
261        self.text = if self.text.is_empty() { note } else { format!("{}\n{note}", self.text) };
262        self
263    }
264
265    pub fn with_data(mut self, data: impl Serialize) -> Self {
266        self.data = serde_json::to_value(data).unwrap_or(Value::Null);
267        self
268    }
269}
270
271/// Per-request context: streaming, progress, logs and cancellation.
272#[derive(Clone)]
273pub struct RunCtx {
274    request_id: String,
275    out: mpsc::UnboundedSender<String>,
276    cancelled: Arc<AtomicBool>,
277    cancel_notify: Arc<Notify>,
278}
279
280impl fmt::Debug for RunCtx {
281    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
282        f.debug_struct("RunCtx").field("request_id", &self.request_id).finish_non_exhaustive()
283    }
284}
285
286impl RunCtx {
287    pub fn request_id(&self) -> &str {
288        &self.request_id
289    }
290
291    /// Stream text for output `field`.
292    pub fn chunk(&self, field: &str, chunk: &str) {
293        self.notify("node.chunk", json!({"request_id": self.request_id, "field": field, "chunk": chunk}));
294    }
295
296    /// Report structured progress.
297    pub fn progress(&self, name: &str, data: impl Serialize) {
298        let data = serde_json::to_value(data).unwrap_or(Value::Null);
299        self.notify("node.progress", json!({"request_id": self.request_id, "name": name, "data": data}));
300    }
301
302    /// Log a line on the host (`debug`, `info`, `warn` or `error`).
303    pub fn log(&self, level: &str, message: &str) {
304        self.notify("log", json!({"level": level, "message": message}));
305    }
306
307    /// Whether the host cancelled this request.
308    pub fn is_cancelled(&self) -> bool {
309        self.cancelled.load(Ordering::SeqCst)
310    }
311
312    /// Resolves when the host cancels this request.
313    pub async fn cancelled(&self) {
314        loop {
315            let notified = self.cancel_notify.notified();
316            if self.is_cancelled() {
317                return;
318            }
319            notified.await;
320        }
321    }
322
323    fn notify(&self, method: &str, params: Value) {
324        let _host_gone = self.out.send(json!({"jsonrpc": "2.0", "method": method, "params": params}).to_string());
325    }
326}
327
328/// A plugin: a set of node kinds and tools.
329#[derive(Clone, Default)]
330pub struct Plugin {
331    name: String,
332    nodes: HashMap<String, NodeHandler>,
333    descriptors: Vec<Value>,
334    tools: HashMap<String, ToolHandler>,
335    tool_specs: Vec<Value>,
336}
337
338impl fmt::Debug for Plugin {
339    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
340        let mut kinds: Vec<&String> = self.nodes.keys().collect();
341        kinds.sort();
342        f.debug_struct("Plugin").field("name", &self.name).field("nodes", &kinds).finish_non_exhaustive()
343    }
344}
345
346impl Plugin {
347    pub fn new(name: impl Into<String>) -> Self {
348        Self { name: name.into(), ..Self::default() }
349    }
350
351    /// Register a node kind handler.
352    pub fn node<F, Fut, O>(mut self, kind: impl Into<String>, handler: F) -> Self
353    where
354        F: Fn(RunCtx, RunRequest) -> Fut + Send + Sync + 'static,
355        Fut: Future<Output = Result<O, PluginError>> + Send + 'static,
356        O: Into<Outcome>,
357    {
358        let handler: NodeHandler = Arc::new(move |ctx, req| {
359            let fut = handler(ctx, req);
360            Box::pin(async move { fut.await.map(Into::into) })
361        });
362        self.nodes.insert(kind.into(), handler);
363        self
364    }
365
366    /// Publish a node descriptor from `initialize` (optional; the manifest is
367    /// usually enough). `descriptor` follows the graphrt node catalog format.
368    pub fn describe(mut self, descriptor: Value) -> Self {
369        self.descriptors.push(descriptor);
370        self
371    }
372
373    /// Register a tool. `spec` is `{name, description, parameters}`.
374    pub fn tool<F, Fut>(mut self, spec: Value, handler: F) -> Self
375    where
376        F: Fn(ToolCall) -> Fut + Send + Sync + 'static,
377        Fut: Future<Output = Result<ToolResult, PluginError>> + Send + 'static,
378    {
379        let name = spec.get("name").and_then(Value::as_str).unwrap_or_default().to_owned();
380        let handler: ToolHandler = Arc::new(move |call| Box::pin(handler(call)));
381        self.tools.insert(name, handler);
382        self.tool_specs.push(spec);
383        self
384    }
385
386    /// Serve the protocol on stdin/stdout until stdin closes or `shutdown` arrives.
387    pub async fn serve_stdio(self) -> std::io::Result<()> {
388        self.serve(tokio::io::stdin(), tokio::io::stdout()).await
389    }
390
391    /// Serve the protocol on any reader/writer pair (useful for tests and
392    /// in-process plugins).
393    pub async fn serve<R, W>(self, reader: R, writer: W) -> std::io::Result<()>
394    where
395        R: AsyncRead + Unpin + Send + 'static,
396        W: AsyncWrite + Unpin + Send + 'static,
397    {
398        let plugin = Arc::new(self);
399        let (out_tx, mut out_rx) = mpsc::unbounded_channel::<String>();
400        let writer_task = tokio::spawn(async move {
401            let mut writer = writer;
402            while let Some(mut line) = out_rx.recv().await {
403                line.push('\n');
404                if writer.write_all(line.as_bytes()).await.is_err() || writer.flush().await.is_err() {
405                    break;
406                }
407            }
408        });
409
410        let running: Arc<Mutex<HashMap<String, Running>>> = Arc::new(Mutex::new(HashMap::new()));
411        let mut lines = BufReader::new(reader);
412        let mut buf = Vec::new();
413        let mut shutdown = false;
414        // The host announces its line limit and optional features in `initialize`.
415        let mut limit = MAX_MESSAGE_BYTES;
416        let mut host_supports_images = false;
417        loop {
418            buf.clear();
419            match read_line_capped(&mut lines, &mut buf, limit).await? {
420                Line::Eof => break,
421                Line::Oversized => {
422                    eprintln!("graphrt plugin {}: dropped a message above {limit} bytes", plugin.name);
423                    let id = recover_id(&buf);
424                    let msg = format!("message exceeds the {limit}-byte limit");
425                    send(&out_tx, error_response(&id, -32600, &msg, Some(json!({"kind": "message_too_large"}))));
426                    continue;
427                }
428                Line::Complete => {}
429            }
430            let Ok(text) = std::str::from_utf8(&buf) else {
431                eprintln!("graphrt plugin {}: message is not valid UTF-8", plugin.name);
432                let data = Some(json!({"kind": "plugin_protocol"}));
433                send(&out_tx, error_response(&recover_id(&buf), -32700, "message is not valid UTF-8", data));
434                continue;
435            };
436            let text = text.trim();
437            if text.is_empty() {
438                continue;
439            }
440            let Ok(msg) = serde_json::from_str::<Value>(text) else {
441                eprintln!("graphrt plugin {}: unreadable message", plugin.name);
442                let data = Some(json!({"kind": "plugin_protocol"}));
443                send(&out_tx, error_response(&recover_id(&buf), -32700, "parse error", data));
444                continue;
445            };
446            if let Some(announced) = msg
447                .get("params")
448                .and_then(|p| p.get("max_message_bytes"))
449                .and_then(Value::as_u64)
450                .filter(|_| msg.get("method").and_then(Value::as_str) == Some("initialize"))
451            {
452                limit = usize::try_from(announced).unwrap_or(usize::MAX).max(1024);
453            }
454            let id = msg.get("id").cloned();
455            let method = msg.get("method").and_then(Value::as_str).unwrap_or_default().to_owned();
456            let params = msg.get("params").cloned().unwrap_or(Value::Null);
457            match (method.as_str(), id) {
458                ("shutdown", _) => {
459                    shutdown = true;
460                    break;
461                }
462                ("node.cancel", None) => {
463                    let request_id = params.get("request_id").and_then(Value::as_str).unwrap_or_default();
464                    if let Some(r) = running.lock().ok().and_then(|mut m| m.remove(request_id)) {
465                        r.cancelled.store(true, Ordering::SeqCst);
466                        r.notify.notify_waiters();
467                        r.task.abort();
468                    }
469                }
470                (_, None) => {}
471                ("initialize", Some(id)) => {
472                    host_supports_images = params
473                        .get("features")
474                        .and_then(Value::as_array)
475                        .is_some_and(|f| f.iter().any(|v| v.as_str() == Some(TOOL_IMAGES_FEATURE)));
476                    let mut result = Map::new();
477                    result.insert("protocol_version".into(), json!(PROTOCOL_VERSION));
478                    result.insert("name".into(), json!(plugin.name));
479                    if !plugin.descriptors.is_empty() {
480                        result.insert("nodes".into(), Value::Array(plugin.descriptors.clone()));
481                    }
482                    if !plugin.tool_specs.is_empty() {
483                        result.insert("tools".into(), Value::Array(plugin.tool_specs.clone()));
484                    }
485                    let result = Value::Object(result);
486                    send(&out_tx, ok_response(&id, result));
487                }
488                ("node.run", Some(id)) => plugin.start_run(id, params, &out_tx, &running),
489                ("tool.list", Some(id)) => {
490                    send(&out_tx, ok_response(&id, json!({"tools": plugin.tool_specs})));
491                }
492                ("tool.call", Some(id)) => {
493                    plugin.start_tool(id, params, &out_tx, ToolHost { supports_images: host_supports_images, limit });
494                }
495                (other, Some(id)) => {
496                    send(&out_tx, error_response(&id, -32601, &format!("method `{other}` not found"), None));
497                }
498            }
499        }
500        // `shutdown` stops in-flight work; end of input lets it finish and reply.
501        let in_flight: Vec<Running> =
502            running.lock().map(|mut m| m.drain().map(|(_, r)| r).collect()).unwrap_or_default();
503        for r in in_flight {
504            if shutdown {
505                r.task.abort();
506            } else {
507                let _finished_or_aborted = r.task.await;
508            }
509        }
510        // Tool tasks hold their own sender, so the writer drains until they finish.
511        drop(out_tx);
512        let _writer_done = writer_task.await;
513        Ok(())
514    }
515
516    fn start_run(
517        &self,
518        id: Value,
519        params: Value,
520        out: &mpsc::UnboundedSender<String>,
521        running: &Arc<Mutex<HashMap<String, Running>>>,
522    ) {
523        let request_id =
524            params.get("request_id").and_then(Value::as_str).map(str::to_owned).unwrap_or_else(|| id_text(&id));
525        let kind = params.get("kind").and_then(Value::as_str).unwrap_or_default().to_owned();
526        let Some(handler) = self.nodes.get(&kind).cloned() else {
527            let msg = format!("plugin `{}` has no node kind `{kind}`", self.name);
528            send(out, error_response(&id, -32602, &msg, Some(json!({"kind": "unknown_kind"}))));
529            return;
530        };
531        let resume = params.get("resume").filter(|r| !r.is_null()).map(|r| Resume {
532            state: r.get("state").cloned().unwrap_or(Value::Null),
533            input: r.get("input").cloned().unwrap_or(Value::Null),
534        });
535        let req = RunRequest {
536            request_id: request_id.clone(),
537            kind,
538            node_id: params.get("node_id").and_then(Value::as_str).unwrap_or_default().to_owned(),
539            attempt: params.get("attempt").and_then(Value::as_u64).and_then(|a| u32::try_from(a).ok()).unwrap_or(1),
540            config: params.get("config").cloned().unwrap_or(Value::Object(Map::new())),
541            resume,
542        };
543        let cancelled = Arc::new(AtomicBool::new(false));
544        let notify = Arc::new(Notify::new());
545        let ctx = RunCtx {
546            request_id: request_id.clone(),
547            out: out.clone(),
548            cancelled: cancelled.clone(),
549            cancel_notify: notify.clone(),
550        };
551        let out = out.clone();
552        let registry = running.clone();
553        let rid = request_id.clone();
554        // Hold the registry lock while spawning so a fast task cannot finish (and try
555        // to deregister) before it is registered.
556        let Ok(mut map) = running.lock() else { return };
557        let task = tokio::spawn(async move {
558            // The handler runs in its own task so a panic becomes an error reply
559            // instead of a silent timeout on the host. Aborting this task (cancel)
560            // aborts the handler too.
561            let inner = AbortOnDrop(tokio::spawn(handler(ctx, req)));
562            let line = match join_handler(inner).await {
563                Some(Ok(Outcome::Done(r))) => encode_result(&id, &r),
564                Some(Ok(Outcome::Pause { kind, data, state })) => {
565                    ok_response(&id, json!({"pause": {"kind": kind, "data": data, "state": state}}))
566                }
567                Some(Err(e)) => plugin_error_response(&id, &e),
568                None => {
569                    // Cancelled: the host abandoned the request.
570                    if let Ok(mut m) = registry.lock() {
571                        m.remove(&rid);
572                    }
573                    return;
574                }
575            };
576            send(&out, line);
577            if let Ok(mut m) = registry.lock() {
578                m.remove(&rid);
579            }
580        });
581        map.insert(request_id, Running { task, cancelled, notify });
582    }
583
584    fn start_tool(&self, id: Value, params: Value, out: &mpsc::UnboundedSender<String>, host: ToolHost) {
585        let name = params.get("name").and_then(Value::as_str).unwrap_or_default().to_owned();
586        let Some(handler) = self.tools.get(&name).cloned() else {
587            let msg = format!("plugin `{}` has no tool `{name}`", self.name);
588            send(out, error_response(&id, -32602, &msg, Some(json!({"kind": "unknown_tool"}))));
589            return;
590        };
591        let call = ToolCall { name, arguments: params.get("arguments").cloned().unwrap_or(Value::Null) };
592        let out = out.clone();
593        tokio::spawn(async move {
594            let inner = AbortOnDrop(tokio::spawn(handler(call)));
595            let line = match join_handler(inner).await {
596                Some(Ok(r)) => encode_result(&id, &r.without_unsupported_images(host.supports_images)),
597                Some(Err(e)) => plugin_error_response(&id, &e),
598                None => return,
599            };
600            // A line above the host's limit would break the connection: report it instead.
601            let line = if line.len() > host.limit {
602                let msg = format!("tool result is {} bytes, above the {}-byte message limit", line.len(), host.limit);
603                error_response(&id, -32000, &msg, Some(json!({"kind": "message_too_large"})))
604            } else {
605                line
606            };
607            send(&out, line);
608        });
609    }
610}
611
612/// What the host announced in `initialize` that shapes tool results.
613#[derive(Clone, Copy, Debug)]
614struct ToolHost {
615    supports_images: bool,
616    limit: usize,
617}
618
619/// Aborts the wrapped task when dropped (so cancelling the outer task stops the handler).
620struct AbortOnDrop<T>(tokio::task::JoinHandle<T>);
621
622impl<T> Drop for AbortOnDrop<T> {
623    fn drop(&mut self) {
624        self.0.abort();
625    }
626}
627
628/// Wait for a handler task. A panic becomes a `plugin_panic` error; `None` means
629/// the task was cancelled.
630async fn join_handler<T>(mut task: AbortOnDrop<Result<T, PluginError>>) -> Option<Result<T, PluginError>> {
631    match (&mut task.0).await {
632        Ok(result) => Some(result),
633        Err(e) if e.is_panic() => {
634            let payload = e.into_panic();
635            let message = payload
636                .downcast_ref::<&str>()
637                .map(|s| (*s).to_owned())
638                .or_else(|| payload.downcast_ref::<String>().cloned())
639                .unwrap_or_else(|| "unknown panic".to_owned());
640            eprintln!("graphrt plugin handler panicked: {message}");
641            Some(Err(PluginError::new("plugin_panic", format!("handler panicked: {message}"))))
642        }
643        Err(_) => None,
644    }
645}
646
647/// Serialize a handler result, replying with an error when it cannot be encoded
648/// (never a `null` result the host would mistake for success).
649fn encode_result<T: Serialize>(id: &Value, result: &T) -> String {
650    match serde_json::to_value(result) {
651        Ok(value) => ok_response(id, value),
652        Err(e) => error_response(
653            id,
654            -32000,
655            &format!("result is not valid JSON: {e}"),
656            Some(json!({"kind": "invalid_output"})),
657        ),
658    }
659}
660
661/// Best-effort request id from the start of a line that could not be read.
662fn recover_id(line: &[u8]) -> Value {
663    let head = String::from_utf8_lossy(line.get(..line.len().min(4096)).unwrap_or_default()).into_owned();
664    let Some(pos) = head.find("\"id\"") else { return Value::Null };
665    let rest = head.get(pos + 4..).unwrap_or_default().trim_start();
666    let Some(rest) = rest.strip_prefix(':') else { return Value::Null };
667    let rest = rest.trim_start();
668    // A string id or an integer id.
669    if let Some(body) = rest.strip_prefix('"') {
670        let mut out = String::new();
671        let mut escaped = false;
672        for c in body.chars() {
673            match (escaped, c) {
674                (true, c) => {
675                    out.push(c);
676                    escaped = false;
677                }
678                (false, '\\') => escaped = true,
679                (false, '"') => return Value::String(out),
680                (false, c) => out.push(c),
681            }
682        }
683        return Value::Null;
684    }
685    let digits: String = rest.chars().take_while(|c| c.is_ascii_digit() || *c == '-').collect();
686    digits.parse::<i64>().map(Value::from).unwrap_or(Value::Null)
687}
688
689struct Running {
690    task: tokio::task::JoinHandle<()>,
691    cancelled: Arc<AtomicBool>,
692    notify: Arc<Notify>,
693}
694
695fn id_text(id: &Value) -> String {
696    match id {
697        Value::String(s) => s.clone(),
698        other => other.to_string(),
699    }
700}
701
702fn send(out: &mpsc::UnboundedSender<String>, line: String) {
703    let _host_gone = out.send(line);
704}
705
706fn ok_response(id: &Value, result: Value) -> String {
707    json!({"jsonrpc": "2.0", "id": id, "result": result}).to_string()
708}
709
710fn error_response(id: &Value, code: i64, message: &str, data: Option<Value>) -> String {
711    let mut error = Map::new();
712    error.insert("code".into(), json!(code));
713    error.insert("message".into(), json!(message));
714    if let Some(data) = data {
715        error.insert("data".into(), data);
716    }
717    json!({"jsonrpc": "2.0", "id": id, "error": Value::Object(error)}).to_string()
718}
719
720fn plugin_error_response(id: &Value, e: &PluginError) -> String {
721    let mut data = Map::new();
722    data.insert("kind".into(), json!(e.kind));
723    data.insert("retryable".into(), json!(e.retryable));
724    if let Some(ms) = e.retry_after_ms {
725        data.insert("retry_after_ms".into(), json!(ms));
726    }
727    error_response(id, -32000, &e.message, Some(Value::Object(data)))
728}
729
730/// Result of reading one line.
731enum Line {
732    Complete,
733    /// Longer than the limit: the rest of the line was discarded, `buf` holds its start.
734    Oversized,
735    Eof,
736}
737
738/// Read one `\n`-terminated line. Lines above `max` bytes are skipped up to their
739/// newline (keeping the stream in sync) and reported as [`Line::Oversized`].
740async fn read_line_capped<R: tokio::io::AsyncBufRead + Unpin>(
741    reader: &mut R,
742    buf: &mut Vec<u8>,
743    max: usize,
744) -> std::io::Result<Line> {
745    let mut oversized = false;
746    loop {
747        let available = reader.fill_buf().await?;
748        if available.is_empty() {
749            return Ok(match (buf.is_empty(), oversized) {
750                (_, true) => Line::Oversized,
751                (true, false) => Line::Eof,
752                (false, false) => Line::Complete,
753            });
754        }
755        let (chunk, done) = match available.iter().position(|b| *b == b'\n') {
756            Some(pos) => (available.get(..=pos).unwrap_or(available), true),
757            None => (available, false),
758        };
759        if !oversized && buf.len().saturating_add(chunk.len()) > max {
760            oversized = true;
761            // Keep the head (for recovering the request id), drop the rest.
762            let room = 4096usize.saturating_sub(buf.len());
763            buf.extend_from_slice(chunk.get(..room.min(chunk.len())).unwrap_or_default());
764        } else if !oversized {
765            buf.extend_from_slice(chunk);
766        }
767        let used = chunk.len();
768        reader.consume(used);
769        if done {
770            return Ok(if oversized { Line::Oversized } else { Line::Complete });
771        }
772    }
773}
774
775#[cfg(test)]
776mod tests {
777    use super::*;
778
779    async fn roundtrip(plugin: Plugin, input: &str) -> Vec<Value> {
780        let (client, server) = tokio::io::duplex(1 << 16);
781        let (server_r, server_w) = tokio::io::split(server);
782        let serve = tokio::spawn(plugin.serve(server_r, server_w));
783        let (client_r, mut client_w) = tokio::io::split(client);
784        client_w.write_all(input.as_bytes()).await.unwrap();
785        client_w.shutdown().await.unwrap();
786        let mut out = String::new();
787        let mut reader = BufReader::new(client_r);
788        let mut line = String::new();
789        while reader.read_line(&mut line).await.unwrap() > 0 {
790            out.push_str(&line);
791            line.clear();
792        }
793        serve.await.unwrap().unwrap();
794        out.lines().map(|l| serde_json::from_str(l).unwrap()).collect()
795    }
796
797    #[tokio::test]
798    async fn handles_initialize_run_and_errors() {
799        let plugin = Plugin::new("t")
800            .node("t.echo", |ctx, req| async move {
801                ctx.chunk("text", "hi");
802                Ok(RunResult::new().output("echo", req.config["x"].clone()))
803            })
804            .node("t.fail", |_ctx, _req| async move {
805                Err::<RunResult, _>(PluginError::retryable("busy", "try later").retry_after(5))
806            })
807            .node("t.pause", |_ctx, req| async move {
808                match req.resume {
809                    None => Ok(Outcome::pause("approval", json!({"q": "ok?"}), json!({"step": 1}))),
810                    Some(r) => Ok(RunResult::new().output("state", r.state).output("input", r.input).into()),
811                }
812            })
813            .tool(json!({"name": "add", "description": "", "parameters": {}}), |call| async move {
814                let a = call.arguments["a"].as_i64().unwrap_or(0);
815                Ok(ToolResult::text(format!("{}", a + 1)))
816            });
817        let input = [
818            r#"{"jsonrpc":"2.0","id":"i","method":"initialize","params":{}}"#,
819            r#"{"jsonrpc":"2.0","id":"r-1","method":"node.run","params":{"request_id":"r-1","kind":"t.echo","config":{"x":5}}}"#,
820            r#"{"jsonrpc":"2.0","id":"r-2","method":"node.run","params":{"request_id":"r-2","kind":"t.fail","config":{}}}"#,
821            r#"{"jsonrpc":"2.0","id":"r-3","method":"node.run","params":{"request_id":"r-3","kind":"t.nope","config":{}}}"#,
822            r#"{"jsonrpc":"2.0","id":"r-4","method":"node.run","params":{"request_id":"r-4","kind":"t.pause","config":{}}}"#,
823            r#"{"jsonrpc":"2.0","id":"r-5","method":"node.run","params":{"request_id":"r-5","kind":"t.pause","config":{},"resume":{"state":{"step":1},"input":"yes"}}}"#,
824            r#"{"jsonrpc":"2.0","id":"t-1","method":"tool.call","params":{"name":"add","arguments":{"a":41}}}"#,
825            r#"{"jsonrpc":"2.0","id":"x","method":"bogus"}"#,
826            "",
827        ]
828        .join("\n");
829        // Give spawned handlers time to answer before stdin closes the loop.
830        let msgs = tokio::time::timeout(std::time::Duration::from_secs(5), async {
831            let plugin = plugin;
832            roundtrip_wait(plugin, &input).await
833        })
834        .await
835        .unwrap();
836        let by_id = |id: &str| msgs.iter().find(|m| m["id"] == id).cloned().unwrap_or_default();
837        assert_eq!(by_id("i")["result"]["protocol_version"], 1);
838        assert_eq!(by_id("i")["result"]["tools"][0]["name"], "add");
839        assert_eq!(by_id("r-1")["result"]["outputs"]["echo"], 5);
840        assert!(msgs.iter().any(|m| m["method"] == "node.chunk" && m["params"]["request_id"] == "r-1"));
841        assert_eq!(by_id("r-2")["error"]["data"]["retryable"], true);
842        assert_eq!(by_id("r-2")["error"]["data"]["retry_after_ms"], 5);
843        assert_eq!(by_id("r-3")["error"]["code"], -32602);
844        assert_eq!(by_id("r-4")["result"]["pause"]["state"]["step"], 1);
845        assert_eq!(by_id("r-5")["result"]["outputs"]["input"], "yes");
846        assert_eq!(by_id("t-1")["result"]["text"], "42");
847        assert_eq!(by_id("x")["error"]["code"], -32601);
848    }
849
850    fn screenshot_plugin() -> Plugin {
851        Plugin::new("screen").tool(json!({"name": "shot", "description": "", "parameters": {}}), |call| async move {
852            let size = call.arguments["size"].as_u64().unwrap_or(8) as usize;
853            Ok(ToolResult::text("800x600").with_image_base64("image/png", "A".repeat(size)))
854        })
855    }
856
857    async fn call_shot(init_params: &str, size: usize) -> Value {
858        let input = [
859            format!(r#"{{"jsonrpc":"2.0","id":"i","method":"initialize","params":{init_params}}}"#),
860            format!(r#"{{"jsonrpc":"2.0","id":"t","method":"tool.call","params":{{"name":"shot","arguments":{{"size":{size}}}}}}}"#),
861            String::new(),
862        ]
863        .join("\n");
864        let msgs = tokio::time::timeout(std::time::Duration::from_secs(5), roundtrip_wait(screenshot_plugin(), &input))
865            .await
866            .unwrap();
867        msgs.into_iter().find(|m| m["id"] == "t").unwrap_or_default()
868    }
869
870    #[tokio::test]
871    async fn tool_images_are_sent_to_hosts_that_support_them() {
872        let reply = call_shot(r#"{"features":["tool_images"]}"#, 8).await;
873        assert_eq!(
874            reply["result"],
875            json!({"text": "800x600", "is_error": false, "images": [{"media_type": "image/png", "data_base64": "AAAAAAAA"}]})
876        );
877    }
878
879    #[tokio::test]
880    async fn tool_images_are_dropped_for_older_hosts() {
881        let reply = call_shot("{}", 8).await;
882        assert_eq!(
883            reply["result"],
884            json!({"text": "800x600\n[1 image(s) omitted: the graphrt host does not support image tool results]", "is_error": false})
885        );
886    }
887
888    #[tokio::test]
889    async fn oversized_tool_results_are_reported_not_sent() {
890        let reply = call_shot(r#"{"features":["tool_images"],"max_message_bytes":2048}"#, 4096).await;
891        assert_eq!(reply["error"]["data"]["kind"], "message_too_large");
892        assert!(reply.get("result").is_none());
893    }
894
895    /// Like [`roundtrip`], but keeps stdin open until every request is answered.
896    async fn roundtrip_wait(plugin: Plugin, input: &str) -> Vec<Value> {
897        let expected = input.lines().filter(|l| l.contains("\"id\"")).count();
898        let (client, server) = tokio::io::duplex(1 << 16);
899        let (server_r, server_w) = tokio::io::split(server);
900        let serve = tokio::spawn(plugin.serve(server_r, server_w));
901        let (client_r, mut client_w) = tokio::io::split(client);
902        client_w.write_all(input.as_bytes()).await.unwrap();
903        let mut reader = BufReader::new(client_r);
904        let mut msgs = Vec::new();
905        let mut responses = 0;
906        let mut line = String::new();
907        while responses < expected {
908            line.clear();
909            if reader.read_line(&mut line).await.unwrap() == 0 {
910                break;
911            }
912            let v: Value = serde_json::from_str(line.trim()).unwrap();
913            if v.get("id").is_some() {
914                responses += 1;
915            }
916            msgs.push(v);
917        }
918        client_w.shutdown().await.unwrap();
919        serve.await.unwrap().unwrap();
920        msgs
921    }
922
923    #[tokio::test]
924    async fn shutdown_and_eof_end_the_loop() {
925        let msgs = roundtrip(Plugin::new("t"), "{\"jsonrpc\":\"2.0\",\"method\":\"shutdown\"}\n").await;
926        assert!(msgs.is_empty());
927        let msgs = roundtrip(Plugin::new("t"), "not json\n").await;
928        assert_eq!(msgs[0]["error"]["code"], -32700);
929    }
930
931    #[tokio::test]
932    async fn cancel_aborts_the_handler() {
933        let plugin = Plugin::new("t").node("t.slow", |ctx, _req| async move {
934            ctx.cancelled().await;
935            Ok(RunResult::new())
936        });
937        let (client, server) = tokio::io::duplex(1 << 16);
938        let (server_r, server_w) = tokio::io::split(server);
939        let serve = tokio::spawn(plugin.serve(server_r, server_w));
940        let (client_r, mut client_w) = tokio::io::split(client);
941        let run = r#"{"jsonrpc":"2.0","id":"r-1","method":"node.run","params":{"request_id":"r-1","kind":"t.slow","config":{}}}"#;
942        let cancel = r#"{"jsonrpc":"2.0","method":"node.cancel","params":{"request_id":"r-1"}}"#;
943        client_w.write_all(format!("{run}\n{cancel}\n").as_bytes()).await.unwrap();
944        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
945        client_w.shutdown().await.unwrap();
946        tokio::time::timeout(std::time::Duration::from_secs(2), serve).await.unwrap().unwrap().unwrap();
947        let mut rest = String::new();
948        let mut reader = BufReader::new(client_r);
949        let mut line = String::new();
950        while reader.read_line(&mut line).await.unwrap() > 0 {
951            rest.push_str(&line);
952            line.clear();
953        }
954        // A cancelled request gets no response.
955        assert!(!rest.contains("\"r-1\""), "{rest}");
956    }
957
958    #[tokio::test]
959    async fn panicking_handler_replies_with_an_error() {
960        let plugin = Plugin::new("t").node("t.panic", |_ctx, _req| async move {
961            if true {
962                panic!("kaboom");
963            }
964            Ok(RunResult::new())
965        });
966        let run = r#"{"jsonrpc":"2.0","id":"r-1","method":"node.run","params":{"request_id":"r-1","kind":"t.panic","config":{}}}"#;
967        let msgs = roundtrip(plugin, &format!("{run}\n")).await;
968        assert_eq!(msgs.len(), 1, "{msgs:?}");
969        assert_eq!(msgs[0]["id"], "r-1");
970        assert_eq!(msgs[0]["error"]["data"]["kind"], "plugin_panic");
971        assert!(msgs[0]["error"]["message"].as_str().unwrap().contains("kaboom"));
972    }
973
974    #[tokio::test]
975    async fn oversized_message_is_answered_and_stream_stays_in_sync() {
976        let plugin = Plugin::new("t").node("t.ok", |_ctx, _req| async move { Ok(RunResult::new().output("ok", true)) });
977        // The host announces a small limit, then sends a line above it, then a normal request.
978        let init = r#"{"jsonrpc":"2.0","id":"i","method":"initialize","params":{"max_message_bytes":2048}}"#;
979        let big = format!(
980            r#"{{"jsonrpc":"2.0","id":"r-big","method":"node.run","params":{{"kind":"t.ok","config":{{"x":"{}"}}}}}}"#,
981            "y".repeat(5000)
982        );
983        let ok = r#"{"jsonrpc":"2.0","id":"r-2","method":"node.run","params":{"request_id":"r-2","kind":"t.ok","config":{}}}"#;
984        let msgs = roundtrip(plugin, &format!("{init}\n{big}\n{ok}\n")).await;
985        let big_reply = msgs.iter().find(|m| m["id"] == "r-big").expect("reply to oversized request");
986        assert_eq!(big_reply["error"]["data"]["kind"], "message_too_large");
987        let ok_reply = msgs.iter().find(|m| m["id"] == "r-2").expect("later request still served");
988        assert_eq!(ok_reply["result"]["outputs"]["ok"], true);
989    }
990}