vscode-cowriting-plugin-content/specs/coauthoring-live-progress.md

---
status: graduated
---
# Solution Design: Live Turn Progress (#60)

| | |
| --- | --- |
| **Author(s)** | Ben Stull (with Claude) |
| **Reviewers / approvers** | Ben Stull |
| **Status** | `graduated` |
| **Version** | v0.1.0 |
| **Source artifacts** | Feature `benstull/vscode-cowriting-plugin#60` (Show Claude's live output/progress during the "asking Claude…" status, `type/feature`, `priority/P1`) · Capture session `vscode-cowriting-plugin-0054` (2026-06-15) · Brainstorming session `vscode-cowriting-plugin-0055` · Builds on (all shipped): the LiveTurn machine-edit ingress (`liveTurn.ts`, INV-8/9), F4 `#12` (propose/accept seam), F10 `#29` (interactive review preview), F11 `#43` (preview toolbar + `editDocument`/`runEditAndPropose`) · Parent specs (graduated): `coauthoring-inner-loop.md`, `coauthoring-propose-accept.md`, `coauthoring-rendered-preview.md`, `coauthoring-document-edit-flow.md` · Lineage: `ben.stull/rfc-app#48` |

**Change log**

| Date | Version | Change | By |
| --- | --- | --- | --- |
| 2026-06-22 | v0.1.0 | Initial draft — brainstorming session 0055. Three forks locked with the operator: **(1) surface** = the existing "asking Claude…" notification carries a live **activity line** *plus* a host **OutputChannel** streaming the full assistant text; **(2) content** = activity (`thinking…`/`writing… (N chars)`/`running <tool>…`) **+ running token count**; **(3) cancellation** = reflect aborted/failed states **and** add a cancel button wired to `agent.abort()`. Two sub-decisions confirmed: OutputChannel auto-reveals (preserveFocus) on first text delta, gated by a `cowriting.liveProgress.revealOutput` setting (default on); the channel **appends** per-turn (with a header), doubling as a debug log. | Ben Stull + Claude |

---

## 1. Business Context

### 1.1 Executive Summary

When the writer asks Claude to edit, the plugin shows one static notification —
*"Cowriting: asking Claude…"* — and then nothing until the whole turn resolves.
Both edit entry points (`editSelection` in `extension.ts:232` and the preview's
`askClaude` in `trackChangesPreview.ts:232`) `await` the turn as **one opaque
promise** (`liveTurn.ts` `runEditTurn` → `agent.run()`). For anything past a
trivial edit this is a black box: the writer can't tell whether Claude is
thinking, reading, partway through writing, or stuck — and a long edit feels like
the tool hung.

The fix is small and almost entirely *additive observability*: `@cline/sdk`
**already streams** everything we need (`assistant-text-delta`,
`tool-started|finished`, `usage-updated`, lifecycle events) via
`agent.subscribe(listener)`, and exposes `agent.abort()` for cancellation — the
extension just never subscribes (`liveTurn.ts` constructs the Agent with no
hook). This design wires that stream to the existing notification (a live
**activity line** + running **token count**), mirrors the full assistant text
into a host **OutputChannel** so the writer can *read it forming*, and makes the
notification **cancellable**. The final result path — `runEditTurn` →
`runEditAndPropose` → F4 proposals — is **untouched**.

### 1.2 Background

The plugin's machine-edit ingress is `LiveTurn` (`liveTurn.ts`, spec
`coauthoring-inner-loop.md` §6.2): one `@cline/sdk` Agent turn on the built-in
`claude-code` provider (INV-8 — the extension holds no credentials; it rides the
operator's local Claude Code login). The turn's result feeds the F4 propose/accept
seam (`coauthoring-propose-accept.md`) and is surfaced in the F10/F11 interactive
review preview. `liveTurn.ts` is **deliberately `vscode`-free** (its module header
says so) so the SDK ingress stays independent of the editor host.

Two gestures invoke a turn, both wrapping it in `vscode.window.withProgress(…
"asking Claude…")`:

- **`editSelection`** (`extension.ts`) — selection → one single-range proposal.
- **preview `askClaude`** (`trackChangesPreview.ts`) — selection or whole
  document → one proposal (range) or one-per-changed-block (document, INV-39).

The preview path runs the turn through an **injectable** seam — `editTurn`
(`trackChangesPreview.ts:56`, type `EditTurn`) — so host E2E can stub the LLM (no
Claude in CI). This design widens that seam without breaking the stub.

### 1.3 Who feels it & why it's P1

The **human coauthor** — anyone who asks Claude to edit and waits for the turn,
most acutely on longer/slower edits. It is **P1** because the opaque wait hurts
*every* Claude turn (the core gesture of the tool), the enabling stream already
exists (low cost), and visible progress materially raises trust ("the tool is
alive and on task"). WSJF (issue #60): Value 6 · TC 3 · OE 4 ÷ Size 4 ≈ 3.25.

---

## 2. Product Design

### 2.1 The experience

During a turn, the writer sees **two coordinated surfaces**, both tied to the
existing "asking Claude…" status — no new window, no webview change:

1. **The notification line (legible motion + scale).** Below the
   "Cowriting: asking Claude…" title, a live activity line that updates as events
   arrive:

   | State | Line |
   | --- | --- |
   | before first output | `thinking…` |
   | streaming text | `writing… (412 chars)` |
   | streaming text + usage seen | `writing… · 1.2k tokens` |
   | a tool is running | `running read_file…` |

   The line shows the **current phase** and, once a `usage-updated` event has
   arrived, the **running token total** (input + output). `chars` and `tokens`
   render together when both are known (`writing… (412 chars) · 1.2k tokens`).

2. **The OutputChannel (read it forming).** A single shared `"Cowriting"` output
   channel receives the **full assistant text** as it streams, under a per-turn
   header `── asking: <instruction> ──`. On the **first** text delta the channel
   reveals itself **without stealing focus** (`show(true)`), so the writer can
   start reading the output before the turn finishes. Auto-reveal is gated by a
   setting `cowriting.liveProgress.revealOutput` (default `true`) for writers who
   prefer to open it manually.

The notification is **cancellable** (`✕`): clicking it aborts the turn
(`agent.abort()`); the status resolves to **"cancelled"** (not a frozen spinner,
not a "failed" error), and **no proposal is created**. If the turn *fails*, the
existing error path shows the error (no longer a frozen "asking Claude…").

### 2.2 What this is *not* (non-goals — from #60)

- **Not a chat/transcript panel.** This is *in-flight progress*, not a persistent
  conversation history surface. (The OutputChannel's append-log is a debug
  convenience, not a product history feature.)
- **Not streaming into the document.** The result still lands as F4 proposals
  exactly as today; only *observation* is added.
- **Not a cancellation feature in its own right.** The `✕` button + abort wiring
  are the cheap, in-scope *reflection* of cancel; rich cancel controls (partial
  apply, resume, queueing) are out of scope.
- **Not surfacing reasoning text.** `assistant-reasoning-delta` is collapsed to a
  generic `thinking…`; the chain-of-thought text is **not** shown (kept the
  notification/OutputChannel uncluttered; operator fork).

### 2.3 Surfaces considered & rejected

| Surface | Why not (as the *primary*) |
| --- | --- |
| **Webview relay** (into the preview) | The `editSelection` path has **no** webview; can't cover both entry points uniformly (acceptance requires both). |
| **Status-bar item only** | One terse line; no room for streamed text; weaker "what is it doing" signal than the in-status notification line. |
| **OutputChannel only** (notification stays a plain spinner) | The "in/alongside the asking-Claude status" signal weakens — the writer must open the Output panel to learn anything. |

Chosen: **notification activity-line (primary, in-status) + OutputChannel
(secondary, full text)** — covers both call sites, no new network/webview surface
(INV-21/INV-45), and delivers both "see motion" and "read output as it forms."

---

## 3. Engineering Design

### 3.1 Architecture — three units

```
@cline/sdk Agent events                 (raw AgentRuntimeEvent stream)
        │  agent.subscribe(listener)
        ▼
┌─────────────────────────┐   pure, vscode-free, SDK-free
│ turnProgress.ts (NEW)   │   reduce(state, event) → TurnProgressSnapshot
│  the reducer (INV-46)   │
└─────────────────────────┘
        │  TurnProgressSnapshot
        ▼
┌─────────────────────────┐   vscode-free (INV-43)
│ liveTurn.ts runEditTurn │   subscribe → reduce → onProgress(snapshot);
│  (EXTENDED)             │    signal?.abort → agent.abort(); result UNCHANGED
└─────────────────────────┘
        │  onProgress(snapshot)   +  AbortSignal in
        ▼
┌─────────────────────────┐   the two UI call sites (relay only)
│ extension.ts:editSelection │  format notification line · append OutputChannel ·
│ trackChangesPreview:askClaude │ withProgress({cancellable}) · token→AbortController
└─────────────────────────┘
```

The decisive layering rule: **progress flows *out* of `liveTurn` as a domain
`TurnProgressSnapshot`; cancel flows *in* as a web-standard `AbortSignal`.** No
`vscode` import is added to `liveTurn.ts` or `turnProgress.ts` (INV-43).

### 3.2 `src/turnProgress.ts` (new, pure) — INV-46

The reducer owns *all* event→state logic so the call sites stay dumb (format +
relay only) and the logic is unit-tested in isolation.

```ts
export interface TurnProgressSnapshot {
  phase: "thinking" | "writing" | "tool";
  tool?: string;        // present iff phase === "tool"
  chars: number;        // accumulated assistant-text length so far
  tokens?: number;      // running total (input+output); undefined until first usage event
  textDelta?: string;   // the new assistant-text chunk since the last snapshot
}

// Opaque carried state; start from createTurnProgressState().
export interface TurnProgressState { /* phase, chars, tokens, toolDepth/name */ }
export function createTurnProgressState(): TurnProgressState;

// Pure: fold one SDK event into the state, returning the next state and the
// snapshot to emit (or undefined for events that don't change the surface).
export function reduceTurnProgress(
  state: TurnProgressState,
  event: AgentRuntimeEvent,   // imported as a TYPE only from @cline/shared
): { state: TurnProgressState; snapshot?: TurnProgressSnapshot };
```

Event mapping (the relevant `AgentRuntimeEvent` members):

| SDK event | Effect on snapshot |
| --- | --- |
| `run-started` / `turn-started` | `phase: "thinking"` |
| `assistant-text-delta` | `phase: "writing"`, `chars = accumulatedText.length`, `textDelta = text` |
| `assistant-reasoning-delta` | `phase: "thinking"` (text **not** surfaced) |
| `tool-started` / `tool-updated` | `phase: "tool"`, `tool = toolCall.name` |
| `tool-finished` | revert `phase` to `writing` if any text seen, else `thinking` |
| `usage-updated` | `tokens = usage` total (input+output) |
| `turn-finished` / `run-finished` / `run-failed` | no snapshot (resolution handled by the turn promise) |

`AgentRuntimeEvent` is imported **type-only** (`import type`) — `turnProgress.ts`
has **no runtime dependency** on the SDK and no `vscode` import, so it is a pure,
fast unit (INV-43/46). Tool concurrency is tracked by name/depth so overlapping
`tool-started`/`tool-finished` pairs resolve the phase correctly.

### 3.3 `liveTurn.ts` `runEditTurn` (extended)

`opts` gains two optional fields; the signature and result type are otherwise
unchanged (INV-44):

```ts
export interface RunEditTurnOptions {
  modelId?: string;
  onProgress?: (s: TurnProgressSnapshot) => void;  // out: live progress
  signal?: AbortSignal;                            // in: cancellation
}
export async function runEditTurn(
  instruction: string,
  selectedText: string,
  opts?: RunEditTurnOptions,
): Promise<EditTurnResult>;
```

Inside, around the existing `agent.run(...)`:

```ts
const agent = new sdk.Agent({ providerId: "claude-code", modelId, systemPrompt });
let state = createTurnProgressState();
const unsubscribe = opts?.onProgress
  ? agent.subscribe((ev) => {
      const next = reduceTurnProgress(state, ev);
      state = next.state;
      if (next.snapshot) opts.onProgress!(next.snapshot);
    })
  : undefined;
const onAbort = () => agent.abort();
opts?.signal?.addEventListener("abort", onAbort);
try {
  const result = await agent.run(`<instruction>…</instruction><text>…</text>`);
  // existing non-"completed" guard throws (covers "aborted" and "failed")
  …
} finally {
  unsubscribe?.();
  opts?.signal?.removeEventListener("abort", onAbort);
}
```

`AbortSignal`/`addEventListener` are web standards (no `vscode`), preserving
INV-43. An aborted turn yields `status: "aborted"` → the existing guard throws →
the call site reflects "cancelled" and proposes nothing (INV-47). **`extractReplacement` and the return shape are untouched** (INV-44).

### 3.4 The two call sites (UI relay)

A small shared host module owns the relay so both sites are identical:

```ts
// src/liveProgressUi.ts (host; vscode-only)
export function createLiveProgressUi(): {
  channel: vscode.OutputChannel;
  // Begin a turn: clears nothing, writes the header, returns the wiring for
  // one withProgress run.
  begin(instruction: string, progress: vscode.Progress<{message: string}>, token: vscode.CancellationToken):
    { signal: AbortSignal; onProgress: (s: TurnProgressSnapshot) => void };
};
```

- **`onProgress(s)`** → `progress.report({ message: formatLine(s) })` where
  `formatLine` renders `phase`/`chars`/`tokens`; and appends `s.textDelta` (if
  any) to the shared `"Cowriting"` channel. On the **first** non-empty
  `textDelta`, if `cowriting.liveProgress.revealOutput` is `true`, call
  `channel.show(true)` once.
- **`signal`** comes from an `AbortController` whose `abort()` is fired by
  `token.onCancellationRequested`.
- The `withProgress` options gain **`cancellable: true`**.
- On `catch`, the call site checks `token.isCancellationRequested` → show
  **"cancelled"** (information) instead of the "failed" error.

`extension.ts:editSelection` passes `{ onProgress, signal }` straight into
`runEditTurn`. The preview path threads the same through its seam:

```ts
// trackChangesPreview.ts — widen the injectable seam (back-compat: opts optional)
type EditTurn = (instruction: string, text: string, opts?: RunEditTurnOptions) => Promise<EditTurnResult>;
```

`runEditAndPropose` forwards `opts` to its single `editTurn(...)` call (both the
`range` and `document` branches invoke the turn exactly once per gesture, so there
is one progress stream per gesture). The **host-E2E stub** (the default-overriding
injection) keeps working — `opts` is optional and ignored by the stub; a focused
test may simulate progress by calling `opts?.onProgress` (§4).

### 3.5 OutputChannel semantics

- **One shared channel** (`createOutputChannel("Cowriting")`), created once at
  activation and disposed with the extension.
- **Append, don't clear** — each turn writes a `── asking: <instruction> ──`
  header then streams text, so the channel doubles as a debug log of recent turns
  (per #60 solution-notes). (Trimming an unbounded log is a possible later
  increment, not v1.)
- **Reveal** on first text delta, `preserveFocus: true`, gated by
  `cowriting.liveProgress.revealOutput` (boolean, default `true`).

### 3.6 New configuration

| Setting | Type | Default | Effect |
| --- | --- | --- | --- |
| `cowriting.liveProgress.revealOutput` | boolean | `true` | Auto-reveal the "Cowriting" OutputChannel (without focus) on the first streamed text of a turn. |

Declared in `package.json` `contributes.configuration`.

### 3.7 Invariants

- **INV-43** — `liveTurn.ts` and `turnProgress.ts` stay **`vscode`-free**:
  progress leaves as a domain `TurnProgressSnapshot`, cancel enters as a
  web-standard `AbortSignal`; `AgentRuntimeEvent` is imported **type-only**. No
  `vscode` import is added to either module.
- **INV-44** — Live progress is **purely additive**: it never changes the result
  path (`runEditTurn` return shape, `extractReplacement`, `runEditAndPropose`,
  the F4 proposals). A turn that emits **no** events (the E2E stub) produces the
  identical proposals it does today.
- **INV-45** — **No new network/webview surface.** Progress rides the existing
  `withProgress` notification + a host `OutputChannel` only; the sealed webview is
  untouched (preserves INV-21).
- **INV-46** — The event→progress **reduction is a pure function**
  (`reduceTurnProgress`), unit-tested in isolation; the UI call sites only format
  and relay its snapshots.
- **INV-47** — **Cancellation reflects, doesn't mutate.** Abort surfaces
  "cancelled" (not a frozen spinner, not a silent partial apply); an aborted turn
  proposes **nothing** (parity with the empty / no-change outcomes).

### 3.8 Error & edge handling

- **Failure** — non-"completed" status throws (existing guard); call site shows
  the error message, the notification resolves (no frozen spinner).
- **Cancel** — `token` → `agent.abort()` → `status: "aborted"` → guarded throw →
  call site detects `token.isCancellationRequested` → "cancelled", no proposal.
- **No events** — if the provider emits nothing before completing, the line stays
  `thinking…` and resolves normally; result identical to today (INV-44).
- **Overlapping tools** — phase tracked by tool name/depth so interleaved
  `tool-started`/`tool-finished` resolve back to `writing`/`thinking` correctly.
- **Empty / no-change replacement** — unchanged from today (warning / info),
  independent of progress.

---

## 4. Testing & E2E

Per the §9 pipeline and `coauthoring-*` precedent (unit + host E2E; this is a
VS Code extension — **no flotilla/PPE**, the pipeline's deploy tiers are N/A; the
gate is unit + host-E2E green).

- **Unit (the core):** `turnProgress.test.ts` exercises `reduceTurnProgress`
  across the full event table — phase transitions (thinking→writing→tool→writing),
  `chars` accumulation, `tokens` appearing only after `usage-updated`, `textDelta`
  carrying each chunk, reasoning-delta staying `thinking`, overlapping tools. Pure,
  no vscode/SDK. (`formatLine` gets its own small unit test.)
- **Unit (relay):** `liveProgressUi` line formatting and first-delta reveal gating
  (mock `OutputChannel`/`Progress`).
- **Host E2E:** the existing preview `editTurn` stub is extended in one test to
  **emit synthetic progress** (call `opts.onProgress` with a couple of snapshots)
  and assert the turn still yields the same proposals (INV-44) and that cancel
  (firing the token) yields **zero** proposals (INV-47). Streamed UI itself (the
  live notification text) isn't asserted — E2E can't read notification subtitles
  reliably; that's covered by the unit tests on the mapping + a **manual smoke**
  on a longer real edit (per #60 acceptance).
- **Manual smoke:** a longer real edit shows the activity line advancing, token
  count rising, the OutputChannel streaming, and `✕` cancelling cleanly.

---

## 5. Delivery Plan (rollout — not a task list)

One increment (the feature is a single design-then-build, #60 decomposition).
Ships through the standard branch → PR → `main` flow; no migration, no persisted
state, no config beyond the one additive setting (default preserves prior
behavior except that progress is now visible). Reversible by reverting the PR.
The implementation plan (downstream `wgl-planning-and-executing` session) owns
the Task breakdown; a natural cut is: **(1)** pure `turnProgress.ts` + tests →
**(2)** `runEditTurn` subscribe/abort wiring → **(3)** `liveProgressUi` +
both call sites + setting → **(4)** host-E2E stub extension + manual smoke.

---

## 6. Open Questions

- **OQ-1** — Unbounded OutputChannel log: append-forever is fine for v1 (it's a
  manual debug surface); if it becomes noisy, add per-turn trimming or a
  "clear on new turn" mode later. *(Deferred — not blocking.)*
- **OQ-2 (inherited)** — The F11 design (`#43`) is still un-graduated (lives in
  code + an issue draft). Unrelated to #60 but noted in the shared lineage; track
  separately.