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}