supercode_harness/tools/

tiers.rs

//! Deterministic tool-schema tiering (TR-8 / T5).
//!
//! Shrinks what's ADVERTISED to the model, never what's stored: tool
//! definitions are config, never session content (SPEC ground rule 4), so
//! this operates purely on the wire-shape `description`/`parameters` pair
//! built fresh at request time ([`crate::agent::Agent::schema_for`]) — there
//! is nothing here to leak into an export or sidecar, since a tier is never
//! persisted anywhere and is recomputed from the registry + [`crate::Config`]
//! on every call.
//!
//! [`SchemaTier::Medium`] and [`SchemaTier::Minimal`] are deterministic,
//! rule-based text transforms — no LLM in the loop, so the same
//! (registry, tier) pair always produces byte-identical output (dev/05). The
//! model must never see an INVALID schema: `required`, every property's
//! `type`, `enum`, and the `properties`/`items` structure itself are never
//! touched by [`minify`] — only prose (`description`) and the
//! `examples`/`title` metadata keys are stripped or trimmed.

use serde_json::Value;

/// How verbose an advertised tool schema is. `Full` is today's behavior —
/// byte-identical to the tool's own `description()`/`parameters()`. Builtins
/// default to `Full` (small, load-bearing); the win target is fat activated
/// MCP tools (set via the global knob or a per-tool override, see
/// [`crate::Config::tool_schema_tier`] / [`crate::config::ToolOverride::schema_tier`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Hash)]
pub enum SchemaTier {
    /// As-shipped: `description()`/`parameters()` verbatim.
    #[default]
    Full,
    /// Trimmed descriptions (top-level and per-param, truncated at a
    /// sentence boundary); `examples`/`title` stripped everywhere.
    /// `required` and every param's `type` are untouched.
    Medium,
    /// One-sentence top-level description; only *required* params keep a
    /// (one-sentence) description — optional params keep name+type only,
    /// with their `description` dropped. `required` and every param's
    /// `type` are untouched, so the schema stays valid and fully typed.
    Minimal,
}

impl SchemaTier {
    /// Parse a config/CLI string form (`"full"` / `"medium"` / `"minimal"`).
    pub fn parse(s: &str) -> Option<Self> {
        match s {
            "full" => Some(SchemaTier::Full),
            "medium" => Some(SchemaTier::Medium),
            "minimal" => Some(SchemaTier::Minimal),
            _ => None,
        }
    }

    /// The canonical string form (round-trips through [`Self::parse`]).
    pub fn as_str(&self) -> &'static str {
        match self {
            SchemaTier::Full => "full",
            SchemaTier::Medium => "medium",
            SchemaTier::Minimal => "minimal",
        }
    }
}

/// Apply `tier` to a tool's advertised `description`/`parameters`, returning
/// the (possibly) minified pair. Deterministic and LLM-free: the same inputs
/// always produce the same output.
///
/// Per-tool byte floor: if the minified wire form (description + serialized
/// parameters) is not smaller than the original, the original is returned
/// unchanged — a tool that's already terse is advertised as-is at any tier,
/// never bloated by the transform.
pub fn minify(description: &str, parameters: &Value, tier: SchemaTier) -> (String, Value) {
    if tier == SchemaTier::Full {
        return (description.to_string(), parameters.clone());
    }
    let budget = if tier == SchemaTier::Minimal { 1 } else { 2 };
    let new_description = truncate_sentences(description, budget);
    let mut new_parameters = parameters.clone();
    minify_node(&mut new_parameters, tier);

    let orig_bytes = description.len()
        + serde_json::to_string(parameters)
            .map(|s| s.len())
            .unwrap_or(0);
    let new_bytes = new_description.len()
        + serde_json::to_string(&new_parameters)
            .map(|s| s.len())
            .unwrap_or(0);
    if new_bytes >= orig_bytes {
        // Byte floor: never grow, and skip the churn on already-terse tools.
        (description.to_string(), parameters.clone())
    } else {
        (new_description, new_parameters)
    }
}

