SDK context budgets, cursor-chain efficiency, and MCP mutation parity

Merged
UN
3mo ago
+1793-210

Summary

This broad SDK and CLI delivery makes project management = context management enforceable across the agent-facing read and mutation surfaces.

  • exposes token-budget controls for list, get, and search across CLI, SDK contracts, cursor semantics, and MCP tool schema 4.3.0
  • adds truthful feasibility and omission receipts, deterministic explanatory-string and row compaction, and a feasible budget-derived triage page
  • replaces repeated cursor-chain metadata with a fingerprint reference on continuation pages while preserving cursor integrity
  • aligns raw SDK and MCP mutation defaults with the CLI lean id/status/change-count envelope and keeps explicit fullChangedFields results
  • refreshes generated contracts, public SDK surface evidence, token baselines, documentation, changelog, and PM history

PM lineage

  • pm-awe3t6 — closed: CLI and MCP mutation-envelope parity
  • pm-7hbfch — delivered cross-surface controls; retained open for current-scale structural negative-control gate
  • pm-yekkvt — delivered truthful feasible receipts; retained open for dual-scale calibration gate
  • pm-sf31yl — delivered continuation compaction and paging; retained open for current-scale full-walk gate

Verification

  • pnpm release:gates: all local gates passed; hosted analysis deferred until this pushed SHA exists
  • 6,631 tests passed
  • coverage: 100% statements, branches, functions, and lines
  • token-budget gate: 28 surfaces plus unbounded and infeasible-declaration negative controls
  • packed npx smoke: 15 packages
  • package-first dogfood: 88 commands
  • isolated npm and Bun installs resolved their own packed binaries and exercised lean mutation plus bounded read receipts
  • pm health and history-drift validation: clean
  • dependency audit and GitHub Dependabot, code-scanning, and secret-scanning inventories: zero open alerts

Summary by cubic

Enforces context token budgets across CLI, SDK, and MCP with budget‑derived paging, truthful receipts, and cursor-chain amortization. Aligns MCP/SDK mutation defaults with the CLI’s lean envelope and tightens docs/tests to enforce it.

  • New Features

    • Added --token-budget to list/get/search; SDK and MCP expose tokenBudget (alias --token_budget) and bump tool schema to 4.3.0.
    • Receipts now include declaration_feasible, result_omitted, and budget_row_compaction; page sizes derive from the remaining budget.
    • Continuation pages reference cursor-chain metadata by fingerprint to cut repetition while preserving cursor integrity.
    • MCP/SDK mutations default to lean id, status, changed_field_count; pass fullChangedFields=true for full deltas, or idOnly=true for IDs only.

  • Bug Fixes

    • Validate measured output independently of receipt claims; over-budget reads fall back to receipt-only without stale counts or cursors.
    • Normalize --token-budget/--token_budget handling across CLI/SDK/MCP and scope tokenBudget parameter descriptions correctly.
    • Preserve useful rows via batch row compaction so at least one row survives before omission.
    • Enforce lean MCP envelope in smoke tests and propagate idOnly through aggregated append; include the SDK token‑budget usage error in the generated catalog.
    • Reconcile review evidence in docs by removing non-discriminating compaction assertions and noting remaining cursor-chain acceptance as open work.

Summary by Sourcery

Enforce context token budgets and truthful receipts across CLI, SDK, and MCP, while reducing cursor-chain overhead and aligning mutation envelopes with the CLI’s lean defaults.

New Features:

  • Expose token-budget controls for context, list, get, next, and search intents over CLI flags, SDK contracts, cursor semantics, and MCP tool parameters.
  • Introduce declaration feasibility and result omission markers in intent receipts, plus a budget-based triage page and row-compaction degradation tier.
  • Add continuation contracts that reference cursor-chain metadata by fingerprint so subsequent pages carry only advancing rows and cursors.

Bug Fixes:

  • Align MCP mutation result envelopes with the CLI default by returning lean id/status/changed_field_count unless fullChangedFields or idOnly is explicitly requested.
  • Correct intent receipts to treat infeasible declarations as omitted results, marking within-budget only for delivered projections.
  • Adjust recovery guidance for oversized positional reads to recommend increasing token budgets or narrowing requests instead of re-running unprojected commands.

Enhancements:

  • Derive default list, search, and context page sizes and activity limits from the effective token budget to keep intent declarations feasible on large trackers.
  • Add deterministic row-compaction logic that trims root collections while preserving at least one useful row before falling back to receipt-only envelopes.
  • Collapse invariant metadata from continuation pages and verify cursor pagination contracts in tests.
  • Extend the token-budget release gate to cover intent surfaces, validate feasible receipts, and normalize fixture IDs in recorded budgets.

Build:

  • Update token-budget manifests and agent token-surface baselines to reflect new intents, budgets, and measurement corpus entries.

Documentation:

  • Refresh output projection and command documentation to describe token-budget-derived paging, feasibility and omission flags, cursor continuation contracts, and MCP mutation envelope parity with the CLI.

Tests:

  • Add unit, integration, and MCP-specific tests for intent token-budget derivation, receipt feasibility semantics, cursor continuation metadata, token-budget gate negative controls, and MCP mutation envelope parity.