From 9c28fcf22c4eb75f8f3ed5161b32dfc59071a42f Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Fri, 1 May 2026 17:49:02 -0700 Subject: [PATCH] docs(runtime-mcp): document channel envelope attributes table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a per-attribute reference table for the tag (push path) and the equivalent JSON shape (poll path) so the agent — and operators reading the docs — know what metadata to expect for every inbound message. Covers the new peer_name, peer_role, agent_card_url fields landing with the wheel-side enrichment in molecule-core#2471, including the registry-lookup graceful-degrade rule (lookup failure → attrs absent, push still delivers) and the deterministic agent_card_url construction (present even on registry outage). Includes a worked example of a peer_agent push so a reader can copy the wire shape into their own host bridge if they need to validate what they're seeing. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/docs/runtime-mcp.mdx | 44 ++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/content/docs/runtime-mcp.mdx b/content/docs/runtime-mcp.mdx index 8c012f3..67d3026 100644 --- a/content/docs/runtime-mcp.mdx +++ b/content/docs/runtime-mcp.mdx @@ -227,6 +227,50 @@ when you're running Claude Code with the dev-channels flag and don't want the per-turn stall. The instructions adapt automatically: with polling disabled, the agent is told push is the only delivery path. +#### `` envelope attributes + +Every inbound message — push or poll — carries the same metadata +shape. On the push path, attributes render inline as XML-style attrs +on the `` tag; on the poll path, the same fields appear in +the JSON returned by `inbox_peek` / `wait_for_message`. Either way, +the agent sees a consistent view. + +| Attribute | When present | Description | +|---|---|---| +| `source` | always | Always `molecule` — distinguishes our channel from other registered servers (`telegram`, etc.). | +| `kind` | always | `canvas_user` (a human in the canvas chat) or `peer_agent` (another workspace's agent). Drives reply routing. | +| `peer_id` | always | Empty for `canvas_user`; the sender's workspace UUID for `peer_agent`. Use as `workspace_id` when calling `delegate_task` to reply. | +| `peer_name` | `peer_agent` only | The peer's display name (e.g. `ops-agent`) resolved from the platform registry. Absent on registry-lookup failure — the push still delivers. | +| `peer_role` | `peer_agent` only | The peer's declared role (e.g. `sre`, `coordinator`). Same registry source as `peer_name`; same graceful-degrade rule. | +| `agent_card_url` | `peer_agent` only | URL of the platform's discover endpoint for this peer. Fetch it if you need the peer's full capability list (skills, runtime, etc.). | +| `activity_id` | always | The inbox row ID. **Pass it to `inbox_pop` after handling** so the message isn't re-delivered on the next push or poll cycle. | +| `ts` | always | ISO-8601 timestamp of when the message landed in the platform's activity log. | + +`peer_name` and `peer_role` are added by the wheel via a TTL'd +registry lookup keyed on `peer_id`. Cache TTL is 5 minutes — long +enough that a busy multi-peer chat doesn't hit the registry on every +push, short enough that role/name renames propagate within a single +agent session. Lookup failure is silent: the attributes are simply +absent and the push delivers anyway, so a registry stall can never +block inbound messages. + +`agent_card_url` is constructed deterministically from `peer_id`, so +it's present even if the registry is down. The agent can hit it +later to enumerate the sender's capabilities once the registry is +back up. + +Worked push example for a `peer_agent` arrival: + +``` + + Can you check the deploy status for the canary? + +``` + | Client | Push path | Poll path | |---|---|---| | Claude Code with `--dangerously-load-development-channels server:molecule` | ✅ inline `← molecule:` tag | ✅ also works |