Closes #100954

What Problem This Solves

When an OpenAI/Azure Responses turn ends with response.incomplete — the max_output_tokens and
content_filter cases, and what Azure emits on early truncation — the agent records zero tokens and
zero cost for that turn. The tokens were spent and billed; the session transcript, usage.cost RPC and
usage bars just do not see them, so per-session accounting drifts low every time a turn is truncated.

This is the drift reported in #100954.

Why This Change Was Made

processResponsesStream in src/agents/openai-responses-transport.ts had a terminal branch for
response.completed only, so response.incomplete matched no branch in the chain and was silently
dropped: output.usage was never written, output.stopReason never set. Unlike the package-side
processor, this one has no "stream ended before a terminal response event" guard, so nothing surfaced the
miss — the loop just ended and the turn was reported as free.

The package side already fixed exactly this. #109615 finalizes both terminal events through one
finalizeResponse (packages/ai/src/providers/openai-responses-shared.ts), which records usage, cost and
service-tier pricing. It did not touch the agent path, and that path is live for the
openclaw-openai-responses-transport / openclaw-azure-openai-responses-transport runtimes — the Azure
one being #100954's subject. So this is a sibling-parity fix: same bug, same shape of fix, the surface
#109615 left behind.

The recording lives in src/agents/openai-responses-terminal-outcome.ts rather than growing
openai-responses-transport.ts, which is a legacy file the max-lines ratchet will not let grow. Pulling
the block out drops it from 2502 to 2444 lines, so the ratchet gets slack instead of pressure.

Addressing the Review

Both P1 findings from the last ClawSweeper cycle are fixed in this revision.

1. Incomplete terminal output: recovery only, never replay

The first version of this change refused terminal-output reconstruction for response.incomplete
outright. @steipete revised that in b2419b0a1a1: some compatible endpoints carry the generated text
only on the terminal event, so discarding it loses a partial answer the user should still see. The
head now backfills partial message text on an incomplete turn while still refusing to materialize an
incomplete function_call — a truncated argument string must never become an executable tool call.

That narrows the contract to a guard rather than a rule, so this push pins both sides of the guard
(openai-transport-stream.incomplete-output.test.ts):

• already-streamed text is not replayed — when deltas already delivered the text and the terminal
  payload repeats it, the turn keeps exactly one copy. This is the duplicate-transcript case: the
  backfill is gated on output.content.length === 0, so it stays a recovery path for streams that
  emitted nothing.
• non-length incomplete stops keep their partial text out — a content_filter stop is surfaced as
  an error, so its partial text is not a recoverable answer and must not be persisted as one.

Both tests are load-bearing, shown by mutating the source and observing exactly one failure each:

MUTATION: drop the already-streamed guard  (output.content.length > 0 → removed)
 FAIL > does not replay terminal text that already streamed
      Tests  1 failed | 1 passed (2)

MUTATION: backfill on any incomplete reason  (&& output.stopReason === "length" → removed)
 FAIL > keeps terminal-only text out of turns that stop for a non-length reason
      Tests  1 failed | 1 passed (2)

Neither mutation trips the other test, so the two cases are independently covered rather than
overlapping. Full file: 49 tests pass across the incomplete-output and base transport suites.

Scope note on the runtime evidence below: the main-versus-branch SSE transcript was recorded on
d050cf4da5e, before the partial-output revision, so it demonstrates the accounting fix — the original
subject of this PR — and not the newer output-preservation behavior. The two tests above are what cover
the revised behavior; I have not produced a fresh live-socket transcript for it.

Verified on the current head 4b3362b864c, which includes both follow-up commits
(fix(agents): preserve partial incomplete Responses output and fix(agents): avoid shadowing Responses options): 49 tests pass across openai-transport-stream.incomplete-output.test.ts and
openai-transport-stream.base.test.ts, and both mutations above still fail exactly one test each on
that head.

2. One canonical terminal-usage mapper

The parallel mapper is gone. Terminal usage buckets, the stop-reason mapping and the two shared overrides
(content-filter → provider error, tool calls → toolUse) now live in one module,
packages/ai/src/providers/openai-responses-terminal-usage.ts, and both finalizeResponse and the agent
transport call it. The duplicated mapStopReason and ResponsesInputTokensDetails in
openai-responses-shared.ts are deleted; the agent module drops from 103 to 68 lines and keeps only the
reasoning-token accounting the package-side Usage type does not carry — the thin adapter the review
asked for.