/// Recursively strip `examples`/`title` and trim/drop `description` per
/// `tier`, over a JSON-Schema object node. Applied uniformly at every depth:
/// each object node's own `required` array decides which of ITS OWN
/// `properties` keep a description at [`SchemaTier::Minimal`], so nested
/// object/array schemas get the same required-vs-optional treatment as the
/// tool's direct parameters — never just a single global flag at depth 0.
/// Recursion also follows every JSON-Schema combinator shape a node can
/// hold: `items` (both single-schema and draft-4 tuple-style array-of-
/// schemas), `anyOf`/`oneOf`/`allOf`, `if`/`then`/`else`, and the schema-map
/// keys `$defs`/`definitions`/`patternProperties` — so a schema whose bulk
/// lives inside a combinator gets the same treatment as one that lives
/// directly under `properties`. `required`, `type`, `enum`, and the
/// `properties`/`items` keys themselves are never touched (dev/02:
/// type/required equality across tiers).
fn minify_node(node: &mut Value, tier: SchemaTier) {
    let Some(map) = node.as_object_mut() else {
        return;
    };
    map.remove("examples");
    map.remove("title");

    // Trim this node's own `description` (e.g. an object-typed param's
    // blurb), if present.
    if let Some(Value::String(d)) = map.get("description").cloned() {
        let n = if tier == SchemaTier::Minimal { 1 } else { 2 };
        map.insert(
            "description".to_string(),
            Value::String(truncate_sentences(&d, n)),
        );
    }

    let required: Vec<String> = map
        .get("required")
        .and_then(Value::as_array)
        .map(|a| {
            a.iter()
                .filter_map(|v| v.as_str().map(str::to_string))
                .collect()
        })
        .unwrap_or_default();

    if let Some(props) = map.get_mut("properties").and_then(|p| p.as_object_mut()) {
        let keys: Vec<String> = props.keys().cloned().collect();
        for key in keys {
            let is_required = required.iter().any(|r| r == &key);
            let Some(prop) = props.get_mut(&key) else {
                continue;
            };
            if let Some(pm) = prop.as_object_mut() {
                pm.remove("examples");
                pm.remove("title");
                // `minify_node` is only ever reached for Medium/Minimal
                // (`minify()` returns early for `Full`), so there's no
                // `Full` case to handle here.
                if tier == SchemaTier::Minimal && !is_required {
                    pm.remove("description");
                } else if let Some(Value::String(d)) = pm.get("description").cloned() {
                    pm.insert(
                        "description".to_string(),
                        Value::String(truncate_sentences(&d, 1)),
                    );
                }
            }
            // Recurse into whatever nested schema shape this property
            // holds (nested object `properties`/`required`, array `items`,
            // or a nested combinator) so the same rule applies at every
            // depth, no matter which JSON-Schema shape carries the bulk.
            minify_node(prop, tier);
        }
    }

    // Array `items`: either a single schema, or (draft-4 tuple validation)
    // an array of per-position schemas.
    if let Some(items) = map.get_mut("items") {
        match items {
            Value::Array(items) => {
                for item in items {
                    minify_node(item, tier);
                }
            }
            _ => minify_node(items, tier),
        }
    }

    // Combinator schema lists: each entry is itself a full schema node.
    for key in ["anyOf", "oneOf", "allOf"] {
        if let Some(Value::Array(arr)) = map.get_mut(key) {
            for item in arr {
                minify_node(item, tier);
            }
        }
    }

    // Conditional schema keys: each holds a single schema node.
    for key in ["if", "then", "else"] {
        if let Some(v) = map.get_mut(key) {
            minify_node(v, tier);
        }
    }

    // Schema-map keys: each value is itself a full schema node, keyed by
    // definition name (`$defs`/`definitions`) or regex (`patternProperties`)
    // rather than by required-tracked property name.
    for key in ["$defs", "definitions", "patternProperties"] {
        if let Some(Value::Object(sub)) = map.get_mut(key) {
            for v in sub.values_mut() {
                minify_node(v, tier);
            }
        }
    }
}

/// Common abbreviations whose trailing `.` must not be mistaken for a
/// sentence boundary. Checked as a suffix of the text scanned so far, so
/// multi-period forms like "e.g." are matched whole (the earlier internal
/// `.` in "e.g" is never itself a boundary candidate, since it isn't
/// followed by whitespace).
const ABBREVIATIONS: &[&str] = &["e.g.", "i.e.", "etc.", "Mr.", "Mrs.", "Dr.", "vs.", "cf."];

