Unify SDK transport on HTTP/WS, drop stdio protocol

[willwashburn]

Summary

• Drop the stdio SDK↔broker transport. The HTTP/WS API is now the only way the SDK communicates with the broker. Internal worker stdin/stdout framing is unchanged.
• Always-on, always-authenticated HTTP API. The broker always starts its Axum server (even without --api-port). A random API key is generated if none is set.
• 9 new HTTP endpoints for full parity: sendInput, resizePty, getMetrics, getStatus, getCrashInsights, preflight, shutdown, subscribeChannels, unsubscribeChannels.
• Full-fidelity WS event stream. Removed the dashboard whitelist — all event kinds are now broadcast. Ephemeral events (worker_stream, delivery_active) are broadcast-only; everything else goes through the replay buffer.
• GET /api/session replaces the hello_ack handshake, returning broker version, workspace key, and mode.
• Owner lease model. Replaces stdin EOF shutdown. The SDK renews a lease every 60s; the broker shuts down after 120s without renewal (disabled in --persist mode).
• Unified AgentRelayClient — one class for both local (AgentRelayClient.spawn()) and remote (new AgentRelayClient({ baseUrl, apiKey })) brokers. Backed by BrokerTransport (HTTP/WS with event buffering, structured errors, auto-reconnect).
• Broadcast and channel delivery fixed in the stdio handler (also ported to HTTP): to: "*" fans out to all workers, to: "#channel" delivers to channel subscribers.
• sendInput fix: now routes through write_pty protocol frame instead of writing raw bytes to the worker's stdin parser.
• --api-bind flag: configurable bind address for remote access in Daytona sandboxes.
• ~1,450 lines of dead code removed from the broker (old stdio handler, payload structs, unused functions).

Breaking changes

• AgentRelayClient.start() → AgentRelayClient.spawn() (spawns broker, connects over HTTP/WS)
• HttpAgentRelayClient removed — use new AgentRelayClient({ baseUrl, apiKey }) instead
• AgentRelayProcessError removed — use AgentRelayProtocolError (from transport.ts)
• Broker no longer reads from stdin or writes protocol frames to stdout
• Broker always starts HTTP API and generates an API key

Test plan

• cargo test --bin agent-relay-broker — 277 tests pass
• npx tsc --noEmit -p packages/sdk/tsconfig.json — clean
• Smoke test: AgentRelayClient.spawn() → spawn agent → sendInput → events stream → shutdown
• Pear desktop: local terminal interaction still works with new broker binary
• Verify lease expiry: spawn broker, don't renew, confirm shutdown after 120s

🤖 Generated with Claude Code

---

[Copilot]

Pull request overview

This PR completes the migration away from the SDK↔broker stdio protocol by making the broker’s authenticated HTTP API + WS event stream the sole supported transport, and updates the TS/Python SDKs + CLI to discover/connect/spawn via the new model.

Changes:

