feat(sdk): Communicate Mode SDK (on_relay) for Python and TypeScript

[khaliqgant]

Summary

• Add Communicate Mode SDK (on_relay) enabling agents to receive tasks via relay messaging
• TypeScript and Python adapter implementations with per-adapter subpath exports
• Spec-compliant ping/pong, auto-detect module matching, and withRelay alias
• Connection retry and error handling
• Multiple rounds of review fixes (spec compliance, adapter improvements, Devin review findings)

Commits

• Initial on_relay SDK for Python and TypeScript
• Spec compliance fixes (ping/pong, module matching)
• Per-adapter subpath exports and withRelay alias
• Connection retry and error handling
• Multiple review rounds addressing feedback

Test plan

• Verify TypeScript adapter connects and receives relay messages
• Verify Python adapter connects and receives relay messages
• Test ping/pong keepalive mechanism
• Test auto-detect module matching
• Test connection retry on disconnect
• Verify subpath exports work (@agent-relay/sdk/communicate)

🤖 Generated with Claude Code

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 8 additional findings in Devin Review.

[devin-ai-integration]

🔴 WebSocket disconnect can hang indefinitely after timeout removal

The disconnect() method previously used Promise.race with a 2-second timeout to prevent hanging if the WebSocket server is unresponsive during the close handshake. The new code awaits the close event with no timeout at all. If the remote server is unresponsive, the ws library's close() sends a close frame and then waits for the TCP connection to fully terminate, which can take minutes (TCP keepalive/timeout). This causes disconnect() — and anything awaiting it like Relay.close() — to hang indefinitely.

Old code with timeout vs new code without

Old code:

await Promise.race([
  new Promise<void>((resolve) => {
    socket.once('close', () => resolve());
    socket.close();
  }),
  new Promise<void>((resolve) => setTimeout(resolve, 2_000)),
]);

New code:

await new Promise<void>((resolve) => {
  socket.once('close', () => resolve());
  socket.close();
});

Callers like Relay.close() (packages/sdk/src/communicate/core.ts:118) directly await this.transport.disconnect(), so the hang propagates to user code in finally blocks and cleanup paths.

Suggested change

	await new Promise<void>((resolve) => {
	socket.once('close', () => resolve());
	socket.close();
	});
	await Promise.race([
	new Promise<void>((resolve) => {
	socket.once('close', () => resolve());
	socket.close();
	}),
	new Promise<void>((resolve) => setTimeout(resolve, 2_000)),
	]);

---

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