/// Truncate `s` to at most `n` sentences, cutting only at a sentence
/// boundary (`.`/`!`/`?` immediately followed by whitespace or
/// end-of-string) — never mid-sentence. Abbreviation-aware: a `.` boundary
/// candidate that closes a known abbreviation (see [`ABBREVIATIONS`]), e.g.
/// "e.g." or "Dr.", is not counted as a sentence end. Returns `s` unchanged
/// if fewer than `n` boundaries are found (nothing sensible to cut at).
/// Byte-index-safe: every cut point sits right after a single-byte ASCII
/// punctuation character, which is always a valid UTF-8 boundary regardless
/// of what multi-byte content surrounds it.
fn truncate_sentences(s: &str, n: usize) -> String {
    if n == 0 || s.is_empty() {
        return s.to_string();
    }
    let bytes = s.as_bytes();
    let mut count = 0;
    for (i, &b) in bytes.iter().enumerate() {
        if b == b'.' || b == b'!' || b == b'?' {
            let boundary = i + 1 == bytes.len() || bytes[i + 1] == b' ' || bytes[i + 1] == b'\n';
            if boundary {
                if b == b'.' && ABBREVIATIONS.iter().any(|a| s[..=i].ends_with(a)) {
                    continue;
                }
                count += 1;
                if count >= n {
                    return s[..=i].to_string();
                }
            }
        }
    }
    s.to_string()
}

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

    #[test]
    fn full_tier_is_identity() {
        let desc = "A very long description. With two sentences.";
        let params = json!({"type":"object","properties":{"a":{"type":"string","description":"x","examples":["e"]}},"required":["a"]});
        let (d, p) = minify(desc, &params, SchemaTier::Full);
        assert_eq!(d, desc);
        assert_eq!(p, params);
    }

    #[test]
    fn truncate_sentences_cuts_at_boundary() {
        assert_eq!(truncate_sentences("One. Two. Three.", 1), "One.");
        assert_eq!(truncate_sentences("One. Two. Three.", 2), "One. Two.");
        assert_eq!(
            truncate_sentences("No punctuation here", 1),
            "No punctuation here"
        );
        assert_eq!(truncate_sentences("", 1), "");
    }

    #[test]
    fn minimal_drops_optional_param_descriptions_keeps_required() {
        let desc = "Does a thing. Has more detail. Even more.";
        let params = json!({
            "type": "object",
            "properties": {
                "req": {"type": "string", "description": "The required one. More detail here."},
                "opt": {"type": "integer", "description": "The optional one. More detail here."}
            },
            "required": ["req"]
        });
        let (d, p) = minify(desc, &params, SchemaTier::Minimal);
        assert_eq!(d, "Does a thing.");
        assert_eq!(p["properties"]["req"]["description"], "The required one.");
        assert!(p["properties"]["opt"].get("description").is_none());
        // Types and required are untouched.
        assert_eq!(p["properties"]["req"]["type"], "string");
        assert_eq!(p["properties"]["opt"]["type"], "integer");
        assert_eq!(p["required"], json!(["req"]));
    }

    #[test]
    fn examples_and_title_stripped_at_every_tier_above_full() {
        let params = json!({
            "type": "object",
            "title": "Top title",
            "properties": {
                "a": {"type": "string", "examples": ["x"], "title": "A title"}
            },
            "required": []
        });
        let (_, p) = minify("desc.", &params, SchemaTier::Medium);
        assert!(p.get("title").is_none());
        assert!(p["properties"]["a"].get("examples").is_none());
        assert!(p["properties"]["a"].get("title").is_none());
    }

    #[test]
    fn byte_floor_never_grows_already_terse_schema() {
        let desc = "Short.";
        let params = json!({"type":"object","properties":{"a":{"type":"string"}},"required":["a"]});
        let (d, p) = minify(desc, &params, SchemaTier::Minimal);
        assert_eq!(d, desc);
        assert_eq!(p, params);
    }

    #[test]
    fn nested_object_properties_get_required_aware_treatment_too() {
        let params = json!({
            "type": "object",
            "properties": {
                "outer": {
                    "type": "object",
                    "properties": {
                        "inner_req": {"type": "string", "description": "Inner required. More."},
                        "inner_opt": {"type": "string", "description": "Inner optional. More."}
                    },
                    "required": ["inner_req"]
                }
            },
            "required": ["outer"]
        });
        let (_, p) = minify("desc. more.", &params, SchemaTier::Minimal);
        let outer = &p["properties"]["outer"];
        assert_eq!(
            outer["properties"]["inner_req"]["description"],
            "Inner required."
        );
        assert!(outer["properties"]["inner_opt"]
            .get("description")
            .is_none());
        assert_eq!(outer["properties"]["inner_req"]["type"], "string");
        assert_eq!(outer["properties"]["inner_opt"]["type"], "string");
    }

    #[test]
    fn array_items_are_recursed_into() {
        let params = json!({
            "type": "object",
            "properties": {
                "list": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "field": {"type": "string", "description": "Field desc. More detail.", "examples": ["e"]}
                        },
                        "required": []
                    }
                }
            },
            "required": []
        });
        let (_, p) = minify("desc. more.", &params, SchemaTier::Minimal);
        let field = &p["properties"]["list"]["items"]["properties"]["field"];
        assert!(field.get("examples").is_none());
        assert!(
            field.get("description").is_none(),
            "not required at that nesting level"
        );
        assert_eq!(field["type"], "string");
    }

    #[test]
    fn truncate_sentences_ignores_common_abbreviations() {
        assert_eq!(
            truncate_sentences("See e.g. the docs. Second sentence.", 1),
            "See e.g. the docs."
        );
        assert_eq!(
            truncate_sentences(
                "Ask Dr. Smith for the etc. items, i.e. all of them. Next.",
                1
            ),
            "Ask Dr. Smith for the etc. items, i.e. all of them."
        );
        // A real sentence end right after an abbreviation is still found.
        assert_eq!(
            truncate_sentences("Contact Mr. Lee. Thanks.", 2),
            "Contact Mr. Lee. Thanks."
        );
        assert_eq!(
            truncate_sentences("Contact Mr. Lee. Thanks.", 1),
            "Contact Mr. Lee."
        );
    }

    /// dev/01: a schema whose bulk lives inside combinators (`anyOf`,
    /// `oneOf`, `allOf`, `$defs`) is minified — same description/example
    /// stripping as under `properties` — while every `type`/`required` is
    /// preserved and the result stays a structurally valid schema.
    #[test]
    fn combinators_are_recursed_into_and_minified() {
        let params = json!({
            "type": "object",
            "properties": {
                "payload": {
                    "anyOf": [
                        {
                            "type": "object",
                            "description": "First shape of the payload, used for the legacy request format. It carries a lot of historical baggage. Keep reading for details.",
                            "properties": {
                                "a": {"type": "string", "description": "The a field. It represents something important. More context follows here."}
                            },
                            "required": ["a"]
                        },
                        {
                            "type": "object",
                            "description": "Second shape of the payload, used for the modern request format. It is much simpler than the legacy one. Keep reading for details.",
                            "properties": {
                                "b": {"type": "integer", "description": "The b field. It represents something else important. More context follows here."}
                            },
                            "required": ["b"]
                        }
                    ]
                },
                "mode": {
                    "oneOf": [
                        {"type": "string", "const": "fast", "description": "Fast mode trades accuracy for speed. Use when latency matters most. Read the docs for tradeoffs."},
                        {"type": "string", "const": "slow", "description": "Slow mode trades speed for accuracy. Use when correctness matters most. Read the docs for tradeoffs."}
                    ]
                },
                "combo": {
                    "allOf": [
                        {
                            "type": "object",
                            "description": "Base combo shape shared by every variant. It defines the common envelope fields. Read carefully before extending.",
                            "properties": {
                                "id": {"type": "string", "description": "The identifier. Must be globally unique. Formatted as a UUID."}
                            },
                            "required": ["id"]
                        },
                        {
                            "type": "object",
                            "description": "Extension combo shape layered on top of the base envelope. It adds variant-specific fields. Read carefully before extending.",
                            "properties": {
                                "extra": {"type": "string", "description": "Extra data. Optional free-form text. Formatted as plain UTF-8."}
                            },
                            "required": []
                        }
                    ]
                }
            },
            "$defs": {
                "Widget": {
                    "type": "object",
                    "description": "A reusable widget definition referenced elsewhere in this schema via $ref. It has a long explanatory blurb here for testing.",
                    "properties": {
                        "name": {"type": "string", "description": "The widget's name. Must be unique within its namespace. Free-form text otherwise."}
                    },
                    "required": ["name"]
                }
            },
            "required": ["payload"]
        });

        let orig_bytes = serde_json::to_string(&params).unwrap().len();
        let (_, p) = minify("desc. more. even more.", &params, SchemaTier::Minimal);
        let new_bytes = serde_json::to_string(&p).unwrap().len();

        // Meaningful size cut: the bulk of this fixture's bytes live inside
        // combinators, so minification only "counts" if it reaches them.
        assert!(
            new_bytes < orig_bytes * 7 / 10,
            "expected a meaningful size cut, got {orig_bytes} -> {new_bytes} bytes"
        );

        // anyOf branches: minified, required-aware, still valid.
        let any_of = &p["properties"]["payload"]["anyOf"];
        assert_eq!(
            any_of[0]["description"],
            "First shape of the payload, used for the legacy request format."
        );
        assert_eq!(any_of[0]["properties"]["a"]["description"], "The a field.");
        assert_eq!(any_of[0]["properties"]["a"]["type"], "string");
        assert_eq!(any_of[0]["required"], json!(["a"]));
        assert_eq!(any_of[1]["properties"]["b"]["type"], "integer");
        assert_eq!(any_of[1]["required"], json!(["b"]));

        // oneOf branches: minified.
        let one_of = &p["properties"]["mode"]["oneOf"];
        assert_eq!(
            one_of[0]["description"],
            "Fast mode trades accuracy for speed."
        );
        assert_eq!(one_of[0]["type"], "string");
        assert_eq!(one_of[0]["const"], "fast");

        // allOf branches: minified, each with its own required-aware
        // per-branch property treatment.
        let all_of = &p["properties"]["combo"]["allOf"];
        assert_eq!(
            all_of[0]["description"],
            "Base combo shape shared by every variant."
        );
        assert_eq!(
            all_of[0]["properties"]["id"]["description"],
            "The identifier."
        );
        assert!(all_of[1]["properties"]["extra"]
            .get("description")
            .is_none());
        assert_eq!(all_of[1]["required"], json!([]));

        // $defs: minified, required-aware.
        let widget = &p["$defs"]["Widget"];
        assert_eq!(
            widget["description"],
            "A reusable widget definition referenced elsewhere in this schema via $ref."
        );
        assert_eq!(
            widget["properties"]["name"]["description"],
            "The widget's name."
        );
        assert_eq!(widget["properties"]["name"]["type"], "string");
        assert_eq!(widget["required"], json!(["name"]));

        // Top-level required/type shape is completely untouched.
        assert_eq!(p["required"], json!(["payload"]));
        assert_eq!(p["type"], "object");
    }

    /// `if`/`then`/`else`, `definitions`, and `patternProperties` are all
    /// recursed into the same way as `anyOf`/`oneOf`/`allOf`/`$defs`.
    #[test]
    fn if_then_else_definitions_and_pattern_properties_are_recursed_into() {
        let params = json!({
            "type": "object",
            "if": {"type": "object", "description": "Condition branch description. More detail here.", "properties": {"x": {"type": "string"}}},
            "then": {"type": "object", "description": "Then branch description. More detail here.", "properties": {"y": {"type": "string", "description": "Y field. More detail here."}}, "required": ["y"]},
            "else": {"type": "object", "description": "Else branch description. More detail here.", "properties": {"z": {"type": "string", "description": "Z field. More detail here."}}, "required": []},
            "definitions": {
                "Old": {"type": "object", "description": "Legacy definition kept for draft-7 compatibility. More detail here.", "properties": {"n": {"type": "string"}}}
            },
            "patternProperties": {
                "^S_": {"type": "string", "description": "Pattern-matched string property. More detail here."}
            },
            "properties": {},
            "required": []
        });
        let (_, p) = minify("desc. more.", &params, SchemaTier::Minimal);
        assert_eq!(p["if"]["description"], "Condition branch description.");
        assert_eq!(p["then"]["description"], "Then branch description.");
        assert_eq!(p["then"]["properties"]["y"]["description"], "Y field.");
        assert_eq!(p["else"]["description"], "Else branch description.");
        assert!(p["else"]["properties"]["z"].get("description").is_none());
        assert_eq!(
            p["definitions"]["Old"]["description"],
            "Legacy definition kept for draft-7 compatibility."
        );
        assert_eq!(
            p["patternProperties"]["^S_"]["description"],
            "Pattern-matched string property."
        );
    }

    /// Draft-4 tuple-style `items` (an array of per-position schemas, as
    /// opposed to a single schema applied to every element) is recursed
    /// into position by position.
    #[test]
    fn tuple_style_items_array_is_recursed_into() {
        let params = json!({
            "type": "array",
            "items": [
                {"type": "string", "description": "First tuple slot description. More detail here.", "examples": ["e"]},
                {"type": "integer", "description": "Second tuple slot description. More detail here.", "title": "t"}
            ]
        });
        let (_, p) = minify("desc. more.", &params, SchemaTier::Minimal);
        assert_eq!(
            p["items"][0]["description"],
            "First tuple slot description."
        );
        assert!(p["items"][0].get("examples").is_none());
        assert_eq!(p["items"][0]["type"], "string");
        assert_eq!(
            p["items"][1]["description"],
            "Second tuple slot description."
        );
        assert!(p["items"][1].get("title").is_none());
        assert_eq!(p["items"][1]["type"], "integer");
    }
}