What the agent does
The agent reads the background script and the manifest first. In an extension shaped like chibat/chrome-extension-typescript-starter, public/manifest.json is Manifest V3 with background.service_worker pointing at js/background.js, permissions of only storage, and host_permissions of <all_urls>. src/background.ts is a polling() function that calls setTimeout(polling, 1000 * 30) to reschedule itself forever. Under Manifest V3 that loop is a bug rather than a design: Chrome stops an idle service worker and starts it again on the next event, so a pending setTimeout dies with the worker and the polling simply stops after the first idle period. webpack/webpack.common.js builds background as its own entry with no vendor chunk, jest.config.js runs ts-jest over src with tsconfig.test.json, and src/__tests__/sum.ts is the only test.
It replaces the timer with the API built for this. src/background.ts becomes two handlers: chrome.runtime.onInstalled creates a named alarm with chrome.alarms.create and a periodInMinutes no shorter than the minimum the API allows, and chrome.alarms.onAlarm runs the poll when an alarm with that name fires. Creating the alarm in onInstalled is idempotent, since creating an alarm with an existing name replaces it, so an update of the extension does not stack alarms. The work the poll does moves into an exported poll() function so it can be tested on its own, and "alarms" joins "storage" in permissions in public/manifest.json; without it, chrome.alarms is undefined at runtime and the worker throws on start.
Tests follow the existing Jest setup. A new src/__tests__/background.ts installs a global.chrome object with jest.fn() implementations of runtime.onInstalled.addListener, alarms.create and alarms.onAlarm.addListener, imports the module, and asserts that the install listener creates the alarm with the expected name and period, that the alarm listener ignores an alarm with another name, and that poll() runs when the right one fires. @types/chrome already in devDependencies types the alarms namespace, so tsconfig.json needs no change, and the ts-jest transform in jest.config.js picks the new file up because it sits under src.
Before it pushes, the agent runs what .github/workflows/build.yml runs on Node 20 and 22: npm ci, npm run build with webpack/webpack.prod.js, and npm test. It then loads the built dist/ directory as an unpacked extension in its own Chromium with --load-extension, opens the service worker's console from the extensions page, and confirms the alarm is listed by chrome.alarms.getAll() and that the poll runs after the worker has been stopped and started again, which is exactly the case setTimeout failed. The popup.tsx, options.tsx and content_script.tsx entries are untouched.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Replace the setTimeout polling in this Chrome extension's background service worker with the chrome.alarms API and open a pull request. Read public/manifest.json, src/background.ts, webpack/webpack.common.js, jest.config.js, tsconfig.json, tsconfig.test.json, src/__tests__/sum.ts and .github/workflows/build.yml first. In src/background.ts, export a poll() function with the work the poll does, create a named alarm in a chrome.runtime.onInstalled listener with chrome.alarms.create and a periodInMinutes no shorter than the API minimum, and run poll() from a chrome.alarms.onAlarm listener only for that alarm name. Remove the setTimeout loop. Add alarms to permissions in public/manifest.json. Add src/__tests__/background.ts that mocks global.chrome with jest.fn() for runtime.onInstalled.addListener, alarms.create and alarms.onAlarm.addListener, and asserts the alarm is created on install with the expected name and period, that another alarm name is ignored, and that poll() runs for the right one. Run npm ci, npm run build and npm test, load dist/ as an unpacked extension in a browser, confirm chrome.alarms.getAll() lists the alarm and the poll runs after the worker restarts, and paste the output in the pull request. Do not change the popup, options page or content script.",
"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 rewrites src/background.ts around onInstalled, alarms.create and onAlarm with an exported poll(), adds "alarms" to permissions in public/manifest.json, and adds src/__tests__/background.ts. The description pastes the npm run build and npm test output from the sandbox and a screenshot of the service worker console listing the alarm, with a note of the poll running after the worker was stopped from the extensions page.
The build workflow runs npm ci, npm run build --if-present and npm test on Node 20 and 22 for the pull request, so the new test file has passed on both before a reviewer opens it. The agent pushes one commit for the worker and manifest and one for the test.
A reviewer checks that the period is at or above the API minimum, since Chrome silently raises a shorter one in a packed extension, that the alarm is created only in onInstalled and not at the top level of the module where it would run on every worker start, that the onAlarm listener checks the alarm name, and that no setTimeout or setInterval remains in the worker. Then they merge and, if the poll needs state between runs, store it with chrome.storage rather than in a module variable, which the worker restart also clears.
Run it on every Manifest V3 migration finding
A team with several extensions from the same starter starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources. Each run reads that extension's own background.ts, so one that also keeps state in module variables or opens a long-lived port gets those called out in the description, and each ends in its own pull request. A request_id in the body makes a retried call return the run it already started.
The key's webhook_url receives run.completed for each run it starts, with session_url for the result, so a script can post the pull request links to the team channel as they land.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The failure is timing-dependent and invisible in a quick manual test: the worker polls once or twice, then goes quiet after Chrome stops it, and nothing logs an error. In a Rush sandbox the agent loads the built extension in its own Chromium, stops the worker from the extensions page and watches the alarm bring it back, and keeps that evidence beside the Jest output in the transcript.
The result passes the repository's own workflow on both Node versions before a reviewer opens it, the behaviour has a test that mocks the chrome namespace the way the project's ts-jest setup allows, and the same request works for any extension whose worker still reschedules itself with a timer.
Frequently asked questions
Why does setTimeout stop working in a service worker?
Manifest V3 background scripts are service workers, and Chrome ends an idle worker and restarts it on the next event. Timers live in the worker's memory, so a pending setTimeout is lost when the worker stops. chrome.alarms is kept by the browser and wakes the worker when the alarm fires, which is what the polling loop needs.
What is the shortest period I can use?
The alarms API has a minimum period for packed extensions and raises anything shorter to it, and the minimum has changed between Chrome versions. The agent sets the period to the current documented minimum and names the Chrome version it checked in the pull request, so you can lower it later if your users' browsers allow.
Does it keep working after the extension updates?
Yes. onInstalled fires on install and on update, and chrome.alarms.create with an existing name replaces that alarm rather than adding a second one, so there is always exactly one. Creating the alarm at module top level would also work but would run on every worker restart, which is why the agent puts it in the listener.
Can the tests run without a browser?
Yes. The handlers are plain functions registered on a chrome object, so the test installs a global.chrome with jest.fn() methods, imports the module and calls the captured listeners directly. The browser check in the sandbox is for the behaviour Jest cannot see, the worker being stopped and woken.