feat: Wire BudgetEngine into CLI for token-aware robot output #7

New Issue

2026-04-24T03:04:51+02:00

root commented

2026-04-24 03:04:51 +02:00

Problem Statement

The BudgetEngine module (crates/terraphim_agent/src/robot/budget.rs, ~13 KB) is fully implemented — counting tokens, trimming results, enforcing --max-content-length and field-mode selection — but it has zero call sites outside the robot/ module. Task 1.5 of the Phase 1 spec remains unmet: users cannot pass --max-tokens, --max-results, --max-content-length, or --fields on the search command, so robot output is unbounded and unsuitable for agent-to-agent budgets.

Current State

BudgetEngine, BudgetedResults, and the field-mode enum (full/summary/minimal/custom) are exported from robot/mod.rs and lib.rs.
grep confirms no callers in repl/, bin/, or cli.rs — the engine is dead code.
Robot mode search currently serialises full result bodies with no trimming or token accounting.

Acceptance Criteria

search subcommand (REPL and CLI) accepts --max-tokens <N>, --max-results <N>, --max-content-length <N>, --fields <mode> flags.
--fields accepts full|summary|minimal|custom:<comma-list> and maps to the existing field-mode enum.
When any budget flag is present, results are routed through BudgetEngine::apply() before serialisation.
Robot JSON output includes a budget block with tokens_used, tokens_budget, results_returned, results_trimmed, content_truncated: bool.
Default behaviour (no flags) is unchanged — no budget applied, full bodies returned.
Budget violations return exit code 2 (soft-limit) matching the existing robot exit-code taxonomy.
cargo test -p terraphim_agent --features repl-full passes.
cargo clippy -p terraphim_agent --features repl-full -- -D warnings passes.

Proposed Approach

Extend the search clap struct in crates/terraphim_agent/src/repl/commands.rs with the four new optional flags, gated behind the existing robot feature.
In ReplHandler::handle_search (repl/handler.rs), when any budget flag is set, build a BudgetConfig and pass the raw result set through BudgetEngine::apply() before the formatter call.
Update robot/output.rs RobotResponse to carry an optional budget: Option<BudgetReport> field.
Map BudgetEngine::Error::OverBudget to ExitCode::SoftLimit in the CLI dispatcher.
Add a unit test in robot/budget.rs for the new CLI path and a snapshot test for the JSON shape.

Dependencies

None — BudgetEngine API is already stable.

Verification

cargo build -p terraphim_agent --features repl-full --release
./target/release/terraphim-agent search "rust async" --robot --format json --max-tokens 500
./target/release/terraphim-agent search "rust async" --robot --format json --fields summary --max-results 5
cargo test -p terraphim_agent --features repl-full robot::budget
cargo clippy -p terraphim_agent --features repl-full -- -D warnings

Expect JSON to contain the budget block; verify tokens_used <= 500 and results are truncated accordingly.

Scope

~200 LOC across repl/commands.rs, repl/handler.rs, robot/output.rs, robot/budget.rs. Single PR.

Upstream: Implements Task 1.5 of docs/specifications/terraphim-agent-session-search-tasks.md for terraphim/terraphim-ai.

## Problem Statement The `BudgetEngine` module (`crates/terraphim_agent/src/robot/budget.rs`, ~13 KB) is fully implemented — counting tokens, trimming results, enforcing `--max-content-length` and field-mode selection — but it has zero call sites outside the `robot/` module. Task 1.5 of the Phase 1 spec remains unmet: users cannot pass `--max-tokens`, `--max-results`, `--max-content-length`, or `--fields` on the `search` command, so robot output is unbounded and unsuitable for agent-to-agent budgets. ## Current State - `BudgetEngine`, `BudgetedResults`, and the field-mode enum (full/summary/minimal/custom) are exported from `robot/mod.rs` and `lib.rs`. - `grep` confirms no callers in `repl/`, `bin/`, or `cli.rs` — the engine is dead code. - Robot mode search currently serialises full result bodies with no trimming or token accounting. ## Acceptance Criteria - [ ] `search` subcommand (REPL and CLI) accepts `--max-tokens <N>`, `--max-results <N>`, `--max-content-length <N>`, `--fields <mode>` flags. - [ ] `--fields` accepts `full|summary|minimal|custom:<comma-list>` and maps to the existing field-mode enum. - [ ] When any budget flag is present, results are routed through `BudgetEngine::apply()` before serialisation. - [ ] Robot JSON output includes a `budget` block with `tokens_used`, `tokens_budget`, `results_returned`, `results_trimmed`, `content_truncated: bool`. - [ ] Default behaviour (no flags) is unchanged — no budget applied, full bodies returned. - [ ] Budget violations return exit code `2` (soft-limit) matching the existing robot exit-code taxonomy. - [ ] `cargo test -p terraphim_agent --features repl-full` passes. - [ ] `cargo clippy -p terraphim_agent --features repl-full -- -D warnings` passes. ## Proposed Approach 1. Extend the `search` clap struct in `crates/terraphim_agent/src/repl/commands.rs` with the four new optional flags, gated behind the existing robot feature. 2. In `ReplHandler::handle_search` (`repl/handler.rs`), when any budget flag is set, build a `BudgetConfig` and pass the raw result set through `BudgetEngine::apply()` before the formatter call. 3. Update `robot/output.rs` `RobotResponse` to carry an optional `budget: Option<BudgetReport>` field. 4. Map `BudgetEngine::Error::OverBudget` to `ExitCode::SoftLimit` in the CLI dispatcher. 5. Add a unit test in `robot/budget.rs` for the new CLI path and a snapshot test for the JSON shape. ## Dependencies None — BudgetEngine API is already stable. ## Verification ```bash cargo build -p terraphim_agent --features repl-full --release ./target/release/terraphim-agent search "rust async" --robot --format json --max-tokens 500 ./target/release/terraphim-agent search "rust async" --robot --format json --fields summary --max-results 5 cargo test -p terraphim_agent --features repl-full robot::budget cargo clippy -p terraphim_agent --features repl-full -- -D warnings ``` Expect JSON to contain the `budget` block; verify `tokens_used <= 500` and results are truncated accordingly. ## Scope ~200 LOC across `repl/commands.rs`, `repl/handler.rs`, `robot/output.rs`, `robot/budget.rs`. Single PR. Upstream: Implements Task 1.5 of `docs/specifications/terraphim-agent-session-search-tasks.md` for terraphim/terraphim-ai.

product-owner referenced this issue

2026-04-24 05:01:22 +02:00

feat: Route REPL command output through machine-readable formatter (Phase 1 Task 1.4.1 and 1.4.3) #10

product-owner referenced this issue

2026-04-24 05:01:25 +02:00

feat: Route REPL command output through machine-readable formatter (Phase 1 Task 1.4.1 and 1.4.3) #11

root referenced this issue

2026-04-27 13:05:00 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35

product-owner referenced this issue

2026-05-07 03:03:12 +02:00

feat: wire ExitCode into main() return for f1.2 robot exit code contract #35