Skip to main content

session_core/
frames.rs

1//! Bounded-inference frames in the session (inference.ts `createSessionFrameStore`, and the `frames` executor and
2//! `NativeHostApi` the TS host hands its `InferenceRuntime`): every `rlm.infer` / `rlm.map` frame is an
3//! `rlm-frame@1` task of the session's typed-agent host (journaled, admitted under its caller, cancelled with the
4//! calling cell, its requests reserved and settled in the usage ledger), its trace is a session value
5//! (`ultron.rlm.frames/<id>`, with the index at `ultron.rlm.frames/index`), and a frame with depth runs its `rlm`
6//! cell on the task's lane.
7
8use crate::compose::Stack;
9use crate::durable_store::{SharedSession, lock};
10use delegation::agents::{Agents, FrameRun, FrameRunner};
11use delegation::usage::{Measurement, Reservation, ReserveRequest, UsageLedger};
12use inference::{FrameExecution, FrameSession, FrameTasks, TraceStore};
13use kernel::Signal;
14use serde_json::{Value, json};
15use session_journal::Write;
16use session_journal::ns::RLM_FRAMES;
17use std::sync::{Arc, Weak};
18
19/// Frame traces as values of the session (`createSessionFrameStore`).
20pub struct SessionTraceStore(pub SharedSession);
21
22impl TraceStore for SessionTraceStore {
23    fn read(&self, key: &str) -> Option<Value> {
24        lock(&self.0).value(RLM_FRAMES, key).cloned()
25    }
26
27    fn write(&self, key: &str, document: &Value) -> Result<(), String> {
28        lock(&self.0)
29            .commit(&[Write::set(RLM_FRAMES, key, document.clone())])
30            .map(drop)
31    }
32}
33
34/// The typed-agent host's runner of `rlm-frame@1` tasks: the session's frames run them.
35pub fn frame_runner(frames: Arc<FrameSession>) -> FrameRunner {
36    Arc::new(move |run: FrameRun| {
37        frames.execute(FrameExecution {
38            task_id: run.task_id,
39            input: run.input,
40            lane: run.lane,
41            usage_root: run.usage_root,
42            deadline_at: run.deadline_at,
43            timeout_ms: run.timeout_ms,
44            signal: run.signal,
45        })
46    })
47}
48
49/// Frames' task host: the session's typed agents and usage ledger, and the stack's lanes for frames with depth.
50pub struct StackFrameTasks {
51    pub agents: Agents,
52    pub usage: UsageLedger,
53    pub stack: Weak<Stack>,
54}
55
56impl StackFrameTasks {
57    /// The per-root limits on the lanes of frames that run code (crate::core::budget_gate).
58    fn gate(&self) -> Option<Arc<crate::core::budget_gate::BudgetGate>> {
59        let stack = self.stack.upgrade()?;
60        Some(crate::core::budget_gate::BudgetGate::with_finals(
61            self.usage.clone(),
62            stack.stats.clone(),
63            Arc::new(|_| None),
64            crate::core::budget_gate::frame_finals(),
65        ))
66    }
67}
68
69/// A code frame's lane run: one per frame (a spent tree admits no further attempt).
70fn frame_run(lane: &str) -> crate::core::budget_gate::LaneRun {
71    crate::core::budget_gate::LaneRun {
72        lane: format!("frame:{lane}"),
73        run: String::new(),
74    }
75}
76
77impl FrameTasks for StackFrameTasks {
78    fn caller_task(&self, lane: &str) -> Option<String> {
79        self.agents.caller_task(lane)
80    }
81
82    fn spawn(&self, lane: &str, input: Value, model: Option<&str>, timeout_ms: u64) -> Result<String, String> {
83        let mut payload = json!({"definition": "rlm-frame@1", "input": input, "timeout_ms": timeout_ms});
84        if let Some(model) = model {
85            payload["model"] = json!(model);
86        }
87        self.agents.spawn_frame(lane, payload)
88    }
89
90    fn result(&self, lane: &str, task_id: &str, signal: &Signal) -> Value {
91        let ask = |cell: Option<&Signal>| self.agents.handle("agents.result", json!({"id": task_id}), lane, cell);
92        match ask(Some(signal)) {
93            Ok(result) => result,
94            Err(_) if signal.is_aborted() => {
95                let _ = self
96                    .agents
97                    .cancel_task(task_id, "Inference cancelled: the calling cell was aborted");
98                ask(None).unwrap_or_else(|error| json!({"status": "cancelled", "error": error}))
99            }
100            Err(error) => json!({"status": "failed", "error": error}),
101        }
102    }
103
104    fn reserve(&self, request: &Value) -> Result<Option<Value>, String> {
105        let text = |key: &str| request[key].as_str().map(str::to_string);
106        let reservation = self.usage.reserve(&ReserveRequest {
107            kind: "model".into(),
108            root_id: text("rootId"),
109            task_id: text("taskId"),
110            parent_task_id: text("parentTaskId"),
111            request_key: text("requestKey"),
112            budget_id: text("budgetId"),
113            timeout_ms: request["timeoutMs"].as_f64(),
114            deadline_at: request["deadlineAt"].as_f64(),
115            ..ReserveRequest::default()
116        })?;
117        Ok(Some(reservation.0))
118    }
119
120    fn settle(&self, reservation: &Value, status: &str, usage: Option<&Value>) {
121        let measured = usage.map(|usage| Measurement {
122            input_tokens: usage["inputTokens"].as_f64(),
123            output_tokens: usage["outputTokens"].as_f64(),
124            total_tokens: usage["totalTokens"].as_f64(),
125            cost: usage["cost"].as_f64(),
126            ..Measurement::default()
127        });
128        let _ = self
129            .usage
130            .settle(&Reservation(reservation.clone()), Some(status), measured.as_ref());
131    }
132
133    fn code_tool(&self, lane: &str) -> Result<Arc<dyn agent::AgentTool>, String> {
134        let stack = self.stack.upgrade().ok_or("The session is closed")?;
135        Ok(Arc::new(stack.rlm(lane)?))
136    }
137
138    fn close_lane(&self, lane: &str) {
139        if let Some(stack) = self.stack.upgrade() {
140            stack.context_reminders.set_frame_lane(lane, None);
141            let _ = stack.lanes.close_lane(lane);
142        }
143    }
144
145    /// Every frame response counts one turn of its root's tree, with the tokens and cost the provider reported.
146    fn charge_turn(&self, root: Option<&str>, reply: &ai::AssistantMessage) {
147        let usage = serde_json::to_value(&reply.usage).unwrap_or(Value::Null);
148        let _ = self
149            .usage
150            .record_turn(root, usage["totalTokens"].as_f64(), usage["cost"]["total"].as_f64());
151    }
152
153    fn gate_request(&self, lane: &str, root: Option<&str>) -> inference::FrameGate {
154        use crate::core::budget_gate::RequestDecision;
155        let Some(gate) = self.gate() else {
156            return inference::FrameGate::Allow;
157        };
158        match gate.request(&frame_run(lane), root) {
159            RequestDecision::Allow => inference::FrameGate::Allow,
160            RequestDecision::Final(note) => inference::FrameGate::Final(note),
161            RequestDecision::Block(reason) => inference::FrameGate::Block(reason),
162        }
163    }
164
165    fn gate_tool(&self, lane: &str, root: Option<&str>) -> Option<(String, bool)> {
166        self.gate()?
167            .tool(&frame_run(lane), root)
168            .map(|block| (block.reason, block.terminate))
169    }
170
171    /// A frame's cells are reminded as its conversation nears the frame model's window (it never compacts).
172    fn frame_context(&self, lane: &str, model: &ai::Model, meter: inference::FrameMeter) {
173        if let Some(stack) = self.stack.upgrade() {
174            let frame = crate::context_reminder::lane_limit(model, false, 0).map(|limit| (limit, meter));
175            stack.context_reminders.set_frame_lane(lane, frame);
176        }
177    }
178}