feat(output-budget): adaptive caps for trace, explore, and node

[SutuSebastian]

Summary

• Add resolveOutputBudget(file_count) in output-budget.ts with the same 500 / 5000 tier boundaries as resolveContextBudget.
• Wire adaptive snippet char caps and explore row limits into composeTraceResult, composeExploreResult, and composeNodeResult when budget_chars / row cap are omitted.
• Explicit budget_chars and rowLimit overrides remain unchanged.

Tier table (when omitted)

Files indexed	Snippet chars	Explore rows
≤500	15,000	500
≤5000	10,000	250
>5000	6,000	125

Test plan

• output-budget.test.ts — tier unit tests + DB-backed effective budget resolution
• trace-engine.test.ts — existing trace/explore/node tests pass
• bun run check green
• Roadmap marks adaptive output budgets shipped

Summary by CodeRabbit

• New Features

  • Output budgets now scale adaptively based on indexed file count, adjusting snippet character limits and explore row caps across small, medium, and large repositories.

• Tests

  • Added comprehensive test coverage for adaptive budget resolution logic across varying repository sizes.

• Documentation

  • Updated architecture guide and roadmap to reflect adaptive output budget behavior.
  • Updated tool descriptions to document tiered row limits and adaptive snippet defaults.

• Chores

  • Added changeset entry documenting the adaptive output budgets feature.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4c557c5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/codemap	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Review limit reached

@SutuSebastian, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 30 minutes and 58 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: be337062-0ca5-40ff-8253-3136f1cd7064

📥 Commits

Reviewing files that changed from the base of the PR and between 3962094 and 4c557c5.

📒 Files selected for processing (11)

• .changeset/adaptive-output-budgets.md
• docs/architecture.md
• docs/roadmap.md
• src/application/mcp-server.test.ts
• src/application/mcp-server.ts
• src/application/output-budget.test.ts
• src/application/output-budget.ts
• src/application/trace-engine.test.ts
• src/application/trace-engine.ts
• templates/agent-content/mcp-instructions.md
• templates/agent-content/skill/10-recipes-context.md

📝 Walkthrough

Walkthrough

This PR implements adaptive output budgeting where snippet character limits and explore row caps scale dynamically based on indexed file count, replacing fixed compile-time defaults. The system is integrated into trace/explore/node composition and includes comprehensive test coverage and documentation updates.

Changes

Adaptive Output Budgets

Layer / File(s)	Summary
Adaptive budget resolution contract and implementation src/application/output-budget.ts	Introduces OutputBudget interface and resolveOutputBudget(fileCount) with tiered rules mapping file counts to snippet char budgets and explore row limits. Adds readIndexedFileCount(db) to query indexed files and helper functions resolveEffectiveSnippetBudget(db, budgetChars?) and resolveEffectiveExploreRowLimit(db, rowLimit?) that honor explicit overrides while computing adaptive defaults from file count.
Trace engine integration with adaptive budgets src/application/trace-engine.ts	Updates composeTraceResult, composeExploreResult, and composeNodeResult to call database-backed resolver functions instead of using fixed defaults. Removes local DEFAULT_EXPLORE_ROW_LIMIT constant and imports the new resolver helpers from output-budget.
Test coverage for budget resolution src/application/output-budget.test.ts	Adds filesystem and database harness with beforeEach/afterEach setup, seedFileCount(count) helper for seeding test file records, and test suites validating resolveOutputBudget tiers, resolveEffectiveSnippetBudget override handling and adaptive behavior, and resolveEffectiveExploreRowLimit override and adaptive scaling.
Documentation and user-facing updates src/application/mcp-server.ts, docs/architecture.md, docs/roadmap.md, templates/agent-content/skill/10-recipes-context.md, .changeset/adaptive-output-budgets.md	Updates tool descriptions to document adaptive defaults for budget_chars and explore row truncation (500 / 250 / 125). Revises architecture wiring, roadmap implementation status, recipe template behavior, and adds changeset entry.

Sequence Diagram

sequenceDiagram
  participant Client
  participant TraceEngine
  participant OutputBudget
  participant Database
  Client->>TraceEngine: explore(rowLimit?, budgetChars?)
  TraceEngine->>Database: open()
  TraceEngine->>OutputBudget: resolveEffectiveExploreRowLimit(db, rowLimit?)
  OutputBudget->>Database: readIndexedFileCount(db)
  Database-->>OutputBudget: indexed_file_count
  OutputBudget->>OutputBudget: resolveOutputBudget(file_count)
  OutputBudget-->>TraceEngine: adaptive_row_limit
  TraceEngine->>OutputBudget: resolveEffectiveSnippetBudget(db, budgetChars?)
  OutputBudget->>OutputBudget: resolveOutputBudget(file_count)
  OutputBudget-->>TraceEngine: adaptive_snippet_budget
  TraceEngine->>TraceEngine: compose explore result with caps
  TraceEngine-->>Client: truncated result

Loading

🎯 3 (Moderate) | ⏱️ ~25 minutes

A rabbit hops through the code with glee,
Adaptive budgets, now file-count-aware, you see!
Snippet caps scale with the repo's size,
No more fixed limits—just runtime surprise! 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: introducing adaptive caps (instead of fixed defaults) for the trace, explore, and node tools based on indexed file count.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/adaptive-output-budgets

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}