[gobby-cli-#769] feat: add token-budgeted gcode output

Author: joshwilhelmi

crates/gcode/contract/gcode.contract.json

@@ -369,6 +369,14 @@
           "allowed_values": [],
           "required": false,
           "repeatable": false
+        },
+        {
+          "name": "--token-budget",
+          "takes_value": true,
+          "value_name": "N",
+          "allowed_values": [],
+          "required": false,
+          "repeatable": false
         }
       ],
       "json_output_keys": [
@@ -897,6 +905,7 @@
         "name",
         "file_path",
         "line",
+        "confidence",
         "relation",
         "distance",
         "metadata",
@@ -941,6 +950,14 @@
           ],
           "required": false,
           "repeatable": false
+        },
+        {
+          "name": "--token-budget",
+          "takes_value": true,
+          "value_name": "N",
+          "allowed_values": [],
+          "required": false,
+          "repeatable": false
         }
       ],
       "json_output_keys": [
@@ -953,6 +970,7 @@
         "name",
         "file_path",
         "line",
+        "confidence",
         "relation",
         "distance",
         "metadata",
@@ -993,6 +1011,7 @@
         "name",
         "file_path",
         "line",
+        "confidence",
         "relation",
         "distance",
         "metadata",
@@ -1073,6 +1092,14 @@
           "required": false,
           "repeatable": false
         },
