|
| 1 | +# wp2 — one visible answer per turn |
| 2 | + |
| 3 | +Consumes: `000_research.md` mechanism 1. |
| 4 | + |
| 5 | +## Problem |
| 6 | + |
| 7 | +Kiro emits answer-like ordinary text and then calls the private completion tool |
| 8 | +in the SAME inference. The adapter releases the prose as `phase: "commentary"` |
| 9 | +and the completion `answer` as `phase: "final_answer"`; |
| 10 | +`src/bridge.ts` closes the commentary message on the phase change and opens a |
| 11 | +new assistant message. The client renders two assistant messages whose text is |
| 12 | +nearly identical. This is what the user saw. |
| 13 | + |
| 14 | +The existing suite pins this pair, so the fix necessarily REPLACES an asserted |
| 15 | +expectation rather than adding to it: |
| 16 | + |
| 17 | +``` |
| 18 | +tests/kiro-stream.test.ts |
| 19 | +{ type: "text_delta", text: "Done.", phase: "commentary" }, |
| 20 | +{ type: "text_delta", text: "Done.", phase: "final_answer" }, |
| 21 | +``` |
| 22 | + |
| 23 | +## Constraint that shapes the design |
| 24 | + |
| 25 | +Progress prose is load-bearing UX: a long tool-using turn streams commentary so |
| 26 | +the user is not left staring at nothing. Withholding ALL commentary until the |
| 27 | +turn resolves would trade a cosmetic duplicate for a silent turn, which the |
| 28 | +repository's own comments call out (`#520` gates exist precisely to avoid |
| 29 | +re-emitting or losing flushed progress). |
| 30 | + |
| 31 | +So the buffering must be NARROW: hold back only the trailing commentary run that |
| 32 | +has not yet been followed by a real tool call, and only while the completion tool |
| 33 | +is still capable of arriving. Release it unchanged the moment a real tool starts, |
| 34 | +the stream ends without a completion answer, or the bounded fallback engages. |
| 35 | + |
| 36 | +## Options |
| 37 | + |
| 38 | +1. **Consume the same inference's retained text on a valid completion.** (CHOSEN — |
| 39 | + narrowed in audit round 1, corrected in round 2.) No new buffer is needed: |
| 40 | + required-mode commentary is ALREADY deferred. But skipping the inner flush is |
| 41 | + NOT sufficient, and this is the correction that matters: |
| 42 | + |
| 43 | + - The inner flush is at `src/adapters/kiro.ts:1467`. |
| 44 | + - `parseKiroAttempt` INDEPENDENTLY drains whatever remains in `deferred` at |
| 45 | + `src/adapters/kiro.ts:996-999`, after the inner generator returns. |
| 46 | + |
| 47 | + So merely skipping the inner flush emits the final answer first and then the |
| 48 | + commentary from the outer drain — the duplicate survives, in reversed order. |
| 49 | + The deferred collection must be CONSUMED on a valid completion: discard and |
| 50 | + release the redundant `text_delta` events, preserve and release every |
| 51 | + non-text event, and leave nothing for the outer drain. That necessarily |
| 52 | + touches retention ownership, so the earlier claim that this change stays |
| 53 | + clear of the retention machinery is withdrawn. |
| 54 | + |
| 55 | + `text_fallback` has the SAME shape through a DIFFERENT collection: it retains |
| 56 | + in `fallbackEvents`, and `src/adapters/kiro.ts:1470-1477` emits all of them |
| 57 | + and then the completion answer. The rule must therefore apply independently |
| 58 | + inside EACH inference: |
| 59 | + |
| 60 | + - required inference + valid completion -> suppress its deferred text, keep |
| 61 | + non-text events, emit the completion answer; |
| 62 | + - text_fallback inference + valid completion -> suppress that inference's |
| 63 | + retained text, keep non-text events, emit the completion answer; |
| 64 | + - never retain one inference's progress across the next inference. |
| 65 | +2. **Retain commentary ACROSS the bounded fallback.** Rejected by the audit: the |
| 66 | + second inference can be long, so withholding first-attempt progress across it |
| 67 | + would make the turn look dead and contradicts the deliberate "first attempt |
| 68 | + already flushed" gate. |
| 69 | +3. **Suppress only on redundancy.** Emit commentary live, and skip the completion |
| 70 | + answer if it is substantially the same text. Rejected: "substantially the same" |
| 71 | + is a similarity heuristic, and a wrong guess either drops the real answer or |
| 72 | + keeps the duplicate. |
| 73 | +4. **Bridge-side coalesce.** Merge a commentary message and an immediately |
| 74 | + following final answer into one assistant message. Rejected as the primary |
| 75 | + seam: the phase distinction is deliberate protocol information, and the same |
| 76 | + split is correct when the commentary genuinely preceded tool work. |
| 77 | + |
| 78 | +Because the deferral already exists, this is a change to WHEN the deferred run is |
| 79 | +released, not a new retention mechanism — which also keeps it clear of the |
| 80 | +retention/budget machinery where duplication bugs have previously lived. |
| 81 | + |
| 82 | +## Criteria |
| 83 | + |
| 84 | +1. A single inference emitting answer-like prose plus a completion answer yields |
| 85 | + exactly ONE visible answer to the client. |
| 86 | +2. Commentary followed by a REAL tool call is still emitted live and in order. |
| 87 | +3. A CLEAN required-mode inference — text or reasoning present, no real tool, no |
| 88 | + completion answer, no explicit non-completion stop reason — still shows its |
| 89 | + progress prose and enters the bounded fallback exactly once. (Narrowed in |
| 90 | + audit round 2: the unqualified form was false for real tools, provider and |
| 91 | + protocol failures, and explicit stops such as `MAX_TOKENS` or |
| 92 | + `CONTENT_FILTERED`.) |
| 93 | +4. A Responses-protocol-level assertion, not only adapter events: the user-visible |
| 94 | + duplicate must be proven gone through the bridge. Adapter-event coverage cannot |
| 95 | + prove this, because the split happens in the bridge on the phase change. The |
| 96 | + assertion belongs in `tests/server-kiro-completion-e2e.test.ts`: one upstream |
| 97 | + request, exactly one visible assistant answer, one terminal completion, and the |
| 98 | + near-duplicate prose absent. |
| 99 | +5. The existing `tests/kiro-stream.test.ts` expectation that asserts the |
| 100 | + commentary/final pair is UPDATED, not deleted — the replacement states the new |
| 101 | + contract for the same scenario. |
| 102 | +6. `text_fallback` ordinary text plus a valid completion also yields exactly one |
| 103 | + visible answer. |
| 104 | +7. The translator budget returns to baseline after suppressed events — suppression |
| 105 | + must release retention, not leak it. |
| 106 | + |
| 107 | +## Release paths that must remain intact |
| 108 | + |
| 109 | +Enumerated from source in audit round 2; each is a control the implementation may |
| 110 | +not regress: |
| 111 | + |
| 112 | +| trigger | release point | |
| 113 | +|---------|---------------| |
| 114 | +| a real tool starts (`sawRealTool`) | `src/adapters/kiro.ts:1172-1177`, released with the tool event | |
| 115 | +| clean no-completion turn needing fallback | flush before `needsFallback` returns, `src/adapters/kiro.ts:1535-1542` / `1600-1603` | |
| 116 | +| stream / protocol / provider failure | outer failure drain, `src/adapters/kiro.ts:996-999` | |
| 117 | +| explicit non-completion stop | released before the incomplete/error branches, `src/adapters/kiro.ts:1545-1598` | |
| 118 | +| plain-text fallback without completion | retained text promoted to `final_answer`, `src/adapters/kiro.ts:1488-1501` | |
| 119 | +| empty / reasoning-only fallback | diagnostics released before the structured incomplete, `src/adapters/kiro.ts:1503-1517` | |
| 120 | + |
| 121 | +## Out of scope |
| 122 | + |
| 123 | +- The terminal-boundary fix (wp1). |
| 124 | +- Changing what `phase` means in the Responses protocol. |
0 commit comments