On placement: openai-responses-shared.ts is not reachable across the package boundary — it is not in
packages/ai exports, tsconfig paths, or the plugin-SDK resolver, and a deep import would resolve under
vitest's catch-all alias while failing tsc and runtime. So the mapper is its own module, re-exported
through the existing internal/openai entry point. No new subpath, no resolver or alias-test change.

One real disagreement surfaced by merging them

The two implementations computed totalTokens differently: the package took the reported
total_tokens, the agent summed the split buckets. The canonical rule is now
max(bucket sum, reported total), which keeps the provider's number while covering both directions the
old pair disagreed on — payloads that omit total_tokens (proxies routinely do; reporting 0 understates
the turn) and payloads whose cached_tokens exceeds input_tokens, where clamping the input bucket to 0
leaves the reported total below what the buckets actually price. Both cases are pinned by tests that fail
without the rule.

Evidence

The added tests fail on origin/main and pass here. On main the assertions report exactly the
symptom from #100954:

× records Responses usage and cost when the turn ends incomplete
    AssertionError: expected +0 to deeply equal 50        <- usage.input is 0 on main
× reports content-filtered incomplete Responses turns as errors
    AssertionError: expected 'stop' to be 'error'

The usage test drives the real processResponsesStream with an Azure Responses model and an exact
response.incomplete event (max_output_tokens, populated usage with cached + cache-write tokens), then
asserts the split buckets and priced cost. Sub-cent totals round to zero at toBeCloseTo's default
precision, so it also asserts toBeGreaterThan(0).

Runtime proof: the real transport over a real socket, main vs this branch

Beyond the unit tests, the fix was exercised end to end through the actual network path. A local HTTP
server speaks the Responses SSE wire protocol and ends the turn with response.incomplete
(incomplete_details.reason = max_output_tokens, populated usage), and the real
createOpenAIResponsesTransportStreamFn() is pointed at it via model.baseUrl. Nothing is mocked —
the OpenAI SDK opens a socket, parses the event stream and hands events to processResponsesStream
exactly as it does against api.openai.com. The only difference from a live run is the hostname, as the
transport's own debug output confirms on both branches:

[model-fetch] start    provider=openai api=openai-responses model=gpt-5.4-pro method=POST url=http://127.0.0.1:PORT/v1/responses
[model-fetch] response provider=openai api=openai-responses model=gpt-5.4-pro status=200 contentType=text/event-stream

Same harness, same event, priced with real cost points — run against origin/main (e01a880) and against
this branch:

This is #100954 reproduced against current main on the agent path, and it is worse than the issue
describes: main does not merely lose the tokens, it also records stopReason: "stop". A turn that hit the
output cap and was truncated mid-answer is persisted as a turn that finished successfully having spent
nothing. Downstream consumers cannot tell a truncated turn from a completed one, so nothing retries or
warns — which is why the drift is silent.

The scenario is routine rather than an edge case: max_output_tokens is what every long answer hits.

On proof shape: the usage payload in the harness is authored, so this proves the transport records
what the provider reports — not that these particular numbers came off an OpenAI invoice. For comparison,
#109615 pinned the identical package-side behavior with a synthetic terminal event
(it("finalizes incomplete terminal events with usage"),
packages/ai/src/providers/openai-responses-shared.test.ts) and no captured provider transcript. If a
redacted live Azure/OpenAI transcript is still required on top of the above, a maintainer run against a
real endpoint is the remaining gap — I do not have live credentials.

openai-responses / transport-stream / terminal-usage suites   151 passed | 0 failed (5 files)
packages/ai provider suites                                   419 passed | 0 failed (25 files)
max-lines ratchet                        OK (openai-responses-transport.ts 2502 -> 2444)
oxlint / oxfmt --check                   clean
tsgo -p tsconfig.json / test/tsconfig.json    no errors

Merge Risk

Low. The response.completed path is unchanged in behavior — the reconstruction it depends on is now
explicitly scoped to it, and the existing transport suites cover it unchanged.

Three behaviors move, all of them the corrections above:

• response.incomplete records usage/cost and sets a stop reason instead of being dropped, so
  per-session totals go up for truncated turns — worth calling out for anyone watching usage
  dashboards.
• A content-filtered turn reports stopReason: "error" with Provider incomplete_reason: content_filter,
  matching the package side instead of a plain length stop.
• totalTokens follows the max(bucket sum, reported total) rule on both Responses paths, which changes
  the package-side value only for payloads that omit total_tokens or report one below the priced
  buckets.

This supersedes the agent-side half of #101608, which I opened before #109615 landed the package-side fix;
that PR is now conflicted and half-redundant, so I am closing it in favor of this narrower one.

AI-assisted.