Skip to content

feat(cli): refresh the statusline ctx segment per settled provider request (#4545) - #4550

Open
me2seeks wants to merge 2 commits into
apache:mainfrom
me2seeks:feat/4545-live-ctx
Open

feat(cli): refresh the statusline ctx segment per settled provider request (#4545)#4550
me2seeks wants to merge 2 commits into
apache:mainfrom
me2seeks:feat/4545-live-ctx

Conversation

@me2seeks

@me2seeks me2seeks commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Closes #4545.

Problem

The TUI statusline ctx used/window pct% segment only moved once per turn, when the end-of-turn token_usage event landed. During a long agentic turn — dozens of tool steps over minutes, exactly when the context grows fastest — the indicator sat frozen at the previous turn's value, hiding the signal that says "time to /compact or wrap up".

Approach

Reuse the desktop inspector's pull model instead of growing a parallel push event (design + audit: docs/tui-live-ctx-updates.md, 中文讲解 docs/tui-live-ctx-updates.zh-CN.md):

  • The Host already commits a latest-context snapshot at every settled provider request (provider-request-telemetry.ts), and context.diagnostics.query is a plain read with no busy gate — the desktop inspector refreshes from it mid-turn on trace-relevant events.
  • New packages/cli/src/tui-context-refresh.ts: the desktop trace-relevant event set (tool_start, tool_result, token_usage, …) + a restart-on-event debouncer (400 ms, same as desktop) whose revision guard lets only the latest issued query apply; a failed read leaves the last value standing.
  • pi-tui-runner.ts: observe() on the shared turn-drain onEvent (covers user-submitted and Host-attached turns alike) and on the resumeLatest loop; cancel() on teardown; a stale-session guard drops results that resolve after a switch. The query calls the driver directly — runControl's serial lock exists for mutations, and /context's mid-turn refusal is a TUI-local choice, not a protocol constraint.
  • The apply path uses the same contextRemaining = contextWindow − inputTokens formula as the token_usage path (fix(runtime): emit contextRemaining in token_usage events so the TUI ctx segment renders #1067), derived from the same settled request — the two cannot disagree. Turn-end token_usage stays the authoritative persisted record; this only enriches the live turn.

Zero protocol / runtime / persistence changes: no new event type, no billing semantics touched (#972).

Non-goals

  • Token-level updates during one streaming request: providers report input tokens only at completion, so exact mid-request values do not exist; the pre-dispatch bytes/4 estimate is too rough (base64 attachments) to show.
  • Unlocking /context mid-turn over the same query path — a free follow-up, kept out to stay small.
  • Desktop changes (already has this granularity).

Test plan

  • New unit tests tui-context-refresh.test.ts (9): event-set parity with desktop, debounce coalescing, out-of-order resolution guard, failed read keeps last value, cancel retires scheduled + in-flight queries, real-timer sanity.
  • New runner integration tests (2): ctx segment moves mid-turn while the turn is parked after tool_start (before any token_usage); a failing snapshot read leaves the segment untouched and silent.
  • Full maka-agent package suite: 732 passed, 0 failed (3 pre-existing skips); whole-repo typecheck green; biome lint/format clean; ASF header check green.

@github-actions github-actions Bot added the effort/L Under 1000 readable lines label Sep 2, 2026
…quest (apache#4545)

The ctx segment only moved when the end-of-turn token_usage event landed,
so a long agentic turn burned context with the indicator frozen at the
previous turn's value. The Host already commits a latest-context snapshot
at every settled provider request (the desktop inspector's data source),
so pull it on the desktop's own signal: trace-relevant events schedule a
400ms-debounced getContextDiagnostics read, and the latest issued read
writes contextRemaining straight into the statusline usage.

- tui-context-refresh.ts: desktop's trace-relevant event set + a
  restart-on-event debouncer whose revision guard lets only the latest
  issued query apply; a failed read leaves the last value standing.
- pi-tui-runner.ts: observe() on the shared turn-drain onEvent (covers
  user and Host-attached turns) and on resumeLatest; cancel on teardown;
  stale-session guard drops pre-switch results. ctxRefreshTicker input
  option injects the timer for tests.

Zero protocol/runtime changes: no new event type, no persistence or
billing semantics touched (apache#972). Turn-end token_usage stays the
authoritative persisted record.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/L Under 1000 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(cli): TUI statusline ctx segment should update per settled provider request, not just at turn end

1 participant