fix(inbox): an unplaced inbox follows its registered agent's group

Merged
KH
5d ago
+261-7

Problem

relaygate placed relaycast:inbox/<name> streams only by streamDefaults prefixes (local-, pit-, slack-). Agent Relay Desktop agents enrol with a device token (keyId device:<uid>, gid from controlPrincipals) and are named by their harness (cursor-…, claude-…, codex-…), so their inboxes matched no prefix and every DM to them was denied at stage mode, reason unknown_stream. Local agents could not DM each other.

Fix

resolveStream order is now: override → registered stream → longest prefix default → registered agent's inbox (only for relaycast:inbox/<name>):

  • owner = the agent, gid = the agent's gid
  • mode / acl / classify from the new optional policy field inboxDefaults: [{gid, mode, acl?, classify?}] for that gid; otherwise 660, no ACL (same group may message it, no one else)
  • a name no agent has stays unknown_stream (deny)
  • audit reason suffix :agent-inbox

Explicit overrides and streamDefaults keep precedence. The pit (gid 22) never gets w on a gid-11 inbox unless policy grants it (built-in default has other = 0; inboxDefaults mirroring local- gives 22 only r).

Visibility unchanged: GET /v1/agents still uses operator rules only (resolveStream(..., { agentInboxes: false })), so a derived inbox does not show an agent in the directory. If we want local Desktop agents to list each other too, that's a one-line flip — called out deliberately.

Policy validator: inboxDefaults gids/ACL gids must be defined groups, at most one entry per gid, mode validated as elsewhere. Also: an agent can now read its own inbox (owner digit), which previously failed for these agents the same way.

Docs: docs/contract.md (Resources → DMs; pit deployment section). examples/policy.pit.json declares inboxDefaults for gid 11.

Deployer policy addition

"inboxDefaults": [{"gid": 11, "mode": "660", "acl": [{"gid": 22, "perm": "r"}, {"gid": 44, "perm": "r"}]}]

(mirror whatever ACL your relaycast:inbox/local- rule has). Without it, Desktop agents still DM each other with built-in 660/no ACL. Chart default: separate infra PR.

Tests

test/agent-inbox.test.ts: device-enrolled cursor-x and claude-y DM each other; pit agent can't DM them (also with inboxDefaults mirroring local-: r yes, w no); explicit streamDefaults/overrides win; unregistered name → unknown_stream; only inbox ids derived; directory visibility unchanged; explain reports agent-inbox; validator rules. npm run typecheck + npm test (167) green.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Desktop agents register with device tokens and are named by their harness (cursor-…, claude-…, codex-…), so no streamDefaults prefix covered their inboxes and every DM to them was denied as unknown_stream. Resolution for an inbox is now override → registered stream → prefix default → the registered agent's inbox, owned by that agent, in its group, with mode/ACL/classify from the new inboxDefaults policy entry (default 660, no ACL); a name no agent has still stays unknown_stream.

  • Explicit overrides and streamDefaults keep precedence; audit reasons end in :agent-inbox.
  • A relay-control user's synthetic ctl: identity holds no token, so it is never a DM recipient through this rule and those names stay unknown_stream.
  • Directory visibility is unchanged: GET /v1/agents still uses operator rules only, so a derived inbox doesn't list the agent.

Migration

  • Operators may add "inboxDefaults": [{"gid": 11, "mode": "660", "acl": [...]}] mirroring their relaycast:inbox/local- rule; without it, desktop agents still DM each other with the built-in 660/no ACL.