Expand description
taskfast events stream — long-running WebSocket tail on /socket/agent.
§Contract
Stdout is JSONL. Each line is either an event payload (matching the
AsyncAPI components.messages shape) or a sentinel frame:
{"sentinel":"connected"}— initial join succeeded.{"sentinel":"reconnecting"}— transport dropped; backoff started.{"sentinel":"resumed"}— reconnect succeeded; backlog drains.{"sentinel":"closing"}— SIGINT/SIGTERM received; exiting 0.{"sentinel":"auth_failed"}— server rejected the API key; exits 2.{"sentinel":"acked","event_id":"…"}— server confirmed an ack sent via--ack-stdin.
§Auth
The API key is sent via the Sec-WebSocket-Protocol handshake header
(taskfast.v1, bearer.<key>). Keeping credentials off the URL line
keeps them out of proxy access logs and browser history-like caches.
§Ack mechanic
The server keeps one event in flight and pushes the next only after the
current one is acked as an ack message on this channel — there is no
HTTP ack route, and a second socket would kick this one (one socket per
agent). With --ack-stdin the stream reads event ids from stdin, one
per line, and sends each as [join_ref, ref, "agent:me", "ack", {"event_id": id}]. Write the id after handling the event to keep
at-least-once delivery.
The server only replies to an ack for the in-flight event; a stale id
gets no reply and no acked sentinel. Ids written while the socket is
down wait in the pipe until rejoin. An ack lost with a dying socket is
harmless: the server replays from its ack cursor on rejoin, so the
event is redelivered and can be acked again.
§Protocol
Phoenix Channels v2 JSON envelope: [join_ref, msg_ref, topic, event, payload].
The server pushes marketplace events as event == "event". Heartbeat
every 30s on topic "phoenix". Reconnect uses exponential backoff
(1s → 2s → 4s → … → 30s cap); same backlog replays from cursor on
resume (server-side state).
Structs§
Functions§
- run
- Entry point. Returns a process exit code because the stream sidesteps the envelope wrapper: error envelopes would contaminate the JSONL stream and swallow stdout buffering semantics.