Add docs/GENERATOR_METADATA.md GetCascadeTrajectoryGeneratorMetadata RPC for context token usage

[Zen0-99]

What

Documents the GetCascadeTrajectoryGeneratorMetadata RPC, which is the endpoint the IDE uses to populate the context-usage indicator (e.g. \63% (125K / 200K)) shown in the Cascade UI.

This RPC is not covered in the existing CASCADE_PROTOCOL.md or WINDSURF_API_SPEC.md. The trajectory steps endpoint (GetCascadeTrajectorySteps) returns content only token counts live in this separate metadata stream.

Key findings

• Token usage chain: \CortexStepGeneratorMetadata\ \ChatModelMetadata\ (field 4 \usage) \ModelUsageStats.input_tokens\ (field 2)
• Numerator: \ModelUsageStats.input_tokens\ the actual context tokens consumed per LLM invocation
• Denominator: \IntentToolConfig.max_context_tokens\ per-model max context window (not in the generator metadata itself)
• Protocol: works with both gRPC-web framing and Buf Connect-RPC (\�pplication/proto)
• Pagination: offset-based, same pattern as \GetCascadeTrajectorySteps\

Schema included

Full field tables for:

• \CortexStepGeneratorMetadata\
• \ChatModelMetadata\
• \ModelUsageStats\
• \IntentToolConfig\

Verification

Tested with a simple message \input_tokens=1719\ for a trivial prompt, consistent with system prompt + context overhead.

Summary by CodeRabbit

• Documentation
  • Added a guide for polling generator metadata alongside trajectory steps to obtain exact per-LLM invocation token-usage details.
  • Documented the request/response structure, pagination via metadata offsets, and the relationship between step-level metadata and model usage stats.
  • Clarified how the IDE context-usage indicator is derived and what determines numerator/denominator values.
  • Included Connect-RPC protocol notes, a verification example, and instructions for finding the relevant protobuf schema in the extension bundle.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5d889a66-5078-4bb7-a98a-ba23ee8ec129

📥 Commits

Reviewing files that changed from the base of the PR and between b345c5b and 7bf6ccb.

📒 Files selected for processing (1)

• docs/GENERATOR_METADATA.md

✅ Files skipped from review due to trivial changes (1)

• docs/GENERATOR_METADATA.md

---

📝 Walkthrough

Walkthrough

Adds a new documentation file describing the GetCascadeTrajectoryGeneratorMetadata RPC, its request/response schema, token-usage chain, context-usage calculation, and Connect-RPC invocation details.

Changes

Generator Metadata Documentation

Layer / File(s)	Summary
Endpoint overview and polling flow docs/GENERATOR_METADATA.md	Documents the GetCascadeTrajectoryGeneratorMetadata RPC, its relation to GetCascadeTrajectorySteps, request/response fields (cascade_id, generator_metadata_offset), and the polling/offset correlation flow.
Token-usage schemas and calculation docs/GENERATOR_METADATA.md	Documents CortexStepGeneratorMetadata and ChatModelMetadata schemas, the ModelUsageStats token chain, numerator (input_tokens) selection logic, and denominator (max_context_tokens) sourcing from IntentToolConfig with percentage calculation.
Protocol notes and verification docs/GENERATOR_METADATA.md	Documents Connect-RPC protobuf framing, required headers, URL pattern, a verification example, and instructions for locating the schema in extension.js.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is specific and accurately reflects the new documentation for the GetCascadeTrajectoryGeneratorMetadata RPC and context token usage.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/GENERATOR_METADATA.md`:
- Around line 23-29: The markdown fence in GENERATOR_METADATA.md is missing a
language tag and is triggering MD040. Update this fence and the other bare code
fences in the document to use an explicit language such as text or bash, and
keep the content unchanged. Use the existing fenced blocks around the cascade
flow examples as the places to update.
- Around line 149-151: The metadata paragraph is pointing readers to the wrong
source for per-model context limits; update the reference in the docs to use
GetCascadeModelConfigs and its max_tokens field instead of
GetUserStatus/cascade_model_config_data.client_model_configs[] in
GENERATOR_METADATA.md. Keep the guidance aligned with the existing model-catalog
terminology and mention the correct symbol names so readers can locate the
source of the per-model limit.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d6cb7eaf-e050-4e32-9877-6d4b55850959

📥 Commits

Reviewing files that changed from the base of the PR and between c331611 and b345c5b.

📒 Files selected for processing (1)

• docs/GENERATOR_METADATA.md