feat(api): expose session context usage and compaction events

[fangliquanflq]

What does this PR do?

API clients can now read the same per-session context occupancy information that Hermes surfaces in its TUI. The authenticated session API exposes a durable context snapshot, completed chat turns include that snapshot in usage metadata, and streaming clients receive automatic compaction lifecycle updates as structured SSE events.

Motivation

Clients integrating through the Hermes API could not determine how full a session context was, how close it was to automatic compression, or when automatic compaction occurred. This left editor integrations unable to present context pressure or react reliably to compression.

Behavior

• GET /api/sessions/{session_id}/context returns the latest normalized context window, occupancy, compression threshold and progress, remaining tokens, compression count, enabled state, compaction state, and update timestamp.
• Completed session chat responses include the same normalized snapshot under turn usage.
• Session chat streams emit automatic compaction lifecycle updates as context.compaction SSE events.
• Context snapshots persist with the session and follow durable compression continuation IDs after session rotation.
• This change does not add historical compaction-event replay or alter the existing TUI gauge.

Implementation

Context-engine readings are normalized in a shared helper and persisted in the existing session database. The API reuses existing authenticated session routes and SSE transport rather than adding a second event subsystem. A structural marker preserves automatic compaction event classification even when context engines customize status text.

Related Issue

Closes #86885

Type of Change

• New feature (non-breaking change that adds functionality)

Changes Made

• agent/context_usage.py - normalize context occupancy and compression metrics across context engines.
• agent/context_engine.py - structurally identify automatic compaction status messages.
• gateway/platforms/api_server.py - expose the context route, turn usage snapshot, capability metadata, persistence, and SSE events.
• hermes_state.py and hermes_state_common.py - persist per-session context snapshots.
• tests/gateway/test_session_api.py and tests/gateway/test_multiplex_api_server_routing.py - cover authentication, routing, persistence, rotation, normalized usage, and stream events.

How to Test

1. Run the focused API, state, and context-engine suites:

scripts/run_tests.sh tests/gateway/test_session_api.py tests/gateway/test_multiplex_api_server_routing.py tests/test_hermes_state.py tests/agent/test_context_engine.py tests/agent/test_context_engine_host_contract.py

2. Confirm the focused suites report 281 passed and 2 skipped.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature (no unrelated commits)
• I've run the repository test entry on the relevant suites and all tests pass
• I've added tests for my changes
• I've tested on my platform: Windows 11

Documentation & Housekeeping

• Relevant documentation updates are N/A because the capability is advertised through the API capability contract
• cli-config.yaml.example updates are N/A because no configuration keys changed
• CONTRIBUTING.md and AGENTS.md updates are N/A because no development workflow changed
• I've considered cross-platform impact; the implementation uses platform-independent Python, SQLite, HTTP, and SSE paths
• Tool description and schema updates are N/A because no model tool changed

Screenshots / Logs

Focused verification: 281 passed, 2 skipped.

[alt-glitch]

This was generated by AI during triage.

Related to #84602 and #15618: this expands the same context-telemetry family with a persisted session endpoint and compaction events, while #84602 focuses on completed-run context usage.