Throughput watchdog reports a character-derived estimate as tok/s

[code-yeongyu]

Summary

The throughput watchdog added in #1743 reports its verdict as tok/s, but it measures an approximation, not tokens. estimateStreamedUnits in packages/agent/src/stream-throughput-watchdog.ts computes Math.max(1, Math.ceil(text.length / 4)) per streamed delta, so the number in the user-facing message and in the settings knob name claims a precision the measurement does not have.

This is a wording and naming honesty issue, not a behavior bug: the estimate is proportional, the floor was chosen against that same scale, and the verdict is correct at the shipped default. Found while auditing the merge, and registered rather than left as a mental note.

Why it matters

The message is the only thing a user sees when a turn is aborted for being too slow, and it is the number they will quote back in a report. A user who measures real tokens per second with a different tool and gets a different figure has no way to know our number is a character-based estimate. The same applies to retry.provider.minThroughputTokensPerSecond: someone tuning it will reasonably assume real tokens.

Expected

Either of these is acceptable, and the first is cheaper:

1. Say what is measured. Report the rate in the units actually counted (the module already calls them "streamed units" internally), or mark the number as approximate in the message, and describe the knob in the settings documentation as a character-derived estimate rather than tokens.
2. Measure real tokens. Use the provider's token accounting where the stream exposes it, and keep the estimate only as a fallback for providers that do not.

Acceptance criteria:

• The user-visible message does not assert a unit the code did not measure.
• The settings documentation for the floor states what the number is derived from.
• The chosen floor keeps its current effective behavior: a ~2 units/s trickle still trips it, and a healthy stream over the same window still does not.

Scope

In: the verdict message wording, the settings documentation for the throughput knobs, and the option of a real-token source where available.

Out: the detection thresholds, the window and grace semantics, and the routing decision that skips the same-model retry budget - those shipped in #1743 and are unaffected.

Related

• fix(agent): fail over provider streams that trickle below a throughput floor (#1739) #1743 (merged a7dee82bb15f216d099c1fd50aa2878ce39e4d59) introduced the watchdog.
• Slow-but-alive provider streams are undetectable: a ~2 tok/s turn never times out, never retries, and never falls back #1739 is the tracking issue it closed.