What the agent does
The agent reads how data moves today before it adds a second channel. In an app laid out like trpc/examples-next-prisma-starter, src/server/routers/post.ts exposes post.list (cursor pagination over prisma.post.findMany, newest first, with a nextCursor), post.byId and post.add, all on publicProcedure, and src/server/routers/_app.ts merges them with a healthcheck query. src/pages/index.tsx renders trpc.post.list.useInfiniteQuery and an add mutation whose onSuccess calls utils.post.list.invalidate(), so the tab that posted refetches and every other tab stays stale until it reloads. src/utils/trpc.ts builds the client with createTRPCNext, a loggerLink and one httpBatchStreamLink at /api/trpc, with superjson as the transformer and ssr: false; src/pages/api/trpc/[trpc].ts serves it with createNextApiHandler. package.json has the four @trpc/* packages on the canary tag, Next 15, React 19, Prisma 6, vitest for src/server/routers/post.test.ts and Playwright for playwright/smoke.test.ts.
Server-sent events need a route that can hold a response open and stream it, and the Pages Router adapter in [trpc].ts is built around a single response per request. So the agent adds src/app/api/trpc/[trpc]/route.ts with fetchRequestHandler from @trpc/server/adapters/fetch, serving the same appRouter and createContext, and leaves the Pages Router handler in place for the batched queries, since Next 15 allows both routers in one project. In src/server/trpc.ts it turns on sse: { ping: { enabled: true, intervalMs: 2_000 }, client: { reconnectAfterInactivityMs: 5_000 } } in initTRPC.create, so a proxy that buffers idle connections drops none.
The subscription itself is post.onAdd in post.ts: an async function* that takes { lastEventId: z.string().nullish() }, first replays every post created after the one the client last saw (a findMany with createdAt greater than that post's, which the schema comment already marks as unique for cursor use), then listens on a process-wide EventEmitter that post.add emits on after prisma.post.create, yielding each post wrapped in tracked(post.id, post) so a client that reconnects resumes from its last id, and returning when opts.signal aborts. On the client, src/utils/trpc.ts gets a splitLink whose condition is op.type === 'subscription', sending those to httpSubscriptionLink({ url: '/api/trpc', transformer }) and everything else to the existing httpBatchStreamLink. index.tsx adds trpc.post.onAdd.useSubscription(undefined, { onData }), where onData writes the post into the first page of the post.list infinite query cache with utils.post.list.setInfiniteData, so the list grows in place instead of refetching.
The agent writes two tests. post.test.ts gains a case that calls caller.post.onAdd({}), adds a post through caller.post.add, reads one value from the iterator and checks its id and title, then calls return() on the iterator. playwright/smoke.test.ts gains a case that opens two pages, adds a post in one with the existing form, and waits for its title in the other without page.reload(). In its sandbox it starts Postgres, runs pnpm prebuild (prisma generate then migrate deploy), pnpm test-unit, pnpm build, pnpm test-e2e and pnpm tsc, the same steps as .github/workflows Testing, and opens the pull request only when all four pass.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add real-time updates to this tRPC and Next.js app so that a post added in one browser tab appears in every open tab without a refresh. Read package.json, src/server/trpc.ts, src/server/routers/post.ts, src/server/routers/_app.ts, src/server/context.ts, src/utils/trpc.ts, src/pages/api/trpc/[trpc].ts, src/pages/index.tsx, src/server/routers/post.test.ts, playwright/smoke.test.ts and .github/workflows first. Add a post.onAdd subscription as an async generator that replays posts newer than lastEventId, then yields each new post wrapped in tracked() from an event emitter that post.add emits on, and stops on the abort signal. Serve subscriptions over server-sent events with the fetch adapter in an App Router route at the same /api/trpc path, enable the sse ping and inactivity reconnect in initTRPC, and keep the Pages Router handler for queries and mutations. On the client add a splitLink that sends subscriptions to httpSubscriptionLink and everything else to the existing link, and subscribe on the index page, inserting each post into the post.list infinite query cache instead of refetching. Add a vitest case for the subscription and a two-tab Playwright test. Run pnpm prebuild, pnpm test-unit, pnpm build, pnpm test-e2e and pnpm tsc with a Postgres, and open a pull request. Do not change the Prisma schema or the existing procedures' inputs.",
"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 adds src/app/api/trpc/[trpc]/route.ts and src/server/events.ts (the emitter), edits src/server/trpc.ts, src/server/routers/post.ts, src/utils/trpc.ts and src/pages/index.tsx, and extends post.test.ts and playwright/smoke.test.ts. Its description pastes the unit and end-to-end output, a curl of the subscription endpoint showing the event: data frames with their id lines, and the reason the App Router route exists next to the Pages Router one.
A reviewer checks that the in-process emitter is the right fan-out for their deployment (one Node process, or a platform that runs several, where Postgres LISTEN/NOTIFY or Redis would replace it), that the replay query is bounded, and that setInfiniteData keeps the nextCursor of each page intact so "Load More" still works after a live insert.
Run it on every new tRPC service
A team that starts services from this starter runs the request once per new repository from its own server: one POST /o/{org}/sessions per repository, each 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 rather than opening a second pull request. Each run reads its own router: a service whose list procedure is a plain query rather than an infinite one gets setData instead of setInfiniteData, and one already on the App Router gets no second handler.
A Linear issue is the other way in. An automation on the Project with a linear trigger on linear.issue.labeled and realtime among its labels runs the same prompt with the issue appended, so "Live comments on post pages" starts a run that adds the subscription for that router instead of post. The automation starts at most max_runs_per_hour runs in an hour.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A subscription touches the server config, a router, an adapter, the client links and a page, and the failure modes are quiet: a stream that works in development and stalls behind a proxy, a reconnect that replays nothing, a cache write that drops the cursor. In its sandbox the agent runs the real two-tab test against a built app, with the SSE ping on, and the pull request carries that result.
Every command and its output is kept with the run, from prisma migrate deploy to the Playwright report, so a reviewer can see the raw event frames the endpoint produced. The same request runs across every tRPC service a team keeps, each run reading that service's own router.
Frequently asked questions
Why server-sent events and not WebSockets?
SSE runs over the same /api/trpc path as the rest of the API, needs no separate server process or port, and tRPC's httpSubscriptionLink handles reconnection with lastEventId on its own. WebSockets need a long-lived server that a Next.js API route cannot host, so they would change the deployment; the generator code is the same if that is ever wanted.
Does this work if the app runs on more than one server?
Only for clients attached to the server that received the mutation, since the emitter is in-process. The pull request says so and names the two usual replacements, Postgres LISTEN/NOTIFY or a Redis channel, which swap in behind the same generator without changing the client.
What happens when a client loses the connection?
The browser's EventSource reconnects and sends the last id it received; the subscription's lastEventId input is that id, and the generator replays every post created after it before listening again. The tracked() wrapper is what gives each event its id, and the server ping keeps an idle connection from being closed as dead.
Will the existing queries and mutations change?
No. The splitLink sends only operations whose type is subscription to the new link; post.list, post.byId and post.add keep going through httpBatchStreamLink to the Pages Router handler, with the same superjson transformer on both links.
More tRPC jobs
The same job on other stacks
- Add Realtime Updates to a Supabase Todo List (Supabase)