@hank-warren/pi-ask-user-question 0.5.3 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @hank-warren/pi-ask-user-question
 
+## 0.6.1
+
+### Patch Changes
+
+- 1035138: Report a waiting question to Herdr as `blocked`.
+
+  `ask_user_question` and Plan Mode's `plan_mode_question` now emit the same
+  `herdr:blocked` event pi-auto-permissions emits for an approval prompt, labelled
+  `question` / `plan question` and cleared in a `finally`, so Herdr's pi
+  integration shows a session waiting on a question as `blocked` rather than
+  `working`. A supervising agent in another pane can wait on that state and answer
+  the dialog. No-op outside Herdr.
+
+## 0.6.0
+
+### Minor Changes
+
+- c079c51: Announce tool availability on a new event, and stop mistaking a symlinked install for somebody else's package.
+
+  Every reconcile now emits `hank:ask-user:availability` (`ASK_USER_AVAILABILITY_EVENT`) with `{ available: boolean }`, letting a consumer such as pi-plan-mode decide whether its own fallback question tool is needed without racing hook order. Availability is read back from the host rather than assumed from the write, because Pi silently ignores a name excluded by `--tools` or a tool policy, and a false positive would leave an interactive session with no question tool at all.
+
+  The check for whether the registered `ask_user_question` is still backed by this package now canonicalizes both paths before comparing. `import.meta.url` is realpath-resolved by Node while Pi passes `sourceInfo.baseDir` through untouched, so every workspace, pnpm, and `npm link` install compared two spellings of the same directory, concluded the tool belonged to someone else, and never restored it after the first headless run. A path that cannot be resolved falls back to a lexical compare rather than failing closed.
+
+  `AbortSignal` is wired through the questionnaire with exactly-once listener cleanup, and the blocked signal is always cleared in a `finally`.
+
 ## 0.5.3
 
 ### Patch Changes

package/README.md

