What the agent does
The agent reads how the app is wired before it limits anything. In a Koa project like koajs/examples, every example is a directory with an app.js that exports module.exports = new Koa() and only listens when run directly (if (!module.parent) app.listen(3000)), which is what lets the tests mount the app on an ephemeral port. The root package.json pins koa at ^2.2.0, @koa/router at ^8.0.5, koa-body, koa-basic-auth, koa-session and koa-logger, with mocha ^5.0.0, supertest ^3.0.0 and should as dev dependencies; the test script is NODE_ENV=test mocha --harmony --reporter spec --require should */test.js, lint is eslint . with eslint-config-koa, and engines asks for Node >= 7.6. .travis.yml runs npm run lint and npm test on Node stable and 8. There is no limiter anywhere: blog/app.js mounts logger(), a render helper, koaBody() and a router with GET /, GET /post/new, GET /post/:id and POST /post, which pushes the request body onto an in-memory posts array, and base-auth/app.js wraps koa-basic-auth (name tj, pass tobi) in a handler that turns a 401 into a WWW-Authenticate: Basic response.
The agent adds koa-ratelimit to dependencies and mounts it in the two examples where it matters. In blog/app.js a general limiter goes right after logger() and before router.routes(): ratelimit({ driver: 'memory', db: new Map(), duration: 60000, max: 100, id: (ctx) => ctx.ip, errorMessage: 'Too many requests, slow down.', headers: { remaining: 'Rate-Limit-Remaining', reset: 'Rate-Limit-Reset', total: 'Rate-Limit-Total' } }). A second, stricter instance with a lower max is attached only to POST /post by passing it as route middleware (router.post('/post', writeLimit, create)), so reads keep the generous budget and writes get the tight one. In base-auth/app.js the limiter is placed after the custom 401 handler and before auth({ name: 'tj', pass: 'tobi' }), so one client guessing passwords is refused with a 429 after max attempts instead of getting unlimited tries. max and duration are read from RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS with the defaults above, and the agent sets app.proxy = true only in the pull request description as a question, because ctx.ip behind a load balancer reads X-Forwarded-For only when that flag is on and the agent cannot know how the app is deployed.
Tests follow the shape the repository already uses. blog/test.js builds its request with supertest.agent(app.listen()) and uses should, so the agent extends it with a describe('rate limit') block that sets process.env.RATE_LIMIT_MAX = '3' before require('./app'), sends four GET / requests, asserts the first three answer 200 with Rate-Limit-Remaining counting down to 0 and the fourth answers 429 with the errorMessage body and a Retry-After header. base-auth/test.js is new: three wrong-password requests get 401, the fourth gets 429 whether the password is right or not. Because mocha loads every */test.js in one process and each app.js holds its own new Map(), the counters do not leak between examples, and the agent says so in a comment next to the env override.
The agent runs npm install, npm test and npm run lint in its sandbox and keeps the output. It reads koa-ratelimit's own engines field from the installed package and compares it with the repository's node >= 7.6; if the limiter needs a newer Node, the pull request says which version and leaves engines for you to change. .travis.yml, .eslintrc.yml and the other examples are untouched, and Readme.md gets one line under the example list describing the two limited apps and the env variables.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add rate limiting to this Koa app with koa-ratelimit. Read package.json, the test script, .travis.yml and each app.js first. Use the memory driver with a Map, key on ctx.ip, set the remaining, reset and total headers, and read max and window from RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS with sensible defaults. Put a general limiter in front of the routes and a stricter one on write routes as route middleware, and put a limiter in front of any basic-auth check so password guessing is throttled. Do not set app.proxy; ask about it in the PR description. Add supertest tests in the existing mocha style that drive a client over the limit and assert the 429, the error message and the headers. Run npm test and npm run lint, check koa-ratelimit's engines field against the repository's, and include the output. Do not change the CI config. 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
What comes back is a pull request that changes package.json (the new dependency), blog/app.js, base-auth/app.js and blog/test.js, and adds base-auth/test.js plus one line in Readme.md. The limiter code is a handful of lines per app; the diff is mostly tests.
The description lists each limiter with its max, duration and where it is mounted, quotes the mocha summary and the eslint result, states the engines comparison, and asks one question: whether the app runs behind a proxy and should set app.proxy = true so ctx.ip is the client and not the balancer. Every command and its full output is in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer checks the two limits against real traffic, decides the proxy question, and considers whether the memory driver is enough: it counts per process, so two instances behind a balancer each allow max. A follow-up message to the same session can switch to driver: 'redis' with ioredis once a Redis URL exists.
Run it on every Koa service with no rate limit
A team with several Koa services starts one run per repository with one POST /o/{org}/sessions each, the repository in resources and this prompt as input. Each run reads its own router and auth middleware, so a service with a login route gets the strict limiter there and a service that is only an API gets the general one.
Send a request_id, a UUID v5 of the repository's full name, so a retried call returns the run it already started. The key's webhook_url reports when each run the key starts finishes, with the run's final answer in result.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Adding a limiter is easy; knowing where it belongs in a middleware chain and proving the 429 actually fires is the work. The agent reads the order of app.use calls, places the limiter so the 401 handler still wraps it, and drives the app over the limit with supertest in a sandbox of its own, so nothing on your machine is touched and the test output is kept.
The pull request carries the mounted middleware, the tests that hit the limit and the passing run, so review is reading a diff rather than reproducing a flood of requests locally. Several services can be done at once, each in its own sandbox with its own pull request.
Frequently asked questions
Does it need Redis?
No. The memory driver keeps counters in a Map inside the process, which is right for one instance and for tests. If you run several instances, say so in the prompt and the agent uses driver: 'redis' with an ioredis client and a REDIS_URL variable instead.
Will the limiter break the existing tests?
The defaults are high enough that the existing supertest cases never reach them, and the new rate-limit tests lower RATE_LIMIT_MAX through the environment before requiring the app. Each example app holds its own Map, so counters do not cross between test files run in one mocha process.
What about clients behind a proxy or load balancer?
ctx.ip is the socket address unless app.proxy = true, in which case Koa reads X-Forwarded-For. The agent does not guess your deployment: it leaves the flag off and asks in the pull request. Turning it on without a trusted proxy lets a client spoof its own key.
Can I limit only the POST routes?
Yes. The limiter is a normal middleware, so the agent passes a separate instance as route middleware on the write routes and leaves the general one off if you ask. Say which routes and what budget in the prompt.
More Koa jobs
The same job on other stacks
- Add Rate Limiting to a Ktor API (Ktor)
- Add Rate Limiting to a LangGraph Agent (LangGraph)
- Add Rate Limiting to a Leptos Server (Leptos)