Expand description
Agent-native payload shaping applied at the JSON serialization funnel. Agent-native payload shaping applied at the single JSON serialization funnel.
§Why this exists
ssh-cli emits structured JSON for fan-out commands (vps list,
health-check --all, exec --all, the SCP/SFTP batches, sftp ls). Without a
reduction surface the agent receives the whole envelope and has to shell out to
jaq to cut it down — which means the large payload is built, serialized, written
and then thrown away. The tokens are already spent by then.
Shaping therefore happens before serialization, inside
crate::json_wire::print_json_line, so the oversized envelope never reaches
stdout in the first place.
§Operation order is fixed
filter → sort → dedupe → limit → select → count-only →
truncate-content → max-output-bytes
The order matters: filtering before limiting keeps the first N matching records rather than filtering an arbitrary prefix, and selecting after sorting lets a run sort by a field it does not intend to emit.
§Cost when unused
crate::agent_shape::is_active short-circuits the whole path. When no shaping flag was passed the
caller serializes exactly as before, so the default path pays no
serde_json::to_value round-trip.
§Truncation is never silent
Any run that drops or shortens data reports it under the agent_shape key, so an
agent can tell “three hosts” apart from “three hosts shown out of ninety”.
Structs§
- Filter
- A single
--filterpredicate. - Shape
Config - Shaping options resolved from global CLI flags.