html-docs desktop · design note · v2

Phase templates for the Session Canvas

Why Mission Control feels laggy, and a three-template protocol — plan, execution, summary — that renders agent status instantly while giving the agent a high-bandwidth, low-token channel to keep it fresh. Templates carry the basics; freeform HTML islands keep custom visualization first-class; and the whole protocol is harness-neutral — Claude Code, Codex, OpenCode, anything that can write a file.

---

1Why it feels slow today

Stage	Delay	Where
Fleet card "step" line	≤ 10 s throttle	canvas-activity.mjs · FLEET_MS
Activity feed patch	≤ 1.5 s throttle	canvas-lib.mjs · patchRegionThrottled
Diff meter	≤ 3 s throttle	canvas-activity.mjs:217
Desktop file watcher	+ 400 ms stability + 500 ms debounce	fleet.ts:61-68
Fleet refresh cost	full re-discovery, every poke	fleet.ts · list() re-parses transcripts
Deliverable ("stage")	minutes — agent hand-writes HTML	canvas skill · curl per region
Summary ("debrief")	only at Stop	canvas-stop.mjs

2The idea: one state file, three templates

3The state schema

{
  "v": 1,
  "phase": "plan" | "execute" | "summary",
  "headline": "Adding PDF export to /convert",   // agent-set, one line — becomes the fleet card step

  "plan": {
    "goal": "PDF in + PDF out on the convert page",
    "steps": [                                    // hook-filled from TodoWrite, agent may override
      { "id": "s1", "text": "Accept .pdf uploads", "status": "done" },
      { "id": "s2", "text": "Render output via Chromium", "status": "doing" },
      { "id": "s3", "text": "Verify + commit", "status": "todo" }
    ],
    "approach_md": "Reuse renderPdf + withPrintCss…",  // freeform room
    "questions": ["Keep print-edition variant out of scope?"]
  },

  "execute": {
    "currentStep": "s2",
    "checks": [ { "name": "tsc", "status": "pass" },
                { "name": "smoke: /convert", "status": "running" } ],
    "blockers": [],
    "note_md": "Chromium path needs --no-sandbox on Vercel",
    "activity": [ …existing… ],                   // hook-filled (unchanged)
    "diff": { "files": 3, "add": 184, "del": 52 } // hook-filled (unchanged)
  },

  "summary": {
    "outcome": "shipped" | "partial" | "blocked",
    "result_md": "PDF upload + output live on /convert…",
    "artifacts": [ { "label": "commit adfc2d9", "ref": "git" } ],
    "verification": ["tsc clean", "renderPdf smoke test → %PDF-"],
    "followups": ["Wire print-edition variant"],
    "blocks": [                                   // optional custom-viz islands — see §5
      { "type": "html", "title": "Coverage map", "html": "<svg …>" }
    ]
  }
}

4The three templates

Plan

Replaces: plan-file markdown mirror + TodoWrite rail (both survive as inputs).

Execution

The step rail collapses to a one-line header here; the full rail stays one click away.

Summary

The Stop hook stamps outcome/diff/duration automatically if the agent hasn't — a summary always exists, even on a crash.

5Custom visualization: structured core, freeform islands

Tier	Rendering	Guarantee
Card / fleet grid	structured fields only (headline, phase, steps, diff)	always fresh, never waits on custom HTML
Phase panels	template blocks, with html islands inline	basics auto-update; islands render verbatim
Stage (deliverable)	fully freeform HTML — unchanged from today	unlimited; the hero surface stays the agent's canvas

6The agent protocol — where the bandwidth comes from

# set the phase + headline (≈20 tokens)
canvas '{"phase":"execute","headline":"Wiring Chromium render"}'

# flip a check (≈15 tokens)
canvas '{"execute":{"checks":[{"name":"tsc","status":"pass"}]}}'

# land the summary (≈60 tokens)
canvas '{"phase":"summary","summary":{"outcome":"shipped",
  "result_md":"PDF in/out live on /convert",
  "followups":["print-edition variant"]}}'

Channel	Cost per update	Freshness
Today: agent curls region HTML	300–1500 tokens	once or twice a session
Proposed: canvas JSON patch	15–60 tokens	every step transition
Hooks (activity, diff, steps)	0 tokens	every tool call

7One protocol, any harness

Harness	Adapter mechanism	What it feeds
Claude Code	hooks (SessionStart / PostToolUse / Stop) — today's code, refactored to emit state patches	activity, diff, TodoWrite→steps, turn status
Codex	codex exec --json event stream — the adapter process parses events and writes patches itself (per-turn process model)	activity, turn status, token/cost
OpenCode	plugin subscribing to its event bus, writing the same patches	activity, steps, turn status
Anything else	lowest common denominator: a generic tailer for stdout/JSONL logs, plus the canvas CLI — any agent that can run a shell command gets the full semantic channel with zero integration	headline, phase, checks, summary

8Plumbing fixes that ride along

• Desktop watcher (fleet.ts): state JSONs are single atomic writes — drop awaitWriteFinish for the state dir and cut the debounce to ~100 ms. Keep the 400 ms window only for transcript files.
• Per-session deltas: on a state-file change, re-read that one file and push a one-card IPC update. Full list() re-discovery only on add/unlink. This is the biggest perceived-latency win.
• Fleet card step: read headline / current step from state directly — the 10 s FLEET_MS throttle stays only for the cloud fleet doc PATCH; the local card updates instantly.
• Status signal: "working" from hook events (UserPromptSubmit → working, Stop → idle) written into state, replacing the transcript-mtime heuristic and its 180 s staleness window.
• Cloud canvas: hooks keep the existing region PATCH throttles (network cost is real) but now render the same shared templates — the desktop never waits on the cloud.

9Rollout

1. Add SessionState v1 types + deep-merge + template functions (incl. the block vocabulary) in one shared module used by both hooks and desktop (canvas-lib.mjs stays the hooks' entry; desktop imports the templates via shared/).
2. Ship the canvas patch CLI + system-prompt teaching lines. Hooks start writing phase/steps/timing into the new fields alongside the old ones.
3. Desktop: state-dir fast-watch + per-session IPC deltas; fleet card reads headline.
4. Session detail + cloud canvas switch to the three templates; old freeform stage/debrief remain as fallback for sessions without v: 1. Stage stays freeform forever — it's tier 3 by design.
5. Extract the Claude hooks' event handling into the adapter shape; implement the Codex adapter against exec --json (the skeleton in codex-adapter.ts already gates on detect()); neutral .mission/ root with the legacy path as read alias.