1@README.md
2
3## Notes for agents
4
5**Keep it stateless toward the Worker.** One HTTP request per message (plus the dev tool-list poll) is what lets the Worker restart under a running session. A held connection or cached MCP session would bring back the restart-both problem this replaced (2026-09-24). The OAuth tokens are the one thing it holds, and only in memory.
6
7**No tokens on disk, ever.** Not the access token, not the refresh token, not a cache of either. A new session signing in once is the cost, and it is the intended one.
8
9**One dependency, outside the workspace.** The MCP SDK, pinned in `package.json`, for `auth()`. It is not a pnpm workspace package, so the SDK stays out of the site's pnpm closure and hash; nix fetches `package-lock.json` by each entry's integrity (`importNpmLock` in `nix/strudel.nix`), so there is no hash to update. After changing `package.json`, run `npm install` here and commit the lockfile. For running it from the tree, `npm install` here first.
10
11**Never poll prod.** Every request there counts against the user's MCP rate (120 a minute); prod's tools change only with a deploy.
12
13**Opening the browser: `rundll32.exe url.dll,FileProtocolHandler`, not `explorer.exe` or `cmd.exe /c start`.** Measured 2026-09-26: explorer.exe exited 1 and opened nothing; cmd splits the URL at `&`. `windows-exec` cannot show a window (session 0). The Windows browser's request to `http://127.0.0.1:<port>` reaches a listener on 127.0.0.1 in the guest.
14
15**Test-only environment:** `JEVSTRUDEL_PROD_MCP_URL` points prod at a local production Worker, `JEVSTRUDEL_MCP_OPEN_BROWSER=0` opens nothing (the test's headless browser reads the URL from stderr instead). `.mcp.json` sets neither.