@howaboua/pi-ask 0.0.10 → 0.0.12

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @howaboua/pi-ask
 
+## 0.0.12
+
+- ### Improvements
+  - Ask returns help when called without arguments, including an empty structured object. Explicit help remains supported.
+
+## 0.0.11
+
+- Parents can receive and answer asynchronous questions through Shepherdr while workers continue.
+
 ## 0.0.10
 
 - Requires Pi 1.0.0 or later.

package/ask/contracts.ts

@@ -16,8 +16,9 @@ const PromptSchema = Type.Object({
 });
 
 export const AskParameters = Type.Object({
+	help: Type.Optional(Type.Literal(true)),
 	handoff: Type.Optional(Type.Boolean()),
-	prompts: Type.Array(PromptSchema),
+	prompts: Type.Optional(Type.Array(PromptSchema)),
 	delivery: Type.Optional(StringEnum(ASK_DELIVERIES)),
 });
 

package/ask/coordinator.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { AskPrompt, PendingAsk } from "./contracts.js";
+import type { AskPrompt, AskResponse, PendingAsk } from "./contracts.js";
 import { normalizeResponses, summarizeResponses } from "./normalize.js";
 import type { PendingAskUpdate } from "./pending.js";
 import { askWithPiUi } from "./pi-ui.js";
