Broker Capability Reference

The complete list of capabilities a Broker developer can request. Capabilities are what a Broker manifest declares as "what permissions I need" — at install time the user sees the capability list and must consent before installation proceeds; at runtime the broker can only call APIs corresponding to granted capabilities.

---

1. Capability Model

1.1 Three Categories

Category	Description	Default Grant
UI Components (Vue/iframe)	graph-editor / theme / form-builder / media-viewer	✅ Granted by default
API Access	rooms.read / rooms.write / guild.tasks.read / storage etc.	Some default, rest on request
Sandbox (Python plugin only)	network / filesystem.read / filesystem.write / extra_modules	❌ Requires explicit consent

1.2 Risk Levels

Level	Meaning	User Prompt
low	Read-only access, no side effects	Usually auto-granted
medium	Write access, limited impact	Requires user consent
high	Destructive operations or fund transfers	Requires explicit user consent

---

2. Complete Capability List

2.1 Sandbox Capabilities

Capability	Risk	Description
network	high	Access external network (HTTP requests), may leak data
filesystem.read	medium	Read the filesystem
filesystem.write	high	Write to the filesystem, can modify user files
extra_modules	medium	Import additional Python modules (see AST allowlist)

Sandbox capabilities only apply to the plugin path. Pure Vue/iframe brokers do not need sandbox capabilities.

2.2 UI Capabilities

Capability	Risk	Default	Description
graph-editor	low	✅	Use the interactive graph editor component (VueFlow)
theme	low	✅	Auto-sync app theme (light/dark)
form-builder	low	✅	Use the dynamic form builder
media-viewer	low	✅	Use the image/video viewer

2.3 API Capabilities

Capability	Risk	Default	Description
rooms.read	low	✅	Read room list and metadata
rooms.write	medium	❌	Create/update rooms
rooms.delete	high	❌	Delete rooms
guild.tasks.read	low	✅	Read task list and details
guild.tasks.write	medium	❌	Create/update tasks
guild.tasks.delete	high	❌	Delete tasks
guild.tokens.write	high	❌	Transfer tokens
profile.read	low	✅	Read user profile
profile.write	medium	❌	Update user profile
agents.read	low	✅	Read agent list
agents.chat	medium	❌	Send messages to agents
storage	low	✅	Broker-scoped KV storage

2.4 High-Level Capabilities (manifest capabilities_required)

These are coarser-grained "business-layer capabilities" declared directly in the manifest:

Capability	Description
guild	Guild/rooms/posts/task library
ledger	Token ledger (issue/transfer/settle)
recipe_call	Call local Recipes (e.g. generate profiles/contracts)
scheduler	Scheduled triggers (cron)
settle.trigger	Trigger settlement

---

3. Role Permission Matrix

3.1 Default Role → Caps Ladder

When the manifest does not declare role_defs, the default ladder is used:

Role	Caps
owner	* (all)
admin	room.* / thread.* / message.* / reputation.rate / deal.* / ledger.append / ledger.read
mod	message.* / room.members.role / room.members.remove
member	message.post / room.read / thread.read / reputation.rate
guest	message.post / room.read

3.2 Custom role_defs

"role_defs": {
  "owner":   {"caps": ["*"]},
  "approver": {"caps": ["task.approve", "task.verdict", "settle.trigger", "message.post", "message.read", "task.read"]},
  "issuer":  {"caps": ["task.publish", "task.propose", "task.read", "message.post", "message.read", "thread.join"]},
  "developer": {"caps": ["task.accept", "task.deliver", "task.read", "message.post", "message.read", "thread.join"]},
  "audience": {"caps": ["task.read", "message.read"]}
}

3.3 Wildcard Matching

Capabilities use dot-namespaced naming with wildcard support:

• room.* matches room.create / room.archive / room.members.add / ...
• * matches everything

room.create             room.archive           room.rename
room.members.add        room.members.remove    room.members.role
thread.create           thread.archive
message.post            message.delete
reputation.rate
deal.propose            deal.transition
ledger.append           ledger.read

