feat(protocol): carry reasoning, and show it in the desktop

The protocol carried reasoningTokens and nothing else, so DeepSeek's reasoner
produced its most distinctive output and every client dropped it. The CLI got
this in #218; the desktop could not, because there was nothing on the wire to
render.

Adds a `reasoning.delta` transient event behind a `reasoningDeltas` capability.
Separate from `item.delta` rather than a flag on it: reasoning is not the
answer, it is never persisted as a completed item, and a client that doesn't
understand the type has to be able to drop it rather than accidentally render
it as assistant text.

The app-server forwards the agent loop's thinking_delta events; the desktop
projects them onto the assistant turn as a distinct `reasoning` field — kept
out of `text` precisely so it can be rendered as its own channel — and shows a
collapsed `▸ thinking · N lines` block above the answer. Collapsed because
reasoner output is long and is not the response; the line count is there
because while a turn streams it is often the only thing to look at.

VS Code and the LSP bridge forward protocol events unchanged, so they receive
the new event without changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: t

apps/desktop/e2e/desktop-preview.spec.ts

@@ -48,6 +48,13 @@ test('resumes a thread and completes an approval-gated protocol turn', async ({
   const approve = page.getByRole('button', { name: /^Approve \(↵\)$/ });
   await expect(approve).toBeVisible();
   await expect(main.getByText(/I’ll update the game safely\./)).toBeVisible();
+
+  // Reasoning arrives as its own channel: collapsed, not mixed into the answer.
+  const reasoning = main.locator('details.reasoning').first();
+  await expect(reasoning).toBeVisible();
+  await expect(reasoning.getByText(/The boss needs a phase field\./)).toBeHidden();
+  await reasoning.getByText('thinking').click();
+  await expect(reasoning.getByText(/The boss needs a phase field\./)).toBeVisible();
   await expect(main.locator('.tool-card').filter({ hasText: 'Edit' }).last()).toBeVisible();
 
   await approve.click();

apps/desktop/src/index.css

@@ -1973,3 +1973,40 @@ select {
 .ch-text {
   overflow-x: auto;
 }
+
+/* ── Reasoning ───────────────────────────────────────────────────────────
+   A dim, collapsed side channel above the answer: reasoner output is long and
+   is not the response, but dropping it entirely hid the most useful thing
+   DeepSeek's reasoner emits. */
+.reasoning {
+  margin: 0 0 8px;
+  border-left: 2px solid var(--line);
+  padding-left: 10px;
+}
+.reasoning > summary {
+  cursor: pointer;
+  color: var(--text-3);
+  font-size: 11.5px;
+  list-style: none;
+  user-select: none;
+}
+.reasoning > summary::-webkit-details-marker {
+  display: none;
+}
+.reasoning > summary::before {
+  content: '▸ ';
+}
+.reasoning[open] > summary::before {
+  content: '▾ ';
+}
+.reasoning-meta {
+  opacity: 0.7;
+}
+.reasoning-body {
+  margin-top: 6px;
+  color: var(--text-3);
+  font-size: 12px;
+  white-space: pre-wrap;
+  max-height: 320px;
+  overflow-y: auto;
+}

apps/desktop/src/lib/protocol-agent.test.ts

@@ -27,6 +27,7 @@ class FakeTransport implements ProtocolTransport {
         structuredToolEvents: true,
         interactiveRequests: true,
         reviewActions: true,
+        reasoningDeltas: true,
         configDiagnostics: true,
         diagnosticExport: true,
         workspaceDiff: true,

apps/desktop/src/lib/protocol-agent.ts

@@ -210,6 +210,14 @@ export class DesktopProtocolAgent {
       case 'item.delta':
         this.emit({ kind: 'event', turnId: event.turnId, type: 'text_delta', text: event.delta });
         break;
+      case 'reasoning.delta':
+        this.emit({
+          kind: 'event',
+          turnId: event.turnId,
+          type: 'thinking_delta',
+          text: event.delta,
+        });
+        break;
       case 'tool.started':
         this.emit({
           kind: 'event',

apps/desktop/src/lib/repl-stream.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import {
+  appendReasoningDelta,
   appendTextDelta,
   appendToolUse,
   attachToolResult,
@@ -279,5 +280,36 @@ describe('threadReviewItems', () => {
     });
     expect(findings).toEqual([{ findingId: 'f1' }]);
     expect(actions).toEqual([{ actionId: 'a1', kind: 'apply' }]);
+describe('appendReasoningDelta', () => {
+  it('opens a turn when reasoning arrives before any answer text', () => {
+    const msgs = appendReasoningDelta([], 'first thought');
+    expect(msgs).toHaveLength(1);
+    const a = msgs[0] as AssistantMsg;
+    expect(a.turn.reasoning).toBe('first thought');
+    expect(a.turn.text).toBe('');
+    expect(a.turn.streaming).toBe(true);
+  });
+
+  it('accumulates into the open turn without touching the answer', () => {
+    let msgs = appendReasoningDelta([], 'a');
+    msgs = appendReasoningDelta(msgs, 'b');
+    msgs = appendTextDelta(msgs, 'answer');
+    const a = msgs[0] as AssistantMsg;
+    expect(a.turn.reasoning).toBe('ab');
+    expect(a.turn.text).toBe('answer');
+    expect(msgs).toHaveLength(1);
+  });
+
+  it('starts a new turn when the previous one has finished', () => {
+    let msgs = appendTextDelta([], 'done');
+    msgs = finalizeStreaming(msgs);
+    msgs = appendReasoningDelta(msgs, 'next turn thinking');
+    expect(msgs).toHaveLength(2);
+    expect((msgs[1] as AssistantMsg).turn.reasoning).toBe('next turn thinking');
+  });
+
+  it('does not leak reasoning into the answer text', () => {
+    const msgs = appendTextDelta(appendReasoningDelta([], 'secret plan'), 'visible');
+    expect((msgs[0] as AssistantMsg).turn.text).toBe('visible');
   });
 });

apps/desktop/src/lib/repl-stream.ts

@@ -20,6 +20,13 @@ export interface ToolInvocation {
 
 export interface AssistantTurn {
   text: string;
+  /**
+   * The model's reasoning for this turn, when it produces any. Kept separate
+   * from `text` so it can be rendered as a distinct, collapsible channel — it
+   * is not the answer, and concatenating it into the answer is how it used to
+   * get dropped instead.
+   */
+  reasoning?: string;
   /** Tool calls interleaved during this turn — rendered as cards after the text. */
   tools: ToolInvocation[];
   streaming: boolean;
@@ -64,6 +71,28 @@ export function appendTextDelta(msgs: Msg[], delta: string): Msg[] {
   return [...msgs, { role: 'assistant', turn: { text: delta, tools: [], streaming: true } }];
 }
 
+/**
+ * Append a reasoning delta to the open assistant turn, opening one if needed.
+ * Reasoning usually arrives *before* any answer text, so this has to be able to
+ * start the turn on its own.
+ */
+export function appendReasoningDelta(msgs: Msg[], delta: string): Msg[] {
+  const idx = lastAssistantIndex(msgs);
+  const target = idx === -1 ? null : (msgs[idx] as AssistantMsg);
+  if (target && target.turn.streaming) {
+    const copy = [...msgs];
+    copy[idx] = {
+      role: 'assistant',
+      turn: { ...target.turn, reasoning: (target.turn.reasoning ?? '') + delta },
+    };
+    return copy;
+  }
+  return [
+    ...msgs,
+    { role: 'assistant', turn: { text: '', reasoning: delta, tools: [], streaming: true } },
+  ];
+}
+
 /** Append a tool invocation to the open assistant turn (same anti-split rule). */
 export function appendToolUse(msgs: Msg[], tool: ToolInvocation): Msg[] {
   const idx = lastAssistantIndex(msgs);

apps/desktop/src/preview-app.tsx

@@ -271,6 +271,7 @@ async function handleProtocolRequest(request: ProtocolRequest): Promise<void> {
           structuredToolEvents: true,
           interactiveRequests: true,
           reviewActions: true,
+          reasoningDeltas: true,
           workspaceDiff: true,
           configDiagnostics: true,
         },
@@ -396,6 +397,13 @@ async function handleProtocolRequest(request: ProtocolRequest): Promise<void> {
       // Emit before the response to exercise the renderer's fast-turn buffer.
       await sendEvent({ type: 'turn.started', threadId: activeThreadId, turn: activeTurn });
       await respond(activeTurn);
+      await sendEvent({
+        type: 'reasoning.delta',
+        threadId: activeThreadId,
+        turnId,
+        itemId: 'assistant-reasoning',
+        delta: 'The boss needs a phase field.\nChecking how spawnBoss reads it.',
+      });
       await sendEvent({
         type: 'item.delta',
         threadId: activeThreadId,

apps/desktop/src/screens/Repl.tsx

@@ -46,6 +46,7 @@ import { projectName } from '../lib/project.js';
 import { useVoice } from '../lib/use-voice.js';
 import { insertTranscript } from '../lib/voice.js';
 import {
+  appendReasoningDelta,
   appendTextDelta,
   appendToolUse,
   attachToolResult,
@@ -366,6 +367,9 @@ export function ReplScreen({
         case 'text_delta':
           setMessages((m) => appendTextDelta(m, e.text ?? ''));
           break;
+        case 'thinking_delta':
+          setMessages((m) => appendReasoningDelta(m, e.text ?? ''));
+          break;
         case 'tool_use': {
           const name = e.name ?? '?';
           const input = e.input ?? {};
@@ -1123,6 +1127,7 @@ function renderMessage(
       <div className="body">
         <div className="author">DeepCode</div>
         <div className="content">
+          {m.turn.reasoning ? <ReasoningBlock text={m.turn.reasoning} /> : null}
           {m.turn.text}
           {m.turn.streaming && isActive && <span className="streaming-cursor" />}
           {m.turn.tools.map((t) => (
@@ -1191,3 +1196,27 @@ function abbreviatePath(p: string): string {
 function truncate(s: string, n: number): string {
   return s.length > n ? s.slice(0, n) + '…\n[truncated]' : s;
 }
+
+/**
+ * The model's reasoning, as a collapsed side channel.
+ *
+ * Collapsed by default: reasoner output is long and is not the answer. Open on
+ * click, and while a turn is still streaming it is often the only thing to look
+ * at, so the summary line reports its length rather than staying silent.
+ */
+function ReasoningBlock({ text }: { text: string }): JSX.Element {
+  const [open, setOpen] = useState(false);
+  const lines = text.split('\n').length;
+  return (
+    <details className="reasoning" open={open} onToggle={(e) => setOpen(e.currentTarget.open)}>
+      <summary>
+        thinking
+        <span className="reasoning-meta">
+          {' · '}
+          {lines} line{lines === 1 ? '' : 's'}
+        </span>
+      </summary>
+      <div className="reasoning-body">{text}</div>
+    </details>
+  );
+}

apps/lsp/src/handler.test.ts

@@ -22,6 +22,7 @@ const capabilities: InitializeResult = {
     structuredToolEvents: true,
     interactiveRequests: true,
     reviewActions: true,
+    reasoningDeltas: true,
     configDiagnostics: true,
     diagnosticExport: true,
     workspaceDiff: true,

apps/server/src/runtime-executor.ts

@@ -134,6 +134,12 @@ export class RuntimeHostExecutor implements TurnExecutor {
             case 'text_delta':
               args.publishDelta(streamingItemId, event.text);
               break;
+            case 'thinking_delta':
+              // Reasoning went nowhere: the protocol carried only
+              // reasoningTokens, so DeepSeek's reasoner produced its most
+              // useful output and every client dropped it.
+              args.publishReasoning(`${streamingItemId}-reasoning`, event.text);
+              break;
             case 'tool_use':
               args.publishToolStarted(event.id, event.name, event.input);
               break;