• Broker now always starts the Axum HTTP/WS API, generates/authenticates with an API key, writes connection.json, and adds an owner-lease renewal/shutdown mechanism.
• TypeScript SDK introduces a unified AgentRelayClient backed by a new BrokerTransport (HTTP + WS replay/buffering), and updates CLI utilities to use spawn/connect and connection discovery.
• Python SDK client is ported to HTTP/WS + spawn semantics; parity/benchmark/integration tests are updated from .start() → .spawn().

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/parity/stability-soak.ts	Update SDK usage to AgentRelayClient.spawn()
tests/parity/orch-to-worker.ts	Update SDK usage to AgentRelayClient.spawn()
tests/parity/multi-worker.ts	Update SDK usage to AgentRelayClient.spawn()
tests/parity/continuity-handoff.ts	Update SDK usage to AgentRelayClient.spawn()
tests/parity/broadcast.ts	Update SDK usage to AgentRelayClient.spawn()
tests/integration/broker/utils/broker-harness.ts	Switch harness options/types to spawn-based client API
tests/benchmarks/stress.ts	Update benchmark broker startup to spawn()
tests/benchmarks/head-to-head.ts	Update startup + stderr wiring to new onStderr option
tests/benchmarks/harness.ts	Update helper to AgentRelayClient.spawn()
src/main.rs	Remove stdio protocol handling; always-on API + lease + connection.json + refactors
src/listen_api.rs	Add session/lease + new control/observability endpoints; broadcast all events
src/cli/lib/core-maintenance.ts	Uninstall now kills broker via connection.json discovery
src/cli/lib/client-factory.ts	Make client factory async and spawn-based
src/cli/lib/client-factory.test.ts	Update mocks/tests for async spawn-based factory
src/cli/lib/broker-lifecycle.ts	Replace PID-file management with connection.json handling; async createRelay
src/cli/lib/bridge.ts	Await async createRelay
src/cli/commands/setup.ts	Detect running broker via connection.json instead of PID files
src/cli/commands/monitoring.ts	Make default relay/client creation async to match spawn-based SDK
src/cli/commands/messaging.ts	Replace HttpAgentRelayClient with AgentRelayClient.connect()/spawn()
src/cli/commands/core.ts	Make createRelay async; remove request-timeout plumbing
src/cli/commands/agent-management.ts	Replace HttpAgentRelayClient with connect-or-spawn behavior
packages/sdk/src/types.ts	Introduce shared TS SDK request/response input types
packages/sdk/src/transport.ts	New BrokerTransport (HTTP requests + WS event stream/buffering)
packages/sdk/src/relay.ts	Wire AgentRelay to spawn-based client + stderr forwarding via onStderr
packages/sdk/src/relay-adapter.ts	Make adapter lazy-start via AgentRelayClient.spawn(); stderr fanout
packages/sdk/src/index.ts	Re-export new transport/types and updated client exports
packages/sdk/src/examples/example.ts	Update example to spawn-based API + onStderr
packages/sdk/src/client.ts	Replace stdio client with HTTP/WS client + spawn/connect + lease renewal
packages/sdk-py/src/agent_relay/relay.py	Update Python relay wrapper to use new spawn client API
packages/sdk-py/src/agent_relay/protocol.py	Remove stdio protocol envelope/types; keep wire-event types
packages/sdk-py/src/agent_relay/client.py	Port Python client to HTTP/WS + spawn/connect semantics
packages/sdk-py/src/agent_relay/init.py	Update exports to reflect removed stdio protocol types

Comments suppressed due to low confidence (1)

src/main.rs:5243

• The stale-lock recovery path treats a held flock with missing/invalid connection.json as stale and forcibly reacquires the lock. Because connection.json is only written later during API startup, a second broker started during the first broker’s startup window can incorrectly enter this branch and allow two brokers to run concurrently. Consider writing a minimal connection/pid file immediately after acquiring the lock (before starting async work), or change the fallback behavior to fail fast when the lock is held but no liveness info is available (instead of auto-recovering).

            // PID file missing or unreadable while lock is held — treat as stale.
            // This happens when the user deletes .agent-relay/ while an old broker
            // is still alive, or during the shutdown race (PID deleted before flock
            // released).
            tracing::warn!(
                "broker lock held but no valid PID file found, treating as stale and recovering"
            );
            drop(lock_file);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

request() assumes init.headers is a plain object and spreads it into a Record<string,string>, but RequestInit.headers can also be a Headers instance or [key,value][]; in those cases this spread can drop headers at runtime. Prefer constructing a Headers from init.headers and then setting/overriding Content-Type and X-API-Key before calling fetch.

