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:
-
It canceled a pending page fetch. Each canceled fetch’s runner is killed. Its
start_readis 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 thereading_control {action: stop}row. -
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?}.messageis"<code>: <message>"for consumers that read only it.codeis the wire’s code, set only when it is a plain lower-case word of at most 64 characters.requestIdis the wire’srequest_id(1 to 64 characters), present on theread_fetch_*errors. An error the client raises itself carries neither.reading_progress→{type: 'reading_progress', requestId?, active?, entryId, state, …}.activeis passed through as sent:falseonly on the inactive answer, absent otherwise.- The tool door’s refusals reach
ToolActivityState.code(busy,timeout, …) from the refusedtool_receipt, so a skin can tell a busy door from a failed one. The page fetch’s own refusal is theread_fetch_failederror 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.