@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/channel/projection.js

@@ -0,0 +1,1031 @@
+import { replaySelectionAttachment } from './ide-selection.js';
+import { isSubagentToolName, parseJobOutputId, toolCommandOf, BACKGROUND_START_ACK, todoPanelItems } from './projection-helpers.js';
+import { ARGS_PREVIEW_LIMIT, harnessToolResultView, LOCAL_OUTPUT_LIMIT, prepareReplayEvents, preview, RESULT_PREVIEW_LIMIT, toolErrorText } from './transcript.js';
+import { estimateTokens, isTokenDelta, tokenDeltaChars, usageOutputTokens } from './usage.js';
+import { transcriptImagesOf } from '../transcript-images.js';
+import { isCompactionCheckpointSource, toolResultPayload } from '../compat/messages.js';
+import { isPeakHour } from '../../deepseekPricing.js';
+import { t } from '../../i18n.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { cleanRenderText } from '../sanitize.js';
+import { NOTICE_CELLS } from './decisions.js';
+import { markChannelReadDirty } from '../../adapter/channel/read-view.js';
+/** One authoritative reducer for both durable replay and live session events. */
+export function createChannelProjection(state, deps) {
+    /** The in-progress assistant text row; `undefined` when no step is streaming. */
+    let streaming;
+    /** The in-progress reasoning row; `undefined` when no reasoning is streaming. */
+    let reasoning;
+    /** Reasoning rows sealed by an assistant/message this turn. They stay
+     *  `streaming: true` — expanded in the transcript — until turn/end folds
+     *  them (WebUI AssistantMarkdown keepOpen parity: thinking holds open
+     *  through the whole in-flight turn, tool-call steps included). */
+    const sealedReasoning = [];
+    /** Wall-clock start of the current reasoning row (durationMs on settle). */
+    let reasoningStart = 0;
+    /** Decode-throughput fold for the current turn. DSH defines one step as
+     *  one model call plus its tools; summing only first-token → message spans
+     *  excludes tool execution and per-request TTFT from generation speed. */
+    let tpsTurn;
+    let tpsBeforeTurn;
+    let tpsTurnDecodeMs = 0;
+    let tpsTurnDecodeTokens = 0;
+    let tpsTurnSampled = false;
+    let tpsStep;
+    /** Tool cards by callId, so tool/result can settle the running card. */
+    const toolCards = new Map();
+    /**
+     * Session events are delivered live and can also be replayed around a
+     * reconnect. A repeated sealed message must not create a second assistant
+     * row for the same durable sequence number.
+     */
+    const handledAssistantMessages = new Set();
+    const handledAssistantChunks = new Set();
+    /** One Agent runs one request at a time. Durable step boundaries also let
+     *  a freshly attached projector accept chunks whose start it missed. */
+    let openStep;
+    let activeAttempt;
+    let lastStreamRevision = -1;
+    const assistantRowsByStep = new Map();
+    const lastTextDelta = new Map();
+    const stepKey = (turn, step) => `${turn}:${step}`;
+    const touchRow = (row) => { markChannelReadDirty(row); markChannelReadDirty(state.rows); };
+    const appendRow = (row) => { state.rows.push(row); markChannelReadDirty(state.rows); };
+    const removeRow = (row) => {
+        const index = state.rows.indexOf(row);
+        if (index !== -1) {
+            state.rows.splice(index, 1);
+            markChannelReadDirty(state.rows);
+        }
+        if (streaming === row)
+            streaming = undefined;
+        if (reasoning === row)
+            reasoning = undefined;
+        if (lastReasoningRow?.row === row)
+            lastReasoningRow = undefined;
+        const sealedIndex = sealedReasoning.indexOf(row);
+        if (sealedIndex !== -1)
+            sealedReasoning.splice(sealedIndex, 1);
+        lastTextDelta.delete(row);
+    };
+    const discardAttempt = (turn, step) => {
+        const key = stepKey(turn, step);
+        const row = assistantRowsByStep.get(key);
+        if (row !== undefined && row.seq === undefined) {
+            state.responseChars = Math.max(0, state.responseChars - row.text.length);
+            removeRow(row);
+            assistantRowsByStep.delete(key);
+        }
+        if (lastReasoningRow !== undefined && lastReasoningRow.turn === turn && lastReasoningRow.step === step && lastReasoningRow.row.seq === undefined) {
+            removeRow(lastReasoningRow.row);
+        }
+        if (activeAttempt !== undefined && activeAttempt.turn === turn && activeAttempt.step === step)
+            activeAttempt = undefined;
+        if (tpsStep !== undefined && tpsStep.turn === turn && tpsStep.step === step) {
+            tpsStep.firstTokenTime = undefined;
+            tpsStep.outputChars = 0;
+        }
+        updateSpinnerMode();
+    };
+    /** Durable session image blocks, loaded lazily through the attachment
+     *  store. Projection never reads pixels; the UI decodes on demand. */
+    const transcriptImages = (content) => transcriptImagesOf(content, deps.attachments);
+    /** V3 deltas are ordered by frame revision and must stay byte-exact.
+     * Legacy reconnect/proxy events may instead repeat a cumulative prefix. */
+    const appendTextDelta = (row, delta, legacy) => {
+        if (delta === '')
+            return;
+        if (!legacy) {
+            row.text += delta;
+            touchRow(row);
+            return;
+        }
+        if (lastTextDelta.get(row) === delta)
+            return;
+        lastTextDelta.set(row, delta);
+        if (delta.startsWith(row.text)) {
+            row.text = delta;
+            touchRow(row);
+            return;
+        }
+        const maxOverlap = Math.min(row.text.length, delta.length, 4096);
+        for (let size = maxOverlap; size > 0; size--) {
+            if (row.text.endsWith(delta.slice(0, size))) {
+                row.text += delta.slice(size);
+                touchRow(row);
+                return;
+            }
+        }
+        row.text += delta;
+        touchRow(row);
+    };
+    /** The host-plane tools registry (dsh-tools). Resolved once; absent in
+     *  bare embedders — every presenter call soft-fails to undefined and the
+     *  card falls back to raw text. */
+    const toolsRegistry = deps.tools;
+    /** Ask the producing tool how its call should render (diff/terminal/…).
+     *  Scoped to the live agent so preset-owned tool definitions resolve —
+     *  the dsh-host-apiproxy presenter pattern. Unknown tool, unparseable
+     *  args, or a throwing presenter all degrade to the plain text card. */
+    const presentCallView = (name, rawArgs) => {
+        try {
+            const tool = toolsRegistry?.get(name, deps.agent());
+            if (tool?.presentCall === undefined)
+                return undefined;
+            return tool.presentCall(JSON.parse(rawArgs));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /** Same for the settled result; `meta` is the tool-private presentation
+     *  payload the tool attached to its tool/result event (dsh-tool-fs reads
+     *  its result-time contextual diff back from here). */
+    const presentResultView = (name, rawArgs, data) => {
+        try {
+            // Harness goal/todo tools first: their raw JSON reads as noise in the
+            // transcript — fold recognizable shapes into a summary card before the
+            // registry gets a chance to (not) know them.
+            const local = harnessToolResultView(name, data);
+            if (local !== undefined)
+                return local;
+            const tool = toolsRegistry?.get(name, deps.agent());
+            if (tool?.presentResult === undefined)
+                return undefined;
+            return tool.presentResult(JSON.parse(rawArgs), {
+                ...toolResultPayload(data.message),
+                ...(data.meta !== undefined ? { meta: data.meta } : {}),
+            });
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // ContentBlockMap is merge-extensible: plugin-added block types are
+    // silently skipped (v1 renders text blocks only) — never crashes.
+    const textOf = (content) => (content ?? []).map(block => (block.type === 'text' ? block.text : '')).join('').trim();
+    /**
+     * Transcript-facing text of a user message: the FIRST text block only.
+     * `@`-mention attachments (issue #15) ride as later blocks — model-facing
+     * only — so joining every block would dump file contents into the bubble,
+     * the sticky header, and session titles.
+     */
+    const firstTextOf = (content) => (content ?? []).find(block => block.type === 'text')?.text.trim() ?? '';
+    const ensureStreaming = (seq) => {
+        if (streaming !== undefined)
+            return streaming;
+        // A reconnect can replay the first delta after the sealed message was
+        // already observed. Reuse that durable row instead of opening a second
+        // assistant bubble for the same event sequence.
+        const existing = seq === undefined
+            ? undefined
+            : [...state.rows].reverse().find(row => row.kind === 'assistant' && row.seq === seq);
+        if (existing !== undefined) {
+            existing.streaming = true;
+            touchRow(existing);
+            streaming = existing;
+            return existing;
+        }
+        streaming = { id: deps.rowIds.value, kind: 'assistant', text: '', streaming: true, fresh: true, ...seq !== undefined ? { seq } : {} };
+        deps.rowIds.value += 1;
+        appendRow(streaming);
+        return streaming;
+    };
+    /** Latest reasoning row keyed by its (turn, step) — lets a resumed
+     *  mid-step stream REVIVE the row the replay sealed (crash-orphan tail:
+     *  replay folds the partial row, live continuation chunks would
+     *  otherwise open a SECOND row for the same step, splitting one
+     *  thinking block in two). */
+    let lastReasoningRow;
+    const ensureReasoning = (seq, turn, step) => {
+        if (reasoning === undefined) {
+            // Same-step revive: the sealed row is this step's thinking — continue
+            // it (durationMs carried over via reasoningStart back-dating).
+            if (lastReasoningRow !== undefined &&
+                turn !== undefined &&
+                lastReasoningRow.turn === turn &&
+                lastReasoningRow.step === step) {
+                reasoning = lastReasoningRow.row;
+                reasoning.streaming = true;
+                touchRow(reasoning);
+                const sealedIdx = sealedReasoning.indexOf(reasoning);
+                if (sealedIdx !== -1)
+                    sealedReasoning.splice(sealedIdx, 1);
+                reasoningStart = Date.now() - (reasoning.durationMs ?? 0);
+                logForDebugging('thinking: revived sealed reasoning row for same step');
+                return reasoning;
+            }
+            reasoningStart = Date.now();
+            reasoning = { id: deps.rowIds.value, kind: 'reasoning', text: '', streaming: true, ...seq !== undefined ? { seq } : {} };
+            deps.rowIds.value += 1;
+            appendRow(reasoning);
+            logForDebugging('thinking: reasoning row open (expanded)');
+        }
+        if (turn !== undefined && step !== undefined) {
+            lastReasoningRow = { row: reasoning, turn, step };
+        }
+        return reasoning;
+    };
+    /** Fold the live reasoning preview the moment the model moves PAST
+     *  thinking — the answer's first text token or a tool call — not at
+     *  `assistant/message` (end of step). A long reply pushes the thinking
+     *  block into terminal scrollback long before the message seals, and
+     *  scrollback rows cannot be repainted (the cursor cannot reach them),
+     *  so a late fold leaves a stale unfolded preview frozen above the
+     *  window — the user scrolls up and the thinking looks "not folded".
+     *  Folding while the block still sits in the live window keeps the
+     *  shrink inside the diff engine's reachable region. Preview mode only
+     *  (`full` holds every block open until turn settle by design). */
+    const foldLiveReasoning = (where) => {
+        if (reasoning === undefined || state.thinkingFold !== 'preview')
+            return;
+        const duration = Math.max(0, Date.now() - reasoningStart);
+        reasoning.durationMs = duration;
+        reasoning.streaming = false;
+        touchRow(reasoning);
+        sealedReasoning.push(reasoning);
+        reasoning = undefined;
+        logForDebugging(`thinking: folded at ${where} (${duration}ms)`);
+    };
+    const settleStreaming = () => {
+        if (streaming !== undefined) {
+            streaming.streaming = false;
+            touchRow(streaming);
+        }
+        streaming = undefined;
+        const folded = sealedReasoning.length + (reasoning !== undefined ? 1 : 0);
+        for (const row of sealedReasoning) {
+            row.streaming = false;
+            touchRow(row);
+        }
+        sealedReasoning.length = 0;
+        if (reasoning !== undefined) {
+            reasoning.streaming = false;
+            reasoning.durationMs = Math.max(0, Date.now() - reasoningStart);
+            touchRow(reasoning);
+        }
+        reasoning = undefined;
+        if (folded > 0)
+            logForDebugging(`thinking: folded ${folded} reasoning row(s) at turn settle`);
+    };
+    /** Recompute the spinner phase from live row/tool state. */
+    const updateSpinnerMode = () => {
+        if (state.activeToolCount > 0) {
+            state.spinnerMode = 'tool-use';
+        }
+        else if (reasoning !== undefined) {
+            // Only LIVE reasoning counts — sealed rows stay streaming=true for
+            // transcript expansion until turn/end but the model is past thinking.
+            state.spinnerMode = 'thinking';
+        }
+        else if (streaming !== undefined) {
+            state.spinnerMode = 'responding';
+        }
+        else {
+            state.spinnerMode = 'requesting';
+        }
+    };
+    /** Fold one goal mutation into the channel's goal projection. */
+    const applyGoalChange = (change) => {
+        if (change.operation === 'clear') {
+            state.goal = undefined;
+        }
+        else if (change.goal !== undefined) {
+            state.goal = {
+                ...change.goal,
+                roundsStarted: change.roundsStarted ?? state.goal?.roundsStarted ?? 0,
+            };
+        }
+    };
+    /**
+     * Fold one goal-sourced message into the channel's goal projection.
+     * Round-zero goal messages may carry the full durable snapshot (or a clear
+     * tombstone) in their source; positive-round messages are admitted
+     * continuation prompts that only advance the rounds counter.
+     */
+    const applyGoalEvent = (event) => {
+        const source = event.data.source;
+        if (source.round > 0) {
+            // Admitted continuation round — the snapshot itself is unchanged.
+            if (state.goal !== undefined) {
+                state.goal = {
+                    ...state.goal,
+                    roundsStarted: Math.max(state.goal.roundsStarted, source.round),
+                };
+            }
+            return;
+        }
+        const change = source.change;
+        // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable replay data may not match the static type
+        if (change === undefined || change.kind !== 'goal/change')
+            return;
+        applyGoalChange(change);
+    };
+    /** Replay paints settled history without the live smooth-reveal animation. */
+    let replaying = false;
+    const replayEvents = (events) => {
+        // Event sequence numbers restart with a replacement session; reset the
+        // idempotency ledger before replay so an old session cannot suppress a
+        // legitimate message in the new transcript.
+        handledAssistantMessages.clear();
+        handledAssistantChunks.clear();
+        openStep = undefined;
+        activeAttempt = undefined;
+        lastStreamRevision = -1;
+        assistantRowsByStep.clear();
+        lastTextDelta.clear();
+        replaying = true;
+        try {
+            for (const event of prepareReplayEvents(events))
+                renderEvent(event);
+        }
+        finally {
+            replaying = false;
+        }
+    };
+    /**
+     * One live stream delta, from a 0.1.5 `agent/assistant-stream` chunk frame
+     * or a legacy `assistant/chunk` session event (pre-0.1.5 hosts and raw
+     * pre-V3 logs). `seq` exists only on the durable-event path.
+     */
+    const renderStreamChunk = (turn, step, chunk, time, seq) => {
+        if (chunk.type === 'text-delta') {
+            if (chunk.text) {
+                // Fold the thinking preview while it is still in the live
+                // window (see foldLiveReasoning) — before this text grows the
+                // transcript and pushes the block into scrollback.
+                foldLiveReasoning('first text token');
+                const key = stepKey(turn, step);
+                const row = assistantRowsByStep.get(key) ?? ensureStreaming(seq);
+                assistantRowsByStep.set(key, row);
+                streaming = row;
+                row.streaming = true;
+                touchRow(row);
+                const before = row.text.length;
+                appendTextDelta(row, chunk.text, seq !== undefined);
+                state.responseChars += Math.max(0, row.text.length - before);
+            }
+        }
+        else if (chunk.type === 'reasoning-delta') {
+            if (chunk.text) {
+                const row = ensureReasoning(seq, turn, step);
+                appendTextDelta(row, chunk.text, seq !== undefined);
+            }
+        }
+        const tps = tpsStep;
+        if (tps !== undefined &&
+            tps.turn === turn &&
+            tps.step === step &&
+            isTokenDelta(chunk)) {
+            tps.firstTokenTime ??= time;
+            tps.outputChars += tokenDeltaChars(chunk);
+            const elapsedMs = Math.max(0, time - tps.firstTokenTime);
+            if (elapsedMs > 500) {
+                const decodeMs = tpsTurnDecodeMs + elapsedMs;
+                const outputTokens = tpsTurnDecodeTokens + Math.ceil(tps.outputChars / 4);
+                state.tps = outputTokens / (decodeMs / 1000);
+            }
+        }
+        updateSpinnerMode();
+    };
+    /**
+     * Live assistant stream frame (0.1.5+): the transient per-token counterpart
+     * of the durable `assistant/message`/`assistant/attempt` settlement. Start
+     * frames own the attempt's (turn, step); a reattach rebuilds that pair
+     * from the open durable step. Settlement owns the text; an abandoned end
+     * must discard provisional rows even when no durable event was written.
+     */
+    const renderStreamFrame = (frame) => {
+        if (frame.revision <= lastStreamRevision)
+            return;
+        lastStreamRevision = frame.revision;
+        if (frame.type === 'start') {
+            if (activeAttempt !== undefined)
+                discardAttempt(activeAttempt.turn, activeAttempt.step);
+            activeAttempt = { attemptId: frame.attemptId, turn: frame.turn, step: frame.step };
+            return;
+        }
+        if (frame.type === 'end') {
+            if (activeAttempt?.attemptId !== frame.attemptId)
+                return;
+            if (frame.outcome.kind === 'abandoned' || frame.outcome.eventType === 'assistant/attempt') {
+                discardAttempt(activeAttempt.turn, activeAttempt.step);
+            }
+            activeAttempt = undefined;
+            return;
+        }
+        if (activeAttempt === undefined && openStep !== undefined) {
+            activeAttempt = { attemptId: frame.attemptId, ...openStep };
+        }
+        const where = activeAttempt?.attemptId === frame.attemptId ? activeAttempt : undefined;
+        if (where === undefined)
+            return;
+        renderStreamChunk(where.turn, where.step, frame.chunk, frame.time);
+    };
+    const renderEvent = (event) => {
+        // Top-level `goal/change` events are how the goal service actually
+        // records durable goal mutations (create/edit/pause/resume/complete/
+        // block/clear) — confirmed in production logs. The pinned peer's
+        // SessionEvent union predates the type, so admit it structurally: the
+        // goal chip and panel stay dark without this fold.
+        if (event.type === 'goal/change') {
+            applyGoalChange(event.data);
+            return;
+        }
+        switch (event.type) {
+            case 'user/message': {
+                // Both legacy and V4 checkpoints render as a folded summary rather
+                // than disappearing with the other injected context.
+                if (isCompactionCheckpointSource(event.data.source)) {
+                    const summary = textOf(event.data.content);
+                    appendRow({ id: deps.rowIds.value, kind: 'notice', text: 'Session summary is ready' });
+                    deps.rowIds.value += 1;
+                    if (summary) {
+                        appendRow({ id: deps.rowIds.value, kind: 'compact', text: summary });
+                        deps.rowIds.value += 1;
+                    }
+                    // The surface replace drops the whole pre-compact history: reset
+                    // the context accounting NOW so the status bar (ctx bar, tokens,
+                    // context-low warning) drops immediately instead of waiting for
+                    // the next request's usage event.
+                    const removed = state.contextSegments.prompt +
+                        state.contextSegments.assistant +
+                        state.contextSegments.thinking +
+                        state.contextSegments.tools;
+                    const summaryTokens = estimateTokens(summary);
+                    state.tokens.input = Math.max(0, state.tokens.input - removed) + summaryTokens;
+                    state.contextSegments = {
+                        system: state.contextSegments.system,
+                        prompt: summaryTokens,
+                        assistant: 0,
+                        thinking: 0,
+                        tools: 0,
+                    };
+                    state.lastUsage = {
+                        input: state.contextSegments.system + summaryTokens,
+                        output: 0,
+                        cacheRead: 0,
+                        cacheWrite: 0,
+                    };
+                    deps.resetContextWarning();
+                    break;
+                }
+                // Same-session goal domain: goal-sourced messages are the round
+                // driver's continuation prompts (positive rounds advance the
+                // counter); some hosts also inline the durable snapshot in a
+                // round-zero source. They are not transcript bubbles — they drive
+                // the goal panel's live projection (replayed on resume/rewind like
+                // every other event; the snapshot itself arrives as the top-level
+                // `goal/change` event admitted above).
+                if (event.data.source.kind === 'goal') {
+                    applyGoalEvent(event);
+                    break;
+                }
+                // Injected context (plugin/skill source) is not a human bubble; v1
+                // renders direct human prompts only.
+                if (event.data.source.kind !== 'user')
+                    break;
+                const text = firstTextOf(event.data.content);
+                const images = transcriptImages(event.data.content);
+                if (text || images.length > 0) {
+                    // IDE selection indicator: the delivery path remembered what this
+                    // message attached; the durable event carries the same message id.
+                    // On replay (session resumed in a NEW process) the in-memory map
+                    // starts empty, so the indicator falls back to the durable content
+                    // itself — the `<attached-file … selection>` block IS part of the
+                    // persisted event, and the session log is the source of truth
+                    // (maintainer review round 3: the indicator used to vanish after a
+                    // restart because nothing re-derived it from the event).
+                    const selectionAttached = deps.selectionAttached(event.data.id)
+                        ?? replaySelectionAttachment(event.data.content);
+                    appendRow({
+                        id: deps.rowIds.value,
+                        kind: 'user',
+                        text,
+                        ...(images.length === 0 ? {} : { images }),
+                        ...(selectionAttached === undefined ? {} : { selectionAttached }),
+                        seq: event.seq,
+                    });
+                    state.lastUserText = text || t('transcript-image-message', { count: images.length });
+                    // The context estimate counts everything sent to the model —
+                    // typed text AND the `@`-mention attachment blocks.
+                    state.contextSegments.prompt += estimateTokens(textOf(event.data.content));
+                    deps.rowIds.value += 1;
+                }
+                break;
+            }
+            case 'step/start': {
+                openStep = { turn: event.data.turn, step: event.data.step };
+                if (tpsTurn === event.data.turn) {
+                    tpsStep = {
+                        turn: event.data.turn,
+                        step: event.data.step,
+                        firstTokenTime: undefined,
+                        outputChars: 0,
+                    };
+                }
+                break;
+            }
+            case 'assistant/attempt': {
+                discardAttempt(event.data.turn, event.data.step);
+                break;
+            }
+            case 'assistant/message': {
+                if (handledAssistantMessages.has(event.seq))
+                    break;
+                handledAssistantMessages.add(event.seq);
+                // V3 embeds its complete attempt stream; older settlements may omit
+                // reasoning that is still durably recorded in assistant/chunk events.
+                const canonical = Array.isArray(event.data.stream);
+                const text = textOf(event.data.message.content);
+                const images = transcriptImages(event.data.message.content);
+                const reasoningText = event.data.message.content
+                    .map(block => (block.type === 'reasoning' ? block.text : ''))
+                    .join('');
+                const settledReasoning = lastReasoningRow !== undefined && lastReasoningRow.turn === event.data.turn && lastReasoningRow.step === event.data.step
+                    ? lastReasoningRow.row : reasoning;
+                if (settledReasoning !== undefined) {
+                    if (reasoningText === '') {
+                        if (canonical)
+                            removeRow(settledReasoning);
+                    }
+                    else {
+                        settledReasoning.text = reasoningText;
+                        settledReasoning.seq ??= event.seq;
+                        touchRow(settledReasoning);
+                    }
+                }
+                else if (reasoningText !== '') {
+                    // Replays and reattachments may not have seen any reasoning delta.
+                    // Insert before a live text row to preserve message block order.
+                    const rebuilt = {
+                        id: deps.rowIds.value,
+                        kind: 'reasoning',
+                        text: reasoningText,
+                        seq: event.seq,
+                    };
+                    deps.rowIds.value += 1;
+                    const textRow = assistantRowsByStep.get(stepKey(event.data.turn, event.data.step));
+                    const textIndex = textRow === undefined ? -1 : state.rows.indexOf(textRow);
+                    if (textIndex === -1)
+                        appendRow(rebuilt);
+                    else {
+                        state.rows.splice(textIndex, 0, rebuilt);
+                        markChannelReadDirty(state.rows);
+                    }
+                }
+                // Reasoning/tool-only steps emit no text: creating an assistant row
+                // anyway leaves an empty `●` bullet in the transcript. A pre-existing
+                // streaming row always has text (ensureStreaming is only reached on
+                // non-empty text deltas), so only create one when text arrives.
+                // Key the step→row ledger only when the event carries a durable
+                // turn/step; a message without them must never collide onto a
+                // previous step's row (a bare `undefined:undefined` key would make
+                // every turn/step-less message reuse the FIRST one's assistant row).
+                const msgTurn = event.data.turn;
+                const msgStep = event.data.step;
+                const msgKey = msgTurn !== undefined && msgStep !== undefined
+                    ? stepKey(msgTurn, msgStep)
+                    : undefined;
+                const row = (msgKey !== undefined ? assistantRowsByStep.get(msgKey) : undefined) ?? streaming ??
+                    (text || images.length > 0
+                        ? ([...state.rows].reverse().find(candidate => candidate.kind === 'assistant' && candidate.seq === event.seq) ?? ensureStreaming(event.seq))
+                        : undefined);
+                if (row !== undefined && canonical && !text && images.length === 0) {
+                    removeRow(row);
+                    if (msgKey !== undefined)
+                        assistantRowsByStep.delete(msgKey);
+                }
+                else if (row !== undefined) {
+                    if (msgKey !== undefined)
+                        assistantRowsByStep.set(msgKey, row);
+                    row.seq ??= event.seq;
+                    row.time = event.time;
+                    if (text || canonical)
+                        row.text = text;
+                    row.images = images.length === 0 ? undefined : images;
+                    row.streaming = false;
+                    // Live settles keep the smooth-reveal cursor alive (a one-shot
+                    // non-streaming delivery still paints as a flow); replayed
+                    // settles must not — the transcript would typewrite on open.
+                    if (!replaying && text)
+                        row.fresh = true;
+                    touchRow(row);
+                }
+                streaming = undefined;
+                if (reasoning !== undefined) {
+                    // Backstop fold: reasoning whose step ended with no text token
+                    // and no tool call (foldLiveReasoning handles those earlier —
+                    // while the block is still in the repaintable live window;
+                    // here a long reply may already have pushed it into scrollback,
+                    // where the shrink cannot be repainted). `full` mode
+                    // (/settings opt-in) keeps the block expanded until turn settle
+                    // — settleStreaming folds the sealed rows then.
+                    reasoning.durationMs = Math.max(0, Date.now() - reasoningStart);
+                    if (state.thinkingFold === 'preview')
+                        reasoning.streaming = false;
+                    touchRow(reasoning);
+                    sealedReasoning.push(reasoning);
+                    logForDebugging(`thinking: step sealed (${reasoning.durationMs}ms), expanded until turn/end`);
+                }
+                reasoning = undefined;
+                if (activeAttempt !== undefined && activeAttempt.turn === event.data.turn && activeAttempt.step === event.data.step)
+                    activeAttempt = undefined;
+                updateSpinnerMode();
+                const usage = event.data.usage;
+                if (usage !== undefined) {
+                    // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable replay data may lack tokens
+                    state.tokens.input += usage.inputTokens ?? 0;
+                    // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable replay data may lack tokens
+                    state.tokens.output += usage.outputTokens ?? 0;
+                    // Cache split totals feed the session cost estimate (hit-priced
+                    // input vs. uncached input) — the durable replay may lack them.
+                    state.tokens.cacheRead += usage.cacheReadTokens ?? 0;
+                    state.tokens.cacheWrite += usage.cacheWriteTokens ?? 0;
+                    // Peak/idle bucketing by the request's own time (the durable replay
+                    // replays historical events, so a resumed session prices each
+                    // request at the rate window it actually ran in — the session cost
+                    // estimate never prices the whole session at the current window).
+                    {
+                        const bucket = isPeakHour(new Date(event.time))
+                            ? state.tokens.peak
+                            : state.tokens.idle;
+                        bucket.input += usage.inputTokens ?? 0;
+                        bucket.output += usage.outputTokens ?? 0;
+                        bucket.cacheRead += usage.cacheReadTokens ?? 0;
+                        bucket.cacheWrite += usage.cacheWriteTokens ?? 0;
+                    }
+                    // The most recent request's usage describes the CURRENT context:
+                    // input (uncached) + cache hits all occupy the window. Cache hits
+                    // also drive the status-line `cache N` readout.
+                    state.lastUsage = {
+                        // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable replay data may lack tokens
+                        input: usage.inputTokens ?? 0,
+                        // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable replay data may lack tokens
+                        output: usage.outputTokens ?? 0,
+                        cacheRead: usage.cacheReadTokens ?? 0,
+                        cacheWrite: usage.cacheWriteTokens ?? 0,
+                    };
+                }
+                const tpsMessageStep = tpsStep;
+                if (tpsTurn === event.data.turn &&
+                    tpsMessageStep !== undefined &&
+                    tpsMessageStep.turn === event.data.turn &&
+                    tpsMessageStep.step === event.data.step &&
+                    tpsMessageStep.firstTokenTime !== undefined) {
+                    const outputTokens = usageOutputTokens(usage)
+                        ?? (tpsMessageStep.outputChars > 0
+                            ? Math.ceil(tpsMessageStep.outputChars / 4)
+                            : undefined);
+                    if (outputTokens !== undefined) {
+                        tpsTurnDecodeMs += Math.max(0, event.time - tpsMessageStep.firstTokenTime);
+                        tpsTurnDecodeTokens += outputTokens;
+                        tpsTurnSampled = true;
+                        if (tpsTurnDecodeMs > 0) {
+                            state.tps = tpsTurnDecodeTokens / (tpsTurnDecodeMs / 1000);
+                        }
+                    }
+                }
+                if (tpsMessageStep !== undefined &&
+                    tpsMessageStep.turn === event.data.turn &&
+                    tpsMessageStep.step === event.data.step) {
+                    tpsStep = undefined;
+                }
+                // Context-bar segmentation (pi-nano-context style): assistant text
+                // and tool calls in the assistant segment, thinking separately.
+                for (const block of event.data.message.content) {
+                    if (block.type === 'text' && block.text) {
+                        state.contextSegments.assistant += estimateTokens(block.text);
+                    }
+                    else if (block.type === 'reasoning' && block.text) {
+                        state.contextSegments.thinking += estimateTokens(block.text);
+                    }
+                }
+                break;
+            }
+            case 'tool/call': {
+                // The ask-user-question tool renders as the interactive questionnaire
+                // panel (DSH user-interaction seam), not as a tool card: the model is
+                // parked waiting for the human, so no running card, no active-tool
+                // spinner, no args noise in the transcript. The Q&A summary is pushed
+                // by the TUI once the batch is answered; tool/result for a call with
+                // no card is a no-op below.
+                if (event.data.name === 'ask_user_question')
+                    break;
+                // The Task tool's plain card is replaced by the live subagent card
+                // (Kimi Code semantics): the delegation itself renders as a subagent
+                // row, so the raw args/result card would only duplicate it. The call
+                // still runs - only its transcript rendering is suppressed.
+                if (isSubagentToolName(event.data.name)) {
+                    try {
+                        const args = JSON.parse(event.data.arguments);
+                        if (typeof args.description === 'string' && args.description)
+                            deps.pendingTaskDescriptions.push(args.description);
+                    }
+                    catch {
+                        // Unparseable args leave the queue untouched; the card falls back
+                        // to the provider label.
+                    }
+                    break;
+                }
+                // Reasoning that led to a tool call is done thinking — fold the
+                // preview now, before the tool card grows the transcript past it
+                // (see foldLiveReasoning).
+                foldLiveReasoning('tool call');
+                const card = {
+                    id: deps.rowIds.value,
+                    kind: 'tool',
+                    text: '',
+                    seq: event.seq,
+                    // Smooth-reveal participation flag: live cards animate their body
+                    // in; replayed cards (resume/rewind) paint complete.
+                    fresh: !replaying,
+                    tool: {
+                        callId: event.data.callId,
+                        name: event.data.name,
+                        argsText: preview(event.data.arguments, ARGS_PREVIEW_LIMIT),
+                        argsFull: event.data.arguments,
+                        status: 'running',
+                        callView: presentCallView(event.data.name, event.data.arguments),
+                        startedAt: Date.now(),
+                    },
+                };
+                deps.rowIds.value += 1;
+                toolCards.set(event.data.callId, card);
+                appendRow(card);
+                state.activeToolCount += 1;
+                state.contextSegments.assistant += estimateTokens(`${event.data.name}${event.data.arguments}`);
+                updateSpinnerMode();
+                break;
+            }
+            case 'tool/result': {
+                const card = toolCards.get(event.data.message.source.callId);
+                if (card !== undefined && card.tool !== undefined) {
+                    const images = transcriptImages(event.data.message.content);
+                    card.images = images.length === 0 ? undefined : images;
+                    card.tool.durationMs = Math.max(0, Date.now() - card.tool.startedAt);
+                    const payload = toolResultPayload(event.data.message);
+                    if (event.data.error !== undefined || payload.isError) {
+                        card.tool.status = 'error';
+                        const errorText = toolErrorText(event);
+                        card.tool.errorText = errorText;
+                        state.contextSegments.tools += estimateTokens(errorText);
+                    }
+                    else {
+                        card.tool.status = 'ok';
+                        const result = textOf(payload.content);
+                        card.tool.resultFull = result || undefined;
+                        card.tool.resultText = result ? preview(result, RESULT_PREVIEW_LIMIT) : undefined;
+                        // The tool's own settled-state view (applied diff, terminal
+                        // output, read content…) wins over the raw text body. argsFull
+                        // pairs the args: live cards are never folded, so it is intact.
+                        card.tool.resultView = presentResultView(card.tool.name, card.tool.argsFull ?? '', event.data);
+                        state.contextSegments.tools += estimateTokens(result);
+                        // A job_output result doubles as the job card's output feed:
+                        // the registry's read() is consuming and reserved for the
+                        // owning agent, so the UI mirrors the tail that already streams
+                        // through the transcript instead of polling the job itself.
+                        if (card.tool.name === 'job_output' && result !== '') {
+                            const id = parseJobOutputId(card.tool.argsFull);
+                            if (id !== undefined)
+                                deps.jobs.onOutputSeen(id, result, event.time ?? Date.now());
+                        }
+                        // A `started background job <id>` ack pairs the job with its
+                        // tool call: capture the FULL command from the args (the
+                        // registry label is the friendly description) for the panel.
+                        const startAck = BACKGROUND_START_ACK.exec(result);
+                        if (startAck !== null) {
+                            const command = toolCommandOf(card.tool.argsFull);
+                            if (command !== undefined)
+                                deps.jobs.onStarted(startAck[1], command);
+                        }
+                    }
+                    state.activeToolCount = Math.max(0, state.activeToolCount - 1);
+                    // The card is settled: no later event looks it up by callId, so
+                    // drop the index entry. The card itself stays in state.rows
+                    // (bounded by MAX_ROWS + foldRows, which also drops the full
+                    // args/result payloads of folded cards).
+                    toolCards.delete(event.data.message.source.callId);
+                    touchRow(card);
+                    updateSpinnerMode();
+                }
+                break;
+            }
+            case 'step/end': {
+                if (openStep !== undefined && openStep.turn === event.data.turn && openStep.step === event.data.step)
+                    openStep = undefined;
+                if (tpsStep !== undefined &&
+                    tpsStep.turn === event.data.turn &&
+                    tpsStep.step === event.data.step) {
+                    tpsStep = undefined;
+                }
+                break;
+            }
+            case 'turn/start': {
+                deps.inputConvergence.cancelInFlight = false;
+                state.cancelPending = false;
+                state.working = true;
+                state.turnStart = Date.now();
+                state.responseChars = 0;
+                state.spinnerMode = 'requesting';
+                // Keep the prior turn visible until this turn produces a measurable
+                // decode span, while starting a fresh weighted step fold.
+                tpsBeforeTurn = state.tps;
+                tpsTurn = event.data.turn;
+                tpsTurnDecodeMs = 0;
+                tpsTurnDecodeTokens = 0;
+                tpsTurnSampled = false;
+                tpsStep = undefined;
+                break;
+            }
+            case 'turn/end': {
+                if (activeAttempt !== undefined)
+                    discardAttempt(activeAttempt.turn, activeAttempt.step);
+                openStep = undefined;
+                deps.inputConvergence.cancelInFlight = false;
+                state.cancelPending = false;
+                settleStreaming();
+                state.working = false;
+                state.activeToolCount = 0;
+                if (tpsTurn !== undefined && tpsTurn === event.data.turn) {
+                    if (tpsTurnSampled && tpsTurnDecodeMs > 0) {
+                        const turnTps = tpsTurnDecodeTokens / (tpsTurnDecodeMs / 1000);
+                        state.tps = turnTps;
+                        state.tpsSamples.push({ tps: turnTps, at: event.time });
+                        if (state.tpsSamples.length > 500)
+                            state.tpsSamples.shift();
+                    }
+                    else {
+                        // Do not leave a chars/4 live estimate behind when no completed
+                        // decode sample exists for this turn.
+                        state.tps = tpsBeforeTurn;
+                    }
+                    tpsTurn = undefined;
+                    tpsStep = undefined;
+                    tpsTurnDecodeMs = 0;
+                    tpsTurnDecodeTokens = 0;
+                    tpsTurnSampled = false;
+                }
+                const reason = event.data.reason;
+                if (reason.kind === 'completed') {
+                    // Replay drains a resumed session's history through the projector;
+                    // its totals describe the past, not a live context-low state.
+                    if (!replaying)
+                        deps.checkContextWarning();
+                    break;
+                }
+                if (reason.kind === 'aborted' || reason.kind === 'interrupted') {
+                    // `Agent.cancel()` closes the turn as `aborted`; `interrupted`
+                    // only appears for crash-orphaned turns. Both user-interruption
+                    // paths render as a distinct dim row.
+                    appendRow({
+                        id: deps.rowIds.value,
+                        kind: 'interrupt',
+                        text: t('interrupted-by-user') + t('interrupted-ask-next'),
+                    });
+                    deps.rowIds.value += 1;
+                    break;
+                }
+                // The notice renders as a single-line Divider title: error.message
+                // can carry newlines/control chars, and an embedded \n splits the
+                // rule across rows. cleanRenderText is the render-path single-line
+                // contract (sessionTree's preview() folds likewise for the tree).
+                const detail = reason.kind === 'error' ? cleanRenderText(reason.error.message, NOTICE_CELLS) : '';
+                appendRow({ id: deps.rowIds.value, kind: 'notice', text: `turn ${reason.kind}${detail ? ` · ${detail}` : ''}` });
+                deps.rowIds.value += 1;
+                // Historical failure notices belong to the transcript row above;
+                // re-raising them as a live toast on every /resume re-alarmes the
+                // user over a turn that already ended.
+                if (!replaying)
+                    deps.notify(t('turn-failed', { detail: detail ? ` · ${detail}` : '' }), { color: 'error', timeoutMs: 8000 });
+                break;
+            }
+            case 'request/context':
+                // Adapter-advertised context capacity; drives the context-low
+                // warning when the route reports one.
+                if (event.data.contextWindow !== undefined) {
+                    state.contextWindow = event.data.contextWindow;
+                }
+                break;
+            case 'system/message': {
+                // V3 system prompts are surface nodes, not header fields: the latest
+                // node holds the active instructions (an empty render clears them).
+                // The context bar's system segment tracks that live text.
+                state.contextSegments.system = estimateTokens(textOf(event.data.message.content));
+                break;
+            }
+            case 'request/header': {
+                // Reasoning effort readout (status line): the header carries the
+                // conversation's call config (provider/model/effort/sampling). The
+                // system prompt moved out of the header at V3 (see system/message);
+                // pre-V3 logs still carry it, admitted structurally below.
+                // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable session data may lack header config
+                const effort = event.data.header.config?.reasoningEffort;
+                if (typeof effort === 'string') {
+                    state.reasoningEffort = effort;
+                }
+                const legacySystem = event.data.header.system;
+                if (typeof legacySystem === 'string') {
+                    state.contextSegments.system = estimateTokens(legacySystem);
+                }
+                break;
+            }
+            case 'session/title':
+                state.sessionTitle = event.data.title;
+                break;
+            default:
+                // Pre-0.1.5 live streams and raw pre-V3 logs carry per-token chunks
+                // as durable session events; 0.1.5 moved live chunks to transient
+                // `agent/assistant-stream` frames (renderStreamFrame) and compacts the
+                // durable record into `assistant/message.stream`. Match by name so the
+                // current union (which no longer lists the type) stays compile-clean.
+                if (event.type === 'assistant/chunk') {
+                    if (handledAssistantChunks.has(event.seq))
+                        break;
+                    handledAssistantChunks.add(event.seq);
+                    const data = event.data;
+                    renderStreamChunk(data.turn, data.step, data.chunk, event.time, event.seq);
+                    break;
+                }
+                // dsh-tool-todo owns this optional module augmentation in alpha.2.
+                // Match by name so the TUI remains loadable without that plugin.
+                if (event.type === 'todo/write') {
+                    const todos = todoPanelItems(event.data);
+                    if (todos !== undefined)
+                        state.todos = todos;
+                    break;
+                }
+                // Logged preset switch (blank sessions only, issue #8): a transcript
+                // marker so a replayed log shows which composition produced the
+                // turns after it. Not in dsh-session's typed union — matched here by
+                // name, like the other plugin-defined events above.
+                if (event.type === 'agent-preset/selected') {
+                    const data = event.data;
+                    const recordedPreset = typeof data.agentPreset === 'string' ? data.agentPreset : undefined;
+                    const renamedOfficialPreset = (recordedPreset === 'code' && state.agentPreset === 'ptc') ||
+                        (recordedPreset === 'ptc' && state.agentPreset === 'code');
+                    const preset = renamedOfficialPreset && state.agentPreset !== undefined
+                        ? state.agentPreset
+                        : recordedPreset ?? 'unknown';
+                    appendRow({
+                        id: deps.rowIds.value,
+                        kind: 'notice',
+                        text: t('agent-preset-switched', { preset }),
+                    });
+                    deps.rowIds.value += 1;
+                    break;
+                }
+                // `/color` accent (dsh-tui plugin event, replayed on resume/rewind
+                // like session/title): last write wins, '' clears to the default.
+                if (event.type === 'session/color') {
+                    const data = event.data;
+                    state.sessionColor = typeof data.color === 'string' ? data.color : '';
+                    break;
+                }
+                // Custom plugin events (tuiRenderers seam): a registered renderer
+                // maps the payload to text rows — title as a local row, body as
+                // preview-clipped local-output rows, same shape pushLocal uses.
+                // Runs on the live stream AND on replay (resume/rewind), so the
+                // projection must stay total; the runtime isolates renderer
+                // crashes per type.
+                if (deps.renderer !== undefined) {
+                    const rendered = deps.renderer.render(event.type, event.data);
+                    if (rendered !== undefined) {
+                        if (rendered.title !== undefined && rendered.title !== '') {
+                            appendRow({ id: deps.rowIds.value, kind: 'local', text: rendered.title });
+                            deps.rowIds.value += 1;
+                        }
+                        for (const line of rendered.lines) {
+                            appendRow({
+                                id: deps.rowIds.value,
+                                kind: 'local-output',
+                                text: preview(String(line), LOCAL_OUTPUT_LIMIT),
+                            });
+                            deps.rowIds.value += 1;
+                        }
+                    }
+                }
+                break;
+        }
+    };
+    function reset() {
+        streaming = undefined;
+        reasoning = undefined;
+        sealedReasoning.length = 0;
+        lastReasoningRow = undefined;
+        toolCards.clear();
+        handledAssistantMessages.clear();
+        handledAssistantChunks.clear();
+        openStep = undefined;
+        activeAttempt = undefined;
+        lastStreamRevision = -1;
+        assistantRowsByStep.clear();
+        lastTextDelta.clear();
+        tpsTurn = undefined;
+        tpsStep = undefined;
+        tpsTurnDecodeMs = 0;
+        tpsTurnDecodeTokens = 0;
+        tpsTurnSampled = false;
+    }
+    return { reset, replayEvents, renderEvent, renderStreamFrame, settleStreaming, updateSpinnerMode, presentCallView, presentResultView, textOf, firstTextOf };
+}