1use 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
39pub const PROTOCOL_VERSION: u32 = 1;
41
42pub 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#[derive(Clone, Debug, PartialEq)]
51pub struct RunRequest {
52 pub request_id: String,
53 pub kind: String,
55 pub node_id: String,
57 pub attempt: u32,
59 pub config: Value,
61 pub resume: Option<Resume>,
63}
64
65#[derive(Clone, Debug, PartialEq)]
67pub struct Resume {
68 pub state: Value,
70 pub input: Value,
72}
73
74#[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 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 pub fn branch(mut self, handle: impl Into<String>) -> Self {
101 self.branch = Some(handle.into());
102 self
103 }
104
105 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 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 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#[derive(Clone, Debug, PartialEq)]
131pub enum Outcome {
132 Done(RunResult),
133 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 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#[derive(Clone, Debug, PartialEq)]
160pub struct PluginError {
161 pub kind: String,
163 pub message: String,
164 pub retryable: bool,
166 pub retry_after_ms: Option<u64>,
167}
168
169impl PluginError {
170 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 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 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#[derive(Clone, Debug, PartialEq)]
201pub struct ToolCall {
202 pub name: String,
203 pub arguments: Value,
204}
205
206#[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 #[serde(skip_serializing_if = "Vec::is_empty")]
216 pub images: Vec<ToolImage>,
217}
218
219#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
221#[serde(untagged)]
222pub enum ToolImage {
223 Base64 { media_type: String, data_base64: String },
225 Url { url: String },
227}
228
229pub 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 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 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 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#[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 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 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 pub fn log(&self, level: &str, message: &str) {
304 self.notify("log", json!({"level": level, "message": message}));
305 }
306
307 pub fn is_cancelled(&self) -> bool {
309 self.cancelled.load(Ordering::SeqCst)
310 }
311
312 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#[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 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 pub fn describe(mut self, descriptor: Value) -> Self {
369 self.descriptors.push(descriptor);
370 self
371 }
372
373 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 pub async fn serve_stdio(self) -> std::io::Result<()> {
388 self.serve(tokio::io::stdin(), tokio::io::stdout()).await
389 }
390
391 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 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 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 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 let Ok(mut map) = running.lock() else { return };
557 let task = tokio::spawn(async move {
558 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 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 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#[derive(Clone, Copy, Debug)]
614struct ToolHost {
615 supports_images: bool,
616 limit: usize,
617}
618
619struct 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
628async 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
647fn 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
661fn 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 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
730enum Line {
732 Complete,
733 Oversized,
735 Eof,
736}
737
738async 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 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 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 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 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 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}