@howaboua/pi-ask 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @howaboua/pi-ask
 
+## 0.0.9
+
+- Removed redundant tool guidance from Ask, Shepherdr, Skills and Browser. Code and Notebook Mode now show one callable contract per tool, with detailed Browser and agent rules in help.
+
+## 0.0.8
+
+- Shepherdr now discovers and answers waiting questions invoked inside Code and Notebook Mode.
+
 ## 0.0.7
 
 - The `ask` tool now supports steering questions that return immediately, preserve the full response panel, and deliver answers at the next safe boundary using the developer role under active Pi Codex Responses.

package/ask/contracts.ts

@@ -4,30 +4,21 @@ import { type Static, Type } from "typebox";
 const ASK_DELIVERIES = ["wait", "steer"] as const;
 
 const ChoiceSchema = Type.Object({
-	label: Type.String({ description: "Short choice." }),
-	description: Type.Optional(Type.String({ description: "Optional detail." })),
+	label: Type.String(),
+	description: Type.Optional(Type.String()),
 });
 
 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." })),
-	choices: Type.Optional(
-		Type.Array(ChoiceSchema, { description: "Choices; omit for free text." }),
-	),
+	title: Type.String(),
+	body: Type.Optional(Type.String()),
+	multiple: Type.Optional(Type.Boolean()),
+	choices: Type.Optional(Type.Array(ChoiceSchema)),
 });
 
 export const AskParameters = Type.Object({
-	handoff: Type.Optional(
-		Type.Boolean({ description: "Wait for user action." }),
-	),
-	prompts: Type.Array(PromptSchema, { description: "Prompts." }),
-	delivery: Type.Optional(
-		StringEnum(ASK_DELIVERIES, {
-			description:
-				"Wait for a gating response; steer while continuing reversible work. Omit to wait.",
-		}),
-	),
+	handoff: Type.Optional(Type.Boolean()),
+	prompts: Type.Array(PromptSchema),
+	delivery: Type.Optional(StringEnum(ASK_DELIVERIES)),
 });
 
 export type PromptChoice = Static<typeof ChoiceSchema>;

package/ask/coordinator.ts

