Skip to content

Latest commit

 

History

History
451 lines (410 loc) · 32.4 KB

events.md

File metadata and controls

451 lines (410 loc) · 32.4 KB

Runner protocol: Events, design reviews and reply buttons

Part of the runner protocol. docs/protocol.md has the rules for all of it and which file each section is in.

Events

Design reviews

show_options gives the calling thread a durable review of pictures, videos and pages. It returns promptly, with the review's id and the review:<id> link that opens it from an ask or a message (see Needs you); the agent may finish its turn while Mike reviews the options. The app shows a compact card outside work groups. Opening it opens a resizable, modeless window that steps through every shot of every option, then shows the options side by side, with the options to tick, one reply box and Send down the right; arrival never steals focus.

An option can have several shots (its overview, a state mid-interaction, a detail) and a live url. Agents used to pass extra shots as options of their own (A2, A3) that couldn't be picked; Mike also picked more than one or none, and answered most reviews in the thread in his own words (4 Nov 2026), hence several picks, none and reply.

It's only for options that are seen: images, videos, page designs. A thread put a research shortlist in one as a page of text per option, and Mike found comparing words there pointless (20 Nov 2026), so the tool and the instructions send options in words to the reply instead.

recommended is the agent's own pick, marked with a star and "Recommended" in the rail and over its picture, worded as an asks card marks suggested. Both notes are inline markdown. Mike, 7 Nov 2026: the note was drawn raw in grey, so backticks showed, nothing stood out, and "I'd pick C" sat halfway through a paragraph.

// pickedIds lists every pick in the review's option order, only when there
// are two or more; pickedId is always the first pick, for older clients.
// Clients send pickedIds (it wins over pickedId); a client that sends only
// pickedId still works. none: none of them will do, never with picks.
// images: pictures pasted into the reply, each placed by a [Picture N] in
// reply, as a message's are (see Reply pictures, below).
type ReviewDraft = { pickedId?: string, pickedIds?: string[], notes: Record<string, string>, reply?: string, images?: ImageRef[], none?: true }
// media: a video (video/mp4, video/quicktime) or an HTML page (text/html)
// the window plays or shows in place of image, which is then its still.
type ReviewShot = { title?: string, image: ImageRef, media?: ImageRef }
type DesignReview = {
  id: string
  title: string
  note?: string        // markdown (bold, code, links), drawn in the text colour
  recommended?: string // the option id the agent would pick: marked with a star and "Recommended", as on an asks card
  options: {
    id: string          // stable within this review
    title: string
    note?: string
    reference?: boolean // can have notes, cannot be picked
    image: ImageRef     // the first shot: a copy owned by the thread, never the source path
    shots?: ReviewShot[] // every shot in order, image first; only when more than one, the one has a title, or it has media
    url?: string        // http(s): where it runs live
  }[]
  status: "pending" | "answered" | "cancelled" | "superseded"
  revision: number     // optimistic concurrency for saves and submission
  createdAt: string
  updatedAt: string
  draft: ReviewDraft
  response?: ReviewDraft
  replyTurnId?: string
}

The following RPCs take full thread/review IDs. Unknown IDs are errors.

method params result
reviews.create { threadId, title, note?, options: { id, title, path?, shots?: { path, title? }[], url?, note?, reference? }[] } { review: DesignReview }
reviews.get { threadId, reviewId } { review: DesignReview }; reviewId may be the start of one (8 or more characters) that names only it, among every review the thread has
reviews.list { threadId } { reviews: DesignReview[] } pending reviews only, oldest first
reviews.save { threadId, reviewId, revision, draft: ReviewDraft } { review: DesignReview }
reviews.respond { threadId, reviewId, revision, draft: ReviewDraft } { review: DesignReview, turnId?: string }
reviews.cancel { threadId, reviewId, revision } { review: DesignReview }

