ping-a-human-pi 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# ping-a-human-pi
+
+Human-in-the-loop and notifications for the [pi](https://pi.dev) coding agent, powered by [ping-a-human](https://www.npmjs.com/package/ping-a-human).
+
+Pi has no built-in MCP support, so this package embeds a tiny MCP client and connects pi's hooks to ping-a-human. You get:
+
+- **`notify_human` / `ask_human` as native pi tools** the model can call directly.
+- **Notifications** — a Telegram ping every time pi finishes a task.
+- **Approval** — pi asks you for the green light before risky tool calls (e.g. `rm -rf`, `sudo`, `git push --force`) and blocks them unless you say yes.
+- **`/ping` command** — manually send yourself a notification: `/ping` or `/ping your message here`.
+- **`pah` CLI** — a global terminal command, independent of pi: `pah ping "build done"`, `pah ask "deploy?"`.
+
+## Install
+
+One command:
+
+```bash
+npx ping-a-human-pi
+```
+
+That's it. It:
+
+- installs the pi extension into `~/.pi/agent/extensions/ping-a-human-pi/` (pi auto-discovers it),
+- installs the `pah` CLI onto your PATH,
+- seeds `~/.pi/agent/ping-a-human.json` with sensible defaults (never overwrites an existing one).
+
+Run `/reload` in pi (or restart it). To remove everything: `npx ping-a-human-pi uninstall`.
+
+First time with ping-a-human? Configure Telegram once: `npx ping-a-human setup`.
+
+## `pah` CLI
+
+A standalone command (no pi required) for pinging a human from any terminal:
+
+```bash
+pah ping "build finished"      # fire-and-forget notification
+pah notify "deploy started"    # alias for ping
+pah ask "ship to prod?"        # waits and prints the human's reply
+pah help
+```
+
+It reads the same `~/.pi/agent/ping-a-human.json` for the server `command`/`args`/`env` (defaults to `npx -y ping-a-human`). The installer drops it in the first writable PATH dir among `~/bin`, `~/.local/bin`, `/usr/local/bin`; if none are on PATH it creates `~/.local/bin` and tells you to add it.
+
+Alternatives:
+
+```bash
+npm i -g ping-a-human-pi        # global install of the pah CLI + installer
+pi install npm:ping-a-human-pi  # load as a pi package
+sh install.sh                   # from a cloned checkout
+```
+
+## Configuration
+
+All optional. Edit `~/.pi/agent/ping-a-human.json` (see `ping-a-human-pi.example.json`):
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `command` / `args` | `npx -y ping-a-human` | how to launch the server |
+| `exposeTools` | `true` | register `notify_human` / `ask_human` as model-callable tools |
+| `notify.enabled` | `true` | ping you when a task finishes |
+| `notify.template` | `✅ pi finished a task in {cwd}:\n\n{summary}` | message text; `{summary}` `{cwd}` substituted |
+| `approval.enabled` | `false` | ask before risky tool calls |
+| `approval.tools` | `["bash"]` | which pi tools to gate |
+| `approval.patterns` | dangerous-command regexes | only gate calls whose args match one; empty = gate all calls of those tools |
+| `approval.template` | `🔐 pi wants to run {tool}:\n\n{details}\n\nApprove? (reply yes/no)` | prompt; `{tool}` `{details}` substituted |
+
+A reply matching `yes/ok/approve/allow/sure/go/lgtm/...` approves; anything else blocks the call (and the reason is sent back to the model).
+
+## Uninstall
+
+```bash
+rm -rf ~/.pi/agent/extensions/ping-a-human-pi
+rm -f ~/.pi/agent/ping-a-human.json   # optional
+rm -f ~/bin/pah ~/.local/bin/pah /usr/local/bin/pah 2>/dev/null  # the CLI
+```

package/bin/cli.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * ping-a-human-pi installer.
+ *
+ *   npx ping-a-human-pi            # install everything
+ *   npx ping-a-human-pi uninstall  # remove it
+ *
+ * Installs:
+ *   1. the pi extension  -> ~/.pi/agent/extensions/ping-a-human-pi/index.ts
+ *   2. the `pah` CLI     -> first writable dir on PATH (~/bin, ~/.local/bin, /usr/local/bin)
+ *   3. a default config  -> ~/.pi/agent/ping-a-human.json (only if missing)
+ */
+
+import { chmodSync, copyFileSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = join(HERE, "..");
+const PI_HOME = process.env.PI_HOME || join(homedir(), ".pi", "agent");
+const EXT_DIR = join(PI_HOME, "extensions", "ping-a-human-pi");
+const CONFIG = join(PI_HOME, "ping-a-human.json");
+
+const c = {
+	bold: (s) => `\x1b[1m${s}\x1b[0m`,
+	green: (s) => `\x1b[32m${s}\x1b[0m`,
+	yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+	dim: (s) => `\x1b[2m${s}\x1b[0m`,
+};
+const say = (s = "") => process.stdout.write(`${s}\n`);
+
+function pathDirs() {
+	return (process.env.PATH || "").split(":").filter(Boolean);
+}
+
+function pickBinDir() {
+	const onPath = new Set(pathDirs());
+	for (const d of [join(homedir(), "bin"), join(homedir(), ".local", "bin"), "/usr/local/bin"]) {
+		if (onPath.has(d)) {
+			try {
+				mkdirSync(d, { recursive: true });
+				return { dir: d, onPath: true };
+			} catch {
+				/* not writable */
+			}
+		}
+	}
+	const fallback = join(homedir(), ".local", "bin");
+	try {
+		mkdirSync(fallback, { recursive: true });
+		return { dir: fallback, onPath: onPath.has(fallback) };
+	} catch {
+		return null;
+	}
+}
+
+function pahTargets() {
+	return [join(homedir(), "bin", "pah"), join(homedir(), ".local", "bin", "pah"), "/usr/local/bin/pah"];
+}
+
+function install() {
+	say(c.bold("→ Installing ping-a-human-pi"));
+
+	// 1. pi extension
+	mkdirSync(EXT_DIR, { recursive: true });
+	copyFileSync(join(PKG, "extension", "index.ts"), join(EXT_DIR, "index.ts"));
+	say(`  ${c.green("✓")} pi extension  ${c.dim("→ " + join(EXT_DIR, "index.ts"))}`);
+
+	// 2. pah CLI
+	const picked = pickBinDir();
+	if (picked) {
+		const dest = join(picked.dir, "pah");
+		copyFileSync(join(PKG, "bin", "pah"), dest);
+		chmodSync(dest, 0o755);
+		say(`  ${c.green("✓")} pah CLI       ${c.dim("→ " + dest)}`);
+		if (!picked.onPath) {
+			say(`  ${c.yellow("!")} ${picked.dir} is not on your PATH. Add to your shell rc:`);
+			say(`      export PATH="${picked.dir}:$PATH"`);
+		}
+	} else {
+		say(`  ${c.yellow("!")} could not install the pah CLI (no writable bin dir)`);
+	}
+
+	// 3. config (never overwrite)
+	mkdirSync(PI_HOME, { recursive: true });
+	if (existsSync(CONFIG)) {
+		say(`  ${c.green("✓")} config        ${c.dim("→ " + CONFIG + " (kept)")}`);
+	} else {
+		const example = join(PKG, "ping-a-human-pi.example.json");
+		if (existsSync(example)) copyFileSync(example, CONFIG);
+		else writeFileSync(CONFIG, JSON.stringify({ notify: { enabled: true }, approval: { enabled: false } }, null, 2) + "\n");
+		say(`  ${c.green("✓")} config        ${c.dim("→ " + CONFIG)}`);
+	}
+
+	say("");
+	say(c.green(c.bold("✅ Installed.")) + " In pi (or after /reload) you now have:");
+	say("   • notify_human + ask_human as tools");
+	say("   • a Telegram ping when each task finishes");
+	say("   • /ping inside pi, and the pah CLI in your terminal");
+	say("   • optional approval prompts (set approval.enabled=true in the config)");
+	say("");
+	say(c.bold("Next:"));
+	say("   1. Configure Telegram (one time):  " + c.bold("npx ping-a-human setup"));
+	say('   2. Try the CLI:                     ' + c.bold('pah ping "hello from my terminal"'));
+}
+
+function uninstall() {
+	say(c.bold("→ Uninstalling ping-a-human-pi"));
+	rmSync(EXT_DIR, { recursive: true, force: true });
+	say(`  ${c.green("✓")} removed extension`);
+	for (const t of pahTargets()) {
+		if (existsSync(t)) {
+			try {
+				rmSync(t, { force: true });
+				say(`  ${c.green("✓")} removed ${t}`);
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+	say(`  ${c.dim("• left config untouched: " + CONFIG)}`);
+	say(c.green("✅ Done."));
+}
+
+const cmd = process.argv[2];
+if (cmd === "uninstall" || cmd === "remove") uninstall();
+else if (!cmd || cmd === "install") install();
+else {
+	say("Usage: npx ping-a-human-pi [install|uninstall]");
+	process.exit(1);
+}

package/bin/pah

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * pah — a tiny CLI for ping-a-human.
+ *
+ *   pah ping [message...]     send a Telegram notification (fire-and-forget)
+ *   pah notify [message...]   alias for `ping`
+ *   pah ask <question...>     ask a human and print their reply (waits)
+ *   pah help                  show usage
+ *
+ * Reads server config from ~/.pi/agent/ping-a-human.json if present
+ * (keys: command, args, env), otherwise defaults to `npx -y ping-a-human`.
+ */
+
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const TIMEOUT_MS = 600_000;
+
+function loadServer() {
+	const candidates = [process.env.PING_A_HUMAN_PI_CONFIG, join(homedir(), ".pi", "agent", "ping-a-human.json")].filter(Boolean);
+	for (const path of candidates) {
+		try {
+			const cfg = JSON.parse(readFileSync(path, "utf8"));
+			return {
+				command: cfg.command ?? "npx",
+				args: cfg.args ?? ["-y", "ping-a-human"],
+				env: cfg.env ?? undefined,
+			};
+		} catch {
+			/* try next */
+		}
+	}
+	return { command: "npx", args: ["-y", "ping-a-human"], env: undefined };
+}
+
+class McpClient {
+	#proc = null;
+	#buf = "";
+	#id = 1;
+	#pending = new Map();
+
+	constructor({ command, args, env }) {
+		this.command = command;
+		this.args = args;
+		this.env = env;
+	}
+
+	async start() {
+		this.#proc = spawn(this.command, this.args, { env: { ...process.env, ...(this.env ?? {}) }, stdio: ["pipe", "pipe", "pipe"] });
+		this.#proc.on("error", (e) => this.#failAll(new Error(`ping-a-human: ${e.message}`)));
+		this.#proc.on("exit", (c) => this.#failAll(new Error(`ping-a-human exited (code ${c})`)));
+		this.#proc.stdout.setEncoding("utf8");
+		this.#proc.stdout.on("data", (c) => this.#onData(c));
+		this.#proc.stderr.setEncoding("utf8");
+		this.#proc.stderr.on("data", () => {});
+		await this.#req("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: "pah-cli", version: "1.0.0" } });
+		this.#notify("notifications/initialized");
+	}
+
+	async call(name, args) {
+		const res = await this.#req("tools/call", { name, arguments: args ?? {} });
+		if (res?.isError) throw new Error((res.content ?? []).map((b) => b.text ?? "").join("\n") || "ping-a-human error");
+		return (res?.content ?? []).map((b) => b.text ?? "").join("\n").trim();
+	}
+
+	stop() {
+		this.#proc?.kill();
+		this.#proc = null;
+	}
+
+	#onData(chunk) {
+		this.#buf += chunk;
+		let i;
+		while ((i = this.#buf.indexOf("\n")) !== -1) {
+			const line = this.#buf.slice(0, i).trim();
+			this.#buf = this.#buf.slice(i + 1);
+			if (!line) continue;
+			let m;
+			try {
+				m = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (m.id == null) continue;
+			const e = this.#pending.get(m.id);
+			if (!e) continue;
+			this.#pending.delete(m.id);
+			clearTimeout(e.timer);
+			if (m.error) e.reject(new Error(m.error.message));
+			else e.resolve(m.result);
+		}
+	}
+
+	#req(method, params) {
+		if (!this.#proc) return Promise.reject(new Error("ping-a-human not running"));
+		const id = this.#id++;
+		this.#proc.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.#pending.delete(id);
+				reject(new Error(`"${method}" timed out`));
+			}, TIMEOUT_MS);
+			this.#pending.set(id, { resolve, reject, timer });
+		});
+	}
+
+	#notify(method, params) {
+		this.#proc?.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+	}
+
+	#failAll(err) {
+		for (const [, e] of this.#pending) {
+			clearTimeout(e.timer);
+			e.reject(err);
+		}
+		this.#pending.clear();
+	}
+}
+
+function usage() {
+	process.stdout.write(
+		[
+			"pah — ping a human from the command line",
+			"",
+			"Usage:",
+			'  pah ping [message...]     send a notification (fire-and-forget)',
+			'  pah notify [message...]   alias for ping',
+			'  pah ask <question...>     ask a human and print their reply (waits)',
+			"  pah help                  show this help",
+			"",
+			"Examples:",
+			'  pah ping "build finished"',
+			'  pah ask "deploy to prod?"',
+			"",
+		].join("\n"),
+	);
+}
+
+async function main() {
+	const [cmd, ...rest] = process.argv.slice(2);
+	const text = rest.join(" ").trim();
+
+	if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+		usage();
+		process.exit(cmd ? 0 : 1);
+	}
+
+	const client = new McpClient(loadServer());
+	try {
+		await client.start();
+		if (cmd === "ping" || cmd === "notify") {
+			const message = text || `👋 Ping from ${process.cwd()}`;
+			const reply = await client.call("notify_human", { message });
+			process.stdout.write(`${reply || "Notification sent."}\n`);
+		} else if (cmd === "ask") {
+			if (!text) {
+				process.stderr.write('pah ask: a question is required, e.g. pah ask "ship it?"\n');
+				process.exitCode = 2;
+			} else {
+				const reply = await client.call("ask_human", { question: text });
+				process.stdout.write(`${reply}\n`);
+			}
+		} else {
+			process.stderr.write(`pah: unknown command "${cmd}"\n\n`);
+			usage();
+			process.exitCode = 2;
+		}
+	} catch (err) {
+		process.stderr.write(`pah: ${err.message}\n`);
+		process.exitCode = 1;
+	} finally {
+		client.stop();
+	}
+}
+
+main();

