vscode-cowriting-plugin

Non-shippable proof-of-concept (Feature #2 of Epic #1): a standalone VS Code extension that drives @cline/sdk — validating Approach A (own coauthoring extension on the Cline SDK, no fork).

What it does

Registers one command, Cowriting: Show Cline SDK Info, which loads @cline/sdk and shows the SDK build version plus the agent's builtin tool catalog (a pure, key-free SDK call) in a notification and the "Cowriting (Cline SDK)" output channel.

Features shipped so far: F2 region-anchored threads (Feature #4), F3 live human/Claude attribution (Feature #6), F4 propose/accept diff flow (Feature #12).

Architecture

• CommonJS extension bundled with esbuild (src/extension.ts → out/extension.cjs).
• @cline/sdk is ESM-only (Node ≥22) and uses createRequire(import.meta.url), so it is not bundled — it is shipped in node_modules and loaded at runtime via dynamic import() from the vscode-free src/cline.ts.

Run it (F5)

1. npm install
2. npm run build
3. Press F5 (or Run → "Run Extension") to launch the Extension Development Host. It opens the committed sandbox/ playground as its workspace (not the repo itself — VS Code won't open one folder in two windows, #8); start with sandbox/playground.md.
4. In the new window: Cmd/Ctrl+Shift+P → "Cowriting: Show Cline SDK Info".

F2 — Region-anchored threads (Feature #4)

Attach durable, region-anchored discussion threads to any document. Threads render in the native VS Code Comments gutter and persist as git-native sidecars under .threads/<doc-path>.json (plain, diffable JSON — no server).

• Create: select text → run "Cowriting: Add Coauthoring Thread on Selection" (or the Comments gutter "+").
• Reply / Resolve: use the native Comments reply box and the thread's Resolve/Reopen actions.
• Survives edits, reload, and external change (git pull): a hybrid anchor (durable content fingerprint + live offset tracking) re-resolves the thread. If the anchored text can't be confidently re-found, the thread is shown as orphaned at its last-known line — never silently moved.

Design: vscode-cowriting-plugin-content/specs/coauthoring-inner-loop.md. No live @cline/sdk turn and no credentials are involved in F2.

F3 — Live human/Claude attribution (Feature #6)

As you and Claude coauthor, every span in the buffer carries an author: human edits render with a subtle left border, Claude-authored spans with a background tint. Text that predates tracking stays plain — the honest record. Edits that touch a boundary (split, merge, partial overwrite) are handled char-precisely.

Attribution is persisted git-natively in the same .threads/ sidecars (attributions[], sharing the same anchors fingerprints as F2 threads). On reload, fingerprints re-resolve spans against the current document; spans that can't be confidently re-found are orphaned (status-bar count + "Cowriting Attribution" output channel) rather than silently moved or discarded.

Commands

• Cowriting: Ask Claude to Edit Selection — select text → enter an instruction → a live @cline/sdk turn runs on the built-in claude-code provider (rides your local Claude Code Pro/Max login; the extension stores no credentials). As of F4 the turn ends in a proposal (see below); accepted text lands as a Claude-attributed span.
• Cowriting: Toggle Attribution — show/hide attribution decorations.
• cowriting.applyAgentEdit (palette-hidden) — the single machine-edit ingress seam. Tests drive this directly so CI requires no LLM.

Design: vscode-cowriting-plugin-content/specs/coauthoring-attribution.md.

F4 — Propose/accept diff flow (Feature #12)

Claude's edits arrive as pending proposals — propose-by-default, the document never changes without your say-so. A proposal renders two ways at once: an amber tint on the target range, and a "Claude proposes" comment thread showing a fenced diff of current → proposed text with two actions:

• ✓ Accept Proposal — applies the replacement through the applyAgentEdit seam, so it lands Claude-attributed (F3) — and the proposal disappears.
• ✗ Reject Proposal — the document is untouched; the proposal disappears.

Pending proposals persist git-natively in the same sidecar (proposals[], sharing the F2/F3 anchors fingerprints), survive reload, and re-anchor as surrounding text changes. If the target text itself changes, the proposal goes stale (status-bar count, accept disabled — never applied by guess); undo the change and it becomes decidable again. cowriting.proposeAgentEdit (palette-hidden) is the programmatic propose ingress E2E drives — no LLM in CI.

Design: vscode-cowriting-plugin-content/specs/coauthoring-propose-accept.md. Live smoke: docs/MANUAL-SMOKE-F4.md.

F5 — Cross-rung format + round-trip (Feature #14)

The .threads/ sidecar is the published cross-rung contract: any rung of the ladder (this editor → Gitea substrate → rfc-app) reads and writes the same record per the contract; git push/pull is the transport, no re-homing ever.

• Normative contract (INV-14): vscode-cowriting-plugin-content/specs/coauthoring-sidecar-contract.md — format changes land there first, then schema, then code.
• Machine-checkable half: schemas/coauthoring-sidecar.schema.json; validate any sidecar from any rung with node scripts/validate-sidecar.mjs <file>. The unit suite validates every serialized artifact — contract drift fails CI.
• Identity crosses rungs: Provenance.email (git's own join key — populated from the workspace git config when available) and agent.onBehalfOf (who the machine acted for).
• Writers preserve unknown fields (INV-15): rewriting a sidecar never destroys another rung's data — unknown keys survive, after known keys, sorted.
• Newer-major sidecars are read-only (INV-16): the editor renders what it understands, warns once, and writes nothing (the store refuses as a backstop).
• Deterministic merge (INV-17): src/mergeArtifacts.ts — union-by-id, documented tie-breaks, every resolved divergence surfaced in conflicts.
• The round-trip is proven, not asserted: scripts/crossrung-reply.mjs is a self-contained conforming foreign writer (the Gitea-rung stand-in); host E2E drives editor-thread → stand-in reply → external-change → the reply renders in the thread.

Design: vscode-cowriting-plugin-content/specs/coauthoring-cross-rung-format.md.

Develop

• npm run watch — rebuild on change.
• npx vitest run — unit suite (SDK driver, schema, store, anchorer, thread mutations, attribution split/merge).
• npm run test:e2e — @vscode/test-electron host E2E (create → reply → resolve → persist → reload → re-anchor → orphan; drives cowriting.applyAgentEdit directly — no LLM required).
• npm run smoke:live — scripted live-turn smoke test for F3; requires Claude Code installed and signed in. See docs/MANUAL-SMOKE-F3.md.
• npm run typecheck — type-check without emit.