car-server-core 0.47.0

//! Session-scoped tool-result values, and the bounded previews that stand in
//! for them in the transcript (Parslee-ai/car#813).
//!
//! # Why this exists
//!
//! The assistant loop used to hard-truncate every tool observation: a 100-row
//! result became ~2 rows and rows 3-100 were *gone*, with no way to reach them
//! short of re-running the tool and hoping the second result fit. Truncation
//! and a bounded preview look identical in the transcript and behave nothing
//! alike — the first destroys data, the second keeps the value live and puts a
//! description of it in the context.
//!
//! Three costs were being paid at once: data loss on any result over the cap;
//! token cost, because full results are re-serialized into history every turn
//! until compaction evicts them (and compaction then rewrites the prefix,
//! invalidating provider-side prefix caching); and silent wrong answers, since
//! a model reasoning over a clipped table has no signal beyond a marker it
//! routinely ignores.
//!
//! # What a preview must carry
//!
//! Enough *shape* that the model does not need the bytes to plan its next call:
//! the concrete type, the true length, and a head/tail sample. NVIDIA's OO
//! Agents work ([arXiv:2607.20709](https://arxiv.org/abs/2607.20709)) reports
//! 82.2% on SWE-bench Verified at ~28 calls / 1.1M tokens per task against
//! 78.2% at 66 calls / 2.2M tokens for the same backend re-serializing full
//! results — higher pass rate at roughly half the tokens and 40% of the calls.
//! Their `agentdoc/_pformat.py` is ~2k lines and they note that finding preview
//! formats that are obvious to an LLM is still open work, so this module makes
//! no claim to be finished. It handles the shapes CAR's own tools return and
//! says plainly, in [`render_preview`], what it does not special-case.
//!
//! # Lifetime
//!
//! The store lives for one loop run and nothing persists past it. Handles are
//! `r1`, `r2`, … — short, because they are typed by the model into subsequent
//! tool arguments, and a handle nobody can type is a handle nobody uses.

use std::collections::HashMap;

use serde_json::Value;

/// How much of a string preview to show at each end.
const TEXT_HEAD_BYTES: usize = 400;
const TEXT_TAIL_BYTES: usize = 200;
/// How many elements of a sequence to sample at each end.
const SEQ_HEAD_ITEMS: usize = 3;
const SEQ_TAIL_ITEMS: usize = 2;
/// How much of a single sampled element to show before eliding it.
const ELEMENT_BUDGET: usize = 120;

/// Per-run store of full tool results, addressed by short handles.
///
/// Deliberately not thread-shared: the loop is sequential and one store per run
/// is the whole lifetime story. A shared store would raise a question this
/// design does not want to answer — whether one run can read another's values.
#[derive(Default, Debug)]
pub struct SessionValues {
    values: HashMap<String, Value>,
    next: usize,
}

impl SessionValues {
    pub fn new() -> Self {
        Self::default()
    }

    /// Retain `value` and return its handle.
    pub fn put(&mut self, value: Value) -> String {
        self.next += 1;
        let handle = format!("r{}", self.next);
        self.values.insert(handle.clone(), value);
        handle
    }

    pub fn get(&self, handle: &str) -> Option<&Value> {
        self.values.get(handle)
    }

    pub fn len(&self) -> usize {
        self.values.len()
    }

    pub fn is_empty(&self) -> bool {
        self.values.is_empty()
    }

    /// Substitute `$rN` references in tool arguments with the values they name.
    ///
    /// Runs BEFORE parameter validation, which is not an implementation detail:
    /// `car-validator` checks parameters against the tool's JSON Schema, and
    /// `"$r3"` is a string where the schema may demand an array. Resolving
    /// first means the validator sees the real value and its guarantees are
    /// unweakened — the alternative, teaching every schema to also admit a
    /// reference form, would punch a hole in all of them.
    ///
    /// Only *whole* string values are treated as references. A string that
    /// merely contains `$r3` is left alone: tool arguments legitimately carry
    /// shell snippets and regexes, and interpolating into the middle of one
    /// would corrupt commands that have nothing to do with this feature.
    ///
    /// An unknown handle is left untouched rather than erased or errored. The
    /// model gets the literal string back and the tool's own validation
    /// reports it, which is a better failure than silently substituting null.
    /// Returns the handles that were resolved, for logging.
    pub fn resolve_refs(&self, params: &mut Value) -> Vec<String> {
        let mut resolved = Vec::new();
        self.resolve_into(params, &mut resolved);
        resolved
    }

