Human-in-the-loop Barriers
Relevant source files
The following files were used as context for generating this wiki page:
Human-in-the-loop (HITL) barriers in PlanQueue are specific markers within a prompt queue that pause automated or manual execution to allow for human review. Represented by a lone --- line (three or more dashes) in the Markdown note, these barriers act as checkpoints. They ensure that complex or high-stakes sequences of agent prompts do not proceed without explicit verification from the user.
Sources: README.md:41-45, README.md:73-77, CHANGELOG.md:19-21
Conceptual Overview
The core purpose of a barrier is to prevent the "babysitting" of a terminal while still maintaining control over the agent's actions. When the PlanQueue system encounters a barrier line, it halts the queue's progress. This is particularly relevant during Auto-run mode, where prompts are otherwise fed to the agent automatically upon the settlement of the previous turn.
Sources: README.md:36-40, README.md:79-84
Triggering and Resolution Logic
The following diagram illustrates how the system handles a barrier during queue execution:
The logic for handling barriers is primarily located in the QueueController. When a barrier kind is identified by the findHead function, the system calls haltAtBarrier.
Sources: src/queue-controller.ts:114-123, src/queue-controller.ts:139-143
Technical Implementation
Syntax and Recognition
A barrier is recognized as a line containing three or more consecutive dashes (---). These lines are excluded from prompt dispatch and instead trigger a state change in the QueueController.
Sources: README.md:73-77, CHANGELOG.md:19-21
Queue Controller Logic
The QueueController manages the internal blocked state. When a barrier is hit:
- Auto-run is disabled: The
autoflag is set tofalse. - State is blocked: The
setBlocked(true)function is called, which can trigger external notifications. - User Notification: A UI notification is sent to the user indicating the queue is paused.
- External Pings: If the environment is a Herdr workspace (
HERDR_ENV=1), a system-level notification is triggered.
Sources: src/queue-controller.ts:104-112, src/queue-controller.ts:114-123
Interaction Patterns
| Action | Result at a Barrier | Source |
|---|---|---|
Ctrl+↓ (Step) | Deletes the --- line and resumes the queue. | README.md:75-77 |
Ctrl+Shift+↓ (Auto) | Auto-run pauses automatically when a barrier is the next head item. | README.md:79-84 |
Agent make_note Tool | The agent can programmatically insert barrierAfter: true to create barriers. | src/main.ts:258-262 |
Herdr Integration
Inside a Herdr environment, HITL barriers trigger more aggressive notifications. This allows the user to leave the workspace while the agent works, knowing they will be alerted when their input is required.
The pingHerdr function executes a shell command herdr notification show with specific arguments for sound and body text to alert the workspace.
Sources: src/queue-controller.ts:39-60, SECURITY.md:27-31
Related Components
The make_note Tool
The make_note LLM tool allows the agent to decompose a high-level goal into a plan that includes barriers. The steps parameter in the tool definition includes an optional barrierAfter boolean. If set to true, the extension appends a --- line after that specific step in the Markdown note.
Sources: src/main.ts:258-265, src/main.ts:296-300
Widget Display
The status of the queue, including whether it is currently blocked by a barrier, is reflected in the UI widget via the queueHint and renderWidgetLines functions.
Sources: src/main.ts:348-360, src/queue-controller.ts:68-71
Conclusion
Human-in-the-loop barriers serve as the primary safety and synchronization mechanism in PlanQueue. By transforming a simple Markdown horizontal rule into a functional checkpoint, the system balances the efficiency of automated prompt execution with the necessity of human oversight in complex development tasks.