pi-ask-popup 0.2.0 → 0.2.1

package/docs/tool-schema.md

@@ -106,19 +106,22 @@ When `error` is `timed_out`, the text is `Questionnaire timed out, the user did
 
 ## Events
 
-The package emits one event on Pi's event bus, after validation passes and before the dialog shows. Import it from the `./events` subpath:
+The package emits lifecycle events on Pi's event bus after validation passes. Import their names and payload types from the `./events` subpath:
 
 ```ts
 import {
   ASK_POPUP_PROMPT_EVENT,
   ASK_POPUP_BLOCKED_EVENT,
+  HERDR_BLOCKED_EVENT,
   type AskPopupPromptEventPayload,
   type AskPopupBlockedEventPayload,
 } from "pi-ask-popup/events";
 ```
 
-`ASK_POPUP_PROMPT_EVENT` channel is `pi-ask-popup:prompt`. Payload is `questions[].{ question, header, multiSelect, options[] }` where each option is `{ label, description, hasPreview }`. Preview content is not shipped, only `hasPreview: boolean`, so listeners that forward the event stay small.
+`ASK_POPUP_PROMPT_EVENT` is `pi-ask-popup:prompt`. It fires once before the dialog shows. Its payload is `questions[].{ question, header, multiSelect, options[] }`, where each option is `{ label, description, hasPreview }`. Preview content is not shipped, only `hasPreview: boolean`, so listeners that forward the event stay small.
 
-`ASK_POPUP_BLOCKED_EVENT` channel is `pi-ask-popup:blocked`. Payload is `{ blocked: boolean }`. It brackets the wait, true when the questionnaire starts and false when it resolves, so status or footer extensions can show that the agent is waiting.
+`ASK_POPUP_BLOCKED_EVENT` is `pi-ask-popup:blocked`. Its payload is `{ active: boolean }`. It brackets the wait with `true` when the questionnaire starts and `false` when it resolves, so status or footer extensions can show that the agent is waiting.
 
-Both payloads are JSON-safe. Channel names are stable. Changes are append-only and optional, and any breaking change ships as a new channel rather than a version field.
+`HERDR_BLOCKED_EVENT` is `herdr:blocked`. It receives the same blocked payload at the same points. Herdr's Pi integration consumes this channel to mark the agent as waiting for input and issue its configured request notification. Nothing happens when Herdr is absent.
+
+The payloads are JSON-safe. Channel names are stable. Changes are append-only and optional, and any breaking change ships as a new channel rather than a version field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ask-popup",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pi extension. A tabbed terminal questionnaire the model can put to you when it would otherwise guess, with typed options, markdown previews and notes instead of free-form replies.",
   "type": "module",
   "license": "MIT",

package/src/ask-user-question.ts

@@ -22,6 +22,7 @@ import {
   ASK_POPUP_BLOCKED_EVENT,
   ASK_POPUP_PROMPT_EVENT,
   buildBlockedPayload,
+  HERDR_BLOCKED_EVENT,
   buildPromptPayload,
 } from "./events.js";
 // Static import: the walker pulls only types, none of the render graph the
@@ -88,7 +89,9 @@ function emitPrompt(pi: ExtensionAPI, params: QuestionParams): void {
 }
 
 function emitBlocked(pi: ExtensionAPI, active: boolean): void {
-  pi.events.emit(ASK_POPUP_BLOCKED_EVENT, buildBlockedPayload(active));
+  const payload = buildBlockedPayload(active);
+  pi.events.emit(ASK_POPUP_BLOCKED_EVENT, payload);
+  pi.events.emit(HERDR_BLOCKED_EVENT, payload);
 }
 
 /** The backstop for a host with no UI at all; the reconciler normally strips the tool first. */

package/src/events.ts

@@ -4,11 +4,11 @@
  * This module deliberately imports nothing. A footer, statusline or notifier
  * subscribes to these channels to know what is being asked and whether the
  * agent is waiting on a person; it should not have to load a render graph, or
- * a schema compiler, to read two strings and four interfaces. Adding an import
+ * a schema compiler, to read three strings and four interfaces. Adding an import
  * here defeats the reason the `./events` subpath exists, so there is a test
  * that fails if one appears.
  *
- * Stability rules for both channels:
+ * Stability rules for these channels:
  *
  *   1. Channel names never change once published. Subscribers hardcode them.
  *   2. Payload changes are append-only, and new fields ship optional.
@@ -29,6 +29,12 @@ export const ASK_POPUP_PROMPT_EVENT = "pi-ask-popup:prompt" as const;
 /** Fired true before the wait and false when it ends, however it ends. */
 export const ASK_POPUP_BLOCKED_EVENT = "pi-ask-popup:blocked" as const;
 
+/**
+ * Herdr's Pi integration listens on this shared channel for nested UI that
+ * needs a decision. Emitting it is inert when Herdr is not installed.
+ */
+export const HERDR_BLOCKED_EVENT = "herdr:blocked" as const;
+
 export interface AskPopupPromptOption {
   label: string;
   description: string;

package/src/index.ts

@@ -13,6 +13,7 @@ import { registerAskPopupReconciler } from "./reconcile.js";
 export {
   ASK_POPUP_BLOCKED_EVENT,
   ASK_POPUP_PROMPT_EVENT,
+  HERDR_BLOCKED_EVENT,
   type AskPopupBlockedEventPayload,
   type AskPopupPromptEventPayload,
   type AskPopupPromptOption,