#256 feat(runtime): ctx.relay — agent-to-agent messaging over the relay (#254 pt.2)

Second piece of #254. Gives handlers a first-class way to message peers over the relay — the inbound counterpart to the relay inbox trigger.

API

ctx.relay.dm(to, text)        // POST /v1/dm
ctx.relay.post(channel, text) // POST /v1/channels/{name}/messages

Both return { ok, messageId? }, are bounded by an 8s timeout, and never throw (return { ok: false } + log on missing token / timeout / non-2xx).

Details

• Auth: the box's agent token — WORKFORCE_AGENT_TOKEN > RELAY_AGENT_TOKEN > RELAY_API_KEY. /v1/dm is agent-scoped, so the workspace key alone won't do.
• Gateway: RELAYCAST_URL > RELAY_BASE_URL (the cloud launcher injects the minted-against value) > https://cast.agentrelay.com.
• Unwraps the relaycast { ok, data } envelope for the message id.
• Implemented inline in runtime, not imported from @agentworkforce/delivery — delivery depends on runtime, so importing it back would be circular. Mirrors delivery's relaycast sender (workforce#255); both default to cast.agentrelay.com. (Follow-up: dedupe by having delivery's relaycast target delegate to ctx.relay.)
• Wired through buildCtx + CtxBuildOptions + CORE_CTX_FIELDS. Typecheck clean; 5/5 new tests.

Replying to a sender

To reply to whoever DM'd the agent, read the sender off the inbound relay event and pass it as to. Surfacing the sender on the typed RelaycastMessageEvent is a follow-up (the event type lives in the external @agent-relay/events); tracked in #254.

Refs #254

🤖 Generated with Claude Code