Dashboard

The AgentFlow Dashboard includes two SOMA pages: the Intelligence Tab (per-agent view) and the Governance Page (global organizational view). Both read from the vault via dedicated API endpoints.

Setup

Start the dashboard server with the --soma-vault flag pointing to your vault directory:

agentflow dashboard --soma-vault .soma/vault

[agentflow] Dashboard server started on http://localhost:3000
[agentflow] SOMA vault loaded: .soma/vault (337 entities)
[agentflow] SOMA API endpoints registered:
[agentflow]   GET  /api/soma/report
[agentflow]   GET  /api/soma/governance
[agentflow]   POST /api/soma/governance/promote
[agentflow]   POST /api/soma/governance/reject
[agentflow]   GET  /api/soma/governance/evidence/:id

The dashboard reads soma-report.json for the intelligence report data. Run soma report or soma run to generate this file before starting the dashboard.

Intelligence Tab

The Intelligence Tab provides a per-agent view of SOMA's knowledge. Navigate to any agent to see its SOMA intelligence panel.

Agent Health Card

The top card shows real-time agent health:

┌─────────────────────────────────────────────────┐
│  agent-alpha                           healthy   │
│  Runs: 42  │  Failures: 2  │  Rate: 4.8%       │
│  Last seen: 3 min ago                            │
└─────────────────────────────────────────────────┘

Status values: healthy (< 10% failure), degraded (10-50%), critical (> 50% or no runs in 30 min).

A staleness warning appears if the agent has not reported in over 30 minutes:

⚠ Agent data is stale (last update: 47 min ago)

All Agents Table

Below the health card, a table of the top 20 agents sorted by activity:

Agent	Runs	Failures	Rate	Status
agent-alpha	42	2	4.8%	healthy
agent-beta	31	0	0.0%	healthy
agent-gamma	28	8	28.6%	degraded

Insights with Layer Badges

Each insight is tagged with its knowledge layer:

[L4] API rate limits require backoff          (canon, enforcing)
[L3] retry-heavy-agents                       (pending, confidence: 0.82)
[L3] fetch-data dominates tool usage          (pending, confidence: 0.71)
[L1] execution trace exec-alpha-091           (archive)

Layer badges are color-coded:

L4 (purple) — Ratified canon, mandatory
L3 (blue) — Emerging proposals, advisory
L2 (green) — Team working memory, contextual
L1 (gray) — Archive, historical

Insights are filterable by type (insight, policy, archetype, decision) and by minimum confidence threshold.

Guard Explanation Cards

When a guard violation occurs, the dashboard renders a structured explanation card showing the rule, threshold vs actual value, source badge, and evidence:

┌──────────────────────────────────────────────────┐
│  max-failure-rate              [SOMA Policy]      │
│  0.75  →  limit 0.3                              │
│  Based on last 50 executions                     │
└──────────────────────────────────────────────────┘

Source badges indicate where the guard rule originates: Static (hardcoded), SOMA Policy (L3/L4 vault), Adaptive (learned), or Assertion (outcome-based). Cards degrade gracefully to a raw message for older violations without structured explanation data.

Cost Efficiency Panel (Pro)

The Efficiency Panel shows per-run cost metrics with wasteful loop detection:

┌──────────────────────────────────────────────────┐
│  Cost Efficiency                                  │
│  Mean: 120    Median: 95    P95: 340    85%      │
│  cost/node    cost/node     cost/node   coverage │
│                                                   │
│  ⚠ Retry loop detected: fetch-data (5 retries)  │
└──────────────────────────────────────────────────┘

Fetches from GET /api/soma/efficiency. Shows aggregate cost-per-node stats, data coverage, and flags for wasteful patterns.

Conformance Drift Chart (Pro)

An inline SVG chart showing agent conformance scores over time with a regression line overlay:

┌──────────────────────────────────────────────────┐
│  Conformance Trend: agent-alpha    [Stable]       │
│  1.0 ─ ● ● ● ● ●──────── (regression)          │
│  0.0 ─────────────────────                        │
│  Slope: -0.0012/run · R²: 0.85 · 12 points      │
└──────────────────────────────────────────────────┘

Status indicators: Stable (green), Degrading (red alert badge), Improving (green), Needs more data (gray, < 10 data points). Fetches from GET /api/soma/drift?agentId=<id>.

Run Receipt Tab

The Receipt tab on each execution detail view renders a structured step table:

