pi-robot-hand 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wayne930242
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# pi-robot-hand
+
+A [pi](https://pi.dev) extension that lets the agent hand the user a command to run themselves.
+
+1. The agent calls `robot_hand` with a command and a one-line reason.
+2. Pi shows an inline selector in place of the prompt, with the reason and exactly what the user would run.
+3. The user picks one:
+   - **Put it in my prompt**: a shell command lands as `! command`, a pi slash command such as `/reload` lands as-is. Pressing Enter runs it; a `!` command's output returns to the conversation.
+   - **Copy it to the clipboard**: the raw shell command, for another terminal.
+   - **No, thanks**: nothing is placed.
+4. The tool returns the choice. After a prompt or clipboard hand-over the agent's turn ends, so the next move is the user's.
+
+The agent never runs the command. It suits commands the user has to run: pi slash commands, `sudo` or interactive commands, and commands a safety extension blocks for the agent.
+
+```
+ robot_hand 需要 sudo 重啟服務
+   ! sudo systemctl restart nginx
+ ──────────────────────────────────────────────
+ Robot Hand — 需要 sudo 重啟服務
+
+   ! sudo systemctl restart nginx
+
+ → Put it in my prompt
+   Copy it to the clipboard
+   No, thanks
+
+ ↑↓ navigate  enter select  escape/ctrl+c cancel
+ ──────────────────────────────────────────────
+```
+
+## Install
+
+```bash
+pi install npm:pi-robot-hand
+```
+
+## Tool: `robot_hand`
+
+| Parameter | Description |
+|---|---|
+| `command` | The command. Shell commands go without a leading `!`; pi commands start with `/`. |
+| `reason` | One short line telling the user why, in the user's language. |
+| `kind` | `shell` (default) or `pi`. |
+
+When the prompt already holds a draft, the prompt option says it replaces the draft. The clipboard option appears only for shell commands in the terminal UI. RPC clients get the prompt option; modes without a UI make the tool fail so the agent shows the command in chat.
+
+## Development
+
+```bash
+npm install
+npm run check   # tsc --noEmit
+npm test        # node --test
+```
+
+Releases publish from GitHub Actions through npm trusted publishing: bump `version` in `package.json`, commit, and push a matching `v<version>` tag.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "pi-robot-hand",
+  "version": "0.1.0",
+  "description": "Pi extension: the agent hands the user a command, and after the user agrees it lands in the pi prompt or the clipboard, never run by the agent",
+  "type": "module",
+  "license": "MIT",
+  "author": "wayne930242",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayne930242/pi-robot-hand.git"
+  },
+  "homepage": "https://github.com/wayne930242/pi-robot-hand#readme",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "clipboard",
+    "command",
+    "approval"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
+    "@types/node": "26.6.3",
+    "typebox": "1.3.34",
+    "typescript": "7.0.2"
+  }
+}

package/src/hand.ts

