All jobs

Add Streaming Responses to a Hono API

Yes. An agent adds NDJSON and server-sent event endpoints to your Hono API with the hono/streaming helpers, tests them with the Workers Vitest pool and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the API into its own cloud sandbox and reads the routes before it adds a streaming one. In a Hono app like the blog workspace in honojs/examples, package.json pins hono ^4.2.4 with wrangler ^3.53.0, vitest 1.3.0 and @cloudflare/vitest-pool-workers, wrangler.example.toml binds a KV namespace as BLOG_EXAMPLE with nodejs_compat, and src/index.ts mounts two sub-apps under /api: a middleware app that applies prettyJSON to everything and basicAuth to non-GET requests on /posts/*, and src/api.ts with the five CRUD routes. src/model.ts stores each post in KV under a v1:post: prefix, and getPosts calls KV.list once, then KV.get for each key in sequence and returns the whole array at the end. Every response is c.json built after all the reads finish; nothing streams.

The agent adds two routes to src/api.ts with the helpers from hono/streaming. GET /posts/export uses stream to write one JSON line per post as application/x-ndjson, so a client with thousands of posts starts receiving the first one while KV is still being read for the last. GET /posts/events uses streamSSE to send a post event per post and a final done event with the count, with id fields so a reconnecting EventSource can resume from Last-Event-ID. Both read through a new iteratePosts async generator in src/model.ts that yields each post as soon as its KV.get returns; unlike getPosts, it follows list_complete and cursor across pages of KV.list, so the export is not capped at the first page. Each route registers stream.onAbort to stop reading KV when the client disconnects, and the existing cors() on /posts/* covers both because they sit under the same path.

Two existing behaviours need checking rather than changing. The prettyJSON middleware only rewrites responses with a JSON content type, so NDJSON and text/event-stream pass through untouched; the basicAuth guard applies to non-GET methods only, so the new GET routes are as public as GET /posts already is, and the pull request says so in one sentence so a reviewer can decide whether that is right. The Bindings type in src/bindings.ts needs no change, and wrangler.example.toml keeps its compatibility_date, since streaming bodies need nothing beyond what the Workers runtime already provides.

Tests follow src/api.test.ts, which calls worker.request(path, init, env) with env from cloudflare:test and runs under defineWorkersConfig in vitest.config.ts with isolatedStorage off. The agent adds cases that create two posts, request /posts/export, read the body with res.text() and assert two parseable lines and the application/x-ndjson header, then request /posts/events and assert text/event-stream, two event: post blocks with id lines and one event: done. A third case creates more posts than one KV.list page in the test environment would return only if the prompt asks for it, because the local KV emulation and production page sizes differ; the agent says which it did. It runs npm -w blog run test, which is vitest --run, and npx tsc --noEmit against the workspace's tsconfig.json.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add streaming responses to this Hono API. Read package.json, wrangler.example.toml (or wrangler.toml), vitest.config.ts, tsconfig.json and every file under src/ first. In src/model.ts add an iteratePosts async generator that yields each post as its KV read completes and follows list_complete and cursor across KV.list pages. In src/api.ts add GET /posts/export, which streams one JSON object per line as application/x-ndjson with the stream helper from hono/streaming, and GET /posts/events, which uses streamSSE to send one post event per post with an id and a final done event with the count; register onAbort on both so reading stops when the client disconnects. Do not change the existing routes, the basicAuth rule or the CORS scope, but state in the pull request that both new routes are GET and therefore unauthenticated like GET /posts. Add Vitest cases in the style of src/api.test.ts that check the NDJSON lines and content type and the SSE events, ids and content type. Run the workspace test script and npx tsc --noEmit, and open a pull request listing the routes, the content types, the abort handling and the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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

What comes back is a pull request on its own branch that adds iteratePosts to src/model.ts, the two routes to src/api.ts, and new cases to src/api.test.ts; src/index.ts, src/bindings.ts, wrangler.example.toml and vitest.config.ts are unchanged. No dependency is added, because hono/streaming ships inside the hono package the app already has.

The description names each route with its content type and framing, explains the onAbort handling and the KV pagination fix, states that the routes are unauthenticated GETs like the existing list, and quotes the Vitest summary and the tsc result. The transcript at GET /o/{org}/sessions/{id}/messages keeps vitest --run and npx tsc --noEmit with their output, so a reviewer can see the new cases pass in the Workers pool rather than read a sentence saying so.

Before merging, a reviewer decides whether the export should sit behind basicAuth like the write routes, and checks that the id on each SSE event is stable across requests so resuming is meaningful. A follow-up on the same session can add ?since= filtering to the export, or a route that streams tokens from a model provider through the same streamText helper.

Run it on every endpoint that buffers a long response

A team with several Hono services runs this once per repository. From a script, send the body above to POST /o/{org}/sessions with each repository in resources, one run per repository, and a request_id that is a UUID v5 of the repository name so a retry is safe. Give the key a webhook_url and every run the key starts posts run.completed with data.session_url when its turn ends; a handler reads the pull request link from the session.

To catch the next buffered list, add an automation to the Project with a github trigger on pull_request.opened and pull_request.synchronize and a prompt that reads the pull request's routes for a handler that builds an array in a loop and returns it with c.json, and comments with the streaming version. The trigger clones that branch and places the event after the prompt, and 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?

Streaming is simple to add and easy to break quietly: a middleware that rewrites JSON, an auth rule that happens not to apply, a list call that stops at the first page, a client that disconnects while the server keeps reading. The agent reads the actual middleware chain and storage code in its own sandbox before it writes the routes, and it proves the framing with tests that run in the Workers runtime rather than in Node.

Every vitest --run and tsc and its output stay in the run's transcript, so the pull request's claim that two posts arrive as two NDJSON lines and two SSE events is checkable, and the laptop that handed off the task is free while it happens. Several services can get the same routes at once, each in its own sandbox and its own pull request.

Frequently asked questions

Does this work outside Cloudflare Workers?

Yes. The hono/streaming helpers return a standard Response with a ReadableStream body, so the same routes run on Deno, Bun and Node through @hono/node-server. The tests here use the Workers Vitest pool because that is the runtime this app deploys to; on another runtime the agent runs the app's own test setup.

What happens when the client disconnects mid-stream?

Both routes register stream.onAbort, which sets a flag the for await loop checks before the next KV.get, so the Worker stops reading storage instead of finishing the whole export for nobody. The pull request names the handler so a reviewer can see it.

Why NDJSON instead of one JSON array?

An array is not parseable until the closing bracket arrives, which defeats the point of streaming. One JSON object per line lets a client parse each line as it lands, and application/x-ndjson tells it to expect that framing. The existing GET /posts keeps returning an array for callers that want one.

Can the same approach stream tokens from a model?

Yes. streamText and streamSSE are the same helpers people use to relay a provider's token stream, so a follow-up that pipes a model response through streamSSE reuses the abort handling and the test pattern this pull request sets up.

Are the new routes protected by the basic auth?

No, and the pull request says so. src/index.ts applies basicAuth only to non-GET requests on /posts/*, so GET /posts/export and GET /posts/events are as public as GET /posts is today. Moving them behind auth is a one-line change to that rule, which the agent leaves to the reviewer rather than changing the API's security model on its own.

More Hono jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading