Expose real-time context/usage metrics in the Copilot SDK

Summary

Today the Copilot CLI provides /context and /usage as first-class UX commands, but the SDK docs do not expose an equivalent stable API for apps to fetch the same information directly.

This makes it hard to build a UI that shows live session context pressure, token usage, and compaction status in real time or near-real time. The closest available surfaces appear to be streaming events like session.usage_info, assistant.usage, and compaction/session lifecycle events, but these are event-based and ephemeral rather than a documented queryable API.

Request

• Add a documented SDK method or session API for retrieving current context/window usage on demand.
• Add a documented session usage API for current/aggregate token and cost metrics.
• Clarify which usage events are ephemeral vs persisted and what is available after resume.
• Provide a stable event/schema contract for session.idle and related lifecycle events.

Why this matters

• Enables apps to render accurate live context bars and usage dashboards.
• Avoids relying on internal/undocumented event shapes.
• Makes Copilot SDK easier to integrate into production UIs.

Docs gap noted

• The SDK docs mention session.usage_info and assistant.usage, but there is no explicit “fetch current context usage now” API like the CLI’s /context command.
• session.idle appears to have inconsistent payload documentation across pages.

Start by reviewing the SDK documentation for session.usage_info, assistant.usage, session.idle, and compaction or lifecycle events, then compare those surfaces with the CLI’s /context and /usage commands. Done means the SDK documents stable on-demand context and usage APIs, explains event persistence and resume behavior, and defines the relevant lifecycle event schemas.