agent-collab AGENTS.md

agent-collab — Agent Guide

Claude Code marketplace with two plugins that delegate work to other AI coding agents: plugins/codex (community fork of openai/codex-plugin-cc) and plugins/cursor (drives Cursor's cursor-agent CLI). Plain Node .mjs with JSDoc types — no build step for runtime code, no dependencies beyond dev tools.

Commands

npm run verify                          # THE pre-merge gate: versions + build + native suite + Linux suite in docker
npm test                                # full suite (~2 min; caps file concurrency at 8)
node --test tests/<file>.test.mjs       # one file
node --test --test-name-pattern="..." tests/<file>.test.mjs   # one test
npm run build                           # regenerates app-server types + tsc checkJs

• Verify test results by exit code, never by grepping output.
• tests/runtime-*.test.mjs and the cancel e2e tests spawn real detached processes; prefer targeted patterns while iterating, but run the full suite (or rely on CI) before claiming a semantics change is safe — "targeted" has missed pinned contracts before.
• npm test runs scripts/run-tests.mjs, which caps file concurrency at min(cores, 8). The process-spawning e2e tests starve their detached workers under unbounded parallelism on high-core machines (a 32-core box would run 32 files at once), so a ceiling is required — but a hardcoded --test-concurrency=8 is an absolute value, not a max, and would raise concurrency on a 2-core CI runner, oversubscribing it and blowing the state lock's warn-and-proceed timeout (lost updates in the concurrency test). The runner's min(cores, 8) caps high-core boxes without ever inflating low-core ones. Run a single file directly with node --test tests/<f>.
• Linux behavior is reproduced exactly by docker run node:22 with the repo copied in; ubuntu CI will agree with it.
• npm run verify is the local merge gate; Required CI is the complementary remote gate and must be required in branch protection. The local gate runs version metadata, build, the native suite, and the full suite on Linux in docker (the Linux leg runs the ~40 win32-guarded tests the Windows run skips, so the two legs together cover more than either alone). A leg that cannot run is reported UNVERIFIED, the gate prints INCOMPLETE, and the process exits 2 — never silently "passed" to a human or automation. Run npm run verify:no-linux only when deliberately skipping docker.
• Do not stream the docker leg's TAP output back over inherited stdio. Doing so reproducibly failed 7 timing-sensitive shared-broker e2e tests that pass every time otherwise — the pipe backpressure was being measured, not the code. scripts/verify.mjs keeps that output inside the container and echoes only a summary.