@howaboua/pi-ask 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# @howaboua/pi-ask
+
+## 0.0.6
+
+- Added a Code and Notebook Mode bridge API. This allows extensions that use Pi TUI to run inside `exec`.
+
+## 0.0.5
+
+### Changes
+
+- [#269](https://github.com/IgorWarzocha/howaboua-pi-stuff/pull/269) [`6138ffd`](https://github.com/IgorWarzocha/howaboua-pi-stuff/commit/6138ffd735bb4f7f80e451320dbfd0933a4acaa7) Thanks [@howaclawa](https://github.com/howaclawa)!:
+  - Add shared realtime voice prompts for ask prompts, Auto Trees, Shepherdr settlements, and review progress.
+  - Announce compaction and stream conversational Pi updates after two sentences.
+  - Keep silent tool-step summaries compatible without exposing Chat Completions thinking content.
+  - Configure delegation acknowledgements and deliver V3 delegations immediately.
+  - Preserve late delegations, calls after data-channel closure, prepared Code Mode prompts, and Codex cache continuity.
+  - Reduce LAN playback dropouts with one more jitter-buffer frame.
+
+## 0.0.4
+
+### Changes
+
+- [#131](https://github.com/IgorWarzocha/howaboua-pi-stuff/pull/131) [`828f52e`](https://github.com/IgorWarzocha/howaboua-pi-stuff/commit/828f52eff1291629d73c3058173cff2fa60e3b28) Thanks [@IgorWarzocha](https://github.com/IgorWarzocha)!:
+  - Uses configured Pi keybindings for ask navigation and theme-native TUI colors.
+
+## 0.0.3
+
+### Changes
+
+- [#128](https://github.com/IgorWarzocha/howaboua-pi-stuff/pull/128) [`9604ec3`](https://github.com/IgorWarzocha/howaboua-pi-stuff/commit/9604ec3505eff2d9ee789f42ef45038bc00da02e) Thanks [@IgorWarzocha](https://github.com/IgorWarzocha)!:
+  - Remove the duplicated ask tool name from the model-facing prompt inventory.
+
+## 0.0.2
+
+### Changes
+
+- [#120](https://github.com/IgorWarzocha/howaboua-pi-stuff/pull/120) [`8f82078`](https://github.com/IgorWarzocha/howaboua-pi-stuff/commit/8f82078a8e733dbe770c7b5fd9ad1b20cd5a21af) Thanks [@IgorWarzocha](https://github.com/IgorWarzocha)!:
+  - Report open ask panels as blocked to Herdr's Pi integration.
+
+## 0.0.1
+
+### Changes
+
+- [#113](https://github.com/IgorWarzocha/howaboua-pi-stuff/pull/113) [`f516f97`](https://github.com/IgorWarzocha/howaboua-pi-stuff/commit/f516f97c76ae27a354f80f85a5a34ecd56c4e9c4) Thanks [@IgorWarzocha](https://github.com/IgorWarzocha)!:
+  - Add interactive human input, review triage, and handoff prompts through the `ask` tool, plus configurable `/fold` and `/grill` workflows.

package/README.md

@@ -14,6 +14,8 @@ Try it for one session:
 pi -e npm:@howaboua/pi-ask
 ```
 
+When [Pi Codex](https://www.npmjs.com/package/@howaboua/pi-codex-conversion) 3.0.24 or newer is installed too, `ask` is available inside Code and Notebook Mode as `await tools.ask({ prompts, handoff? })`.
+
 ## How it behaves
 
 The agent can present several independently decidable prompts in one tabbed panel. Each prompt supports a short title, supporting evidence, one or more choices, free text, and an optional comment. Review findings become one prompt each, so you can fix, defer, or reject them without translating a wall of prose back into instructions.
@@ -29,7 +31,7 @@ When Pi runs inside Herdr with its Pi integration installed, an open ask panel m
 - `/fold [report]` turns a long report or structured list into one interactive disposition prompt per item.
 - `/grill [idea]` investigates an idea, asks successive decisions, and keeps the agreed plan in `docs/`.
 
-Both templates are enabled by default. The extension creates `~/.pi/agent/ask.json` on first load:
+Both templates are enabled by default. The extension creates `ask.json` under Pi's agent directory on first load. That is `~/.pi/agent/ask.json` by default. `PI_CODING_AGENT_DIR` changes the agent directory.
 
 ```json
 {

package/ask/contracts.ts

@@ -1,13 +1,11 @@
 import { type Static, Type } from "typebox";
 
-export { OTHER_OPTION_LABEL, REPHRASE_REQUEST_RESPONSE } from "./constants.js";
-
-export const ChoiceSchema = Type.Object({
+const ChoiceSchema = Type.Object({
 	label: Type.String({ description: "Short choice." }),
 	description: Type.Optional(Type.String({ description: "Optional detail." })),
 });
 
-export const PromptSchema = Type.Object({
+const PromptSchema = Type.Object({
 	title: Type.String({ description: "Short prompt." }),
 	body: Type.Optional(Type.String({ description: "Context or evidence." })),
 	multiple: Type.Optional(Type.Boolean({ description: "Allow multiple." })),

package/ask/normalize.ts

@@ -14,7 +14,7 @@ export function textContent(text: string): { type: "text"; text: string } {
 	return { type: "text", text };
 }
 
-export function normalizePromptChoice(choice: unknown): PromptChoice | null {
+function normalizePromptChoice(choice: unknown): PromptChoice | null {
 	if (!isRecord(choice)) return null;
 	const label =
 		typeof choice["label"] === "string" ? choice["label"].trim() : "";
@@ -26,7 +26,7 @@ export function normalizePromptChoice(choice: unknown): PromptChoice | null {
 	return { label, ...(description ? { description } : {}) };
 }
 
-export function normalizePrompt(
+function normalizePrompt(
 	input: unknown,
 	index: number,
 	handoff = false,

package/ask/tool.ts

@@ -16,8 +16,10 @@ type AskInComposer = (
 ) => Promise<unknown>;
 
 interface BlockedState {
+	id: string;
 	active: boolean;
 	label: string;
+	prompt: string;
 }
 
 type OnBlockedChange = (state: BlockedState) => void;
@@ -42,7 +44,7 @@ export function createAskTool({
 			"ask: Do not add Other/rephrase; it is automatic.",
 		],
 		executionMode: "sequential",
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			const { handoff, prompts } = normalizeAskInput(params);
 			if (prompts.length === 0) {
 				throw new Error(
@@ -53,8 +55,12 @@ export function createAskTool({
 				throw new Error("ask requires an interactive UI.");
 
 			const blockedState = {
+				id: toolCallId,
 				active: true,
 				label: handoff ? "Human action needed" : "Waiting for input",
+				prompt: handoff
+					? "The user needs to complete an action before the active work can continue. Please announce this briefly in your natural voice."
+					: "User input is required before the active work can continue. Please announce this briefly in your natural voice.",
 			};
 			onBlockedChange?.(blockedState);
 			let rawResponses: unknown;
@@ -89,11 +95,13 @@ export function createAskTool({
 				details: { kind: handoff ? "handoff" : "prompt", responses },
 			};
 		},
-		renderCall(args, theme) {
+		renderCall(args, theme, context) {
 			const count = Array.isArray(args.prompts) ? args.prompts.length : 0;
 			return new Text(
 				theme.fg(
-					"toolTitle",
+					context && "isBlocked" in context && context.isBlocked === true
+						? "warning"
+						: "toolTitle",
 					theme.bold(args.handoff === true ? "ask handoff " : "ask "),
 				) + theme.fg("muted", `${count} prompt${count === 1 ? "" : "s"}`),
 				0,

package/ask/tui-input.ts

@@ -0,0 +1,145 @@
+import type { KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import type { Editor } from "@earendil-works/pi-tui";
+import type {
+	AskPrompt,
+	AskResponse,
+	PromptChoice,
+	PromptState,
+} from "./contracts.js";
+import { promptStatesToResponses } from "./state.js";
+
+export type EditingKind = "other" | "comment";
+
+export interface AskUiState {
+	tab: number;
+	focus: number;
+	editing: EditingKind | null;
+}
+
+interface EditingInputOptions {
+	advance: () => void;
+	editor: Editor;
+	keybindings: KeybindingsManager;
+	refresh: () => void;
+	saveEditing: (submittedText?: string) => void;
+	state: AskUiState;
+}
+
+export function handleAskEditingInput(
+	data: string,
+	{
+		advance,
+		editor,
+		keybindings,
+		refresh,
+		saveEditing,
+		state,
+	}: EditingInputOptions,
+): void {
+	if (keybindings.matches(data, "tui.input.tab")) {
+		saveEditing(editor.getText());
+		state.editing = null;
+		advance();
+		return;
+	}
+	if (keybindings.matches(data, "tui.select.cancel")) {
+		state.editing = null;
+		refresh();
+		return;
+	}
+	editor.handleInput(data);
+	refresh();
+}
+
+interface PromptInputOptions {
+	advanceWithDefault: () => void;
+	choices: () => PromptChoice[];
+	count: () => number;
+	keybindings: KeybindingsManager;
+	pick: (index: number) => void;
+	refresh: () => void;
+	selectOther: () => void;
+	startEditingComment: () => void;
+	state: AskUiState;
+}
+
+export function handleAskPromptInput(
+	data: string,
+	{
+		advanceWithDefault,
+		choices,
+		count,
+		keybindings,
+		pick,
+		refresh,
+		selectOther,
+		startEditingComment,
+		state,
+	}: PromptInputOptions,
+): void {
+	if (keybindings.matches(data, "tui.select.up")) {
+		state.focus = Math.max(0, state.focus - 1);
+		refresh();
+		return;
+	}
+	if (keybindings.matches(data, "tui.select.down")) {
+		state.focus = Math.min(count() - 1, state.focus + 1);
+		refresh();
+		return;
+	}
+	if (keybindings.matches(data, "tui.input.tab")) {
+		advanceWithDefault();
+		return;
+	}
+	if (!keybindings.matches(data, "tui.select.confirm")) return;
+	if (state.focus === choices().length) {
+		selectOther();
+		return;
+	}
+	if (state.focus === choices().length + 1) {
+		startEditingComment();
+		return;
+	}
+	pick(state.focus);
+}
+
+interface NavigationInputOptions {
+	done: (responses: AskResponse[] | null) => void;
+	isReview: () => boolean;
+	keybindings: KeybindingsManager;
+	promptStates: PromptState[];
+	prompts: AskPrompt[];
+	setTab: (next: number) => void;
+	state: AskUiState;
+}
+
+export function handleAskNavigationInput(
+	data: string,
+	{
+		done,
+		isReview,
+		keybindings,
+		promptStates,
+		prompts,
+		setTab,
+		state,
+	}: NavigationInputOptions,
+): boolean {
+	if (keybindings.matches(data, "tui.select.cancel")) {
+		done(null);
+		return true;
+	}
+	if (keybindings.matches(data, "tui.editor.cursorLeft")) {
+		setTab(state.tab - 1);
+		return true;
+	}
+	if (keybindings.matches(data, "tui.editor.cursorRight")) {
+		setTab(state.tab + 1);
+		return true;
+	}
+	if (!isReview()) return false;
+	if (keybindings.matches(data, "tui.select.confirm")) {
+		done(promptStatesToResponses(prompts, promptStates));
+	}
+	return true;
+}

package/ask/tui-render.ts

@@ -0,0 +1,273 @@
+import {
+	type ExtensionContext,
+	type KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { Editor, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { OTHER_OPTION_LABEL } from "./constants.js";
+import type { AskPrompt, PromptChoice, PromptState } from "./contracts.js";
+import type { AskUiState, EditingKind } from "./tui-input.js";
+
+type AskTheme = ExtensionContext["ui"]["theme"];
+type AskKeybinding = Parameters<KeybindingsManager["getKeys"]>[0];
+type AddLine = (line?: string) => void;
+interface RenderTabsOptions {
+	handoff: boolean;
+	prompts: AskPrompt[];
+	responded: (index: number) => boolean;
+	tab: number;
+	theme: AskTheme;
+}
+
+interface RenderReviewOptions {
+	add: AddLine;
+	handoff: boolean;
+	keybindings: KeybindingsManager;
+	promptStates: PromptState[];
+	prompts: AskPrompt[];
+	theme: AskTheme;
+	width: number;
+}
+
+interface RenderChoiceOptions {
+	add: AddLine;
+	checked: boolean | undefined;
+	choice: PromptChoice;
+	selected: boolean;
+	theme: AskTheme;
+	width: number;
+}
+
+interface RenderPromptOptions {
+	add: AddLine;
+	editor: Editor;
+	handoff: boolean;
+	isEditing: EditingKind | null;
+	keybindings: KeybindingsManager;
+	choices: PromptChoice[];
+	prompt: AskPrompt;
+	promptState: PromptState | undefined;
+	state: AskUiState;
+	theme: AskTheme;
+	width: number;
+}
+
+function addWrapped(
+	add: AddLine,
+	text: string,
+	width: number,
+	indent = "",
+): void {
+	for (const line of wrapTextWithAnsi(
+		text,
+		Math.max(1, width - indent.length),
+	)) {
+		add(`${indent}${line}`);
+	}
+}
+
+function renderKeyHint(
+	theme: AskTheme,
+	keybindings: KeybindingsManager,
+	action: AskKeybinding,
+	description: string,
+): string {
+	return (
+		theme.fg("dim", keybindings.getKeys(action).join("/")) +
+		theme.fg("muted", ` ${description}`)
+	);
+}
+export function renderAskTabs({
+	handoff,
+	prompts,
+	responded,
+	tab,
+	theme,
+}: RenderTabsOptions): string {
+	return ` ${Array.from({ length: prompts.length + 1 }, (_, index) => {
+		const active = index === tab;
+		const label =
+			index === prompts.length
+				? handoff
+					? "Resume"
+					: "Review"
+				: `${responded(index) ? "■" : "□"} ${index + 1}`;
+		return active
+			? theme.bg("selectedBg", theme.fg("text", ` ${label} `))
+			: theme.fg("muted", ` ${label} `);
+	}).join(" ")}`;
+}
+
+export function renderAskReview({
+	add,
+	handoff,
+	keybindings,
+	promptStates,
+	prompts,
+	theme,
+	width,
+}: RenderReviewOptions): void {
+	add(theme.fg("accent", handoff ? " Resume agent" : " Review"));
+	add();
+	prompts.forEach((prompt, index) => {
+		const promptState = promptStates[index];
+		const selections = promptState?.selections ?? [];
+		addWrapped(
+			add,
+			theme.fg("muted", `${index + 1}. ${prompt.title}`),
+			width,
+			" ",
+		);
+		addWrapped(
+			add,
+			theme.fg("text", selections.join(", ") || "No selection"),
+			width,
+			"    ",
+		);
+		if (promptState?.comment.trim()) {
+			addWrapped(
+				add,
+				theme.fg("muted", `Comment: ${promptState.comment.trim()}`),
+				width,
+				"    ",
+			);
+		}
+	});
+	add();
+	addWrapped(
+		add,
+		" " +
+			renderKeyHint(
+				theme,
+				keybindings,
+				"tui.select.confirm",
+				handoff ? "return control" : "submit",
+			) +
+			" • " +
+			renderKeyHint(
+				theme,
+				keybindings,
+				"tui.editor.cursorLeft",
+				"previous prompt",
+			) +
+			" • " +
+			renderKeyHint(
+				theme,
+				keybindings,
+				"tui.editor.cursorRight",
+				"next prompt",
+			) +
+			" • " +
+			renderKeyHint(theme, keybindings, "tui.select.cancel", "dismiss"),
+		width,
+	);
+}
+
+function renderAskChoice({
+	add,
+	checked,
+	choice,
+	selected,
+	theme,
+	width,
+}: RenderChoiceOptions): void {
+	add(
+		`${selected ? theme.fg("accent", "> ") : "  "}${checked ? theme.fg("success", "✓ ") : "  "}${theme.fg(selected ? "accent" : "text", choice.label)}`,
+	);
+	if (choice.description) {
+		addWrapped(add, theme.fg("muted", choice.description), width, "    ");
+	}
+}
+
+export function renderAskPrompt({
+	add,
+	editor,
+	handoff,
+	isEditing,
+	keybindings,
+	choices,
+	prompt,
+	promptState,
+	state,
+	theme,
+	width,
+}: RenderPromptOptions): void {
+	if (handoff) {
+		add(theme.fg("accent", " Human action needed"));
+		add();
+	}
+	addWrapped(add, theme.fg("text", prompt.title), width, " ");
+	add(
+		theme.fg(
+			"muted",
+			` ${prompt.multiple ? "Choose any that apply" : "Choose one"}`,
+		),
+	);
+	if (prompt.body) {
+		add();
+		addWrapped(add, theme.fg("muted", prompt.body), width, "   ");
+	}
+	add();
+	choices.forEach((choice, index) => {
+		renderAskChoice({
+			add,
+			checked: promptState?.selections.includes(choice.label),
+			choice,
+			selected: state.focus === index,
+			theme,
+			width,
+		});
+	});
+	const selectedOther = state.focus === choices.length;
+	add(
+		`${selectedOther ? theme.fg("accent", "> ") : "  "}${promptState?.customEnabled ? theme.fg("success", "✓ ") : "  "}${theme.fg(selectedOther ? "accent" : "muted", OTHER_OPTION_LABEL)}${promptState?.customText.trim() ? theme.fg("text", `: ${promptState.customText.trim()}`) : ""}`,
+	);
+	if (isEditing === "other") {
+		add();
+		for (const line of editor.render(width - 2)) add(` ${line}`);
+	}
+	const selectedComment = state.focus === choices.length + 1;
+	add();
+	add(
+		`${selectedComment ? theme.fg("accent", "> ") : "  "}${theme.fg(selectedComment ? "accent" : "text", "Comment (optional)")}`,
+	);
+	if (promptState?.comment.trim()) {
+		addWrapped(
+			add,
+			theme.fg("muted", promptState.comment.trim()),
+			width,
+			"    ",
+		);
+	}
+	if (isEditing === "comment") {
+		add();
+		for (const line of editor.render(width - 2)) add(` ${line}`);
+	}
+	add();
+	if (isEditing) {
+		addWrapped(
+			add,
+			" " +
+				renderKeyHint(theme, keybindings, "tui.input.submit", "save") +
+				" • " +
+				renderKeyHint(theme, keybindings, "tui.input.tab", "next/default") +
+				" • " +
+				renderKeyHint(theme, keybindings, "tui.select.cancel", "cancel edit"),
+			width,
+		);
+		return;
+	}
+	addWrapped(
+		add,
+		" " +
+			renderKeyHint(theme, keybindings, "tui.select.up", "up") +
+			" • " +
+			renderKeyHint(theme, keybindings, "tui.select.down", "down") +
+			" • " +
+			renderKeyHint(theme, keybindings, "tui.select.confirm", "choose/type") +
+			" • " +
+			renderKeyHint(theme, keybindings, "tui.input.tab", "next/default") +
+			" • blank Other/rephrase = follow-up • " +
+			renderKeyHint(theme, keybindings, "tui.select.cancel", "close"),
+		width,
+	);
+}