|
| 1 | +# 050 — Phase 5: a buffered turn that never terminated is not "completed" |
| 2 | + |
| 3 | +The last follow-up recorded in `000_index.md`. Deferred from `010` pending |
| 4 | +evidence; that evidence now exists and is worse than the note assumed. |
| 5 | + |
| 6 | +## Measured, not assumed |
| 7 | + |
| 8 | +`buildResponseJSON` defaults to `"completed"` whenever no error or incomplete |
| 9 | +event is present (`bridge.ts:1830-1834`). Probed directly against the current |
| 10 | +tree: |
| 11 | + |
| 12 | +| Adapter events | Result | |
| 13 | +|----------------|--------| |
| 14 | +| `[text]`, no terminal | `status: "completed"`, no `incomplete_details` | |
| 15 | +| `[tool_call_start, tool_call_delta("{\"code\":\"tru")]` | `status: "completed"` with a `function_call` item, `status: "completed"`, `arguments: "{\"code\":\"tru"` | |
| 16 | +| same + `tool_call_end` | `status: "failed"`, item `status: "incomplete"` | |
| 17 | + |
| 18 | +The second row is the defect. A truncated tool call — invalid JSON, never closed — |
| 19 | +is handed back as a **successful** turn containing an apparently complete |
| 20 | +function call. A caller that trusts `status` will try to execute it. |
| 21 | + |
| 22 | +The third row is the same bridge, on the same arguments, getting it right. The |
| 23 | +rejection logic already exists (`bridge.ts:1070-1080`); it is reached only when |
| 24 | +an explicit `tool_call_end` arrives. When the stream simply stops, nothing runs |
| 25 | +it. |
| 26 | + |
| 27 | +## Why this is in scope |
| 28 | + |
| 29 | +`010` and `040` both closed *adapter-side* routes to this shape: a truncated EOF |
| 30 | +and a server cancel now raise typed errors, so those paths no longer reach the |
| 31 | +buffered default. This phase closes the default itself, which is what makes the |
| 32 | +guarantee hold for any adapter that ends a stream without a terminal — including |
| 33 | +future ones nobody has audited. |
| 34 | + |
| 35 | +## Scope warning |
| 36 | + |
| 37 | +`src/bridge.ts` is shared by **every** provider. This phase therefore: |
| 38 | + |
| 39 | +- changes only the no-terminal case, leaving every explicit `done`/`error`/ |
| 40 | + `incomplete` path byte-identical; |
| 41 | +- runs the **full** suite on `ssh lidge`, not the cursor subset. A baseline full |
| 42 | + run at `6d97442839` is captured before the change so any new failure is |
| 43 | + attributable. |
| 44 | + |
| 45 | +## Contract |
| 46 | + |
| 47 | +| Buffered turn | Status | |
| 48 | +|---------------|--------| |
| 49 | +| explicit `done` | `completed` — unchanged | |
| 50 | +| explicit `error` | `failed` — unchanged | |
| 51 | +| `incomplete` / `max_tokens` / `content_filter` | `incomplete` — unchanged | |
| 52 | +| no terminal, no open tool call | `incomplete`, `incomplete_details.reason = "adapter_eof"` | |
| 53 | +| no terminal, tool call left open | `incomplete`, and the item is **not** `completed` | |
| 54 | + |
| 55 | +Streaming already reports `adapter_eof` for the fourth row (`bridge.ts:1283`), so |
| 56 | +this aligns the buffered path with the streaming one rather than inventing a new |
| 57 | +signal. |
| 58 | + |
| 59 | +## Diff-level plan |
| 60 | + |
| 61 | +**`src/bridge.ts`** |
| 62 | + |
| 63 | +- In `buildResponseJSONWithBudget`, track whether any adapter terminal |
| 64 | + (`done`/`error`/`incomplete`) was observed. |
| 65 | +- When none was, resolve `status` to `"incomplete"` with |
| 66 | + `incomplete_details: { reason: "adapter_eof" }`, matching the streaming path's |
| 67 | + wording exactly. |
| 68 | +- An unclosed tool call must not carry item `status: "completed"`. Reuse the |
| 69 | + existing incomplete-item marking rather than adding a second notion of |
| 70 | + "unfinished". |
| 71 | +- Do not touch `stopReason` handling, usage reporting, or compaction. |
| 72 | + |
| 73 | +## Tests (`tests/bridge-nonstreaming-terminal.test.ts`) |
| 74 | + |
| 75 | +1. Text with no terminal -> `incomplete` + `adapter_eof`, not `completed`. Red today. |
| 76 | +2. Open tool call with truncated arguments and no `tool_call_end` -> turn is not |
| 77 | + `completed` and the item is not `completed`. Red today; this is the executable- |
| 78 | + garbage case. |
| 79 | +3. Parity: the same events through streaming and buffered agree on terminal |
| 80 | + status. This is the assertion that keeps the two paths from drifting again. |
| 81 | +4. Explicit `done` -> still `completed` (regression). |
| 82 | +5. Explicit `error` -> still `failed`; explicit `incomplete` -> still `incomplete` |
| 83 | + with its own reason preserved (regression). |
| 84 | + |
| 85 | +## Done when |
| 86 | + |
| 87 | +All five pass, `bun run typecheck` clean, and the **full** suite on `ssh lidge` |
| 88 | +matches the pre-change baseline. Tests 1 and 2 demonstrated red beforehand. |
| 89 | + |
| 90 | + |
| 91 | +## Shipped, and what the audit chain changed |
| 92 | + |
| 93 | +Five review rounds. The plan's core claim survived; nearly every detail did not. |
| 94 | + |
| 95 | +| Commit | What it closed | |
| 96 | +|--------|----------------| |
| 97 | +| `aa800ae65` | The default itself: a buffered turn with no adapter terminal is `incomplete`/`adapter_eof`, and an open tool call is no longer emitted as a completed `function_call` with half-written JSON. | |
| 98 | +| `44fde398b` | The #422 compaction guard could only see explicit failure events, so a terminal-less turn still installed replacement history. | |
| 99 | +| `f73f09c9e` | Streaming emitted the compaction item *before* reading `stopReason`; Google's `parseResponse` dropped `finishReason` entirely. | |
| 100 | +| `95f73db17` | `stopReason` is an open-ended string and adapters disagree (`length`, `refusal`); canonical-only matching left the guard bypassable. | |
| 101 | +| `71730023a` | **My own regression:** suppressing the item without downgrading the turn produced `completed` with zero compaction items — the shape codex-rs fatals on. Suppression and status now come from one decision. | |
| 102 | +| `ea5e61677` | Anthropic `pause_turn` is unfinished by definition; AI SDK `error` is a failure, so Command Code emits a real error terminal instead of a stop reason. | |
| 103 | + |
| 104 | +The lesson worth keeping: each round fixed the previous round's fix. Round 4 found |
| 105 | +that my round-3 change had made things *worse* in one direction — a suppressed |
| 106 | +compaction item with a success status is more dangerous than the bug it replaced, |
| 107 | +because codex-rs treats zero items as fatal. Widening a guard without widening |
| 108 | +what it reports is not a partial fix; it is a new failure. |
| 109 | + |
| 110 | +## Open follow-ups (adapter-side, deliberately not folded in) |
| 111 | + |
| 112 | +Both erase truncation metadata **before** the bridge can defend anything, so they |
| 113 | +cannot be fixed here: |
| 114 | + |
| 115 | +- **Kiro** (`kiro.ts:1315`, `:1485`): in `completionMode: "disabled"` — which routed |
| 116 | + compaction selects, because it removes tools — the normalized reason is observed |
| 117 | + and then the final `done` omits `stopReason`. `MAX_TOKENS` and |
| 118 | + `MODEL_CONTEXT_WINDOW_EXCEEDED` both vanish. |
| 119 | +- **Google ordinary mode** (`google.ts:779`, `:947`): only `MAX_TOKENS` and five safety |
| 120 | + values are forwarded. `MALFORMED_RESPONSE`, `UNEXPECTED_TOOL_CALL`, `IMAGE_SAFETY`, |
| 121 | + and `LANGUAGE` become reasonless `done` events. The Vertex/CCA fail-closed guard |
| 122 | + covers only part of this. |
| 123 | + |
| 124 | +Each is its own unit with its own truncation subsystem. Recording them beats |
| 125 | +half-fixing them inside a bridge phase. |
| 126 | + |
| 127 | +## Final state (eight rounds) |
| 128 | + |
| 129 | +| Commit | Closed | |
| 130 | +|--------|--------| |
| 131 | +| `ea5e61677` | Anthropic `pause_turn` is unfinished by definition; AI SDK `error` is a failure, so Command Code emits a real error terminal. | |
| 132 | +| `6478cbb02` | Removing `error` from the shared table was safe only for Command Code — Anthropic forwards `stop_reason` verbatim, so it needed its own error terminal on the buffered and streaming paths. Both terminals carry usage. | |
| 133 | +| `1651002c5` | Anthropic has a **third** terminal path: the EOF branch for providers that close after `message_delta` without `message_stop` bypasses `emitDone` entirely and still reported success. | |
| 134 | + |
| 135 | +Round 8: **PASS, no findings.** Verified exhaustively that Anthropic's terminal |
| 136 | +paths are `message_stop`/`emitDone`, the compatible-provider EOF branch, and |
| 137 | +buffered `parseResponse` — and that `anthropicEofTolerance` is not a fourth, |
| 138 | +since it runs only when no stop reason was received and delegates back through |
| 139 | +`emitDone`. |
| 140 | + |
| 141 | +Final verification on `ssh lidge` at `1651002c59`: typecheck clean, |
| 142 | +**12800 pass / 0 fail** across 830 files. The pre-phase baseline was 12761/0. |
| 143 | + |
| 144 | +### Two tests that were protecting nothing |
| 145 | + |
| 146 | +Worth recording, because both looked like coverage: |
| 147 | + |
| 148 | +- The Anthropic streaming test was titled "carrying usage" and never asserted |
| 149 | + usage. Removing usage from the error terminal kept it green. |
| 150 | +- The Command Code coverage hand-constructed the downstream error event instead |
| 151 | + of driving the parser, so it stayed green while the adapter still emitted a |
| 152 | + clean `done`. |
| 153 | + |
| 154 | +Both now drive the real parsers, and dropping usage from either error terminal |
| 155 | +turns the suite red. |
| 156 | + |
| 157 | +### What the round count actually bought |
| 158 | + |
| 159 | +Eight rounds, and the finding that justified them arrived at round 7 — after two |
| 160 | +rounds had already declared the area closed. Two of the defects were regressions |
| 161 | +I introduced while fixing the previous round's finding: |
| 162 | + |
| 163 | +1. Suppressing the compaction item without downgrading the turn produced |
| 164 | + `completed` with zero compaction items, which codex-rs treats as fatal. A |
| 165 | + half-widened guard was more dangerous than the bug it replaced. |
| 166 | +2. Removing `error` from the shared table fixed Command Code and silently |
| 167 | + re-opened Anthropic, which forwards the same string verbatim. |
| 168 | + |
| 169 | +Both share a shape: a fix that is correct for the case in front of you and wrong |
| 170 | +for the one next to it. That is the argument for auditing revisions, not just |
| 171 | +first drafts. |
0 commit comments