@@ -123,6 +123,10 @@ pi.events.on("hank:ask-user:prompt", ({ questions }) => {
 Channel names are immutable and payloads are append-only — see
 [`events.ts`](./events.ts) for the full stability policy.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## License
 
 MIT

package/ask-user-question.ts

@@ -65,9 +65,23 @@ function emitPrompt(pi: ExtensionAPI, params: AskUserParams): void {
 	pi.events.emit(ASK_USER_PROMPT_EVENT, payload);
 }
 
+/**
+ * Label Herdr shows for a pane waiting on this dialog. A supervising agent
+ * reads it to tell a question from an Auto Permissions prompt (whose label
+ * is the gate name, e.g. `shell command`).
+ */
+export const HERDR_BLOCKED_LABEL = "question";
+
 function emitBlocked(pi: ExtensionAPI, active: boolean): void {
 	const payload: AskUserBlockedEventPayload = { active };
 	pi.events.emit(ASK_USER_BLOCKED_EVENT, payload);
+	// Herdr's pi integration turns `herdr:blocked` into `agent_status: "blocked"`,
+	// which is how an orchestrator in another pane learns this session is
+	// waiting on a human rather than working. Same contract pi-auto-permissions
+	// uses (`setHerdrBlocked`); duplicated rather than imported, because a
+	// questionnaire must not pull in the permissions engine. No-op outside Herdr.
+	if (process.env.HERDR_ENV !== "1") return;
+	pi.events.emit("herdr:blocked", active ? { active: true, label: HERDR_BLOCKED_LABEL } : { active: false });
 }
 
 export function registerTool(pi: ExtensionAPI): void {
@@ -77,7 +91,7 @@ export function registerTool(pi: ExtensionAPI): void {
 		description: DESCRIPTION,
 		parameters: QuestionParamsSchema,
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const typed = params as unknown as AskUserParams;
 
 			// Backstop only — reconcile.ts should already have stripped the tool
@@ -96,6 +110,11 @@ export function registerTool(pi: ExtensionAPI): void {
 			}
 
 			const session = new QuestionnaireSession(typed);
+			if (signal?.aborted) return buildResponse(session.cancelledResult(), typed);
+
+			let dialog: QuestionnaireDialog | undefined;
+			const cancel = () => dialog?.cancel();
+			signal?.addEventListener("abort", cancel, { once: true });
 			emitPrompt(pi, typed);
 			emitBlocked(pi, true);
 			try {
@@ -110,8 +129,8 @@ export function registerTool(pi: ExtensionAPI): void {
 				// pi-auto-permissions' approval prompt already puts `OptionSelector`.
 				// pi restores the input editor when `done` fires.
 				const result = await ctx.ui.custom<QuestionnaireResult | null>(
-					(tui, theme, _keybindings, done) =>
-						new QuestionnaireDialog({
+					(tui, theme, _keybindings, done) => {
+						dialog = new QuestionnaireDialog({
 							session,
 							theme,
 							// Reuse pi's own markdown theme so previews match the
@@ -119,7 +138,10 @@ export function registerTool(pi: ExtensionAPI): void {
 							markdownTheme: getMarkdownTheme(),
 							done,
 							requestRender: () => tui.requestRender(),
-						}),
+						});
+						if (signal?.aborted) queueMicrotask(() => dialog?.cancel());
+						return dialog;
+					},
 				);
 
 				// `custom()` resolving undefined means the host reported hasUI but
@@ -133,6 +155,7 @@ export function registerTool(pi: ExtensionAPI): void {
 				}
 				return buildResponse(result, typed);
 			} finally {
+				signal?.removeEventListener("abort", cancel);
 				// In `finally` so listeners are never left believing we are still
 				// blocked on a human after a throw.
 				emitBlocked(pi, false);

package/events.ts

@@ -53,3 +53,11 @@ export interface AskUserBlockedEventPayload {
 	/** True while input is awaited; false when the wait ends (answer, cancel, or error). */
 	active: boolean;
 }
+
+/** Emitted after the active tool set has been reconciled for the current run. */
+export const ASK_USER_AVAILABILITY_EVENT = "hank:ask-user:availability" as const;
+
+export interface AskUserAvailabilityEventPayload {
+	/** True only when an interactive global question tool is active and usable. */
+	available: boolean;
+}

package/index.ts

@@ -11,13 +11,16 @@
  * reconcile.ts.
  */
 
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerTool } from "./ask-user-question.ts";
 import { registerReconciler } from "./reconcile.ts";
 
 export {
+	ASK_USER_AVAILABILITY_EVENT,
 	ASK_USER_BLOCKED_EVENT,
 	ASK_USER_PROMPT_EVENT,
+	type AskUserAvailabilityEventPayload,
 	type AskUserBlockedEventPayload,
 	type AskUserPromptEventPayload,
 	type AskUserPromptOption,
@@ -26,5 +29,7 @@ export {
 
 export default function askUserQuestionExtension(pi: ExtensionAPI): void {
 	registerTool(pi);
-	registerReconciler(pi);
+	// Our own location, resolved without touching a runtime action method:
+	// nothing on `pi` may be *called* during extension loading.
+	registerReconciler(pi, fileURLToPath(import.meta.url));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-ask-user-question",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "Structured questionnaire tool for Pi with numbered options, digit hotkeys and Tab-to-comment, composed from the shared permission-selector component.",
   "type": "module",
   "keywords": [
@@ -24,7 +24,7 @@
   },
   "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-ask-user-question#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.19.0"
   },
   "pi": {
     "extensions": [

package/questionnaire.ts

@@ -25,7 +25,7 @@ import {
 	type QuestionnaireResult,
 } from "./tool/schema.ts";
 
-export interface SelectableRow {
+interface SelectableRow {
 	value: string;
 	label: string;
 	description?: string;

package/reconcile.ts

@@ -22,7 +22,10 @@
  * `before_agent_start` runs.
  */
 
+import { realpathSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ASK_USER_AVAILABILITY_EVENT } from "./events.ts";
 import { TOOL_NAME } from "./tool/schema.ts";
 
 /**
@@ -30,18 +33,82 @@ import { TOOL_NAME } from "./tool/schema.ts";
  * already in the right state, the active set (and every sibling tool in it) is
  * left untouched.
  */
-export function reconcileTool(pi: ExtensionAPI, ctx: ExtensionContext): void {
+export function reconcileTool(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	ownSourcePath?: string,
+): boolean {
 	const active = pi.getActiveTools();
 	const present = active.includes(TOOL_NAME);
+	let wrote = false;
 	if (!ctx.hasUI && present) {
 		pi.setActiveTools(active.filter((name) => name !== TOOL_NAME));
-	} else if (ctx.hasUI && !present) {
+		wrote = true;
+	} else if (ctx.hasUI && !present && ownsRegisteredTool(pi, ownSourcePath)) {
 		pi.setActiveTools([...active, TOOL_NAME]);
+		wrote = true;
 	}
+	// Availability is read back from the host, never assumed from the list we
+	// asked for: Pi silently ignores a name that is excluded by --tools or a
+	// tool policy, so an accepted write is not proof the tool is there. Plan
+	// mode drops its own fallback on this signal, and a false positive would
+	// leave an interactive session with no question tool at all.
+	const available =
+		ctx.hasUI && (wrote ? pi.getActiveTools() : active).includes(TOOL_NAME);
+	pi.events?.emit(ASK_USER_AVAILABILITY_EVENT, { available });
+	return available;
 }
 
-export function registerReconciler(pi: ExtensionAPI): void {
+/**
+ * Whether the name is still backed by *this* package's registration.
+ *
+ * Compared by directory, not by exact path: Pi records the extension path as
+ * it was configured (relative, npm-resolved, or synthetic) while `baseDir` is
+ * the resolved directory, and only the directory is stable across all three.
+ * Anything unknowable fails open to "ours", which preserves the original
+ * always-restore behaviour on hosts that report no source information.
+ */
+function ownsRegisteredTool(pi: ExtensionAPI, ownSourcePath?: string): boolean {
+	if (!ownSourcePath || typeof pi.getAllTools !== "function") return true;
+	const effective = pi.getAllTools().find((tool) => tool.name === TOOL_NAME);
+	if (!effective) return true;
+	const info = effective.sourceInfo as { path?: string; baseDir?: string } | undefined;
+	const ownDir = dirname(ownSourcePath);
+	if (info?.baseDir) return sameDirectory(info.baseDir, ownDir);
+	if (info?.path) return sameDirectory(dirname(info.path), ownDir);
+	return true;
+}
+
+/**
+ * Directory equality that survives a symlink on either side.
+ *
+ * `resolve()` alone is not enough, and the asymmetry is guaranteed rather than
+ * unlucky: `ownSourcePath` comes from `import.meta.url`, which Node hands back
+ * already realpath-resolved, while Pi passes `sourceInfo.baseDir` through
+ * untouched (`core/source-info.js`). Any workspace, pnpm, or npm-link install
+ * reaches the package through a symlink, so the two spellings differ for the
+ * same directory — and the caller treats a mismatch as "not ours", which would
+ * strip `ask_user_question` on the first headless run and never restore it,
+ * leaving an interactive session with no question tool at all.
+ *
+ * A `realpathSync` throw (a deleted or unreadable path) falls back to the
+ * lexical form rather than propagating, matching the fail-open posture of
+ * every other branch in `ownsRegisteredTool`.
+ */
+function sameDirectory(a: string, b: string): boolean {
+	const canonical = (path: string): string => {
+		const absolute = resolve(path);
+		try {
+			return realpathSync(absolute);
+		} catch {
+			return absolute;
+		}
+	};
+	return canonical(a) === canonical(b);
+}
+
+export function registerReconciler(pi: ExtensionAPI, ownSourcePath?: string): void {
 	pi.on("before_agent_start", (_event, ctx) => {
-		reconcileTool(pi, ctx);
+		reconcileTool(pi, ctx, ownSourcePath);
 	});
 }

package/tool/envelope.ts

@@ -14,7 +14,7 @@ export const DECLINE_MESSAGE = "User declined to answer questions";
 export const ENVELOPE_PREFIX = "User has answered your questions:";
 export const ENVELOPE_SUFFIX = "You can now continue with the user's answers in mind.";
 
-export interface ToolResult {
+interface ToolResult {
 	content: Array<{ type: "text"; text: string }>;
 	details: QuestionnaireResult;
 }
@@ -28,7 +28,7 @@ export function buildToolResult(text: string, details: QuestionnaireResult): Too
  * preview and the user's note appended when present. Order and wording match
  * rpiv's envelope and are pinned by tests.
  */
-export function buildAnswerSegment(a: QuestionAnswer): string {
+function buildAnswerSegment(a: QuestionAnswer): string {
 	const parts: string[] = [`"${a.question}"="${a.answer}"`];
 	if (a.preview && a.preview.length > 0) parts.push(`selected preview: ${a.preview}`);
 	if (a.notes && a.notes.length > 0) parts.push(`user notes: ${a.notes}`);

package/tool/schema.ts

@@ -12,13 +12,13 @@ import { Type } from "typebox";
 export const TOOL_NAME = "ask_user_question";
 
 export const MIN_OPTIONS = 2;
-export const MAX_OPTIONS = 4;
+const MAX_OPTIONS = 4;
 /**
  * Multi-select questions get a larger cap. Checkboxes are a shortlist UI, not a
  * pick-one UI, so six is where a list stops fitting comfortably above the input
  * dock — not where it stops being a decision.
  */
-export const MAX_MULTI_OPTIONS = 6;
+const MAX_MULTI_OPTIONS = 6;
 export const MIN_QUESTIONS = 1;
 export const MAX_QUESTIONS = 4;
 
@@ -42,7 +42,7 @@ export const CUSTOM_ANSWER_VALUE = "\u0000custom-answer";
 /** Separator joining a multi-select answer's labels into `answer` (spec §5.4). */
 export const MULTI_SELECT_JOIN = ", ";
 
-export const OptionSchema = Type.Object({
+const OptionSchema = Type.Object({
 	label: Type.String({
 		description:
 			"The display text for this option that the user will see and select. Aim for 1-5 words, but there is no hard limit: a longer label is fine when it genuinely helps, and long labels wrap in the dialog rather than being rejected.",
@@ -59,7 +59,7 @@ export const OptionSchema = Type.Object({
 	),
 });
 
-export const QuestionSchema = Type.Object({
+const QuestionSchema = Type.Object({
 	question: Type.String({
 		description:
 			"The complete question to ask the user. Should be clear, specific, and end with a question mark.",
@@ -91,13 +91,13 @@ export const QuestionParamsSchema = Type.Object({
 	}),
 });
 
-export interface OptionParams {
+interface OptionParams {
 	label: string;
 	description: string;
 	preview?: string;
 }
 
-export interface QuestionParams {
+interface QuestionParams {
 	question: string;
 	header: string;
 	/** Checkbox mode: the user may check several options. Default false. */

package/tool/validate.ts

@@ -24,7 +24,7 @@ import {
 	RESERVED_LABELS,
 } from "./schema.ts";
 
-export type ValidationCode =
+type ValidationCode =
 	| "bad_question_count"
 	| "bad_option_count"
 	| "header_too_long"
@@ -33,7 +33,7 @@ export type ValidationCode =
 	| "duplicate_label"
 	| "empty_question";
 
-export interface ValidationError {
+interface ValidationError {
 	code: ValidationCode;
 	message: string;
 }

package/view/dialog.ts

@@ -64,11 +64,11 @@ import type { QuestionnaireSession } from "../questionnaire.ts";
 import type { QuestionnaireResult } from "../tool/schema.ts";
 
 /** Structural subset of pi's Theme used here; keeps the view unit-testable. */
-export interface DialogTheme {
+interface DialogTheme {
 	fg(role: string, text: string): string;
 }
 
-export interface DialogOptions {
+interface DialogOptions {
 	session: QuestionnaireSession;
 	theme?: DialogTheme;
 	/** Called exactly once with the final outcome. */
@@ -215,6 +215,11 @@ export class QuestionnaireDialog {
 		this.opts.done(result);
 	}
 
+	/** Cancel from an external lifecycle signal. Safe to call after user completion. */
+	cancel(): void {
+		this.finish(this.session.cancelledResult());
+	}
+
 	/** True while the free-text custom-answer editor is open. */
 	isTypingCustom(): boolean {
 		return this.tab?.customText !== undefined;