Skip to main content

graphrt_core/
response.rs

1//! Ordered response streaming.
2//!
3//! The engine emits raw events as soon as they happen: tokens from parallel
4//! LLM nodes interleave, and nodes finish in any order. A chat-style consumer
5//! wants something different: the text of each response node (`answer`, and
6//! optionally `end`) rendered in template order, with model tokens streamed
7//! through as early as it is safe to do so.
8//!
9//! [`ResponseAssembler`] is a consumer-side transducer that does exactly that:
10//!
11//! ```ignore
12//! let mut assembler = ResponseAssembler::new(engine.graph());
13//! while let Some(event) = run.next().await {
14//!     for chunk in assembler.push(&event) {
15//!         print!("{}", chunk.text);
16//!     }
17//! }
18//! ```
19//!
20//! ## Rules
21//!
22//! - Only response nodes of the **root scope** are assembled. Events from child
23//!   frames (iteration / loop bodies) are ignored, unless
24//!   [`ResponseAssembler::pass_through_unreferenced`] is enabled, in which case
25//!   their chunks are forwarded verbatim.
26//! - At most one response is *active* at a time. Responses are activated in the
27//!   order they become **certain** to execute (ties broken by topological
28//!   order). Certainty is a linear-time fixpoint over the graph — never a path
29//!   enumeration:
30//!   - a node that started or finished is certain, and so is the root entry;
31//!   - a node is certain when one incoming edge comes from a certain source and
32//!     that edge will be taken if the source succeeds: every edge of a
33//!     non-branching node (except `fail-branch` edges), or the edge matching the
34//!     handle a finished branch node selected. Node failures are not anticipated,
35//!     except that an unfinished node with the `fail-branch` strategy makes none
36//!     of its edges certain (either side may be taken).
37//! - While a response is active, its template is drained left to right:
38//!   literal text is emitted immediately; a variable produced by a graph node
39//!   emits that node's buffered stream chunks for the variable's field as they
40//!   arrive; once the node finishes, a variable that never streamed is emitted
41//!   whole (`Value::to_text`). Variables of skipped or failed nodes render as
42//!   nothing. Variables outside graph nodes (`sys.*`, `conversation.*`, ...)
43//!   are resolved from values given via [`ResponseAssembler::with_value`] /
44//!   [`ResponseAssembler::with_pool`], or render as nothing.
45//! - `end` nodes do not stream by default (their outputs are structured data,
46//!   delivered in `RunSucceeded`). Enable [`ResponseAssembler::include_end`] to
47//!   render them as their output values joined by newlines.
48//! - **Retries and handled failures never mix attempts.** A source node whose
49//!   policy allows retries (`retry.max_retries > 0`) or handles errors
50//!   (`on_error` other than `fail`) is *not* streamed live: its chunks are
51//!   buffered and emitted only once the node finishes. A `node_retry` event
52//!   discards the buffered chunks of the failed attempt. On success the final
53//!   attempt's text is emitted; after a handled `default-value` failure the
54//!   default output is emitted instead of any partial text; after a
55//!   `fail-branch` failure (or an unhandled one) nothing is emitted for the
56//!   variable. The trade-off: such nodes lose token-by-token streaming in
57//!   exchange for an answer that always matches the node's final output.
58//! - Ordering after handled failures follows the engine: a non-branch node with
59//!   `default-value` continues along its regular edges, a `fail-branch` node
60//!   along its `fail-branch` edges, and a branch node with `default-value`
61//!   along the handle named by its `branch` default value (no edge if absent).
62//! - A terminal run event (`RunSucceeded`, `RunFailed`, `RunAborted`) flushes
63//!   everything that can still be rendered, as does [`ResponseAssembler::finish`].
64
65use std::collections::{HashMap, HashSet, VecDeque};
66use std::sync::Arc;
67
68use serde::Deserialize;
69
70use crate::dsl::ErrorStrategy;
71use crate::event::Event;
72use crate::graph::{FAIL_BRANCH, Graph, NodeIx};
73use crate::node::NodeRole;
74use crate::pool::{Selector, VariablePool};
75use crate::snapshot::{EdgeStatus, FrameSnapshot, NodeStatus};
76use crate::template::{Part, Template};
77use crate::value::Value;
78
79/// A piece of ordered response text.
80#[derive(Clone, Debug, PartialEq, Eq)]
81pub struct ResponseChunk {
82    /// Response node the text belongs to (or, for passed-through chunks, the
83    /// node that produced them). Shared with the graph, so a chunk does not
84    /// copy it.
85    pub node_id: Arc<str>,
86    pub text: String,
87    /// `true` exactly once per response node, on an empty chunk marking that
88    /// its template is fully rendered.
89    pub is_final: bool,
90}
91
92impl ResponseChunk {
93    fn text(node_id: &Arc<str>, text: String) -> Self {
94        Self { node_id: Arc::clone(node_id), text, is_final: false }
95    }
96
97    fn done(node_id: &Arc<str>) -> Self {
98        Self { node_id: Arc::clone(node_id), text: String::new(), is_final: true }
99    }
100}
101
102#[derive(Clone, Copy, Debug, PartialEq, Eq)]
103enum Status {
104    Unknown,
105    Started,
106    Succeeded,
107    /// Failed but kept going through its error strategy.
108    Handled,
109    /// Failed without an error strategy: outputs never appear.
110    Failed,
111    Skipped,
112}
113
114impl Status {
115    fn finished(self) -> bool {
116        matches!(self, Status::Succeeded | Status::Handled | Status::Failed | Status::Skipped)
117    }
118}
119
120#[derive(Debug)]
121struct Response {
122    node: NodeIx,
123    id: Arc<str>,
124    parts: Vec<Part>,
125    queued: bool,
126    done: bool,
127}
128
129#[derive(Debug, Default)]
130struct StreamBuf {
131    text: String,
132}
133
134/// Stream buffers by node id, then field (a node has few referenced fields).
135type Streams = HashMap<Arc<str>, Vec<(Arc<str>, StreamBuf)>>;
136
137fn stream_buf<'a>(streams: &'a Streams, node: &str, field: &str) -> Option<&'a StreamBuf> {
138    streams.get(node)?.iter().find(|(f, _)| f.as_ref() == field).map(|(_, buf)| buf)
139}
140
141#[derive(Debug)]
142struct Active {
143    response: usize,
144    part: usize,
145    /// Byte offset already emitted from the current variable's stream buffer.
146    offset: usize,
147}
148
149#[derive(Deserialize)]
150struct EndOutput {
151    value_selector: Selector,
152}
153
154/// Turns raw run events into ordered response text. See the module docs.
155#[derive(Debug)]
156pub struct ResponseAssembler {
157    graph: Arc<Graph>,
158    responses: Vec<Response>,
159    status: Vec<Status>,
160    branch: Vec<Option<String>>,
161    /// Nodes whose streams are buffered until they finish (retry / handled-error policy).
162    deferred: Vec<bool>,
163    /// Edge states restored from a snapshot (indexed like `Graph::edges`).
164    edge_state: Vec<Option<EdgeStatus>>,
165    /// Response nodes fully rendered before a pause (restored via `resume_from`).
166    rendered: Vec<bool>,
167    /// Stream buffers of the `(node id, field)` pairs templates reference, by
168    /// node id. Looked up by `&str`, so a chunk costs no allocation.
169    streams: Streams,
170    /// Namespaces templates reference: only their outputs are kept in `pool`.
171    referenced: HashSet<Arc<str>>,
172    pool: VariablePool,
173    queue: VecDeque<usize>,
174    active: Option<Active>,
175    emitted: String,
176    pass_through: bool,
177    include_end: bool,
178    finished: bool,
179    /// Certainty of each node, maintained incrementally between events.
180    certain: Vec<bool>,
181    /// Whether `certain` reflects the current state (false after construction / resume).
182    certain_valid: bool,
183    /// Root nodes whose status changed since the last certainty refresh.
184    changed: Vec<NodeIx>,
185}
186
187impl ResponseAssembler {
188    /// Build an assembler for runs of `graph`.
189    pub fn new(graph: &Arc<Graph>) -> Self {
190        let mut this = Self {
191            graph: Arc::clone(graph),
192            responses: Vec::new(),
193            status: vec![Status::Unknown; graph.nodes().len()],
194            branch: vec![None; graph.nodes().len()],
195            deferred: graph
196                .nodes()
197                .iter()
198                .map(|n| n.policy.retry.max_retries > 0 || !matches!(n.policy.on_error, ErrorStrategy::Fail))
199                .collect(),
200            edge_state: vec![None; graph.edges().len()],
201            rendered: vec![false; graph.nodes().len()],
202            streams: Streams::new(),
203            referenced: HashSet::new(),
204            pool: VariablePool::new(),
205            queue: VecDeque::new(),
206            active: None,
207            emitted: String::new(),
208            pass_through: false,
209            include_end: false,
210            finished: false,
211            certain: vec![false; graph.nodes().len()],
212            certain_valid: false,
213            changed: Vec::new(),
214        };
215        this.rebuild_responses();
216        this
217    }
218
219    /// Forward chunks that no template references (and child-frame chunks) verbatim.
220    pub fn pass_through_unreferenced(mut self, enabled: bool) -> Self {
221        self.pass_through = enabled;
222        self
223    }
224
225    /// Also render `end` nodes (their outputs joined by newlines).
226    pub fn include_end(mut self, enabled: bool) -> Self {
227        self.include_end = enabled;
228        self.rebuild_responses();
229        self
230    }
231
232    /// Provide a value for a non-node variable such as `sys.query`.
233    pub fn with_value(mut self, selector: &Selector, value: Value) -> Self {
234        self.pool.set(selector, value);
235        self
236    }
237
238    /// Provide non-node variables in bulk (e.g. the run's `sys` / `conversation` values).
239    pub fn with_pool(mut self, pool: VariablePool) -> Self {
240        for (ns, name, value) in pool.iter() {
241            self.pool.insert(ns, name, value.clone());
242        }
243        self
244    }
245
246    /// Continue assembling a resumed run from the root frame snapshot carried by
247    /// `RunPaused` (`snapshot.root`).
248    ///
249    /// Restores every variable value of the snapshot (node outputs included, so
250    /// templates can reference nodes that will not run again), node and edge
251    /// states (for correct ordering), and marks response nodes that already
252    /// succeeded before the pause as rendered, so they are not emitted twice.
253    /// A response that was only partially rendered when the run paused is
254    /// rendered again from the start.
255    pub fn resume_from(mut self, snapshot: &FrameSnapshot) -> Self {
256        let restored = VariablePool::from_snapshot(snapshot.pool.clone());
257        for (ns, name, value) in restored.iter() {
258            self.pool.insert(ns, name, value.clone());
259        }
260        for (ix, edge) in self.graph.edges().iter().enumerate() {
261            if let (Some(state), Some(slot)) = (snapshot.edges.get(edge.id.as_ref()), self.edge_state.get_mut(ix)) {
262                *slot = Some(*state);
263            }
264        }
265        for (node_id, node) in &snapshot.nodes {
266            let Some(ix) = self.root_node(node_id) else { continue };
267            let status = match node.status {
268                NodeStatus::Succeeded => Status::Succeeded,
269                NodeStatus::Skipped => Status::Skipped,
270                NodeStatus::Failed if self.has_taken_outgoing(ix) => Status::Handled,
271                NodeStatus::Failed => Status::Failed,
272                NodeStatus::Paused => Status::Started,
273                NodeStatus::Pending => Status::Unknown,
274            };
275            if let Some(slot) = self.status.get_mut(ix) {
276                *slot = status;
277            }
278            if let Some(slot) = self.rendered.get_mut(ix) {
279                *slot = status == Status::Succeeded;
280            }
281        }
282        self.certain_valid = false;
283        self.rebuild_responses();
284        self
285    }
286
287    fn has_taken_outgoing(&self, ix: NodeIx) -> bool {
288        self.graph.outgoing(ix).iter().any(|&ex| self.edge_state.get(ex).copied().flatten() == Some(EdgeStatus::Taken))
289    }
290
291    /// All response text emitted so far, concatenated.
292    pub fn text_so_far(&self) -> &str {
293        &self.emitted
294    }
295
296    /// Feed one event; returns the response chunks it unlocks.
297    pub fn push(&mut self, event: &Event) -> Vec<ResponseChunk> {
298        let mut out = Vec::new();
299        self.push_into(event, &mut out);
300        out
301    }
302
303    /// [`ResponseAssembler::push`] appending to `out` instead of returning a
304    /// new list, so a consumer can reuse one buffer for a whole run.
305    ///
306    /// ```
307    /// # use std::sync::Arc;
308    /// # use graphrt_core::{Graph, Registry, response::ResponseAssembler};
309    /// # let graph = Arc::new(Graph::from_text(r#"{"graph": {"nodes": [{"id": "start", "type": "start"}], "edges": []}}"#, &Registry::with_builtins()).unwrap());
310    /// # let events: Vec<graphrt_core::Event> = Vec::new();
311    /// let mut assembler = ResponseAssembler::new(&graph);
312    /// let mut chunks = Vec::new();
313    /// for event in &events {
314    ///     assembler.push_into(event, &mut chunks);
315    ///     for chunk in chunks.drain(..) {
316    ///         print!("{}", chunk.text);
317    ///     }
318    /// }
319    /// ```
320    pub fn push_into(&mut self, event: &Event, out: &mut Vec<ResponseChunk>) {
321        if self.finished {
322            return;
323        }
324        match event {
325            Event::NodeStarted { frame, node_id, .. } if frame.is_empty() => {
326                self.set_status(node_id, Status::Started);
327            }
328            Event::NodeChunk { frame, node_id, field, chunk, .. } => {
329                let buf = match self.streams.get_mut(node_id.as_ref()) {
330                    Some(fields) if frame.is_empty() => fields.iter_mut().find(|(f, _)| f == field),
331                    _ => None,
332                };
333                let buffered = match buf {
334                    Some((_, buf)) => {
335                        buf.text.push_str(chunk);
336                        true
337                    }
338                    None => {
339                        if self.pass_through && !chunk.is_empty() {
340                            out.push(ResponseChunk::text(node_id, chunk.clone()));
341                        }
342                        false
343                    }
344                };
345                if self.certain_valid {
346                    // A chunk changes no node status: at most the active response advances.
347                    if buffered {
348                        self.drain(false, out);
349                    }
350                    return;
351                }
352            }
353            Event::NodeSucceeded { frame, node_id, outputs, branch, .. } if frame.is_empty() => {
354                if self.referenced.contains(node_id.as_ref()) {
355                    self.pool.set_outputs(node_id, outputs);
356                }
357                if let Some(ix) = self.root_node(node_id) {
358                    if let Some(b) = self.branch.get_mut(ix) {
359                        b.clone_from(branch);
360                    }
361                }
362                self.set_status(node_id, Status::Succeeded);
363            }
364            Event::NodeFailed { frame, node_id, handled, outputs, .. } if frame.is_empty() => {
365                if *handled && self.referenced.contains(node_id.as_ref()) {
366                    self.pool.set_outputs(node_id, outputs);
367                }
368                self.set_status(node_id, if *handled { Status::Handled } else { Status::Failed });
369            }
370            Event::NodeSkipped { frame, node_id } if frame.is_empty() => {
371                self.set_status(node_id, Status::Skipped);
372            }
373            Event::NodeRetry { frame, node_id, .. } if frame.is_empty() => {
374                // The failed attempt's partial output must never reach the answer.
375                if let Some(fields) = self.streams.get_mut(node_id.as_ref()) {
376                    fields.iter_mut().for_each(|(_, buf)| buf.text.clear());
377                }
378                return;
379            }
380            Event::RunSucceeded { .. } | Event::RunFailed { .. } | Event::RunAborted { .. } => {
381                self.finish_into(out);
382                return;
383            }
384            _ => return,
385        }
386        self.refresh_certainty();
387        self.drain(false, out);
388    }
389
390    /// Flush: treat every pending variable as resolved and render what is
391    /// available. Idempotent.
392    pub fn finish(&mut self) -> Vec<ResponseChunk> {
393        let mut out = Vec::new();
394        self.finish_into(&mut out);
395        out
396    }
397
398    fn finish_into(&mut self, out: &mut Vec<ResponseChunk>) {
399        if self.finished {
400            return;
401        }
402        self.refresh_certainty();
403        self.drain(true, out);
404        self.finished = true;
405    }
406
407    fn rebuild_responses(&mut self) {
408        let Some(scope) = self.graph.root_scope() else {
409            return;
410        };
411        let mut responses = Vec::new();
412        for &ix in &scope.nodes {
413            let Some(node) = self.graph.node(ix) else { continue };
414            if node.role != NodeRole::Response {
415                continue;
416            }
417            let parts = match &*node.kind {
418                "answer" => node
419                    .doc
420                    .config
421                    .get("answer")
422                    .and_then(serde_json::Value::as_str)
423                    .map(|s| Template::parse(s).parts().to_vec())
424                    .unwrap_or_default(),
425                "end" if self.include_end => end_parts(&node.doc.config),
426                _ => continue,
427            };
428            let rendered = self.rendered.get(ix).copied().unwrap_or(false);
429            responses.push(Response { node: ix, id: node.id.clone(), parts, queued: rendered, done: rendered });
430        }
431        let mut old = std::mem::take(&mut self.streams);
432        self.referenced.clear();
433        for sel in responses.iter().flat_map(|r| r.parts.iter()).filter_map(|p| match p {
434            Part::Var(sel) => Some(sel),
435            Part::Text(_) => None,
436        }) {
437            let node: Arc<str> = Arc::from(sel.namespace());
438            self.referenced.insert(Arc::clone(&node));
439            if !sel.path().is_empty() {
440                continue;
441            }
442            let fields = self.streams.entry(node).or_default();
443            if fields.iter().any(|(f, _)| f.as_ref() == sel.name()) {
444                continue;
445            }
446            // Keep text already buffered for the pair, if any.
447            let buf = old
448                .get_mut(sel.namespace())
449                .and_then(|v| v.iter_mut().find(|(f, _)| f.as_ref() == sel.name()))
450                .map(|(_, buf)| std::mem::take(buf))
451                .unwrap_or_default();
452            fields.push((Arc::from(sel.name()), buf));
453        }
454        self.responses = responses;
455    }
456
457    fn root_node(&self, id: &str) -> Option<NodeIx> {
458        self.graph.index_of(id).filter(|&ix| self.graph.node(ix).is_some_and(|n| n.parent.is_none()))
459    }
460
461    fn set_status(&mut self, node_id: &str, status: Status) {
462        if let Some(ix) = self.root_node(node_id) {
463            if let Some(s) = self.status.get_mut(ix) {
464                // Never downgrade a finished node back to "started" (retries reuse the id).
465                if !(s.finished() && status == Status::Started) {
466                    if *s != status {
467                        self.changed.push(ix);
468                    }
469                    *s = status;
470                }
471            }
472        }
473    }
474
475    fn status_of(&self, ix: NodeIx) -> Status {
476        self.status.get(ix).copied().unwrap_or(Status::Unknown)
477    }
478
479    /// Whether `ix` is certain to run, given the certainty of its predecessors.
480    fn compute_certain(&self, ix: NodeIx, entry: NodeIx, certain: &[bool]) -> bool {
481        match self.status_of(ix) {
482            Status::Skipped => false,
483            Status::Unknown => ix == entry || self.has_certain_edge(ix, certain),
484            _ => true,
485        }
486    }
487
488    /// Bring the certain set up to date and enqueue newly certain responses.
489    ///
490    /// Certainty only grows as a run progresses, so after one full pass each
491    /// status change is propagated forward from the changed node: O(affected
492    /// nodes) per event instead of O(graph). A node losing certainty (not
493    /// expected in practice) falls back to a full recomputation.
494    fn refresh_certainty(&mut self) {
495        let Some(scope) = self.graph.root_scope() else {
496            return;
497        };
498        let entry = scope.entry;
499        let mut certain = std::mem::take(&mut self.certain);
500        certain.resize(self.graph.nodes().len(), false);
501        // The change list doubles as the work list; its buffer is handed back below.
502        let mut work = std::mem::take(&mut self.changed);
503        let mut full = !self.certain_valid;
504        if !full {
505            while let Some(ix) = work.pop() {
506                let now = self.compute_certain(ix, entry, &certain);
507                let before = certain.get(ix).copied().unwrap_or(false);
508                if before && !now {
509                    full = true;
510                    break;
511                }
512                if now != before {
513                    if let Some(c) = certain.get_mut(ix) {
514                        *c = now;
515                    }
516                }
517                // Even when `ix` itself was already certain, its outgoing edges may
518                // have become certain (e.g. a branch picked its handle).
519                if now {
520                    for &ex in self.graph.outgoing(ix) {
521                        if let Some(edge) = self.graph.edge(ex) {
522                            if !certain.get(edge.target).copied().unwrap_or(false)
523                                && self.compute_certain(edge.target, entry, &certain)
524                            {
525                                if let Some(c) = certain.get_mut(edge.target) {
526                                    *c = true;
527                                }
528                                work.push(edge.target);
529                            }
530                        }
531                    }
532                }
533            }
534        }
535        work.clear();
536        self.changed = work;
537        if full {
538            certain.iter_mut().for_each(|c| *c = false);
539            for &ix in &scope.nodes {
540                let is_certain = self.compute_certain(ix, entry, &certain);
541                if let Some(c) = certain.get_mut(ix) {
542                    *c = is_certain;
543                }
544            }
545        }
546        for (i, r) in self.responses.iter_mut().enumerate() {
547            if !r.queued && certain.get(r.node).copied().unwrap_or(false) {
548                r.queued = true;
549                self.queue.push_back(i);
550            }
551        }
552        self.certain = certain;
553        self.certain_valid = true;
554    }
555
556    /// Whether an incoming edge of `ix` will be taken given its (certain) source.
557    fn has_certain_edge(&self, ix: NodeIx, certain: &[bool]) -> bool {
558        self.graph.incoming(ix).iter().filter_map(|&ex| self.graph.edge(ex).map(|e| (ex, e))).any(|(ex, edge)| {
559            if !certain.get(edge.source).copied().unwrap_or(false) {
560                return false;
561            }
562            // States restored from a snapshot are authoritative.
563            match self.edge_state.get(ex).copied().flatten() {
564                Some(EdgeStatus::Taken) => return true,
565                Some(EdgeStatus::Skipped) => return false,
566                Some(EdgeStatus::Unknown) | None => {}
567            }
568            let Some(src) = self.graph.node(edge.source) else { return false };
569            let status = self.status_of(edge.source);
570            let fail_branch = matches!(src.policy.on_error, ErrorStrategy::FailBranch);
571            match status {
572                Status::Failed | Status::Skipped => false,
573                Status::Handled if fail_branch => edge.handle.as_ref() == FAIL_BRANCH,
574                Status::Handled if src.role == NodeRole::Branch => {
575                    default_branch(&src.policy.on_error).as_deref() == Some(edge.handle.as_ref())
576                }
577                Status::Handled => edge.handle.as_ref() != FAIL_BRANCH,
578                Status::Succeeded if src.role == NodeRole::Branch => {
579                    self.branch.get(edge.source).and_then(Option::as_deref) == Some(edge.handle.as_ref())
580                }
581                _ if src.role == NodeRole::Branch => false,
582                // Unfinished fail-branch node: which side it takes is not known yet.
583                _ if fail_branch => false,
584                _ => edge.handle.as_ref() != FAIL_BRANCH,
585            }
586        })
587    }
588
589    /// Render as much as possible. With `flush`, pending variables are treated as resolved.
590    fn drain(&mut self, flush: bool, out: &mut Vec<ResponseChunk>) {
591        loop {
592            if self.active.is_none() {
593                match self.queue.pop_front() {
594                    Some(response) => self.active = Some(Active { response, part: 0, offset: 0 }),
595                    None => return,
596                }
597            }
598            let Some(active) = self.active.as_mut() else { return };
599            let Some(response) = self.responses.get(active.response) else {
600                self.active = None;
601                continue;
602            };
603            // A response node that ended up skipped renders nothing.
604            if self.status.get(response.node).copied() == Some(Status::Skipped) {
605                self.finish_active(None, out);
606                continue;
607            }
608            // Parts are borrowed, not cloned: this runs for every streamed chunk.
609            match response.parts.get(active.part) {
610                None => {
611                    let id = Arc::clone(&response.id);
612                    self.finish_active(Some(&id), out);
613                }
614                Some(Part::Text(text)) => {
615                    emit(&mut self.emitted, out, &response.id, text.clone());
616                    active.part += 1;
617                    active.offset = 0;
618                }
619                Some(Part::Var(sel)) => {
620                    let sources = Sources {
621                        graph: &self.graph,
622                        status: &self.status,
623                        deferred: &self.deferred,
624                        streams: &self.streams,
625                        pool: &self.pool,
626                    };
627                    let step = resolve_var(&sources, sel, active.offset, flush);
628                    if !step.text.is_empty() {
629                        emit(&mut self.emitted, out, &response.id, step.text);
630                    }
631                    active.offset = step.offset;
632                    if step.complete {
633                        active.part += 1;
634                        active.offset = 0;
635                    } else {
636                        return;
637                    }
638                }
639            }
640        }
641    }
642
643    fn finish_active(&mut self, id: Option<&Arc<str>>, out: &mut Vec<ResponseChunk>) {
644        if let Some(active) = self.active.take() {
645            if let Some(r) = self.responses.get_mut(active.response) {
646                r.done = true;
647            }
648            if let Some(id) = id {
649                out.push(ResponseChunk::done(id));
650            }
651        }
652    }
653}
654
655struct Step {
656    text: String,
657    offset: usize,
658    complete: bool,
659}
660
661/// Read-only view of the state a template variable is resolved from.
662struct Sources<'a> {
663    graph: &'a Graph,
664    status: &'a [Status],
665    deferred: &'a [bool],
666    streams: &'a Streams,
667    pool: &'a VariablePool,
668}
669
670fn resolve_var(sources: &Sources<'_>, sel: &Selector, offset: usize, flush: bool) -> Step {
671    let Sources { graph, status, deferred, streams, pool } = *sources;
672    let node_ix = graph.index_of(sel.namespace()).filter(|&ix| graph.node(ix).is_some_and(|n| n.parent.is_none()));
673    let Some(ix) = node_ix else {
674        // Not produced by a root graph node: host-provided value (or nothing).
675        return Step { text: pool.get(sel).map(|v| v.to_text()).unwrap_or_default(), offset: 0, complete: true };
676    };
677    let node_status = status.get(ix).copied().unwrap_or(Status::Unknown);
678
679    let is_deferred = deferred.get(ix).copied().unwrap_or(false);
680    let buffered = if sel.path().is_empty() {
681        stream_buf(streams, sel.namespace(), sel.name()).filter(|b| !b.text.is_empty())
682    } else {
683        None
684    };
685
686    if is_deferred {
687        // Emitted only once the node has finished, from its final attempt.
688        let text = match node_status {
689            Status::Succeeded => match buffered {
690                Some(buf) => buf.text.clone(),
691                None => pool.get(sel).map(|v| v.to_text()).unwrap_or_default(),
692            },
693            // Default-value outputs (or nothing on fail-branch, whose outputs are only error fields).
694            Status::Handled => pool.get(sel).map(|v| v.to_text()).unwrap_or_default(),
695            _ => String::new(),
696        };
697        return Step { text, offset: 0, complete: node_status.finished() || flush };
698    }
699
700    // Live streaming: emit whatever was buffered beyond `offset`.
701    let mut text = String::new();
702    let mut new_offset = offset;
703    let streamed = buffered.is_some();
704    if let Some(buf) = buffered {
705        if let Some(rest) = buf.text.get(offset..) {
706            text.push_str(rest);
707            new_offset = buf.text.len();
708        }
709    }
710
711    let complete = match node_status {
712        Status::Skipped | Status::Failed => true,
713        Status::Succeeded | Status::Handled => {
714            if !streamed {
715                if let Some(v) = pool.get(sel) {
716                    text.push_str(&v.to_text());
717                }
718            }
719            true
720        }
721        Status::Unknown | Status::Started => {
722            if flush && !streamed {
723                if let Some(v) = pool.get(sel) {
724                    text.push_str(&v.to_text());
725                }
726            }
727            flush
728        }
729    };
730    Step { text, offset: new_offset, complete }
731}
732
733/// Handle named by a `branch` entry of a `default-value` strategy.
734fn default_branch(strategy: &ErrorStrategy) -> Option<String> {
735    match strategy {
736        ErrorStrategy::DefaultValue { values } => values.get("branch").and_then(Value::as_str).map(str::to_owned),
737        _ => None,
738    }
739}
740
741fn emit(emitted: &mut String, out: &mut Vec<ResponseChunk>, id: &Arc<str>, text: String) {
742    if text.is_empty() {
743        return;
744    }
745    emitted.push_str(&text);
746    out.push(ResponseChunk::text(id, text));
747}
748
749fn end_parts(config: &serde_json::Map<String, serde_json::Value>) -> Vec<Part> {
750    let outputs: Vec<EndOutput> = config
751        .get("outputs")
752        .cloned()
753        .and_then(|v| serde_json::from_value::<Vec<serde_json::Value>>(v).ok())
754        .unwrap_or_default()
755        .into_iter()
756        .filter_map(|v| serde_json::from_value(v).ok())
757        .collect();
758    let mut parts = Vec::with_capacity(outputs.len() * 2);
759    for (i, o) in outputs.into_iter().enumerate() {
760        if i > 0 {
761            parts.push(Part::Text("\n".to_owned()));
762        }
763        parts.push(Part::Var(o.value_selector));
764    }
765    parts
766}