Skip to main content

docsrs_cli/agent_ops/
mod.rs

1//! Agent-native payload reduction applied to the JSON envelope before it is written.
2//!
3//! # Why this exists
4//!
5//! `docsrs-cli` is consumed by LLM agents. Forcing an agent to pipe stdout through
6//! `jaq`/`sed` to reach two fields burns tokens on data the agent never wanted. The
7//! reduction knobs live in the binary so the cut happens **before** the envelope is
8//! handed to the caller.
9//!
10//! # Fixed application order
11//!
12//! `filter` → `sort-by` → `dedupe-by` → `max-items` → `select` → `count-only` →
13//! `truncate-content` → `max-output-bytes`. The order is a contract, and each step
14//! sits where it does for a reason:
15//!
16//! - sorting **before** deduplication decides *which* duplicate survives, so the
17//!   surviving row is the ranked one rather than whichever came first upstream;
18//! - limiting **after** deduplication stops a duplicate from consuming a slot the
19//!   caller wanted spent on a distinct element;
20//! - limiting **before** projection avoids projecting rows that are about to be cut;
21//! - `--count-only` therefore counts what survived filtering, deduplication **and**
22//!   the limit — never the raw upstream total.
23//!
24//! Sorting is what makes limiting meaningful: `--max-items` without an order returns
25//! an arbitrary slice of the matches, which is a worse answer than the full set.
26//!
27//! # Result-array location
28//!
29//! Reduction targets the result array inside `envelope.data`. The array is located by
30//! probing [`RESULT_ARRAY_KEYS`] in order, then falling back to the first array of
31//! objects on the payload. When `data` is itself an array it is used directly; when no
32//! array exists at all, projection applies to the `data` object itself.
33//!
34//! # Failure envelopes
35//!
36//! An envelope with `ok: false` is passed through byte-for-byte. `--filter` never
37//! silences a failure — a filtered-away error would look like an empty success.
38//!
39//! # Module layout
40//!
41//! - [`filter`] — dotted-path addressing and the `--filter` predicate grammar
42//! - `reduce` — the envelope transformations (locate, dedupe, project, truncate)
43//! - this module — the plan ([`AgentOps`]) and the order in which it is applied
44//!
45//! # Examples
46//!
47//! ```
48//! use docsrs_cli::agent_ops::AgentOps;
49//! use docsrs_cli::cli::AgentArgs;
50//!
51//! let args = AgentArgs {
52//!     select: vec!["name".to_string()],
53//!     ..AgentArgs::default()
54//! };
55//! let ops = AgentOps::from_args(&args).expect("valid knobs");
56//! assert!(ops.is_active());
57//! ```
58
59pub mod filter;
60mod reduce;
61#[cfg(test)]
62mod tests;
63
64use serde_json::{Map, Value};
65
66use crate::cli::{AgentArgs, Cli};
67use crate::error::AppResult;
68
69pub use filter::{Filter, FilterOp};
70use reduce::{
71    array_mut, dedupe, locate_array_key, project, reconcile_counts, sort_by, truncate_strings,
72};
73
74/// Keys probed, in order, when locating the result array inside `envelope.data`.
75///
76/// Product payloads use `hits` (search) and `checks` / `commands` / `items` (meta
77/// commands). `results` and `data` are accepted for forward compatibility.
78pub const RESULT_ARRAY_KEYS: &[&str] = &["hits", "results", "items", "checks", "commands", "data"];
79
80/// Sibling integer keys that count the result array and must follow it when it shrinks.
81///
82/// Deliberately narrow. `emitted` is documented as "hits actually emitted", so it
83/// describes *this* envelope's array. `total` is deliberately absent: it counts what
84/// the upstream index classified before any limit, and survives reduction unchanged.
85pub const EMITTED_COUNT_KEYS: &[&str] = &["emitted"];
86
87/// Resolved set of agent-native reduction knobs for one invocation.
88#[derive(Debug, Clone, Default)]
89pub struct AgentOps {
90    select: Vec<String>,
91    filters: Vec<Filter>,
92    sort_by: Option<String>,
93    dedupe_by: Option<String>,
94    max_items: Option<usize>,
95    count_only: bool,
96    truncate_content: Option<usize>,
97    max_output_bytes: Option<u64>,
98}
99
100/// Counters reported under `agent_surface` when any knob is active.
101#[derive(Debug, Clone, Copy, Default)]
102struct Surface {
103    input_count: usize,
104    output_count: usize,
105    limited: bool,
106    content_truncated: bool,
107    output_truncated: bool,
108}
109
110impl AgentOps {
111    /// Build the plan from parsed CLI flags.
112    ///
113    /// # Errors
114    ///
115    /// Returns [`crate::error::ErrorKind::InvalidInput`] when a `--filter` expression
116    /// is malformed.
117    pub fn from_cli(cli: &Cli) -> AppResult<Self> {
118        Self::from_args(&cli.agent)
119    }
120
121    /// Build the plan from the reduction flag group.
122    ///
123    /// `select` accepts CSV or repetition; empty items are dropped so a stray comma
124    /// never becomes a projection for the empty key.
125    ///
126    /// # Errors
127    ///
128    /// Returns [`crate::error::ErrorKind::InvalidInput`] when a `--filter` expression
129    /// is malformed.
130    pub fn from_args(args: &AgentArgs) -> AppResult<Self> {
131        let select: Vec<String> = args
132            .select
133            .iter()
134            .flat_map(|s| s.split(','))
135            .map(str::trim)
136            .filter(|s| !s.is_empty())
137            .map(ToString::to_string)
138            .collect();
139        let mut filters = Vec::with_capacity(args.filter.len());
140        for expr in &args.filter {
141            filters.push(Filter::parse(expr)?);
142        }
143        let non_empty = |s: &Option<String>| s.clone().filter(|v| !v.is_empty());
144        Ok(Self {
145            select,
146            filters,
147            sort_by: non_empty(&args.sort_by),
148            dedupe_by: non_empty(&args.dedupe_by),
149            max_items: args.max_items,
150            count_only: args.count_only,
151            truncate_content: args.truncate_content,
152            max_output_bytes: args.max_output_bytes,
153        })
154    }
155
156    /// Whether any reduction knob is set.
157    ///
158    /// `--max-output-bytes` alone does **not** activate the pipeline: per-command
159    /// budgeting already enforces it upstream, and activating here would change the
160    /// established envelope shape for callers that never asked for `agent_surface`.
161    pub fn is_active(&self) -> bool {
162        !self.select.is_empty()
163            || !self.filters.is_empty()
164            || self.sort_by.is_some()
165            || self.dedupe_by.is_some()
166            || self.max_items.is_some()
167            || self.count_only
168            || self.truncate_content.is_some()
169    }
170
171    /// Apply the pipeline to already-serialized envelope bytes.
172    ///
173    /// Passes the input through unchanged when it is not a JSON object (shell
174    /// completion scripts, human markdown) or when the envelope reports `ok: false`.
175    /// The returned buffer always ends with a newline when non-empty.
176    pub fn apply_to_bytes(&self, raw: &[u8]) -> Vec<u8> {
177        if raw.is_empty() {
178            return Vec::new();
179        }
180        let Ok(mut env) = serde_json::from_slice::<Value>(raw) else {
181            return raw.to_vec();
182        };
183        if !env.is_object() || env.get("ok").and_then(Value::as_bool) == Some(false) {
184            return raw.to_vec();
185        }
186        self.apply_to_envelope(&mut env);
187        match serde_json::to_vec(&env) {
188            Ok(mut buf) => {
189                buf.push(b'\n');
190                buf
191            }
192            Err(_) => raw.to_vec(),
193        }
194    }
195
196    /// Apply the pipeline in place to a parsed success envelope.
197    ///
198    /// Adds an `agent_surface` object describing what the reduction did. Callers that
199    /// pass an error envelope get an untouched value.
200    pub fn apply_to_envelope(&self, env: &mut Value) {
201        if env.get("ok").and_then(Value::as_bool) == Some(false) {
202            return;
203        }
204        let mut surface = Surface::default();
205        let Some(data) = env.get_mut("data") else {
206            return;
207        };
208
209        let array_key = locate_array_key(data);
210        let strip: Vec<&str> = array_key.as_deref().into_iter().collect();
211
212        if let Some(list) = array_mut(data, array_key.as_deref()) {
213            surface.input_count = list.len();
214            if !self.filters.is_empty() {
215                list.retain(|el| self.filters.iter().all(|f| f.matches(el, &strip)));
216            }
217            if let Some(key) = &self.sort_by {
218                sort_by(list, key, &strip);
219            }
220            if let Some(key) = &self.dedupe_by {
221                dedupe(list, key, &strip);
222            }
223            if let Some(max) = self.max_items {
224                surface.limited = list.len() > max;
225                list.truncate(max);
226            }
227            if !self.select.is_empty() {
228                for el in list.iter_mut() {
229                    *el = project(el, &self.select, &strip);
230                }
231            }
232            surface.output_count = list.len();
233            reconcile_counts(data, surface.output_count);
234        } else {
235            surface.input_count = 1;
236            surface.output_count = 1;
237            if !self.select.is_empty() {
238                *data = project(data, &self.select, &strip);
239            }
240        }
241
242        if self.count_only {
243            let count = surface.output_count;
244            *data = Value::Object(Map::from_iter([("count".to_string(), Value::from(count))]));
245        }
246
247        if let Some(limit) = self.truncate_content {
248            surface.content_truncated = truncate_strings(data, limit);
249        }
250
251        // Attach the surface before budgeting so the byte count measures the envelope
252        // the caller actually receives, not a smaller draft of it.
253        if let Some(obj) = env.as_object_mut() {
254            obj.insert("agent_surface".to_string(), surface.to_value());
255        }
256
257        if let Some(max) = self.max_output_bytes {
258            surface.output_truncated = self.enforce_output_budget(env, array_key.as_deref(), max);
259            if surface.output_truncated {
260                if let Some(data) = env.get_mut("data") {
261                    if let Some(list) = array_mut(data, array_key.as_deref()) {
262                        surface.output_count = list.len();
263                    }
264                    // The budget dropped rows after the first reconciliation, so the
265                    // sibling counter is stale again. Re-running it can only shrink
266                    // the envelope (fewer or equal digits), never breach the budget.
267                    reconcile_counts(data, surface.output_count);
268                }
269            }
270            if let Some(obj) = env.as_object_mut() {
271                obj.insert("agent_surface".to_string(), surface.to_value());
272            }
273        }
274    }
275
276    /// Drop trailing elements until the serialized envelope fits `max` bytes.
277    ///
278    /// Never slices the JSON text: a mid-string cut would emit an unparseable
279    /// document, which is strictly worse than an over-budget one.
280    fn enforce_output_budget(&self, env: &mut Value, array_key: Option<&str>, max: u64) -> bool {
281        let mut dropped = false;
282        loop {
283            let len = match serde_json::to_vec(env) {
284                Ok(buf) => buf.len() as u64,
285                Err(_) => return dropped,
286            };
287            if len <= max {
288                return dropped;
289            }
290            let Some(data) = env.get_mut("data") else {
291                return dropped;
292            };
293            let Some(list) = array_mut(data, array_key) else {
294                return dropped;
295            };
296            if list.pop().is_none() {
297                return true;
298            }
299            dropped = true;
300        }
301    }
302}
303
304impl Surface {
305    fn to_value(self) -> Value {
306        Value::Object(Map::from_iter([
307            ("input_count".to_string(), Value::from(self.input_count)),
308            ("output_count".to_string(), Value::from(self.output_count)),
309            // Distinguishes "the set was small" from "the set was cut": without it a
310            // caller cannot tell whether raising --max-items would return more.
311            ("limited".to_string(), Value::Bool(self.limited)),
312            (
313                "content_truncated".to_string(),
314                Value::Bool(self.content_truncated),
315            ),
316            (
317                "output_truncated".to_string(),
318                Value::Bool(self.output_truncated),
319            ),
320        ]))
321    }
322}