Skip to content

Answer blocks

Generated from the code by apps/docs/scripts/reference.mjs: edit the source, not this page.

An agent wisp runs ends its final message with a ```wisp block: {"blocks": [...]}. wisp draws each block (the diff, the tests, the preview…) and hides the rest of the message. This is the catalogue the agent is given, word for word.

hero

{"type":"hero","title":"<what happened, ≤8 words>","topic":"<the subject of the request, ≤6 words>","summary":"<1–2 sentences>","status":"done|partial|blocked|info"}

Always first. “topic” is what the user asked about as a short noun phrase (“Rate limit on /login”), not what you did; wisp names the task with it. Optional after the first turn.

markdown

{"type":"markdown","text":"<github-flavoured markdown>"}

steps

{"type":"steps","title":"…","items":[{"title":"…","detail":"…","status":"done|skipped|failed"}]}

What you did, in order.

stats

{"type":"stats","items":[{"label":"tests passing","value":42,"unit":"","delta":"+6","tone":"good|bad|neutral"}]}

Numbers animate; use real numbers only.

files

{"type":"files","items":[{"path":"src/a.ts","change":"added|modified|deleted|renamed","note":"why"}]}

diff

{"type":"diff","file":"src/a.ts","caption":"…"}

Shows the REAL diff of your edits to that file (wisp captured them). Use for the 1–3 most important changes. Optionally add “before”/“after” strings to show a hand-picked snippet instead.

tests

{"type":"tests","command":"npm test","passed":48,"failed":1,"skipped":2,"durationMs":5300,"failures":[{"name":"auth > rejects expired token","message":"expected 401, got 500","file":"test/auth.test.ts:42"}]}

A test/lint/type-check run you actually executed. Prefer this over “terminal” for test runs.

commits

{"type":"commits","items":[{"hash":"a1b2c3d","message":"feat(auth): add rate limiter","files":3,"additions":120,"deletions":8}],"branch":"feat/limit"}

Commits you created, if any.

graph

{"type":"graph",…} Branch graph: merge conflicts, a rebase, where branches diverged. Read its fields with `wisp_blocks` (mcp__wisp__wisp_blocks) before you use it.

tree

{"type":"tree","title":"…","items":[{"path":"src/auth/limiter.ts","change":"added","note":"…"}]}

A file tree; use for new modules/scaffolding where structure matters.

code

{"type":"code","language":"ts","code":"…","caption":"…","file":"src/a.ts","line":10,"highlight":[3,4]}

Key snippet (new API, signature, config) — not whole files.

compare

{"type":"compare","before":{"label":"Before","items":["…"]},"after":{"label":"After","items":["…"]}}

flow

{"type":"flow","title":"…","nodes":[{"id":"a","label":"Request","note":"…"}],"edges":[["a","b","label"]]}

Architecture / data flow / sequence. Edges optional (nodes are chained in order if omitted).

chart

{"type":"chart","title":"…","unit":"ms","items":[{"label":"before","value":420},{"label":"after","value":95}]}

terminal

{"type":"terminal","command":"npm test","output":"<trimmed output>","exitCode":0}

checklist

{"type":"checklist","title":"…","items":[{"text":"…","done":true}]}

Where a ship, release or deploy stands, one item per stage, done or not.

callout

{"type":"callout","tone":"info|success|warn|danger","title":"…","text":"…"}

Risks, caveats, assumptions you made. Rare: if every answer has one, none stand out.

image

{"type":"image","path":"relative/or/absolute.png","caption":"…"}

A screenshot or generated image on disk. Every UI change gets one (desktop and phone if both matter).

video

{"type":"video","path":"relative/or/absolute.mp4","caption":"…"}

A video you made or recorded (mp4, webm, mov), played inline. Use it instead of linking the file.

preview

{"type":"preview","url":"http://localhost:5173/settings","device":"mobile|tablet|desktop|1280x720","title":"…","caption":"…"}

A live web page shown in the answer, in a sandboxed frame at that screen size: a dev server you started, a deployed page you changed. The best evidence for a new feature: the user clicks through it in place. Point the url at the page that shows the change, not the root. Pick the device that shows it (mobile for a responsive fix); the user can switch sizes. Keep the server running and say so.

map

{"type":"map","title":"…","places":[{"name":"Blue Bottle Coffee","address":"66 Mint St, San Francisco, CA 94103","note":"…"}],"route":false}

Addresses or places (an office, a venue, shops to visit): wisp shows them on a Google map, each with Open in Google Maps. Full street addresses, or “lat”/“lng”; all of them in one block. “route”: true adds directions through them in order.

doc

{"type":"doc","path":"docs/plan.md","title":"…","caption":"…"}

A markdown file you wrote for the user to read (a plan, report, spec, ADR). wisp shows its opening with Full screen and Show in folder, so point at the file rather than pasting it into a markdown block.

task

{"type":"task","id":"8e64708d4b75","note":"…"}

Another wisp task (from wisp_sessions or wisp_session) that you found or point to. wisp shows its title and state and the user opens it with a click. Use one per task instead of naming ids in prose.

stuff

{"type":"stuff","id":"0bac5acb43c9","note":"…"}

Something you saved or updated in the user’s My Stuff (its id). An app shows with Launch and opens inside wisp; the rest with Open. One per thing you saved this turn.

question

{"type":"question","question":"…","options":[{"label":"Short choice","reply":"full message sent back to you"}]}

When you need a decision. The user’s click resumes you with the reply.

blocked

{"type":"blocked","items":[{"tool":"shell","detail":"npm publish","why":"needs network access"}]}

Actions your permissions or sandbox refused (a denied tool call, a command that failed for lack of network or write access). wisp shows them with an Allow & retry button. Not for ordinary failures.

actions

{"type":"actions","title":"…","items":[{"label":"Run tests","command":"npm test"},{"label":"Follow up","reply":"…"}]}

One-click shell commands (executed in the project root) or follow-up actions the user may want to trigger. After a code change, the first item is the next ship step (see Picking blocks).

next

{"type":"next","items":["Suggested follow-up the user might send", "…"]}

Usually last. 2–4 concrete follow-ups, the most likely next request first: what the user usually does next (ship, deploy, look at it), then ideas. {“type”:“hero”,“title”:“Login now rate-limited”,“topic”:“Rate limit on /login”,“summary”:“Added a sliding-window limiter to /login. 5 attempts per minute per IP.”,“status”:“done”}, {“type”:“diff”,“file”:“src/auth/login.ts”}, {“type”:“tests”,“command”:“npm test”,“passed”:48,“failed”:0,“skipped”:0,“durationMs”:4100}, {“type”:“callout”,“tone”:“warn”,“title”:“Assumption”,“text”:“Behind a proxy, so I read the IP from X-Forwarded-For.”}, {“type”:“actions”,“items”:[{“label”:“Commit and open a PR”,“reply”:“Commit this and open a PR”}]}, {“type”:“next”,“items”:[“Make the limit configurable”,“Add the same limiter to /reset-password”]}