@howaboua/pi-ask 0.0.11 → 0.0.12

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # @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.

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/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/tool.ts

@@ -6,6 +6,7 @@ import {
 	createAskCoordinator,
 } from "./coordinator.js";
 import {
+	isAskHelpInput,
 	isSteeringAskInput,
 	normalizeAskInput,
 	normalizeResponses,
@@ -45,15 +46,26 @@ export function createAskRuntime({
 	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(
@@ -115,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";
@@ -127,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.11",
+	"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.46",
+		"@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.46",
+		"@howaboua/pi-codex-conversion": "3.0.48",
 		"@biomejs/biome": "^2.5.10",
-		"@earendil-works/pi-ai": "1.0.4",
-		"@earendil-works/pi-coding-agent": "1.0.4",
-		"@earendil-works/pi-tui": "1.0.4",
+		"@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 .",