From 2324b3ee10ad1a2cecc929773547e8e01a5b79b9 Mon Sep 17 00:00:00 2001 From: Molecule AI Documentation Specialist Date: Fri, 17 Apr 2026 18:36:20 +0000 Subject: [PATCH] docs(canvas): A2A topology overlay and audit trail panel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two Canvas features merged today: - PR #751: A2A topology overlay — animated delegation edges (violet <5 min, blue otherwise), toolbar toggle, localStorage-persisted, polls every 60s - PR #759: Audit trail panel — Side Panel Audit tab, tamper-evident chain, event-type filters, cursor pagination, chain_valid tamper indicator Changes: - concepts.mdx: expand The Canvas section with overlay + audit panel docs - api-reference.mdx: add GET /workspaces/:id/audit with full entry schema; update activity row to document ?type=delegation filter Co-Authored-By: Claude Sonnet 4.6 --- content/docs/api-reference.mdx | 42 +++++++++++++++++++++++++++++++++- content/docs/concepts.mdx | 32 ++++++++++++++++++++++++++ 2 files changed, 73 insertions(+), 1 deletion(-) diff --git a/content/docs/api-reference.mdx b/content/docs/api-reference.mdx index adde987..59e6789 100644 --- a/content/docs/api-reference.mdx +++ b/content/docs/api-reference.mdx @@ -200,10 +200,50 @@ Activity logging and search for A2A communications, task updates, and agent logs | Method | Path | Auth | Description | |--------|------|------|-------------| -| GET | `/workspaces/:id/activity` | WorkspaceAuth | List activity logs for a workspace. Supports `?source=canvas` or `?source=agent` filter. | +| GET | `/workspaces/:id/activity` | WorkspaceAuth | List activity logs for a workspace. Supports `?source=canvas` or `?source=agent` filter, and `?type=delegation` for A2A topology overlay polling. | | POST | `/workspaces/:id/activity` | WorkspaceAuth | Log an activity entry (used by workspace runtimes to self-report). | | POST | `/workspaces/:id/notify` | WorkspaceAuth | Agent-to-user push message via WebSocket. Delivers a notification to connected Canvas clients. | +--- + +## Audit Ledger + +Tamper-evident audit trail for workspace events. Used by the Canvas Audit Trail panel. + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/workspaces/:id/audit` | WorkspaceAuth | List audit entries for a workspace. Supports `?event_type=delegation\|decision\|gate\|hitl`, `?cursor=`, and `?limit=` (default 50). | + +### Audit entry schema + +| Field | Type | Description | +|-------|------|-------------| +| `id` | string | Unique entry ID | +| `event_type` | string | `delegation`, `decision`, `gate`, or `hitl` | +| `actor` | string | Workspace ID that generated the event | +| `summary` | string | Human-readable event description | +| `chain_valid` | bool | `false` if the entry's hash does not match the prior chain — indicates possible tampering | +| `created_at` | string (ISO 8601) | Event timestamp | +| `cursor` | string \| null | Opaque pagination cursor; `null` when there are no more entries | + +Example response: + +```json +{ + "entries": [ + { + "id": "aud_xyz789", + "event_type": "delegation", + "actor": "ws_abc123", + "summary": "Delegated task 'fix CI' to Backend Engineer", + "chain_valid": true, + "created_at": "2026-04-17T14:05:00Z" + } + ], + "cursor": "eyJpZCI6ImF1ZF94eXo3ODkifQ" +} +``` + ### Session Search | Method | Path | Auth | Description | diff --git a/content/docs/concepts.mdx b/content/docs/concepts.mdx index ef70c56..e0294bc 100644 --- a/content/docs/concepts.mdx +++ b/content/docs/concepts.mdx @@ -108,6 +108,38 @@ The canvas isn't just a viewer — it's the operator surface. Drag nodes to reorganise teams, click to chat, right-click for actions, watch the team work in real time. +### A2A Topology Overlay + +The canvas renders **live delegation edges** on top of the workspace graph. +When one agent delegates to another, a directed edge appears: + +- **Animated violet** — delegation occurred within the last 5 minutes +- **Static blue** — delegation occurred earlier + +The overlay polls `GET /workspaces/:id/activity?type=delegation` for every +visible node every 60 seconds. Toggle it on/off with the **A2A** button in +the toolbar (⊞ mesh icon) — the setting persists across page loads. + +### Audit Trail Panel + +Every workspace's **Side Panel → Audit** tab (⊟ ledger icon) shows the +workspace's tamper-evident audit ledger via `GET /workspaces/:id/audit`. +Each entry records what happened (event type, actor, outcome) and whether +its hash chain is intact. + +| Event type | Colour | Meaning | +|-----------|--------|---------| +| `delegation` | Blue | An A2A delegation was made or received | +| `decision` | Violet | A gate or approval decision was recorded | +| `gate` | Yellow | A HITL or automated gate was evaluated | +| `hitl` | Orange | A human-in-the-loop approval request | + +Entries with `chain_valid: false` display a red ⚠ tamper indicator — +investigate immediately; the audit chain may have been modified offline. + +Use the event-type filter bar at the top of the panel to narrow results. +Click **Load more** to paginate (cursor-based, 50 entries per page). + ## How they fit together A typical org definition: