Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

Reading aloud

The read verb on the wire: start_read and reading_control, the reading_progress answers (request_id echo, the optional active:false for a stop with no read open), the read_fetch_cancelled / read_fetch_superseded / read_fetch_failed errors that answer a page fetch by its request_id, their order, the spoken controls open while a fetch is pending, and the Client Core's typed code / requestId / active.

Living doc, checked against the code 2026-11-14

reading.v1 — the read verb on the wire: start_read, reading_control, reading_progress

  • Status: live on protocol 5, additive. An older client ignores every optional field below.
  • Scope: what a client sends to start and steer a read, and every frame that answers it. The page is fetched through the typed tool door (pi_internet_search fetch_url) as a door run on its own task. The read speaks one segment at a time behind a cursor kept per owner.

Client → gateway

command fields answered by
start_read url or text (exactly one), restart?, request_id? the first reading_progress echoing request_id, or an error (below)
reading_control action: pause | resume | next | previous | restart | stop | where; request_id? a reading_progress echoing request_id, or an error (below)

A request_id is cut to 64 characters before it is echoed.

Gateway → client: reading_progress

Sent when a read starts and at each segment boundary (no request_id), and as the answer to a reading command (with the command’s request_id).

field type
request_id string, optional only on the progress that answers a command
entry_id string the cursor’s key, stable across restarts of the same source; "" when active is false
state string reading, paused or finished; stopped when active is false
title, site, url string, optional
cursor, segments, words_total, words_remaining number all 0 when active is false
position string the line where would speak
segment string, optional the segment now in flight
active bool, optional false on the answer to a stop that found no read open; absent on every progress that describes an open read

A stop with no read open

A reading_control stop with no read open is answered by reading_progress {request_id: <the stop's>, active: false, entry_id: "", state: "stopped", …}, never by reading_inactive. Two cases:

  1. It canceled a pending page fetch. Each canceled fetch’s runner is killed. Its start_read is answered first, then the stop, then the spoken “Stopped.”. The order on the wire:

    {"type":"error","code":"read_fetch_cancelled","message":"the page fetch was cancelled","request_id":"r-read"}
    {"type":"reading_progress","request_id":"r-stop","entry_id":"","state":"stopped","cursor":0,"segments":0,"words_total":0,"words_remaining":0,"position":"Nothing is being read.","active":false}

    A client may show “stopped (fetch cancelled)” when the error arrives before the progress, as Vulpine.app does. The trace keeps reading_fetch_failed {code: cancelled} and the reading_control {action: stop} row.

  2. There was nothing to stop. Only the progress above is sent. Nothing is spoken and no trace row is written.

A stop with a read open cancels any pending fetch the same way (the errors first) and then ends the read. Every other control with no read open is answered error {code: reading_inactive}.

Gateway → client: error

error {code, message, request_id?}. request_id is the command the error answers, when it answers one by id.

code when request_id
read_fetch_cancelled a stop (typed or spoken) canceled the page fetch the canceled fetch’s start_read
read_fetch_superseded a newer start_read superseded the page fetch still in flight the superseded fetch’s start_read
read_fetch_failed the fetch was refused (no loadout, not allowed, four door runs already running: busy) or the page could not be fetched the fetch’s start_read
read_source_required, read_source_ambiguous start_read without a source, or with both absent
nothing_to_read the source had nothing readable in it absent
reading_inactive a control other than stop with no read open absent
session_required start_read before start_session absent

The spoken controls

The spoken reading grammar (turn::reading_phrase: “pause”, “keep going”, “next paragraph”, “go back”, “from the top”, “stop reading”, “where are we”, …) is live while a read is open or a page fetch is pending on the session (LiveSessionState::read_fetch_pending, published through sync_reading_active). “Stop reading” said before the page lands cancels the fetch as the typed stop does: the same error, a reading_progress {active: false} with no request_id, and the spoken “Stopped.”. The grammar closes again when the fetch is gone.

where and a read the wake cut. where speaks the position line. On a read that is reading, it then carries on from the sentence the read stopped in. The wake word cuts a playing read (turn_interrupted {reason: invocation_alias}) before “where are we” arrives. A read cut that way, or by a barge-in, and not steered since counts as reading, so where carries on there too. Its reading_control row then carries heard_ms, sentence_offset, sentences and resume_chars, and the answering progress says reading. A read the operator paused, or one the gateway parked (reading_paused), stays paused after where.

After a stop. stop closes the read and the grammar with it: “where are we” said after “stop reading” is not a reading control and goes to the brain. A stopped read’s cursor is kept per owner, and the next start_read of the same source without restart picks it up.

In the Client Core

packages/voice-client passes every answer above through typed, so a skin never parses a message:

  • error → {type: 'error', message, code?, requestId?}. message is "<code>: <message>" for consumers that read only it. code is the wire’s code, set only when it is a plain lower-case word of at most 64 characters. requestId is the wire’s request_id (1 to 64 characters), present on the read_fetch_* errors. An error the client raises itself carries neither.
  • reading_progress → {type: 'reading_progress', requestId?, active?, entryId, state, …}. active is passed through as sent: false only on the inactive answer, absent otherwise.
  • The tool door’s refusals reach ToolActivityState.code (busy, timeout, …) from the refused tool_receipt, so a skin can tell a busy door from a failed one. The page fetch’s own refusal is the read_fetch_failed error above, not a receipt.

Ordering. For one stop the cancel errors come first, then the stop’s reading_progress {active: false}. A client that holds its read’s start_read id can settle the read on the error (matched by requestId) and the stop on the progress (matched by its own request_id), from the frames alone. A refusal with no request_id (reading_inactive, …) answers the oldest waiting command. Vulpine.app does this in apps/glyph/src/readingSettle.ts. The shared view-model (packages/vulpine-voice-ui-state, “wire notices”) shows a read_fetch_* code as the reason a read ended, never as a session error.

Was this page helpful?