What the agent does
The agent reads the server and the page before adding an event. In a chat laid out like socketio/chat-example, index.js forks one worker per CPU from the primary with cluster.fork({ PORT: 3000 + i }) and setupPrimary() from @socket.io/cluster-adapter, and each worker opens chat.db with sqlite, creates a messages table keyed by a unique client_offset, and builds a Server with connectionStateRecovery: {} and the cluster adapter. The only event is chat message: the handler inserts the row, ignores a SQLITE_CONSTRAINT error from a retried offset, calls io.emit with the row id, and acknowledges; a socket that did not recover replays rows after handshake.auth.serverOffset. index.html connects with ackTimeout: 10000, retries: 3 and a serverOffset in auth, sends on form submit with a clientOffset built from socket.id and a counter, and appends each incoming message to a list. There is no username, no input listener, and package.json has no test script.
A typing indicator must not be reliable, which is the design decision the agent makes first. The client in index.html gets an input listener on the text field that emits typing at most once every two seconds while the user types (a timestamp guard, not a timer per keystroke) and stop typing from a 1500 ms timer that resets on every keystroke and on submit. Both are sent with socket.volatile.emit, so a burst during a reconnect is dropped rather than queued and replayed after the chat message retries, and neither carries an acknowledgement. Because the page has no identity, the agent adds a username to auth on connect, chosen once and kept in sessionStorage, so an indicator can say who is typing.
On the server the handler is small and guarded. socket.on('typing') calls socket.broadcast.volatile.emit('typing', username), never io.emit, so the sender does not see their own indicator, and the cluster adapter relays the broadcast to the other workers' sockets the same way it relays chat message. The server also keeps a timer per socket: a typing event arms a 3000 ms timeout that emits stop typing on the socket's behalf if the client goes quiet or disconnects without sending it, and the disconnect handler clears both the timer and the indicator. The username is read from socket.handshake.auth.username, trimmed and capped in length, and a socket without one is given a short generated name instead of being refused, so the existing chat keeps working for old pages.
The page shows the state under the message list: an element that reads Alice is typing or Alice and Bob are typing from a Set of names updated by the two events, cleared for a name on stop typing. To prove the events cross workers, the agent writes test/typing.test.js under node --test with socket.io-client: it starts the server with two workers on fixed ports, connects a client to each, types on the first and asserts the second receives typing with the right name and then stop typing within the server timeout even when the first client never sends it; package.json gets a test script. The agent runs it in the sandbox, then opens the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a typing indicator to this Socket.IO chat. Read index.js, index.html, package.json and README.md first. In index.html add a username chosen once and kept in sessionStorage, sent in auth on connect; add an input listener that emits typing with socket.volatile.emit at most once every two seconds while the user types, and stop typing from a 1500 ms timer reset on each keystroke and on submit; show who is typing under the message list from a Set of names. In index.js read and cap the username from handshake.auth, give a socket without one a generated name, handle typing with socket.broadcast.volatile.emit, keep a per-socket 3000 ms timeout that emits stop typing when the client goes quiet or disconnects, and clear it on disconnect. Write test/typing.test.js under node --test that starts the server with two workers, connects a socket.io-client to each, types on the first and asserts the second receives typing with the name and stop typing within the timeout without the first client sending it; add a test script. Run the test until it passes and open a pull request that explains why the events are volatile and what the server timeout covers.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes index.js, index.html and package.json, and adds test/typing.test.js. Its description explains the three choices in plain terms: the events are volatile because a stale indicator is worse than a missed one, the client throttles so a fast typist sends a handful of events per message rather than one per key, and the server timeout exists so a closed laptop does not leave a name on everyone's screen.
It quotes the test output from the sandbox showing the typing and stop typing events arriving on a socket connected to a different worker, which is the case the cluster adapter has to handle, and it states what did not change: chat message, its acknowledgement and retry path, and the SQLite replay.
Before merging, a reviewer decides whether the indicator should be limited to a room once the chat has rooms, whether the generated name for an old page is acceptable or the page should ask, and whether the 1500 ms and 3000 ms timers suit the product.
Run it on every Linear issue labelled chat
An automation on the Project with a linear trigger on linear.issue.labeled, chat in config.labels, and the prompt "this issue names a presence or typing behaviour to change; adjust the client throttle, the server timeout or the display, extend test/typing.test.js, and open a pull request" starts one run per labelled issue once the indicator exists. The trigger adds the issue after the prompt and fills in nothing else.
A team with several Socket.IO chats sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own app: a chat with rooms gets the broadcast scoped with socket.to(room), and one with a TypeScript client gets the events added to its typed event map.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A typing indicator looks like the smallest feature in a chat, and it is where reliability settings go wrong: an indicator sent with a normal emit is queued during a reconnect and arrives after the message it announced, a per-keystroke emit floods a busy room, and a missing server timeout leaves ghosts typing forever. The agent reads how the chat already handles retries and offsets, keeps the new events out of that path on purpose, and proves the cross-worker delivery with a test that runs two workers in its sandbox.
The test output and the diff stay with the run, so a reviewer sees the indicator arrive on a socket served by another process and clear on the timeout. A team that owns several chat services makes the same change across all of them at once, each in its own sandbox.
Frequently asked questions
Why volatile events?
A typing indicator is only useful now. If the client is reconnecting, a queued typing delivered seconds later is wrong, and it would compete with the chat message retries the page already configures. socket.volatile.emit drops the event when the connection is not ready instead of buffering it.
Does it work with several workers?
Yes. The server uses socket.broadcast.emit, which the cluster adapter already relays between the forked workers, the same path chat message takes. The test connects a client to each of two workers and asserts the indicator crosses from one to the other.
What stops a name from being stuck as typing?
Two things: the client's 1500 ms timer emits stop typing when the user pauses or submits, and the server's own 3000 ms timeout emits it on the socket's behalf if the client goes quiet or disconnects. The test covers the second case by never sending stop typing from the client.
Does the chat need accounts for this?
No. The page asks for a display name once, keeps it in sessionStorage and sends it in auth on connect. The server caps its length and generates a short name for a page that sends none, so the existing chat keeps working while the indicator has something to show.
More Socket.IO jobs
More jobs like this: Hand off a long task
- Add a Typo Check to a Docusaurus Site in CI (Docusaurus)
- Add a Typo Check to an Eleventy Blog in CI (Eleventy)
- Add a Typo Check to a Hugo Site (Hugo)