feat(antigravity): native token counts via title-slot tee

[peyton-alt]

https://entire.io/gh/entireio/cli/trails/507

Summary

Follow-up to #1287 (which intentionally deferred token counts). Adds native per-checkpoint token usage for the Antigravity (agy) agent, surfaced in committed checkpoint metadata exactly like every other agent — so the entire.io UI displays agy tokens with zero web-side changes.

Why this approach: agy exposes token usage only via the JSON payload piped to its title/statusline script on every agent state change (context_window.{total_input_tokens, total_output_tokens, current_usage{...}}, cumulative per conversation). It is absent from transcripts, hook payloads, logs, and the protobuf session state. The statusline schema is the single source — verified against real agy transcripts and the published docs.

How it works (end-to-end):

1. title-tee shim — entire hooks antigravity title-tee [--wrap '<original>'] is installed into agy's global ~/.gemini/antigravity-cli/settings.json title slot. On every state change it tees the JSON to a per-conversation append-only JSONL store (<cache>/entire/antigravity/status/<conversation_id>.jsonl) and pipes through to any pre-existing user title command. We use the title slot (not statusLine) — same payload, lower blast radius.
2. OutOfBandTokenSource capability — new interface for agents whose token data lives outside the transcript. Built-in only (external agents excluded).
3. Delta computation — baseline snapshot captured at TurnStart (stored in PrePromptState), delta = latest cumulative totals − baseline at TurnEnd (the Codex cumulative-minus-baseline pattern, sourced from the tee file). Input/output exact; cache/api-call counts best-effort sampled.
4. Additive lifecycle fallback — only fires when transcript-based calc returns nil; strict no-op for claude-code/gemini/codex/etc.
5. Condensation fallback — accumulated SessionState.TokenUsage copied into committed metadata for non-TokenCalculator agents.
6. Doctor check — warns when agy hooks are installed but the title-tee isn't configured.

Install/uninstall semantics: install wraps + preserves any existing user title command (self-describing via --wrap); uninstall (agent-removal only, never per-repo disable since the slot is global) restores the original or clears a bare tee, and leaves foreign/user-wrapped commands untouched.

Notable properties

• Safe in agy's render path: the shim never exits non-zero and never writes noise to stdout (stdout is the window title). Measured ~36ms warm/invocation (≤50ms budget); ~55µs/append on a 500-line file.
• Privacy: snapshot store holds only token counts, never prompts/file contents. All new logging is metadata-only.
• Degrades to nil, never errors when agy lacks the title hook or the user removes the config.

Known v1 limitations (documented in code)

• Resumed conversations (agy --continue) whose title-tee hasn't fired before the first TurnStart over-count that one turn by the prior cumulative total.
• Cache-creation/cache-read/api-call counts are best-effort (snapshot sampling); input/output totals are exact.

Test Plan

• Unit: snapshot store (dedup, garbage tolerance, prune), title installer (wrap/unwrap/idempotent/round-trip incl. embedded single quotes), delta math (baseline, nil-baseline, clamp-on-backwards, unparseable-baseline degradation), capability gating.
• Integration: TestAntigravity_TokenUsageInCheckpointMetadata — seeds snapshots, drives the real hook lifecycle, commits, asserts token_usage 3500/300 in both per-session metadata.json and the CheckpointSummary aggregate on entire/checkpoints/v1.
• Doctor: configured/not-configured/not-installed cases.
• mise run check green (unit -race + integration + Vogon canary 58/58). Vogon unaffected (degrades to nil).
• Shim latency re-measured against final binary (~36ms warm).

🤖 Generated with Claude Code

---

Note

Medium Risk
Modifies global Antigravity user config and checkpoint token metadata paths; failures degrade to missing counts rather than blocking hooks, but misconfigured title-tee affects all agy workspaces on the machine.

Overview
Adds native per-checkpoint token usage for Antigravity, which only exposes context_window totals via the global title command JSON—not transcripts or lifecycle hooks.

A title-tee shim (entire hooks antigravity title-tee) is installed into ~/.gemini/antigravity-cli/settings.json, tees state JSON into a per-conversation JSONL snapshot cache, and optionally chains the user’s original title command via --wrap. Hook install always attempts title-tee setup (even when repo hooks are already idempotent) so upgrades can repair a missing global slot.

