useSessionStream subscribes to one channel of a session and updates a records array as new records arrive. It reads the out channel by default (the agent’s output) or in (the input channel). It is read-only; useSession is reserved for two-way (read and write) communication.
Requires a Public Access Token with the
read:sessions:{id} scope. See Realtime
auth for generating one.Basic usage
Pass the session id (or external id) and anaccessToken. The hook returns the records received so far, the last control record, the cursor of the last record seen, and any error:
Options
records: every data record received so far, in arrival order. Control records are delivered toonControlinstead.lastEventId: the cursor of the last record seen. Persist it and pass it back as thelastEventIdoption to resume.lastControl: the last control record (for exampleturn-complete).stop: abort the subscription, keeping the records received so far.
Start from the latest record
By default the hook replays the channel history, then live-tails. Passfrom: "latest" to start at the current tail (the latest record, then live updates) instead of replaying, and maxRecords to bound memory:
from: "latest" requires a server that supports it. Against an older server a client that passes
it degrades safely to a full replay.Resume from a cursor
The hook resumes automatically across a component remount. A full page reload clears in-memory state, so to resume there, persist the returnedlastEventId and pass it back on the next load. The channel then continues after that record with no replay and no gap:
React to control records
Control records (such asturn-complete) never enter records. Handle them with onControl, or read the latest from lastControl:
refreshAccessToken (see Realtime auth). To read a session channel outside React, use session.out.read().