┌──────────────────────────────────────────────────┐
│  Run ID: run-123    Agent: agent-alpha            │
│  Status: completed  Duration: 3.5s               │
├────┬──────────┬──────────┬──────────┬────────────┤
│  # │ Step     │ Type     │ Status   │ Tokens     │
├────┼──────────┼──────────┼──────────┼────────────┤
│  1 │ Start    │ startNode│ ✓        │ —          │
│  2 │ Analyze  │ llmNode  │ ✓        │ 1,200      │
│  3 │ End      │ endNode  │ ✗        │ —          │
├────┴──────────┴──────────┴──────────┴────────────┤
│  Total: 1,200 tokens                             │
└──────────────────────────────────────────────────┘

The token cost column only appears when cost data is present in the trace metadata.

Model Variant Toggle (Pro)

The Variant Explorer supports toggling between path-based and model-based variant views. When enabled (Pro tier), a "By Model" checkbox appears that splits variants by which model was used, showing model badges on each row.

Policies

Cross-Agent Knowledge Flow

The Intelligence tab shows a Cross-Agent section when SOMA has insights that reference data from 2+ agents. Each agent pair shows the shared insights with claims:

Agent pairs grouped alphabetically
Each insight shows name, claim summary, and tags
Appears automatically when source_agents data exists on L3 insights

Data populates after running soma pipeline --provider ... which triggers the synthesizer to create cross-agent insights with source_agents tracking.

Agent Health Briefing

The Briefing tab on the agent profile page provides a single-page operational view synthesizing all SOMA intelligence for the selected agent. It shows:

Status: critical (>50% failure), degraded (>10%), or healthy with failure rate
Intelligence by type: contradictions, constraints, decisions, policies, insights — each showing the top 3 items with claims
Peer comparison: horizontal bar chart showing all agents sorted by success rate, highlighting the current agent
Drift trend: conformance score status and data point count

Decision Replay

The Decisions tab on the execution detail view shows the step-by-step decision chain for that specific execution. Each step displays:

Decision index, outcome icon (ok/failed/timeout/skipped), action name, and duration
Click any step to expand and see the reasoning (why the agent made that choice) and the output or error
Pattern signature displayed at the top showing the collapsed decision chain

This view requires trace data with decision-level granularity (session JSONL files with tool calls, or JSON traces with tool nodes).

Policies

Active guard policies show their enforcement severity:

┌──────────────────────────────────────────────────┐
│  Guard Policies                                   │
├──────────────────────────────────────────────────┤
│  [L4] max-retry-count          severity: error   │
│  [L3] payload-size-limit       severity: warning │
└──────────────────────────────────────────────────┘

Policies from L4 are mandatory (error severity blocks execution). Policies from L3 are advisory (warning severity logs but does not block).

Governance Page

The Governance Page is the visual equivalent of the soma governance CLI commands. Navigate to /governance in the dashboard.

Layer Summary Bar

A horizontal bar at the top shows entry counts per layer:

┌──────────────────────────────────────────────────────────┐
│  L1: 298  │  L2: 12  │  L3: 19  │  L4: 8               │
│  ████████████████████  ██  ████  ██                      │
└──────────────────────────────────────────────────────────┘

The bar is proportionally sized. Governance stats appear below:

Pending: 4  │  Promoted: 6  │  Rejected: 2

Pending Proposals List

Each pending L3 proposal shows as a card with approve/reject actions:

┌──────────────────────────────────────────────────────────┐
│  retry-heavy-agents                    confidence: 0.82  │
│  Type: archetype  │  Evidence: 14 traces from 6 agents   │
│                                                          │
│  6 agents exhibit retry counts above threshold.          │
│  Pattern suggests missing circuit breaker logic.         │
│                                                          │
│  [▼ Show evidence]    [✓ Approve]    [✗ Reject]         │
└──────────────────────────────────────────────────────────┘

Clicking Show evidence expands the evidence chain, showing all linked L1 entries:

  Evidence chain:
    [L1] decision-retry-agent-alpha-exec-091  (retry: 4, failed)
    [L1] decision-retry-agent-alpha-exec-088  (retry: 3, completed)
    [L1] decision-retry-agent-beta-exec-044   (retry: 5, failed)
    [L1] decision-retry-agent-gamma-exec-031  (retry: 4, failed)
    ... expand to see all 14

Clicking Approve calls POST /api/soma/governance/promote with the current user as reviewerId. Clicking Reject opens a dialog for a rejection reason, then calls POST /api/soma/governance/reject.

