[li-xiu-qi]

Resolves #161

Problem

Issue #161 asks for a way to see what is consuming the current context window. The existing /usage view reports cumulative token and cost totals, but it does not show the composition of the request that will be sent next: instructions, tool definitions, and conversation are not separated, and there is no view of free space or the configured compaction reserve.

Changes

Add a read-only /context [all] command that reports the composition of the current request without starting a model turn.

• Group the report into instructions, tool definitions, and conversation.
• Split conversation into user input, AI answers, thinking, tool calls, tool output, compaction summaries, injected context, and other messages.
• Split tool definitions into built-in, MCP, extension, and SDK tools.
• Show used tokens, context window, percentage, free space after the compaction reserve, and the configured compaction reserve.
• Support /context all, or pressing a in the TUI panel, to expand individual skills, context files, and tools.
• Count token totals through the Step token-count endpoint. Step models use their own tokenizer; other providers borrow the Step 3.7 tokenizer (step-3.7-flash) so /context does not need a provider-specific counter. The command sends segmented payloads for instructions, tool definitions, the full conversation, and each conversation category; these are tokenizer requests, not model generations.
• Keep a local structural estimator as the fallback for offline use, missing Step auth, endpoint errors, rate limits, or any failed tokenizer segment. The report header shows either token-count API or estimated; there is no mixed mode, because a partial tokenizer response discards all provider counts and falls back to local estimates.
• Add an optional ExtensionCommandContext.getContextReportSnapshot() so commands can read the effective system prompt, base prompt options, registered tool catalog, MCP server names, active messages, context window, and reserve tokens without re-deriving them.
• Add reserveTokens to ContextUsage so extension consumers can see the configured compaction reserve, or zero when automatic compaction is disabled.
• Refactor skill prompt rendering to expose a single-skill formatter and allocate the shared skills-section overhead across individual skills.
• Document the new command and the new extension context snapshot.

Behavior and compatibility

• New user-visible command: /context [all].
• New optional extension API: ctx.getContextReportSnapshot() in command contexts. It returns undefined when the host does not provide a snapshot, so existing extension hosts remain source-compatible.
• ContextUsage gains an optional reserveTokens field. Existing consumers that read only tokens, contextWindow, and percent are unaffected.
• No configuration keys, environment variables, CLI arguments, provider responses, persisted sessions, RPC/SDK calls, or extension hooks are changed.
• No model-visible text, system prompt, tool description, reminder, or tool output is changed. The report is user-visible terminal output only.
• /context may call the Step token-count endpoint, including for non-Step active models. It never calls a chat, responses, or messages generation endpoint, and it never mutates session state.
• The report is an estimate of the current request structure. It is not cumulative billing or cache statistics; /usage remains the owner of those views.

Validation

Run from the repository root on Windows with Node.js v24.21.0:

• pnpm run check — passed. This includes Biome, TypeScript, dependency and boundary checks, and the browser smoke check.
• pnpm exec vitest --run test/context-report.test.ts test/token-count.test.ts in packages/coding-agent — passed, 20 tests, including a regression for nonnegative instruction subtotals after per-section rounding.
• pnpm exec vitest --run test/skills.test.ts in packages/coding-agent — passed, 30 tests.
• pnpm exec vitest --run test/extensions-runner.test.ts test/extensions-tool-catalog.test.ts test/extension-tool-availability.test.ts test/runtime-info-extension.test.ts test/step-capabilities-extension.test.ts test/agent-session-stats.test.ts test/trigger-compact-extension.test.ts test/suite/agent-session-auto-clm.test.ts test/suite/agent-session-live-context.test.ts test/step-usage-lifecycle.test.ts in packages/coding-agent — passed, 170 tests, 1 skipped.
• pnpm exec vitest --run test/step-slash-commands.test.ts -t "registers product adapters without replacing Pi's native commands" in packages/coding-agent — passed.
• npm run build:unbundled in packages/coding-agent and npm run build in apps/cli — passed.
• pnpm run check:browser-smoke — passed.

Limitations

• The repository-wide ./test.sh was not run locally. GitHub CI build-check-test and commit attribution pass on the current head.
• Two Windows-only failures in test/step-slash-commands.test.ts are unrelated to this change: they assert forward-slash diagnostic paths and create a diagnostics filename containing control characters. They reproduce on the current branch without the /context token-count changes.
• The token-count endpoint documents total_tokens / input_tokens totals, not a native per-section response. This PR therefore requests segmented totals and allocates structural children from those counts. Category totals can differ from the full-request total by message-role and tool-schema overhead; the full-request total remains the displayed group total.
• Tool definitions are counted with a tools field probe first and a serialized JSON fallback second, because the public token-count documentation does not state whether tools is included.
• Non-Step providers borrow the Step 3.7 tokenizer. Local estimation is only the fallback when Step tokenization is unavailable or any segment fails.