Communication, API & A2A

Part of the Comprehensive Technical Documentation. Definitive reference based on a non-invasive scan of the molecule-core repository.

6. Communication Rules

Hierarchy = Topology

The CanCommunicate() function is the single source of truth for all access control.

Direction	Allowed	Example
Sibling ↔ Sibling	YES	Marketing Agent ↔ Developer PM
Parent → Child	YES	Developer PM → Frontend Agent
Child → Parent	YES	Frontend Agent → Developer PM
Skip levels	NO	Frontend Agent → Business Core (403)
Cross-team	NO	Frontend Agent → Operations Team (403)

Access Check Algorithm

IF caller.parent_id == target.parent_id → ALLOW (siblings)
ELIF both parent_id IS NULL → ALLOW (root-level siblings)
ELIF caller.ID == target.parent_id → ALLOW (parent→child)
ELIF target.ID == caller.parent_id → ALLOW (child→parent)
ELSE → DENY (403 Forbidden)

This same logic governs: A2A delegation, memory scope enforcement, activity visibility, approval routing, and WebSocket event fanout.

7. Platform API Routes

Workspace Lifecycle (8 endpoints)

Method	Endpoint	Purpose
`POST`	`/workspaces`	Create and provision new workspace
`GET`	`/workspaces`	List all with canvas layout data
`GET`	`/workspaces/:id`	Get single workspace
`PATCH`	`/workspaces/:id`	Update name, role, tier, runtime, parent
`DELETE`	`/workspaces/:id`	Remove workspace
`POST`	`/workspaces/:id/restart`	Restart container
`POST`	`/workspaces/:id/pause`	Pause with cascade to children
`POST`	`/workspaces/:id/resume`	Resume from pause

Registry & Discovery (5 endpoints)

Method	Endpoint	Purpose
`POST`	`/registry/register`	Workspace self-registration on startup
`POST`	`/registry/heartbeat`	Liveness + current task + error rate (30s interval)
`POST`	`/registry/update-card`	Push Agent Card updates (skills, capabilities)
`GET`	`/registry/discover/:id`	Resolve workspace URL (hierarchy-validated)
`GET`	`/registry/:id/peers`	List reachable peers for workspace

Memory (6 endpoints)

Method	Endpoint	Purpose
`POST`	`/workspaces/:id/memories`	Commit HMA-scoped memory (LOCAL/TEAM/GLOBAL)
`GET`	`/workspaces/:id/memories`	Search scoped memories with query
`DELETE`	`/workspaces/:id/memories/:memoryId`	Delete specific memory entry
`GET`	`/workspaces/:id/memory`	List key/value workspace memory
`POST`	`/workspaces/:id/memory`	Upsert key/value pair (optional TTL)
`DELETE`	`/workspaces/:id/memory/:key`	Delete key/value entry

Secrets & Config (5 endpoints)

Method	Endpoint	Purpose
`GET`	`/workspaces/:id/secrets`	Get merged workspace + global secrets
`POST`	`/workspaces/:id/secrets`	Upsert workspace secret (triggers auto-restart)
`DELETE`	`/workspaces/:id/secrets/:key`	Delete secret (triggers auto-restart)
`GET`	`/workspaces/:id/config`	Get workspace config.yaml
`PATCH`	`/workspaces/:id/config`	Update workspace config

A2A & Activity (5 endpoints)

Method	Endpoint	Purpose
`POST`	`/workspaces/:id/a2a`	Proxy A2A request to target workspace
`GET`	`/workspaces/:id/activity`	List activity rows (filterable)
`POST`	`/workspaces/:id/activity`	Report activity from workspace
`POST`	`/workspaces/:id/notify`	Emit user-facing notification
`GET`	`/workspaces/:id/session-search`	Search recent activity + memory for contextual recall

Team & Hierarchy (2 endpoints)

Method	Endpoint	Purpose
`POST`	`/workspaces/:id/expand`	Expand workspace into team (become coordinator)
`POST`	`/workspaces/:id/collapse`	Collapse team back to single workspace

Files, Terminal, Templates, Bundles (8 endpoints)

Method	Endpoint	Purpose
`GET`	`/workspaces/:id/files[/*path]`	List or read files
`PUT`	`/workspaces/:id/files/*path`	Write file
`DELETE`	`/workspaces/:id/files/*path`	Delete file
`WS`	`/workspaces/:id/terminal`	WebSocket terminal session into container
`GET`	`/bundles/export/:id`	Export workspace as `.bundle.json`
`POST`	`/bundles/import`	Import workspace bundle (recursive)
`GET`	`/templates`	List available workspace templates
`POST`	`/templates/import`	Import custom template folder

Observability & Real-Time (5 endpoints)

Method	Endpoint	Purpose
`GET`	`/health`	Health check
`GET`	`/metrics`	Prometheus metrics (v0.0.4 format)
`GET`	`/workspaces/:id/traces`	Langfuse trace links
`GET`	`/events[/:workspaceId]`	Event stream (SSE)
`WS`	`/ws`	WebSocket hub for real-time event fanout

8. A2A Protocol

Message Format (JSON-RPC 2.0 over HTTP)

{
  "jsonrpc": "2.0",
  "id": "task-123",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{"kind": "text", "text": "Build the login feature"}],
      "messageId": "msg-456"
    }
  }
}

Two Call Modes

Mode	Method	Use Case
Synchronous	`message/send`	Short tasks, immediate response
Streaming	`message/sendSubscribe`	Long tasks, SSE progress updates

Discovery Flow

Caller queries GET /registry/discover/:targetId with X-Workspace-ID header
Platform validates CanCommunicate(caller, target) — returns 403 if denied
Returns Docker-internal URL (workspace caller) or host-mapped URL (Canvas/external caller)
Caller sends A2A message directly to target (peer-to-peer)
Target processes task and responds

Task State Machine

submitted → working → completed
                   → failed
                   → canceled
         → input-required → working (caller provides input)

Authentication

MVP (current): Discovery-time validation only. Direct A2A calls are unauthenticated (acceptable for self-hosted Docker network isolation).
Post-MVP: Platform-issued short-lived signed tokens scoped to caller/target pair.

On this page