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.

Bắt đầu bằng cách xem lại tài liệu SDK cho session.usage_info, assistant.usage, session.idle và các sự kiện compaction hoặc vòng đời, sau đó so sánh các bề mặt đó với các lệnh /context và /usage của CLI. Công việc được xem là hoàn tất khi SDK ghi lại các API ổn định theo yêu cầu cho ngữ cảnh và mức sử dụng, giải thích việc duy trì sự kiện và hành vi tiếp tục, đồng thời định nghĩa các schema của những sự kiện vòng đời liên quan.