Auto-run Automation
Relevant source files
The following files were used as context for generating this wiki page:
Auto-run is a core automation feature of PlanQueue that enables the sequential dispatch of prompts from a Markdown-based queue to a coding agent without manual intervention. It transforms the session note into an active FIFO (First-In-First-Out) queue that automatically feeds the next pending task whenever the agent settles from a previous turn.
The system is designed to maintain a "human-in-the-loop" balance by pausing at specific barriers, halting on errors, or stopping when the user opens the editor to modify the plan. This ensures that while the agent can process a series of tasks autonomously, the user retains ultimate control over the execution flow.
Sources: README.md:16-19, src/queue-controller.ts:1-12
Architecture and Execution Flow
The Auto-run mechanism is managed by the QueueController, which coordinates between the note's content and the OMP (Oh My Pi) agent's session state. The automation relies on the session_stop event to trigger the next step in the queue.
Core Logic and Triggers
The automation flow follows a specific lifecycle:
- Activation: Toggled via a configurable shortcut (default
Ctrl+Shift+Down). - Priming: If the agent is idle when activated, it immediately dispatches the first pending task.
- Execution: After a turn completes, the system marks the previous task as done (
- [x]) and evaluates the queue for the next item. - Advance: If the next item is a valid prompt, it is sent as a
followUpmessage to avoidAgentBusyError.
Sources: src/queue-controller.ts:60-63, src/queue-controller.ts:133-138, src/queue-controller.ts:162-168
Lifecycle Diagram
The following diagram illustrates the state transitions and decision points during an Auto-run sequence.
Human-in-the-Loop (HITL) Barriers
Auto-run identifies --- lines as barriers. When the automation encounters a barrier, it performs the following actions:
- Disables the
autostate. - Sets a
blockedflag. - Triggers a notification to the user.
- If running in a Herdr environment (
HERDR_ENV=1), it executes a shell command to show a system-level notification.
Sources: src/queue-controller.ts:47-58, src/queue-controller.ts:98-107, SECURITY.md:31-33
Herdr Integration
The system integrates with the Herdr workspace to provide external alerts when the queue requires manual attention.
| Feature | Description | Implementation |
|---|---|---|
| Notification | System-level alert for paused queues | herdr notification show |
| Sound | Audio cue for user attention | --sound request |
| Sidebar Sync | Mirrors blocked state to Herdr UI | pi.events.emit("herdr:blocked", ...) |
Sources: src/queue-controller.ts:32-43, src/queue-controller.ts:76-83
Safety and Interruption Handling
Auto-run includes several safety checks to prevent the agent from executing prompts in a broken or invalid state.
Failure Handling
The system monitors the stopReason of the assistant's last message. If a turn ends in an error or is aborted, Auto-run automatically halts to prevent the agent from cascading errors through subsequent prompts.
Sources: src/queue-controller.ts:21-29, src/queue-controller.ts:149-153
Editor Protection
To prevent race conditions where a background auto-save might clobber manual edits, Auto-run "pauses striking" when the notes editor is open. The editorOpen() check ensures that task state transitions (like marking a task done) do not occur while the user is actively modifying the note.
Sources: src/queue-controller.ts:154, src/main.ts:241-244
Component Summary
| Component | Role | File Reference |
|---|---|---|
QueueController | Manages the internal auto and blocked states. | src/queue-controller.ts |
autoAdvance | Logic for evaluating the next queue item after settle. | src/queue-controller.ts:145 |
sendPrompt | Dispatches message and marks line as in-flight (- [>]). | src/queue-controller.ts:86 |
turnFailed | Inspects SessionStopEvent for errors or aborts. | src/queue-controller.ts:21 |
pingHerdr | Executes external notification subprocess. | src/queue-controller.ts:32 |
Summary
Auto-run Automation in PlanQueue provides a robust mechanism for executing multi-step plans with minimal manual interaction. By leveraging the session_stop event and treating Markdown checkboxes as state indicators, it maintains a persistent, resumable execution flow. Its safety features, including barrier support and failure detection, ensure that automated prompt delivery remains reliable and observable within the OMP environment.