Skip to content

The agent that grows with you

fix(desktop): a re-sent reply segment upserts by its wire identity

Teknium1f0f2cecd15d
diff --git a/apps/desktop/e2e/core/reattach-running-turn.spec.ts b/apps/desktop/e2e/core/reattach-running-turn.spec.ts
index ee66c21f5b1..ee2a332d845 100644
--- a/apps/desktop/e2e/core/reattach-running-turn.spec.ts
+++ b/apps/desktop/e2e/core/reattach-running-turn.spec.ts
@@ -5,8 +5,11 @@
* history a re-attaching window fetches already holds that round while the
* live stream keeps drawing the same segment (#127288, #127665). Each step
* leaves the chat mid-turn by a different road (switch away and back during
- * the answer or the running tool, a steer, a socket drop) and holds the settled turn to the
- * transcript oracle, whose in-page sampler also fails a transient double.
+ * the answer or the running tool, a reload, a steer, a socket drop) and holds
+ * the settled turn to the transcript oracle, whose in-page sampler also fails a
+ * transient double. The last two specs re-send frames the backend already
+ * delivered under new seqs; the turn's wire identity (turn_id, segment, offset)
+ * is what lets the renderer upsert them.
*/
import fs from 'node:fs'
@@ -155,6 +158,23 @@ test('re-attaching to a running tool turn renders each segment once', async () =
await assertTranscriptOracle(page, ws, provider, session, 're-attach during the tool')
})
+ await test.step('reload while the answer after a tool streams', async () => {
+ const hold = gate()
+ provider.script(U(4), [
+ { text: words(AI(4), 'narrating', 'again'), toolCalls: [echo('reattach-c')] },
+ { text: words(A(4), 'answer', 'across', 'a', 'reload'), holdAfterFirstChunk: hold }
+ ])
+ await send(page, `${U(4)} reload mid answer`, 'Enter', ws)
+ await provider.streamStarted(U(4), 1)
+ await expect(viewport(page)).toContainText(A(4))
+ session.expectUserMarkers.push(U(4))
+ await page.reload()
+ await expect(viewport(page)).toContainText(AI(4), { timeout: 60_000 })
+ await installDuplicateSampler(page)
+ hold.open()
+ await settled(page, ws, A(4))
+ await assertTranscriptOracle(page, ws, provider, session, 're-attach after a reload')
+ })
await test.step('a steer during the answer, then switch away and back mid-turn', async () => {
const hold = gate()
const steerHold = gate()
@@ -316,3 +336,39 @@ test('a tool completion redelivered under a newer seq renders one tool row', asy
})
})
+test('a narrated segment replayed after a message.start renders once', async () => {
+ await withApp('replay-segment', async ({ app, page, provider, ws }) => {
+ const session: OracleTarget = { sessionId: '', expectUserMarkers: [] }
+
+ const isEvent = (msg: any, type: string) => msg?.method === 'event' && msg.params?.type === type
+
+ // When the tool starts, replay the turn's message.start and the narration
+ // deltas after it: the segment a superseded attempt re-streams.
+ const redelivery = await routeRedelivery(
+ page,
+ ws,
+ msg => isEvent(msg, 'tool.start') && JSON.stringify(msg.params.payload ?? {}).includes(`replay-${nonce}`),
+ delivered => {
+ const start = delivered.findLastIndex(frame => isEvent(frame, 'message.start'))
+
+ return [delivered[start], ...delivered.slice(start + 1).filter(frame => isEvent(frame, 'message.delta'))]
+ }
+ )
+
+ await page.reload()
+ await waitForInteractive(app, page)
+ await installDuplicateSampler(page)
+ provider.script(U(1), [
+ { text: words(AI(1), 'commentary', 'before', 'the', 'tool'), toolCalls: [echo(`replay-${nonce}`)] },
+ { text: words(A(1), 'a', 'different', 'final', 'answer') }
+ ])
+ await send(page, `${U(1)} commentary then answer`, 'Enter', ws)
+ await settled(page, ws, A(1))
+ session.sessionId = await currentSessionId(page)
+ session.expectUserMarkers.push(U(1))
+ expect(redelivery.redelivered).toBe(true)
+ await page.screenshot({ path: test.info().outputPath('replayed-segment.png') })
+ session.lossyWire = [U(1)]
+ await assertTranscriptOracle(page, ws, provider, session, 'replayed narrated segment')
+ })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts
index 92392b292c9..79cc9d1daf4 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/message-stream.ts
@@ -23,6 +23,8 @@ import { lightDesktopMessagingCompletion } from '@/store/session-unread'
import { pruneFinishedSessionSubagents } from '@/store/subagents'
import { clearActiveSessionTodos } from '@/store/todos'
+import { segmentStamp } from '../segment-identity'
+
import type { GatewayEventContext } from './types'
function firstBillingLine(text: string): string {
@@ -124,6 +126,105 @@ function lightOwnMessagingTurn(runtimeId: string, admissionId: string | undefine
lightDesktopMessagingCompletion(storedId, admissionId, storedId === $focusedStoredSessionId.get(), profile)
}
+/** message.start: arm the session for a new turn, unless it re-sends the current one. */
+function handleMessageStart(ctx: GatewayEventContext): boolean {
+ const { deps, payload, sessionId, isActiveEvent } = ctx
+ const { compactedTurnRef, flushQueuedDeltas, dropQueuedDeltas, nativeSubagentSessionsRef } = deps
+ const { sessionStateByRuntimeIdRef, updateSessionState } = deps
+
+ if (!sessionId) {
+ return true
+ }
+
+ const turnId = typeof payload?.turn_id === 'string' ? payload.turn_id : ''
+
+ // A re-sent start of the turn this session already has (reconnect replay,
+ // a superseded attempt) is not a new occurrence: resetting here would let
+ // the turn's re-sent segment paint as a second copy (#144609).
+ if (turnId && sessionStateByRuntimeIdRef.current.get(sessionId)?.streamTurnId === turnId) {
+ return true
+ }
+
+ // Turn-boundary orphan drop (#119543): when no turn is live, anything
+ // still queued belongs to a turn that already ended (a delta reordered
+ // behind its own complete or heartbeat). Flushing it would seed a bubble
+ // the new turn inherits, painting a stale duplicate of the previous
+ // reply. A still-live previous turn (steer) keeps the flush: those bytes
+ // are real output of the bubble on screen.
+ if (sessionStateByRuntimeIdRef.current.get(sessionId)?.turnLive) {
+ flushQueuedDeltas(sessionId)
+ } else {
+ dropQueuedDeltas(sessionId)
+ }
+
+ pruneFinishedSessionSubagents(sessionId)
+ setSessionCompacting(sessionId, false)
+ compactedTurnRef.current.delete(sessionId)
+ nativeSubagentSessionsRef.current.delete(sessionId)
+ // A fresh turn on this session optimistically clears its billing wall;
+ // if credits are still exhausted the next failure re-raises it.
+ clearBillingBlock(sessionId)
+
+ if (isActiveEvent) {
+ triggerHaptic('streamStart')
+ }
+
+ // Submit→accept latency: seedOptimistic armed the clock at Enter; this
+ // event is the backend accepting the turn. Debug-only visibility into
+ // how long the arm actually took (the "no progress box for seconds"
+ // complaint) — reads the pre-update cache, costs nothing when clean.
+ const seededAt = sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt
+
+ if (typeof seededAt === 'number') {
+ console.debug('[turn-accept-latency]', { sessionId, ms: Date.now() - seededAt })
+ }
+
+ updateSessionState(sessionId, state => {
+ // If the user clicked Stop (cancelRun set interrupted=true), don't
+ // let a stale message.start from a chained turn (goal follow-up,
+ // completion drain) or an in-flight LLM response re-arm busy.
+ // The interrupt is user intent — the backend's cooperative cancel
+ // may not have propagated yet, so its events are stale. The turn's
+ // finally block will emit session.info with running=false to clear
+ // busy for real once the agent loop actually exits.
+ if (state.interrupted) {
+ return state
+ }
+
+ return {
+ ...state,
+ busy: true,
+ awaitingResponse: true,
+ sawAssistantPayload: false,
+ interrupted: false,
+ interimBoundaryPending: false,
+ // Backend accepted the turn — the no-payload settle gate below may
+ // now treat a running=false heartbeat as a real turn end.
+ turnLive: true,
+ // A new turn is a new occurrence: the previous turn's late terminal
+ // frame (#119569) can no longer claim its heartbeat-settled bubble.
+ heartbeatSettledStreamId: null,
+ streamTurnId: turnId || null,
+ // Keep the submit-time seed (submit.ts seedOptimistic) — resetting
+ // here would hide the submit→accept round trip from the timer.
+ // Backend-originated turns (queue drain elsewhere, goal follow-up)
+ // have no seed and arm here.
+ turnStartedAt: state.turnStartedAt ?? Date.now()
+ }
+ })
+
+ if (isActiveEvent) {
+ // Belt-and-suspenders mirror of the ACTIVE session's per-session
+ // clock (the load-bearing mirror is the view-sync flush in
+ // use-session-state-cache). Mirror the seeded value, not Date.now():
+ // resetting to accept-time here would visibly snap the timer back
+ // after the submit-time seed above already started it.
+ setTurnStartedAt(sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt ?? Date.now())
+ }
+
+ return true
+}
+
// health: allow CC -- usage-window limit: one guard so the error card, not a second billing toast, says it; this event switch was over target on main
export function handleMessageStreamEvent(ctx: GatewayEventContext): boolean {
const { deps, event, payload, sessionId, isActiveEvent, occurredAt } = ctx
@@ -142,92 +243,12 @@ export function handleMessageStreamEvent(ctx: GatewayEventContext): boolean {
} = deps
if (event.type === 'message.start') {
- if (!sessionId) {
- return true
- }
-
- // Turn-boundary orphan drop (#119543): when no turn is live, anything
- // still queued belongs to a turn that already ended (a delta reordered
- // behind its own complete or heartbeat). Flushing it would seed a bubble
- // the new turn inherits, painting a stale duplicate of the previous
- // reply. A still-live previous turn (steer) keeps the flush: those bytes
- // are real output of the bubble on screen.
- if (sessionStateByRuntimeIdRef.current.get(sessionId)?.turnLive) {
- flushQueuedDeltas(sessionId)
- } else {
- dropQueuedDeltas(sessionId)
- }
-
- pruneFinishedSessionSubagents(sessionId)
- setSessionCompacting(sessionId, false)
- compactedTurnRef.current.delete(sessionId)
- nativeSubagentSessionsRef.current.delete(sessionId)
- // A fresh turn on this session optimistically clears its billing wall;
- // if credits are still exhausted the next failure re-raises it.
- clearBillingBlock(sessionId)
-
- if (isActiveEvent) {
- triggerHaptic('streamStart')
- }
-
- // Submit→accept latency: seedOptimistic armed the clock at Enter; this
- // event is the backend accepting the turn. Debug-only visibility into
- // how long the arm actually took (the "no progress box for seconds"
- // complaint) — reads the pre-update cache, costs nothing when clean.
- const seededAt = sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt
-
- if (typeof seededAt === 'number') {
- console.debug('[turn-accept-latency]', { sessionId, ms: Date.now() - seededAt })
- }
-
- updateSessionState(sessionId, state => {
- // If the user clicked Stop (cancelRun set interrupted=true), don't
- // let a stale message.start from a chained turn (goal follow-up,
- // completion drain) or an in-flight LLM response re-arm busy.
- // The interrupt is user intent — the backend's cooperative cancel
- // may not have propagated yet, so its events are stale. The turn's
- // finally block will emit session.info with running=false to clear
- // busy for real once the agent loop actually exits.
- if (state.interrupted) {
- return state
- }
-
- return {
- ...state,
- busy: true,
- awaitingResponse: true,
- sawAssistantPayload: false,
- interrupted: false,
- interimBoundaryPending: false,
- // Backend accepted the turn — the no-payload settle gate below may
- // now treat a running=false heartbeat as a real turn end.
- turnLive: true,
- // A new turn is a new occurrence: the previous turn's late terminal
- // frame (#119569) can no longer claim its heartbeat-settled bubble.
- heartbeatSettledStreamId: null,
- // Keep the submit-time seed (submit.ts seedOptimistic) — resetting
- // here would hide the submit→accept round trip from the timer.
- // Backend-originated turns (queue drain elsewhere, goal follow-up)
- // have no seed and arm here.
- turnStartedAt: state.turnStartedAt ?? Date.now()
- }
- })
-
- if (isActiveEvent) {
- // Belt-and-suspenders mirror of the ACTIVE session's per-session
- // clock (the load-bearing mirror is the view-sync flush in
- // use-session-state-cache). Mirror the seeded value, not Date.now():
- // resetting to accept-time here would visibly snap the timer back
- // after the submit-time seed above already started it.
- setTurnStartedAt(sessionStateByRuntimeIdRef.current.get(sessionId)?.turnStartedAt ?? Date.now())
- }
-
- return true
+ return handleMessageStart(ctx)
}
if (event.type === 'message.delta') {
if (sessionId) {
- appendAssistantDelta(sessionId, coerceGatewayText(payload?.text), occurredAt)
+ appendAssistantDelta(sessionId, coerceGatewayText(payload?.text), occurredAt, segmentStamp(payload))
}
return true
@@ -243,7 +264,7 @@ export function handleMessageStreamEvent(ctx: GatewayEventContext): boolean {
const text = coerceGatewayText(payload?.text)
if (text) {
- finalizeInterimAssistantMessage(sessionId, text, occurredAt)
+ finalizeInterimAssistantMessage(sessionId, text, occurredAt, segmentStamp(payload))
}
}
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts
index 0cb8b6e24a3..d9bd25805c0 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/gateway-event/types.ts
@@ -6,6 +6,7 @@ import type { GatewayEventPayload } from '@/lib/chat-messages'
import type { ErrorSurface } from '@/lib/error-surface'
import type { ClientSessionState } from '../../../../types'
+import type { SegmentStamp } from '../segment-identity'
export interface GatewayEventDeps {
activeGatewayProfile: string
@@ -13,7 +14,7 @@ export interface GatewayEventDeps {
compactedTurnRef: MutableRefObject<Set<string>>
lastCwdInfoSessionRef: MutableRefObject<string | null>
nativeSubagentSessionsRef: MutableRefObject<Set<string>>
- appendAssistantDelta: (sessionId: string, delta: string, occurredAt?: number) => void
+ appendAssistantDelta: (sessionId: string, delta: string, occurredAt?: number, stamp?: null | SegmentStamp) => void
appendReasoningDelta: (sessionId: string, delta: string, replace?: boolean, occurredAt?: number) => void
completeAssistantMessage: (
sessionId: string,
@@ -34,7 +35,12 @@ export interface GatewayEventDeps {
) => void
flushQueuedDeltas: (sessionId?: string) => void
dropQueuedDeltas: (sessionId?: string) => void
- finalizeInterimAssistantMessage: (sessionId: string, text: string, occurredAt?: number) => void
+ finalizeInterimAssistantMessage: (
+ sessionId: string,
+ text: string,
+ occurredAt?: number,
+ stamp?: null | SegmentStamp
+ ) => void
hydrateFromStoredSession: (
attempts?: number,
storedSessionId?: string | null,
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/index.ts b/apps/desktop/src/app/session/hooks/use-message-stream/index.ts
index 4035aaaa1eb..76c4630522f 100644
--- a/apps/desktop/src/app/session/hooks/use-message-stream/index.ts
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/index.ts
@@ -52,6 +52,7 @@ import { handleServerRequest as dispatchServerRequest } from './gateway-event/se
import { extendInterruptedReply } from './interrupted-reply'
import { bindReceiptUserRows } from './receipt-user-rows'
import { currentResponseParts, mergeCurrentResponseText } from './response-parts'
+import { admitSegmentDelta, admitSegmentSeal, type SegmentCursor, type SegmentStamp } from './segment-identity'
import { completionErrorText, delegateTaskPayloads, MAX_STREAM_FLUSH_GAP_MS, STREAM_DELTA_FLUSH_MS } from './utils'
interface MessageStreamOptions {
@@ -300,6 +301,9 @@ export function useMessageStream({
const nativeSubagentSessionsRef = useRef<Set<string>>(new Set())
// Turns that auto-compacted: skip post-turn hydrate so live scrollback survives.
const compactedTurnRef = useRef<Set<string>>(new Set())
+ // Per session: how far the live turn's stamped reply has been applied, so a
+ // re-sent delta or seal upserts instead of painting a second copy.
+ const segmentCursorsRef = useRef<Map<string, SegmentCursor>>(new Map())
// Last session we applied a session.info cwd for — lets us tell an agent
// relocating the SAME session (follow it) from a session switch (don't yank).
const lastCwdInfoSessionRef = useRef<null | string>(null)
@@ -516,11 +520,17 @@ export function useMessageStream({
}, [flushQueuedDeltas])
const appendAssistantDelta = useCallback(
- (sessionId: string, delta: string, occurredAt?: number) => {
+ (sessionId: string, delta: string, occurredAt?: number, stamp?: null | SegmentStamp) => {
if (!delta) {
return
}
+ if (stamp) {
+ const admitted = admitSegmentDelta(segmentCursorsRef.current.get(sessionId), stamp, delta)
+ segmentCursorsRef.current.set(sessionId, admitted.cursor)
+ delta = admitted.text
+ }
+
queueDelta(sessionId, 'assistant', delta, occurredAt)
},
[queueDelta]
@@ -627,7 +637,17 @@ export function useMessageStream({
)
const finalizeInterimAssistantMessage = useCallback(
- (sessionId: string, text: string, occurredAt = Date.now() / 1000) => {
+ (sessionId: string, text: string, occurredAt = Date.now() / 1000, stamp?: null | SegmentStamp) => {
+ if (stamp) {
+ const admitted = admitSegmentSeal(segmentCursorsRef.current.get(sessionId), stamp)
+ segmentCursorsRef.current.set(sessionId, admitted.cursor)
+
+ // A copy of a seal this turn already applied: its bubble is on screen.
+ if (!admitted.fresh) {
+ return
+ }
+ }
+
updateSessionState(sessionId, state => {
if (state.interrupted) {
return state
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/segment-identity-replay.test.tsx b/apps/desktop/src/app/session/hooks/use-message-stream/segment-identity-replay.test.tsx
new file mode 100644
index 00000000000..74ad6f3768f
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/segment-identity-replay.test.tsx
@@ -0,0 +1,91 @@
+import { act, cleanup } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { chatMessageText } from '@/lib/chat-messages'
+
+import { type MessageStreamHarness, renderMessageStream } from './test-harness'
+import { STREAM_DELTA_FLUSH_MS } from './utils'
+
+// A turn's frames carry their wire identity (tui_gateway/stream_segments.py):
+// message.start the turn id, each delta its segment + offset, each interim the
+// segment it seals. A frame re-sent under a new seq (reconnect replay, a
+// superseded attempt re-streaming its segment) must upsert what is on screen.
+const SID = 'segment-identity-replay'
+const TURN = 'turn-a'
+const COMMENTARY = 'Commentary before the tool, streamed once.'
+const FINAL = 'A different final answer.'
+
+let stream: MessageStreamHarness
+
+const send = (type: string, payload: Record<string, unknown>) =>
+ act(() => stream.handleEvent({ payload, session_id: SID, type: type as never }))
+
+const start = (turn = TURN) => send('message.start', { turn_id: turn })
+
+const delta = (text: string, segment: number, offset: number, turn = TURN) =>
+ send('message.delta', { offset, segment, text, turn_id: turn })
+
+const interim = (text: string, segment: number, turn = TURN) =>
+ send('message.interim', { already_streamed: true, segment, text, turn_id: turn })
+
+const tool = (phase: 'start' | 'complete', id = 'call-1') =>
+ send(`tool.${phase}`, { name: 'terminal', tool_id: id, ...(phase === 'complete' ? { result: 'ok' } : {}) })
+
+const flush = () => act(async () => void (await vi.advanceTimersByTimeAsync(STREAM_DELTA_FLUSH_MS + 10)))
+
+const commentaryCopies = () =>
+ stream
+ .state()
+ .messages.filter(message => message.role === 'assistant' && !message.hidden)
+ .reduce((count, message) => count + chatMessageText(message).split(COMMENTARY).length - 1, 0)
+
+describe('a re-sent segment of a stamped turn renders once', () => {
+ afterEach(() => {
+ cleanup()
+ vi.useRealTimers()
+ })
+
+ it('drops the start + narration a superseded attempt re-sends when the tool starts', async () => {
+ vi.useFakeTimers()
+ stream = renderMessageStream(SID)
+ await start()
+ await delta(COMMENTARY.slice(0, 10), 0, 0)
+ await delta(COMMENTARY.slice(10), 0, 10)
+ await flush()
+ await interim(COMMENTARY, 0)
+ await tool('start')
+ // The replay: the same start and narration deltas again.
+ await start()
+ await delta(COMMENTARY.slice(0, 10), 0, 0)
+ await delta(COMMENTARY.slice(10), 0, 10)
+ await interim(COMMENTARY, 0)
+ await flush()
+ await tool('complete')
+ await delta(FINAL, 1, 0)
+ await flush()
+ await send('message.complete', { text: FINAL })
+
+ expect(commentaryCopies()).toBe(1)
+ })
+
+ it('keeps commentary the agent genuinely repeats in a later segment', async () => {
+ vi.useFakeTimers()
+ stream = renderMessageStream(SID)
+ await start()
+ await delta(COMMENTARY, 0, 0)
+ await flush()
+ await interim(COMMENTARY, 0)
+ await tool('start', 'call-1')
+ await tool('complete', 'call-1')
+ await delta(COMMENTARY, 1, 0)
+ await flush()
+ await interim(COMMENTARY, 1)
+ await tool('start', 'call-2')
+ await tool('complete', 'call-2')
+ await delta(FINAL, 2, 0)
+ await flush()
+ await send('message.complete', { text: FINAL })
+
+ expect(commentaryCopies()).toBe(2)
+ })
+})
diff --git a/apps/desktop/src/app/session/hooks/use-message-stream/segment-identity.ts b/apps/desktop/src/app/session/hooks/use-message-stream/segment-identity.ts
new file mode 100644
index 00000000000..0ecfffe6bb4
--- /dev/null
+++ b/apps/desktop/src/app/session/hooks/use-message-stream/segment-identity.ts
@@ -0,0 +1,81 @@
+/**
+ * Wire identity of a turn's streamed reply (tui_gateway/stream_segments.py).
+ *
+ * A prompt turn stamps its message.start with `turn_id`, every message.delta
+ * with `turn_id` + `segment` + `offset`, and every message.interim with the
+ * `turn_id` + `segment` it seals. The same frame can reach the renderer twice
+ * (a reconnect replay under new seqs, a superseded attempt re-streaming the
+ * segment it already sent, a second socket); without an identity it can only
+ * append, and the copy paints beside the original (#144609, #128158). The
+ * cursor below remembers how far each turn's reply has been applied, so a
+ * re-sent chunk or seal is an upsert of what is already there. Frames without
+ * a stamp (older backends, non-prompt emitters) pass through unchanged.
+ */
+
+export interface SegmentStamp {
+ turnId: string
+ segment: number
+ offset?: number
+}
+
+export interface SegmentCursor {
+ turnId: string
+ /** The segment deltas currently extend. */
+ segment: number
+ /** UTF-16 code units of `segment` already applied. */
+ end: number
+}
+
+const nonNegativeInt = (value: unknown): null | number =>
+ typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null
+
+/** The stamp a message.delta / message.interim payload carries, or null. */
+export function segmentStamp(payload: unknown): null | SegmentStamp {
+ const record = (payload ?? {}) as Record<string, unknown>
+ const turnId = typeof record.turn_id === 'string' ? record.turn_id : ''
+ const segment = nonNegativeInt(record.segment)
+
+ if (!turnId || segment === null) {
+ return null
+ }
+
+ const offset = nonNegativeInt(record.offset)
+
+ return offset === null ? { turnId, segment } : { turnId, segment, offset }
+}
+
+/** The part of a stamped delta not applied yet ('' when it is a re-send). */
+export function admitSegmentDelta(
+ cursor: SegmentCursor | undefined,
+ stamp: SegmentStamp,
+ text: string
+): { cursor: SegmentCursor; text: string } {
+ const offset = stamp.offset ?? 0
+ const end = offset + text.length
+
+ if (!cursor || cursor.turnId !== stamp.turnId || stamp.segment > cursor.segment) {
+ return { cursor: { turnId: stamp.turnId, segment: stamp.segment, end }, text }
+ }
+
+ if (stamp.segment < cursor.segment || end <= cursor.end) {
+ return { cursor, text: '' }
+ }
+
+ // Overlap keeps only the unseen tail; a gap (frames lost) applies whole.
+ return { cursor: { ...cursor, end }, text: text.slice(Math.max(0, cursor.end - offset)) }
+}
+
+/** Whether a stamped seal closes a segment not sealed yet, and the cursor after it. */
+export function admitSegmentSeal(
+ cursor: SegmentCursor | undefined,
+ stamp: SegmentStamp
+): { cursor: SegmentCursor; fresh: boolean } {
+ const next = { turnId: stamp.turnId, segment: stamp.segment + 1, end: 0 }
+
+ // The cursor already moved past this segment: an earlier copy of the seal did it.
+ if (cursor?.turnId === stamp.turnId && stamp.segment < cursor.segment) {
+ return { cursor, fresh: false }
+ }
+
+ return { cursor: next, fresh: true }
+}
diff --git a/apps/desktop/src/app/types.ts b/apps/desktop/src/app/types.ts
index 671de33786c..fa6a937c579 100644
--- a/apps/desktop/src/app/types.ts
+++ b/apps/desktop/src/app/types.ts
@@ -188,6 +188,9 @@ export interface ClientSessionState {
* heartbeat (#119569); when it lands it settles onto this bubble instead of
* appending a duplicate. Cleared by the next message.start or complete. */
heartbeatSettledStreamId?: null | string
+ /** `turn_id` of the newest message.start (tui_gateway/stream_segments.py): a
+ * re-sent start of the same turn is not a new occurrence. */
+ streamTurnId?: null | string
/** A blocking clarify prompt is waiting on the user for this session. Drives
* the sidebar "needs input" indicator; cleared when the turn resumes/ends. */
needsInput: boolean
diff --git a/apps/desktop/src/lib/chat-messages/types.ts b/apps/desktop/src/lib/chat-messages/types.ts
index 2473f0ce2a5..59153fdabaa 100644
--- a/apps/desktop/src/lib/chat-messages/types.ts
+++ b/apps/desktop/src/lib/chat-messages/types.ts
@@ -120,6 +120,10 @@ export type GatewayEventPayload = {
yolo?: boolean
running?: boolean
turn_started_at?: number | null
+ /** message.start / delta / interim: the prompt turn's wire identity (segment-identity.ts). */
+ turn_id?: string
+ segment?: number
+ offset?: number
cwd?: string
branch?: string
terminal_backend?: string
diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.ts
index 6e777117819..8a7e702a17c 100644
--- a/apps/shared/src/gateway-contract.generated.ts
+++ b/apps/shared/src/gateway-contract.generated.ts
@@ -5626,12 +5626,16 @@ export interface MessageStartPayload {
display_text?: string | null
notification_category?: string | null
text?: string | null
+ turn_id?: string | null
}
-/** ``message.delta``. A session-authority local-viewer turn also publishes ``text: null``: the reply segment boundary (the agent's ``stream_delta_callback(None)``, before tool lines) that closes the classic CLI's reply box. Every other viewer ignores an empty chunk. */
+/** ``message.delta``. A session-authority local-viewer turn also publishes ``text: null``: the reply segment boundary (the agent's ``stream_delta_callback(None)``, before tool lines) that closes the classic CLI's reply box. Every other viewer ignores an empty chunk. A prompt turn stamps ``turn_id`` + ``segment`` (interim seals before it) + ``offset`` (UTF-16 code units of that segment already sent): a client drops a re-sent chunk it already applied. */
export interface MessageDeltaPayload {
text: string | null
rendered?: string | null
verbose?: boolean | null
+ turn_id?: string | null
+ segment?: number | null
+ offset?: number | null
}
/** ``prompt_turn._invoke_agent._stream`` (message.delta: ``text`` + optional ``rendered``), ``agent_callbacks._agent_cbs`` (reasoning.delta / thinking.delta), ``tool_progress._progress_reasoning`` (reasoning.available). ``verbose`` rides only when the session's verbose reasoning mode is on. */
export interface StreamDeltaPayload {
@@ -5643,6 +5647,8 @@ export interface StreamDeltaPayload {
export interface MessageInterimPayload {
text: string
already_streamed: boolean
+ turn_id?: string | null
+ segment?: number | null
}
/** ``prompt_turn._complete_turn_payload`` / ``session_auto_continue._emit_terminal_turn_error`` / ``agent_callbacks._mirror_subagent_to_child`` (child watch mirror: ``text`` only) / ``compute_host_bridge`` (``text`` + ``status``). */
export interface MessageCompletePayload {
diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.json
index 6b23ca77f24..de705649271 100644
--- a/apps/shared/src/gateway-contract.openrpc.json
+++ b/apps/shared/src/gateway-contract.openrpc.json
@@ -23445,7 +23445,7 @@
},
"MessageDeltaPayload": {
"additionalProperties": false,
- "description": "``message.delta``. A session-authority local-viewer turn also publishes ``text: null``: the\nreply segment boundary (the agent's ``stream_delta_callback(None)``, before tool lines) that\ncloses the classic CLI's reply box. Every other viewer ignores an empty chunk.",
+ "description": "``message.delta``. A session-authority local-viewer turn also publishes ``text: null``: the\nreply segment boundary (the agent's ``stream_delta_callback(None)``, before tool lines) that\ncloses the classic CLI's reply box. Every other viewer ignores an empty chunk.\n\nA prompt turn stamps ``turn_id`` + ``segment`` (interim seals before it) + ``offset`` (UTF-16 code\nunits of that segment already sent): a client drops a re-sent chunk it already applied.",
"properties": {
"text": {
"anyOf": [
@@ -23481,6 +23481,42 @@
],
"default": null,
"title": "Verbose"
+ },
+ "turn_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Turn Id"
+ },
+ "segment": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Segment"
+ },
+ "offset": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Offset"
}
},
"required": [
@@ -23500,6 +23536,30 @@
"already_streamed": {
"title": "Already Streamed",
"type": "boolean"
+ },
+ "turn_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Turn Id"
+ },
+ "segment": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Segment"
}
},
"required": [
@@ -23728,6 +23788,18 @@
],
"default": null,
"title": "Text"
+ },
+ "turn_id": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Turn Id"
}
},
"title": "MessageStartPayload",
diff --git a/tests/tui_gateway/test_stream_segment_identity.py b/tests/tui_gateway/test_stream_segment_identity.py
new file mode 100644
index 00000000000..c3feeb3ce2b
--- /dev/null
+++ b/tests/tui_gateway/test_stream_segment_identity.py
@@ -0,0 +1,40 @@
+"""A prompt turn's message.* frames carry its wire identity (tui_gateway/stream_segments.py).
+
+The desktop upserts a re-sent frame by this identity instead of painting a second copy (#144609):
+every delta names its turn, segment (interim seals before it) and UTF-16 offset inside that segment,
+every interim the segment it seals.
+"""
+
+import contextlib
+from types import SimpleNamespace
+
+import tui_gateway.server as srv
+
+
+def test_deltas_and_seals_carry_turn_segment_and_utf16_offset(monkeypatch):
+ events = []
+ monkeypatch.setattr(srv, "_emit", lambda event, _sid, payload=None: events.append((event, payload)))
+ monkeypatch.setattr(srv, "_load_interim_assistant_messages", lambda: True)
+ monkeypatch.setattr(srv, "_start_usage_ticker", lambda _sid, _agent: (SimpleNamespace(set=lambda: None), SimpleNamespace(join=lambda: None)))
+
+ def run_conversation(_message, **kwargs):
+ stream = kwargs["stream_callback"]
+ stream("Looking 👀 ")
+ stream("now.")
+ agent.interim_assistant_callback("Looking 👀 now.", already_streamed=True)
+ stream("Done.")
+ return {"final_response": "Done."}
+
+ agent = SimpleNamespace(_session_title_hint="Scratch", run_conversation=run_conversation)
+ session = {"pending_title": None, "session_key": "k", "history_lock": contextlib.nullcontext(), "agent": agent}
+ st = srv._TurnRun(agent=agent, one_turn_restore=None, terminal_callback=None, receipt_committed=True)
+ srv._invoke_agent("sid", session, st, "ping", "ping", None, [], None, None)
+
+ stamps = [(e, p.get("segment"), p.get("offset")) for e, p in events if e in {"message.delta", "message.interim"}]
+ # The eye emoji is one code point but two UTF-16 units: "Looking 👀 " advances the offset by 11.
+ assert stamps == [
+ ("message.delta", 0, 0), ("message.delta", 0, 11), ("message.interim", 0, None), ("message.delta", 1, 0)]
+ turn_ids = {p["turn_id"] for e, p in events if e in {"message.delta", "message.interim"}}
+ assert turn_ids == {st.segments.turn_id}
+ assert st.segments.turn_id and srv._TurnRun(
+ agent=agent, one_turn_restore=None, terminal_callback=None, receipt_committed=True).segments.turn_id != st.segments.turn_id
diff --git a/tui_gateway/contracts/events.py b/tui_gateway/contracts/events.py
index 58e2209d206..cddb893776d 100644
--- a/tui_gateway/contracts/events.py
+++ b/tui_gateway/contracts/events.py
@@ -142,6 +142,9 @@ class MessageStartPayload(Payload):
display_text: str | None = None
notification_category: str | None = None
text: str | None = None
+ #: ``stream_segments.TurnSegments`` identity of the prompt turn; a client that sees the same id again is
+ #: looking at a re-sent frame of the turn it already has, not a new turn.
+ turn_id: str | None = None
event("message.start", MessageStartPayload,
@@ -161,9 +164,15 @@ class StreamDeltaPayload(Payload):
class MessageDeltaPayload(StreamDeltaPayload):
"""``message.delta``. A session-authority local-viewer turn also publishes ``text: null``: the
reply segment boundary (the agent's ``stream_delta_callback(None)``, before tool lines) that
- closes the classic CLI's reply box. Every other viewer ignores an empty chunk."""
+ closes the classic CLI's reply box. Every other viewer ignores an empty chunk.
+
+ A prompt turn stamps ``turn_id`` + ``segment`` (interim seals before it) + ``offset`` (UTF-16 code
+ units of that segment already sent): a client drops a re-sent chunk it already applied."""
text: str | None
+ turn_id: str | None = None
+ segment: int | None = None
+ offset: int | None = None
event("message.delta", MessageDeltaPayload, doc="One streamed chunk of the assistant reply (null text: segment boundary).")
@@ -177,6 +186,9 @@ class MessageInterimPayload(Payload):
text: str
already_streamed: bool
+ #: The turn and segment this seal closes; a re-sent seal of a closed segment is not a new bubble.
+ turn_id: str | None = None
+ segment: int | None = None
event("message.interim", MessageInterimPayload,
diff --git a/tui_gateway/prompt_turn.py b/tui_gateway/prompt_turn.py
index 67bf1e3c30a..639552cd0c6 100644
--- a/tui_gateway/prompt_turn.py
+++ b/tui_gateway/prompt_turn.py
@@ -12,6 +12,7 @@ from __future__ import annotations
import dataclasses
from .method_ctx import HandlerRegistry, bind_module
+from .stream_segments import TurnSegments
_registry = HandlerRegistry()
@@ -505,6 +506,8 @@ class _TurnRun:
prompt_text: str = ""
marker_key: str = ""
receipt_attempted: bool = False
+ #: The turn id + segment cursor stamped on this turn's message.* frames.
+ segments: TurnSegments = dataclasses.field(default_factory=TurnSegments)
def _adopt_out_of_band_turns(session: dict) -> None:
@@ -762,7 +765,7 @@ def _invoke_agent(
delta, hold["held"] = hold["held"] + delta, ""
with session["history_lock"]:
_append_inflight_delta(session, delta)
- payload = {"text": delta}
+ payload = {"text": delta, **st.segments.delta(delta)}
if streamer and (r := streamer.feed(delta)) is not None:
payload["rendered"] = r
if st.tts_queue is not None and isinstance(delta, str):
@@ -774,7 +777,8 @@ def _invoke_agent(
def _interim_assistant_cb(text: str, *, already_streamed: bool = False) -> None:
if getattr(agent, "_mute_notification_reply", False):
return
- _emit("message.interim", sid, {"text": text, "already_streamed": already_streamed})
+ _emit("message.interim", sid,
+ {"text": text, "already_streamed": already_streamed, **st.segments.seal()})
agent.interim_assistant_callback = (
_interim_assistant_cb if _load_interim_assistant_messages() else None)
# A synthesized turn is typed at turn START so a crash persist writes a timeline event,
@@ -1131,8 +1135,10 @@ def _run_prompt_submit(
"kind=%s chars=%s images=%d",
sid, session.get("session_key") or "", getattr(agent, "session_id", "") or "",
display_kind or "user", len(text) if isinstance(text, str) else "-", len(images))
+ from tui_gateway.stream_segments import TurnSegments # bound functions run in server's globals
+ segments = TurnSegments()
if not muted:
- _emit("message.start", sid)
+ _emit("message.start", sid, segments.start())
def run_body():
# RPC-dispatcher ContextVars do not follow onto this thread: rebind the transport
@@ -1142,6 +1148,7 @@ def _run_prompt_submit(
st = _TurnRun(
session["agent"], session.pop("one_turn_model_restore", None), terminal_callback,
receipt_committed=terminal_callback is None)
+ st.segments = segments
st.marker_key = _record_turn_marker(session, text, auto_continue=terminal_callback is None,
notification_category=(display_metadata or {}).get("notification_category"))
goal_followup = None
diff --git a/tui_gateway/stream_segments.py b/tui_gateway/stream_segments.py
new file mode 100644
index 00000000000..6f53f0ec207
--- /dev/null
+++ b/tui_gateway/stream_segments.py
@@ -0,0 +1,46 @@
+"""Wire identity for one turn's streamed reply.
+
+A turn's frames reach a client more than once on some roads: a reconnect replay that re-stamps
+seqs, a superseded attempt that re-streams the segment it already sent, a second socket. Without an
+identity the client can only append, so the copy paints beside the original (#144609, #128158).
+Every ``message.start`` / ``message.delta`` / ``message.interim`` of a turn therefore carries the
+turn's ``turn_id``; a delta adds its ``segment`` (how many interim seals came before it) and its
+``offset`` inside that segment, an interim the ``segment`` it seals. A client upserts by that
+identity and drops what it has already applied.
+
+``offset`` counts UTF-16 code units, the unit a JavaScript string indexes in, so an emoji or other
+astral character advances it by the same amount on both sides.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+
+def _utf16_len(text: str) -> int:
+ return len(text.encode("utf-16-le", errors="surrogatepass")) // 2
+
+
+class TurnSegments:
+ """The segment cursor of one turn: created at ``message.start``, advanced by every delta and seal."""
+
+ def __init__(self) -> None:
+ self.turn_id = uuid.uuid4().hex
+ self.segment = 0
+ self.offset = 0
+
+ def start(self) -> dict[str, Any]:
+ return {"turn_id": self.turn_id}
+
+ def delta(self, text: Any) -> dict[str, Any]:
+ stamp = {"turn_id": self.turn_id, "segment": self.segment, "offset": self.offset}
+ if isinstance(text, str):
+ self.offset += _utf16_len(text)
+ return stamp
+
+ def seal(self) -> dict[str, Any]:
+ stamp = {"turn_id": self.turn_id, "segment": self.segment}
+ self.segment += 1
+ self.offset = 0
+ return stamp