---
title: "Reading aloud"
description: "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."
type: "living"
source: "docs/contracts/reading.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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:

   ```json
   {"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.