+        {
+          "name": "--token-budget",
+          "takes_value": true,
+          "value_name": "N",
+          "allowed_values": [],
+          "required": false,
+          "repeatable": false
+        },
         {
           "name": "--format",
           "takes_value": true,
@@ -1095,6 +1122,7 @@
         "name",
         "file_path",
         "line",
+        "confidence",
         "relation",
         "distance",
         "metadata",

crates/gcode/src/cli.rs

@@ -200,6 +200,9 @@ pub(crate) enum Command {
         /// Filter by source language (e.g. rust, python, css)
         #[arg(long)]
         language: Option<String>,
+        /// Trim returned rows to an approximate token budget
+        #[arg(long, value_parser = positive_usize)]
+        token_budget: Option<usize>,
     },
     /// Exact-first symbol/name search with deterministic ranking
     SearchSymbol {
@@ -362,6 +365,9 @@ pub(crate) enum Command {
         /// Skip first N results (for pagination)
         #[arg(long, default_value = "0")]
         offset: usize,
+        /// Trim returned rows to an approximate token budget
+        #[arg(long, value_parser = positive_usize)]
+        token_budget: Option<usize>,
     },
     /// Show import graph for a file [requires graph backend]
     Imports { file: String },
@@ -383,6 +389,9 @@ pub(crate) enum Command {
         target: String,
         #[arg(long, default_value = "3")]
         depth: usize,
+        /// Trim returned rows to an approximate token budget
+        #[arg(long, value_parser = positive_usize)]
+        token_budget: Option<usize>,
     },
 
     // ── Project Management ───────────────────────────────────────────

crates/gcode/src/cli/tests/search.rs

@@ -60,6 +60,19 @@ fn test_parse_search_language_filters() {
     }
 }
 
+#[test]
+fn test_parse_search_token_budget() {
+    let cli = Cli::try_parse_from(["gcode", "search", "outline", "--token-budget", "120"])
+        .expect("search --token-budget parses");
+
+    match cli.command {
+        Command::Search { token_budget, .. } => {
+            assert_eq!(token_budget, Some(120));
+        }
+        _ => panic!("expected search command"),
+    }
+}
+
 #[test]
 fn test_parse_search_positional_paths() {
     let cli = Cli::try_parse_from([

crates/gcode/src/cli/tests/top_level.rs

@@ -45,15 +45,28 @@ fn test_parse_usages_remains_top_level() {
             symbol_name,
             limit,
             offset,
+            token_budget,
         } => {
             assert_eq!(symbol_name, "DatabasePool");
             assert_eq!(limit, 10);
             assert_eq!(offset, 0);
+            assert_eq!(token_budget, None);
         }
         _ => panic!("expected top-level usages command"),
     }
 }
 
+#[test]
+fn test_parse_usages_token_budget() {
+    let cli = Cli::try_parse_from(["gcode", "usages", "DatabasePool", "--token-budget", "80"])
+        .expect("usages --token-budget parses");
+
+    match cli.command {
+        Command::Usages { token_budget, .. } => assert_eq!(token_budget, Some(80)),
+        _ => panic!("expected top-level usages command"),
+    }
+}
+
 #[test]
 fn test_parse_imports_remains_top_level() {
     let cli = Cli::try_parse_from(["gcode", "imports", "src/auth.ts"]).expect("imports parses");
@@ -89,14 +102,36 @@ fn test_parse_blast_radius_remains_top_level() {
         Cli::try_parse_from(["gcode", "blast-radius", "handleAuth"]).expect("blast-radius parses");
 
     match cli.command {
-        Command::BlastRadius { target, depth } => {
+        Command::BlastRadius {
+            target,
+            depth,
+            token_budget,
+        } => {
             assert_eq!(target, "handleAuth");
             assert_eq!(depth, 3);
+            assert_eq!(token_budget, None);
         }
         _ => panic!("expected top-level blast-radius command"),
     }
 }
 
+#[test]
+fn test_parse_blast_radius_token_budget() {
+    let cli = Cli::try_parse_from([
+        "gcode",
+        "blast-radius",
+        "handleAuth",
+        "--token-budget",
+        "100",
+    ])
+    .expect("blast-radius --token-budget parses");
+
+    match cli.command {
+        Command::BlastRadius { token_budget, .. } => assert_eq!(token_budget, Some(100)),
+        _ => panic!("expected top-level blast-radius command"),
+    }
+}
+
 #[test]
 fn top_level_help_includes_agent_task_examples() {
     let help = Cli::command().render_help().to_string();

crates/gcode/src/commands/graph/reads.rs

@@ -1,5 +1,6 @@
 use std::collections::BTreeMap;
 
+use crate::commands::token_budget;
 use crate::config::Context;
 use crate::db;
 use crate::graph::code_graph;
@@ -10,6 +11,10 @@ use serde::Serialize;
 
 const GRAPH_BACKEND_HINT: &str =
     "Graph commands require a configured FalkorDB graph backend and synced graph projection.";
+const USAGES_TOKEN_BUDGET_REFINE_HINT: &str =
+    "`--limit`, `--offset`, or a more specific symbol query";
+const BLAST_RADIUS_TOKEN_BUDGET_REFINE_HINT: &str =
+    "`--depth`, a more specific symbol query, or a symbol UUID";
 
 fn hint_for(ctx: &Context) -> Option<String> {
     if ctx.falkordb.is_none() {
@@ -37,6 +42,12 @@ fn print_graph_hint_text(ctx: &Context, error: Option<&anyhow::Error>) {
     }
 }
 
+fn print_hint_text(hint: Option<&str>) {
+    if let Some(hint) = hint {
+        eprintln!("Hint: {hint}");
+    }
+}
+
 fn graph_read_unavailable(error: &anyhow::Error) -> bool {
     matches!(
         error.downcast_ref::<code_graph::GraphReadError>(),
@@ -429,6 +440,7 @@ pub fn usages(
     symbol_name: &str,
     limit: usize,
     offset: usize,
+    token_budget: Option<usize>,
     format: Format,
 ) -> anyhow::Result<()> {
     let Some((symbol, total, results)) = read_paged_symbol_graph_results(
@@ -443,6 +455,15 @@ pub fn usages(
     else {
         return Ok(());
     };
+    let unbudgeted_result_count = results.len();
+    let budgeted = token_budget::trim_results(
+        results,
+        token_budget,
+        USAGES_TOKEN_BUDGET_REFINE_HINT,
+        |result| format_usage_result_line(result, &symbol.display_name),
+    );
+    let results = budgeted.results;
+    let hint = token_budget::combine_hints(hint_for(ctx), budgeted.hint);
 
     match format {
         Format::Json => output::print_json(&PagedResponse {
@@ -451,18 +472,21 @@ pub fn usages(
             offset,
             limit,
             results,
-            hint: hint_for(ctx),
+            hint,
         }),
         Format::Text => {
-            if results.is_empty() && offset == 0 {
+            if unbudgeted_result_count == 0 && offset == 0 {
                 output::print_text(&format!("No usages found for '{}'", symbol.display_name))?;
                 print_graph_hint_text(ctx, None);
-            } else if results.is_empty() {
+            } else if unbudgeted_result_count == 0 {
                 eprintln!("No usages at offset {offset} (total {total})");
+            } else if results.is_empty() {
+                print_hint_text(hint.as_deref());
             } else {
                 output::print_text(&format_grouped_graph_results(&results, |r| {
                     format_usage_result_line(r, &symbol.display_name)
                 }))?;
+                print_hint_text(hint.as_deref());
                 if total > offset + results.len() {
                     eprintln!(
                         "-- {} of {} results (use --offset {} for more)",
@@ -541,6 +565,7 @@ pub fn blast_radius(
     ctx: &Context,
     target: &str,
     depth: usize,
+    token_budget: Option<usize>,
     format: Format,
 ) -> anyhow::Result<()> {
     let Some(()) =
@@ -560,26 +585,37 @@ pub fn blast_radius(
         return Ok(());
     };
     let total = results.len();
+    let budgeted = token_budget::trim_results(
+        results,
+        token_budget,
+        BLAST_RADIUS_TOKEN_BUDGET_REFINE_HINT,
+        format_blast_radius_result_line,
+    );
+    let results = budgeted.results;
+    let hint = token_budget::combine_hints(hint_for(ctx), budgeted.hint);
     match format {
         Format::Json => output::print_json(&PagedResponse {
             project_id: ctx.project_id.clone(),
             total,
             offset: 0,
             limit: total,
             results,
-            hint: hint_for(ctx),
+            hint,
         }),
         Format::Text => {
-            if results.is_empty() {
+            if total == 0 {
                 output::print_text(&format!(
                     "No blast radius found for '{}'",
                     symbol.display_name
                 ))?;
                 print_graph_hint_text(ctx, None);
+            } else if results.is_empty() {
+                print_hint_text(hint.as_deref());
             } else {
                 output::print_text(&format_grouped_graph_results(&results, |r| {
                     format_blast_radius_result_line(r)
                 }))?;
+                print_hint_text(hint.as_deref());
             }
             Ok(())
         }

crates/gcode/src/commands/graph/tests.rs

@@ -8,6 +8,7 @@ use super::reads::{
     format_symbol_path_text, format_usage_result_line,
 };
 use super::{imports, report};
+use crate::commands::token_budget;
 use crate::config::Context;
 use crate::graph::code_graph::{self, GraphLifecycleAction, GraphLifecycleOutput};
 use crate::models::{
@@ -123,6 +124,59 @@ fn graph_read_text_lines_surface_confidence_labels() {
     );
 }
 
+#[test]
+fn graph_read_token_budget_uses_rendered_rows() {
+    let first = GraphResult {
+        id: "sym-1".to_string(),
+        name: "run".to_string(),
+        file_path: "src/lib.rs".to_string(),
+        line: 12,
+        confidence: ProjectionProvenance::Extracted,
+        relation: Some("CALLS".to_string()),
+        distance: Some(1),
+        metadata: None,
+    };
+    let second = GraphResult {
+        id: "sym-2".to_string(),
+        name: "run_more".to_string(),
+        file_path: "src/lib.rs".to_string(),
+        line: 18,
+        confidence: ProjectionProvenance::Inferred,
+        relation: Some("CALLS".to_string()),
+        distance: Some(2),
+        metadata: None,
+    };
+    let budget = token_budget::estimate_tokens(&format_usage_result_line(&first, "main"));
+
+    let trimmed = token_budget::trim_results(
+        vec![first.clone(), second.clone()],
+        Some(budget),
+        "`--limit` or `--offset`",
+        |result| format_usage_result_line(result, "main"),
+    );
+
+    assert_eq!(trimmed.results.len(), 1);
+    assert_eq!(trimmed.results[0].id, first.id);
+    assert!(trimmed.hint.expect("usage budget hint").contains("1 of 2"));
+
+    let blast_budget = token_budget::estimate_tokens(&format_blast_radius_result_line(&first));
+    let trimmed_blast = token_budget::trim_results(
+        vec![first.clone(), second],
+        Some(blast_budget),
+        "`--depth`",
+        format_blast_radius_result_line,
+    );
+
+    assert_eq!(trimmed_blast.results.len(), 1);
+    assert_eq!(trimmed_blast.results[0].id, first.id);
+    assert!(
+        trimmed_blast
+            .hint
+            .expect("blast budget hint")
+            .contains("refine with `--depth`")
+    );
+}
+
 #[test]
 fn graph_path_text_prints_ordered_chain_with_locations() {
     let path = vec![

crates/gcode/src/commands/mod.rs

@@ -10,4 +10,5 @@ pub mod setup;
 pub mod status;
 pub mod symbol_at;
 pub mod symbols;
+pub(crate) mod token_budget;
 pub mod vector;