molecule-ai/docs
35
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(runtime-mcp): document channel envelope attributes table

Browse Source 
Adds a per-attribute reference table for the <channel> 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) <noreply@anthropic.com>
This commit is contained in:
Hongming Wang 2026-05-01 17:49:02 -07:00
parent a45a1c65c3
commit 9c28fcf22c
1 changed files with 44 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
content/docs/runtime-mcp.mdx
View File

@ -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.
#### `<channel>` 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 `<channel>` 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:
```
<channel source="molecule" kind="peer_agent"
peer_id="11111111-2222-3333-4444-555555555555"
peer_name="ops-agent" peer_role="sre"
agent_card_url="https://platform.example.com/registry/discover/11111111-2222-3333-4444-555555555555"
activity_id="act-742" ts="2026-05-01T12:34:56Z">
Can you check the deploy status for the canary?
</channel>
```
| Client | Push path | Poll path |
|---|---|---|
| Claude Code with `--dangerously-load-development-channels server:molecule` | ✅ inline `← molecule:` tag | ✅ also works |