feat(sdk-py): add direct spawn/message API

[khaliqgant]

Summary

Adds AgentRelay facade, AgentRelayClient, Agent handles, and Models constants to the Python SDK so it can spawn agents and exchange messages directly via the broker binary — matching the TypeScript SDK's API.

New files:

• protocol.py, client.py, relay.py, models.py in packages/sdk-py/src/agent_relay/

Features:

• Backward compatible: workflow builder (workflow(), fan_out(), pipeline(), dag()) still works unchanged
• Auto-downloads broker binary on first use
• Event hooks for messages, agent lifecycle events

Target usage

from agent_relay import AgentRelay, Models

async def main():
    relay = AgentRelay(channels=["GTM"])
    relay.on_message_received = lambda msg: print(f"[{msg.from_name}]: {msg.text}")

    await relay.claude.spawn(name="Analyst", model=Models.Claude.OPUS, channels=["GTM"], task="Analyze")
    await relay.codex.spawn(name="Coder", model=Models.Codex.GPT_5_3_CODEX, channels=["GTM"], task="Build")

    await asyncio.gather(
        relay.wait_for_agent_ready("Analyst"),
        relay.wait_for_agent_ready("Coder"),
    )
    await relay.shutdown()

Split from PR #472

This PR contains only the Python SDK changes, split out from #472 as requested. The openclaw-relaycast package will be in a separate PR.

Test plan

• All existing workflow builder tests pass
• New imports verified working
• Integration test with live broker binary

🤖 Generated with Claude Code

---

General approach: Avoid passing untrusted or environment-derived values into a shell-processed command string. Use child_process.execFileSync (or spawnSync) with an argument array instead of execSync with a concatenated string. That way, targetPath and downloadUrl become plain arguments to curl, not subject to shell parsing.

Best specific fix here:

• Replace the execSync call that runs curl with execFileSync('curl', [...]), passing downloadUrl and targetPath as separate arguments.
• Similarly, replace the codesign invocation on macOS with execFileSync('codesign', [...]).
• Replace the verification step execSync(\"${targetPath}" --help`, ...)withexecFileSync(targetPath, ['--help'], ...)`.
• Keep timeouts and stdio options as close as possible to the original behavior.
• To implement this, we only need to:
  • Import execFileSync from node:child_process alongside the existing imports.
  • Update the three execSync usages inside installBrokerBinary to execFileSync with argument arrays.

All changes are confined to packages/sdk/src/client.ts in the shown regions.

In general, the safest way to fix this kind of issue is to avoid spawning a shell when executing external commands, and instead use APIs that accept the program name and its arguments as separate parameters (for Node.js, child_process.execFile / execFileSync or spawn). This way, any untrusted strings are passed directly as arguments to the target program and are not interpreted by a shell, eliminating shell injection concerns.

For this specific code, installBrokerBinary already imports execSync from node:child_process and uses it to run curl, codesign, and the newly installed broker binary. The only flagged command is the codesign invocation on macOS:

execSync(`codesign --force --sign - "${targetPath}"`, {
  timeout: 10_000,
  stdio: ['pipe', 'pipe', 'pipe'],
});

The minimal, behavior-preserving fix is to replace this with a call to execFileSync and pass the arguments as an array: ['--force', '--sign', '-', targetPath]. This avoids using a shell entirely, so any contents of targetPath (even if influenced by environment variables) are treated purely as a path argument by codesign. To do this:

1. Update the import from node:child_process at the top of packages/sdk/src/client.ts to include execFileSync alongside the existing execSync and spawn.
2. Replace the execSync invocation within the macOS codesign block with execFileSync('codesign', ['--force', '--sign', '-', targetPath], { ... }), preserving the existing timeout and stdio options.

No other behavior changes are needed, and the rest of the function can remain untouched. This single change will also address any additional alert variants that refer to the same sink.

General approach: Avoid passing any value derived from untrusted input (including environment variables) into a shell command string. Prefer child_process.execFileSync (or spawn with shell: false) so arguments are passed as an array and not interpreted by a shell. This removes shell metacharacter interpretation regardless of the content of targetPath.

Best concrete fix here: change the verification step on line 717 from execSync with a constructed command string to execFileSync with targetPath as the executable and '--help' as an argument. That way, even if HOME/USERPROFILE are maliciously set, targetPath is treated purely as an executable path, not parsed by a shell.

Details:

• In packages/sdk/src/client.ts, add execFileSync to the existing import from node:child_process.
• Replace:

  execSync(`"${targetPath}" --help`, { timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'] });

  with:

  execFileSync(targetPath, ['--help'], { timeout: 10_000, stdio: ['pipe', 'pipe', 'pipe'] });

• This keeps behavior the same (run the just-installed broker with --help to verify it works) but avoids shell interpretation.
• No additional helper methods or complex sanitization are needed.

---

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 13 additional findings in Devin Review.

[devin-ai-integration]

🔴 Uncaught exception in event listener kills the stdout reader, silently breaking all event processing

If any event hook callback (e.g., on_message_received, on_agent_ready) raises an exception, it propagates through _handle_stdout_line → _read_stdout, terminating the reader coroutine. After this, no more broker events or responses are processed, causing all pending and future requests to hang until their timeouts.

Root Cause and Impact

In client.py:407, event listeners are called in a bare loop with no try/except:

for listener in self._event_listeners:
    listener(event)

The listeners include the relay's _wire_events handler (relay.py:636), which calls user-provided hooks like self.on_message_received(msg) at relay.py:653. If the user's hook raises (e.g., relay.on_message_received = lambda msg: 1/0), the exception propagates up through _handle_stdout_line at client.py:388, out of the while True loop in _read_stdout at client.py:367-373, killing the reader task.

Since the reader task is fire-and-forget (asyncio.create_task at client.py:345), the exception is silently lost ("Task exception was never retrieved"). All subsequent stdout from the broker is ignored. Pending requests in self._pending hang until their individual timeouts. The broker process continues running but the SDK is effectively dead.

The TypeScript equivalent uses Node.js readline's on('line', ...) event handler (client.ts:403-414), where an exception in a handler doesn't prevent subsequent line events from being processed — making the TS version naturally more resilient to callback errors.

Impact: A single user callback error permanently breaks the SDK instance, with no visible error or recovery path.

Suggested change

	for listener in self._event_listeners:
	listener(event)
	for listener in self._event_listeners:
	try:
	listener(event)
	except Exception:
	pass # Don't let listener errors kill the reader

---

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