feat(vgr): hand off escalated agentic runs

[gburachas]

Behind agentic_handoff, compact_handoff and local_turn_budget_seconds (all off by default): tell the capable tier once per user turn that it inherits unverified tool-using work, optionally condense the local history into a cache-stable digest, and escalate a user turn once its local wall-clock budget is spent.

What

Adds three optional controls for agentic escalation: a handoff note, history compaction, and a local wall-clock budget per user turn. All are disabled by default and exposed through the existing VGR TOML configuration.

Why

When the capable tier takes over, earlier tool activity and completion claims may still be unverified. The handoff makes that explicit. Compaction reduces the history sent repeatedly after escalation, while the turn budget limits time spent locally across model calls and client-side tool execution.

Notes for reviewers

Review this against #719. Start with hand_off and turn_budget_spent in crates/libsy/src/algorithms/vgr/runtime.rs, then read compact, digest, and Compactor::score in vgr/compaction.rs.

• Handoff: On the first escalation of a user turn containing tool activity, the capable tier receives a note asking it to check the environment and task requirements. When available, the rejected local final answer is included as a clipped, explicitly unchecked claim. Off mode skips the note.
• Compaction: Uses deterministic text extraction, with no summarizer call. It preserves messages through the first user task and replaces the following history with a digest attached to that task. Earlier tool steps receive short entries; the last three receive more detail. Later user text is limited to the last two text blocks, so the digest is intentionally lossy.
• Subsequent requests: Stores the digest and a fingerprint of the original message prefix in session state. The compactor runs before affinity routing and reapplies the same digest only when that prefix matches, preserving later messages. Changed histories pass through untouched; a new user turn clears the recorded compaction.
• Turn budget: Starts at the first request of a user turn and includes elapsed time between requests. It is checked before starting another local attempt, rather than interrupting an in-flight call. The existing per-request verification deadline remains separate.
• Existing APIs: Reuses has_new_user_turn, State.extra, the Classifier pipeline, and clip_mid. Request edits use append_note or drop_exact_replay so preserved provider payloads cannot bypass the rewritten content. TOML construction rejects compact_handoff without agentic_handoff.
• Tests: Cover sending the handoff once with the unchecked claim, skipping local generation when the budget is exhausted, identical condensed prefixes on follow-up requests, changed-history handling, and reset on a new user turn.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-881/
Built to branch gh-pages at 2026-09-30 19:27 UTC. Preview will be ready when the GitHub Pages deployment is complete.