OMP Host API Interactions
Relevant source files
The following files were used as context for generating this wiki page:
PlanQueue is an OMP (Oh My Pi) extension designed to integrate a session-notes panel and a FIFO prompt queue directly into the OMP environment. It functions as a bridge between the user's planning process and the coding agent's execution by utilizing the OMP Host API to manage UI components, intercept session events, and dispatch messages to the underlying LLM.
The extension leverages the ExtensionAPI provided by the host to register tools, commands, and shortcuts, while also reacting to lifecycle events like session starts and stops. This deep integration allows PlanQueue to maintain persistence across repo branches and sessions while providing a seamless "human-in-the-loop" experience.
Sources: src/main.ts:1-13, README.md:14-22
Core API Integration Architecture
The PlanQueue extension is initialized via a factory function that receives the ExtensionAPI. This API serves as the primary gateway for all interactions with the OMP host. The extension uses this interface to set up its internal state, register commands, and establish event listeners.
The diagram shows how the PlanQueue extension connects to various subsystems of the OMP Host via the central ExtensionAPI.
Sources: src/main.ts:251-255, src/queue-controller.ts:69-70
Extension Lifecycle Events
PlanQueue monitors specific session events to synchronize its local state (notes and queue progress) with the host's active context.
| Event | Action Taken | Source |
|---|---|---|
session_start | Initializes session paths and loads notes. | src/main.ts:352 |
session_switch | Flushes pending saves and re-initializes for the new context. | src/main.ts:354-357 |
session_stop | Marks in-flight tasks as done and triggers auto-advance. | src/queue-controller.ts:186-191 |
session_shutdown | Ensures all pending note changes are flushed to disk. | src/main.ts:359-361 |
User Interface and Widget Management
The extension interacts with the OMP UI through ctx.ui to render a status widget and manage custom editor overlays.
The Below-Editor Widget
The primary visual element is a widget placed below the terminal editor. It is updated dynamically to reflect the current state of the prompt queue, including checkbox glyphs (☐, ▸, ✓) and shortcut hints.
This sequence illustrates the rendering request sent to the OMP host to display the queue status.
Sources: src/main.ts:269-281, CHANGELOG.md:16-19
Custom Editor Integration
When a user initiates note editing (via Ctrl+N or /note), PlanQueue requests a custom UI component from the host. It uses ctx.ui.custom to mount a CustomEditor provided by the host's SDK.
- Submission: Handled by
editor.onSubmit, which triggers persistence and closes the overlay. - Cancellation: Handled by
editor.onEscape, which may prompt the user to save changes if the buffer was modified. - Clipboard: Uses
editor.onCopyPromptto execute OSC 52 escape sequences for terminal-agnostic copying.
Sources: src/main.ts:63-78, src/main.ts:326-342
Command and Tool Registration
PlanQueue extends the host's functionality by registering slash commands and LLM-accessible tools.
Slash Commands
The extension registers several commands using pi.registerCommand.
/note <text>: Appends a task or opens the editor./planqueue: Opens a cross-session browser usingctx.ui.select./make-note <goal>: Sends a meta-prompt to the agent to generate a plan.
Sources: src/main.ts:222-248
LLM Tools
To allow the coding agent to interact with the queue, PlanQueue registers tools that the host's LLM engine can invoke.
| Tool Name | Purpose | Parameters |
|---|---|---|
note_add | Appends a single - [ ] task to the current note. | text (string) |
make_note | Overwrites or bootstraps a note with a structured plan. | heading (string), steps (array) |
Sources: src/main.ts:145-171, src/main.ts:187-217
Prompt Queue Execution Logic
The interaction for sending prompts involves complex state management between the extension and the host's agent.
The flow describes how PlanQueue decides to dispatch messages based on whether the OMP agent is currently busy or idle.
Sources: src/queue-controller.ts:98-109
Auto-run and Barriers
Auto-run is a stateful mode where PlanQueue automatically feeds the next prompt upon receiving a session_stop event.
- Barrier Detection: If the next line is
---, the extension halts auto-run and notifies the user viactx.ui.notify. - Failure Handling: If a turn ends in an
erroror isaborted, auto-run is immediately disabled to prevent cascading failures. - External Notifications: When running in a Herdr environment (
HERDR_ENV=1), the extension executes a host sub-process (herdr notification show) to alert the user at barriers.
Sources: src/queue-controller.ts:161-184, src/queue-controller.ts:40-58
Summary
Interactions with the OMP Host API are the foundation of PlanQueue's functionality. By utilizing the host's ExtensionAPI, PlanQueue effectively manages a persistent, session-aware prompt queue. It balances automated execution with human-in-the-loop control through a combination of custom UI components, global shortcuts, and event-driven logic, ensuring that the coding agent remains aligned with the user's defined plan.