    /// Resolve `$rN`, or `$rN.field.sub` / `$rN.0` into a value.
    ///
    /// Field addressing is not a nicety. Tools return *envelopes* — CAR's
    /// `read_file` yields `{content, path, size_bytes, total_lines}` — so a
    /// handle that could only name the whole envelope would force the model to
    /// pass a JSON object everywhere a string was wanted, and the feature would
    /// be unusable for the very case it was built for.
    ///
    /// `None` for an unknown handle or a path that does not exist, which the
    /// caller turns into "leave the literal alone".
    fn lookup(&self, reference: &str) -> Option<&Value> {
        let mut parts = reference.split('.');
        let mut cursor = self.get(parts.next()?)?;
        for part in parts {
            cursor = match cursor {
                Value::Object(map) => map.get(part)?,
                // A numeric segment indexes an array, so a row of a result set
                // is addressable without a separate syntax.
                Value::Array(items) => items.get(part.parse::<usize>().ok()?)?,
                _ => return None,
            };
        }
        Some(cursor)
    }

    fn resolve_into(&self, node: &mut Value, resolved: &mut Vec<String>) {
        match node {
            Value::String(s) => {
                if let Some(reference) = s.strip_prefix('$') {
                    if let Some(value) = self.lookup(reference) {
                        resolved.push(reference.to_string());
                        *node = value.clone();
                    }
                }
            }
            Value::Array(items) => {
                for item in items {
                    self.resolve_into(item, resolved);
                }
            }
            Value::Object(map) => {
                for (_, v) in map.iter_mut() {
                    self.resolve_into(v, resolved);
                }
            }
            _ => {}
        }
    }
}

/// Render a bounded, typed preview of `value`, naming the handle that holds it.
///
/// The shapes handled are the ones CAR's own tools return: JSON arrays and
/// objects, and text (shell stdout, file contents, log output). Everything else
/// — numbers, booleans, null — is small enough to render whole, so there is
/// nothing to preview.
///
/// **Not special-cased**, and worth knowing before trusting a preview to carry
/// enough shape: tabular text (CSV/TSV output is previewed as text, so the
/// model sees a row count only if it counts lines itself), binary payloads
/// (rendered as their JSON escaping), and deeply nested objects (only top-level
/// keys are listed). Each is a candidate for the design pass #813 asks for.
pub fn render_preview(handle: &str, value: &Value) -> String {
    match value {
        Value::Array(items) => render_array(handle, items),
        Value::Object(map) => render_object(handle, map),
        Value::String(s) => render_text(handle, s),
        // Scalars are already their own best preview.
        other => format!("{handle} = {other}"),
    }
}

fn render_array(handle: &str, items: &[Value]) -> String {
    let len = items.len();
    if len <= SEQ_HEAD_ITEMS + SEQ_TAIL_ITEMS {
        let all: Vec<String> = items.iter().map(summarize_element).collect();
        return format!("{handle} = array(len={len}, [{}])", all.join(", "));
    }
    let head: Vec<String> = items
        .iter()
        .take(SEQ_HEAD_ITEMS)
        .map(summarize_element)
        .collect();
    let tail: Vec<String> = items[len - SEQ_TAIL_ITEMS..]
        .iter()
        .map(summarize_element)
        .collect();
    format!(
        "{handle} = array(len={len}, [:{}]=[{}], [-{}:]=[{}])",
        SEQ_HEAD_ITEMS,
        head.join(", "),
        SEQ_TAIL_ITEMS,
        tail.join(", ")
    )
}

