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

.github/workflows/package-validation.yml

@@ -102,8 +102,10 @@ jobs:
  echo "=== Validating packages ==="
  ERRORS=0
 
- # Check dist files exist (skip non-Node package directories)
- SKIP_PACKAGES="build-plans brand"
+ # Check dist files exist (skip non-Node package directories).
+ # broker-* packages ship a Rust-built binary in bin/, not a JS
+ # dist — they live under packages/ only for workspace linkage.
+ SKIP_PACKAGES="build-plans brand broker-darwin-arm64 broker-darwin-x64 broker-linux-arm64 broker-linux-x64 broker-win32-x64"
  for pkg_dir in packages/*/; do
  pkg_name=$(basename "$pkg_dir")
  if [ ! -f "$pkg_dir/package.json" ]; then

.github/workflows/verify-publish-sdk.yml

@@ -0,0 +1,187 @@
+name: Verify Published SDK (Cross-Platform)
+
+# Clean-room verification that @agent-relay/sdk — freshly installed from the
+# public registry on each target OS/arch — pulls in the correct
+# @agent-relay/broker-<platform>-<arch> optional dep and actually spawns a
+# broker end-to-end. This is the last line of defense for the optional-dep
+# pattern: pre-publish the smoke-broker-packages job exercises the logic via
+# locally-packed tarballs, but it cannot catch registry round-trip bugs
+# (wrong os/cpu manifest, selection logic, CDN propagation).
+#
+# Triggered:
+# - Automatically after the publish workflow completes (via workflow_call)
+# - Manually via workflow_dispatch (useful for re-verifying an existing
+# version, e.g. after a registry flake or to check propagation).
+#
+# Not wired to pull_request: the workflow installs from the public registry,
+# which means it can only verify versions that have already shipped. For
+# pre-publish validation of this logic, use the smoke-broker-packages job in
+# publish.yml — it runs the same assertions against locally-packed tarballs.
+
+on:
+ workflow_dispatch:
+ inputs:
+ version:
+ description: 'SDK version to verify (default: latest)'
+ required: false
+ type: string
+ default: 'latest'
+ workflow_call:
+ inputs:
+ version:
+ description: 'SDK version to verify'
+ required: false
+ type: string
+ default: 'latest'
+
+env:
+ AGENT_RELAY_TELEMETRY_DISABLED: 1
+
+jobs:
+ verify-sdk:
+ name: Verify @agent-relay/sdk (${{ matrix.platform }})
+ runs-on: ${{ matrix.os }}
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - platform: darwin-arm64
+ os: macos-14
+ expected_pkg: '@agent-relay/broker-darwin-arm64'
+ - platform: darwin-x64
+ os: macos-13
+ expected_pkg: '@agent-relay/broker-darwin-x64'
+ - platform: linux-x64
+ os: ubuntu-latest
+ expected_pkg: '@agent-relay/broker-linux-x64'
+ - platform: linux-arm64
+ os: ubuntu-24.04-arm
+ expected_pkg: '@agent-relay/broker-linux-arm64'
+ - platform: win32-x64
+ os: windows-latest
+ expected_pkg: '@agent-relay/broker-win32-x64'
+
+ steps:
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: '22.14.0'
+
+ - name: Resolve version spec
+ id: spec
+ shell: bash
+ run: |
+ VERSION="${{ inputs.version }}"
+ if [ -z "$VERSION" ]; then
+ VERSION="latest"
+ fi
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+ echo "spec=@agent-relay/sdk@$VERSION" >> "$GITHUB_OUTPUT"
+ echo "Using spec: @agent-relay/sdk@$VERSION"
+
+ # Registry/CDN propagation can lag the publish by up to a minute. Retry
+ # with exponential backoff so the first run after publish doesn't miss.
+ - name: Wait for package on registry
+ shell: bash
+ run: |
+ set -euo pipefail
+ SPEC="${{ steps.spec.outputs.spec }}"
+ VERSION="${{ steps.spec.outputs.version }}"
+ if [ "$VERSION" = "latest" ]; then
+ echo "version=latest — no wait needed"
+ exit 0
+ fi
+ for i in 1 2 3 4 5 6; do
+ if npm view "$SPEC" version >/dev/null 2>&1; then
+ echo "registry has $SPEC"
+ exit 0
+ fi
+ WAIT=$((2 ** i))
+ echo "attempt $i: registry not ready, sleeping ${WAIT}s"
+ sleep "$WAIT"
+ done
+ echo "FAIL: registry never surfaced $SPEC"
+ exit 1
+
+ - name: Install @agent-relay/sdk into scratch project
+ shell: bash
+ run: |
+ set -euo pipefail
+ SCRATCH="$RUNNER_TEMP/verify-sdk"
+ mkdir -p "$SCRATCH"
+ echo "SCRATCH=$SCRATCH" >> "$GITHUB_ENV"
+ cd "$SCRATCH"
+ npm init -y --silent >/dev/null
+ echo "Installing ${{ steps.spec.outputs.spec }}"
+ npm install --no-audit --no-fund "${{ steps.spec.outputs.spec }}"
+ echo ""
+ echo "=== installed @agent-relay/ packages ==="
+ ls node_modules/@agent-relay/
+
+ - name: Verify only the matching broker package was installed
+ shell: bash
+ run: |
+ set -euo pipefail
+ cd "$SCRATCH"
+ EXPECTED="${{ matrix.expected_pkg }}"
+ if [ ! -d "node_modules/$EXPECTED" ]; then
+ echo "FAIL: expected optional dep $EXPECTED was not installed"
+ echo "installed @agent-relay/ packages:"
+ ls node_modules/@agent-relay/ 2>&1 || true
+ exit 1
+ fi
+ echo "OK: $EXPECTED present in node_modules"
+
+ # npm should skip every sibling whose os/cpu doesn't match this
+ # runner. Catch a missing os/cpu constraint by asserting the
+ # unmatched packages were NOT installed.
+ for pkg in \
+ @agent-relay/broker-darwin-arm64 \
+ @agent-relay/broker-darwin-x64 \
+ @agent-relay/broker-linux-arm64 \
+ @agent-relay/broker-linux-x64 \
+ @agent-relay/broker-win32-x64; do
+ if [ "$pkg" != "$EXPECTED" ] && [ -d "node_modules/$pkg" ]; then
+ echo "FAIL: sibling optional dep $pkg was installed on ${{ matrix.platform }}"
+ echo "npm should skip it based on os/cpu — published manifest may be missing constraints"
+ exit 1
+ fi
+ done
+ echo "OK: only ${{ matrix.expected_pkg }} was installed; siblings correctly skipped"
+
+ - name: Resolver smoke — getBrokerBinaryPath()
+ shell: bash
+ run: |
+ cd "$SCRATCH"
+ node --input-type=module -e "
+ import { getBrokerBinaryPath, getOptionalDepPackageName } from '@agent-relay/sdk/broker-path';
+ import { accessSync, constants } from 'node:fs';
+ const expected = getOptionalDepPackageName();
+ const p = getBrokerBinaryPath();
+ console.log('expected package:', expected);
+ console.log('resolved:', p);
+ if (!p) { console.error('FAIL: resolver returned null'); process.exit(1); }
+ if (!p.includes(expected)) {
+ console.error('FAIL: resolution did not go through the optional-dep package; got', p);
+ process.exit(1);
+ }
+ accessSync(p, constants.X_OK);
+ console.log('OK: resolver returned executable binary from optional-dep package');
+ "
+
+ - name: Spawn smoke — AgentRelayClient.spawn()
+ shell: bash
+ run: |
+ cd "$SCRATCH"
+ node --input-type=module -e "
+ import { AgentRelayClient } from '@agent-relay/sdk';
+ const client = await AgentRelayClient.spawn({
+ cwd: process.cwd(),
+ channels: ['general'],
+ startupTimeoutMs: 45000,
+ onStderr: (line) => console.error('[broker]', line),
+ });
+ console.log('OK: AgentRelayClient.spawn() returned');
+ await client.shutdown();
+ console.log('OK: client.shutdown() completed');
+ "

package.json

@@ -7,7 +7,6 @@
  "types": "dist/src/index.d.ts",
  "files": [
  "dist",
- "bin",
  "install.sh",
  "scripts/postinstall.js",
  "scripts/build-cjs.mjs",

packages/broker-darwin-arm64/README.md

@@ -0,0 +1,11 @@
+# @agent-relay/broker-darwin-arm64
+
+Prebuilt `agent-relay-broker` binary for **macOS (Apple Silicon)**.
+
+This package is installed automatically as an optional dependency of
+[`@agent-relay/sdk`](https://www.npmjs.com/package/@agent-relay/sdk). You do
+not need to depend on it directly. The SDK resolves the correct platform
+binary at runtime via `require.resolve`.
+
+See the [agent-relay repository](https://github.com/AgentWorkforce/relay) for
+source and build tooling.

packages/broker-darwin-arm64/package.json

@@ -0,0 +1,17 @@
+{
+ "name": "@agent-relay/broker-darwin-arm64",
+ "version": "5.0.0",
+ "description": "agent-relay-broker binary for darwin arm64. Installed automatically as an optional dependency of @agent-relay/sdk.",
+ "files": [
+ "bin"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/AgentWorkforce/relay.git",
+ "directory": "packages/broker-darwin-arm64"
+ },
+ "license": "MIT",
+ "publishConfig": {
+ "access": "public"
+ }
+}

packages/broker-darwin-x64/README.md

@@ -0,0 +1,11 @@
+# @agent-relay/broker-darwin-x64
+
+Prebuilt `agent-relay-broker` binary for **macOS (Intel)**.
+
+This package is installed automatically as an optional dependency of
+[`@agent-relay/sdk`](https://www.npmjs.com/package/@agent-relay/sdk). You do
+not need to depend on it directly. The SDK resolves the correct platform
+binary at runtime via `require.resolve`.
+
+See the [agent-relay repository](https://github.com/AgentWorkforce/relay) for
+source and build tooling.

packages/broker-darwin-x64/package.json

@@ -0,0 +1,17 @@
+{
+ "name": "@agent-relay/broker-darwin-x64",
+ "version": "5.0.0",
+ "description": "agent-relay-broker binary for darwin x64. Installed automatically as an optional dependency of @agent-relay/sdk.",
+ "files": [
+ "bin"
+ ],
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/AgentWorkforce/relay.git",
+ "directory": "packages/broker-darwin-x64"
+ },
+ "license": "MIT",
+ "publishConfig": {
+ "access": "public"
+ }
+}

packages/broker-linux-arm64/README.md

@@ -0,0 +1,12 @@
+# @agent-relay/broker-linux-arm64
+
+Prebuilt `agent-relay-broker` binary for **Linux ARM64**. The broker is
+compiled with `musl` static linking so it works on both glibc and musl hosts.
+
+This package is installed automatically as an optional dependency of
+[`@agent-relay/sdk`](https://www.npmjs.com/package/@agent-relay/sdk). You do
+not need to depend on it directly. The SDK resolves the correct platform
+binary at runtime via `require.resolve`.
+
+See the [agent-relay repository](https://github.com/AgentWorkforce/relay) for
+source and build tooling.