New OutOfBandTokenSource captures a baseline at turn start (PrePromptState.token_baseline) and computes turn deltas at turn end when transcript token calc is nil; condensation copies accumulated session token usage into committed metadata for OOB agents only. entire doctor warns when repo Antigravity hooks exist but title-tee is not configured; title-tee is removed on agent removal, not per-repo disable.

^{Reviewed by Cursor Bugbot for commit acad86f. Configure here.}

[Copilot]

Pull request overview

Adds native, per-checkpoint token usage support for the Antigravity (agy) agent by capturing token totals from agy’s title/statusline JSON payload out-of-band, computing per-turn deltas (cumulative − baseline), and ensuring those values flow through SaveStep → session state → condensation → committed checkpoint metadata so the entire.io UI can display token counts without web changes.

Changes:

• Introduces an Antigravity title-tee shim command and global settings installer/uninstaller to persist token snapshot JSONL per conversation.
• Adds a built-in-only OutOfBandTokenSource capability plus lifecycle baseline/delta handling to produce checkpoint-scoped token usage when transcripts lack token data.
• Extends condensation + doctor + tests (unit + integration) to propagate and validate token usage in committed metadata.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cmd/entire/cli/strategy/manual_commit_condensation.go	Condensation fallback to persist session-state token usage when transcript recompute yields none (non-token-calculator agents).
cmd/entire/cli/strategy/manual_commit_condensation_test.go	Unit test ensuring out-of-band session token usage reaches committed checkpoint metadata.
cmd/entire/cli/state.go	Stores an opaque token baseline in PrePromptState for out-of-band token agents.
cmd/entire/cli/setup.go	Uninstalls Antigravity global title-tee only on agent removal (not per-repo disable).
cmd/entire/cli/lifecycle.go	Adds out-of-band token computation fallback at TurnEnd when transcript-based calc returns nil.
cmd/entire/cli/integration_test/antigravity_test.go	Integration test asserting token usage appears in both per-session metadata and checkpoint summary.
cmd/entire/cli/hooks_cmd.go	Adds the hidden entire hooks antigravity title-tee subcommand under Antigravity hooks.
cmd/entire/cli/hooks_antigravity_title.go	Implements the title-tee shim that appends snapshots and optionally pipes through a wrapped title command.
cmd/entire/cli/hooks_antigravity_title_test.go	Tests that title-tee is silent, writes snapshots, and wrap passthrough works.
cmd/entire/cli/doctor.go	Adds a doctor check warning when repo hooks exist but the global title-tee isn’t configured.
cmd/entire/cli/doctor_test.go	Tests the doctor check behavior for configured / missing / not-installed cases.
cmd/entire/cli/agent/capabilities.go	Adds AsOutOfBandTokenSource capability helper (built-in only).
cmd/entire/cli/agent/capabilities_test.go	Tests new capability gating behavior for out-of-band token sources.
cmd/entire/cli/agent/antigravity/title_install.go	Installs/uninstalls the global settings.json title command with optional --wrap preservation.
cmd/entire/cli/agent/antigravity/title_install_test.go	Unit tests for install/uninstall idempotency and wrap round-trips (incl. quotes).
cmd/entire/cli/agent/antigravity/statusline.go	Snapshot store + baseline + delta implementation for Antigravity out-of-band token usage.
cmd/entire/cli/agent/antigravity/statusline_test.go	Unit tests + benchmark for snapshot writing, dedup, pruning, and delta math.
cmd/entire/cli/agent/antigravity/hooks.go	Hook install now best-effort configures the global title-tee during repo hook setup.
cmd/entire/cli/agent/antigravity/hooks_test.go	Updates tests to isolate global config mutation via env override.
cmd/entire/cli/agent/antigravity/antigravity.go	Declares Antigravity implements OutOfBandTokenSource.
cmd/entire/cli/agent/antigravity/antigravity_test.go	Ensures tests don’t touch real global config by setting config-dir env override.
cmd/entire/cli/agent/agent.go	Adds the OutOfBandTokenSource interface definition and lifecycle contract documentation.

[peyton-alt]

@BugBot review

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit acad86f. Configure here.}