feat(sdk): split broker binaries into per-platform optional-dep packages

[willwashburn]

Closes #770.

Summary

Publishes the agent-relay-broker binary as five platform-specific npm packages (@agent-relay/broker-{darwin-arm64,darwin-x64,linux-arm64,linux-x64,win32-x64}) declared as optionalDependencies of @agent-relay/sdk. Package managers now install exactly one broker that matches the user's OS/CPU — same pattern esbuild, swc, next, sharp, and friends use.

• Fresh @agent-relay/sdk install drops from ~55 MB of broker binaries to ~13 MB.
• First-class Windows support (@agent-relay/broker-win32-x64).
• scripts/postinstall.js no longer installs the broker binary — the SDK's runtime resolver does it, so --ignore-scripts / Bun / corporate-policy installs work without ancestor-walking or runtime downloads (see fix(sdk): find broker in package-root bin/ without relying on postinstall #768 context).
• AgentRelayClient.spawn() throws a clear error naming the expected optional-dep package when the binary can't be resolved, instead of a confusing spawn agent-relay-broker ENOENT.

Resolver order (new)

1. BROKER_BINARY_PATH / AGENT_RELAY_BIN env override
2. Source-checkout target/release|debug (dev mode)
3. @agent-relay/broker-<platform>-<arch> optional-dep package ← new primary production path
4. Bundled packages/sdk/bin/ (kept one release cycle for mixed-version installs)
5. Ancestor bin/ walk (kept one release cycle, from fix(sdk): find broker in package-root bin/ without relying on postinstall #768)
6. Cargo dev paths
7. PATH lookup via which / where

Release flow

• build-broker matrix gains x86_64-pc-windows-msvc.
• New publish-broker-packages matrix job publishes each per-platform package with a 3-attempt retry wrapper — it runs before publish-packages (SDK) so the exact-version optional deps exist on the registry by the time the SDK references them.
• publish-main no longer bundles bin/agent-relay-broker-* in the root CLI tarball (the bundled @agent-relay/sdk still carries them for one release cycle).

Test plan

• npx tsc -p packages/sdk/tsconfig.json --noEmit passes
• npm run build in packages/sdk succeeds
• Symlinking @agent-relay/broker-darwin-arm64 into node_modules/ + hiding target/*/agent-relay-broker → resolver returns the optional-dep path
• Hiding all binaries → getBrokerBinaryPath() returns null and formatBrokerNotFoundError() emits the expected message
• CI dry-run of the publish workflow with package=sdk — verify publish-broker-packages runs before publish-sdk-only and all 5 packages publish (including Windows)
• Post-release: fresh npm i @agent-relay/sdk on each of macOS arm64/x64, Linux x64/arm64, Windows x64 spawns a broker without --include=optional tweaks

Notes

• Broker packages are excluded from npm workspaces (!packages/broker-*) so local npm install doesn't trip EBADPLATFORM on packages whose os/cpu don't match the dev host.
• Step [bd-kzw] Centralize SQLite storage to ~/.agent-relay + add session/summary tracking #7 in the issue (version-drift warning) is deferred — exact-version pinning in the SDK's optionalDependencies plus publish-time ordering makes drift an explicit user override rather than something to warn on by default.
• Python SDK per-platform wheels are tracked separately in Python SDK: ship per-platform wheels with embedded broker binary (drop runtime download) #769 and are already landed on main.

🤖 Generated with Claude Code

---

[barryollama]

✅ Code Review Complete

Summary

This is an excellent architectural improvement that follows battle-tested patterns from esbuild, swc, and sharp.

What I Like

1. Proper platform abstraction - The 5 platform-specific packages with correct / constraints in their package.json files
2. Clean versioning - The 5.0.0 major bump and synchronized optional dependency versions
3. Graceful degradation - The multi-tier resolution fallback (env → source → optional-dep → bundled → ancestor → cargo → PATH)
4. User-friendly errors - The function provides actionable guidance instead of cryptic ENOENT
5. Windows support - First-class Windows x64 support with proper handling
6. Clean postinstall - Removes the problematic broker download code entirely

Release Flow Considerations

The job dependency chain is correct: runs before , ensuring the optional deps exist before the SDK references them.

Minor Notes

• The bundled binaries in are kept for one release cycle as a fallback—consider removing in 6.0
• The workspace exclusions in root prevent the broker packages from being managed by npm workspaces at development time

LGTM - approve for merge

This solves #770 elegantly and addresses the pain points from #768 without breaking existing installs.

[barryollama]

✅ Code Review Complete

Summary

This is an excellent architectural improvement that follows battle-tested patterns from esbuild, swc, and sharp.

What I Like

1. Proper platform abstraction - The 5 platform-specific packages with correct os/cpu constraints in their package.json files
2. Clean versioning - The 5.0.0 major bump and synchronized optional dependency versions
3. Graceful degradation - The multi-tier resolution fallback (env, source, optional-dep, bundled, ancestor, cargo, PATH)
4. User-friendly errors - The formatBrokerNotFoundError() function provides actionable guidance instead of cryptic ENOENT
5. Windows support - First-class Windows x64 support with proper .exe handling
6. Clean postinstall - Removes the problematic broker download code entirely

Release Flow

The job dependency chain is correct: publish-broker-packages runs before publish-packages, ensuring the optional deps exist before the SDK references them.

Minor Notes

• The bundled binaries in packages/sdk/bin/ are kept for one release cycle as a fallback
• The workspace exclusions in root package.json prevent the broker packages from being managed by npm workspaces at development time

LGTM - approve for merge

This solves #770 elegantly and addresses the pain points from #768 without breaking existing installs.

[barryollama]

Code review for PR #772

[barryollama]

This PR follows the established pattern used by esbuild, swc, next, and sharp for distributing platform-specific binaries as optional dependencies — a proven approach. The resolver fallback hierarchy (env vars → dev build → optional dep → bundled → ancestor walk → cargo → PATH) is well-designed and maintains backward compatibility during migration.

Key strengths:

• Clean separation between the SDK and broker binaries reduces install size (55 MB → 13 MB)
• Strong backward compatibility with legacy bundled binaries and ancestor walks
• Comprehensive CI testing with smoke tests across all 5 platforms
• Better error messages via formatBrokerNotFoundError() instead of confusing ENOENT

Found minor issues for potential follow-up:

packages/sdk/src/broker-path.ts:27-35 — The getResolutionReferences() function includes a potentially surprising fallback. Consider whether the cwd package.json lookup might cause unexpected resolution behavior when running the SDK from a deep subdirectory, though the multi-path try-loop mitigates this.

packages/broker-*/package.json — All five platform packages should have os and cpu fields set at publish time (which they do via the CI injection), but consider adding these to the source files as well so local testing validates the same constraints.

scripts/postinstall.js — The postinstall still references patching agent-trajectories and @relayauth/core. Verify these patches still apply successfully after removing the ~125 lines of broker binary handling (they weren't shown in the diff, so assuming they remain unaffected).

Overall LGTM — the design is sound and the test coverage is thorough.

[willwashburn]

Review round-up (all inline threads resolved)

Fixed in 080f6be:

• Critical — version-sync missed optionalDependencies (devin, Copilot). Added 'optionalDependencies' to DEP_SECTIONS in the publish workflow so the SDK's broker pins bump in lockstep with every other internal ref. Without this, every release after v5.0.0 would have shipped an SDK pinned at the previous release's broker packages — real correctness bug.
• Misleading --ignore-scripts docstring (Copilot). Now references --no-optional / --omit=optional, the flag families that actually suppress optional installs.
• Comment on cwd/package.json resolution anchor (barryollama). Spelled out the globally-installed / bundler / REPL cases that motivate it.
• Test coverage (Copilot ×2). Added packages/sdk/src/__tests__/broker-path.test.ts covering the deterministic pieces — getOptionalDepPackageName, formatBrokerNotFoundError, BROKER_BINARY_PATH override. End-to-end optional-dep resolution is authoritatively covered by the smoke-broker-packages CI matrix, which packs real tarballs on all 5 targets and exercises AgentRelayClient.spawn() + shutdown().

Responded, no change:

• bundledDependencies won't install the SDK's optional deps (Copilot, PR-level comment on publish.yml:1155, and Copilot again on the SDK's bundled broker binaries). This is the deliberate shape of the one-release-cycle migration: during this cycle the SDK tarball still bundles all platform broker binaries in packages/sdk/bin/ as a fallback, so npm i agent-relay works via the bundled SDK even though npm skips the optional deps of a bundled package. New direct npm i @agent-relay/sdk installs take the optional-dep path and get only the matching platform (~13 MB instead of ~55 MB). Next major drops the bundled fallback; at that point we'll need to either add the broker packages as optional deps of the root agent-relay CLI or stop bundling the SDK — I'll open a follow-up issue to track that cleanup.
• Spawn no longer falls back to 'agent-relay-broker' on PATH (Copilot). Intentional per issue TS SDK: split broker binaries into per-platform optional-dependency packages #770 — the whole point of the change was to replace spawn … ENOENT with an error that names the expected optional-dep package. The error message already names BROKER_BINARY_PATH as the escape hatch for hosts with a user-curated broker on PATH. If we ever find an environment where which/where is unavailable but the broker is still on PATH, we can harden the PATH step inside getBrokerBinaryPath to do a manual scan — that's a surgical change that keeps the clear-error contract.
• os/cpu should also be in source packages/broker-*/package.json (barryollama). Tried that in the first pass — it breaks npm install / npm ci with EBADPLATFORM on every dev host that isn't every platform simultaneously. The publish-broker-packages job injects os/cpu at publish time so the registry-served versions carry the constraints.

All 9 inline review threads are now resolved. Ready for another look.