@@ -14,6 +14,7 @@ export interface AskCoordinatorOptions {
 	askInComposer?: AskInComposer;
 	deliverSteer?: (message: string) => void;
 	onPendingChange?: (update: PendingAskUpdate) => void;
+	onSteerActiveChange?: (request: PendingAsk, active: boolean) => void;
 }
 
 interface PresentAskOptions {
@@ -34,11 +35,13 @@ export function createAskCoordinator({
 	askInComposer,
 	deliverSteer,
 	onPendingChange,
+	onSteerActiveChange,
 }: AskCoordinatorOptions = {}) {
 	let generation = 0;
 	let sessionAbort = new AbortController();
 	let presentationTail = Promise.resolve();
 	const activeSteers = new Set<string>();
+	let presentedSteer: PendingAsk | undefined;
 
 	const present = (
 		ctx: ExtensionContext,
@@ -95,10 +98,19 @@ export function createAskCoordinator({
 		}
 	};
 
-	const close = (ctx: ExtensionContext, id: string) => {
+	const close = (
+		ctx: ExtensionContext,
+		id: string,
+		responses?: AskResponse[],
+	) => {
 		activeSteers.delete(id);
 		try {
-			onPendingChange?.({ version: 1, state: "closed", id });
+			onPendingChange?.({
+				version: 1,
+				state: "closed",
+				id,
+				...(responses ? { responses } : { dismissed: true }),
+			});
 		} catch (error) {
 			notifyFailure(ctx, error);
 		}
@@ -123,12 +135,22 @@ export function createAskCoordinator({
 		void present(ctx, request.prompts, {
 			steering: true,
 			signal: sessionAbort.signal,
+			onActiveChange: (active) => {
+				if (requestGeneration === generation && !sessionAbort.signal.aborted) {
+					presentedSteer = active ? request : undefined;
+					onSteerActiveChange?.(request, active);
+				}
+			},
 		}).then(
 			(responses) => {
 				if (requestGeneration !== generation || sessionAbort.signal.aborted)
 					return;
 				if (deliver(ctx, steerResponse(request.prompts, responses)))
-					close(ctx, request.id);
+					close(
+						ctx,
+						request.id,
+						normalizeResponses(request.prompts, responses) ?? undefined,
+					);
 			},
 			(error: unknown) => {
 				if (requestGeneration !== generation || sessionAbort.signal.aborted)
@@ -153,6 +175,7 @@ export function createAskCoordinator({
 		},
 		restorePending(pending: readonly PendingAsk[], ctx: ExtensionContext) {
 			generation++;
+			presentedSteer = undefined;
 			sessionAbort.abort();
 			sessionAbort = new AbortController();
 			presentationTail = Promise.resolve();
@@ -161,9 +184,14 @@ export function createAskCoordinator({
 			for (const request of pending) startSteer(request, ctx, false);
 		},
 		shutdown() {
-			generation++;
-			sessionAbort.abort();
-			activeSteers.clear();
+			try {
+				if (presentedSteer) onSteerActiveChange?.(presentedSteer, false);
+			} finally {
+				presentedSteer = undefined;
+				generation++;
+				sessionAbort.abort();
+				activeSteers.clear();
+			}
 		},
 		get sessionSignal(): AbortSignal {
 			return sessionAbort.signal;

package/ask/normalize.ts

@@ -52,6 +52,13 @@ export function isSteeringAskInput(input: unknown): boolean {
 	);
 }
 
+export function isAskHelpInput(input: unknown): boolean {
+	if (input === undefined) return true;
+	if (!isRecord(input) || Array.isArray(input)) return false;
+	const keys = Object.keys(input);
+	return keys.length === 0 || (keys.length === 1 && input["help"] === true);
+}
+
 export function normalizeAskInput(params: unknown): {
 	delivery: "wait" | "steer";
 	handoff: boolean;

package/ask/pending.ts

@@ -1,12 +1,18 @@
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
-import type { AskPrompt, PendingAsk } from "./contracts.js";
+import type { AskPrompt, AskResponse, PendingAsk } from "./contracts.js";
 import { normalizeAskInput } from "./normalize.js";
 
 export const PENDING_ASK_ENTRY_TYPE = "pi-ask-pending";
 
 export type PendingAskUpdate =
 	| { version: 1; state: "pending"; id: string; prompts: AskPrompt[] }
-	| { version: 1; state: "closed"; id: string };
+	| {
+			version: 1;
+			state: "closed";
+			id: string;
+			responses?: AskResponse[];
+			dismissed?: boolean;
+	  };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;

package/ask/tool.ts

@@ -6,6 +6,7 @@ import {
 	createAskCoordinator,
 } from "./coordinator.js";
 import {
+	isAskHelpInput,
 	isSteeringAskInput,
 	normalizeAskInput,
 	normalizeResponses,
@@ -33,25 +34,38 @@ export function createAskRuntime({
 	deliverSteer,
 	onBlockedChange,
 	onPendingChange,
+	onSteerActiveChange,
 }: AskToolOptions = {}) {
 	const coordinator = createAskCoordinator({
 		...(askInComposer ? { askInComposer } : {}),
 		...(deliverSteer ? { deliverSteer } : {}),
 		...(onPendingChange ? { onPendingChange } : {}),
+		...(onSteerActiveChange ? { onSteerActiveChange } : {}),
 	});
 
 	const tool = defineTool({
 		name: "ask",
 		label: "Ask",
-		description: "Request user input or action",
+		description: "Request user input or action; {} for help",
 		parameters: AskParameters,
-		promptGuidelines: [
-			"ask: Omit delivery to wait; steer only while reversible work can continue. Handoffs wait for user action; state the completion signal",
-			"ask: For reviews, make each finding a prompt with disposition choices; do not report first.",
-			"ask: Other/rephrase is automatic; omit choices for free text",
-		],
 		executionMode: "sequential",
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			if (isAskHelpInput(params)) {
+				return {
+					content: [
+						textContent(
+							[
+								"ask({}) or ask({ help: true }) returns help",
+								'ask({ prompts: [{ title, body?, multiple?, choices?: [{ label, description? }] }], delivery?: "wait"|"steer", handoff? })',
+								"Omit delivery to wait; steer only while reversible work can continue. Handoffs wait for user action; state the completion signal",
+								"For reviews, make each finding a prompt with disposition choices; do not report first",
+								"Other/rephrase is automatic; omit choices for free text. Blank Other/rephrase means rephrase or follow up",
+							].join("\n"),
+						),
+					],
+					details: { kind: "help" },
+				};
+			}
 			const { delivery, handoff, prompts } = normalizeAskInput(params);
 			if (prompts.length === 0) {
 				throw new Error(
@@ -70,7 +84,7 @@ export function createAskRuntime({
 				return {
 					content: [
 						textContent(
-							"Question presented. Continue working; the response will arrive as steering.",
+							"Question queued. Continue working; the response will arrive as steering.",
 						),
 					],
 					details: { kind: "prompt", pending: true, id: toolCallId },
@@ -113,6 +127,8 @@ export function createAskRuntime({
 			};
 		},
 		renderCall(args, theme, context) {
+			if (isAskHelpInput(args))
+				return new Text(theme.fg("toolTitle", theme.bold("ask help")), 0, 0);
 			const count = Array.isArray(args.prompts) ? args.prompts.length : 0;
 			const label =
 				args.handoff === true

package/index.ts

@@ -9,7 +9,7 @@ import {
 	createSteerDelivery,
 	type TryCodexDeveloperMessage,
 } from "./ask/delivery.js";
-import { isSteeringAskInput } from "./ask/normalize.js";
+import { isAskHelpInput, isSteeringAskInput } from "./ask/normalize.js";
 import { PENDING_ASK_ENTRY_TYPE, readPendingAsks } from "./ask/pending.js";
 import { createAskRuntime, createAskTool } from "./ask/tool.js";
 import registerPackageChangelog from "./changelog.js";
@@ -62,6 +62,20 @@ export default async function humanInTheLoop(pi: ExtensionAPI): Promise<void> {
 		onPendingChange: (update) => {
 			pi.appendEntry(PENDING_ASK_ENTRY_TYPE, update);
 		},
+		onSteerActiveChange: (request, active) => {
+			pi.appendEntry(
+				"pi-ask-active",
+				active
+					? {
+							version: 1,
+							state: "active",
+							id: request.id,
+							delivery: "steer",
+							prompts: request.prompts,
+						}
+					: { version: 1, state: "closed", id: request.id },
+			);
+		},
 	});
 	const ask = askRuntime.tool;
 	const restorePending = (ctx: ExtensionContext) => {
@@ -113,9 +127,9 @@ async function registerAskInCodeMode(
 			await import("@howaboua/pi-codex-conversion/code-mode");
 		const registration = registerCodeModeExtensionTools(pi, () => [
 			adaptToolForCodeMode(ask, {
-				blocking: (input) => !isSteeringAskInput(input),
-				usage:
-					'await tools.ask({ prompts: [{ title, body?, multiple?, choices?: [{ label, description? }] }], delivery?: "wait"|"steer", handoff? })',
+				blocking: (input) =>
+					!isAskHelpInput(input) && !isSteeringAskInput(input),
+				usage: "await tools.ask() // help",
 			}),
 		]);
 		pi.on("session_shutdown", () => registration.unregister());

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@howaboua/pi-ask",
-	"version": "0.0.10",
+	"version": "0.0.12",
 	"description": "Interactive decisions, review triage, and human handoffs for Pi.",
 	"type": "module",
 	"license": "MIT",
@@ -45,7 +45,7 @@
 		]
 	},
 	"peerDependencies": {
-		"@howaboua/pi-codex-conversion": ">=3.0.43",
+		"@howaboua/pi-codex-conversion": ">=3.0.48",
 		"@earendil-works/pi-ai": ">=1.0.0",
 		"@earendil-works/pi-coding-agent": ">=1.0.0",
 		"@earendil-works/pi-tui": ">=1.0.0",
@@ -57,18 +57,17 @@
 		}
 	},
 	"devDependencies": {
-		"@howaboua/pi-codex-conversion": "3.0.43",
+		"@howaboua/pi-codex-conversion": "3.0.48",
 		"@biomejs/biome": "^2.5.10",
-		"@earendil-works/pi-ai": "1.0.0",
-		"@earendil-works/pi-coding-agent": "1.0.0",
-		"@earendil-works/pi-tui": "1.0.0",
+		"@earendil-works/pi-ai": "1.1.0",
+		"@earendil-works/pi-coding-agent": "1.1.0",
+		"@earendil-works/pi-tui": "1.1.0",
 		"typebox": "1.3.18",
 		"typescript": "^7.0.2"
 	},
 	"scripts": {
-		"check": "bun run lint && bun run typecheck && bun run test",
+		"check": "bun run lint && bun run typecheck",
 		"prepack": "bun run check",
-		"test": "bun test",
 		"typecheck": "tsgo --noEmit",
 		"lint": "biome check .",
 		"format": "biome check --write .",