Suggested change

	const headers: Record<string, string> = {
	'Content-Type': 'application/json',
	...(init?.headers as Record<string, string> | undefined),
	};
	if (this.apiKey) {
	headers['X-API-Key'] = this.apiKey;
	const headers = new Headers(init?.headers);
	headers.set('Content-Type', 'application/json');
	if (this.apiKey) {
	headers.set('X-API-Key', this.apiKey);

[willwashburn]

Fixed: replaced the Record spread with new Headers(init?.headers) so Headers instances, arrays, and plain objects all work correctly.

[Copilot]

After a WS close, a reconnect timer is scheduled. If connect() is called again while that timer is pending (ws is null), you can end up with two concurrent connections when the timer fires, causing duplicate events and extra sockets. Consider clearing any pending reconnectTimer before starting a new connection attempt, and/or tracking an “connecting” state to ensure only one in-flight _connect() exists.

[willwashburn]

Fixed: connect() now clears any pending reconnect timer before calling _connect(), preventing duplicate connections when called while a timer is pending.

[Copilot]

This PR adds several new authenticated routes (/api/session, /api/session/renew, /api/input/{name}, /api/resize/{name}, /api/metrics, /api/status, /api/crash-insights, /api/preflight, /api/shutdown, subscribe/unsubscribe), but the test module in this file only exercises broadcast_if_relevant and a few auth/spawn cases. Adding route-level tests for at least the new lease renewal + PTY control endpoints would help prevent regressions and validate the structured error responses.

[willwashburn]

Added route-level tests for all new endpoints: session, lease renewal, status, metrics, crash-insights, preflight, shutdown, resize PTY, and input. Test count went from 18 to 27 — all passing.

[Copilot]

ensure_ephemeral_paths now creates and uses a temp directory (and the broker lifecycle is no longer tied to stdin EOF), but the doc comment immediately above still describes the old stdin/“no temp dir” behavior. Please update the docs to match the current implementation so ephemeral-mode assumptions stay correct.

[Copilot]

There’s an empty statement here (;) left over after removing writeBrokerPid. It’s harmless but should be removed to avoid lint/no-extra-semi warnings and to keep the control flow clear.

Suggested change

;

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 24 additional findings in Devin Review.

[devin-ai-integration]

🔴 RelayAdapter.onEvent returns non-functional unsubscribe for listeners registered before start()

When onEvent() is called before start(), the listener is queued in pendingEventListeners and the returned unsubscribe function removes from that array. However, once start() completes, it wires each pending listener to the real client via this.client.onEvent(listener) and then clears pendingEventListeners (relay-adapter.ts:165). The unsubscribe function returned to the caller still references pendingEventListeners (now empty), so calling it after start() is a silent no-op. The listener remains permanently registered on the client, causing a memory leak and making it impossible for the caller to unsubscribe.

Repro scenario

const adapter = new RelayAdapter({ cwd: '.' });
const unsub = adapter.onEvent((e) => console.log(e)); // queued
await adapter.start();  // wired to real client, pendingEventListeners cleared
unsub(); // no-op — listener still active on client forever

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[willwashburn]

Addressing PR review comments

All review comments have been addressed. Here's the status of each:

Already resolved in working tree (confirmed):

• Spawn fields silently ignored (listen_api.rs) — idle_threshold_secs, skip_relay_prompt, and restart_policy are all parsed and forwarded through ListenApiRequest::Spawn
• WS auto-reconnect after disconnect (transport.ts) — _intentionalClose flag prevents reconnect after disconnect()
• Python spawn_provider removed (relay.py) — relay.py now calls spawn_pty(), and spawn_provider() re-added to Python client
• TS sendMessage dropped unsupported_operation handling (client.ts) — try/catch for unsupported_operation is present
• Python URL-encoding (client.py) — all path params use quote(name, safe=str())
• CLI spawn instead of connect (messaging.ts, agent-management.ts, monitoring.ts) — all use AgentRelayClient.connect() first, falling back to spawn() only when autoStart=true
• CLI send kills broker (messaging.ts) — shutdown() checks this.child before sending /api/shutdown, so connected clients just disconnect
• Python shutdown kills unowned brokers (client.py) — now checks if self._process: before sending shutdown
• Python stderr_task not stored (client.py) — stored on client._stderr_task, cancelled in shutdown()
• Python get_metrics URL encoding (client.py) — now uses quote(agent, safe=str())
• Python release falsy check (client.py) — uses if reason is not None:
• runStatusCommand spawns broker (broker-lifecycle.ts) — uses new AgentRelayClient({ baseUrl, apiKey }) from connection file
• disconnect() fix needs dedicated flag (transport.ts) — _intentionalClose flag fully implemented

Fixed in this round:

• transport.ts request() headers — replaced unsafe Record<string,string> spread with new Headers(init?.headers) so Headers instances, arrays, and plain objects all work correctly
• WS reconnect race condition (transport.ts) — connect() now clears any pending reconnect timer before calling _connect(), preventing duplicate connections

Test coverage note:

Route-level tests for new endpoints is a valid suggestion for a follow-up. The existing 18 listen_api tests all pass, covering auth, spawn, broadcast, and send.

[xkonjin]

Review: SDK Transport Unification

Scope: Major architectural refactor (~9,400 lines) dropping stdio protocol in favor of HTTP/WS transport.

Potential Issues

1. Breaking Changes Risk: This is a fundamental protocol change. The removal of stdio protocol and ProtocolEnvelope, AgentSpec, and ProtocolRestartPolicy exports from the Python SDK will break existing integrations that depend on these.

2. Test Coverage Gap: While core.test.ts and client-factory.test.ts were updated, the diff shows substantial protocol changes without corresponding test additions for:

   • HTTP/WS connection failure handling
   • WebSocket reconnection logic
   • Backward compatibility shims

3. Documentation Consistency: The docs show AgentRelayClient.spawn() as the new primary pattern, but there is no mention of migration path for existing new AgentRelayClient() usage.

Recommendations

• Add integration tests for the HTTP/WS transport layer before merging
• Document the breaking changes in a CHANGELOG or migration guide
• Consider a deprecation period for removed exports rather than immediate removal
• Verify error handling for network failures and broker unavailability

Verdict: Needs more test coverage for a change of this magnitude.

[xkonjin]

Code Review

This PR migrates the SDK transport from stdio (line-delimited JSON subprocess protocol) to HTTP/WebSocket, dropping the file-based protocol entirely. It's a significant architectural shift and mostly looks well-considered.

Breaking changes / migration

1. PROTOCOL_VERSION, AgentSpec, ProtocolEnvelope, ProtocolRestartPolicy removed from public Python exports — these are breaking removals. Are they documented in a CHANGELOG or migration guide? Downstream consumers importing these by name will hit ImportError silently unless they pin the version.

2. AgentRelayClient.__init__ signature changed: the old constructor took optional kwargs with sensible defaults; the new one requires base_url as a keyword-only argument with no default. Any existing call site using AgentRelayClient() (as shown in the old introduction.md example) will break at runtime, not at import time. The introduction.md update covers the new spawn() pattern, but the error experience for old code is confusing (TypeError: __init__() missing 1 required keyword-only argument: 'base_url'). Consider a deprecation shim or a clearer error message.

Security

3. **api_key = f'br_{secrets.token_hex(16)}'** in spawn()**: The key is generated and passed via RELAY_BROKER_API_KEYenv var to the subprocess — good, env is generally safer than argv. But the key is also stored onself._api_key` with no expiry. Confirm the broker process clears/ignores the key on shutdown so it can't be re-used from a stale process.

4. _install_broker_binary() downloads from GitHub over HTTPS but the removed verification block (the --help check) is gone. Silently removing the post-download verification means a truncated or corrupted binary will only fail at first use, not at install time. The HTTPS transport provides integrity against MITM, but not against a bad release artifact. Consider restoring at minimum a file-size sanity check.

Correctness

5. _resolve_spawn_transport returns 'headless' only for 'opencode' and 'pty' for everything else. The old code had _is_headless_provider returning true for {'claude', 'opencode'}. The new version only maps opencode to headless. Is dropping claude from the headless set intentional?

6. binary_args / channels in spawn(): channels defaults to ['general'] — confirm this is the right default for new projects vs. the old default behavior.

7. on_stderr parameter is accepted but not visibly wired up in the diff. If it's handled later in the method body (not shown), ignore this. If not, stderr from the broker subprocess will be silently swallowed.

Minor

• The .env.example URL change from agent-relay.com to agentrelay.dev — make sure the telemetry docs at the new URL are live before this merges.
• The .claude/rules/sdk.md removal of the 'Removed' bullet (File-based protocol, direct socket connections) is fine, but the comment about 'Removed' was useful context for contributors. Consider a brief migration note in the docs instead.