# Depute (AX) - Complete Documentation

This file contains the complete, concatenated documentation for the Depute React component library. It is optimized for LLMs and AI coding agents.

---

---
title: Introduction
description: React primitives for the human side of agentic AI.
---


## What is Depute?

*Depute (verb meaning to appoint or delegate).*

**Depute** is a React component library for Agentic Experience (AX) design — purpose-built UI primitives for AI agent supervision and human oversight.

The founding frame is [Delegation UI](/docs/lexicon#delegation-ui). Terms used on this site are defined in the [Lexicon](/docs/lexicon).

When an AI agent runs in your product, users need to see what's happening — not raw logs, but structured UI for delegation, trust, and control.

## Why Depute?

Most UI libraries build for CRUD apps. Depute builds for the moment *after* you hand off work to an agent:

- The agent proposes a plan → [**Plan Card**](/docs/components/plan-card) shows it before execution
- The agent wants to send email → [**Approval Gate**](/docs/components/approval-gate) blocks until the user approves
- The agent is running → [**Run Controls**](/docs/components/run-controls) let the user pause or stop at any time
- Multiple agents are coordinating → [**Orchestrator View**](/docs/components/orchestrator-view) shows who's managing whom

**A toolkit for both Builders and Auditors:**
For Product Engineers, Depute provides the UI to stop users from feeling anxious and losing context during long autonomous runs. 
For Security & Risk Teams, Depute is compliance infrastructure. Under emerging governance standards—like the **Singapore IMDA Agentic AI Governance Framework (Jan 2026)**—providing escalation paths, defining UI checkpoints for high-stakes actions, and making humans "meaningfully accountable" is a primary regulatory expectation. Depute helps you operationalize those governance requirements in code.

## Defeating Cognitive Failures

Human-automation research shows that humans are terrible at passively monitoring highly autonomous systems. When working with AI agents, users fall into predictable cognitive traps. Depute maps its primitives directly against these known failures:

- [**Automation Bias**](/docs/lexicon#automation-bias): Users blindly rubber-stamp agent actions without scrutiny → *Mitigated by an [**Automation Bias Alert**](/docs/components/automation-bias-alert) and [**Confidence Meter**](/docs/components/confidence-meter)*
- [**Execution Amnesia**](/docs/lexicon#execution-amnesia): Users lose track of the total "blast radius" of a massive agent session → *Mitigated by a [**Session Overview**](/docs/components/session-overview) and [**State Diff**](/docs/components/state-diff)*
- [**Responsibility Diffusion**](/docs/lexicon#responsibility-diffusion): Users approve actions assuming the machine is accountable → *Mitigated by a [**Decision Record**](/docs/components/decision-record) and [**Binding Approval**](/docs/components/binding-approval)*

## Mitigating Systemic Threats

While Cognitive Failures describe UX traps, Systemic Threats describe catastrophic operational failure modes increasingly targeted by international AI legislation (e.g., IMDA Systemic Threats). Depute's components function as active algorithmic firebreaks:

- [**Cascading Failures**](/docs/lexicon#cascading-failures): An agentic error pollutes downstream autonomous systems rapidly → *Contained by a [**Swarm Monitor**](/docs/components/swarm-monitor) and [**Orchestrator View**](/docs/components/orchestrator-view)*
- [**Hallucinated Planning**](/docs/lexicon#hallucinated-planning): An agent proposes a destructive or nonsensical sequence of tools → *Exposed by a [**Plan Card**](/docs/components/plan-card) and [**Confidence Meter**](/docs/components/confidence-meter)*
- [**Rogue Tool Use**](/docs/lexicon#rogue-tool-use): An agent attempts an irreversible action out-of-bounds → *Blocked by an [**Approval Gate**](/docs/components/approval-gate) and [**Tool Trace**](/docs/components/tool-trace)*
- [**Unpredictable Outcomes**](/docs/lexicon#unpredictable-outcomes): A run completes with thousands of opaque, unlogged side effects → *Audited with a [**State Diff**](/docs/components/state-diff) and [**Session Overview**](/docs/components/session-overview)*

## Use-Case Index (Problem-First)

Not sure which component to use? **Press `⌘K` to search by problem.** The docs are mapped to UX challenges (e.g., search for "cognitive load" or "context switch").

Or start here:
- *"I need to safely switch agent focus across a swarm"* → Use an [**Orchestrator View**](/docs/components/orchestrator-view) + [**Shared Context Ledger**](/docs/components/shared-context-ledger)
- *"I need to stop an agent from making an unrecoverable mistake"* → Use an [**Approval Gate**](/docs/components/approval-gate) + [**Tool Trace**](/docs/components/tool-trace)
- *"I need to show the user what the agent is thinking"* → Use a [**Plan Card**](/docs/components/plan-card) + [**Confidence Meter**](/docs/components/confidence-meter)
- *"I need to prevent users from blindly rubber-stamping approvals"* → Use an [**Automation Bias Alert**](/docs/components/automation-bias-alert) wrapping an [**Approval Gate**](/docs/components/approval-gate)
- *"I need a person to confirm an irreversible action, then show the backend's receipt"* → Use a [**Binding Approval**](/docs/components/binding-approval) + [**Transaction Receipt**](/docs/components/transaction-receipt). Those components display a signature or hash your backend produced. They do not sign.
- *"I need to roll back a sequence of 40 API calls"* → Use a [**Rollback Timeline**](/docs/components/rollback-timeline) + [**State Diff**](/docs/components/state-diff)

## Distribution model

Components are delivered via CLI copy-paste (like shadcn/ui). The source lands in your repo — you own it, you can read it, you can modify it.

```bash
npx ax-depute@latest add approval-gate
```

No lock-in. No black-box npm package the agent can't inspect.

## The AI Skill Layer

You aren't the only one building this app—your AI agent is too. Depute ships with a native **Skill Layer** built for Claude Code, Cursor, and Copilot.

When you install a component, you get the UI code for the human *and* the structural reasoning instructions for your AI agent. The skill teaches your agent exactly when to use an `ApprovalGate` versus a `RunControls` boundary, ensuring the UI your agent helps you build is the same UI your agent knows how to use.

```bash
npx ax-depute@latest init
```

This command drops a `skills/depute/SKILL.md` file into your project, automatically giving Claude Code, Cursor, or Copilot deep intelligence on how to use Depute's primitives in your specific codebase.

## Three tiers

| Tier | Components | Use case |
|------|-----------|----------|
| **Single Agent** | 7 primitives | One agent acting on behalf of a user |
| **Multi-Agent** | 11 primitives | Multiple agents coordinating, delegating, or running in parallel |
| **Compliance & Forensics** | 9 primitives | High-stakes intent, mutation visibility, and audit trails |

## Component Architecture

To help you quickly understand how to compose the library, every component in the sidebar is explicitly tagged with its architectural classification. You will see these taxonomy badges next to every component name:

- <span className={`text-xs uppercase font-mono px-1.5 py-0.5 rounded-sm border align-middle mr-1 ${taxonomyTone('Primitive')}`}>Primitive</span> A foundational, single-responsibility building block (e.g., `PlanCard`, `ApprovalGate`).
- <span className={`text-xs uppercase font-mono px-1.5 py-0.5 rounded-sm border align-middle mr-1 ${taxonomyTone('View')}`}>View</span> A compositional surface that aggregates multiple primitives into a larger macro-interface (e.g., `OrchestratorView`, `SwarmInbox`).
- <span className={`text-xs uppercase font-mono px-1.5 py-0.5 rounded-sm border align-middle mr-1 ${taxonomyTone('Control')}`}>Control</span> An operational or forensic surface used to halt, direct, or audit execution (e.g., `EscalationRouter`, `DecisionRecord`).
- <span className={`text-xs uppercase font-mono px-1.5 py-0.5 rounded-sm border align-middle mr-1 ${taxonomyTone('Pattern')}`}>Pattern</span> A highly specialized workflow wrapper designed to enforce a specific behavioral policy (e.g., `AutomationBiasAlert`, `HandoffProtocol`).

Class definitions are canonical in the [Lexicon](/docs/lexicon#primitive).

Start with Single Agent primitives. Add Multi-Agent when you need orchestration.

Components in the sidebar are ordered by **solution patterns** — the sequence you'd encounter them when building a complete agent interaction, not alphabetically.


---

---
title: Installation
description: Add Depute components to your project using the CLI.
---


## Requirements

- React 18+
- TypeScript
- CSS Modules support (standard in Vite, Next.js, CRA)

Depute is **agent-agnostic** — it works with any AI backend (OpenAI, Anthropic, LangChain, AutoGen, or custom).

## Install a component

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add approval-gate
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add approval-gate
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add approval-gate
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add approval-gate
```
  </Tab>
</Tabs>

This copies the component source files directly into `src/components/ApprovalGate/`. You own the code.

Each fetched file is checked against the release checksum before anything is written. If one does not match, or the command is interrupted, that attempt removes only the files and directories it created and restores any stylesheet it edited. Files and directories that were already in the project are left as they were, including empty directories.

On first install, shared files are also added once, next to the component directory:

- `src/types/ax-common.ts` — shared TypeScript types (`PlanStep`, `ToolCall`, `Artifact`)
- `src/types/ax-core.ts` — handoff and presented-payload types (`HandoffContext`, `PresentedPayload`)
- `src/utils/ax-receipt.ts` — canonical approval receipt, hash, and `verify`
- `src/utils/ax-a11y.tsx` — accessibility utilities used across components
- `src/styles/depute.css` — design tokens and motion. This is the one stylesheet import.

## Styles

Component CSS reads `--ax-*` tokens. Without the stylesheet, an installed component renders unstyled. The CLI copies `depute.css`, `tokens.css`, and `animations.css` into `src/styles/` and, when it finds a global stylesheet such as `src/index.css`, inserts:

```css
@import "./styles/depute.css";
```

Pass `--css src/index.css` to choose the file, or `--no-css` to skip the edit and add the import yourself. That single import is the only manual step when the CLI cannot find a stylesheet.

`--dir` moves the shared files with the components. `add run-controls --dir components/ax` writes the component to `components/ax/RunControls/` and the shared files to `components/types`, `components/utils`, and `components/styles`, then rewrites the imports so they resolve.

## Initialize the AI Skill Layer

Depute ships with a native **Skill Layer** that teaches your AI agent (Claude Code, Cursor, Copilot) how to use the components you just installed. 

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest init
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest init
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest init
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest init
```
  </Tab>
</Tabs>

This command writes `skills/depute/SKILL.md` (and its reference files) into your repository, plus `skills/depute/depute.skill.json` with the CLI version. It also installs the design tokens when `src/styles/depute.css` is not already there, and writes `src/types/ax-common.ts` and `src/utils/ax-a11y.tsx` when those files are missing. A second run skips files that already exist and does not duplicate the CSS import. The skill tells an agent how to compose the primitives. It is not a runtime dependency.

## List all components

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute list
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute list
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute list
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute list
```
  </Tab>
</Tabs>

## Install multiple components

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add plan-card
npx ax-depute@latest add tool-trace
npx ax-depute@latest add run-controls
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add plan-card
pnpm dlx ax-depute@latest add tool-trace
pnpm dlx ax-depute@latest add run-controls
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add plan-card
yarn dlx ax-depute@latest add tool-trace
yarn dlx ax-depute@latest add run-controls
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add plan-card
bunx ax-depute@latest add tool-trace
bunx ax-depute@latest add run-controls
```
  </Tab>
</Tabs>

## Shared types

All components use these core types from `src/types/ax-common.ts`:

```ts
interface PlanStep {
  id: string;
  label: string;
  status: 'pending' | 'active' | 'completed' | 'failed';
  confidence?: number;
}

interface ToolCall {
  id: string;
  name: string;
  input?: Record<string, unknown>;
  output?: Record<string, unknown>;
  status: 'pending' | 'running' | 'completed' | 'failed';
  timestamp: string;
  policyFlags?: {
    requiresApproval?: boolean;
    writesState?: boolean;
    externalAction?: boolean;
  };
}

interface Artifact {
  id: string;
  content: string;
  format: 'markdown' | 'json' | 'csv' | 'code';
  sourceStepId?: string;
  toolCallIds?: string[];
}
```

## No backend required

Optional prototyping generators are a separate install. They are not copied with a component:

```bash
npx ax-depute add mock-data
```

```tsx

const plan = generateMockPlan(4);       // 4-step agent plan
const trace = generateMockToolCalls(3); // 3 tool call entries
```

`mock-data` type-imports the components it describes. Add those components before typechecking. With `--dir`, the file is written under that directory's parent `utils/` folder and its imports point at the components you installed there.


---

---
title: Agent Roster
description: Status dashboard for scanning all active sub-agents.
badge: View
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add agent-roster
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add agent-roster
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add agent-roster
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add agent-roster
```
  </Tab>
</Tabs>

## Overview

A dense table view designed for the "Flat Swarm" orchestration model (e.g., [OpenAI's Swarm](https://github.com/openai/swarm)). It allows a human supervisor to scan 20+ concurrent workers at a glance, monitoring roll-up metrics like agent status, uptime, and token cost.


<ComponentPreview>
  <AgentRosterDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-agentroster--default" />

## Basic usage
```tsx

const mockAgents: AgentRosterItem[] = [
  {
    id: 'ag_1',
    name: 'Research Router',
    role: 'Orchestrator',
    status: 'working',
    currentTask: 'Delegating to search APIs',
    tokensUsed: 1250,
    lastActive: 'Just now'
  },
  {
    id: 'ag_2',
    name: 'Browser Node',
    role: 'Web Scraper',
    status: 'failed',
    currentTask: 'Scraping Wikipedia',
    tokensUsed: 840,
    lastActive: '5m ago'
  }
];

export function App() {
  const [selectedId, setSelectedId] = useState<string>('ag_1');

  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg">
      <AgentRoster 
        agents={mockAgents}
        selectedAgentId={selectedId}
        onAgentSelect={(agent) => setSelectedId(agent.id)}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `agents` | `AgentRosterItem[]` | `undefined` | Array of agent data objects to render as rows in the table. |
| `selectedAgentId` | `string` | `undefined` | The `id` of the currently selected agent row. |
| `onAgentSelect` | `(agent: AgentRosterItem) => void` | `undefined` | Callback fired when the user clicks on a row. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `AgentRosterItem`

```typescript

export interface AgentRosterItem {
  id: string;
  name: string;
  role: string;
  status: AgentStatus;          // 'idle' | 'working' | 'blocked' | 'failed' | 'completed'
  currentTask?: string;         // E.g., "Summarizing PDF"
  tokensUsed?: number;          // Token burn count for this session
  lastActive?: string;          // E.g., "2m ago"
}
```

## Solution Patterns
`Agent Roster` is specifically designed for flat worker pools. 
- Use it alongside **Swarm Monitor** at the top of the viewport to provide aggregate cost and error metrics for the entire fleet.
- When a user clicks a specific row (`onAgentSelect`), surface the detail view for that agent using a combination of **Plan Card**, **Tool Trace**, and **Run Controls**.

## Design rationale
**1. Data Density for Flat Swarms**  
While `Orchestrator View` is best for hierarchical workflows, `Agent Roster` is designed for "flat" worker pools (like OpenAI Swarm). It prioritizes information density over structural mapping, allowing supervisors to monitor dozens of parallel tasks without scrolling.

**2. Roll-Up Status Metrics**  
The header of the roster automatically calculates and displays summary metric pills based on the `agents` array (e.g., showing how many agents are Working, Blocked, or Failed). This provides instant situational awareness of the swarm's health.

**3. Economic Visibility**  
Agents spend money. The `tokensUsed` column surfaces economic metrics directly into the operational view, treating API spend as a first-class citizen alongside task status and uptime.


---

---
title: Approval Gate
description: Block execution and ask the user to approve a risky or high-stakes agent action.
badge: Primitive
---


Answers: [Rogue Tool Use](/docs/lexicon#rogue-tool-use), [Scoped grant](/docs/lexicon#scoped-grant), [Staged approval](/docs/lexicon#staged-approval), [L3 Supervised](/docs/lexicon#l3-supervised).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add approval-gate
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add approval-gate
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add approval-gate
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add approval-gate
```
  </Tab>
</Tabs>

## Overview

`Approval Gate` is the trust boundary primitive. It pauses agent execution and surfaces a structured approval UI before the agent crosses a trust boundary — sending emails, writing to a database, calling an external API.

The key design principle (from Stripe's SPT pattern): **approvals are scoped grants, not binary yes/no decisions**. A user approving "send emails" shouldn't be approving "send unlimited emails forever."


<ComponentPreview>
  <ApprovalGateDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-approvalgate--default" />

## Basic usage

```tsx
<ApprovalGate
  title="Send email to customer"
  description="The agent will send a follow-up to 3 recipients."
  agentReasoning="Task requires notifying stakeholders of completed analysis."
  status="pending"
  onApprove={() => agent.continue()}
  onReject={() => agent.abort()}
/>
```

## With scoped grant

```tsx
<ApprovalGate
  title="Charge payment method"
  description="The agent will charge $49.00 to the customer's card on file."
  agentReasoning="Subscription renewal detected. Auto-charge is enabled for this account."
  mode="simple"
  status="pending"
  scope={{
    target: 'Stripe API',
    resourceLimit: 4900,     // in cents
    durationSeconds: 300,    // expires in 5 minutes
  }}
  onApprove={() => agent.continue()}
  onReject={() => agent.abort()}
/>
```

## Staged mode (Preview → Confirm → Execute)

For high-risk multi-step actions, use `mode="staged"` to walk the user through three phases before execution:

```tsx
<ApprovalGate
  title="Deploy to production"
  description="The agent will deploy the current build to the production environment."
  agentReasoning="All tests passed. Deployment window is clear."
  mode="staged"
  status="pending"
  onApprove={() => agent.deploy()}
  onReject={() => agent.cancelDeploy()}
/>
```

## Async Approval Handoff (Dispatch Pattern)

If an agent executes a long-running background workflow, the human may step away from their machine. A blocking modal that nobody is watching acts indistinguishably from a hung process. 

To solve this, configure the `approvalHandoff` prop to automatically hand the approval off to a mobile device or Slack channel after a set timeout:

```tsx
<ApprovalGate
  title="Execute Production Failover"
  status={status}
  approvalHandoff={{
    timeoutMs: 30000,           // 30 seconds of inactivity triggers handoff
    fallbackBehavior: 'block',  // What happens if the async deadline passes
  }}
  onHandoff={async (ctx) => {
     await sendSmsWebhook(user.phone, ctx);
     setStatus('handoff_pending');
  }}
  handoffDeadlineMs={Date.now() + 86400000} // Backend TTL for UI rehydration sync
/>
```

When `status` shifts to `handoff_pending`, the component drops the blocking modal trap and gracefully collapses into a non-blocking ambient status card that counts down to the deadline.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Short label for the action being approved |
| `description` | `string` | — | Human-readable explanation of what the agent will do |
| `agentReasoning` | `string` | — | Why the agent thinks this action is necessary |
| `mode` | `'simple' \| 'staged'` | `'simple'` | Staged adds Preview → Confirm → Execute steps |
| `status` | `'pending' \| 'approved' \| 'rejected' \| 'handoff_pending' \| 'handoff_denied' \| 'handoff_expired'` | `'pending'` | Controls gate state |
| `scope` | `ApprovalScope` | — | Optional scoped grant (target, resourceLimit, durationSeconds) |
| `onApprove` | `() => void` | — | Called when user approves |
| `onReject` | `() => void` | — | Called when user rejects |
| `approvalHandoff` | `ApprovalHandoff` | — | Configures timeout and fallback to automatically trigger async handoff. |
| `onHandoff` | `(ctx) => Promise<void>` | — | Fires when the synchronous timeout is breached. |
| `handoffDeadlineMs` | `number` | — | Absolute unix timestamp for TTL enforcement (useful for UI sync on session restore). |

## When to use

- The agent is about to cross a trust boundary — sending an email, modifying a database record, calling an external API, executing a financial transaction
- The action is irreversible or hard to undo and a human should explicitly sign off before it runs
- You need a scoped, time-limited capability grant rather than a blanket yes/no decision
- The agent has low confidence or is operating in an unfamiliar context

## When not to use

- The agent is performing read-only operations — no approval gate is needed for purely observational tool calls
- Every single agent step requires approval — this creates approval fatigue; gate only the high-stakes boundaries
- The action is trivially reversible (e.g., drafting a note that hasn't been sent) — use `Plan Card` to show intent without requiring an explicit approval
- For irreversible actions where your backend must record the confirmation, escalate to `Binding Approval` instead

## Accessibility

- The gate renders as a `role="dialog"` region with `aria-modal="true"` when in blocking mode to trap focus appropriately
- Approve and Reject buttons have explicit `aria-label` values that include the action name (e.g., "Approve: Send email to customer")
- Status changes (approved, rejected, handoff_pending) are announced via `aria-live="assertive"` on the status region
- All scoped grant details are exposed as readable text, not just visual badges
- Keyboard navigation: `Tab` moves between Approve/Reject, `Enter`/`Space` triggers; `Escape` does not dismiss (intentional — prevents accidental closure)

## Solution Patterns

`Approval Gate` usually sits immediately after a `Plan Card` and before `Run Controls`:

```text
Plan Card → [Approval Gate] → Run Controls → Tool Trace
```
It pauses execution until a person approves, rejects, or the handoff deadline passes.

## Design rationale

**Why `scope`?** Binary approve/reject is the wrong mental model for agents. Stripe never approves an action with a simple yes/no — they issue capability grants scoped to a specific target, resource limit, and time window.

**Why `mode="staged"`?** Agent flows are state machines, not request-response cycles. `staged` mode maps to Stripe's Authorization Chain pattern: Intent → Plan → Permission Check → Execution → Audit. Each phase can fail or pause for human input.

**For irreversible or legally binding actions**, consider using [**Binding Approval**](/docs/components/binding-approval) instead. It extends the approval pattern with mandatory term acknowledgment, an `isSigning` freeze state, and signer identity capture. See the [decision rule](/docs/components/binding-approval#design-rationale) for when to escalate.

---

---
title: Artifact Card
description: Render the final output of an agentic workflow with export and provenance tracing.
badge: Primitive
---


Answers: [Provenance](/docs/lexicon#provenance), [L1 Human-Led](/docs/lexicon#l1-human-led).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add artifact-card
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add artifact-card
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add artifact-card
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add artifact-card
```
  </Tab>
</Tabs>

## Overview

The agent's "receipt" of work completed. It renders the final output alongside crucial provenance data: precisely which plan step and tool calls generated it. It also provides integrated export options.


<ComponentPreview>
  <ArtifactCardDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-artifactcard--default" />

## Basic usage

```tsx
<Artifact Card
  artifact={myArtifactData}
/>
```

## With mock data

Because `Artifact Card` requires a full artifact object to render, here is an example of what that object looks like:

```tsx

const mockArtifact: Artifact = {
  id: 'art_123',
  type: 'code',
  title: 'Database Schema Migration',
  createdAt: new Date(),
  content: 'CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(50));',
  sourceStepId: 'step_2',
  toolCallIds: ['call_456']
};

export function App() {
  return (
    <Artifact Card 
      artifact={mockArtifact} 
      exportFormats={['markdown', 'sql']} 
      onExport={(format) => console.log(`Exporting as ${format}`)}
      showPreview={true}
    />
  );
}
```

## Streaming state

When content is still arriving from a live backend, pass `isStreaming`. Adds `data-streaming="true"` to the root — no built-in animation; the host product styles it:

```tsx
<ArtifactCard
  artifact={partialArtifact}
  showPreview
  isStreaming={agent.isStreaming}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `artifact` | `Artifact` | **Required** | The artifact object to display (contains `title`, `type`, `content`, etc.). |
| `exportFormats` | `ExportFormat[]` | `undefined` | Array of available export formats to show as action buttons (e.g., `'markdown'`, `'json'`). |
| `onExport` | `(format: ExportFormat) => void` | `undefined` | Callback fired when an export button is clicked. |
| `showPreview` | `boolean` | `true` | Whether to render a preview of the artifact's `content` inside the card. |
| `maxPreviewHeight` | `string` | `'24rem'` | Maximum height of the content preview area before an internal scrollbar appears. |
| `isStreaming` | `boolean` | `false` | Signals that content is still arriving. Adds `data-streaming="true"` to the root element — no built-in animation; style via CSS. |

## When to use

- The agent has completed a workflow and produced a discrete, shareable output (document, code, report, data) that the user needs to review, export, or act on
- Provenance matters — the user should be able to trace the output back to the specific plan step and tool calls that produced it
- The output type varies across runs (markdown, JSON, code, SQL) and you need a single component that handles all of them

## When not to use

- The agent's output is a direct action that has already been executed (e.g., an email sent, a file deployed) — use `Transaction Receipt` or `Decision Record` instead
- The output is a streaming partial — wait for completion or use `isStreaming` only as a transitional state, not a permanent one
- You only need to display a success/failure confirmation with no shareable content — a simple status notification is less heavyweight

## Accessibility

- The artifact content area is a `<section>` with `aria-label` derived from the artifact title (e.g., "Artifact: Database Schema Migration")
- Export buttons have explicit `aria-label` values that include the format (e.g., "Export as Markdown")
- Streaming content is announced via `aria-live="polite"` so screen readers track new content arriving without interruption
- Code content is rendered inside `<pre><code>` with appropriate `role="region"` and `aria-label="Code output"` for keyboard traversal
- Provenance metadata (step ID, tool calls) is rendered as readable text, not hidden behind hover states

## Solution Patterns

`Artifact Card` is the grand finale of a single-agent execution sequence:

```text
Plan Card → Approval Gate → Run Controls → Tool Trace → [Artifact Card]
```
Once the agent finishes its work, the trace concludes and this component is rendered to display the final, tangible output.

## Design rationale

**Why the "Receipt" Pattern?** In traditional SaaS, the UI *is* the application. In agentic software, the UI is often just the exhaust of the application. The `Artifact Card` treats the final output as a primary, shareable asset. 

**Why verifiable provenance?** Trust requires auditability. The `sourceStepId` and `toolCallIds` metadata fields visually connect the final artifact back to the exact operations that produced it, preventing "hallucinated outputs" from passing without scrutiny.

**Why focus on actionability?** Agents excel at generation, but humans excel at distribution. Integrated `exportFormats` acknowledge that the artifact's lifecycle doesn't end in the chat UI—it needs to be pulled into PRs, Slack messages, or Google Docs.


---

---
title: Automation Bias Alert
description: Counteract "rubber-stamping" behavior by introducing deliberate friction when passive oversight is detected.
badge: Pattern
---


Answers: [Automation Bias](/docs/lexicon#automation-bias), [L3 Supervised](/docs/lexicon#l3-supervised).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add automation-bias-alert
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add automation-bias-alert
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add automation-bias-alert
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add automation-bias-alert
```
  </Tab>
</Tabs>

## Overview

> [!NOTE]
> `AutomationBiasAlert` is not a standalone UI module. It is a **policy wrapper pattern** designed to sit exclusively over existing approval boundaries.

Automation bias occurs when humans over-trust automated systems, leading to passive oversight or "rubber-stamping" of errors. This wrapper counteracts this by monitoring approval patterns and introducing a mandatory review pause when bypass behavior is detected.

<ComponentPreview>
  <AutomationBiasAlertDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-automationbiasalert--default" />

## Basic usage

The component works as a wrapper around interactive oversight elements (like `ApprovalGate`). It uses the `useAutomationBias` hook to monitor events and trigger the alert.

```tsx

function MyOversightUI() {
  const { isAlertTriggered, recordAction, dismissAlert } = useAutomationBias();

  const handleAction = (action: 'approved' | 'rejected') => {
    // Record the action to update internal bias heuristics
    recordAction(action);
    executeAction(action);
  };

  return (
    <AutomationBiasAlert 
      isActive={isAlertTriggered} 
      onAcknowledge={dismissAlert}
      actionName="this deployment"
    >
      <button onClick={() => handleAction('approved')}>Approve</button>
    </AutomationBiasAlert>
  );
}
```

## With custom thresholds

You can tune the sensitivity of the bias detection by passing custom thresholds to the hook.

```tsx
const { isAlertTriggered, recordAction, dismissAlert } = useAutomationBias({
  consecutiveApprovals: 3,   // Alert after 3 consecutive approvals
  minApprovalTimeMs: 2500,  // Require 2.5s review time
  approvalRateCeiling: 0.8  // Alert if approval rate > 80%
});
```

## Detection Heuristics

The `useAutomationBias` hook monitors three specific behavioral signals:

1. **Consecutive Approvals**: Detecting long streaks of approvals without a single rejection or modification.
2. **Approval Velocity**: Measuring the time between the UI rendering and the user clicking "Approve". If it's faster than a human could realistically review the content, it triggers friction.
3. **Session Ceilings**: Monitoring the overall approval-to-rejection ratio. If a user approves >90% of actions over a long period, it indicates potential over-trust.

## Props

### AutomationBiasAlert

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `children` | `ReactNode` | - | The interactive UI to be wrapped/protected. |
| `isActive` | `boolean` | `false` | Whether the friction overlay should be displayed. |
| `onAcknowledge` | `() => void` | - | Callback when the user acknowledges the alert after the pause. |
| `actionName` | `string` | `'this action'` | The name of the action being gated, used in the alert message. |
| `className` | `string` | - | Optional custom styling for the container. |

### useAutomationBias

| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `consecutiveApprovals` | `number` | `5` | Trigger alert after this many consecutive approvals. |
| `minApprovalTimeMs` | `number` | `1500` | Minimum ms required for a "valid" review. |
| `approvalRateCeiling` | `number` | `0.9` | Trigger alert if overall approval rate exceeds this % (0-1). |

## When to use

- Users are approving high-stakes agent actions in rapid succession — financial transactions, code deployments, medical recommendations
- You have evidence or suspicion of rubber-stamping behavior in your product (high approval rates, very short review times)
- The consequence of a false positive (approving a bad action) significantly outweighs the friction cost of a pause
- You are operating a swarm inbox or batch approval queue where velocity bias is structurally likely

## When not to use

- The approval flow is for low-stakes reversible actions — introducing friction here erodes trust in the friction itself, making it ineffective when it matters
- Users have no ability to meaningfully review the content before approving (e.g., the action details aren't surfaced) — fix the information architecture first
- You are using it as a substitute for actually improving the clarity of the approval interface

## Accessibility

- The friction overlay renders as a `role="alertdialog"` with `aria-modal="true"` to capture focus during the mandatory pause
- The countdown timer is announced as a live region (`aria-live="polite"`) so screen reader users are aware of the pause duration
- The acknowledge button is focussed automatically when the overlay appears
- The alert message includes explicit text explaining why the pause was triggered — not just a visual warning icon
- Color (amber/red) is never the sole indicator of the alert state; an icon and text label always accompany it

## Solution Patterns

### The Interceptor Layer
`AutomationBiasAlert` is an **interceptor layer**. It should wrap components that have `onApprove` or `onProceed` callbacks:

```text
Plan Card → [Automation Bias Alert → Approval Gate] → Run Controls
```

It monitors the final interaction point before an irreversible action is executed.

### Progressive Friction against Approval Fatigue
In high-throughput environments (like a `SwarmInbox` queue), users experience "velocity bias" — they approve faster as the queue grows, actively degrading their scrutiny. You can dynamically scale the friction thresholds to combat this cognitive failure.

```tsx
// Instead of static thresholds, progressively harden them based on state
const consecutiveThreshold = approvalStreak >= 5 ? 2 : 5;
const requiredPauseMs = approvalStreak >= 5 ? 5000 : 1500;

const { isAlertTriggered, recordAction, dismissAlert } = useAutomationBias({
  consecutiveApprovals: consecutiveThreshold,
  minApprovalTimeMs: requiredPauseMs,
});
```
*If a user approves 5 items in a row without rejection, the enforced pause climbs from 1.5 seconds to 5 seconds. This explicitly breaks their automatic rhythm.*

## Design rationale

**Why friction?**
When an interface is too smooth, users stop paying attention. They settle into a rhythm of clicking — "rubber-stamping" — and critical details slip past them unreviewed.

**Why does familiarity increase errors?**
The more a user feels "in control" of an AI system, the more likely they are to blindly accept its suggestions. Research by [Shalaleh Rismani](https://shalalehrismani.com/), an AI safety researcher at McGill and Mila, confirms this: users who better understood an AI writing assistant trusted it more — and accepted significantly more errors as a result. More transparency doesn't always lead to better oversight; it often leads to more trust and less scrutiny.

**Why a mandatory pause?**
`AutomationBiasAlert` detects when repeated approvals suggest a user has stopped actually reviewing — and introduces a pause to break the pattern. The discomfort is the point.

- **Non-blocking**: It doesn't prevent the user from approving, but it breaks the physical rhythm of repetitive clicking.
- **Contextual**: It only appears when behavioral patterns suggest the human is no longer actually reviewing the data.
- **Safety-Critical**: Essential for agents performing financial transactions, medical evaluations, or high-consequence code deployments.


---

---
title: Binding Approval
description: High-stakes intent gate. Displays a signature your backend supplies.
badge: Primitive
---


Answers: [Binding Approval](/docs/lexicon#binding-approval), [Responsibility Diffusion](/docs/lexicon#responsibility-diffusion).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add binding-approval
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add binding-approval
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add binding-approval
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add binding-approval
```
  </Tab>
</Tabs>

## Overview

Unlike a standard `ApprovalGate` used for day-to-day coordination, `BindingApproval` provides a heavy-duty friction boundary for irreversible or financial actions. It forces explicit acknowledgment of terms and implements a multi-phase `isSigning` visual state.

`BindingApproval` does not sign, hash, or talk to a ledger. Pass `signature` and `hash` when your backend has already produced them, and pass `onVerify` if the app should check that proof. The component only displays those values.

<ComponentPreview>
  <BindingApprovalDemo />
</ComponentPreview>

<StorybookEmbed story="v2-compliance-forensics-bindingapproval--default" />

## Basic Usage

```tsx
<BindingApproval
  title="Wire Transfer Authorization"
  description="Execute a $5,000 wire transfer."
  impactStatement="$5,000.00 will be transferred immediately."
  signerIdentity="alice@company.com"
  terms={[
    { id: 't1', text: 'I authorize the transfer of $5,000.00', acknowledged: false },
    { id: 't2', text: 'I understand this action is irreversible', acknowledged: false },
  ]}
  signature={backendSignature}
  hash={backendHash}
  onSign={() => backend.recordIntent()}
  onVerify={(proof) => backend.verify(proof)}
/>
```

## Solution Patterns

This primitive replaces `ApprovalGate` in high-stakes nodes. The internal state expects a clear distinction between `reviewing` and `signing`, where `isSigning: true` disables interaction and renders a deterministic loading state while your backend records the intent.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Title of the binding action |
| `description` | `string` | — | Detailed explanation of the action |
| `impactStatement` | `string` | — | Estimated impact (e.g., "$5,000 will be transferred") |
| `status` | `'reviewing' \| 'signing' \| 'signed' \| 'rejected' \| 'expired'` | `'reviewing'` | Current status |
| `terms` | `BindingTerm[]` | — | Terms that must be acknowledged |
| `requireAllTerms` | `boolean` | `true` | Require all terms acknowledged to sign |
| `isSigning` | `boolean` | `false` | Toggles the active signing visual state |
| `signerIdentity` | `string` | — | Identity of the approver |
| `timeoutSeconds` | `number` | — | Signing window timeout |
| `onSign` | `() => void` | — | Called when the user confirms. Your backend records the intent. |
| `onReject` | `(reason?: string) => void` | — | Called when rejected |
| `signature` | `string` | — | Signature string from your backend. Display only. |
| `hash` | `string` | — | Hash string from your backend. Display only. |
| `onVerify` | `(proof) => void` | — | Your app's check for the displayed signature and hash. |

## Design rationale

**When to use `ApprovalGate` vs `BindingApproval`:**

| | `ApprovalGate` | `BindingApproval` |
|---|---|---|
| **Use when** | The action is reversible, operational, or low-to-moderate stakes | The action is irreversible or financial, and your backend will record the intent |
| **Friction level** | Quick scoped grant — review and approve | Mandatory term acknowledgment + signing flow |
| **State model** | `pending → approved / rejected` | `reviewing → signing → signed / rejected` |
| **Examples** | "Send this email", "Deploy to staging", "Run this query" | "Wire $50k", "Sign this contract", "Commit to ledger" |

Use `ApprovalGate` by default. Escalate to `BindingApproval` only when the action is irreversible and your backend must record who confirmed it.

**Why `isSigning`?** Normal approvals execute instantly. High-stakes approvals often wait on a backend round trip. `isSigning` freezes the component so the user cannot submit twice. The component still does not produce a signature.

**Why explicit terms?** Click-fatigue trains users to blindly click "Approve." Forcing the user to manually acknowledge explicit terms (e.g. "This action cannot be undone") breaks automatic behavior and captures verifiable intent.


---

---
title: Branch Controls
description: Scoped execution controls for a single branch of the swarm.
badge: Control
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add branch-controls
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add branch-controls
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add branch-controls
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add branch-controls
```
  </Tab>
</Tabs>

## Overview

While `Run Controls` operates on a single agent, and `Swarm Monitor` can kill the entire fleet, `Branch Controls` operates on a specific *sub-tree*. It allows a supervisor to pause or quarantine a troubled workflow branch without freezing the rest of the healthy swarm.


<ComponentPreview>
  <BranchControlsDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-branchcontrols--default" />

## Basic usage
```tsx

export function App() {
  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-sm">
      <BranchControls 
        branchName="Data Scraping Pipeline"
        status="running"
        onPause={() => console.log('Pausing branch')}
        onResume={() => console.log('Resuming branch')}
        onQuarantine={() => console.log('Quarantining branch')}
        onCancel={() => console.log('Canceling branch')}
        onThrottle={() => console.log('Throttling branch speed')}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `branchName` | `string` | **Required** | The display name of the organizational branch or sub-tree. |
| `status` | `'running' \| 'paused' \| 'quarantined'` | **Required** | The current execution state of this specific branch. |
| `onPause` | `() => void` | `undefined` | Callback fired to halt execution on this branch. |
| `onResume` | `() => void` | `undefined` | Callback fired to resume execution on this branch. |
| `onQuarantine` | `() => void` | `undefined` | Callback fired to isolate this branch (e.g., cut off its network/API access). |
| `onCancel` | `() => void` | `undefined` | Callback fired to permanently terminate all agents in this branch. |
| `onThrottle` | `() => void` | `undefined` | Callback fired to artificially slow down the loop speed of this branch. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Solution Patterns

`Branch Controls` is applied to sub-trees within an `Orchestrator View`:

```text
Orchestrator View → Tree Node → [Branch Controls]
```
Rather than stopping the entire swarm, it pauses a specific branch of execution.

## Design rationale
**1. Surgical Intervention**  
In a 20-agent swarm, one agent hitting a bad API shouldn't crash the other 19. `Branch Controls` provides the surgical tools needed to manage a complex hierarchical system. If a "Scraper" branch is misbehaving, you can pause it, adjust the scraper prompt, and resume it, all while the "Summary" branch continues to process the data already collected.

**2. The Quarantine Concept**  
Unlike "Pause" (which stops the agent from reasoning), "Quarantine" allows the branch to continue thinking but revokes its Write/Execute permissions. This is a critical debugging state: it lets the human observe *what the agent wants to do next* without actually letting it do it.

**3. State-Driven UI**  
The visible buttons dynamically swap based on the `status` prop. If the branch is `running`, the user sees Pause and Quarantine. If it's `paused`, they see Resume. This prevents the supervisor from clicking invalid state transitions during a fast-moving escalation.


---

---
title: Budget Meter
description: Visual gauge showing session budget vs. burn rate.
badge: Primitive
---


Answers: [Budget](/docs/lexicon#budget).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add budget-meter
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add budget-meter
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add budget-meter
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add budget-meter
```
  </Tab>
</Tabs>

## Overview

Delegation requires guardrails. Instead of blocking every action, `Budget Meter` allows users to grant agents an explicit budget (API tokens, currency, or API call limits) and tracks the real-time burn rate. It automatically calculates severity thresholds to warn users before the budget is exhausted.

<ComponentPreview>
  <BudgetMeterDemo />
</ComponentPreview>

<StorybookEmbed story="v2-compliance-forensics-budgetmeter--default" />

## Basic Usage

```tsx
<BudgetMeter
  label="Session Tokens"
  used={45000}
  total={50000}
  unit="tokens"
  burnRate={1200}
/>
```

## Solution Patterns

Integrate `BudgetMeter` directly into a `DelegationGate` prior to spawning a new agent to enforce explicit limits, or embed it persistently within `RunControls` alongside pause/stop actions to maintain situational awareness of a running swarm.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | — | Human-readable label |
| `spent` | `number` | — | Current amount consumed |
| `limit` | `number` | — | Maximum budget allowance |
| `unit` | `'currency' \| 'tokens' \| 'api-calls' \| 'compute' \| 'custom'` | `'tokens'` | Unit type |
| `burnRate` | `number` | — | Current burn rate per minute |
| `estimatedTimeRemaining` | `string` | — | Human-readable time remaining |
| `elevatedThreshold` | `number` | `60` | Percentage to trigger elevated state |
| `criticalThreshold` | `number` | `85` | Percentage to trigger critical state |
| `compact` | `boolean` | `false` | Render inline variant |

## Design rationale

**Why proportional thresholds?** Raw numbers (e.g., "45,000 tokens") are meaningless without context. Auto-calculating elevated (>60%) and critical (>85%) severity colors translates abstract numbers into actionable visual urgency.


---

---
title: Capability Matrix
description: Permission inspector showing allowed and denied capabilities.
badge: Primitive
---


Answers: [Capability](/docs/lexicon#capability).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add capability-matrix
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add capability-matrix
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add capability-matrix
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add capability-matrix
```
  </Tab>
</Tabs>

## Overview

`Capability Matrix` is the "Agent Handshake." As products explicitly declare their tools to agents via frameworks like WebMCP, humans need to see that exact programmatic contract. This component visualizes what an agent is capable of doing in the current specific operating context.

<ComponentPreview>
  <CapabilityMatrixDemo />
</ComponentPreview>

<StorybookEmbed story="v2-compliance-forensics-capabilitymatrix--default" />

## Basic Usage

```tsx
<CapabilityMatrix
  title="Agent Permissions"
  agentId="sysadmin-bot-01"
  capabilities={[
    { name: 'logs.read', description: 'Read system logs', permission: 'full', category: 'Observability' },
    { name: 'services.restart', permission: 'conditional', condition: 'requires 2FA', category: 'Operations' },
    { name: 'db.drop', description: 'Drop database tables', permission: 'none', category: 'Storage' },
  ]}
/>
```

## Solution Patterns

Render `CapabilityMatrix` inside a `DelegationGate` when an agent is spawned, ensuring the user understands the absolute bounds of the agent's authority before letting it execute.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Title of the matrix |
| `agentId` | `string` | — | Agent identity label |
| `capabilities` | `Capability[]` | — | List of defined permissions |
| `groupByCategory` | `boolean` | `true` | Group capabilities by category |
| `highlightDenied` | `boolean` | `true` | Emphasize denied/none permissions |

## Design rationale

**Why `highlightDenied`?** In security, knowing what an agent *cannot* do is often more important than what it can. Visually elevating explicit denials (e.g., "Write to Production: Denied") builds trust that guardrails are actively in place.


---

---
title: Confidence Meter
description: Show how confident the agent is in its next step.
badge: Primitive
---


Answers: [Automation Bias](/docs/lexicon#automation-bias), [Hallucinated Planning](/docs/lexicon#hallucinated-planning).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add confidence-meter
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add confidence-meter
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add confidence-meter
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add confidence-meter
```
  </Tab>
</Tabs>

## Overview

Displays an agent's confidence score with optional reasoning. Supports a full `meter` display (a horizontal bar) as well as a compact `badge` display for tight spaces like roster rows in `Subagent Card`.


<ComponentPreview>
  <ConfidenceMeterDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-confidencemeter--default" />

## Basic usage

```tsx
<Confidence Meter
  value={85}
  showLabel={true}
  showValue={true}
  reasoning="I have successfully retrieved the user's billing history."
/>
```

## Compact Badge Display

For tight UI spaces like tables or agent rosters, use the `badge` variant.

```tsx
<Confidence Meter
  value={42}
  display="badge"
  size="sm"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | `undefined` | Confidence score from 0-100. If omitted, meter shows an indeterminate pulsing state. |
| `display` | `'meter' \| 'badge'` | `'meter'` | Structural variant: full horizontal bar (`meter`) or a compact inline pill (`badge`). |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the component. |
| `showValue` | `boolean` | `true` | Whether to show the exact numeric percentage. |
| `showLabel` | `boolean` | `true` | Whether to display a textual confidence category (e.g., "High", "Medium", "Low"). |
| `reasoning` | `string` | `undefined` | An optional explanation from the agent justifying its confidence score. |
| `animate` | `boolean` | `true` | Whether to animate the bar filling and color transitions when the value changes. |

## When to use

- The agent's confidence in its next action is meaningful signal — e.g., before an `Approval Gate` where confidence should influence the human's decision
- The agent is operating in a domain with variable accuracy (medical, legal, financial) where uncertainty carries real stakes
- You want to preemptively surface a human review trigger: if confidence drops below a threshold, escalate automatically

## When not to use

- Your agent backend doesn't produce calibrated confidence scores — displaying a fabricated or uncalibrated number is actively misleading and erodes trust
- The operation is routine and fully reversible — injecting a confidence signal for low-stakes actions adds noise without value
- The agent has already completed the action — `Confidence Meter` communicates intent before execution, not retrospective certainty

## Accessibility

- The meter renders as `<meter>` (native HTML) with `min`, `max`, and `value` attributes set, giving screen readers built-in percentage readout
- The confidence label (High / Medium / Low) is always present as visible text, not conveyed through color alone
- Color differentiation (green / amber / red) meets WCAG 3:1 minimum contrast ratio against the background
- Reasoning text is rendered as a visible `<p>` and not hidden behind a tooltip — no hover-only content
- Badge variant includes `aria-label="Confidence: 42%"` for screen reader clarity in dense layouts

## Solution Patterns

`Confidence Meter` is typically evaluated continuously during an agent's runtime, often surfaced right before an `Approval Gate`:

```text
Plan Card → [Confidence Meter] → Approval Gate → Run Controls
```
If confidence drops below a specified threshold, the flow can be automatically paused for human review.

## Design rationale

**Why quantitative trust signaling?** Humans struggle to calibrate trust in LLMs. Without a signal, every agent response carries the same implicit weight — whether the model is 95% confident or guessing. Surfacing a score *before* execution creates a moment of deliberate comparison: the human sees the number, and that number reframes how they read the output. A 58% confidence on a financial recommendation is a different document than a 96% one.

**Why the `reasoning` prop?** A score without rationale is still partially opaque. An agent that outputs `58%` with no explanation is almost as unhelpful as no score at all. The `reasoning` prop gives the agent space to surface what it's uncertain about — missing context, competing interpretations, ambiguous inputs. That explanation is what makes the confidence score actionable rather than decorative, and what gives the human something to actually verify.


---

---
title: Decision Record
description: Immutable visual receipt of a human approval decision to counteract Responsibility Diffusion. Who approved, why, and under what policy.
badge: Control
---


Answers: who approved — [Responsibility Diffusion](/docs/lexicon#responsibility-diffusion), [Decision Record](/docs/lexicon#decision-record), [Who approved](/docs/lexicon#who-approved), [Audit Triad](/docs/lexicon#audit-triad), [L3 Supervised](/docs/lexicon#l3-supervised).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add decision-record
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add decision-record
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add decision-record
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add decision-record
```
  </Tab>
</Tabs>

## The Audit Triad

`DecisionRecord` is one of three audit-layer components. Each captures a different moment in the accountability chain:

| Component | Scope | Records | Question it answers |
|-----------|-------|---------|---------------------|
| **Decision Record** | Per-approval | Who approved, why, and under what policy | *"Who authorized this?"* |
| [**Transaction Receipt**](/docs/components/transaction-receipt) | Per-action | What the machine did, with verification hash | *"What actually happened?"* |
| [**Session Overview**](/docs/components/session-overview) | Per-session | Semantic rollup of everything the agent touched | *"What was the total blast radius?"* |

Use all three together for full audit coverage: `DecisionRecord` captures the human side, `TransactionReceipt` captures the machine side, and `SessionOverview` captures the session-level summary.

## Basic usage

Use `<DecisionRecord />` to log a human's active oversight of an agentic workflow. While the agent executes actions, you need an immutable record of *who* authorized it and *why*.


<DecisionRecordDemo />

```tsx

export function AuditLog() {
  return (
    <DecisionRecord
      decision="approved"
      approver={{
        name: "Alice Engineering",
        role: "DevOps",
        timestamp: new Date()
      }}
      agentContext={{
        intent: "Restart production API gateway",
        policyInvoked: "INFRA-001"
      }}
      humanReasoning="Verified metrics on Datadog. Latency spike requires restart."
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `decision` | `'approved' \| 'rejected' \| 'modified'` | — | The final human decision |
| `approver` | `{ name: string, role?: string, timestamp: Date \| string }` | — | The human who made the decision |
| `agentContext` | `{ intent: string, policyInvoked?: string }` | — | The agent intent and policy at the time |
| `humanReasoning` | `string` | — | Optional human reasoning for the decision |

The component intentionally requires strict object shapes to ensure the audit log is semantically complete for role-based access control (RBAC) environments.

## Solution Patterns

### The Responsibility Terminal
Embed the `DecisionRecord` at the end of every `ApprovalGate` flow. If the user clicks "Approve", the final screen rendered should be the immutable receipt.

```text
Action Propsed → [Approval Gate] → (Approves) → [Action Executes] → [Decision Record]
```

This closes the "Execution Amnesia" loop by confirming to the user that their identity is now bound to the output.

## Design rationale

**Why not just use `TransactionReceipt`?**
A `TransactionReceipt` logs what the *machine* did (e.g., "Deployed smart contract `0x123` at block `8841`"). A `DecisionRecord` logs what the *human* did (e.g., "Alice approved the contract deployment because the Q/A tests passed"). 

In enterprise and high-compliance environments, "Responsibility Diffusion" happens when humans blindly click approve because they aren't explicitly reminded that their identity is being audited. By forcing an explicit, formal, visual receipt of *their* decision, we heighten their scrutiny on the next request.


---

---
title: Delegation Gate
description: Approval surface for spawning a new autonomous sub-agent.
badge: Control
---


Answers: [Mandate](/docs/lexicon#mandate), [L2 Collaborative](/docs/lexicon#l2-collaborative).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add delegation-gate
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add delegation-gate
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add delegation-gate
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add delegation-gate
```
  </Tab>
</Tabs>

## Overview

A specialized approval surface explicitly designed for the creation of new autonomous entities. It surfaces the proposed agent's mandate, tool constraints, and forecasted economic cost before the agent is allowed to execute.


<ComponentPreview>
  <DelegationGateDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-delegationgate--default" />

## Basic usage
```tsx

export function App() {
  const proposedAgent = {
    role: 'Financial Analyst',
    mandate: 'Read Q3 earnings reports and extract revenue metrics into a CSV.',
    allowedTools: ['read_file', 'write_csv'],
    maxDepth: 10,
    estimatedTokens: 15000,
    estimatedCost: '$0.25'
  };

  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-lg">
      <DelegationGate 
        requestingAgent="Main Orchestrator"
        proposedSubagent={proposedAgent}
        onApprove={() => console.log('Sub-agent authorized')}
        onDeny={() => console.log('Spawn request denied')}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `requestingAgent` | `string` | **Required** | The name or ID of the parent agent requesting to spawn the child. |
| `proposedSubagent` | `Object` | **Required** | Details about the sub-agent being proposed (see Type below). |
| `onApprove` | `() => void` | **Required** | Callback fired when the user authorizes the creation of the sub-agent. |
| `onDeny` | `() => void` | **Required** | Callback fired when the user rejects the creation of the sub-agent. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `ProposedSubagent`

```typescript
export interface ProposedSubagent {
  role: string;             // Display role, e.g., "Financial Analyst"
  mandate: string;          // The specific instructions given to the new agent
  allowedTools?: string[];  // Sandbox constraints: which tools it can access
  maxDepth?: number;        // Maximum number of reasoning steps before timeout
  estimatedTokens: number;  // Forecasted token burn
  estimatedCost: string;    // Forecasted USD cost, e.g., "$0.25"
}
```

## Solution Patterns

## Solution Patterns

`Delegation Gate` intercepts an orchestrator right before it spawns a new worker. 

**Authorization is not just approval.**
Because approving an agent is an authorization of *autonomy* (not just a single action), it represents a significantly higher-stakes decision. We strongly recommend wrapping this in `AutomationBiasAlert` to prevent "rubber-stamping" of agent authorizations:

```text
Orchestrator View → [AutomationBiasAlert → Delegation Gate] → Subagent spawned
```

It ensures human oversight before compute is multiplied.

## Design rationale
**1. Intent vs. Autonomy**  
`Approval Gate` (v0) is used before an agent takes a specific, discrete action. `Delegation Gate` (v1) is used before an agent *creates another agent*. Approving an action validates intent; approving an agent authorizes capacity. The UI reflects this shift from operational to structural decision-making.

**2. The "Box" Model (Sandboxing)**  
When humans manage humans, they create boundaries via job descriptions. When humans manage AI, they create boundaries via constraints. The `allowedTools` and `maxDepth` fields explicitly visualize the "sandbox" the new agent will be trapped in, increasing human trust that the sub-agent cannot escape its mandate.

**3. Forecasted Economics**  
Agents aren't just code; they are active compute consumers. Displaying `estimatedCost` directly on the spawn request shifts the UI from purely operational to financial, preventing "infinite loop" surprises on the monthly bill.


---

---
title: Escalation Router
description: Alert feed for sub-agent failures with routing options.
badge: Control
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add escalation-router
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add escalation-router
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add escalation-router
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add escalation-router
```
  </Tab>
</Tabs>

## Overview

A high-severity intervention surface. When an agent critically fails (e.g., gets stuck in a loop, hits a rate limit, or crashes), `Escalation Router` surfaces the error trace and provides the human supervisor with three deterministic resolution paths: Retry, Reassign, or Cancel.


<ComponentPreview>
  <EscalationRouterDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-escalationrouter--default" />

## Basic usage
```tsx

export function App() {
  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-lg">
      <EscalationRouter 
        failedAgent="Data Processor Node"
        branchId="branch_7A"
        errorSummary="Database Timeout: Allowed duration exceeded (3000ms)"
        errorTrace="Error: Connection refused at pg_connect() \n at query (db.js:42:12)"
        recommendation="retry"
        onRetry={() => console.log('Retrying task on same agent...')}
        onReassign={() => console.log('Opening reassignment modal...')}
        onCancelBranch={() => console.log('Killing branch_7A')}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `failedAgent` | `string` | **Required** | The name or ID of the agent that encountered the critical error. |
| `errorSummary` | `string` | **Required** | A human-readable, single-sentence summary of what went wrong. |
| `onRetry` | `() => void` | **Required** | Callback fired when the human chooses to restart the failed task on the same agent. |
| `onReassign` | `() => void` | **Required** | Callback fired when the human chooses to route the task to a different agent. |
| `onCancelBranch` | `() => void` | **Required** | Callback fired to terminate the task and explicitly fail the workflow branch. |
| `branchId` | `string` | `undefined` | The specific execution branch or thread ID associated with the task. |
| `errorTrace` | `string` | `undefined` | The raw system error, API response, or stack trace (rendered in a dark-themed code block). |
| `recommendation` | `'retry' \| 'reassign' \| 'cancel'` | `undefined` | The orchestrator's suggestion for how the human should resolve the issue (highlights the primary button). |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Solution Patterns

`Escalation Router` surfaces hard blockers from deep within the swarm up to the human supervisor:

```text
Failed Subagent → [Escalation Router] → Human Override
```
It allows the user to re-route or manually resolve the blocker.

## Design rationale
**1. The "Three-Way Intersection"**  
When autonomous systems fail, they often just stop or loop infinitely. `Escalation Router` forces the system to pause and present a clear three-way intersection to the human: Try Again (transient errors), Give to Someone Else (capability errors), or Give Up (bad intent/unsolvable).

**2. Visual Urgency**  
This is one of the few components in the library that uses aggressive Red styling by default. It acts as an `alertdialog`, breaking the user out of passive monitoring and demanding active resolution.

**3. Orchestrator Recommendations**  
If the orchestrator is intelligent enough to know *why* an agent failed (e.g., a 429 Rate Limit), it can use the `recommendation` prop. This highlights the "Retry" button as the primary action, turning the human into a simple "Approve" clicker rather than forcing them to diagnose the trace themselves.


---

---
title: Handoff Protocol
description: Structured comprehension UI for context transfers between agents.
badge: Pattern
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add handoff-protocol
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add handoff-protocol
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add handoff-protocol
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add handoff-protocol
```
  </Tab>
</Tabs>

## Overview

A "Comprehension UI" that visualizes the transfer of state between two agents (or an agent and a human). It clearly delineates the source, destination, assigned goal, and the exact payload being transferred.


<ComponentPreview>
  <HandoffProtocolDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-handoffprotocol--default" />

## Basic usage
```tsx

export function App() {
  const payload = [
    { label: 'Scraped URLs', value: '42 pages processed' },
    { label: 'Extraction Rule', value: 'Find pricing tables' },
    { label: 'Cost Incurred', value: '$0.45' }
  ];

  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-lg">
      <HandoffProtocol 
        sourceAgent="Web Scraper"
        destinationAgent="Data Synthesizer"
        goal="Extract pricing tiers into standardized JSON structure."
        summary="I have crawled the target domain and identified 42 pages containing tabular data that likely represent pricing structures."
        payload={payload}
        nextRequest="Please parse the HTML tables in this payload and ensure the resulting JSON matches the ProductTier schema."
        canIntercept={true}
        onAccept={() => console.log('Handoff proceeds')}
        onIntercept={() => console.log('Human takes over')}
        onCancel={() => console.log('Handoff cancelled')}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `sourceAgent` | `string` | **Required** | The name or ID of the agent sending the context. |
| `destinationAgent` | `string` | **Required** | The name or ID of the agent (or human) receiving the context. |
| `goal` | `string` | **Required** | The high-level intent behind this specific transfer of control. |
| `summary` | `string` | **Required** | A readable description from the source agent of what has been accomplished so far. |
| `payload` | `HandoffPayloadItem[]` | `undefined` | Key-value pairs representing the structured data being passed. |
| `nextRequest` | `string` | `undefined` | Explicit instructions from the source agent to the destination agent. |
| `canIntercept` | `boolean` | `false` | If true, renders the action buttons allowing the human to Accept, Intercept, or Cancel the transfer. |
| `onAccept` | `() => void` | `undefined` | Callback fired when the user allows the handoff to proceed. |
| `onIntercept` | `() => void` | `undefined` | Callback fired when the user decides to take over the task manually or reroute it. |
| `onCancel` | `() => void` | `undefined` | Callback fired when the user cancels the handoff entirely. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `HandoffPayloadItem`

```typescript
export interface HandoffPayloadItem {
  label: string;
  value: string;
}
```

## Solution Patterns

`Handoff Protocol` sits securely between two agents when ownership or state transfers:

```text
Source Agent → [Handoff Protocol] → Destination Agent
```
It gives the human a chance to intercept the transfer before the next agent begins.

## Design rationale
**1. Comprehension Over Logging**  
Agent handoffs are usually hidden deep in terminal logs (`Agent A passed context to Agent B`). `Handoff Protocol` pulls this event out of the log and formats it as a formal "shipping manifest," drastically increasing the human supervisor's situational awareness.

**2. Not Inherently a Gate**  
Unless `canIntercept` is `true`, this component is purely a *Comprehension UI*. It exists to be read, not clicked. In full autonomous mode, these cards stream by as a verifiable record of context transfer.

**3. The Intercept Hook**  
When an AI orchestrator realizes it is stuck or routing incorrectly, it can use the `Handoff Protocol` with `canIntercept={true}`. The "Intercept" action allows the human to break the chain, take the accumulated context, and manually complete or reroute the task.


---

---
title: Orchestrator View
description: Visualize the full agent hierarchy as a collapsible tree.
badge: View
---


Answers: [Cascading Failures](/docs/lexicon#cascading-failures), [L4 Autonomous](/docs/lexicon#l4-autonomous).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add orchestrator-view
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add orchestrator-view
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add orchestrator-view
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add orchestrator-view
```
  </Tab>
</Tabs>

## Overview

A recursive tree graph representing the Orchestrator and all of its spawned worker sub-agents. It provides a macro-view of the swarm's structure and highlights blocked or failed nodes that require human attention.


<ComponentPreview>
  <OrchestratorViewDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-orchestratorview--default" />

## Basic usage
```tsx

const mockSwarm: OrchestratorNode[] = [
  {
    id: 'orch_1',
    label: 'Main Router',
    role: 'Orchestrator',
    status: 'working',
    currentTask: 'Delegating work to sub-agents...',
    children: [
      {
        id: 'sub_1',
        label: 'Data Researcher',
        role: 'Search API',
        status: 'completed',
      },
      {
        id: 'sub_2',
        label: 'Code Writer',
        role: 'React Expert',
        status: 'blocked',
        currentTask: 'Waiting for missing API key',
      }
    ]
  }
];

export function App() {
  const [selectedId, setSelectedId] = useState<string>('orch_1');

  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-md">
      <OrchestratorView 
        nodes={mockSwarm} 
        selectedNodeId={selectedId}
        onNodeClick={(node) => setSelectedId(node.id)}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `nodes` | `OrchestratorNode[]` | `undefined` | Hierarchical tree data. Usually contains a single root node representing the main orchestrator agent. |
| `onNodeClick` | `(node: OrchestratorNode) => void` | `undefined` | Callback fired when the user clicks on an individual node in the tree. |
| `selectedNodeId` | `string` | `undefined` | The `id` of the currently selected node, used to highlight the active agent in the tree. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `OrchestratorNode`

```typescript
export type AgentStatus = 'idle' | 'working' | 'blocked' | 'failed' | 'completed';

export interface OrchestratorNode {
  id: string;
  label: string;
  status: AgentStatus;
  role?: string;
  currentTask?: string;
  children?: OrchestratorNode[];
}
```

## Solution Patterns
`Orchestrator View` acts as the navigation tree for a complex, hierarchical swarm.
- Use it as the left-pane side navigation in a specialized dashboard.
- Pair it with **Swarm Monitor** at the top of the viewport for aggregate metrics spanning the entire tree.
- When an individual node is clicked (`onNodeClick`), render a **Plan Card** + **Tool Trace** + **Run Controls** trio in the main right-hand pane to inspect that specific sub-agent.

## Design rationale
**1. The Macro/Micro Split**  
When multiple agents are running in a swarm, a single terminal log or chat thread becomes impossible to follow. `Orchestrator View` serves as the "macro" view—a structural map of *who* is doing what. Clicking a node typically updates an adjacent pane with the "micro" view (a standard `Plan Card` + `Tool Trace` for that specific agent).

**2. Exception Highlighting**  
The tree naturally collapses cognitive load by burying successful (`completed`) and waiting (`idle`) agents. However, `blocked` and `failed` nodes use high-contrast color codes to draw the supervisor's eye directly to the nodes requiring intervention, regardless of how deep they are nested.

**3. Depth**  
Nesting is the indent and the dashed guide beside a child list. A node does not get a colored side stripe. Its state is the dot and the status label.


---

---
title: Plan Card
description: Show the agent's proposed plan before it executes. Users see the trajectory before anything happens.
badge: Primitive
---


Answers: [Hallucinated Planning](/docs/lexicon#hallucinated-planning), [Plan-first](/docs/lexicon#plan-first).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add plan-card
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add plan-card
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add plan-card
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add plan-card
```
  </Tab>
</Tabs>

## Overview

`Plan Card` implements the plan-first pattern: show the trajectory, then execute. Before an agent takes any action, it proposes a plan — a numbered list of steps with confidence scores and assumptions.

This lowers fear and increases informed consent. Users can see where they're going before anything happens.


<ComponentPreview>
  <PlanCardDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-plancard--default" />

## Basic usage

```tsx
<PlanCard
  steps={agent.proposedPlan}
  assumptions={agent.assumptions}
/>
```

## With mock data

```tsx

const plan = generateMockPlan(4); // 4-step plan

<PlanCard
  steps={plan.steps}
  assumptions={plan.assumptions}
/>
```

## Live execution state

When the agent is running, pass `activeStepId` to highlight the current step:

```tsx
<PlanCard
  steps={agent.plan}
  activeStepId={agent.currentStepId}
/>
```

## Streaming state

When steps are still being generated by a streaming backend, pass `isStreaming`. This adds `data-streaming="true"` to the root element — no built-in animation. Style it however the host product expects:

```tsx
<PlanCard
  title={agent.planTitle}
  steps={agent.partialSteps}
  isStreaming={agent.isStreaming}
  mode="indeterminate"
/>
```

```css
/* Host product controls the visual */
[data-streaming="true"] .plan-card-title::after {
  content: "…";
  animation: pulse 1s infinite;
}
```

## Per-step reasoning

When each `PlanStep` has a `reasoning` string, opt-in to collapsible reasoning toggles with `showReasoning`. Set `defaultExpandedStepId` to pre-expand a specific step on mount:

```tsx
<PlanCard
  title={agent.planTitle}
  steps={agent.planSteps} // steps with .reasoning populated
  showReasoning
  defaultExpandedStepId={agent.activeStepId}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `steps` | `PlanStep[]` | **Required** | Ordered list of plan steps |
| `title` | `string` | **Required** | Title of the plan |
| `assumptions` | `string[]` | `undefined` | Agent's stated assumptions |
| `reasoning` | `string` | `undefined` | Agent's overall reasoning (collapsible) |
| `activeStepId` | `string` | `undefined` | ID of the currently executing step |
| `showConfidence` | `boolean` | `false` | Show confidence badge per step |
| `isStreaming` | `boolean` | `false` | Signals that steps are still being generated. Adds `data-streaming="true"` to the root element — no built-in animation; style via CSS. |
| `showReasoning` | `boolean` | `false` | Renders a collapsible reasoning toggle on each step that has a `reasoning` string. |
| `defaultExpandedStepId` | `string` | `undefined` | ID of the step whose reasoning is expanded by default (uncontrolled). Follows the `activeStepId` pattern. |

## PlanStep type

```ts
interface PlanStep {
  id: string;
  label: string;
  status: 'pending' | 'active' | 'completed' | 'failed';
  confidence?: number;   // 0–1
}
```

## When to use

- The agent is about to take a multi-step or multi-tool action and the user should be aware of the trajectory before it begins
- Trust is low or the action surface is new — surfacing the plan early builds informed consent
- The agent's intent is ambiguous without a plan (e.g., "refactor this codebase" covers too many possibilities)
- You want to give the user a natural moment to abort before any irreversible step starts

## When not to use

- The agent is performing a single, trivially understood action (e.g., "look up the weather") — a full plan card adds friction without value
- The agent's actions are happening fully in the background with no synchronous human checkpoint; use `Tool Trace` for passive monitoring instead
- You are already showing a `Decision Record` that captures the full approved plan — avoid duplicating plan state in both components

## Accessibility

- Uses semantic `<ol>` for step lists; each step renders as `<li>` with `role="listitem"`
- Active step is annotated with `aria-current="step"` to assist screen reader navigation
- Completed and failed steps carry `aria-label` values that include their status (e.g., "Step 2: Complete. Write schema migration.")
- Streaming state is announced via `aria-live="polite"` on the container when `isStreaming` is true
- All collapsible reasoning toggles use `<button aria-expanded>` with accessible toggle labels

## Solution Patterns

`Plan Card` is always the first primitive in a single-agent flow:

```
Plan Card → Approval Gate → Run Controls → Tool Trace → Artifact Card
```

Show it before the agent runs. Once execution starts, it updates step statuses live.

## Design rationale

**Why show the plan before execution?** Claude Cowork (Anthropic) shows the full plan in a "Progress" panel before any action is taken — validating the plan-first pattern. The core idea: agents that propose concrete work before asking for permission feel collaborative rather than autonomous. Users who can see a trajectory are far more likely to engage with it critically than users who are handed a fait accompli.

---

---
title: Policy Banner
description: Sandbox / production / staging environment policy indicator.
badge: Primitive
---


Answers: [Live fire](/docs/lexicon#live-fire).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add policy-banner
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add policy-banner
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add policy-banner
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add policy-banner
```
  </Tab>
</Tabs>

## Overview

`Policy Banner` is a persistent boundary indicator. It visually anchors the agent's current operating policy, ensuring the human operator strictly understands whether they are supervising a simulation, navigating staging environments, or engaging in a live fire production exercise.

<ComponentPreview>
  <PolicyBannerDemo />
</ComponentPreview>

<StorybookEmbed story="v2-compliance-forensics-policybanner--default" />

## Basic Usage

```tsx
<PolicyBanner
  mode="simulation"
  policyName="Dry Run Mode"
  description="Agent actions will be simulated and logged, but no external APIs will be mutated."
  constraints={[
    { label: 'Network', value: 'Mocked Responses' },
    { label: 'Database', value: 'Read-only connection', isViolated: false },
  ]}
/>
```

## Solution Patterns

Render `PolicyBanner` at the top of the supervision viewport. Using `mode="production"` automatically activates a heavy-duty, pulsing visual treatment designed to cut through "banner blindness" when navigating live, high-risk systems.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `mode` | `PolicyMode` | — | E.g., `'sandbox'`, `'production'`, `'simulation'` |
| `label` | `string` | — | Optional override for mode name |
| `description` | `string` | — | Short policy description |
| `severity` | `'info' \| 'warning' \| 'critical'` | auto | Visual treatment level |
| `constraints` | `PolicyConstraint[]` | — | Active policy constraints |
| `showLiveIndicator` | `boolean` | `false` | Show pulsing dot for live modes |
| `collapsible` | `boolean` | `false` | Allow banner to collapse |

## Design rationale

**Why a persistent banner?** Agent oversight interfaces look identical whether running on test data or production servers. A persistent banner prevents operator error by anchoring the environment context at the top of the supervision viewport.


---

---
title: Rollback Timeline
description: Undo-tree for agentic tool sequences.
badge: Pattern
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add rollback-timeline
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add rollback-timeline
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add rollback-timeline
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add rollback-timeline
```
  </Tab>
</Tabs>

## Overview

`Rollback Timeline` is an undo-tree designed specifically for agentic action sequences. When agents execute long chains of tool calls, humans need a safe way to regress state if an error or hallucination is caught late. This component visualizes execution history and makes irreversibility explicit.

<ComponentPreview>
  <RollbackTimelineDemo />
</ComponentPreview>

<StorybookEmbed story="v2-compliance-forensics-rollbacktimeline--default" />

## Basic Usage

```tsx
<RollbackTimeline
  title="Action Timeline"
  points={[
    { id: 'p1', label: 'Updated email', status: 'rolled-back', timestamp: '2026-03-19T10:00:00Z', reversible: true },
    { id: 'p2', label: 'Dropped legacy table', status: 'current', timestamp: '2026-03-19T10:05:00Z', reversible: false },
  ]}
  onRollback={(id) => handleRevert(id)}
/>
```

## Solution Patterns

Typically paired with `ToolTrace` for deep orchestration. When an agent executes a sequence of 10 tools and fails on the 11th, the timeline provides a structured path to rewind system state safely without guessing.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Title of the timeline |
| `points` | `RollbackPoint[]` | — | Ordered list of rollback points |
| `onRollback` | `(pointId: string) => void` | — | Rollback callback handler |
| `requireConfirmation` | `boolean` | `true` | Ask for confirmation before reverting |

## Design rationale

**Prerequisites:** This component assumes your product has reversible operations. If your agent's tool calls are all-or-nothing (e.g., sending emails, executing payments), `RollbackTimeline` will show the history but rollback actions won't be available past irreversible nodes. Evaluate your system's undo capabilities before adopting this component — it is most effective in environments where tool calls can be programmatically reversed (e.g., database migrations, file system changes, API calls with corresponding undo endpoints).

**Why explicit irreversibility?** Agent sequences frequently cross immutable boundaries (e.g., dropping a database table). Marking specific nodes `reversible: false` prevents the user from attempting a regression past a terminal action, saving engineering headaches.


---

---
title: Run Controls
description: Let users pause, resume, or stop a running agent.
badge: Primitive
---


Answers: [L4 Autonomous](/docs/lexicon#l4-autonomous).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add run-controls
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add run-controls
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add run-controls
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add run-controls
```
  </Tab>
</Tabs>

## Overview

Minimal execution steering — pause, resume, stop, retry. Intentionally kept simple. Extend via the actions slot for additional controls.


<ComponentPreview>
  <RunControlsDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-runcontrols--default" />

## Basic usage

```tsx
<Run Controls
  state="running"
  onPause={() => agent.pause()}
  onStop={() => agent.kill()}
/>
```

## With local state

```tsx

export function ExecutionWrapper() {
  const [state, setState] = useState<RunState>('running');

  return (
    <Run Controls 
      state={state} 
      showLabel={true}
      onStart={() => setState('running')}
      onPause={() => setState('paused')}
      onStop={() => setState('stopped')}
      onRetry={() => setState('running')}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `state` | `RunState` | **Required** | Current execution state (`'idle' \| 'running' \| 'paused' \| 'completed' \| 'failed' \| 'stopped'`). |
| `onStart` | `() => void` | `undefined` | Callback fired when user clicks start or resume. |
| `onPause` | `() => void` | `undefined` | Callback fired when user clicks pause. |
| `onStop` | `() => void` | `undefined` | Callback fired when user clicks stop (cancel execution entirely). |
| `onRetry` | `() => void` | `undefined` | Callback fired when user clicks retry after a failure state. |
| `showLabel` | `boolean` | `false` | Whether to display a text label showing the current state next to the pulsing indicator. |
| `actions` | `ReactNode` | `undefined` | Slot for additional custom action buttons (e.g., an Undo button). |

## When to use

- An agent is actively running and the user needs the ability to intervene at any time — pause, steer, or hard-stop
- The execution is long-running (multi-step, multi-tool) and the user may need to inspect progress before the agent continues
- Your product has compliance or safety requirements that mandate a human escape hatch during autonomous operation

## When not to use

- The agent run is fully instantaneous (< 1 second) — there is no execution window in which a control is meaningful
- The agent is running fully headless/background with no synchronous user session; surfacing controls the user cannot act on is confusing
- You're only displaying results after an agent has already completed — use `Artifact Card` to present the output, not `Run Controls`

## Accessibility

- Buttons use native `<button>` elements — no `div onClick` wrappers
- Each button has an explicit `aria-label` (e.g., "Pause agent run", "Stop agent run") independent of any icon or visual state
- Active state is communicated via `aria-pressed` where applicable (e.g., paused state on the pause button)
- The pulsing status indicator is marked `aria-hidden="true"` — status is conveyed via `aria-live` text, not animation
- All state transitions (running → paused, paused → running) are announced via `aria-live="polite"`

## Solution Patterns

`Run Controls` is the central execution steering wheel, usually placed immmediately before or right next to an agent's `Tool Trace`:

```text
Plan Card → Approval Gate → [Run Controls] → Tool Trace → Artifact Card
```
It controls whether the `Tool Trace` continues to append new events or pauses execution.

## Design rationale

**Why a hard stop?** When an agent is running autonomously, the human supervisor must always have an immediate, unambiguous way to halt it — not a "cancel this step" or "skip this action," but a full stop. The same instinct behind the physical emergency stop button on industrial machinery applies here: the safest systems always prioritize the human's ability to exit over the system's ability to complete. `Run Controls` makes that affordance obvious and persistent throughout the execution lifecycle.

**Why derive controls from state?** The controls are not a static button group. They derive from the `state` prop — so if the agent has already completed, the stop button disappears. If it has failed, the retry button appears. This isn't just DX convenience: it prevents the class of bug where a developer shows a stop button on a completed run, or a resume button on a failed one. The UI cannot express an impossible transition because impossible transitions have no visual representation.


---

---
title: Session Overview
description: Semantic rollup of a high-velocity agent session to prevent execution amnesia and cognitive load.
badge: View
---


Answers: [Execution Amnesia](/docs/lexicon#execution-amnesia), [Session Overview](/docs/lexicon#session-overview), [Audit Triad](/docs/lexicon#audit-triad), [L4 Autonomous](/docs/lexicon#l4-autonomous).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add session-overview
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add session-overview
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add session-overview
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add session-overview
```
  </Tab>
</Tabs>

## Basic usage

Use `<SessionOverview />` at the conclusion of a complex, multi-step agent run where the agent touches across dozens of files, APIs, or databases.


<SessionOverviewDemo />

```tsx

export function PostRunReport() {
  return (
    <SessionOverview
      sessionSummary="Refactored the authentication strategy and updated corresponding unit tests."
      duration="14m 23s"
      surfacesTouched={[
        { type: "file", label: "src/auth/index.ts", action: "write" },
        { type: "system", label: "jest-test-runner", action: "execute" }
      ]}
      keyDecisions={[
        { description: "Bypassed standard hashing due to legacy auth constraints." }
      ]}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `sessionSummary` | `string` | — | High-level semantic summary of what the agent achieved |
| `duration` | `string` | — | Total elapsed time of the agent session |
| `surfacesTouched` | `Array<{ type, label, action }>` | `[]` | Which digital surfaces the agent interacted with |
| `keyDecisions` | `Array<{ description: string }>` | `[]` | Significant decisions or deviations made autonomously |

## Solution Patterns

### Combating Execution Amnesia
When working with AI IDEs or multi-agent swarms, humans "fire and forget". After 10 prompts, humans suffer from **Execution Amnesia**—they no longer know what files were created, what systems were mutated, or what environment variables were exposed. 

By rendering a `SessionOverview` dynamically updating on the side of the screen (or upon session completion), humans can quickly parse the total blast radius of the agentic action.

### The Impact Matrix
Display `SessionOverview` next to the `SharedContextLedger`. The Ledger shows the *memory* the agent holds, while the Overview displays the *tangible mutations* the agent authored.

## Design rationale

**Why categorize impacts by Read vs Write vs Execute?**
When scanning a massive wall of text generated by an agent ("I did XYZ and then ABC"), users tune out. By categorizing surfaces touched strictly by their read/write vectors using standard UI badges, a security auditor or reviewing engineer can immediately identify exactly where side-effects happened in thousands of lines of code.

Visual layout scales better than walls of text for tracking agentic blast radiuses.


---

---
title: Shared Context Ledger
description: Read-only viewer for shared memory across agents, with provenance.
badge: View
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add shared-context-ledger
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add shared-context-ledger
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add shared-context-ledger
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add shared-context-ledger
```
  </Tab>
</Tabs>

## Overview

A read-only surface that visualizes the shared memory of the swarm. It tracks facts, decisions, and constraints written by multi-agent workflows, including who wrote each entry and when.


<ComponentPreview>
  <SharedContextLedgerDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-sharedcontextledger--default" />

## Basic usage
```tsx

const mockEntries: ContextLedgerEntry[] = [
  {
    id: 'ctx_1',
    scope: 'global',
    type: 'constraint',
    key: 'Budget Limit',
    value: 'Max spend $5.00 across all active instances.',
    provenance: {
      authorAgent: 'System Policy',
      timestamp: '2026-03-01T12:00:00Z'
    }
  },
  {
    id: 'ctx_2',
    scope: 'branch',
    type: 'fact',
    key: 'Competitor Pricing',
    value: 'Pro Tier is $49/mo',
    provenance: {
      authorAgent: 'Web Scraper Node',
      source: 'https://example.com/pricing',
      timestamp: 'Just now'
    },
    conflict: true
  }
];

export function App() {
  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-2xl">
      <SharedContextLedger 
        entries={mockEntries}
        currentScope="global"
        onFilterContext={(scope) => console.log('Filtering memory by scope:', scope)}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `entries` | `ContextLedgerEntry[]` | `undefined` | Array of memory items available to the swarm (see Type below). |
| `currentScope` | `'global' \| 'branch' \| 'agent-local'` | `undefined` | The currently active viewing filter. |
| `onFilterContext` | `(scope) => void` | `undefined` | Callback fired when the user selects a scope tab in the header. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `ContextLedgerEntry`

```typescript
export interface ContextLedgerEntry {
  id: string;
  scope: 'global' | 'branch' | 'agent-local'; // Controls visibility radius
  type: 'fact' | 'decision' | 'constraint' | 'artifact';
  key: string;              // E.g., "Target Audience"
  value: string;            // E.g., "Developers aged 25-34"
  provenance: {
    authorAgent: string;    // Which agent wrote this memory?
    source?: string;        // Where did they get it? (e.g., a URL)
    timestamp: string;      
  };
  conflict?: boolean;       // True if another agent tried to overwrite this with a different value
}
```

## Solution Patterns

`Shared Context Ledger` provides a read-only overview of the "memory" being passed around the swarm:

```text
Agent A (State) → [Shared Context Ledger] ← Agent B (State)
```
It is typically rendered globally alongside the `Swarm Monitor`.

## Design rationale
**1. The Epistemology Hub**  
When multiple agents collaborate, hallucinations compound. If Agent A hallucinates a "fact" and writes it to shared memory, Agents B, C, and D will treat it as ground truth. The `Shared Context Ledger` exists to expose the swarm's epistemology to the human supervisor.

**2. Strict Provenance**  
A memory without an author is useless for debugging. The UI forces the display of the `provenance` block. If a human sees a hallucination in the ledger, they can instantly trace it back to the specific `authorAgent` that wrote it and the `source` it originated from.

**3. Conflict Visualization**  
In autonomous swarms, agents frequently debate or arrive at different conclusions. When two agents attempt to write conflicting values to the same `key`, the ledger displays both and flags them with `conflict: true`. This turns a silent failure of consensus into a visible prompt for human resolution.


---

---
title: State Diff
description: Structured before/after view of state mutations.
badge: Primitive
---


Answers: [Execution Amnesia](/docs/lexicon#execution-amnesia), [Unpredictable Outcomes](/docs/lexicon#unpredictable-outcomes), [L2 Collaborative](/docs/lexicon#l2-collaborative).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add state-diff
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add state-diff
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add state-diff
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add state-diff
```
  </Tab>
</Tabs>

## Overview

`State Diff` provides mutation visibility, turning abstract JSON payloads into human-readable proof of what changed. In high-stakes environments, humans cannot simply trust an agent's summary — they need exact before-and-after deltas.

<ComponentPreview>
  <StateDiffDemo />
</ComponentPreview>

<StorybookEmbed story="v2-compliance-forensics-statediff--default" />

## Basic Usage

```tsx
<StateDiff
  title="Configuration Changes"
  entries={[
    { field: 'max_instances', type: 'modified', before: '2', after: '5' },
    { field: 'region', type: 'added', after: 'us-east-1' },
    { field: 'legacy_mode', type: 'removed', before: 'true' },
  ]}
/>
```

## Solution Patterns

Place `StateDiff` inside a `ToolTrace` or a `PlanCard` to show exact intended or completed mutations. Pair it with `BindingApproval` so the person can see the mutation they are confirming. The signature, if any, comes from your backend.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Title of the diff (e.g. "Database Mutation") |
| `description` | `string` | — | Optional context |
| `entries` | `DiffEntry[]` | — | Flat list of diff entries |
| `groups` | `DiffGroup[]` | — | Grouped entries (takes precedence over entries) |
| `hideUnchanged` | `boolean` | `false` | Hide unchanged fields |
| `defaultCollapsed` | `boolean` | `false` | Start collapsed |
| `timestamp` | `string` | — | Mutation timestamp |
| `sourceId` | `string` | — | Tool call/step ID |

## Design rationale

**Why `hideUnchanged`?** Massive JSON payloads distract from the actual mutation. Highlighting only the delta reduces cognitive load and focuses human attention exactly where the risk is.

**Why structure over syntax highlighting?** A human cannot easily parse a raw git-style diff of a minified JSON object. Transforming the delta into a structured, dot-notated table makes the blast radius legible to non-engineers.


---

---
title: Subagent Card
description: A compact embeddable card for a single sub-agent.
badge: View
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add subagent-card
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add subagent-card
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add subagent-card
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add subagent-card
```
  </Tab>
</Tabs>

## Overview

A versatile, compact card component used to represent individual workers. It surfaces the most critical agent telemetry (current task, plan progress, token burn, and status) and provides an expansion point to drill down into the agent's full v0 detail panel.


<ComponentPreview>
  <SubagentCardDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-subagentcard--default" />

## Basic usage
```tsx

export function App() {
  return (
    <div className="p-4 grid gap-4 grid-cols-1 md:grid-cols-2">
      <SubagentCard 
        agentName="Search Node"
        role="Web Scraper API"
        status="working"
        currentTask="Extracting pricing tables from competitor sites"
        planStepCount={5}
        planStepsCompleted={2}
        tokensUsed={4500}
        onExpand={() => console.log('Drill down tapped')}
      />

      <SubagentCard 
        agentName="Summary Node"
        role="Data Synthesizer"
        status="idle"
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `agentName` | `string` | **Required** | The primary title or ID of the sub-agent. |
| `status` | `AgentStatus` | **Required** | Current operating status (`'idle' \| 'working' \| 'blocked' \| 'failed' \| 'completed'`). |
| `role` | `string` | `undefined` | A secondary label describing the agent's core capability or model. |
| `currentTask` | `string` | `undefined` | A description of the specific action the agent is taking right now. |
| `planStepCount` | `number` | `undefined` | Total number of steps in the agent's current plan (enables the progress bar). |
| `planStepsCompleted` | `number` | `undefined` | Number of completed steps in the agent's current plan. |
| `tokensUsed` | `number` | `undefined` | Optional token burn count displayed in the footer. |
| `onExpand` | `() => void` | `undefined` | Callback fired when the user clicks the "expand" or drill-down button. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Solution Patterns

`Subagent Card` is designed for list or grid views of multiple agents.

```text
Orchestrator View → Agent Roster → [Subagent Card]
```
It provides a high-level summary of a single agent's identity and status.

## Design rationale
**1. Contextual Embeds**  
`Subagent Card` is designed to be embedded *inside* other orchestration components. It serves as the rich payload within `Orchestrator View` tree nodes, or as the dense grid item in a non-list swarm dashboard.

**2. Progressive Disclosure via `onExpand`**  
A single agent's full context (its `Plan Card`, `Tool Trace`, `Run Controls`, and `Approval Gate`) takes up an entire screen. The `Subagent Card` acts as the closed envelope; the `onExpand` handler allows developers to wire it up to a modal, slide-over, or detail pane where the human supervisor can actually debug the specific node.

**3. Visual Mini-Plan**  
If `planStepCount` is provided, a miniature progress bar appears. This leverages the established AX standard: always show the human the deterministic boundaries (a plan) around the non-deterministic generation.


---

---
title: Swarm Inbox
description: Prioritized inbox for approval requests, escalations, and violations.
badge: View
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add swarm-inbox
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add swarm-inbox
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add swarm-inbox
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add swarm-inbox
```
  </Tab>
</Tabs>

## Overview

A centralized attention triage surface for the swarm supervisor. It aggregates critical events (like permission requests, failed nodes, or policy violations) from across the entire agent fleet into a single, prioritized inbox with one-click drill-down actions.


<ComponentPreview>
  <SwarmInboxDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-swarminbox--default" />

## Basic usage
```tsx

const mockNotifications: SwarmInboxItem[] = [
  {
    id: 'evt_1',
    type: 'escalation',
    severity: 'critical',
    title: 'Database connection refused',
    agentId: 'SQL Writer Node',
    branchPath: 'Reporting / Q3',
    timestamp: 'Just now',
    detail: 'Allowed duration exceeded (3000ms)'
  },
  {
    id: 'evt_2',
    type: 'approval',
    severity: 'warning',
    title: 'Requested read access to S3 bucket',
    agentId: 'Data Sync Node',
    timestamp: '2m ago'
  }
];

export function App() {
  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-lg">
      <SwarmInbox 
        items={mockNotifications}
        onOpenItem={(item) => console.log('Opening detail modal for', item.id)}
        onDismissItem={(id) => console.log('Dismissed', id)}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `items` | `SwarmInboxItem[]` | `undefined` | Array of notification items to render in the inbox list. |
| `onOpenItem` | `(item: SwarmInboxItem) => void` | `undefined` | Callback fired when the user clicks the "View" button to drill down into an issue. |
| `onDismissItem` | `(id: string) => void` | `undefined` | Callback fired when the user clicks the "×" (dismiss) button on a non-critical item. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `SwarmInboxItem`

```typescript
export type SwarmInboxSeverity = 'critical' | 'warning' | 'info';

export interface SwarmInboxItem {
  id: string;
  type: 'approval' | 'escalation' | 'policy_violation' | 'stalled' | 'budget_overrun' | 'conflict';
  severity: SwarmInboxSeverity; 
  title: string;
  agentId: string;         // The agent requiring attention
  branchPath?: string;     // The organizational sub-tree where this agent lives
  timestamp: string;       // Formatted time string, e.g., "Just now"
  detail?: string;         // Optional one-liner description for extra context
}
```

## Solution Patterns

### The Exception-Only Console

`Swarm Inbox` aggregates cross-agent communication. It is typically a top-level navigational element alongside the `Swarm Monitor` or `Agent Roster`:

```text
[Swarm Monitor] ← Global KPIs + kill switch
[Swarm Inbox]   ← Prioritized interrupts requiring human action
[Agent Roster]  ← At-a-glance agent status
```

### Composition: SwarmInbox → EscalationRouter

The `onOpenItem` callback is designed to transition the user from the macro view (inbox) to the micro view (resolution). For `escalation`-type items, the standard pattern is to open an [**Escalation Router**](/docs/components/escalation-router) in a modal:

```tsx
<SwarmInbox
  items={notifications}
  onOpenItem={(item) => {
    if (item.type === 'escalation') {
      openModal(<EscalationRouter
        failedAgent={item.agentId}
        branchId={item.branchPath}
        errorSummary={item.detail}
        onRetry={() => retryAgent(item.agentId)}
        onReassign={() => reassignTask(item.id)}
        onCancelBranch={() => cancelBranch(item.branchPath)}
      />);
    }
  }}
/>
```

For `approval`-type items, open an `ApprovalGate` instead. The inbox is the funnel — the specific component you open depends on the event type.

## Design rationale
**1. The "Exception-Only" Workflow**  
Supervising a multi-agent swarm requires shifting from "babysitting" to an "exception-only" workflow. The human should only look at the UI when the UI explicitly asks for help. `Swarm Inbox` is the funnel for all of those system interrupts.

**2. Type-Driven Visual Sorting**  
Not all interruptions are equal. A `policy_violation` (an agent trying to access a restricted tool) gets a distinct visual treatment from a standard `approval` loop. The `critical` severity visually dominates the list, pulsing if necessary, ensuring triage happens in the correct order.

**3. Actionable Drill-Downs**  
An inbox without actions is just a log. The `onOpenItem` callback transitions the user from the inbox to resolution — typically opening an [Escalation Router](/docs/components/escalation-router) or [Approval Gate](/docs/components/approval-gate) inside a modal.


---

---
title: Swarm Monitor
description: Aggregate health grid showing throughput, tokens, and global controls.
badge: View
---


Answers: [Cascading Failures](/docs/lexicon#cascading-failures), [L4 Autonomous](/docs/lexicon#l4-autonomous).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add swarm-monitor
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add swarm-monitor
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add swarm-monitor
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add swarm-monitor
```
  </Tab>
</Tabs>

## Overview

A macro-level dashboard header. It aggregates the operating health of the entire swarm into a single row of KPIs, and features a prominent "global kill switch" for emergency overrides. Use this alongside `Agent Roster` for per-agent drill-downs.


<ComponentPreview>
  <SwarmMonitorDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-swarmmonitor--default" />

## Basic usage
```tsx

export function App() {
  const currentMetrics = {
    activeInstances: 14,
    idleInstances: 3,
    totalCost: '$1.42',
    tokensBurned: 145000,
    errorRate: 12, // 12% 
    taskCompletionRate: 68, // 68%
    estimatedTimeRemaining: '~4m'
  };

  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg">
      <SwarmMonitor 
        metrics={currentMetrics}
        onGlobalPause={() => console.log('Swarm paused')}
        onGlobalKill={() => console.log('Swarm killed')}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `metrics` | `Object` | **Required** | Aggregate metrics object displaying the health of the entire swarm (see Type below). |
| `onGlobalPause` | `() => void` | `undefined` | Callback fired when the user clicks the "Pause All" action. |
| `onGlobalKill` | `() => void` | `undefined` | Callback fired when the user clicks the "Halt Swarm" emergency kill switch. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `SwarmMetrics`

```typescript
export interface SwarmMonitorProps {
  metrics: {
    activeInstances: number;     // Currently running agents
    idleInstances: number;       // Agents waiting for routing/input
    totalCost: string;           // Formatted USD string e.g. "$1.42"
    tokensBurned: number;        // Raw input+output token count
    errorRate: number;           // Percentage 0–100. Colors amber > 5%, red > 15%
    taskCompletionRate?: number; // Percentage 0–100. Renders as a progress bar
    estimatedTimeRemaining?: string; 
  };
}
```

## Solution Patterns
`Swarm Monitor` is the apex header of a multi-agent dashboard.
- Render it at the very top of complex pages to provide aggregate situational awareness.
- Pair it with **Agent Roster** (for flat worker pools) or **Orchestrator View** (for hierarchical delegation trees) beneath it so users can drill into the specific agents causing the error rates reported in the monitor.
- If the monitor shows a high error spike, the user clicks the prominent `onGlobalKill` button to halt the entire system at once.

## Design rationale
**1. The "Big Red Button" at Scale**  
While `Run Controls` stops a single agent, `Swarm Monitor` controls the fleet. When an unexpected loop or hallucination cascade begins, supervisors do not have time to find the specific rogue agent. The `onGlobalKill` action provides instant peace of mind.

**2. Visualizing Severity (The 15% Rule)**  
The `errorRate` metric is not a static number; it is a dynamic severity indicator. By default, it tints Amber if the error rate exceeds 5%, and solid Red if it exceeds 15% (the point at which a generative swarm is likely caught in a retry loop).

**3. Progress vs. Time**  
Generative workflows are non-deterministic, making time estimates notoriously inaccurate. `Swarm Monitor` centers the `taskCompletionRate` (a deterministic ratio of pending vs completed tasks) rather than a shaky countdown clock, grounding the human in reality.


---

---
title: Task Queue
description: A backlog of pending swarm tasks with priority routing.
badge: View
---


## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add task-queue
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add task-queue
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add task-queue
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add task-queue
```
  </Tab>
</Tabs>

## Overview

A structured list of pending and assigned tasks before they are executed by the swarm. It surfaces task priority, routing status, and provides manual override actions (promote, assign, cancel) to the human supervisor.


<ComponentPreview>
  <TaskQueueDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-v1-taskqueue--default" />

## Basic usage
```tsx

const mockTasks: TaskQueueItem[] = [
  {
    id: 't_1',
    title: 'Generate Weekly Report',
    priority: 'high',
    status: 'in_progress',
    assignedTo: 'Analytics Node',
    estimatedTokens: 4500
  },
  {
    id: 't_2',
    title: 'Update Notification Settings',
    description: 'User requested daily digest instead of immediate alerts.',
    priority: 'medium',
    status: 'pending'
  }
];

export function App() {
  return (
    <div className="p-4 border border-zinc-200 dark:border-zinc-800 rounded-lg max-w-lg">
      <TaskQueue 
        tasks={mockTasks}
        onTaskAction={(id, action) => console.log(`Task ${id} action: ${action}`)}
      />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `tasks` | `TaskQueueItem[]` | `undefined` | Array of tasks to render in the queue. Automatically grouped by status. |
| `onTaskAction` | `(id: string, action) => void` | `undefined` | Callback fired when a user clicks an action button (Promote, Assign, Cancel) on a task. |
| `className` | `string` | `undefined` | Additional CSS class for the root element. |

## Types

### `TaskQueueItem`

```typescript
export type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
export type TaskStatus = 'pending' | 'assigned' | 'in_progress';

export interface TaskQueueItem {
  id: string;
  title: string;
  description?: string;
  priority: TaskPriority;
  assignedTo?: string;            // Agent the task is assigned to, if any
  status: TaskStatus;
  estimatedTokens?: number;       // Forecasted cost of the task
}
```

## Solution Patterns

`Task Queue` manages the pending backlog for a specific agent:

```text
Orchestrator → [Task Queue] → Active Plan Card
```
It allows humans to re-prioritize work before the agent officially plans it.

## Design rationale
**1. Exposing the Routing Layer**  
In an autonomous swarm, tasks are often dynamically generated and routed without human input. `Task Queue` forcibly visualizes this "pending state," transforming invisible background queues into a tangible list of upcoming work.

**2. Manual Overrides**  
AI orchestrators make routing mistakes. `Task Queue` includes built-in action hooks (`promote`, `assign`, `cancel`) that allow the human supervisor to step in, re-prioritize a critical task, or cancel a low-value generation before compute limits are burned.

**3. Visual Grouping**  
Tasks are automatically sorted and grouped by their `TaskStatus` (`in_progress` → `assigned` → `pending`). Priority badges use semantic color coding (Red for Critical, Amber for High) to ensure the most important work isn't lost in the backlog.


---

---
title: Tool Trace
description: Live timeline of every tool call with inputs, outputs, and policy flags.
badge: Primitive
---


Answers: [Rogue Tool Use](/docs/lexicon#rogue-tool-use), [L1 Human-Led](/docs/lexicon#l1-human-led).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add tool-trace
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add tool-trace
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add tool-trace
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add tool-trace
```
  </Tab>
</Tabs>

## Overview

Auto-scrolling timeline representing the agent's inner loop. Entries with `policyFlags` (`requiresApproval`, `writesState`, `externalAction`) are visually distinguished from routine calls.


<ComponentPreview>
  <ToolTraceDemo />
</ComponentPreview>

<StorybookEmbed story="ax-components-tooltrace--default" />

## Basic usage

```tsx
<Tool Trace
  calls={[]}
  autoScroll={true}
/>
```

## With mock data

Because `Tool Trace` requires an array of tool call objects to render its timeline, you'll typically pass in an array that looks like this:

```tsx

const mockCalls: ToolCall[] = [
  {
    id: 'call_1',
    name: 'fetch_user_data',
    status: 'completed',
    timestamp: new Date(),
    input: { userId: '123' },
    output: { name: 'Alice' },
    policyFlags: { externalAction: true }
  }
];

export function App() {
  return (
    <Tool Trace 
      calls={mockCalls} 
      expandable={true} 
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `calls` | `ToolCall[]` | **Required** | Array of tool calls to display in the trace timeline. |
| `autoScroll` | `boolean` | `false` | Whether the timeline should automatically scroll to the latest entry when new calls are added. |
| `maxHeight` | `string` | `undefined` | Maximum height of the container before an internal scrollbar appears (e.g., `'400px'`). |
| `onEntryClick` | `(call: ToolCall) => void` | `undefined` | Callback fired when a user clicks on a tool call entry. |
| `expandable` | `boolean` | `false` | If true, entries can be clicked to expand and reveal their raw JSON input and output. |

## When to use

- An agent is actively executing and the user should be able to observe its tool call activity in real time
- Auditability is required — after the run, the user or a reviewer should be able to inspect exactly which tools ran, with what inputs, and what they returned
- The agent can call external, state-mutating, or policy-flagged tools and you want to surface those calls distinctly from routine ones

## When not to use

- The agent's operations are already fully visible through another mechanism (e.g., a database log) — don't duplicate audit trails in the UI
- The agent only performs a single tool call — a full scrollable trace timeline adds visual weight without value; a simpler status indicator suffices
- You are building a developer debugging view — `Tool Trace` is a user-facing oversight tool, not a raw log viewer; for raw logs, link to your platform's log explorer

## Accessibility

- Each tool call entry is a `<li>` within a `role="log"` list, which communicates the live-updating nature to assistive technologies
- New entries appended during streaming are announced via `aria-live="polite"` on the log container
- Expandable entries use `<button aria-expanded>` with descriptive labels (e.g., "Expand tool call: fetch_user_data")
- Policy flag badges (e.g., `externalAction`, `writesState`) are exposed as `aria-label` text — not color alone
- Duration and timestamp metadata are part of the accessible text, not hidden in tooltips

## Solution Patterns

`Tool Trace` is the primary visual feedback mechanism while an agent is actively running. It generally renders below `Run Controls`:

```text
Plan Card → Approval Gate → Run Controls → [Tool Trace] → Artifact Card
```
It updates asynchronously. As soon as the agent completes its final tool call, the flow concludes with an `Artifact Card`.

## Design rationale

**Why comprehension over logging?** Standard terminal logs are unreadable for non-engineers. Tool Trace formats JSON inputs and outputs into a structured UI, translating machine process into human-readable proof of work.

**What is policy flagging?** Not all tools are equal. A `read_file` is routine, but a `execute_payment` is critical. The `policyFlags` system allows specific tool calls to bear visual severity tokens (e.g., an amber badge for `writesState`), distinguishing high-risk calls from routine ones at a glance and directing human attention where it matters.

**Why automatic anchoring?** In an active stream, the human loses context if the UI doesn't track the edge of computation. The `autoScroll` logic ensures the most recent action is always in view, creating a sense of live generative momentum.


---

---
title: Transaction Receipt
description: Provenance receipt with verification hash for completed actions.
badge: Control
---


Answers: [Transaction Receipt](/docs/lexicon#transaction-receipt), [Audit Triad](/docs/lexicon#audit-triad).

## Install

<Tabs groupId="package-manager" items={["npm", "pnpm", "yarn", "bun"]} persist>
  <Tab value="npm">
```bash
npx ax-depute@latest add transaction-receipt
```
  </Tab>
  <Tab value="pnpm">
```bash
pnpm dlx ax-depute@latest add transaction-receipt
```
  </Tab>
  <Tab value="yarn">
```bash
yarn dlx ax-depute@latest add transaction-receipt
```
  </Tab>
  <Tab value="bun">
```bash
bunx ax-depute@latest add transaction-receipt
```
  </Tab>
</Tabs>

## Overview

`Transaction Receipt` is the audit-log component. After an irreversible action passes a gate, the supervisor needs a record of the outcome. A hash or signature shown here is supplied by your backend. The component does not create one.

Pass `approvalReceipt` when the gate emitted an `ApprovalReceipt`. The card shows that document's hash, checks it with `verify`, and downloads the JSON. It still does not sign.

<ComponentPreview>
  <TransactionReceiptDemo />
</ComponentPreview>

<StorybookEmbed story="v2-compliance-forensics-transactionreceipt--default" />

## Basic Usage

```tsx
<TransactionReceipt
  transactionId="TX-98765"
  title="Wire Transfer Complete"
  status="success"
  timestamp="2026-03-19T14:30:00Z"
  agentId="payment-agent-01"
  hash="0xabcdef1234567890abcdef1234567890fedcba09"
  lineItems={[
    { label: 'Amount', value: '$5,000.00', highlight: true },
    { label: 'From', value: 'Account ****4521' },
    { label: 'To', value: 'Account ****8903' },
  ]}
/>
```

## Solution Patterns

This component acts as the final terminal output of an `OrchestratorView` node, replacing a generic `ArtifactCard` when the event is financial or structurally immutable.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `transactionId` | `string` | — | Unique identifier |
| `title` | `string` | — | Title of the receipt |
| `status` | `'success' \| 'failed' \| 'pending' \| 'reverted'` | `'success'` | Current status |
| `timestamp` | `string` | — | Completion timestamp |
| `lineItems` | `ReceiptLineItem[]` | — | Key-value pairs of the transaction |
| `hash` | `string` | — | Hash supplied by your backend. Display only. |
| `signature` | `string` | — | Signature supplied by your backend. Display only. |
| `onVerify` | `(proof) => void` | — | Your app's check for the displayed hash and signature. |
| `agentId` | `string` | — | ID of the acting agent |
| `copyableHash` | `boolean` | `true` | Allow copying the hash |

## Design rationale

**Why show a hash?** A receipt is easier to trust when the backend's own proof is visible. `TransactionReceipt` displays the `hash` and `signature` you pass in. It does not compute them. Verification belongs in `onVerify`, which your app implements.


---

---
title: Governance Levels
description: Mapping the Singapore IMDA Agentic AI Governance Framework directly to Depute's primitive components.
---

When deploying Agentic AI into production, "human-in-the-loop" is no longer a sufficient framing. Under emerging governance standards like the **Singapore IMDA Model AI Governance Framework for Agentic AI** (January 2026), organizations are expected to formally classify the autonomy level of their agents and provide corresponding human oversight.

Depute provides UI primitives that support implementation of each of these four governance dimensions. Canonical wording for the four levels is in the [Lexicon](/docs/lexicon#l1-human-led).

---

## The L1–L4 Autonomy Taxonomy

### L1 — Human-Led
**Agent proposes, human operates.** The agent acts exclusively as an advisor. It generates data, intelligence, or suggestions, but the human must manually execute the final action in their own tooling.
- **Depute Implementation:** Use an [**Artifact Card**](/docs/components/artifact-card) or [**Tool Trace**](/docs/components/tool-trace) to display the agent's work cleanly. No complex execution barriers are needed because the agent lacks execution privileges in the host environment.

### L2 — Collaborative
**Agent and human work together.** The agent can draft actions and stage tools, but requires active back-and-forth guidance and synchronous alignment.
- **Depute Implementation:** Use a [**Delegation Gate**](/docs/components/delegation-gate) to smoothly manage the handoff when the human decides the agent is ready to take the reins. Wrap interactions in [**State Diff**](/docs/components/state-diff) to show the human exactly what the agent drafted before it applies to the global state.

### L3 — Supervised
**Agent operates, human approves.** The most critical boundary for high-stakes deployments. The agent can run end-to-end, and an irreversible action waits for an explicit human confirmation. The UI displays that confirmation. Your backend records it.
- **Depute Implementation:** 
  - Wrap dangerous tools in an [**Approval Gate**](/docs/components/approval-gate) to halt execution immediately.
  - Surround the gate with an [**Automation Bias Alert**](/docs/components/automation-bias-alert) to ensure the human doesn't blindly rubber-stamp the request out of fatigue.
  - Bind the final decision to a [**Decision Record**](/docs/components/decision-record) to log an immutable audit trail of the *human's* approval logic for forensic review.

### L4 — Autonomous
**Agent operates, human observes.** The agent runs asynchronously in the background across prolonged periods. The risk shifts from "preventing a single bad action" to "detecting cascading failures" across a massive, opaque blast radius.
- **Depute Implementation:** 
  - Ensure users have persistent [**Run Controls**](/docs/components/run-controls) to hard-kill the agent workflow at any moment from anywhere in the application.
  - Provide a [**Session Overview**](/docs/components/session-overview) upon completion to cure "Execution Amnesia" and summarize the entire blast radius of the agent's autonomous run.
  - Use an [**Orchestrator View**](/docs/components/orchestrator-view) and [**Swarm Monitor**](/docs/components/swarm-monitor) to map the topology of multiple agents spinning up sub-agents autonomously.


---

---
title: Lexicon
description: Canonical definitions for Delegation UI, automation bias, rubber-stamping, execution amnesia, responsibility diffusion, diffusion of responsibility, blast radius, who approved, live fire, and session budget.
---

This page is the canonical wording for the terms depute uses. Other pages link here. Quote these sentences; do not paraphrase them.

depute documents this vocabulary. It does not claim to have invented the underlying research. Origin tags stay attached to their terms.

Components are UI and callbacks. Enforcement is the caller's backend.

## Frame

### Delegation UI

Software UI has gone through two eras. **Command Line:** you told the machine what to do, step by step. **Navigation:** you drove software through menus, flows, and screens. That paradigm held for thirty years — and it's the one that's dying.

**Delegation UI** is the third era. You describe an outcome and an agent pursues it. The interface is no longer a vehicle you drive — it's a cockpit you monitor. You're setting intent, reviewing decisions, and maintaining oversight.

Also described as: third era, cockpit you monitor, supervise instead of operate.

Origin: published in the depute README as the project's frame for this interface era.

### Agentic Experience

**Depute** is a React component library for Agentic Experience (AX) design — purpose-built UI primitives for AI agent supervision and human oversight.

Origin: Tabah & Landon, *AX: The Rise of Agentic Experience* (LCA). Chapter mappings used elsewhere in depute — Ch. 9, Ch. 12, and Pattern 6 ("Generative Momentum") — are pending confirmation against the physical copy.

### depute

*Depute (verb meaning to appoint or delegate).*

## Failures

### Automation Bias

Users blindly rubber-stamp agent actions without scrutiny.

Also described as: rubber-stamping, click-through approvals, passive oversight.

Origin: Mosier & Skitka (1996); Parasuraman & Manzey (2010). Mosier, K. L., & Skitka, L. J. (1996). Human decision makers and automated decision aids: Made for each other? In R. Parasuraman & M. Mouloua (Eds.), *Automation and Human Performance: Theory and Applications*. Lawrence Erlbaum. Parasuraman, R., & Manzey, D. H. (2010). Complacency and bias in human use of automation: An attentional integration. *Human Factors, 52*(3), 381–410.

Answered by [Automation Bias Alert](/docs/components/automation-bias-alert) and [Confidence Meter](/docs/components/confidence-meter).

### Execution Amnesia

Users lose track of the total "blast radius" of a massive agent session. When working with AI IDEs or multi-agent swarms, humans "fire and forget". After 10 prompts, humans suffer from Execution Amnesia—they no longer know what files were created, what systems were mutated, or what environment variables were exposed.

Also described as: lost track of what the agent did, fire and forget, blast radius.

Origin: wording published in the depute docs. No earlier paper is cited for this phrase here.

Answered by [Session Overview](/docs/components/session-overview) and [State Diff](/docs/components/state-diff).

### Responsibility Diffusion

Users approve actions assuming the machine is accountable. In enterprise and high-compliance environments, "Responsibility Diffusion" happens when humans blindly click approve because they aren't explicitly reminded that their identity is being audited.

Also described as: diffusion of responsibility, who approved, the machine is accountable.

Origin: lineage of Darley & Latané (1968). Darley, J. M., & Latané, B. (1968). Bystander intervention in emergencies: Diffusion of responsibility. *Journal of Personality and Social Psychology, 8*(4), 377–383. That paper is about bystander intervention. The depute docs apply the lineage to a person approving an agent action while assuming the machine is accountable.

Answered by [Decision Record](/docs/components/decision-record) and [Binding Approval](/docs/components/binding-approval).

### Cascading Failures

An agentic error pollutes downstream autonomous systems rapidly.

Also described as: downstream autonomous systems, error pollutes downstream.

Origin: sentence published on the depute introduction, under systemic threats targeted by frameworks such as the Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026).

Answered by [Swarm Monitor](/docs/components/swarm-monitor) and [Orchestrator View](/docs/components/orchestrator-view).

### Hallucinated Planning

An agent proposes a destructive or nonsensical sequence of tools.

Also described as: destructive plan, nonsensical sequence of tools.

Origin: sentence published on the depute introduction, under systemic threats targeted by frameworks such as the Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026).

Answered by [Plan Card](/docs/components/plan-card) and [Confidence Meter](/docs/components/confidence-meter).

### Rogue Tool Use

An agent attempts an irreversible action out-of-bounds.

Also described as: irreversible action, out-of-bounds tool call.

Origin: sentence published on the depute introduction, under systemic threats targeted by frameworks such as the Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026).

Answered by [Approval Gate](/docs/components/approval-gate) and [Tool Trace](/docs/components/tool-trace).

### Unpredictable Outcomes

A run completes with thousands of opaque, unlogged side effects.

Also described as: opaque side effects, unlogged side effects.

Origin: sentence published on the depute introduction, under systemic threats targeted by frameworks such as the Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026).

Answered by [State Diff](/docs/components/state-diff) and [Session Overview](/docs/components/session-overview).

## Patterns

### Audit Triad

`DecisionRecord` is one of three audit-layer components. Each captures a different moment in the accountability chain:

| Component | Scope | Records | Question it answers |
|-----------|-------|---------|---------------------|
| Decision Record | Per-approval | Who approved, why, and under what policy | "Who authorized this?" |
| Transaction Receipt | Per-action | What the machine did, with verification hash | "What actually happened?" |
| Session Overview | Per-session | Semantic rollup of everything the agent touched | "What was the total blast radius?" |

Use all three together for full audit coverage: `DecisionRecord` captures the human side, `TransactionReceipt` captures the machine side, and `SessionOverview` captures the session-level summary.

Component pages: [Decision Record](/docs/components/decision-record), [Transaction Receipt](/docs/components/transaction-receipt), [Session Overview](/docs/components/session-overview).

### Decision Record

Immutable visual receipt of a human approval decision to counteract Responsibility Diffusion. Scope: per-approval. Records who approved, why, and under what policy. Question it answers: "Who authorized this?"

It is an immutable *visual* receipt. It displays the decision. Enforcement is the caller's backend.

### Who approved

Plain-language form of the [Decision Record](#decision-record) question: who approved, why, and under what policy. The record's own question is "Who authorized this?" See [Responsibility Diffusion](#responsibility-diffusion).

### Transaction Receipt

Per-action record of what the machine did, with a verification hash. Question it answers: "What actually happened?"

`Transaction Receipt` is the audit-log component. After an irreversible action passes a gate, the supervisor needs a record of the outcome. A hash or signature shown here is supplied by your backend. The component does not create one. `TransactionReceipt` displays the `hash` and `signature` you pass in. It does not compute them.

### Session Overview

Semantic rollup of a high-velocity agent session to prevent execution amnesia and cognitive load. Scope: per-session. Records a semantic rollup of everything the agent touched. Question it answers: "What was the total blast radius?"

### Binding Approval

`BindingApproval` does not sign, hash, or talk to a ledger. Pass `signature` and `hash` when your backend has already produced them, and pass `onVerify` if the app should check that proof. The component only displays those values.

Answered on the [Binding Approval](/docs/components/binding-approval) page. The failure it sits under is [Responsibility Diffusion](#responsibility-diffusion).

### Scoped grant

Approvals are scoped grants, not binary yes/no decisions. A user approving "send emails" shouldn't be approving "send unlimited emails forever."

A scoped grant is scoped to a specific target, resource-bounded, time-bounded, and revocable at any time.

Origin: Stripe SPT (Shared Payment Token), as credited in the depute design rationale.

Answered by [Approval Gate](/docs/components/approval-gate).

### Staged approval

Preview → Confirm → Execute. Stripe validates at multiple points in a transaction flow, not just once. `mode="staged"` lets `ApprovalGate` function as a multi-step gate rather than a single popup.

Origin: Stripe's Authorization Chain pattern, as credited in the depute design rationale.

Answered by [Approval Gate](/docs/components/approval-gate).

### Provenance

The agent's "receipt" of work completed. It renders the final output alongside crucial provenance data: precisely which plan step and tool calls generated it.

Origin: Stripe's audit trail and Coinbase's receipts pattern, as credited in the depute design rationale. Once agents act autonomously, auditability becomes the trust backbone.

Answered by [Artifact Card](/docs/components/artifact-card).

### Plan-first

Show the trajectory, then execute. `PlanCard` shows the plan before execution, not after.

Origin: Claude Cowork (Anthropic), as credited in the depute design rationale. Cowork calls this "Generative Momentum" (AX Book Pattern 6). That chapter mapping is pending confirmation against the physical copy.

Answered by [Plan Card](/docs/components/plan-card).

### Mandate

`ApprovalGate` approves an **action**. `DelegationGate` approves the **creation of an autonomous entity**.

Coinbase's "Mandate + Guardrails" pattern (set a budget, define constraints, then authorize) maps directly to `DelegationGate`. You're not just saying yes — you're issuing a mandate with guardrails.

Origin: Coinbase Agentic Wallets, as credited in the depute design rationale.

Answered by [Delegation Gate](/docs/components/delegation-gate).

## System terms

### Blast radius

The total "blast radius" of a massive agent session is what users lose track of under Execution Amnesia: what files were created, what systems were mutated, or what environment variables were exposed. The per-session question in the Audit Triad is "What was the total blast radius?"

See [Execution Amnesia](#execution-amnesia) and the [Audit Triad](#audit-triad).

### Live fire

`Policy Banner` is a persistent boundary indicator. It visually anchors the agent's current operating policy, ensuring the human operator strictly understands whether they are supervising a simulation, navigating staging environments, or engaging in a live fire production exercise.

Also described as: live fire mistakes, production rather than sandbox.

Answered by [Policy Banner](/docs/components/policy-banner).

### Budget

Visual gauge showing session budget vs. burn rate. Delegation requires guardrails. Instead of blocking every action, `Budget Meter` allows users to grant agents an explicit budget (API tokens, currency, or API call limits) and tracks the real-time burn rate.

Also described as: burn rate, session budget, unbounded API budget.

Answered by [Budget Meter](/docs/components/budget-meter).

### Capability

`Capability Matrix` is the "Agent Handshake." As products explicitly declare their tools to agents via frameworks like WebMCP, humans need to see that exact programmatic contract. This component visualizes what an agent is capable of doing in the current specific operating context.

Also described as: agent handshake, permissions the agent holds.

Answered by [Capability Matrix](/docs/components/capability-matrix).

### Human-in-the-loop

When deploying Agentic AI into production, "human-in-the-loop" is no longer a sufficient framing. The levels below are the classification the docs use instead.

Origin: the depute governance page, citing the Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026).

### L1 Human-Led

**Agent proposes, human operates.** The agent acts exclusively as an advisor. It generates data, intelligence, or suggestions, but the human must manually execute the final action in their own tooling.

Origin: Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026), as mapped on the [governance levels](/docs/governance-levels) page. depute supplies the UI named below. It did not author the L1–L4 framework.

Answered by [Artifact Card](/docs/components/artifact-card) and [Tool Trace](/docs/components/tool-trace).

### L2 Collaborative

**Agent and human work together.** The agent can draft actions and stage tools, but requires active back-and-forth guidance and synchronous alignment.

Origin: Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026), as mapped on the [governance levels](/docs/governance-levels) page.

Answered by [Delegation Gate](/docs/components/delegation-gate) and [State Diff](/docs/components/state-diff).

### L3 Supervised

**Agent operates, human approves.** The most critical boundary for high-stakes deployments. The agent can run end-to-end, and an irreversible action waits for an explicit human confirmation. The UI displays that confirmation. Your backend records it.

Origin: Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026), as mapped on the [governance levels](/docs/governance-levels) page.

Answered by [Approval Gate](/docs/components/approval-gate), [Automation Bias Alert](/docs/components/automation-bias-alert), and [Decision Record](/docs/components/decision-record).

### L4 Autonomous

**Agent operates, human observes.** The agent runs asynchronously in the background across prolonged periods. The risk shifts from "preventing a single bad action" to "detecting cascading failures" across a massive, opaque blast radius.

Origin: Singapore IMDA Model AI Governance Framework for Agentic AI (January 2026), as mapped on the [governance levels](/docs/governance-levels) page.

Answered by [Run Controls](/docs/components/run-controls), [Session Overview](/docs/components/session-overview), [Orchestrator View](/docs/components/orchestrator-view), and [Swarm Monitor](/docs/components/swarm-monitor).

### Primitive

A foundational, single-responsibility building block (e.g., `PlanCard`, `ApprovalGate`).

### View

A compositional surface that aggregates multiple primitives into a larger macro-interface (e.g., `OrchestratorView`, `SwarmInbox`).

### Control

An operational or forensic surface used to halt, direct, or audit execution (e.g., `EscalationRouter`, `DecisionRecord`).

### Pattern

A highly specialized workflow wrapper designed to enforce a specific behavioral policy (e.g., `AutomationBiasAlert`, `HandoffProtocol`).

The four classes above are the docs taxonomy. They are copied from the introduction page.


---

---
title: Introduction to Multi-Agent 
description: Understanding the two macro-views for swarm orchestration and supervision.
---

## The Supervision Problem

When you scale from one agent to a swarm of intelligent workers, the oversight problem changes entirely. You no longer need to see every single thought or tool call. If you try to supervise a 20-agent swarm using single-agent components (like [Plan Card](/docs/components/plan-card) or [Tool Trace](/docs/components/tool-trace)), your operators will be paralyzed by noise.

Instead, multi-agent supervision requires **triage**, **hierarchy**, and **aggregated context**.

## Where to start

If you are building a multi-agent product, do not start by dropping 10 different components on a page. Start by identifying your swarm's structure. There are two "macro-views" that serve as the anchors for all other components in this section:

### 1. Tree-structured swarms
If your swarm follows a recursive, "manager / worker" delegation tree (where Agent A spawns Agent B to complete a subtask), start with the [OrchestratorView](/docs/components/orchestrator-view). It visualizes the hierarchy and highlights which branches are blocked.

### 2. Flat-pool swarms
If your swarm operates as a flat pool of autonomous workers pulling equally from a backlog, start with the [AgentRoster](/docs/components/agent-roster). It optimizes for density, letting supervisors scan 20+ concurrent workers at a glance.

## The surrounding ecosystem

Once you have your macro-view anchor, you can compose the rest of the multi-agent console around it:

- Need triage for escalations? Add a [Swarm Inbox](/docs/components/swarm-inbox).
- Need global metrics and a kill switch? Pin a [Swarm Monitor](/docs/components/swarm-monitor) to the top.
- Need to expose hidden agent-to-agent memory? Render the [Shared Context Ledger](/docs/components/shared-context-ledger).

Begin at your architectural root, and only add the Control and Pattern components when specific operational friction demands them.


---

---
title: Theming
description: Token tiers, the rename map, and density.
---

Components read semantic and component tokens. Base ramps (`--ax-gray-*`, `--ax-accent-*`, status hues) stay internal. Override a semantic token to theme the library.

## Tiers

Import the stylesheet once:

```css
@import "./styles/depute.css";
```

That file loads four layers:

1. **Base** — 12-step gray, one accent, and status hues. Light is the default. Dark follows `data-theme="dark"`, a `.dark` class, or `prefers-color-scheme`, unless the page sets `data-theme="light"` or `.light`.
2. **Semantic** — surfaces, text, borders, status pairs, type, space, radius, shadow, and motion.
3. **Component** — card, button, badge, meter, and row tokens.
4. **Legacy** — the 0.4 names, aliased for this minor version.

Fonts are not bundled. Install `@fontsource/geist-sans` and `@fontsource/geist-mono`, or use `next/font`. The stack falls back to the system font.

## Density

Set `data-ax-density="comfortable"` on a parent to raise card padding, row height, and the default button height. Compact is the default. Coarse pointers raise the button and row height to 44px.

```html
<div data-ax-density="comfortable">
  <!-- depute components -->
</div>
```

## Rename map

| 0.4 name | 0.5 name |
| --- | --- |
| `--ax-surface-primary` | `--ax-bg-surface` |
| `--ax-text-primary` / `--ax-text-secondary` | `--ax-fg-default` / `--ax-fg-muted` |
| `--ax-border-color` | `--ax-border-default` |
| `--ax-status-pending-*` | `--ax-status-neutral-*` |
| `--ax-status-active-*` | `--ax-status-info-*` |
| `--ax-status-completed-*` | `--ax-status-success-*` |
| `--ax-status-failed-*` | `--ax-status-danger-*` |
| `--ax-status-waiting-*` | `--ax-status-warning-*` |
| `--ax-font-family` | `--ax-font-sans` |
| `--ax-shadow-sm` / `md` / `lg` | `--ax-shadow-1` / `2` / `3` |

Status text uses step 11 on a step 3 tint so the pair stays at least 4.5:1 in both themes.


---