pi-robot-hand 0.3.1 → 0.4.0

package/README.md

@@ -68,7 +68,7 @@ The contract is "dialog contract v1", shared by every extension that owns a dial
 
 | 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:pending` | owner → bus | `{ version, id, toolCallId, digest, select: { title, choices: [{ label, note?, localOnly?, next?, tagged? }], copy } }`. `id` is a random UUID for this dialog. `note` says where a choice acts; `localOnly` marks the clipboard, which is this computer's; `next` says which terminal opens once the choice is accepted (`"terminal"` for the prompt, `"pane"` for the two Herdr pane choices); `tagged: true` on a pane choice means the pane is marked as described below. `next` and `tagged` are hints and are not hashed. `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`. |
@@ -77,6 +77,8 @@ The digest is the lowercase hex SHA-256 of `JSON.stringify(["pi-dialog/1", "sele
 
 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"`.
 
+When an accepted answer picks one of the two Herdr pane choices, `robot_hand` marks the pane it just opened so the answerer can tell which pane is the owner's: right after `herdr pane split` and before anything is typed or run there, it runs `herdr pane report-metadata <pane_id> --source robot-hand --token sb_answer=<answerId> --ttl-ms 600000`. The value is exactly the answer's `answerId`. [Straw Boss](https://github.com/wayne930242/pi-straw-boss) grants its terminal keys only to the pane that carries it. The tag is set once, with no retry; if it fails, the command still runs and the answerer grants no pane. A pick in the terminal, and answers for the other choices, tag nothing.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-robot-hand",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -43,7 +43,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc --noEmit",
-    "test": "npm run build && node --test tests/*.test.ts",
+    "test": "npm run build && node --test --test-force-exit tests/*.test.ts",
     "prepack": "npm run build"
   },
   "peerDependencies": {

package/skills/secret-drop/SKILL.md

@@ -10,8 +10,8 @@ Secrets reach files and commands through the `secret_drop` tool, so the value ne
 ## Writing a secret
 
 1. Pick the destination the consuming program expects. For a `regex` placement in a file that is not yet protected, read its structure first.
-2. When the value is created or revealed on a web page and you can drive the user's own browser, where they are signed in, first ask the user whether you should prepare that page. When they agree, open it, fill in every field (name, scope, permissions, expiration), and stop at the button that creates or reveals the value; your `instructions` then say which button to press in which tab and what to copy. Once that button is pressed the value is on screen, so leave the tab alone (no snapshot, screenshot, or page text) until `secret_drop` reports the value applied, then close it. When the user declines or no browser is available, write the full steps for them to follow.
-3. Call `secret_drop` with a `label` naming exactly what to enter (service, account, environment), `instructions` the user can follow without asking (the exact page or menu path, every field to fill in such as name, scope, permissions, and expiration, and what to copy), the page as `url` when there is one, both in the user's language, and one format:
+2. When the value is newly created on a web page and a browser session on the user's signed-in profile is already open to you, ask the user with your question tool whether you should prepare that page; starting a browser only to qualify does not count. When they agree, open it, fill in every field (name, scope, permissions, expiration), and stop at the button that creates the value. From then on make no browser tool call in that session, whatever `secret_drop` returns, until the user has closed that tab: browser tools return page content, and the value is on that page once the button is pressed. Learn that the tab is closed from the user, through your question tool, rather than from a browser call. A page that shows an existing secret already holds the value in its DOM, so give its `url` and steps instead of opening it. When the user declines or no such session is open, write the full steps.
+3. Call `secret_drop` with a `label` naming exactly what to enter (service, account, environment), `instructions` the user can follow without asking (the exact page or menu path, every field to fill in such as name, scope, permissions, and expiration, and what to copy; for a prepared page, the tab, the button to press, what to copy, and closing the tab afterwards), the page as `url` when there is one, both in the user's language, and one format:
    - `key` + `destination` (format `env`): sets `KEY=value`, replacing existing `KEY` / `export KEY` lines or appending one. Other lines and trailing comments stay. For a file read by `docker --env-file`, pass `quote: "none"`, since Docker keeps quotes as part of the value.
    - `format: "regex"` + `destination` + `regex`: replaces capture group 1, or the whole match, in an existing file. Make the group cover only the value, e.g. `password: "([^"]*)"`.
    - `format: "file"` + `destination`: the whole file is the secret, for key files and single-value files. An existing destination is refused unless `overwrite: true` is passed; pass it only to rotate a single-value file, never for a multi-value file such as `.env`.
@@ -22,7 +22,7 @@ Secrets reach files and commands through the `secret_drop` tool, so the value ne
 4. Call it once per secret and wait for the result:
    - **Applied**: the report states the change and `length check passed (N chars)`. That report is the verification; the value is in place.
    - **Question**: the user pressed Tab and asked instead; nothing was staged. Answer it, then call `secret_drop` again.
-   - **Cancelled or aborted**: nothing was applied. Ask the user how to proceed.
+   - **Cancelled or aborted**: nothing was applied. Ask the user how to proceed; have the user revoke a token created on a prepared page that was not applied.
    - **Apply failed**: the staged value was discarded. Fix the parameters from the error (a regex that does not match, a failing command) and call again.
 
 When the user offers to paste a secret into chat, call `secret_drop` instead.

package/src/dialog.ts

@@ -7,7 +7,9 @@ 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 }
+// `next` and `tagged` are hints, not hashed: `next` says which terminal opens once the choice is accepted, `tagged` that the
+// owner marks the pane it opened with the answer's own `answerId` (token `sb_answer`).
+export interface BusChoice { label: string; note?: string; localOnly?: true; next?: "terminal" | "pane"; tagged?: true }
 type By = "local" | "remote" | "cancel" | "timeout" | "abort" | "error";
 type Reason = "closed" | "digest" | "malformed" | "not-allowed";
 const PREFIX = "robot-hand";
@@ -42,6 +44,7 @@ export function openDialog(bus: Bus, o: { toolCallId: string; title: string; cho
 	const local = new AbortController();
 	let by: By | undefined;
 	let winner: number | undefined;
+	let winnerAnswerId: string | 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;
@@ -60,6 +63,7 @@ export function openDialog(bus: Bus, o: { toolCallId: string; title: string; cho
 		if (typeof verdict === "string") return result(false, verdict);
 		settle("remote", answerId, () => {
 			winner = verdict;
+			winnerAnswerId = answerId;
 			local.abort();
 			result(true);
 		});
@@ -74,6 +78,8 @@ export function openDialog(bus: Bus, o: { toolCallId: string; title: string; cho
 		signal: AbortSignal.any(o.signal ? [o.signal, local.signal] : [local.signal]),
 		get open() { return by === undefined; },
 		get remote() { return by === "remote"; },
+		// The accepted answer's id, once a remote answer has won.
+		get answerId() { return by === "remote" ? winnerAnswerId : undefined; },
 		finish(picked: number | undefined): number | undefined {
 			settle(picked === undefined ? "cancel" : "local");
 			return by === "local" ? picked : winner;

package/src/hand.ts

@@ -1,5 +1,7 @@
 /** What the agent hands over, and how each of the user's choices turns into editor or clipboard text. */
 
+import type { BusChoice } from "./dialog.ts";
+
 export type Kind = "shell" | "pi";
 export type Preferred = "prompt" | "clipboard" | "herdr-type" | "herdr-run";
 export type Choice = Preferred | "cancel";
@@ -77,9 +79,18 @@ const NOTES: Record<Choice, string | undefined> = {
 	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 } : {}) }));
+// Which terminal opens once an answer is accepted. A pane choice also marks its pane with the answer's id (see startRun).
+const NEXT: Record<Choice, { next: "terminal" } | { next: "pane"; tagged: true } | undefined> = {
+	prompt: { next: "terminal" },
+	clipboard: undefined,
+	"herdr-type": { next: "pane", tagged: true },
+	"herdr-run": { next: "pane", tagged: true },
+	cancel: undefined,
+};
+
+/** The choices as published on the dialog bus, each with its note and where it leads. */
+export function busChoices(list: Option[]): BusChoice[] {
+	return list.map(({ choice, label }) => ({ label, ...(NOTES[choice] ? { note: NOTES[choice] } : {}), ...(choice === "clipboard" ? { localOnly: true as const } : {}), ...NEXT[choice] }));
 }
 
 /** The selector title: why the agent hands this over, then exactly what the user would run. */

package/src/herdr.ts

@@ -75,8 +75,11 @@ export function sliceOutput(screen: string, token: string): string {
 	return cut ? `[earlier output omitted]\n${text}` : text;
 }
 
-/** Opens the pane below pi, focuses it, and starts the wrapper. */
-export async function startRun(exec: Exec, opts: { piPane: string; cwd: string; tmp: string; command: string; type: boolean; shell: "zsh" | "bash" }): Promise<HerdrRun> {
+/**
+ * Opens the pane below pi, focuses it, and starts the wrapper. With an `answerId` (an accepted answer from another
+ * extension), the new pane is marked `sb_answer=<answerId>` first, so Straw Boss can tell it is the pane this answer opened.
+ */
+export async function startRun(exec: Exec, opts: { piPane: string; cwd: string; tmp: string; command: string; type: boolean; shell: "zsh" | "bash"; answerId?: string }): Promise<HerdrRun> {
 	const token = randomBytes(4).toString("hex");
 	const dir = join(opts.tmp, "pi-robot-hand", token);
 	await mkdir(dir, { recursive: true, mode: 0o700 });
@@ -91,6 +94,8 @@ export async function startRun(exec: Exec, opts: { piPane: string; cwd: string;
 		await rm(dir, { recursive: true, force: true });
 		throw new Error(`herdr could not open a pane: ${split.stdout.trim() || `exit ${split.code}`}`);
 	}
+	// Best effort and once: if the tag fails Straw Boss grants no pane, and the command still runs.
+	if (opts.answerId) await exec(["pane", "report-metadata", paneId, "--source", "robot-hand", "--token", `sb_answer=${opts.answerId}`, "--ttl-ms", "600000"]).catch(() => undefined);
 	await exec(["pane", "focus", "--pane", opts.piPane, "--direction", "down"]);
 	const run = await exec(["pane", "run", paneId, `${opts.shell} ${shellQuote(script)}`]);
 	if (run.code !== 0) {

package/src/index.ts

@@ -150,7 +150,7 @@ export function createRobotHand(copy: (text: string) => Promise<void> = copyToCl
 						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) });
+						const run = await startRun(exec, { piPane, cwd: ctx.cwd, tmp, command: offer.command, type: choice === "herdr-type", shell: findShell(env.PATH), answerId: dialog.answerId });
 						runs.set(run.token, { run, ticks: 0, busy: false });
 						timer ??= setInterval(watch, WATCH_MS);
 					}

package/src/secret-drop/index.ts

@@ -197,7 +197,7 @@ export default function secretDrop(pi: ExtensionAPI) {
 			"Use secret_drop whenever a password, token, key, or other credential must land in a file or be fed to a command; never ask the user to paste secrets into chat.",
 			"Files that hold secrets are consumed by programs, never read or printed by the agent.",
 			"Give secret_drop instructions the user can follow without asking: the exact page or menu, every field to fill in, and what to copy; write them and the label in the user's language.",
-			"When the secret is created or revealed on a web page and you can drive the user's signed-in browser, first ask whether to prepare that page up to its final create or reveal button, so the user only presses it and copies the value; after that press, leave the tab unread until the value is applied.",
+			"When the secret is newly created on a web page and a browser session on the user's signed-in profile is already open to you, ask with your question tool whether to prepare that page up to its final create button, so the user only presses it and copies the value; then make no browser call in that session until the user tells you, when you ask, that the tab is closed, whatever secret_drop returns. Give the URL and steps instead of opening a page that shows an existing secret, and full steps when the user declines.",
 			"When secret_drop returns a question from the user, answer it, then call secret_drop again.",
 		],
 		parameters: Params,