Creation validates the whole request and imports supported files before publishing the card. A shot's path is a picture (PNG, JPEG, GIF, WebP), a video (MP4 or QuickTime, by its header) or a page (.html/.htm). Agents had to hand Mike stills of clips that only made sense moving (6 Nov 2026). A video or page is copied in as the shot's media, and its still, made by Quick Look on a Mac or ffmpeg for a video elsewhere (a plain dark card when neither can), is its image, which thumbnails and older clients show. A page comes in a folder of its own with the files it names (src, href, url(), a stylesheet's own) from its folder down, at most 100 files and 50 MB; never anything above its folder, nor other pages it links to. The Mac window shows the page the way the side pane does: scripts off, nothing loaded from outside, and Open in Browser for a page with scripts. A video loops. On the stage it has controls and plays with sound; side by side with the others in the grid it's muted. Paths can be absolute, home-relative or relative to the thread's folder. An option's shots are path then shots, or shots alone; it needs at least one. Limit: 12 options, 8 shots each and 40 in all, each image at most 25 MB, video 200 MB and page 5 MB (videos and pages 500 MB in all), nonempty unique option IDs and titles, title/note at most 200/4000 characters, url http or https. Draft notes are at most 4000 characters per option and the reply 8000; unknown option IDs, picks of reference options and none with picks are invalid. A response needs a pick, none, a reply, a picture or a nonblank note. Saving an empty draft is allowed. The agent's message reads `Picked A.

<title>.` or `Picked A + D. <title> + <title>.`, or `Picked none of them.`, then the reply as written, then any notes. With a pick, a last paragraph names the pickable options passed over (`Passed over: B. <title>; C. <title>.` and a fixed sentence, `PASSED_OVER_TAIL`), so the agent doesn't later offer one as a new follow-up. The Mac, phone and GPUI apps read that wording back for Mike's bubble (`ReviewAnswer`), leaving the passed-over paragraph out, so change them with it.

As a page beside the thread (the reviewPage experiment; Mike, 20 Nov 2026): he went into the window for the pictures and back out to the thread to read about them, as the window drew each option's words at 12pt grey in a column 270pt wide, and agents wrote the options out again in their reply. With it on, the GPUI app opens this Mac's reviews as a page in the side pane: the note, then each option with its words at the thread's reading size and its shots under them, made by the app from the review (desktop/core/src/review_page.rs) and shown sealed, scripts off, reading only the review's own folder. Nothing changes in these RPCs. A tick on the page saves the draft's picks with reviews.save, and they show as chips over the thread's message box, which is the reply box: sending it calls reviews.respond with the picks as the page shows them, the box's words as reply and its pictures as images (they're in inbox/, as a reply's are), so the answer is the same one the window sends, taken whole or not at all. Ticks alone can be sent. A message starting with /, or sent with answers picked on a card of asks, is an ordinary message, and like one sent with nothing ticked it supersedes the review, as before. (A first version had the runner turn a plain threads.send into the answer; Codex and Gemini's reviews found it could be sent twice after a restart, lose its pictures and swallow a command.) A picture on the page opens the review window at that shot, as a closer look: the stage across the window with that option's words under it, and no column down the right. The pane opens 640pt wide for a review, 920pt when a shot is a wide design (1000px or more across and wider than tall), keeps the transcript 420pt, and goes back when the page closes unless the divider was dragged meanwhile. The phone and the website keep their own sheets.

Reply pictures: a picture pasted or dropped in the window's reply box is a chip, as in the thread's box, imported with media.import and sent in the draft's images with [Picture N] markers in reply (Mike, 17 Nov 2026: the box was plain text, so a pasted screenshot went in as its file path). At most 20. Save and respond take only pictures in the runner's inbox/ (what media.import made) or ones already kept with the review, never a link, and copy each into media/<thread>/reviews/<id>/reply/ under a name from its contents, so a draft outlives the inbox's week, saving the same picture again keeps one copy, and a retried answer naming the inbox copy is the same answer. The saved draft names those copies, and the window takes them in place of its own. Pictures alone are an answer. The agent's message carries them as its images.

Every change persists a review.updated event with { review: DesignReview }. An option's url is an http or https page; the Mac app drops any other (a file: URL, another app's link) as it decodes one, whatever runner sent it, and Open live opens only a web page. Its stable card ID is the review ID; later snapshots update that card in place even when the original event is outside the loaded transcript page. ThreadSummary.pendingReviews?: number counts pending reviews and makes needsYou true even after mark-read, turn-end and runner restart. It does not hold a CLI open or prevent an update. Cancelling closes the request without sending an agent message. A message from Mike in the thread (from the app or the phone, not one sent by the runner, a schedule or another thread's agent) supersedes every pending review there: he often answers in the thread instead of the window. Each becomes superseded, read-only like a cancelled one, with no agent message. Closing a window only keeps the draft. The thread header can open pending reviews from reviews.list, including requests older than the transcript's loaded event page; Mike does not need to scroll back through earlier turns to find what still needs an answer.

Save and submit reject a stale revision with -32602; the client reloads and preserves its unsaved text for retry. Answered/cancelled reviews are read-only. Retrying an identical response to an answered review returns the original result and never sends twice; a different response is an error. The runner durably queues the submitted reply with its review ID and structured response, alongside readable text naming the review and each option. An idle agent resumes; a busy one receives it after its turn. The queue survives restart. The response and queue are persisted together before acknowledging submission. user.message may include reviewId and reviewResponse: ReviewDraft; these identify the review that prompted the reply. The same fields accompany queued replies on disk.

An internal delivery marker is saved after the CLI's session.send accepts the reply. A crash between that call and the marker may replay the reply after restart (at-least-once dispatch). Repeated reviews.respond requests with the same response never add another reply.

Both Claude and Codex receive threadbear.show_options through the shared MCP tool definitions, bound to the calling thread. Its schema matches reviews.create without threadId; it returns the review ID and explains that the choice/notes will arrive as a later message. The existing URL patch panels are independent of these review windows. Reviews take pictures, videos and pages, with a live url per option opened in the browser; overlays are deferred.

Reviews on the phone

Backend API 86 adds phone:designReviews(token, threadId, reviewId?) and phone:respondReview(token, threadId, reviewId, revision, draft). Both queue commands on the owning runner. Without an id the first returns pending review titles ({ reviews: [{ id, title }], truncated? }); with an id, or the start of one as a review: link gives, it returns that review, pending or not ({ review }). phone:command carries the result, as JSON text for the phone to parse (a draft's notes are keyed by option id, which Convex can't take as an object key). The runner must be online to read or answer a review. Responses use reviews.respond, including its revision checks and idempotent retry behavior.

What the phone gets of a review has no paths in it: each shot's still is named by an opaque src (review:<reviewId>:<sha256 of its path>), and the draft or response is only pickedId, pickedIds, notes, reply and none. A draft's pasted pictures (images, paths on the Mac) stay there, and an answer from the phone keeps them. The answer's notes go as a list, [{ id, text }], as an option's id can be any text and Convex refuses an object key that isn't plain ASCII or starts with $; the runner rebuilds the draft from those fields alone.

A review's stills go up only when the phone opens that review: the runner queues them as the designReviews command with an id runs, as reply pictures at seq 0 whose src and path are both the opaque source, and phone:reviewImages(token, threadId, sources) follows them as they arrive (phone:images leaves them out). Only a file in the review's own media folder that isn't a link goes (a moved review's paths are the other runner's word). One over the reply-picture limit (10 MB) or in a format the phone doesn't take is shrunk to a JPEG first, and one that can't be sent at all comes with preview: false, so the phone says so rather than waiting.

The phone's Reviews sheet opens from the pending-review button or a review:<id> link. It shows reference and recommended options, each shot's still, multiple picks, none, per-option notes and a reply. HTML and video originals stay on the Mac; the phone labels their stills. Loading and failed submissions keep the user's draft. A stale revision reloads the review and requires another deliberate send. Older backends keep the Mac-only explanation.

Reply buttons

Standard since 11 Nov 2026 (it was the replyButtons experiment). Mike asked on 7 Nov 2026 for buttons partway through a long reply (the Daily brief's "Needs attention" lines) that start a background thread with a brief the agent wrote, or send a message to a thread that's already going, so he can set jobs off as he reads without typing. He picked a tool that makes the button over a link that carries the brief: the runner checks the folder, login and target thread when the button is made, so a mistake reaches the agent while it can still fix it, not Mike as a dead button the next morning, and the brief lives in the thread rather than in the reply's text.

The thread's agent calls add_button, which stores a ReplyButton on the thread and returns its link, button:<id>. The agent puts [title](button:<id>) in its reply where it belongs; the apps draw that link as a button. A button the reply never links isn't shown anywhere. Nothing runs until Mike presses it.

type ReplyButton = {
  id: string            // 8 lower-case letters and digits, unique in the thread
  title: string         // what the button says, at most 60 characters
  createdAt: string
  turnId?: string       // the turn that made it
  // Exactly one of start, send and panel.
  start?: {             // a new thread, as create_thread would make it
    text: string        // the brief, at most 20,000 characters
    title?: string
    cwd: string         // checked to be a folder when made
    accountId?: string  // checked to be a login when made
    poolId?: string     // checked to be a pool when made
    model?: string
    effort?: EffortLevel
    permissionMode: PermissionMode
    why?: string
  }
  send?: {              // a message to a thread of this runner's
    threadId: string    // checked to exist, and not to be this thread
    threadTitle: string // its title when made
    text: string        // at most 20,000 characters
  }
  panel?: {             // another folder's patch panel, opened beside this thread
    cwd: string         // the folder, checked when made
    panelId: string     // its web panel's id there, checked when made
    title: string       // its title then: "YouTube"
  }
  pressed?: { at: string, threadId: string } // the thread it started, or the one it messaged; a panel button's own thread, at its last press
  failed?: { at: string, error: string }     // the last press failed; it can be pressed again
}
method params result
buttons.press { threadId, buttonId } { button: ReplyButton } Starts the thread or sends the message, once. A button already pressed returns as it is, with nothing run again, so a dropped reply or a second click (or a press from the phone and the Mac) never fires twice. A press that fails (the folder has gone, the target thread was deleted) is saved as failed, and the error comes back as -32602. A panel button is the exception: every press opens its panel again (below)
buttons.list { threadId } { buttons: ReplyButton[] } every button the thread has, oldest first

Panel buttons. Mike asked on 18 Nov 2026 for the Daily brief's "Go through comments" to open the YouTube patch's panel (from yt-channel-manager) rather than start a thread, as he'd write his comment replies there. A patch's panels only show for threads in its folder, so add_button's panel: { folder, panel } names a folder and one of its web panels, by id or title, found as a thread there would have them (a list panel, which the runner renders for a thread in that folder, is refused). Pressing it adds that panel to the pressing thread's panels, from then on, and asks for it to be shown as show_panel does (a panelRequest), on every press: it opens a panel rather than doing a job, so it's never spent, and the agent hears nothing of it. The panel's badge and summary run in its folder whenever the thread's patches are read, as for that folder's own threads, which is what starts a patch's server (the YouTube patch's badge starts its page's). Its id is <panelId>@<8 hex of its folder's hash> and it has from, its folder, so nothing takes the thread for one of that folder's (the YouTube page lists the threads that have its panel as ones to ask in). Its url's {threadId} is left empty, for the same reason: the page sees no thread of its own, and the YouTube page then offers its recent threads and New thread for Ask Claude. A thread's newest press of each panel counts, so a brief that makes the same button every day still has one panel. A folder that has gone by the press fails it; a panel that isn't there once the patches are read again (its patch broke, or its when hid it) is saved as failed after the press. Only this runner's apps show it: the phone and the website get start and send buttons only, so a panel button's link is drawn there as its words.

Every change persists a button.updated event with { button }; clients keep the latest per id, as for reviews, and redraw any link to it. A press marks the started thread as started by this thread (startedBy { kind: "thread", label: "Button" }) and its first message, or the message sent, begins with the usual [Sent by the agent in the thread ...] line, as the agent wrote the words and Mike only chose to send them.

The thread whose reply had the button hears of the press before Mike's next message to it: a line from Threadbear naming each button pressed since, the thread it started or messaged and the start of what it sent, so its agent doesn't send the same job again (on 8 Nov 2026 the Daily brief did, after Mike pressed RSVP yes and then said go ahead in his reply). The line is kept on the thread (presses in thread.json, the last 20) from the press, so it outlives the button. Read from disk (a moved thread's thread.json is the old runner's), only well-formed notes are kept, at most 220, each line at most 2,000 characters. Every list and object in a record that the runner walks is put in the shape it expects as it's read (normaliseRecord in store.ts: a queue that isn't a list is empty, entries of the wrong kind go, a wait needs a thread id), a record whose folder isn't a string is rebuilt, and every step of a start that goes through the threads (recovery, summaries, stopped work, waits, owed reviews) takes them one at a time: a thread that throws is said in a notice and left as it is, rather than stopping the runner. A turn that doesn't complete (a failure, Stop, a restart part way) hears it again, so does a fresh session that replays the message, and so does an edit back past the message that carried it. A run's press already tells the agent how its command went, so it isn't in that line.

Safety. Only a thread's own agent can make its buttons: add_button is bound to the calling thread like the other threadbear tools, and there's no RPC that makes one. Pressing (Mike's click on the Mac, phone or website) is the only thing that runs one. A thread that isn't in full access can't make a button for more than it has: a new thread's permissionMode defaults to the maker's and can't be above it, and a message to a thread with more access is refused (send_message, which asks first, is for that). A thread keeps its last 200 buttons.

Run on the card (asks carrying a run command with a Run button) was taken out on 14 Nov 2026. end_turn ignores an ask's run, a button left over from it (one with run and neither start nor send) refuses a press, and clients ignore run on an ask. Backend API 71 still lets an ask carry it, for rows written then.

On the phone and the website (Sync, backend API 59), pressing calls phone:press({ threadId, buttonId }), which queues a press command with { buttonId } for the thread's runner; the runner calls buttons.press and finishes the command with the thread it started or messaged as resultThreadId, so phone:command hands the phone its id to open. Each mirrored assistant message carries the state of the buttons its text links, in the order it links them (buttons?: { id, title, kind: "start" | "send", target?: string, pressedThreadId?: string, failed?: string }[]; target is the new thread's folder name or the messaged thread's title, and never the brief or message itself). A button.updated that presses or fails a button sends the row that links it again (found among the thread's recent events after a restart), and the backend changes only its buttons. A link whose id the row doesn't carry is drawn as its title. A shared page draws every button link as its title: whoever it's shared with can't press Mike's buttons, and the share query doesn't return buttons. The phone draws the buttons a line ends with as real buttons after its words, and one partway through a line as a link that presses it.

Every persisted event has an envelope:

type Event = {
  seq: number           // 1, 2, 3 ... per thread, no gaps among persisted events
  ts: string
  threadId: string
  turnId?: string
  type: string
  // ...type-specific fields below
}

Persisted event types (stored in events.ndjson, returned by threads.events):

type fields
user.message text, images: ImageRef[], answers?: AskAnswer[] (the open card's asks it answers, as threads.send gave them: for showing, the agent only gets text), origin?: "runner" | "schedule" | "phone" (runner when the runner sent the message by itself, such as the resume after a restart; schedule when a schedule sent it, with scheduleId; phone when it came from the phone through the Convex mirror (Sync), and the agent then gets it after a line saying so and whether the user is at the Mac, though text keeps what was typed; absent for anything a person or client sent), wakeReason?: string (only with origin: "runner": what happened, in a few words, such as "The Threadbear GPUI app restarted onto daabd88f7"; a turn the runner's message started gets the same "14 h later" divider as one background work woke, saying this, or "Threadbear woke it" without one, unless a "Woke up" note already said so), scheduleId?, editOf?: number (the seq of the message this one replaced, see Editing a message)
assistant.text itemId, text (complete markdown for that block), summary?: true (the turn's summary, written by the runner from end_turn; see "Needs you"), givesWay?: true (on a summary, with bullet replies off: see "The summary"), narration?: true (Claude sent this as a narration block, whose text reaches the runner only as a short summary of what the agent wrote, not its words: see Transient events), final?: true (with one reply, the agent's message after end_turn, the turn's reply: see "Needs you", One reply). A later assistant.text with the same itemId replaces the earlier one where it stands
reasoning itemId, text (summary)
tool.call itemId, name (raw tool name), kind (command | read | edit | write | search | web | mcp | task | todo | image | other; image is image generation), title (one line, e.g. "npm test" or "Edit src/a.ts"), input (object, large strings truncated to 16 KB)
tool.result itemId (matches the call), ok, text (truncated to 64 KB), truncated, blobPath?, images: ImageRef[]
edit.diff itemId, path, hunks: {oldStart, oldLines, newStart, newLines, lines: string[]}[] (lines start with " ", "-" or "+"); sent after tool.call for Edit/MultiEdit/Write when the runner can compute it. One event per file: a tool that changes several files (a Codex patch) has one per path. A later edit.diff with the same itemId and path replaces that file's diff; a new path adds one
approval.requested approvalId, itemId? (absent for a subagent's tools, which have no tool.call), name, title, input (a command, and every argument of an MCP tool or a file edit, whole: a call with one longer than 16 KB is refused with no card; other strings cut as in tool.call), options: ("allow" | "allowAlways" | "deny")[], reason? (why it's asking, when Claude's CLI says: Auto's safety check couldn't clear the call, a rule or a hook asks; never the permission mode itself. Clients show it under the title. A call the CLI refuses without a card, such as one Auto's check stops, is a system.note saying why, when it gives a reason). A subagent's card (no itemId) needs no turn: it can come with no turnId, and it outlives the turn it came in ("A subagent's card")
question.requested approvalId, itemId? (absent for a subagent's), questions: {question, header?, multiSelect, options: {label, description?}[]}[]
secret.requested approvalId, itemId?, label, reason, placeholder?: an agent's ask_secret (Secrets). Answered with secrets.answer, never approvals.respond
approval.queued approvalId, calls: {itemId, name, title, input}[]: the agent's other tool calls from the same reply that are waiting behind this card and expected to ask too, in order, each with its input as a card would show it. A later one replaces the list (it grows as more calls stream in). A client that doesn't know it shows the card on its own, and each queued call asks with a card of its own later ("Queued calls")
approval.resolved approvalId, decision (allow | allowAlways | deny | answered | expired), message?
plan.updated entries: {text, status: "pending" | "in_progress" | "completed"}[]
plan.proposed itemId, text (Markdown): a "Plan first" plan waiting for Mike (see "Plan first")
plan.resolved itemId, decision (go | revise): it was approved, or sent back for another go
turn.started turnId, wokeBy?: {kind, description}[]. A turn the agent starts by itself (a background task finished) has no user.message before it. wokeBy is on such a turn when background work finishing started it: each task that had finished since the last turn, kind as in BackgroundTask (agent | shell | monitor | other), its description possibly empty. Clients mark the time between that turn and the one before it in the transcript (a "6 min later" divider, Mike 3 Nov). A user.message after turn.started was sent while the turn ran and went into it
turn.completed turnId, outcome (completed | interrupted | failed), durationMs, costUsd? (Codex turns have none), usage? (Claude: {inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens}; Codex: {inputTokens, cachedInputTokens, cacheWriteTokens?, outputTokens, reasoningTokens}), error?, errorKind? (usageLimit | contextWindow | auth | network, when a failed turn's cause is known, so a client can offer the fix without reading error), needs? (you | nothing), asks?: Ask[], next?: string[] (with nothing: suggested follow-ups), needsFrom? (tool | text): what a completed turn said it needs from Mike (Needs you), review?: LabReviewLedger (on the turn that answered a review by another lab's findings: see that)
asks.ticked asksSeq, ticked: number[] (indexes into that turn's asks, the whole set now ticked). Outside any turn. The latest one for an asksSeq is that card's ticks
system.note text (e.g. "Resumed session", "Compacted the conversation", "Patch reseed added: action Reseed dev DB."), wake?: true on a background task's notification that went into the running turn, which the agent reads at its next step (see "Once a turn, or once a message"), login?: true on a note about the thread's login running out: its move to another one, its wait for room, or that wait being called off (Pools, "Moves in the transcript"), savedMessage?: true when an early Stop saved a message for the next send. Login and saved-message notes go up to the backend (Sync, "Messages"), so other Macs, the phone and the website show them
error message
action.run actionId, patch, title, command, ok, exitCode?, text (what it printed, truncated to 64 KB), truncated, durationMs, trigger? ("turn.end" when a hook ran it, "worktree.setup" for a new worktree's setup, "worktree.teardown" for an archived thread's worktree teardown (see Worktrees); absent for a chip or tb run). A command that actions.run or a hook ran; outside any turn unless one was running, in which case it carries that turnId
thread.rewound fromSeq, toSeq, files: { undone: string[], failed: { path, reason }[], how: "checkpoint" | "diffs" | "none" }. Mike edited the message at fromSeq (see Editing a message): every event from fromSeq to toSeq (inclusive, always this event's seq - 1) is gone from the conversation, and clients hide them. Outside any turn. The edited message comes next, as a user.message with editOf: fromSeq

Transient events are only sent to subscribers, never persisted, and carry seq of the last persisted event (they don't consume a number):

type fields
assistant.text.delta itemId, text (append)
reasoning.delta itemId, text (append)
tool.output.delta itemId, text (append, for long-running commands if available)

When an item completes, its persisted event (assistant.text, reasoning) replaces whatever the deltas built up. That can be of the other kind: Claude at times sends its reply as a thinking block signed as narration, which streams as reasoning.delta and lands as assistant.text with the same itemId (it is the reply, so end_turn counts it). A client lets the text take the streaming reasoning row's place.

A narration block's text is not the agent's words: with summarised thinking (the only kind the CLI offers besides none) the API sends a short summary of it, in the agent's voice ("I've laid out the full setup steps..."), and the words themselves never reach the runner. On 29 Oct 2026 a numbered walkthrough reached Mike as one such paragraph, twice (thread 66935d23). So that event carries narration: true. An end_turn with no summary bullets, whose turn replied only in narration, is accepted, and its result asks for the whole message again as ordinary text with nothing after it (a text block followed by no tool call is never narration); the runner keeps that text, which it otherwise drops after an accepted end_turn, and persists it with the summary's itemId and no narration, so it takes the summary's place. Readers that list a thread's messages keep only the last assistant.text of an itemId. The Convex mirror keys messages by seq, so the phone and website show the summary and then the reply.