@@ -0,0 +1,61 @@
+/** What the agent hands over, and how each of the user's choices turns into editor or clipboard text. */
+
+export type Kind = "shell" | "pi";
+export type Choice = "prompt" | "clipboard" | "cancel";
+
+export interface Offer {
+	command: string;
+	kind: Kind;
+}
+
+export interface Option {
+	choice: Choice;
+	label: string;
+}
+
+/** Checks the command and fills in the default kind. Throws with a message the agent can act on. */
+export function toOffer(command: string, kind: Kind | undefined): Offer {
+	const text = command.trim();
+	if (text.length === 0) throw new Error("`command` is empty.");
+	const resolved = kind ?? "shell";
+	if (resolved === "shell" && text.startsWith("!")) {
+		throw new Error("Pass the shell command without a leading `!`; robot_hand adds it when the command goes to the prompt.");
+	}
+	if (resolved === "pi" && !text.startsWith("/")) {
+		throw new Error("kind=pi takes a pi slash command such as `/reload`; use kind=shell for shell commands.");
+	}
+	return { command: text, kind: resolved };
+}
+
+/** The text placed in the pi prompt: shell commands run through pi's `!` prefix, pi commands go as-is. */
+export function promptText(offer: Offer): string {
+	return offer.kind === "shell" ? `! ${offer.command}` : offer.command;
+}
+
+/**
+ * The choices shown to the user. The clipboard needs the local terminal and only makes sense for a
+ * shell command run elsewhere; a pi command only runs inside pi.
+ */
+export function options(offer: Offer, hasDraft: boolean, canCopy: boolean): Option[] {
+	const list: Option[] = [{ choice: "prompt", label: hasDraft ? "Put it in my prompt (replaces my draft)" : "Put it in my prompt" }];
+	if (canCopy && offer.kind === "shell") list.push({ choice: "clipboard", label: "Copy it to the clipboard" });
+	list.push({ choice: "cancel", label: "No, thanks" });
+	return list;
+}
+
+/** 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  ")}`;
+}
+
+/** What the tool tells the agent after the user chose. */
+export function resultText(choice: Choice, offer: Offer): string {
+	if (choice === "prompt") {
+		const output = offer.kind === "shell" ? " Its output appears in the conversation when they run it." : "";
+		return `The user put \`${promptText(offer)}\` in their prompt; it runs only when they press Enter.${output} Nothing has run yet; wait for the user.`;
+	}
+	if (choice === "clipboard") {
+		return "The user copied the command to their clipboard to run it themselves. Nothing has run yet; wait for the user to report the result.";
+	}
+	return "The user declined; nothing was placed or run. Ask how they want to proceed.";
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+/**
+ * pi-robot-hand: the agent hands the user a command. After the user agrees, it lands in the pi
+ * prompt (shell commands as `! command`) or the clipboard. The user decides whether to run it;
+ * the agent never does.
+ */
+
+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";
+
+interface HandDetails {
+	command: string;
+	status: "waiting" | Choice;
+}
+
+const Params = Type.Object({
+	command: Type.String({
+		description: "The command to hand over. kind=shell: a shell command without a leading `!`. kind=pi: a pi slash command such as `/reload`.",
+	}),
+	reason: Type.String({ description: "One short line telling the user why they should run it, in the user's language." }),
+	kind: Type.Optional(
+		StringEnum(["shell", "pi"] as const, {
+			description:
+				"shell: goes to the prompt as `! command` (output returns to the conversation) or to the clipboard for another terminal. pi: a pi slash command, placed in the prompt as-is. Default shell.",
+		}),
+	),
+});
+
+export function createRobotHand(copy: (text: string) => Promise<void> = copyToClipboard) {
+	return function robotHand(pi: ExtensionAPI) {
+		pi.registerTool({
+			name: "robot_hand",
+			label: "Robot Hand",
+			description:
+				"Hand the user a command to run themselves. The user sees the command and the reason, then puts it in their pi prompt (a shell command becomes `! command`, whose output returns to the conversation when they press Enter), copies it to the clipboard, or declines. The tool returns the user's choice; it never runs the command.",
+			promptSnippet: "Hand the user a command to run themselves, via their pi prompt or clipboard",
+			promptGuidelines: [
+				"Use robot_hand when the user has to run a command themselves: pi slash commands such as /reload, interactive or sudo commands, commands a guard blocked, or anything they asked to run on their own.",
+				"Pass one command per robot_hand call and write the reason in the user's language.",
+				"After robot_hand places or copies a command, nothing has run yet: wait for the user instead of assuming the result.",
+			],
+			parameters: Params,
+			executionMode: "sequential",
+
+			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.");
+				}
+				const offer = toOffer(params.command, params.kind);
+				const text = promptText(offer);
+				const choices = options(offer, ctx.ui.getEditorText().trim().length > 0, ctx.mode === "tui");
+
+				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;
+				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";
+
+				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");
+				}
+				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) {
+				const head = `${theme.fg("toolTitle", theme.bold("robot_hand "))}${theme.fg("dim", args.reason ?? "")}`;
+				const command = args.command ? (args.kind === "pi" ? args.command : `! ${args.command}`) : "";
+				const lines = command.split("\n").map((line: string) => `  ${theme.fg("accent", line)}`);
+				return new Text([head, ...lines].join("\n"), 0, 0);
+			},
+
+			renderResult(result, _options, theme) {
+				const details = result.details as HandDetails | undefined;
+				if (!details || typeof details.status !== "string") {
+					const first = result.content[0];
+					return new Text(first?.type === "text" ? first.text : "", 0, 0);
+				}
+				if (details.status === "waiting") return new Text(theme.fg("dim", "Waiting for you to take the command"), 0, 0);
+				if (details.status === "prompt") return new Text(`${theme.fg("success", "✓ ")}In your prompt — press Enter to run it`, 0, 0);
+				if (details.status === "clipboard") return new Text(`${theme.fg("success", "✓ ")}Copied to your clipboard`, 0, 0);
+				return new Text(theme.fg("warning", "Declined — nothing placed or run"), 0, 0);
+			},
+		});
+	};
+}
+
+export default createRobotHand();