@@ -17,6 +17,7 @@ export interface AskCoordinatorOptions {
 }
 
 interface PresentAskOptions {
+	onActiveChange?: (active: boolean) => void;
 	handoff?: boolean;
 	steering?: boolean;
 	signal?: AbortSignal;
@@ -42,23 +43,33 @@ export function createAskCoordinator({
 	const present = (
 		ctx: ExtensionContext,
 		prompts: AskPrompt[],
-		{ handoff = false, steering = false, signal }: PresentAskOptions = {},
+		{
+			handoff = false,
+			steering = false,
+			signal,
+			onActiveChange,
+		}: PresentAskOptions = {},
 	): Promise<unknown> => {
 		const run = async () => {
 			if (signal?.aborted) return null;
-			return askInComposer
-				? await askInComposer(prompts, signal)
-				: ctx.mode === "tui"
-					? await askInTui(ctx, prompts, {
-							handoff,
-							steering,
-							...(signal ? { signal } : {}),
-						})
-					: await askWithPiUi(ctx, prompts, {
-							handoff,
-							steering,
-							...(signal ? { signal } : {}),
-						});
+			try {
+				onActiveChange?.(true);
+				return askInComposer
+					? await askInComposer(prompts, signal)
+					: ctx.mode === "tui"
+						? await askInTui(ctx, prompts, {
+								handoff,
+								steering,
+								...(signal ? { signal } : {}),
+							})
+						: await askWithPiUi(ctx, prompts, {
+								handoff,
+								steering,
+								...(signal ? { signal } : {}),
+							});
+			} finally {
+				onActiveChange?.(false);
+			}
 		};
 		const result = presentationTail.then(run, run);
 		presentationTail = result.then(

package/ask/tool.ts

@@ -1,6 +1,6 @@
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { AskParameters } from "./contracts.js";
+import { AskParameters, type AskPrompt } from "./contracts.js";
 import {
 	type AskCoordinatorOptions,
 	createAskCoordinator,
@@ -18,6 +18,8 @@ interface BlockedState {
 	active: boolean;
 	label: string;
 	prompt: string;
+	handoff: boolean;
+	prompts: AskPrompt[];
 }
 
 type OnBlockedChange = (state: BlockedState) => void;
@@ -41,13 +43,12 @@ export function createAskRuntime({
 	const tool = defineTool({
 		name: "ask",
 		label: "Ask",
-		description: "Request user input or action. Requires interactive UI.",
+		description: "Request user input or action",
 		parameters: AskParameters,
-		promptSnippet: "Request human input or action.",
 		promptGuidelines: [
-			"ask: Use steer only while useful reversible work can continue; wait for gating answers and handoffs, stating a handoff's completion signal.",
+			"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: Do not add Other/rephrase; it is automatic.",
+			"ask: Other/rephrase is automatic; omit choices for free text",
 		],
 		executionMode: "sequential",
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
@@ -79,24 +80,22 @@ export function createAskRuntime({
 			const blockedState = {
 				id: toolCallId,
 				active: true,
+				handoff,
+				prompts,
 				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;
-			try {
-				const presentationSignal = signal
-					? AbortSignal.any([signal, coordinator.sessionSignal])
-					: coordinator.sessionSignal;
-				rawResponses = await coordinator.present(ctx, prompts, {
-					handoff,
-					signal: presentationSignal,
-				});
-			} finally {
-				onBlockedChange?.({ ...blockedState, active: false });
-			}
+			const presentationSignal = signal
+				? AbortSignal.any([signal, coordinator.sessionSignal])
+				: coordinator.sessionSignal;
+			const rawResponses = await coordinator.present(ctx, prompts, {
+				handoff,
+				signal: presentationSignal,
+				onActiveChange: (active) =>
+					onBlockedChange?.({ ...blockedState, active }),
+			});
 			const responses = normalizeResponses(prompts, rawResponses);
 			if (!responses) {
 				return {

package/index.ts

@@ -29,15 +29,35 @@ export default async function humanInTheLoop(pi: ExtensionAPI): Promise<void> {
 	const askRuntime = createAskRuntime({
 		deliverSteer: createSteerDelivery(pi, trySendCodexDeveloperMessage),
 		onBlockedChange: (state) => {
-			pi.events.emit(REALTIME_VOICE_PROMPT_CHANNEL, {
-				id: state.id,
-				active: state.active,
-				prompt: state.prompt,
-			});
-			pi.events.emit("herdr:blocked", {
-				active: state.active,
-				label: state.label,
-			});
+			const notify = () => {
+				pi.events.emit(REALTIME_VOICE_PROMPT_CHANNEL, {
+					id: state.id,
+					active: state.active,
+					prompt: state.prompt,
+				});
+				pi.events.emit("herdr:blocked", {
+					active: state.active,
+					label: state.label,
+				});
+			};
+			// Publish before Herdr reports blocked, including calls nested inside exec.
+			try {
+				pi.appendEntry(
+					"pi-ask-active",
+					state.active
+						? {
+								version: 1,
+								state: "active",
+								id: state.id,
+								handoff: state.handoff,
+								prompts: state.prompts,
+							}
+						: { version: 1, state: "closed", id: state.id },
+				);
+			} finally {
+				if (!state.active) notify();
+			}
+			if (state.active) notify();
 		},
 		onPendingChange: (update) => {
 			pi.appendEntry(PENDING_ASK_ENTRY_TYPE, update);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@howaboua/pi-ask",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"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.26",
+		"@howaboua/pi-codex-conversion": ">=3.0.33",
 		"@earendil-works/pi-ai": ">=0.84.3",
 		"@earendil-works/pi-coding-agent": ">=0.84.3",
 		"@earendil-works/pi-tui": ">=0.84.3",
@@ -57,11 +57,11 @@
 		}
 	},
 	"devDependencies": {
-		"@howaboua/pi-codex-conversion": "3.0.26",
+		"@howaboua/pi-codex-conversion": "3.0.33",
 		"@biomejs/biome": "^2.5.10",
-		"@earendil-works/pi-ai": "0.85.0",
-		"@earendil-works/pi-coding-agent": "0.85.0",
-		"@earendil-works/pi-tui": "0.85.0",
+		"@earendil-works/pi-ai": "0.85.1",
+		"@earendil-works/pi-coding-agent": "0.85.1",
+		"@earendil-works/pi-tui": "0.85.1",
 		"typebox": "1.3.18",
 		"typescript": "^7.0.2"
 	},