Skip to main content

host/
cell.rs

1//! One cell's tool result text: `UltronRlmKernel.executeCell` (experimental/session-worker.ts) over
2//! `truncateToolOutput` (ultron/rlm/output-truncation.ts) and `maskCellOutputCounted` (ultron/rlm/output-secrets.ts).
3//!
4//! A cell's stdout, stderr and value are joined by newlines, secrets are masked, and an oversized text keeps its head
5//! and tail (the whole text spilled to a private file when a spill directory is given). A failed cell becomes
6//! [`CellFailure`]: what it printed, then the traceback.
7
8use crate::secrets::OutputMasker;
9use kernel::{ExecutionResult, Status};
10use std::fs::{DirBuilder, OpenOptions};
11use std::io::Write;
12use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt, PermissionsExt};
13use std::path::Path;
14use std::time::{SystemTime, UNIX_EPOCH};
15
16pub const SPILL_KEEP: usize = 20;
17
18/// A cell's tool result: its text and how many secrets were masked in it.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub struct CellOutput {
21    pub text: String,
22    pub masked: usize,
23}
24
25/// A cell that raised (`RlmCellError`): the message is the output and traceback; `ename` the exception type.
26#[derive(Debug, Clone, PartialEq, Eq)]
27pub struct CellFailure {
28    pub message: String,
29    pub ename: String,
30    pub masked: usize,
31}
32
33/// How a cell's text is finished: the masker, `ULTRON_MASK_SECRETS`, the byte budget and the spill directory.
34pub struct CellFormat<'a> {
35    pub masker: &'a OutputMasker,
36    pub mask_secrets: Option<&'a str>,
37    pub max_bytes: usize,
38    pub spill_dir: Option<&'a Path>,
39}
40
41fn drop_final_newline(text: &str) -> &str {
42    text.strip_suffix('\n').unwrap_or(text)
43}
44
45fn join_present(parts: &[&str]) -> String {
46    parts
47        .iter()
48        .filter(|part| !part.is_empty())
49        .copied()
50        .collect::<Vec<_>>()
51        .join("\n")
52}
53
54/// `executeCell`'s text for a kernel result.
55pub fn cell_output(result: &ExecutionResult, format: &CellFormat<'_>) -> Result<CellOutput, CellFailure> {
56    let stdout = drop_final_newline(&result.stdout);
57    let stderr = drop_final_newline(&result.stderr);
58    if result.status == Status::Error {
59        let ename = result
60            .error
61            .as_ref()
62            .map_or("PythonError", |error| error.ename.as_str());
63        let evalue = result
64            .error
65            .as_ref()
66            .map_or("Execution failed", |error| error.evalue.as_str());
67        let summary = format!("{ename}: {evalue}");
68        let traceback = result
69            .error
70            .as_ref()
71            .map(|error| error.traceback.join("\n"))
72            .unwrap_or_default();
73        let failure = if traceback.is_empty() {
74            summary
75        } else if traceback.ends_with(&summary) {
76            traceback
77        } else {
78            format!("{traceback}\n{summary}")
79        };
80        let (text, masked) = format
81            .masker
82            .mask_counted(&join_present(&[stdout, stderr, &failure]), format.mask_secrets);
83        return Err(CellFailure {
84            message: truncate_tool_output(&text, format.max_bytes, format.spill_dir),
85            ename: ename.to_string(),
86            masked,
87        });
88    }
89    let value = result.result.as_deref().unwrap_or("");
90    let (text, masked) = format
91        .masker
92        .mask_counted(&join_present(&[stdout, stderr, value]), format.mask_secrets);
93    Ok(CellOutput {
94        text: truncate_tool_output(&text, format.max_bytes, format.spill_dir),
95        masked,
96    })
97}
98
99/// `spillOutput`: `text` in a new 0600 file in the 0700 `dir`, dropping the oldest `.txt` files beyond
100/// [`SPILL_KEEP`]; the path, or `None` when it cannot be written.
101pub fn spill_output(text: &str, dir: &Path, name: &str) -> Option<String> {
102    DirBuilder::new().recursive(true).mode(0o700).create(dir).ok()?;
103    std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700)).ok()?;
104    let mut files: Vec<(SystemTime, std::path::PathBuf)> = std::fs::read_dir(dir)
105        .ok()?
106        .filter_map(Result::ok)
107        .filter(|entry| entry.file_name().to_string_lossy().ends_with(".txt"))
108        .map(|entry| {
109            let modified = entry.metadata().and_then(|meta| meta.modified()).unwrap_or(UNIX_EPOCH);
110            (modified, entry.path())
111        })
112        .collect();
113    files.sort();
114    let excess = files.len().saturating_sub(SPILL_KEEP - 1);
115    for (_, path) in files.iter().take(excess) {
116        std::fs::remove_file(path).ok()?;
117    }
118    let nanos = SystemTime::now()
119        .duration_since(UNIX_EPOCH)
120        .map_or(0, |elapsed| elapsed.as_nanos());
121    let path = dir.join(format!("{nanos}-{}-{name}.txt", std::process::id()));
122    let mut file = OpenOptions::new()
123        .write(true)
124        .create_new(true)
125        .mode(0o600)
126        .open(&path)
127        .ok()?;
128    file.write_all(text.as_bytes()).ok()?;
129    Some(path.display().to_string())
130}
131
132/// `truncateToolOutput`: keep the head and tail of `text` within `max_bytes` (UTF-8) and say what was elided.
133pub fn truncate_tool_output(text: &str, max_bytes: usize, spill_dir: Option<&Path>) -> String {
134    let data = text.as_bytes();
135    if data.len() <= max_bytes {
136        return text.to_string();
137    }
138    let saved = spill_dir.and_then(|dir| spill_output(text, dir, "cell"));
139    let keep = max_bytes / 2;
140    // A cut inside a multi-byte character drops that character rather than adding a replacement glyph.
141    let head = String::from_utf8_lossy(&data[..keep]);
142    let head = head.strip_suffix('\u{fffd}').unwrap_or(&head);
143    let tail = String::from_utf8_lossy(&data[data.len() - keep..]);
144    let tail = tail.strip_prefix('\u{fffd}').unwrap_or(&tail);
145    let lines = text.matches('\n').count() + 1;
146    let elided = data.len() - 2 * keep;
147    let saved = saved.map_or_else(String::new, |path| format!("; full output in {path}"));
148    [
149        format!(
150            "Warning: truncated output ({} bytes, {lines} lines; the middle {elided} bytes were cut). Process large data in Python and print only what you need.",
151            data.len()
152        ),
153        String::new(),
154        head.to_string(),
155        format!("[... {elided} bytes truncated{saved} ...]"),
156        tail.to_string(),
157    ]
158    .join("\n")
159}