What the agent does
The agent reads the middleware chain before it adds a link to it. In an API laid out like javieraviles/node-typescript-koa-rest, src/server.ts opens a TypeORM connection and then builds the app in order: koa-helmet's contentSecurityPolicy, @koa/cors with defaults, the winston logger from src/logger.ts that times each request and logs method url status ms, koa-bodyparser, the unprotectedRouter (GET / answering Hello World!), koa-jwt with .unless({ path: [/^\/swagger-/] }), and the protectedRouter, a SwaggerRouter from koa-swagger-decorator that serves the user routes, /swagger-json and /swagger-html. package.json runs koa ^2.13.1 with engines at Node 14.x.x and npm 6.x.x, the Dockerfile builds on node:14-alpine, and tsconfig.json targets ES2017 with lib: ["es6"] and noImplicitAny. The lint script is tsc --noEmit plus ESLint, test is Jest 26 through ts-jest, and the two test files under tests/ mock typeorm and class-validator and never start the server.
The agent installs koa-compress and, when tsc --noEmit asks for them, its type declarations, and adds src/compression.ts exporting a configured middleware: threshold: 1024, so the twelve-byte hello-world text and a single user object stay as they are; br left at the package's default quality of 4 because Node 14 has Brotli in zlib; gzip and deflate as fallbacks; and the default filter, the compressible list, which covers application/json and text/html. zstd needs nothing: koa-compress enables it only when zlib.createZstdCompress exists, which Node 14 lacks and a later Node provides. In server.ts the middleware goes right after cors() and before the logger, so every router response, the JSON user list and the swagger page, passes through it, and the timing the logger writes includes the compression.
Two responses are handled on purpose. /swagger-html is the largest page the app serves and is the one a reviewer will see change in the network panel, so the pull request measures it; and the error path in src/logger.ts, which sets ctx.body = err.message on a thrown error, stays uncompressed under the threshold, so a 401 from koa-jwt reads the same as before. The agent leaves ctx.compress alone in the controllers: the README's DELETE /testusers and the user routes return small bodies, and forcing compression on them would cost CPU for nothing.
Because the existing tests never open a socket, the agent writes tests/compression.test.ts with Node's own http and zlib: it builds a small Koa app with the exported middleware and a route that answers a JSON body larger than the threshold, listens on port 0, requests it with Accept-Encoding: gzip and checks content-encoding: gzip and that gunzipSync of the bytes parses to the original; repeats with br and brotliDecompressSync; requests a body the size of the hello-world text and asserts no content-encoding; and requests with no Accept-Encoding and asserts identity, which is the package's defaultEncoding. The test uses no new dependency and runs under ts-jest with the testMatch already in package.json. The agent runs npm ci, npm run lint and npm test in its sandbox, then starts the server against a Postgres it runs there, as docker-compose.yml does with postgres:10-alpine, and records the content-length of /swagger-html with and without Accept-Encoding: br.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add response compression to this Koa and TypeScript API. Read package.json, tsconfig.json, src/server.ts, src/logger.ts, src/config.ts, src/unprotectedRoutes.ts, src/protectedRoutes.ts, src/controller/user.ts, the Dockerfile and the tests under tests first. Install koa-compress and any type declarations tsc --noEmit needs. Add src/compression.ts exporting the middleware with a 1024-byte threshold, brotli at the default quality, gzip and deflate, and use it in server.ts after cors and before the logger. Write tests/compression.test.ts with node's http and zlib that start a small Koa app with the middleware and assert gzip and br responses decompress to the body, that a body under the threshold is not encoded, and that a request without Accept-Encoding gets identity. Run npm ci, npm run lint and npm test, then start the server against a Postgres in the sandbox and record the size of /swagger-html with and without Accept-Encoding: br. Quote the output. Open a pull request.",
"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/compression.ts and tests/compression.test.ts, changes src/server.ts (one app.use), package.json and package-lock.json (the dependency), and the README's included-middleware list. Its description quotes npm run lint and npm test, and shows the two content-length values for /swagger-html, plain and brotli, from the agent's own server.
A reviewer starts the server, opens /swagger-html with the network panel and reads the content-encoding header, then requests / and sees none. In the code they check the middleware's position, that nothing above it in server.ts writes a body, and that the threshold matches what they want: a lower one compresses the single-user responses, which the pull request leaves as a one-number change.
No route, controller or entity changes. The Postman collection under integrationtests/ and the newman scripts keep working, since newman decompresses what it is sent.
Run it on every new Node service
A platform team that wants every HTTP service to compress its responses starts this from its own server: a handler lists the repositories and, for each one whose package.json has koa, express or fastify and no compression package, sends this body to POST /o/{org}/sessions with that repository in resources. A request_id that is a UUID v5 of the repository's full name keeps a retried call from starting a second run, since the same request_id and body return the run already started.
A Rush automation with a github trigger on pull_request.opened can watch for a new route whose response would be large; its runs are read-only, so they comment and do not push. The run that adds the middleware is the one above.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Compression is a header you have to see to believe. The agent runs the server in its own sandbox with a database beside it, requests the swagger page with and without Accept-Encoding, and keeps the two sizes and the test output with the pull request, so the reviewer compares numbers the agent measured rather than a claim that the middleware is on.
A team with several Node services on different frameworks starts the same request for each at once. Each run reads its own middleware chain, Node version and routes, so a Node 14 service gets Brotli and gzip and a Node 22 service also gets zstd, and each pull request says which.
Frequently asked questions
Where does the middleware go in server.ts?
After cors() and before the winston logger, so the two routers and the swagger pages are all downstream of it. Koa middleware wraps what comes after it, and a compressor placed after a router would never see that router's body.
Does Brotli work on Node 14?
Yes. zlib has had Brotli since Node 11.7, and koa-compress uses it at its default quality of 4. zstd is different: the package turns it on only when zlib.createZstdCompress exists, which arrives in Node 22.15, so on this engines setting it stays off without any configuration.
Why a 1024-byte threshold?
It is the package default and it keeps the small bodies this API returns, the hello-world text, one user, a 401 message, out of the compressor, where the CPU cost would exceed the bytes saved. The user list and the swagger page are over it. The number is one line in src/compression.ts.
Why not use supertest for the test?
The repository has no HTTP test dependency, and Node's http and zlib are enough to request a listening app and decompress what it returns. Adding supertest would be a reasonable choice too; the pull request says so and keeps the dependency list as it is.