85 lines
3 KiB
Markdown
85 lines
3 KiB
Markdown
|
---
|
||
|
|
title: Interventions — Reference
|
||
|
|
---
|
||
|
|
|
||
|
|
# Interventions — Reference
|
||
|
|
|
||
|
|
The Interventions page lists every task that has been flagged `needs_human=true` — actions that only a human can take. It polls the API every 15 seconds and organises tasks into **Open** and **Completed / Cancelled** sections.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## What is a human intervention?
|
||
|
|
|
||
|
|
A human intervention is a task that an agent has determined cannot proceed without direct human action — for example, approving a financial decision, confirming a legal commitment, or resolving a sensitive ambiguity. Flagging a task does not change its work status; the task continues to be `todo`, `in_progress`, or `blocked` while awaiting attention.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## KPI sidebar card
|
||
|
|
|
||
|
|
| Metric | Meaning |
|
||
|
|
|---|---|
|
||
|
|
| **open** | Number of tasks currently flagged and not yet resolved |
|
||
|
|
| **critical / high** | Subset with `critical` or `high` priority — shown in red when non-zero |
|
||
|
|
| **by domain** | Top-3 domains by open intervention count |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Open section
|
||
|
|
|
||
|
|
Tasks are sorted by priority (critical → high → medium → low), then by status (blocked → in_progress → todo). Each card shows:
|
||
|
|
|
||
|
|
| Element | Meaning |
|
||
|
|
|---|---|
|
||
|
|
| Priority badge | `critical` / `high` / `medium` / `low` |
|
||
|
|
| Status chip | Current task status |
|
||
|
|
| Domain | Source domain slug |
|
||
|
|
| Workstream | Parent workstream title |
|
||
|
|
| Action note | The `intervention_note` — what the human needs to do |
|
||
|
|
| Task detail | Expandable `<details>` with the task title and description (shown when different from the action note) |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Marking an intervention as done
|
||
|
|
|
||
|
|
Click **Mark done** on any open card. An inline form appears requiring a **resolution comment** — a short note describing what was done. The comment is mandatory; clicking **Confirm** without entering text highlights the field in red and does nothing.
|
||
|
|
|
||
|
|
Once confirmed, the API call sets `status = done`, `needs_human = false`, and replaces the action note with your resolution comment. The card moves to the **Completed / Cancelled** section on the next poll.
|
||
|
|
|
||
|
|
Click **Cancel** to dismiss the form without making changes.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Flagging and clearing interventions via MCP
|
||
|
|
|
||
|
|
```
|
||
|
|
flag_for_human(
|
||
|
|
task_id = "<uuid>",
|
||
|
|
note = "Approve the Q2 budget allocation before the 15th"
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
```
|
||
|
|
clear_human_flag(task_id = "<uuid>")
|
||
|
|
```
|
||
|
|
|
||
|
|
`clear_human_flag` sets `needs_human = false` and preserves the `intervention_note` as a historical record. It does **not** change the task's work status. Use the dashboard's **Mark done** button when you also want to advance the status to `done`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Filtering by workstream
|
||
|
|
|
||
|
|
`list_human_interventions(workstream_id="<uuid>")` via MCP returns only interventions for a specific workstream — useful for scoped reviews in agent sessions.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## REST endpoints
|
||
|
|
|
||
|
|
| Method | Path | Effect |
|
||
|
|
|---|---|---|
|
||
|
|
| `GET` | `/tasks/?needs_human=true` | List all flagged tasks |
|
||
|
|
| `PATCH` | `/tasks/{id}/` | Update status, needs_human, intervention_note |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
*Interventions are never created from the dashboard — they are raised by agents during task execution and resolved by the human.*
|