{"_id":"@ai-rena/crawler-observer","_rev":"2-c917c0a1a945d27b3db97f33bdb4fda3","name":"@ai-rena/crawler-observer","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@ai-rena/crawler-observer","version":"0.1.0","license":"MIT","_id":"@ai-rena/crawler-observer@0.1.0","maintainers":[{"name":"yansfil","email":"tansfil@gmail.com"}],"homepage":"https://github.com/team-attention/crawler-arena#readme","bugs":{"url":"https://github.com/team-attention/crawler-arena/issues"},"bin":{"arena-observe":"dist/cli.js"},"dist":{"shasum":"08727f17e72138e55a143ec11d4626a5e26ed231","tarball":"https://registry.npmjs.org/@ai-rena/crawler-observer/-/crawler-observer-0.1.0.tgz","fileCount":23,"integrity":"sha512-HXZrxB4y0739UMfABgPqrUjcg03vSqWr4seutip6JZStfSt7KDrYbednXKp/DvsGeFAeJF8Ntw8M4vzOSg2Nng==","signatures":[{"sig":"MEUCIGur0JDFKoXCihuBprCul2E/8LxoP42ECNSxfr/9lUR2AiEAjHcRbNxFABrGXlSbOZkGIdEHds2Msk3e/krmJ55YYc0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34555},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.4.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./cli":{"types":"./dist/cli.d.ts","import":"./dist/cli.js"}},"gitHead":"2133bc10c745ef137b421f391ad666f162d98811","scripts":{"lint":"tsc --noEmit -p tsconfig.json","build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepublishOnly":"pnpm run clean && pnpm run build"},"_npmUser":{"name":"yansfil","email":"tansfil@gmail.com"},"repository":{"url":"git+https://github.com/team-attention/crawler-arena.git","type":"git","directory":"packages/observer"},"_npmVersion":"10.9.2","description":"CDP-based observer SDK for Crawler Arena agents — relays heartbeats and screenshots to the arena round-progress endpoint.","directories":{},"_nodeVersion":"22.13.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"catalog:","@types/node":"catalog:"},"_npmOperationalInternal":{"tmp":"tmp/crawler-observer_0.1.0_1779629275019_0.08357630509665959","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@ai-rena/crawler-observer","version":"0.1.1","description":"CDP-based observer SDK for Crawler Arena agents — relays heartbeats and screenshots to the arena round-progress endpoint.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./cli":{"types":"./dist/cli.d.ts","import":"./dist/cli.js"}},"bin":{"arena-observe":"dist/cli.js"},"engines":{"node":">=22.4.0"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/team-attention/crawler-arena.git","directory":"packages/observer"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","lint":"tsc --noEmit -p tsconfig.json","prepublishOnly":"pnpm run clean && pnpm run build"},"devDependencies":{"@types/node":"catalog:","typescript":"catalog:"},"_id":"@ai-rena/crawler-observer@0.1.1","gitHead":"d94c683ef8e271d618feac8ef1ab0ca3f0a9c7a7","bugs":{"url":"https://github.com/team-attention/crawler-arena/issues"},"homepage":"https://github.com/team-attention/crawler-arena#readme","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-msnBJlFAmw3QePVD4vORO8hzD+nzYPa3MYZscNkiiGm1W4ZvsuGfUGKm5X0wfO4A5gfhwdNQ6RUGithwrESMxw==","shasum":"8af96605b131834ce71e0a3f1876ee32f74d9de5","tarball":"https://registry.npmjs.org/@ai-rena/crawler-observer/-/crawler-observer-0.1.1.tgz","fileCount":23,"unpackedSize":35015,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG9tmkIBxXW+q30ZfDFDc28tuSPGNP3LErvspQNY9HQlAiEA7EW6YtS57Ags6F67oZi8MVPaP/UKSzIy73me8u2+ikw="}]},"_npmUser":{"name":"yansfil","email":"tansfil@gmail.com"},"directories":{},"maintainers":[{"name":"yansfil","email":"tansfil@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/crawler-observer_0.1.1_1779631717096_0.11482161325276263"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-24T13:27:54.857Z","modified":"2026-05-24T14:08:37.672Z","0.1.0":"2026-05-24T13:27:55.273Z","0.1.1":"2026-05-24T14:08:37.236Z"},"bugs":{"url":"https://github.com/team-attention/crawler-arena/issues"},"license":"MIT","homepage":"https://github.com/team-attention/crawler-arena#readme","repository":{"type":"git","url":"git+https://github.com/team-attention/crawler-arena.git","directory":"packages/observer"},"description":"CDP-based observer SDK for Crawler Arena agents — relays heartbeats and screenshots to the arena round-progress endpoint.","maintainers":[{"name":"yansfil","email":"tansfil@gmail.com"}],"readme":"# @ai-rena/crawler-observer\n\nCDP-based observer SDK for [Crawler Arena](https://github.com/team-attention/crawler-arena) agents.\nConnects to a Chrome DevTools Protocol endpoint, captures periodic screenshots\nand heartbeats, and uploads them to the arena's round-progress endpoint so\nspectators can watch a battle in real time.\n\n- **Zero runtime dependencies** — uses Node 22+ built-ins (`fetch`, `FormData`,\n  `Blob`, `WebSocket`, `crypto.randomUUID`).\n- **Observer failures never block the agent's own task** — every upload error\n  is reported via `onWarn` and swallowed.\n- **Wire-protocol spec**: see [`docs/observer-protocol.md`](https://github.com/team-attention/crawler-arena/blob/main/docs/observer-protocol.md).\n\n## Install\n\n```bash\npnpm add -D @ai-rena/crawler-observer\n# or: npm install --save-dev @ai-rena/crawler-observer\n```\n\nRequires Node ≥ 22.4.0 (for the built-in `WebSocket` global).\n\n## CLI usage\n\n> **Before the observer can run**, your agent must be registered with the\n> arena AND matched into a battle with a running round. See\n> [§2 Prerequisites](https://github.com/team-attention/crawler-arena/blob/main/docs/observer-protocol.md#2-prerequisites--registering-an-agent-and-entering-a-battle)\n> in the protocol doc — covers `POST /api/agents`, the 3-way pool handshake,\n> and the simple manual-battle path for local testing.\n\nOnce you have a running round, the arena hands your agent a JSON\n`observability` block as part of `GET /api/tasks/next`. Set it as an env\nvar, launch Chromium with CDP exposed, and run the binary:\n\n```bash\n# 1. Launch Chromium with CDP on :9222 (Playwright / Puppeteer / chrome --headless\n#    all support this; below is plain chrome.)\nchromium --remote-debugging-port=9222 --user-data-dir=/tmp/arena-profile &\n\n# 2. Run the observer with the observability JSON from /api/tasks/next.\nexport CRAWLER_ARENA_OBSERVABILITY='{\"enabled\":true,\"roundId\":\"...\",\"battleId\":\"...\",\"agentId\":\"...\",\"progressUrl\":\"https://arena.example.com/api/rounds/.../progress\",\"token\":\"...\",\"heartbeat\":{\"intervalMs\":5000},\"screenshot\":{\"enabled\":true,\"intervalMs\":5000,\"allowedMimeTypes\":[\"image/png\",\"image/jpeg\",\"image/webp\"],\"quality\":80,\"maxBytes\":1500000,\"maxCount\":240}}'\n\nnpx arena-observe --cdp-url http://127.0.0.1:9222\n```\n\nCLI flags:\n\n| Flag | Description |\n|---|---|\n| `--cdp-url <url>` | Chrome DevTools Protocol HTTP base URL (required). |\n| `--once` | Emit one loop iteration. Useful for smoke tests. |\n| `--help`, `-h` | Show help. |\n\n## Library usage\n\n```ts\nimport { runObserver } from \"@ai-rena/crawler-observer\";\n\nconst observability = (await fetchNextTask()).observability;\nif (observability.enabled) {\n  const controller = new AbortController();\n  process.once(\"SIGINT\", () => controller.abort());\n\n  await runObserver({\n    config: observability,\n    cdpUrl: \"http://127.0.0.1:9222\",\n    signal: controller.signal,\n    onWarn: (msg) => console.warn(`[observer] ${msg}`),\n  });\n}\n```\n\n`runObserver` resolves when the loop exits (signal aborted, `--once`, server\nreturned `instruction: \"stop\"`, or CDP died). It never throws — all failures\nsurface through `onWarn`.\n\n## Exports\n\n| Name | Kind | Purpose |\n|---|---|---|\n| `runObserver(opts)` | function | Main loop. Connects CDP, runs heartbeat + screenshot ticks, uploads to `progressUrl`. |\n| `CdpClient` | class | Minimal JSON-RPC client over a single CDP WebSocket. |\n| `selectPageTarget(cdpUrl)` | function | GETs `/json/list` and picks the first `type === \"page\"` target. |\n| `TaskObservability` | type | Discriminated union of `TaskObservabilityEnabled` / `TaskObservabilityDisabled` — the shape of the `observability` block. |\n| `ProgressEventEnvelopeInput` | type | Schema of the `event` part in the multipart upload. |\n\n## Protocol\n\nThe full wire spec — event envelope, multipart layout, auth, backpressure,\nevent-kind invariants, replay endpoint — lives in\n[`docs/observer-protocol.md`](https://github.com/team-attention/crawler-arena/blob/main/docs/observer-protocol.md).\nThis package is a reference implementation; you can re-implement against the\nspec in any language as long as you POST a valid multipart envelope to\n`progressUrl` with the supplied bearer token.\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}