pi-robot-hand 0.2.2 → 0.3.0

package/README.md

@@ -13,12 +13,14 @@ pi-robot-hand hands them to you in one keystroke and brings the result back to t
 pi install npm:pi-robot-hand
 ```
 
+Also on the [pi package gallery](https://pi.dev/packages/pi-robot-hand).
+
 ## `robot_hand`
 
 The agent calls `robot_hand` with a command and a one-line reason, and pi shows a selector:
 
 ```
- Robot Hand — 需要 sudo 重啟服務
+ Robot Hand — Restarting nginx needs sudo
 
    ! sudo systemctl restart nginx
 
@@ -58,6 +60,25 @@ It can set a `.env` key, replace a regex match, write a whole file, or feed the
 `/secret-drop` lists protected files.
 See [docs/secret-drop.md](https://github.com/wayne930242/pi-robot-hand/blob/main/docs/secret-drop.md) for parameters, protection details, and limits.
 
+## Answering from another extension
+
+`robot_hand` publishes the selector it opens on pi's in-process event bus, so another extension (a browser page, a remote UI) can answer it. The terminal selector works as before whether or not anyone listens, and an answer runs exactly as if you had picked it there.
+
+The contract is "dialog contract v1", shared by every extension that owns a dialog; only the event prefix differs. For `robot_hand` the prefix is `robot-hand`. Every payload carries `version: 1`.
+
+| Event | Direction | Payload |
+|---|---|---|
+| `robot-hand:pending` | owner → bus | `{ version, id, toolCallId, digest, select: { title, choices: [{ label, note?, localOnly? }], copy } }`. `id` is a random UUID for this dialog. `note` says where a choice acts; `localOnly` marks the clipboard, which is this computer's. `copy` is the command, for a page that offers a copy button. |
+| `robot-hand:answer` | bus → owner | `{ version, id, answerId, digest, selections: [index] }`. `answerId` is `[A-Za-z0-9_-]{16,64}`, minted by the answerer; `digest` is the one from `pending`; `selections` holds exactly one zero-based index into `choices`. No other keys. |
+| `robot-hand:answer-result` | owner → bus | `{ version, id, answerId, accepted, reason? }`, emitted synchronously inside the `answer` listener. `reason` is `closed`, `digest`, `malformed`, or `not-allowed`. An answer for an unknown `id` gets no result. |
+| `robot-hand:closed` | owner → bus | `{ version, id, by, answerId? }`, once per dialog: `by` is `local` (picked in the terminal), `remote` (with the `answerId`), `cancel` (Escape), `abort` (the agent's turn was aborted), or `error`. |
+
+The digest is the lowercase hex SHA-256 of `JSON.stringify(["pi-dialog/1", "select", title, labels])`, where `labels` are the choice labels in order. It binds an answer to what the user saw. For the title `Robot Hand — Deploy needs your sudo password\n\n  ! npm run deploy` and the labels `Type it into a new Herdr pane (I press Enter)`, `Put it in my prompt`, `No, thanks`, the digest is `2974924308b3389b43761124fc7cbc4a4feced24e7f83706ae3f568a21b45faf`.
+
+An answer for this dialog's `id` is refused whole unless its `version`, `answerId`, `digest`, and `selections` are right and it has no extra keys; an `answerId` that fails the pattern comes back as an empty string in the result. The first of a terminal pick, a valid answer, Escape, or an abort wins: a later answer gets `accepted: false, reason: "closed"`, and an answer sent while `pending` is being emitted wins before the selector opens. A remote answer closes the terminal selector; the tool result is the same text as a terminal pick, with `details.answeredFrom: "browser"`.
+
+Any extension in the pi process can read dialog ids from the bus and answer. That adds no authority: such an extension could already run commands itself, so there is no opt-in setting. `secret_drop` never publishes anything and can only be answered in the terminal.
+
 ## Safety
 
 pi-robot-hand depends on no other extension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-robot-hand",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "The lazy kit for pi: no IDE, no copy-paste, safety net still on. The agent hands you commands (prompt, clipboard, or a Herdr pane that reports back), answers your ! commands, and takes secrets through a masked dialog it never sees",
   "type": "module",
   "license": "MIT",

package/src/dialog.ts

@@ -0,0 +1,87 @@
+// Dialog contract v1, owner side: robot_hand publishes the selector it opens and accepts one valid answer from another
+// extension through the path a terminal pick takes. The first of pick, answer, Escape, or abort wins; answers are checked
+// against this call's own copy of the dialog.
+import { createHash, randomUUID } from "node:crypto";
+
+export interface Bus {
+	emit(channel: string, data: unknown): void;
+	on(channel: string, handler: (data: unknown) => void): () => void;
+}
+export interface BusChoice { label: string; note?: string; localOnly?: true }
+type By = "local" | "remote" | "cancel" | "timeout" | "abort" | "error";
+type Reason = "closed" | "digest" | "malformed" | "not-allowed";
+const PREFIX = "robot-hand";
+const ANSWER_ID = /^[A-Za-z0-9_-]{16,64}$/;
+const KEYS = new Set(["version", "id", "answerId", "digest", "selections", "text", "comment"]);
+
+/** SHA-256 of the canonical select form: the title and the choice labels, nothing else. */
+export function digestOf(title: string, labels: string[]): string {
+	return createHash("sha256").update(JSON.stringify(["pi-dialog/1", "select", title, labels]), "utf8").digest("hex");
+}
+
+// A selector takes exactly one index: no words, no comment. Returns that index, or why the whole answer is refused.
+function check(a: Record<string, unknown>, digest: string, count: number): number | Reason {
+	const { selections, text, comment } = a;
+	const has = (key: string): boolean => Object.hasOwn(a, key);
+	const picks = Array.isArray(selections) ? [...selections] : [];
+	const picksOk = picks.length > 0 && new Set(picks).size === picks.length && picks.every((i) => Number.isInteger(i) && i >= 0 && i < count);
+	const shaped =
+		a.version === 1 && typeof a.answerId === "string" && ANSWER_ID.test(a.answerId) && typeof a.digest === "string" && Object.keys(a).every((key) => KEYS.has(key)) &&
+		has("selections") !== has("text") &&
+		(!has("selections") || picksOk) &&
+		(!has("text") || (typeof text === "string" && text.trim() !== "")) &&
+		(!has("comment") || (typeof comment === "string" && has("selections")));
+	if (!shaped) return "malformed";
+	if (a.digest !== digest) return "digest";
+	return !has("text") && !has("comment") && picks.length === 1 ? (picks[0] as number) : "not-allowed";
+}
+
+export function openDialog(bus: Bus, o: { toolCallId: string; title: string; choices: BusChoice[]; copy: string; signal?: AbortSignal }) {
+	const id = randomUUID();
+	const digest = digestOf(o.title, o.choices.map((choice) => choice.label));
+	const local = new AbortController();
+	let by: By | undefined;
+	let winner: number | undefined;
+	// The flag is written before anything is closed or emitted, so the other claimant sees "closed".
+	const settle = (how: By, answerId?: string, between?: () => void): void => {
+		if (by) return;
+		by = how;
+		between?.();
+		bus.emit(`${PREFIX}:closed`, { version: 1, id, by: how, ...(answerId ? { answerId } : {}) });
+	};
+	const onAbort = (): void => settle("abort");
+	const off = bus.on(`${PREFIX}:answer`, (raw) => {
+		if (typeof raw !== "object" || raw === null) return;
+		const a = { ...raw } as Record<string, unknown>;
+		if (a.id !== id) return;
+		const answerId = typeof a.answerId === "string" && ANSWER_ID.test(a.answerId) ? a.answerId : "";
+		const result = (accepted: boolean, reason?: Reason): void => bus.emit(`${PREFIX}:answer-result`, { version: 1, id, answerId, accepted, ...(reason ? { reason } : {}) });
+		const verdict = by ? "closed" : check(a, digest, o.choices.length);
+		if (typeof verdict === "string") return result(false, verdict);
+		settle("remote", answerId, () => {
+			winner = verdict;
+			local.abort();
+			result(true);
+		});
+	});
+	o.signal?.addEventListener("abort", onAbort, { once: true });
+	bus.emit(`${PREFIX}:pending`, { version: 1, id, toolCallId: o.toolCallId, digest, select: { title: o.title, choices: o.choices.map((choice) => ({ ...choice })), copy: o.copy } });
+	if (o.signal?.aborted) settle("abort");
+	// signal: for `select`, aborts on the tool signal or a remote answer. open: false when an answer arrived during the
+	// `pending` emit, so the selector is not opened. finish: settles with the terminal's outcome (index, or undefined for
+	// Escape) unless something else won, and returns the winning index. dispose: settles as an error, drops the listeners.
+	return {
+		signal: AbortSignal.any(o.signal ? [o.signal, local.signal] : [local.signal]),
+		get open() { return by === undefined; },
+		get remote() { return by === "remote"; },
+		finish(picked: number | undefined): number | undefined {
+			settle(picked === undefined ? "cancel" : "local");
+			return by === "local" ? picked : winner;
+		},
+		dispose(): void {
+			settle("error");
+			off();
+			o.signal?.removeEventListener("abort", onAbort);
+		},
+	};
+}

package/src/hand.ts

@@ -68,6 +68,20 @@ export function options(offer: Offer, reach: Reach, preferred: Preferred = "prom
 	return [...ordered, { choice: "cancel", label: "No, thanks" }];
 }
 
+// Where each choice acts, for an answerer that shows the choices elsewhere. The clipboard is this computer's.
+const NOTES: Record<Choice, string | undefined> = {
+	prompt: "Lands in the terminal's prompt; press Enter there",
+	clipboard: "Copies on this computer",
+	"herdr-type": "Opens a pane with the command typed; press Enter there",
+	"herdr-run": "Runs it at once in a new pane",
+	cancel: undefined,
+};
+
+/** The choices as published on the dialog bus, each with its note. */
+export function busChoices(list: Option[]): { label: string; note?: string; localOnly?: true }[] {
+	return list.map(({ choice, label }) => ({ label, ...(NOTES[choice] ? { note: NOTES[choice] } : {}), ...(choice === "clipboard" ? { localOnly: true as const } : {}) }));
+}
+
 /** The selector title: why the agent hands this over, then exactly what the user would run. */
 export function dialogTitle(offer: Offer, reason: string): string {
 	return `Robot Hand — ${reason}\n\n  ${promptText(offer).split("\n").join("\n  ")}`;

package/src/index.ts

@@ -10,12 +10,15 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { copyToClipboard, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { type Choice, dialogTitle, options, promptText, resultText, toOffer } from "./hand.ts";
+import { openDialog } from "./dialog.ts";
+import { busChoices, type Choice, dialogTitle, options, promptText, resultText, toOffer } from "./hand.ts";
 import { checkRun, cleanup, type Exec, findShell, type HerdrRun, outcomeText, startRun } from "./herdr.ts";
 
 interface HandDetails {
 	command: string;
 	status: "waiting" | Choice;
+	/** Present when another extension answered the selector. */
+	answeredFrom?: "browser";
 }
 
 export const HERDR_RESULT_TYPE = "robot-hand-herdr";
@@ -103,7 +106,7 @@ export function createRobotHand(copy: (text: string) => Promise<void> = copyToCl
 			parameters: Params,
 			executionMode: "sequential",
 
-			async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			async execute(toolCallId, params, signal, onUpdate, ctx) {
 				if (!ctx.hasUI) {
 					throw new Error("robot_hand needs an interactive pi UI; show the command to the user in chat instead.");
 				}
@@ -117,37 +120,49 @@ export function createRobotHand(copy: (text: string) => Promise<void> = copyToCl
 				};
 				const choices = options(offer, reach, params.default);
 
-				onUpdate?.({ content: [{ type: "text", text: "Waiting for the user to take the command..." }], details: { command: text, status: "waiting" } });
-				pi.events.emit("herdr:blocked", { active: true, label: "Waiting for the user to take a command" });
-				let picked: string | undefined;
+				const title = dialogTitle(offer, params.reason);
+				const dialog = openDialog(pi.events, { toolCallId, title, choices: busChoices(choices), copy: offer.command, signal });
 				try {
-					picked = await ctx.ui.select(
-						dialogTitle(offer, params.reason),
-						choices.map((option) => option.label),
-						{ signal },
-					);
-				} finally {
-					pi.events.emit("herdr:blocked", { active: false });
-				}
-				const choice = choices.find((option) => option.label === picked)?.choice ?? "cancel";
+					onUpdate?.({ content: [{ type: "text", text: "Waiting for the user to take the command..." }], details: { command: text, status: "waiting" } });
+					pi.events.emit("herdr:blocked", { active: true, label: "Waiting for the user to take a command" });
+					let won: number | undefined;
+					try {
+						let picked: string | undefined;
+						if (dialog.open) {
+							picked = await ctx.ui.select(
+								title,
+								choices.map((option) => option.label),
+								{ signal: dialog.signal },
+							);
+						}
+						// Settle right after the selector resolves, before anything else can run.
+						const at = choices.findIndex((option) => option.label === picked);
+						won = dialog.finish(at < 0 ? undefined : at);
+					} finally {
+						pi.events.emit("herdr:blocked", { active: false });
+					}
+					const choice = (won === undefined ? undefined : choices[won]?.choice) ?? "cancel";
 
-				if (choice === "prompt") {
-					ctx.ui.setEditorText(text);
-					ctx.ui.notify("Review the command in your prompt and press Enter to run it.", "info");
-				} else if (choice === "clipboard") {
-					await copy(offer.command);
-					ctx.ui.notify("Command copied to the clipboard.", "info");
-				} else if ((choice === "herdr-type" || choice === "herdr-run") && piPane) {
-					const run = await startRun(exec, { piPane, cwd: ctx.cwd, tmp, command: offer.command, type: choice === "herdr-type", shell: findShell(env.PATH) });
-					runs.set(run.token, { run, ticks: 0, busy: false });
-					timer ??= setInterval(watch, WATCH_MS);
+					if (choice === "prompt") {
+						ctx.ui.setEditorText(text);
+						ctx.ui.notify("Review the command in your prompt and press Enter to run it.", "info");
+					} else if (choice === "clipboard") {
+						await copy(offer.command);
+						ctx.ui.notify("Command copied to the clipboard.", "info");
+					} else if ((choice === "herdr-type" || choice === "herdr-run") && piPane) {
+						const run = await startRun(exec, { piPane, cwd: ctx.cwd, tmp, command: offer.command, type: choice === "herdr-type", shell: findShell(env.PATH) });
+						runs.set(run.token, { run, ticks: 0, busy: false });
+						timer ??= setInterval(watch, WATCH_MS);
+					}
+					return {
+						content: [{ type: "text", text: resultText(choice, offer) }],
+						details: { command: text, status: choice, ...(dialog.remote ? { answeredFrom: "browser" } : {}) } satisfies HandDetails,
+						// The next move is the user's; a follow-up from the agent would only talk over it.
+						terminate: choice !== "cancel",
+					};
+				} finally {
+					dialog.dispose();
 				}
-				return {
-					content: [{ type: "text", text: resultText(choice, offer) }],
-					details: { command: text, status: choice } satisfies HandDetails,
-					// The next move is the user's; a follow-up from the agent would only talk over it.
-					terminate: choice !== "cancel",
-				};
 			},
 
 			renderCall(args, theme) {