Skip to main content

pixie_pi/ai/
stream.rs

1//! Streaming primitives: the SSE decoder, a tolerant streaming-JSON parser,
2//! the fine-grained [`AssistantMessageEvent`] protocol, and the
3//! [`AssistantStream`] type that providers return.
4
5use std::pin::Pin;
6
7use futures::Stream;
8use serde_json::Value;
9use tokio::sync::mpsc;
10use tokio_stream::wrappers::ReceiverStream;
11
12use super::types::{AssistantMessage, StopReason};
13
14/// A raw Server-Sent Event decoded from the HTTP response body.
15#[derive(Debug, Clone)]
16pub struct ServerSentEvent {
17    pub event: Option<String>,
18    pub data: String,
19}
20
21/// Incremental line-buffered SSE decoder (mirrors pi's `iterateSseMessages`).
22///
23/// Feed it raw bytes via [`SseDecoder::feed`] and call [`SseDecoder::finish`]
24/// when the stream ends. An SSE event is delimited by a blank line.
25#[derive(Default)]
26pub struct SseDecoder {
27    event: Option<String>,
28    data: Vec<String>,
29    buffer: String,
30}
31
32impl SseDecoder {
33    pub fn new() -> Self {
34        Self::default()
35    }
36
37    /// Append bytes and return any complete SSE events.
38    pub fn feed(&mut self, bytes: &[u8]) -> Vec<ServerSentEvent> {
39        self.buffer.push_str(&String::from_utf8_lossy(bytes));
40        let mut out = Vec::new();
41        while let Some((line, rest)) = consume_line(&self.buffer) {
42            self.buffer = rest;
43            if let Some(ev) = self.decode_line(&line) {
44                out.push(ev);
45            }
46        }
47        out
48    }
49
50    /// Flush any trailing buffered data. Call once the body stream ends.
51    pub fn finish(&mut self) -> Vec<ServerSentEvent> {
52        let mut out = Vec::new();
53        if !self.buffer.is_empty() {
54            let line = std::mem::take(&mut self.buffer);
55            if let Some(ev) = self.decode_line(&line) {
56                out.push(ev);
57            }
58        }
59        if let Some(ev) = self.flush_event() {
60            out.push(ev);
61        }
62        out
63    }
64
65    fn decode_line(&mut self, line: &str) -> Option<ServerSentEvent> {
66        if line.is_empty() {
67            return self.flush_event();
68        }
69        // Comment line.
70        if line.starts_with(':') {
71            return None;
72        }
73        let (field, value) = match line.find(':') {
74            Some(idx) => {
75                let value = &line[idx + 1..];
76                let value = value.strip_prefix(' ').unwrap_or(value);
77                (&line[..idx], value)
78            }
79            None => (line, ""),
80        };
81        match field {
82            "event" => self.event = Some(value.to_string()),
83            "data" => self.data.push(value.to_string()),
84            _ => {}
85        }
86        None
87    }
88
89    fn flush_event(&mut self) -> Option<ServerSentEvent> {
90        if self.event.is_none() && self.data.is_empty() {
91            return None;
92        }
93        let event = ServerSentEvent {
94            event: self.event.take(),
95            data: self.data.join("\n"),
96        };
97        self.data.clear();
98        Some(event)
99    }
100}
101
102/// Split off the first line of `text`, handling both `\n` and `\r\n`.
103fn consume_line(text: &str) -> Option<(String, String)> {
104    let bytes = text.as_bytes();
105    let cr = text.find('\r');
106    let lf = text.find('\n');
107    let idx = match (cr, lf) {
108        (None, None) => return None,
109        (None, Some(l)) => l,
110        (Some(c), None) => c,
111        (Some(c), Some(l)) => c.min(l),
112    };
113    let mut next = idx + 1;
114    if bytes[idx] == b'\r' && bytes.get(next) == Some(&b'\n') {
115        next += 1;
116    }
117    Some((text[..idx].to_string(), text[next..].to_string()))
118}
119
120/// Parse possibly-truncated streaming JSON (e.g. tool-call `input_json_delta`
121/// fragments). Mirrors pi's `parseStreamingJson`: returns the best-effort
122/// parsed value, repairing truncated input so the agent always gets usable
123/// arguments to execute.
124pub fn parse_streaming_json(input: &str) -> Value {
125    let trimmed = input.trim();
126    if trimmed.is_empty() {
127        return Value::Object(Default::default());
128    }
129    if let Ok(v) = serde_json::from_str::<Value>(trimmed) {
130        return v;
131    }
132    match repair_json(trimmed) {
133        Some(v) => v,
134        None => Value::Object(Default::default()),
135    }
136}
137
138/// Close any open string and unmatched brackets/braces so truncated JSON can
139/// still be parsed.
140fn repair_json(input: &str) -> Option<Value> {
141    let bytes = input.as_bytes();
142    let mut stack: Vec<u8> = Vec::new();
143    let mut in_string = false;
144    let mut escape = false;
145    for &b in bytes {
146        if in_string {
147            if escape {
148                escape = false;
149            } else if b == b'\\' {
150                escape = true;
151            } else if b == b'"' {
152                in_string = false;
153            }
154            continue;
155        }
156        match b {
157            b'"' => in_string = true,
158            b'{' | b'[' => stack.push(b),
159            b'}' => {
160                if stack.last() == Some(&b'{') {
161                    stack.pop();
162                }
163            }
164            b']'
165                if stack.last() == Some(&b'[') => {
166                    stack.pop();
167                }
168            _ => {}
169        }
170    }
171    let mut repaired = input.to_string();
172    if in_string {
173        repaired.push('"');
174    }
175    // A truncation can land right after a structural comma — streaming
176    // `input_json_delta` chunks frequently split at exactly these token
177    // boundaries, e.g. `{"path":"foo",`. The open string is already closed
178    // above, so any comma now sitting at the tail is a *dangling structural*
179    // comma, not one inside a value. Strip it (char-wise via `pop`) before the
180    // closers below, otherwise the closed JSON keeps `,...}` and the whole
181    // value is dropped to `{}` — silently losing every key already received.
182    while repaired.ends_with(',') {
183        repaired.pop();
184    }
185    while let Some(&open) = stack.last() {
186        repaired.push(match open {
187            b'{' => '}',
188            b'[' => ']',
189            _ => break,
190        });
191        stack.pop();
192    }
193    serde_json::from_str(&repaired).ok()
194}
195
196// ---------------------------------------------------------------------------
197// Assistant message events
198// ---------------------------------------------------------------------------
199
200/// Fine-grained events emitted while streaming a model response. Mirrors
201/// pi's `AssistantMessageEvent`.
202///
203/// Unlike the TS version we deliberately do **not** clone the full partial
204/// message into every delta event (that would be O(n²) for long outputs).
205/// The loop rebuilds the partial from start/delta/end events and replaces it
206/// with the authoritative message carried by [`Self::Done`] / [`Self::Error`].
207#[derive(Debug, Clone, serde::Serialize)]
208pub enum AssistantMessageEvent {
209    Start,
210    TextStart { content_index: usize },
211    TextDelta { content_index: usize, delta: String },
212    TextEnd { content_index: usize },
213    ThinkingStart { content_index: usize },
214    ThinkingDelta { content_index: usize, delta: String },
215    ThinkingEnd { content_index: usize },
216    ToolCallStart { content_index: usize },
217    ToolCallDelta { content_index: usize, delta: String },
218    ToolCallEnd { content_index: usize },
219    Done { reason: StopReason, message: AssistantMessage },
220    Error { reason: StopReason, message: AssistantMessage },
221}
222
223/// A boxed, pinned async stream of assistant events.
224pub type AssistantStream =
225    Pin<Box<dyn Stream<Item = AssistantMessageEvent> + Send + Unpin>>;
226
227/// Build an [`AssistantStream`] from a channel pair. The provider pushes
228/// events through the sender from a spawned task.
229pub fn channel_stream(buffer: usize) -> (mpsc::Sender<AssistantMessageEvent>, AssistantStream) {
230    let (tx, rx) = mpsc::channel(buffer);
231    let stream: AssistantStream = Box::pin(ReceiverStream::new(rx));
232    (tx, stream)
233}
234
235#[cfg(test)]
236mod tests {
237    use super::*;
238
239    #[test]
240    fn sse_decodes_message_events() {
241        let raw = b"event: message_start\n\
242                    data: {\"type\":\"message_start\"}\n\
243                    \n\
244                    event: content_block_delta\n\
245                    data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Hi\"}}\n\
246                    \n\
247                    event: message_stop\n\
248                    data: {\"type\":\"message_stop\"}\n\n";
249        let mut dec = SseDecoder::new();
250        let events = dec.feed(raw);
251        let events: Vec<_> = events.into_iter().chain(dec.finish()).collect();
252        assert_eq!(events.len(), 3);
253        assert_eq!(events[0].event.as_deref(), Some("message_start"));
254        assert_eq!(events[1].event.as_deref(), Some("content_block_delta"));
255    }
256
257    #[test]
258    fn parse_streaming_json_repairs_truncated_input() {
259        let v = parse_streaming_json(r#"{"path":"foo.txt"#);
260        assert_eq!(v["path"], "foo.txt");
261
262        let v = parse_streaming_json(r#"{"edits":[{"oldText":"a","newText":"b"}"#);
263        assert_eq!(v["edits"][0]["oldText"], "a");
264
265        // Already-complete JSON passes through unchanged.
266        let v = parse_streaming_json(r#"{"command":"ls"}"#);
267        assert_eq!(v["command"], "ls");
268
269        // Empty input yields an empty object.
270        assert!(parse_streaming_json("").is_object());
271    }
272
273    #[test]
274    fn parse_streaming_json_repairs_trailing_comma() {
275        // Truncation at a comma token boundary must keep the already-received
276        // key, not drop the whole object to {}.
277        let v = parse_streaming_json(r#"{"path":"foo","#);
278        assert_eq!(v["path"], "foo");
279
280        // A comma inside an *unclosed* string value is preserved: the string is
281        // closed first, so only the dangling structural comma is stripped.
282        let v = parse_streaming_json(r#"{"a":"x,y","#);
283        assert_eq!(v["a"], "x,y");
284
285        // Nested trailing comma inside a truncated array.
286        let v = parse_streaming_json(r#"{"items":[1,2,"#);
287        assert_eq!(v["items"][0], 1);
288        assert_eq!(v["items"][1], 2);
289    }
290
291    #[test]
292    fn consume_line_handles_crlf() {
293        let (line, rest) = consume_line("abc\r\ndef").unwrap();
294        assert_eq!(line, "abc");
295        assert_eq!(rest, "def");
296    }
297}