Both mutations are executed via the SOMA CLI internally (child_process.execSync with sanitized arguments). The browser never writes to the vault directly — all writes go through SOMA's permission-enforced system.

Canon View

Below the pending list, all ratified L4 entries are displayed:

┌──────────────────────────────────────────────────────────┐
│  Canon (8 entries)                                        │
├──────────────────────────────────────────────────────────┤
│  max-retry-count              ratified by: ops-lead      │
│  Policy: enforcing            2026-03-18                 │
│                                                          │
│  api-backoff-required         ratified by: platform-eng  │
│  Policy: enforcing            2026-03-15                 │
│                                                          │
│  ... (6 more)                                            │
└──────────────────────────────────────────────────────────┘

Each canon entry shows the reviewer who promoted it and the timestamp.

API Endpoints

Method	Endpoint	Description	Body
`GET`	`/api/soma/report`	Intelligence report data (`soma-report.json`)	—
`GET`	`/api/soma/governance`	Layer counts, pending proposals, canon entries	—
`POST`	`/api/soma/governance/promote`	Promote L3 to L4	`{ entryId, reviewerId }`
`POST`	`/api/soma/governance/reject`	Reject L3 proposal	`{ entryId, reviewerId, reason }`
`GET`	`/api/soma/governance/evidence/:id`	Full evidence chain for a proposal	—
`GET`	`/api/soma/efficiency`	Per-run cost metrics, aggregate stats, wasteful flags	—
`GET`	`/api/soma/drift?agentId=<id>`	Conformance drift data with regression analysis	—

Example: Fetching Governance Data

curl http://localhost:3000/api/soma/governance | jq

{
  "layers": {
    "archive": 298,
    "working": 12,
    "emerging": 19,
    "canon": 8
  },
  "governance": {
    "pending": 4,
    "promoted": 6,
    "rejected": 2
  },
  "proposals": [
    {
      "id": "retry-heavy-agents",
      "type": "archetype",
      "confidence": 0.82,
      "status": "pending",
      "evidence_count": 14,
      "summary": "6 agents exhibit retry counts above threshold..."
    }
  ],
  "canon": [
    {
      "id": "canon-max-retry-count",
      "type": "policy",
      "ratified_by": "ops-lead",
      "ratified_at": "2026-03-18T10:00:00.000Z"
    }
  ]
}

Example: Promoting via API

curl -X POST http://localhost:3000/api/soma/governance/promote \
  -H "Content-Type: application/json" \
  -d '{"entryId": "retry-heavy-agents", "reviewerId": "alice"}'

{
  "success": true,
  "created": "canon-retry-heavy-agents",
  "ratified_by": "alice",
  "ratified_at": "2026-03-21T09:15:00.000Z"
}

Example: Fetching Evidence

curl http://localhost:3000/api/soma/governance/evidence/retry-heavy-agents | jq

{
  "proposal": {
    "id": "retry-heavy-agents",
    "type": "archetype",
    "confidence": 0.82,
    "summary": "6 agents exhibit retry counts above threshold..."
  },
  "evidence": [
    {
      "id": "decision-retry-agent-alpha-exec-091",
      "type": "decision",
      "layer": "archive",
      "decision_type": "retry",
      "agent_id": "agent-alpha",
      "outcome": "failed"
    }
  ]
}

Setup​

Intelligence Tab​

Agent Health Card​

All Agents Table​

Insights with Layer Badges​

Guard Explanation Cards​

Cost Efficiency Panel (Pro)​

Conformance Drift Chart (Pro)​

Run Receipt Tab​

Model Variant Toggle (Pro)​

Policies​

Cross-Agent Knowledge Flow​

Agent Health Briefing​

Decision Replay​

Policies​

Governance Page​

Layer Summary Bar​

Pending Proposals List​

Canon View​

API Endpoints​

Example: Fetching Governance Data​

Example: Promoting via API​

Example: Fetching Evidence​

Setup

Intelligence Tab

Agent Health Card

All Agents Table

Insights with Layer Badges

Guard Explanation Cards

Cost Efficiency Panel (Pro)

Conformance Drift Chart (Pro)

Run Receipt Tab

Model Variant Toggle (Pro)

Policies

Cross-Agent Knowledge Flow

Agent Health Briefing

Decision Replay

Policies

Governance Page

Layer Summary Bar

Pending Proposals List

Canon View

API Endpoints

Example: Fetching Governance Data

Example: Promoting via API

Example: Fetching Evidence