stream_poll
Fetch new frames incrementally from an open session with a private, per-consumer cursor. Acknowledge delivery via since_seq to release frames, and optionally parse each frame server-side.
Instructions
Per-consumer incremental frame poll on an open session — a private cursor with its own deframer, fully independent of read (the two never steal frames from each other). Call with session_id to create a subscription: the result carries its subscription_id plus any frames already buffered. Call with that subscription_id to fetch what arrived since; frames carry a monotonic per-subscription seq, and next_seq is the seq the next frame will get. since_seq acknowledges delivery: frames with seq < since_seq are released — ack with the last delivered frame's seq + 1, not next_seq (next_seq can run ahead of a max_frames-capped page, and acknowledging frames never delivered is a loud error). Each page also stops at max_inline_bytes of rendered payload (default 4096, metered as each frame's hex length + text length; page_bytes reports the page's actual total) — whole frames only, in seq order; a first frame alone beyond the budget is still delivered, alone, with oversized_frame: true, so delivery always makes progress. Omit since_seq and the unacknowledged frames are redelivered unchanged (idempotent re-read, so a lost response costs nothing). A consumer that lags loses the oldest retained frames beyond 1024, counted cumulatively in dropped_frames; a subscription the session's byte buffer overflowed past counts the gaps in dropped_chunks — never silently. close: true releases the subscription (result carries closed: true). At most 8 subscriptions per session; ones idle beyond 120 s are swept by later stream_poll calls, and closing the session releases them all. Every result folds in the session's live counters as stats. Returns immediately with whatever is available — never waits; a poll with nothing left to deliver on a dead port errors loudly instead of looking healthy. Optionally pass parse: {device, command} when CREATING a subscription (never on a follow-up poll — that is a loud error) to parse every frame server-side with that workspace command's response.parse: each frame then carries parsed (the field values) or parse_error (the per-frame reason; one bad frame never stops the stream), parsed once at arrival so redelivery repeats the identical outcome, and every result echoes parse: {device, command} plus the command's units (same semantics as run_command). A device or command that does not exist, or a command without a response.parse block, fails subscription creation loudly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| close | No | Release the subscription instead of polling it | |
| parse | No | Only when creating a subscription (with session_id): parse every frame server-side with this workspace command's response.parse — frames carry parsed or parse_error; a follow-up poll passing parse is a loud error | |
| since_seq | No | Acknowledge delivery: release frames with seq < since_seq — pass the last delivered frame's seq + 1; omit to redeliver the unacknowledged frames | |
| max_frames | No | ||
| session_id | No | Open session to subscribe to; required when no subscription_id is given | |
| subscription_id | No | Subscription from an earlier stream_poll; required for follow-up polls and for close | |
| max_inline_bytes | No | Byte budget for one page's inlined frames, metered as each frame's rendered hex length + text length; whole frames only, except a single first frame beyond the budget (delivered with oversized_frame: true) |