fn render_object(handle: &str, map: &serde_json::Map<String, Value>) -> String {
    let bytes = Value::Object(map.clone()).to_string().len();
    // Keys ALONE are not enough shape, and this is the case that proves it:
    // CAR's `read_file` returns `{content, path, size_bytes, total_lines}`, so
    // a key list tells the model there is a `content` and nothing whatsoever
    // about the 55 KB inside it — strictly less useful than the text preview
    // the same payload would have got on its own. Each value is therefore
    // summarized by type and size, so a large field announces itself and the
    // model knows which one to address.
    if map.len() > 24 {
        let keys: Vec<&str> = map.keys().take(8).map(String::as_str).collect();
        return format!(
            "{handle} = json(keys={} total, first=[{}, …], bytes={bytes})",
            map.len(),
            keys.join(", ")
        );
    }
    let fields: Vec<String> = map
        .iter()
        .map(|(k, v)| format!("{k}: {}", describe_field(v)))
        .collect();
    format!("{handle} = json({}, bytes={bytes})", fields.join(", "))
}

/// One field of an object: type and size for anything big, the literal value
/// for anything small enough to be its own best description.
fn describe_field(value: &Value) -> String {
    match value {
        Value::String(s) if s.len() > ELEMENT_BUDGET => {
            format!("text(len={}, lines={})", human(s.len()), s.lines().count())
        }
        Value::String(s) => format!("{s:?}"),
        Value::Array(items) => format!("array(len={})", items.len()),
        Value::Object(inner) => format!("json(keys={})", inner.len()),
        other => other.to_string(),
    }
}

fn render_text(handle: &str, s: &str) -> String {
    let bytes = s.len();
    let lines = s.lines().count();
    if bytes <= TEXT_HEAD_BYTES + TEXT_TAIL_BYTES {
        return format!("{handle} = text(len={}, lines={lines}) {s:?}", human(bytes));
    }
    let head = clip(s, TEXT_HEAD_BYTES, true);
    let tail = clip(s, TEXT_TAIL_BYTES, false);
    format!(
        "{handle} = text(len={}, lines={lines}, head={head:?}, tail={tail:?})",
        human(bytes)
    )
}

/// One element of a sequence, bounded so a long row cannot blow the preview.
fn summarize_element(value: &Value) -> String {
    match value {
        Value::Object(map) => {
            let inner: Vec<String> = map
                .iter()
                .take(2)
                .map(|(k, v)| format!("{k}:{}", clip_str(&scalar_or_type(v), 24)))
                .collect();
            let more = if map.len() > 2 { ", …" } else { "" };
            format!("{{{}{more}}}", inner.join(","))
        }
        Value::Array(items) => format!("array(len={})", items.len()),
        Value::String(s) => format!("{:?}", clip_str(s, ELEMENT_BUDGET)),
        other => clip_str(&other.to_string(), ELEMENT_BUDGET),
    }
}

fn scalar_or_type(value: &Value) -> String {
    match value {
        Value::Object(_) => "{…}".to_string(),
        Value::Array(items) => format!("array({})", items.len()),
        Value::String(s) => s.clone(),
        other => other.to_string(),
    }
}

/// Clip to a byte budget on a char boundary, marking the elision.
///
/// `pub(crate)` because `events_query` bounds its event payloads the same way
/// (#815) — one clipper, so the two model-facing surfaces cannot disagree about
/// what an elision looks like.
pub(crate) fn clip_str(s: &str, budget: usize) -> String {
    if s.len() <= budget {
        return s.to_string();
    }
    let mut end = budget;
    while !s.is_char_boundary(end) {
        end -= 1;
    }
    format!("{}…", &s[..end])
}

/// Take `budget` bytes from the head or tail, respecting char boundaries.
fn clip(s: &str, budget: usize, from_head: bool) -> String {
    if s.len() <= budget {
        return s.to_string();
    }
    if from_head {
        let mut end = budget;
        while !s.is_char_boundary(end) {
            end -= 1;
        }
        s[..end].to_string()
    } else {
        let mut start = s.len() - budget;
        while !s.is_char_boundary(start) {
            start += 1;
        }
        s[start..].to_string()
    }
}

