Guides/Approvals

Approvals

Human-in-the-loop approval gates surfaced through the operator queue on the Operations page. Agents that need authorization for a sensitive action write an approval item; an operator approves or rejects from the UI; the agent reads the decision back and continues.

Watch

All videos

Trinity Platform Demo — operator queue & approvals

May 2026

Concepts

•Approval item — A row in the operator queue with type=approval. Created by the agent, consumed by an operator.

•Options — JSON array of choices the operator picks from (typically ["approve", "reject"], but agents may define richer sets like ["draft", "send", "discard"]).

•Priority — critical, high, medium, low. Affects sort order in the queue.

•Response window — Optional expires_at. After expiry the item moves to expired; agents may choose to fail-safe or fail-open.

How It Works

The agent reaches a step that needs operator authorization.

The agent writes an approval item to ~/.trinity/operator-queue.json (or calls a helper skill that does so).

The Operator Queue Sync Service polls the file every 5 seconds and persists the item to the backend.

The item appears on the Operations page under the Needs Response tab, with title, question, options, and any context the agent attached. Resolved items (acknowledged, cancelled, expired) move to the Resolved tab.

An operator picks an option and optionally adds a text comment.

The decision is written back into ~/.trinity/operator-queue.json for the agent to read.

The agent acknowledges the response and continues.

Bulk Operations

The Operations page offers a per-tab Clear All that hides resolved items, and pending items can be bulk-cancelled. Because cancellation can race with a response, submitting a decision returns 409 if the item left the pendingstate in the meantime (for example, it was cancelled by a bulk operation) — refresh the queue and re-check before retrying.

Real-Time Notifications

WebSocket events fired along the way:

•operator_queue_new — when the item arrives

•operator_queue_responded — when the operator decides

•operator_queue_acknowledged — when the agent confirms it saw the decision

For Agents

Approvals share the operator-queue API surface:

Endpoint	Method	Description
/api/operator-queue	GET	List queue items (filter by `type=approval`)
/api/operator-queue/{id}	GET	Get a single item
/api/operator-queue/{id}/respond	POST	Submit the operator's decision
/api/operator-queue/{id}/cancel	POST	Cancel a pending item
/api/operator-queue/agents/{name}	GET	Items scoped to a specific agent

MCP Tools

Agents can inspect the queue programmatically (read-only):

Tool	Description
list_operator_queue	List queue items, broad or filtered by `agent_name`
get_operator_queue_item	Fetch a single item by id

Agent-scoped API keys see only items for the calling agent itself plus agents it has been explicitly permitted to access. Responding and cancelling remain operator actions through the API/UI.