package/extension/index.ts

@@ -0,0 +1,366 @@
+/**
+ * ping-a-human-pi — human-in-the-loop for pi, powered by ping-a-human.
+ *
+ * Pi has no built-in MCP support, so this extension embeds a tiny MCP stdio
+ * client and connects pi to the `ping-a-human` MCP server. It gives you:
+ *
+ *   1. Tools:        `notify_human` and `ask_human` become native pi tools the
+ *                    model can call directly.
+ *   2. Notifications: when a task finishes (`agent_end`) you get a Telegram ping
+ *                    via `notify_human`.
+ *   3. Approval:      before risky tool calls (`tool_call`) pi asks you via
+ *                    `ask_human` and blocks the call unless you approve.
+ *
+ * Zero config required. To tune behavior, drop a JSON file at
+ *   ~/.pi/agent/ping-a-human.json   (or set $PING_A_HUMAN_PI_CONFIG)
+ * See ping-a-human-pi.example.json for all options.
+ */
+
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Config (all optional)
+// ---------------------------------------------------------------------------
+interface Config {
+	/** How to launch the ping-a-human MCP server. */
+	command?: string;
+	args?: string[];
+	env?: Record<string, string>;
+	/** Register notify_human / ask_human as tools the model can call. Default true. */
+	exposeTools?: boolean;
+	notify?: {
+		enabled?: boolean; // default true
+		template?: string; // {summary} {cwd}
+	};
+	approval?: {
+		enabled?: boolean; // default false
+		tools?: string[]; // pi tool names to gate (default ["bash"])
+		patterns?: string[]; // regex/substrings; if set, only matching calls are gated
+		template?: string; // {tool} {details}
+	};
+}
+
+const DEFAULTS = {
+	command: "npx",
+	args: ["-y", "ping-a-human"],
+	exposeTools: true,
+	notify: {
+		enabled: true,
+		template: "✅ pi finished a task in {cwd}:\n\n{summary}",
+	},
+	approval: {
+		enabled: false,
+		tools: ["bash"],
+		patterns: [
+			"rm\\s+-rf",
+			"\\bsudo\\b",
+			"git\\s+push",
+			"--force",
+			"\\bdd\\b",
+			"mkfs",
+			">\\s*/dev/",
+			"chmod\\s+-R",
+			"chown\\s+-R",
+			":\\(\\)\\s*\\{",
+			"\\bshutdown\\b",
+			"\\breboot\\b",
+		],
+		template: "🔐 pi wants to run {tool}:\n\n{details}\n\nApprove? (reply yes/no)",
+	},
+};
+
+const PROTOCOL_VERSION = "2024-11-05";
+const REQUEST_TIMEOUT_MS = 600_000; // human-in-the-loop calls can wait a while
+
+const NOTIFY_TOOL = "notify_human";
+const ASK_TOOL = "ask_human";
+
+// ---------------------------------------------------------------------------
+// Minimal MCP stdio client (newline-delimited JSON-RPC)
+// ---------------------------------------------------------------------------
+interface JsonRpcResponse {
+	id?: number | string;
+	result?: unknown;
+	error?: { code: number; message: string };
+}
+interface McpTool {
+	name: string;
+	description?: string;
+	inputSchema?: Record<string, unknown>;
+}
+interface McpContentBlock {
+	type: string;
+	text?: string;
+	data?: string;
+	mimeType?: string;
+	[k: string]: unknown;
+}
+
+class McpClient {
+	private proc: ChildProcessWithoutNullStreams | null = null;
+	private buffer = "";
+	private nextId = 1;
+	private pending = new Map<number | string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: NodeJS.Timeout }>();
+
+	constructor(private readonly command: string, private readonly args: string[], private readonly env?: Record<string, string>) {}
+
+	async start(): Promise<McpTool[]> {
+		this.proc = spawn(this.command, this.args, {
+			env: { ...process.env, ...(this.env ?? {}) },
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+		this.proc.on("error", (e) => this.failAll(new Error(`[ping-a-human] ${e.message}`)));
+		this.proc.on("exit", (c) => this.failAll(new Error(`[ping-a-human] exited (code ${c})`)));
+		this.proc.stdout.setEncoding("utf8");
+		this.proc.stdout.on("data", (c: string) => this.onData(c));
+		this.proc.stderr.setEncoding("utf8");
+		this.proc.stderr.on("data", () => {});
+
+		await this.request("initialize", {
+			protocolVersion: PROTOCOL_VERSION,
+			capabilities: {},
+			clientInfo: { name: "ping-a-human-pi", version: "1.0.0" },
+		});
+		this.notify("notifications/initialized");
+		const listed = (await this.request("tools/list", {})) as { tools?: McpTool[] };
+		return listed.tools ?? [];
+	}
+
+	async callTool(name: string, args: unknown, signal?: AbortSignal): Promise<McpContentBlock[]> {
+		const res = (await this.request("tools/call", { name, arguments: args ?? {} }, signal)) as {
+			content?: McpContentBlock[];
+			isError?: boolean;
+		};
+		if (res.isError) throw new Error((res.content ?? []).map((c) => c.text ?? "").join("\n") || "ping-a-human error");
+		return res.content ?? [];
+	}
+
+	stop(): void {
+		this.failAll(new Error("[ping-a-human] stopped"));
+		this.proc?.kill();
+		this.proc = null;
+	}
+
+	private onData(chunk: string): void {
+		this.buffer += chunk;
+		let i: number;
+		while ((i = this.buffer.indexOf("\n")) !== -1) {
+			const line = this.buffer.slice(0, i).trim();
+			this.buffer = this.buffer.slice(i + 1);
+			if (!line) continue;
+			let m: JsonRpcResponse;
+			try {
+				m = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (m.id === undefined || m.id === null) continue;
+			const e = this.pending.get(m.id);
+			if (!e) continue;
+			this.pending.delete(m.id);
+			clearTimeout(e.timer);
+			if (m.error) e.reject(new Error(m.error.message));
+			else e.resolve(m.result);
+		}
+	}
+
+	private request(method: string, params: unknown, signal?: AbortSignal): Promise<unknown> {
+		if (!this.proc) return Promise.reject(new Error("[ping-a-human] not running"));
+		const id = this.nextId++;
+		const payload = `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error(`[ping-a-human] "${method}" timed out`));
+			}, REQUEST_TIMEOUT_MS);
+			this.pending.set(id, { resolve, reject, timer });
+			signal?.addEventListener(
+				"abort",
+				() => {
+					const e = this.pending.get(id);
+					if (e) {
+						this.pending.delete(id);
+						clearTimeout(e.timer);
+						reject(new Error("[ping-a-human] aborted"));
+					}
+				},
+				{ once: true },
+			);
+			this.proc!.stdin.write(payload);
+		});
+	}
+
+	private notify(method: string, params?: unknown): void {
+		this.proc?.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+	}
+
+	private failAll(err: Error): void {
+		for (const [, e] of this.pending) {
+			clearTimeout(e.timer);
+			e.reject(err);
+		}
+		this.pending.clear();
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function loadConfig(): Config {
+	const candidates = [process.env.PING_A_HUMAN_PI_CONFIG, join(homedir(), ".pi", "agent", "ping-a-human.json")].filter(Boolean) as string[];
+	for (const path of candidates) {
+		try {
+			return JSON.parse(readFileSync(path, "utf8")) as Config;
+		} catch {
+			// try next / fall back to defaults
+		}
+	}
+	return {};
+}
+
+function toPiContent(blocks: McpContentBlock[]): Array<Record<string, unknown>> {
+	const out: Array<Record<string, unknown>> = [];
+	for (const b of blocks) {
+		if (b.type === "image" && b.data) out.push({ type: "image", source: { type: "base64", mediaType: b.mimeType ?? "image/png", data: b.data } });
+		else if (typeof b.text === "string") out.push({ type: "text", text: b.text });
+		else out.push({ type: "text", text: JSON.stringify(b) });
+	}
+	if (out.length === 0) out.push({ type: "text", text: "(no content)" });
+	return out;
+}
+
+function blocksToText(blocks: McpContentBlock[]): string {
+	return blocks.map((b) => b.text ?? "").join("\n").trim();
+}
+
+function lastAssistantText(messages: Array<{ role?: string; content?: unknown }>): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m.role !== "assistant") continue;
+		if (typeof m.content === "string") return m.content;
+		if (Array.isArray(m.content)) {
+			const t = m.content
+				.filter((c) => c && typeof c === "object" && (c as { type?: string }).type === "text")
+				.map((c) => (c as { text?: string }).text ?? "")
+				.join("")
+				.trim();
+			if (t) return t;
+		}
+	}
+	return "";
+}
+
+const APPROVED = /^(y|yes|ok|okay|approve|approved|allow|allowed|sure|go|go ahead|lgtm|do it|proceed)\b/i;
+
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+export default async function pingAHumanPi(pi: ExtensionAPI) {
+	const cfg = loadConfig();
+	const command = cfg.command ?? DEFAULTS.command;
+	const args = cfg.args ?? DEFAULTS.args;
+	const exposeTools = cfg.exposeTools ?? DEFAULTS.exposeTools;
+	const notify = { ...DEFAULTS.notify, ...(cfg.notify ?? {}) };
+	const approval = { ...DEFAULTS.approval, ...(cfg.approval ?? {}) };
+
+	const client = new McpClient(command, args, cfg.env);
+	let tools: McpTool[];
+	try {
+		tools = await client.start();
+	} catch (err) {
+		client.stop();
+		// eslint-disable-next-line no-console
+		console.error(`[ping-a-human-pi] could not start ping-a-human: ${(err as Error).message}`);
+		return;
+	}
+
+	// 1. Expose ping-a-human tools to the model.
+	if (exposeTools) {
+		for (const tool of tools) {
+			pi.registerTool({
+				name: tool.name,
+				label: tool.name === ASK_TOOL ? "Ask a human" : tool.name === NOTIFY_TOOL ? "Notify a human" : tool.name,
+				description: tool.description ?? `ping-a-human tool "${tool.name}"`,
+				promptSnippet: tool.description ?? `ping-a-human ${tool.name}`,
+				parameters: Type.Unsafe(tool.inputSchema ?? { type: "object", properties: {} }),
+				async execute(_id, params, signal) {
+					const content = await client.callTool(tool.name, params, signal);
+					return { content: toPiContent(content), details: { tool: tool.name } };
+				},
+			});
+		}
+	}
+
+	const hasNotify = tools.some((t) => t.name === NOTIFY_TOOL);
+	const hasAsk = tools.some((t) => t.name === ASK_TOOL);
+
+	// 2. Notify on task completion.
+	if (notify.enabled && hasNotify) {
+		pi.on("agent_end", async (event, ctx) => {
+			const messages = (event as { messages?: Array<{ role?: string; content?: unknown }> }).messages ?? [];
+			let summary = lastAssistantText(messages) || "Task finished.";
+			if (summary.length > 1500) summary = `${summary.slice(0, 1500)}…`;
+			const message = notify.template.replace("{summary}", summary).replace("{cwd}", ctx.cwd);
+			try {
+				await client.callTool(NOTIFY_TOOL, { message });
+			} catch {
+				// never let a notification failure affect the agent
+			}
+		});
+	}
+
+	// 3. Human-in-the-loop approval before risky tool calls.
+	if (approval.enabled && hasAsk) {
+		const gated = new Set(approval.tools);
+		const patterns = approval.patterns.map((p) => {
+			try {
+				return new RegExp(p, "i");
+			} catch {
+				return new RegExp(p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i");
+			}
+		});
+
+		pi.on("tool_call", async (event: { toolName: string; input: unknown }, ctx: ExtensionContext) => {
+			if (!gated.has(event.toolName)) return;
+			const serialized = JSON.stringify(event.input ?? {});
+			if (patterns.length > 0 && !patterns.some((re) => re.test(serialized))) return;
+
+			const details = serialized.length > 1200 ? `${serialized.slice(0, 1200)}…` : serialized;
+			const question = approval.template.replace("{tool}", event.toolName).replace("{details}", details);
+			try {
+				const reply = blocksToText(await client.callTool(ASK_TOOL, { question }, ctx.signal));
+				if (APPROVED.test(reply.trim())) return; // approved
+				return { block: true, reason: `Blocked by human: ${reply || "declined"}` };
+			} catch (err) {
+				return { block: true, reason: `ping-a-human approval unavailable: ${(err as Error).message}` };
+			}
+		});
+	}
+
+	// 4. /ping command — manually notify a human (optionally with a message).
+	//    /ping              -> sends a default "pinging you from pi" message
+	//    /ping <message>    -> sends your message
+	if (hasNotify) {
+		pi.registerCommand("ping", {
+			description: "Send a Telegram notification via ping-a-human (/ping [message])",
+			handler: async (args, ctx) => {
+				const message = (args ?? "").trim() || `\uD83D\uDC4B Ping from pi (${ctx.cwd})`;
+				try {
+					const reply = blocksToText(await client.callTool(NOTIFY_TOOL, { message }, ctx.signal));
+					ctx.ui.notify(reply || "Notification sent.", "info");
+				} catch (err) {
+					ctx.ui.notify(`Ping failed: ${(err as Error).message}`, "error");
+				}
+			},
+		});
+	}
+
+	pi.on("session_shutdown", async () => {
+		client.stop();
+	});
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "ping-a-human-pi",
+  "version": "0.1.0",
+  "description": "Human-in-the-loop and notifications for the pi coding agent, powered by ping-a-human. One command: npx ping-a-human-pi.",
+  "type": "module",
+  "bin": {
+    "ping-a-human-pi": "bin/cli.mjs",
+    "pah": "bin/pah"
+  },
+  "files": [
+    "bin",
+    "extension",
+    "ping-a-human-pi.example.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["pi-package", "pi", "mcp", "ping-a-human", "human-in-the-loop", "notifications", "cli"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/startriseio/ping-a-human.git",
+    "directory": "ping-a-human-pi"
+  },
+  "homepage": "https://github.com/startriseio/ping-a-human#readme",
+  "bugs": {
+    "url": "https://github.com/startriseio/ping-a-human/issues"
+  },
+  "license": "MIT",
+  "pi": {
+    "extensions": ["./extension"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/ping-a-human-pi.example.json

@@ -0,0 +1,32 @@
+{
+  "//": "Optional config for ping-a-human-pi. Copy to ~/.pi/agent/ping-a-human.json and edit. Everything here is optional; omit keys to use defaults.",
+
+  "command": "npx",
+  "args": ["-y", "ping-a-human"],
+
+  "exposeTools": true,
+
+  "notify": {
+    "enabled": true,
+    "template": "✅ pi finished a task in {cwd}:\n\n{summary}"
+  },
+
+  "approval": {
+    "enabled": false,
+    "tools": ["bash"],
+    "patterns": [
+      "rm\\s+-rf",
+      "\\bsudo\\b",
+      "git\\s+push",
+      "--force",
+      "\\bdd\\b",
+      "mkfs",
+      ">\\s*/dev/",
+      "chmod\\s+-R",
+      "chown\\s+-R",
+      "\\bshutdown\\b",
+      "\\breboot\\b"
+    ],
+    "template": "🔐 pi wants to run {tool}:\n\n{details}\n\nApprove? (reply yes/no)"
+  }
+}