/// Byte counts a human can compare at a glance — the difference between a 2 KB
/// and a 2 MB result is the whole point of showing the true length.
fn human(bytes: usize) -> String {
    const KB: usize = 1024;
    const MB: usize = KB * 1024;
    if bytes >= MB {
        format!("{:.1}MB", bytes as f64 / MB as f64)
    } else if bytes >= KB {
        format!("{:.1}KB", bytes as f64 / KB as f64)
    } else {
        format!("{bytes}B")
    }
}

/// The line appended to a preview telling the model the value is still reachable.
///
/// Without this the preview is just a prettier truncation: the model has to
/// know the reference form exists, and it will not infer `$r3` from seeing
/// `r3 = …`.
pub fn reference_hint(handle: &str) -> String {
    format!(
        "\n[full value retained this run — pass \"${handle}\" as a tool argument \
         to operate on all of it, or \"${handle}.<field>\" for one field]"
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn handles_are_short_and_sequential() {
        let mut store = SessionValues::new();
        assert_eq!(store.put(json!(1)), "r1");
        assert_eq!(store.put(json!(2)), "r2");
        assert_eq!(store.get("r1"), Some(&json!(1)));
        assert_eq!(store.get("nope"), None);
        assert_eq!(store.len(), 2);
    }

    /// The property #813 is actually about: rows 3-100 must remain reachable.
    #[test]
    fn the_elided_data_is_recoverable_through_the_handle() {
        let mut store = SessionValues::new();
        let rows: Vec<Value> = (0..100).map(|i| json!({"id": i})).collect();
        let handle = store.put(json!(rows));

        let preview = render_preview(&handle, store.get(&handle).unwrap());
        assert!(
            preview.contains("len=100"),
            "true length must survive: {preview}"
        );

        // The whole value is still there — this is the difference from cap().
        let recovered = store.get(&handle).unwrap().as_array().unwrap();
        assert_eq!(recovered.len(), 100);
        assert_eq!(recovered[57], json!({"id": 57}));
    }

    #[test]
    fn array_preview_carries_type_length_and_both_ends() {
        let items: Vec<Value> = (0..100).map(|i| json!(i)).collect();
        let p = render_preview("r1", &json!(items));
        assert!(p.starts_with("r1 = array(len=100"), "{p}");
        assert!(p.contains("[:3]=[0, 1, 2]"), "head sample missing: {p}");
        assert!(p.contains("[-2:]=[98, 99]"), "tail sample missing: {p}");
    }

    /// A short sequence needs no elision — showing it whole is strictly more
    /// useful than showing two ends of five items.
    #[test]
    fn short_arrays_render_whole() {
        let p = render_preview("r1", &json!([1, 2, 3]));
        assert_eq!(p, "r1 = array(len=3, [1, 2, 3])");
    }

    #[test]
    fn object_preview_describes_fields_not_just_key_names() {
        let p = render_preview("r2", &json!({"name": "car", "version": "0.46.1"}));
        assert!(
            p.contains(r#"name: "car""#),
            "small values shown literally: {p}"
        );
        assert!(p.contains("bytes="), "true size must be stated: {p}");
    }

    /// The case that exposed key-lists-only as insufficient: CAR's `read_file`
    /// returns an envelope, and a preview naming `content` without describing
    /// it tells the model less about the payload than a bare text preview of
    /// the same bytes would have.
    #[test]
    fn a_large_field_inside_an_envelope_announces_itself() {
        let body = format!("HEAD\n{}\nTAIL", "z".repeat(50_000));
        let value = json!({
            "content": body,
            "path": "./big.txt",
            "size_bytes": 50_010,
            "total_lines": 3,
        });
        let p = render_preview("r1", &value);
        assert!(
            p.contains("content: text(len=") && p.contains("lines=3"),
            "the big field must state its size and shape: {p}"
        );
        assert!(
            p.contains(r#"path: "./big.txt""#),
            "small fields stay literal: {p}"
        );
        assert!(
            p.len() < 400,
            "preview must stay bounded: {} bytes",
            p.len()
        );
    }

    /// Tools return envelopes, so a handle that could only name the whole
    /// envelope would force a JSON object into every slot that wants a string.
    #[test]
    fn dotted_paths_address_a_field_of_a_retained_value() {
        let mut store = SessionValues::new();
        let h = store.put(json!({"content": "the payload", "path": "./f.txt"}));

        let mut params = json!({"content": format!("${h}.content")});
        let resolved = store.resolve_refs(&mut params);
        assert_eq!(resolved, vec![format!("{h}.content")]);
        assert_eq!(params["content"], json!("the payload"));

        // Numeric segments index arrays, so one row of a result set is
        // addressable without inventing a second syntax.
        let rows = store.put(json!([{"id": 1}, {"id": 2}, {"id": 3}]));
        let mut p2 = json!({"row": format!("${rows}.1.id")});
        store.resolve_refs(&mut p2);
        assert_eq!(p2["row"], json!(2));

        // A path that does not exist stays literal rather than becoming null —
        // a model typo must not silently change what the tool receives.
        let mut p3 = json!({"x": format!("${h}.nope")});
        assert!(store.resolve_refs(&mut p3).is_empty());
        assert_eq!(p3["x"], json!(format!("${h}.nope")));
    }

    #[test]
    fn text_preview_reports_size_lines_and_both_ends() {
        let body = format!("FIRST LINE\n{}\nLAST LINE", "x".repeat(5_000));
        let p = render_preview("r3", &json!(body));
        assert!(p.contains("text(len="), "{p}");
        assert!(p.contains("lines=3"), "line count missing: {p}");
        assert!(p.contains("FIRST LINE"), "head missing: {p}");
        assert!(p.contains("LAST LINE"), "tail missing: {p}");
        // The preview must be far smaller than the value it describes.
        assert!(p.len() < 1_200, "preview not bounded: {} bytes", p.len());
    }

    /// Multi-byte characters must not panic the clipper — the old `cap()` had
    /// to walk back to a char boundary for exactly this reason.
    #[test]
    fn multibyte_text_does_not_panic() {
        let body = "€".repeat(5_000);
        let p = render_preview("r1", &json!(body));
        assert!(p.contains("text(len="), "{p}");
    }

    #[test]
    fn whole_string_references_resolve() {
        let mut store = SessionValues::new();
        let handle = store.put(json!([1, 2, 3]));
        let mut params = json!({"rows": format!("${handle}"), "limit": 10});
        let resolved = store.resolve_refs(&mut params);
        assert_eq!(resolved, vec![handle]);
        assert_eq!(params["rows"], json!([1, 2, 3]));
        assert_eq!(params["limit"], json!(10));
    }

    /// A reference nested inside an array or object must resolve too — tool
    /// arguments are structured, not flat.
    #[test]
    fn nested_references_resolve() {
        let mut store = SessionValues::new();
        let h = store.put(json!("hello"));
        let mut params = json!({"outer": {"inner": [format!("${h}")]}});
        store.resolve_refs(&mut params);
        assert_eq!(params["outer"]["inner"][0], json!("hello"));
    }

    /// Only WHOLE string values are references. Tool arguments legitimately
    /// carry shell snippets and regexes; interpolating into the middle of one
    /// would corrupt commands that have nothing to do with this feature.
    #[test]
    fn partial_matches_are_left_alone() {
        let mut store = SessionValues::new();
        let h = store.put(json!("VALUE"));
        let mut params = json!({"cmd": format!("echo ${h} > out.txt"), "re": "^\\$r1$"});
        let resolved = store.resolve_refs(&mut params);
        assert!(
            resolved.is_empty(),
            "a substring must not trigger substitution: {params}"
        );
        assert_eq!(params["cmd"], json!(format!("echo ${h} > out.txt")));
    }

    /// An unknown handle stays literal. Erasing it or substituting null would
    /// turn a model typo into a silently different tool call; leaving it lets
    /// the tool's own validation report it.
    #[test]
    fn unknown_handles_are_left_untouched() {
        let store = SessionValues::new();
        let mut params = json!({"rows": "$r99"});
        let resolved = store.resolve_refs(&mut params);
        assert!(resolved.is_empty());
        assert_eq!(params["rows"], json!("$r99"));
    }

    #[test]
    fn reference_hint_names_the_typed_form() {
        let hint = reference_hint("r7");
        assert!(
            hint.contains("\"$r7\""),
            "the model must see the exact form: {hint}"
        );
    }
}