All jobs

Add Graceful Shutdown to a grammY Bot

Yes. An agent stops long polling on SIGINT and SIGTERM with bot.stop() or the runner's handle, fixes the Docker CMD so the signal arrives, 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 reads how each bot starts, because the stop call depends on it. In a repository laid out like grammyjs/examples, echo.ts, menu.ts, stats.ts, stats-lazy.ts and menu-with-conversation.ts end with bot.start(), which long-polls Telegram; runner.ts uses run(bot) from @grammyjs/runner for bots with many updates; fastify.ts and the setups/ for Vercel, AWS Lambda and Deno Deploy take webhooks through webhookCallback and have no polling to stop. setups/docker-node/main.ts is the one deployed as a long-running process: bot.start() under a Dockerfile whose CMD is ["npm", "run", "start"], running tsx ./main.ts as the node user. package.json takes grammy ^1.4.3 and @grammyjs/runner ^1.0.2; there is no lockfile.

None of them handles a signal. When Docker stops the container it sends SIGTERM and waits ten seconds before SIGKILL; a polling bot that ignores the first is killed mid-request, and the update it was handling is fetched again on the next start, so a user gets the same reply twice. For bot.start() the fix is two lines before it: process.once("SIGINT", () => bot.stop()) and the same for SIGTERM. bot.stop() ends the polling loop after the current getUpdates call returns and confirms the updates it received, so the process exits on its own. For the runner, run(bot) returns a handle, and the handler is () => handle.isRunning() && handle.stop(), which stops fetching and waits for the updates already being processed.

The agent adds those handlers to each file that polls, in the numbered comment style the examples use, and leaves the webhook setups alone, since there is nothing to stop. In setups/docker-node it also changes the CMD to ["tsx", "./main.ts"]: with npm run start in front, the signal reaches npm first, and whether it is forwarded depends on the npm version in node:lts-slim on the day the image is built. Running the bot process directly removes the question. docker-compose.yml keeps command: npm run dev for local work, where tsc-watch restarts on save.

There is no token in the sandbox, so the agent does not start a bot. It type-checks each changed file with the repository's tsconfig.json (strict, noImplicitReturns), runs npm run typecheck in setups/docker-node, and writes a short script that imports main.ts with a stubbed Bot to show the handler is registered and stop is called once on SIGTERM, then deletes it. Those outputs, and the Dockerfile diff, go in the description.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add graceful shutdown to the grammY bots in this repository. Read package.json, tsconfig.json, every file at the root that calls bot.start() or run(bot), and setups/docker-node with its Dockerfile and docker-compose.yml first. For each bot that long-polls, register SIGINT and SIGTERM handlers that call bot.stop(), or the runner handle's stop() guarded by isRunning() where @grammyjs/runner is used. Leave the webhook examples and setups unchanged. In setups/docker-node, change the Dockerfile CMD to run tsx ./main.ts directly so the signal reaches the bot process, and say why in the pull request. Do not start a bot; type-check each changed file and quote the result. Open a pull request.",
  "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 that touches the polling examples, echo.ts, runner.ts, menu.ts, stats.ts, stats-lazy.ts, menu-with-conversation.ts and setups/docker-node/main.ts, with two or three lines each, and setups/docker-node/Dockerfile with a new CMD. The webhook files, fastify.ts and the Vercel, Lambda and Deno setups, are untouched, and package.json does not change.

The description shows the type-check output for every changed file, the stub run that registered the handlers and called stop on a SIGTERM, and the reason for the CMD change in one paragraph. The run's record keeps the tsc runs and the stub script, so a reviewer can see it was not a real bot.

Before merging, a reviewer decides whether the Docker setup should also set stop_grace_period in docker-compose.yml for a bot whose handlers take longer than ten seconds; the agent leaves the default and notes it.

Run it on every pull request

A new example that forgets the handlers is the way this comes back. An automation with a github trigger on pull_request.opened and pull_request.synchronize starts a run that reads the diff for a new bot.start() or run(bot) without a matching process.once, and comments on the pull request with the two lines to add and the file they belong in; with nothing missing, it says nothing.

The trigger adds the pull request to the prompt after it. A comment, not a push, keeps the author's branch theirs, and the prompt says to open no pull request from the automation.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The change is small and the reasoning is not: which call stops which kind of bot, what npm run does with a signal, and which setups poll at all. The agent reads every file that starts a bot and writes the handler each one needs, in one pass, rather than copying one pattern over seven files.

With no token in the sandbox, the proof is a type-check and a stub, and both are in the run's record for a reviewer to read. Across a team's bots the same request runs at once, one sandbox each, and each pull request names the files that polled and the ones that did not need a change.

Frequently asked questions

Does bot.stop() drop the update being handled?

No. It stops the polling loop, so no further getUpdates call is made, and the process exits when the handlers in flight return. The updates already received are confirmed, so they are not delivered again on the next start.

Why isRunning() on the runner handle?

A second signal, or a signal after the runner already stopped on its own, would call stop() on a handle that is not running. The guard makes the handler safe to call more than once.

Why change the Docker CMD instead of adding a signal handler to npm?

Because npm is not the bot. npm run start puts a second process between Docker and tsx, and whether it forwards SIGTERM depends on the npm version in the base image. Running tsx ./main.ts as the CMD makes the bot process the one Docker signals.

What about the webhook setups?

Nothing to stop. webhookCallback handles one request at a time inside Fastify, Vercel, Lambda or Deno's own server, and those runtimes manage their own shutdown.

More grammY jobs

The same job on other stacks

Keep reading