pi-ask-herdr 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# pi-ask-herdr
+
+A Pi extension that adds an `ask_user` tool, with optional integration with
+[Herdr](https://herdr.dev) notifications and agent state.
+
+## Structure
+
+```text
+index.ts      # Pi auto-discovery entry point
+src/
+  tool.ts     # Tool registration and parameter schema
+  ui.ts       # TUI prompts (text, confirm, select, multiselect)
+  herdr.ts    # Herdr socket / event-bus integration
+  options.ts  # Option normalization and display formatting
+  types.ts    # Shared TypeScript types
+```
+
+## What it does
+
+- Registers an `ask_user` tool that can ask the user for:
+  - free-form text (`type: "text"`)
+  - yes/no confirmation (`type: "confirm"`)
+  - single choice from a list (`type: "select"`)
+  - multiple choices from a list (`type: "multiselect"`)
+- Waits for the answer and returns it to the agent.
+- For `select` and `multiselect`, an **"Other (custom)"** option is always
+  available so the user can type their own answer.
+- For `confirm`, you can enable the same custom option with
+  `"allow_custom": true`.
+- No extra slash command is registered — only the `ask_user` tool.
+- When Pi runs inside a Herdr pane, it:
+  - reports the pane state as `blocked` while waiting
+  - sends a Herdr toast notification so the user knows input is needed
+  - restores the pane state after the user answers
+
+## Install
+
+### From npm (recommended)
+
+```bash
+pi install npm:pi-ask-herdr
+```
+
+Then reload Pi with `/reload`.
+
+### From git
+
+```bash
+pi install git:github.com/leset0ng/pi-ask-herdr@v0.1.0
+```
+
+### Manual
+
+Copy or clone this directory into Pi's extensions folder:
+
+```bash
+# Global
+cp -R pi-ask-herdr ~/.pi/agent/extensions/
+
+# Or project-local
+cp -R pi-ask-herdr .pi/extensions/
+```
+
+Then reload Pi with `/reload`, or test it directly with:
+
+```bash
+pi -e ~/.pi/agent/extensions/pi-ask-herdr/index.ts
+```
+
+## Tool usage
+
+Simple string options:
+
+```json
+{
+  "question": "Which database should we use?",
+  "type": "select",
+  "options": ["PostgreSQL", "SQLite", "MySQL"]
+}
+```
+
+Options with descriptions:
+
+```json
+{
+  "question": "Which database should we use?",
+  "type": "select",
+  "options": [
+    { "label": "PostgreSQL", "description": "Full-featured relational database" },
+    { "label": "SQLite", "description": "Zero-config file database" },
+    { "label": "MySQL", "description": "Widely used open-source RDBMS" }
+  ]
+}
+```
+
+### Parameters
+
+| Name         | Type                 | Required | Description                                      |
+|--------------|----------------------|----------|--------------------------------------------------|
+| question     | string               | yes      | The question to display                          |
+| type         | string               | no       | `"text"`, `"confirm"`, `"select"`, `"multiselect"` (default: text) |
+| options      | string[] or object[] | no       | Required when `type` is `select` or `multiselect`. Each item can be a string or `{ "label": string, "description"?: string }` |
+| default      | string               | no       | Prefilled value for text input                               |
+| timeout      | number               | no       | Auto-cancel after N milliseconds                             |
+| allow_custom | boolean              | no       | For `confirm`: also offer "Other (custom)"                   |
+
+## Herdr integration
+
+The extension detects Herdr via the environment variables that Herdr injects
+into its panes:
+
+- `HERDR_ENV=1`
+- `HERDR_SOCKET_PATH`
+- `HERDR_PANE_ID`
+
+If these are present, the extension:
+
+- emits `herdr:blocked` with `active: true` before prompting (the official
+  Herdr Pi integration turns this into a `blocked` pane state)
+- calls `notification.show` with the question as the body
+- emits `herdr:blocked` with `active: false` after the user answers
+
+No extra configuration is required.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,15 @@
+/**
+ * pi-ask-herdr
+ *
+ * A Pi extension that adds an `ask_user` tool and integrates with Herdr.
+ *
+ * Source modules live under `./src/`; this file is only the auto-discovered
+ * entry point that Pi loads.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerAskuserTool } from "./src/tool.ts";
+
+export default function askuserHerdr(pi: ExtensionAPI) {
+	registerAskuserTool(pi);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pi-ask-herdr",
+  "version": "0.1.0",
+  "description": "Pi extension that adds an ask_user tool and integrates with Herdr notifications/agent state.",
+  "type": "module",
+  "main": "./index.ts",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "herdr",
+    "ask-user"
+  ],
+  "homepage": "https://github.com/leset0ng/pi-ask-herdr#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leset0ng/pi-ask-herdr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/leset0ng/pi-ask-herdr/issues"
+  },
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "src/**/*",
+    "README.md",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/herdr.ts

@@ -0,0 +1,98 @@
+/**
+ * Herdr integration helpers.
+ *
+ * - Detects whether Pi is running inside a Herdr pane.
+ * - Sends toast notifications via the Herdr Unix socket.
+ * - Reports blocked/working state through the official Herdr Pi integration
+ *   event bus (`herdr:blocked`).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createConnection } from "node:net";
+
+export function isHerdrEnv(): boolean {
+	return process.env.HERDR_ENV === "1" && !!process.env.HERDR_SOCKET_PATH && !!process.env.HERDR_PANE_ID;
+}
+
+function herdrSocketPath(): string | undefined {
+	return process.env.HERDR_SOCKET_PATH;
+}
+
+/**
+ * Send a single JSON-RPC-style request to the Herdr Unix socket and return
+ * the matching result. Herdr speaks newline-delimited JSON.
+ */
+function herdrRequest<T>(method: string, params: object): Promise<T | undefined> {
+	const socketPath = herdrSocketPath();
+	if (!socketPath) return Promise.resolve(undefined);
+
+	const id = `askuser-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+	return new Promise<T | undefined>((resolve, reject) => {
+		let buffer = "";
+		const client = createConnection(socketPath);
+
+		const timer = setTimeout(() => {
+			client.end();
+			reject(new Error("herdr socket timeout"));
+		}, 5000);
+
+		client.on("connect", () => {
+			client.write(JSON.stringify({ id, method, params }) + "\n");
+		});
+
+		client.on("data", (data) => {
+			buffer += data.toString("utf8");
+		});
+
+		client.on("end", () => {
+			clearTimeout(timer);
+			const lines = buffer
+				.split("\n")
+				.map((l) => l.trim())
+				.filter(Boolean);
+
+			for (const line of lines) {
+				try {
+					const msg = JSON.parse(line) as { id?: string; result?: T; error?: { message: string } };
+					if (msg.id === id) {
+						if (msg.error) {
+							reject(new Error(msg.error.message));
+						} else {
+							resolve(msg.result);
+						}
+						return;
+					}
+				} catch {
+					// ignore malformed lines
+				}
+			}
+			resolve(undefined);
+		});
+
+		client.on("error", (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+
+export async function herdrNotify(title: string, body: string) {
+	try {
+		await herdrRequest<{ type: string; shown: boolean; reason?: string }>("notification.show", {
+			title,
+			body,
+			sound: "request",
+		});
+	} catch (err) {
+		console.error("[pi-ask-herdr] notification.show failed:", err);
+	}
+}
+
+export function setHerdrBlocked(pi: ExtensionAPI, active: boolean, label?: string) {
+	try {
+		pi.events.emit("herdr:blocked", { active, label });
+	} catch (err) {
+		console.error("[pi-ask-herdr] failed to emit herdr:blocked:", err);
+	}
+}

package/src/options.ts

@@ -0,0 +1,28 @@
+/**
+ * Option normalization and display formatting for select / multiselect.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { OptionItem, OptionObject } from "./types.ts";
+
+export function normalizeOptions(options: (string | OptionObject)[]): OptionItem[] {
+	return options.map((opt) => {
+		if (typeof opt === "string") {
+			return { label: opt, value: opt };
+		}
+		return { label: opt.label, value: opt.label, description: opt.description };
+	});
+}
+
+/**
+ * Bold the label when a description is present so described options stand out.
+ */
+export function formatOptionDisplay(
+	item: OptionItem,
+	theme: ExtensionContext["ui"]["theme"],
+): string {
+	if (!item.description) {
+		return item.label;
+	}
+	return `${theme.bold(item.label)} — ${item.description}`;
+}

package/src/tool.ts

@@ -0,0 +1,119 @@
+/**
+ * Tool registration for ask_user.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { isHerdrEnv, herdrNotify, setHerdrBlocked } from "./herdr.ts";
+import { askInTui, renderAnswer } from "./ui.ts";
+import type { AskDetails } from "./types.ts";
+
+export function registerAskuserTool(pi: ExtensionAPI) {
+	const OptionSchema = Type.Object({
+		label: Type.String({ description: "Display label and returned value" }),
+		description: Type.Optional(Type.String({ description: "Optional longer description shown in the menu" })),
+	});
+
+	const AskParamsSchema = Type.Object({
+		question: Type.String({ description: "The question to ask the user" }),
+		type: Type.Optional(
+			StringEnum(["text", "confirm", "select", "multiselect"] as const, {
+				description: "Input type: text (default), confirm, select, or multiselect",
+			}),
+		),
+		options: Type.Optional(
+			Type.Array(Type.Union([Type.String(), OptionSchema]), {
+				description: "Required when type is select or multiselect; items can be strings or {label, description?}",
+			}),
+		),
+		default: Type.Optional(Type.String({ description: "Default value for text input" })),
+		timeout: Type.Optional(
+			Type.Number({ description: "Optional timeout in milliseconds before auto-cancelling" }),
+		),
+		allow_custom: Type.Optional(
+			Type.Boolean({
+				description:
+					"For confirm: also offer an 'Other (custom)' explain option. For select/multiselect it is always enabled.",
+			}),
+		),
+	});
+
+	pi.registerTool({
+		name: "ask_user",
+		label: "Ask User",
+		description:
+			"Ask the user a question and wait for an answer. Use when you need user input to continue.",
+		promptSnippet: "Prompt the user for input when the next step depends on a choice or missing detail.",
+		promptGuidelines: [
+			"Use ask_user only when the task cannot proceed without user input.",
+			"For ask_user with type 'select' or 'multiselect', always provide the options array.",
+			"Keep the question concise but include enough context for the user to answer.",
+			"Users can always choose 'Other (custom)' for select/multiselect to type their own answer.",
+			"Use { label, description } objects for options when the user needs extra context to decide.",
+		],
+		parameters: AskParamsSchema,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
+			// Guard against non-interactive invocations.
+			if (ctx.mode !== "tui") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "ask_user can only be used in interactive TUI mode.",
+						},
+					],
+					details: {
+						question: params.question,
+						type: params.type ?? "text",
+						options: params.options,
+						answer: null,
+						cancelled: true,
+					} satisfies AskDetails,
+				};
+			}
+
+			// Validate select/multiselect input up front.
+			if (
+				(params.type === "select" || params.type === "multiselect") &&
+				(!params.options || params.options.length === 0)
+			) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `ask_user error: type '${params.type}' requires an options array.`,
+						},
+					],
+					details: {
+						question: params.question,
+						type: params.type,
+						options: params.options,
+						answer: null,
+						cancelled: true,
+					} satisfies AskDetails,
+				};
+			}
+
+			// Tell Herdr that this pane is blocked waiting for input.
+			if (isHerdrEnv()) {
+				setHerdrBlocked(pi, true, "ask_user");
+				await herdrNotify("Pi needs input", params.question);
+			}
+
+			const details = await askInTui(params, ctx);
+
+			// Restore agent state now that the prompt is done.
+			if (isHerdrEnv()) {
+				setHerdrBlocked(pi, false);
+			}
+
+			return {
+				content: [{ type: "text", text: renderAnswer(details) }],
+				details,
+			};
+		},
+	});
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared types for the pi-ask-herdr extension.
+ */
+
+export type AskType = "text" | "confirm" | "select" | "multiselect";
+
+export interface OptionObject {
+	label: string;
+	description?: string;
+}
+
+export interface AskParams {
+	question: string;
+	type?: AskType;
+	options?: (string | OptionObject)[];
+	default?: string;
+	timeout?: number;
+	allow_custom?: boolean;
+}
+
+export interface OptionItem {
+	label: string;
+	value: string;
+	description?: string;
+}
+
+export interface AskDetails {
+	question: string;
+	type: AskType;
+	options: (string | OptionObject)[] | undefined;
+	answer: string | boolean | string[] | null;
+	cancelled: boolean;
+	custom?: boolean;
+}
+
+// Sentinel value used internally for the "Other (custom)" menu item.
+export const CUSTOM_SENTINEL = "__askuser_custom__";
+export const CUSTOM_LABEL = "✎ Other (custom)";

package/src/ui.ts

@@ -0,0 +1,248 @@
+/**
+ * TUI prompting implementation for the ask_user tool.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AskDetails, AskParams, AskType, OptionItem } from "./types.ts";
+import { CUSTOM_LABEL } from "./types.ts";
+import { formatOptionDisplay, normalizeOptions } from "./options.ts";
+
+function makeSignal(timeout?: number): AbortSignal | undefined {
+	if (!timeout || timeout <= 0) return undefined;
+	const controller = new AbortController();
+	setTimeout(() => controller.abort(), timeout);
+	return controller.signal;
+}
+
+async function askText(params: AskParams, ctx: ExtensionContext): Promise<AskDetails> {
+	const signal = makeSignal(params.timeout);
+	const text = await ctx.ui.input(params.question, params.default ?? "", signal ? { signal } : undefined);
+	return {
+		question: params.question,
+		type: "text",
+		options: undefined,
+		answer: text ?? null,
+		cancelled: text === null,
+	};
+}
+
+async function askConfirm(params: AskParams, ctx: ExtensionContext): Promise<AskDetails> {
+	const signal = makeSignal(params.timeout);
+	const allowCustom = params.allow_custom ?? false;
+
+	if (!allowCustom) {
+		const ok = await ctx.ui.confirm(params.question, undefined, signal ? { signal } : undefined);
+		return {
+			question: params.question,
+			type: "confirm",
+			options: undefined,
+			answer: ok === null ? null : ok,
+			cancelled: ok === null,
+		};
+	}
+
+	const options = ["Yes", "No", CUSTOM_LABEL];
+	const choice = await ctx.ui.select(params.question, options, signal ? { signal } : undefined);
+
+	if (choice === null) {
+		return {
+			question: params.question,
+			type: "confirm",
+			options: undefined,
+			answer: null,
+			cancelled: true,
+		};
+	}
+
+	if (choice === CUSTOM_LABEL) {
+		const text = await ctx.ui.input("Please explain your choice:");
+		return {
+			question: params.question,
+			type: "confirm",
+			options: undefined,
+			answer: text ?? null,
+			cancelled: text === null,
+			custom: true,
+		};
+	}
+
+	return {
+		question: params.question,
+		type: "confirm",
+		options: undefined,
+		answer: choice === "Yes",
+		cancelled: false,
+	};
+}
+
+async function askSelect(params: AskParams, ctx: ExtensionContext): Promise<AskDetails> {
+	const rawOptions = params.options ?? [];
+	if (rawOptions.length === 0) {
+		ctx.ui.notify("ask_user: select requires options", "error");
+		return {
+			question: params.question,
+			type: "select",
+			options: rawOptions,
+			answer: null,
+			cancelled: true,
+		};
+	}
+
+	const normalized = normalizeOptions(rawOptions);
+	const items = normalized.map((o) => ({
+		...o,
+		display: formatOptionDisplay(o, ctx.ui.theme),
+	}));
+	const displayOptions = [...items.map((o) => o.display), CUSTOM_LABEL];
+	const choice = await ctx.ui.select(params.question, displayOptions);
+
+	if (choice === null) {
+		return {
+			question: params.question,
+			type: "select",
+			options: rawOptions,
+			answer: null,
+			cancelled: true,
+		};
+	}
+
+	if (choice === CUSTOM_LABEL) {
+		const text = await ctx.ui.input("Enter your custom answer:");
+		return {
+			question: params.question,
+			type: "select",
+			options: rawOptions,
+			answer: text ?? null,
+			cancelled: text === null,
+			custom: true,
+		};
+	}
+
+	const picked = items.find((o) => o.display === choice);
+	return {
+		question: params.question,
+		type: "select",
+		options: rawOptions,
+		answer: picked?.value ?? choice,
+		cancelled: false,
+	};
+}
+
+async function askMultiselect(params: AskParams, ctx: ExtensionContext): Promise<AskDetails> {
+	const rawOptions = params.options ?? [];
+	if (rawOptions.length === 0) {
+		ctx.ui.notify("ask_user: multiselect requires options", "error");
+		return {
+			question: params.question,
+			type: "multiselect",
+			options: rawOptions,
+			answer: null,
+			cancelled: true,
+		};
+	}
+
+	const normalized = normalizeOptions(rawOptions);
+	let optionItems: Array<OptionItem & { display: string }> = normalized.map((o) => ({
+		...o,
+		display: formatOptionDisplay(o, ctx.ui.theme),
+	}));
+	const selected = new Set<string>();
+
+	while (true) {
+		const displayOptions: string[] = ["✓ Done", "✗ Cancel", CUSTOM_LABEL];
+		for (const item of optionItems) {
+			const prefix = selected.has(item.value) ? "[x]" : "[ ]";
+			displayOptions.push(`${prefix} ${item.display}`);
+		}
+
+		const choice = await ctx.ui.select(params.question, displayOptions);
+
+		if (choice === null || choice === "✗ Cancel") {
+			return {
+				question: params.question,
+				type: "multiselect",
+				options: rawOptions,
+				answer: null,
+				cancelled: true,
+			};
+		}
+
+		if (choice === "✓ Done") {
+			return {
+				question: params.question,
+				type: "multiselect",
+				options: rawOptions,
+				answer: Array.from(selected),
+				cancelled: false,
+			};
+		}
+
+		if (choice === CUSTOM_LABEL) {
+			const text = await ctx.ui.input("Enter a custom value to add:");
+			if (text) {
+				if (!optionItems.some((i) => i.value === text)) {
+					optionItems.push({
+						label: text,
+						value: text,
+						display: text,
+					});
+				}
+				selected.add(text);
+			}
+			continue;
+		}
+
+		// Toggle a regular option.
+		const display = choice.replace(/^\[[x ]\] /, "");
+		const item = optionItems.find((i) => i.display === display);
+		const value = item?.value ?? display;
+		if (selected.has(value)) {
+			selected.delete(value);
+		} else {
+			selected.add(value);
+		}
+	}
+}
+
+export async function askInTui(params: AskParams, ctx: ExtensionContext): Promise<AskDetails> {
+	const question = params.question.trim();
+	if (!question) {
+		return {
+			question: "",
+			type: params.type ?? "text",
+			options: params.options,
+			answer: null,
+			cancelled: true,
+		};
+	}
+
+	const type: AskType = params.type ?? "text";
+	switch (type) {
+		case "confirm":
+			return askConfirm(params, ctx);
+		case "select":
+			return askSelect(params, ctx);
+		case "multiselect":
+			return askMultiselect(params, ctx);
+		case "text":
+		default:
+			return askText(params, ctx);
+	}
+}
+
+export function renderAnswer(details: AskDetails): string {
+	if (details.cancelled) {
+		return "User cancelled the prompt.";
+	}
+	if (details.answer === null) {
+		return "No answer provided.";
+	}
+	if (typeof details.answer === "boolean") {
+		return details.answer ? "User answered yes." : "User answered no.";
+	}
+	if (Array.isArray(details.answer)) {
+		if (details.answer.length === 0) return "User selected nothing.";
+		return `User selected: ${details.answer.join(", ")}`;
+	}
+	return `User answered: ${details.answer}`;
+}