3.4 room.owner Super-Role

room.owner (the creator) is treated as a super-role by the registry: regardless of how the manifest is written, role=owner is directly allowed all operations. This prevents a misconfigured manifest from locking the room owner out of their own room.

---

4. Authorization Flow

4.1 At Install Time

1. User clicks install → bridge parses manifest.capabilities_required + manifest.permissions
2. Frontend renders the capability list + risk levels
3. User checks to consent → POST /api/broker_workshop/instances/consent
4. After consent the broker starts a worker (sandbox) or registers in-memory (in-process)

4.2 At Runtime

• Each (broker_id, role) combination has an independent caps set
• PermissionRegistry is the single source of truth: bridge routes, SDK calls, and plugin code all consult it for answers
• capability_grants/ (src/broker/capability_grants/repos.py) persists per-(broker, cluster) specific grant records

4.3 Drift Detection

If a manifest upgrade changes the capability hash → raises CapabilityDrifted, requiring the user to re-consent.

---

5. Known Broker Capability Requirements

5.1 Ventaris (Guild Collaboration)

"capabilities_required": ["guild", "ledger", "recipe_call", "scheduler"]

Full role_defs example in §3.2.

reputation_dimensions:

[
  {"key": "delivery", "label": "Delivery Quality", "min": 0, "max": 10},
  {"key": "punctuality", "label": "Punctuality", "min": 0, "max": 10},
  {"key": "collaboration", "label": "Collaboration", "min": 0, "max": 10},
  {"key": "leadership", "label": "Leadership", "min": 0, "max": 10}
]

5.2 starter_broker

No explicit capabilities_required (pure UI demo).

5.3 hello_broker

"capabilities": ["rooms.read", "rooms.write"]

5.4 example_broker

"capabilities": ["graph-editor", "theme", "rooms.read", "rooms.write",
                 "guild.tasks.read", "guild.tasks.write"],
"permissions": {"network": false, "storage": true}

---

6. Capability Registry REST API

6.1 Query Registry

GET /api/broker_workshop/capabilities/registry

Returns a CapabilityInfo list of all known capabilities.

6.2 Describe Capabilities

GET /api/broker_workshop/capabilities/describe?names=rooms.read,guild

Returns {name, description, category, risk_level} for the specified capabilities.

6.3 Query Approval Status

GET /api/broker_workshop/instances/{broker_id}/capabilities/status

Returns the current broker's capability approval status.

6.4 Approve Capabilities

POST /api/broker_workshop/instances/{broker_id}/capabilities/approve
Body: {"capabilities": ["network", "extra_modules"], "approved": true}

---

7. PermissionRegistry Implementation Details

# src/broker/permissions.py
class PermissionRegistry:
    """Role-to-capability resolution.

    * In-memory, rebuilt on each install / resume.
    * Merges manifest's role_defs with sensible defaults.
    * Wildcard matching via fnmatch.
    * room.owner short-circuits to True.
    """

    def register(self, broker_id: str, role_defs: dict) -> None
    def check(self, broker_id: str, role: str, capability: str) -> bool
    def list_roles(self, broker_id: str) -> list[str]
    def list_caps(self, broker_id: str, role: str) -> list[str]

Checks are O(1) dict lookup + fnmatch pass. PermissionRegistry is synchronous and side-effect-free.

---

8. Security Boundaries

Boundary	Current Status
Permission enforcement inside Sandbox	✅ Landed (AST guard + worker restrictions)
Permission enforcement in Bridge API	🔶 TODO (manifest.permissions not yet enforced server-side in bridge routes)
Cross-cluster permission propagation	🔶 Hooks in place

---

Reference Source Code

• Capability registry: src/broker/capability_registry.py
• Permission registry: src/broker/permissions.py
• Capability grants: src/broker/capability_grants/repos.py
• Member capabilities: src/broker/member_caps.py
• REST: src/bridge/routes/broker_workshop.py