pi-inspect 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# pi-inspect
+
+[![npm version](https://img.shields.io/npm/v/pi-inspect.svg)](https://www.npmjs.com/package/pi-inspect)
+[![npm downloads](https://img.shields.io/npm/dm/pi-inspect.svg)](https://www.npmjs.com/package/pi-inspect)
+
+Introspection dashboard for the [pi coding agent](https://pi.dev) — see what's actually loaded into a session: tools, slash commands, skills, and the system prompt injected on init.
+
+![pi-inspect demo](https://raw.githubusercontent.com/NikiforovAll/pi-inspect/main/assets/demo.png)
+
+## Installation
+
+```sh
+pi install npm:pi-inspect
+```
+
+Then use `/inspect start | stop | restart | status | open | list | snapshot` from inside pi.
+
+## Usage (inside a pi session)
+
+| Command | What it does |
+| --- | --- |
+| `/inspect` | Open the dashboard for the **current** session in your browser (`http://localhost:5462/?session=<id>`) |
+| `/inspect <sessionId>` | Open dashboard pinned to a specific past session |
+| `/inspect snapshot` | Re-capture the current session snapshot now |
+| `/inspect list` | Print all captured session IDs in the terminal |
+| `/inspect open web\|app` | Open in browser or as a PWA window |
+| `/inspect start` / `stop` / `restart` / `status` | Manage the local server |
+
+State is driven entirely through the `?session=` URL param — share or refresh URLs to pin views. The in-page picker also writes to the URL.
+
+## What it captures
+
+- **Tools** — name, description, parameter schema, source
+- **Slash commands** — name, source
+- **System prompt** — full text injected on init, split into system / user `AGENTS.md` / project `AGENTS.md` sections
+- **Session meta** — cwd, model, sessionId, sessionName, captured timestamp
+
+Snapshots live at `~/.pi/agent/inspect/snapshots/<sessionId>.json`.
+
+## Port
+
+`5462` — override via `PORT` env var.

package/extensions/inspect.ts

@@ -0,0 +1,309 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { homedir } from "node:os";
+import { join as joinPath, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const extDir = fileURLToPath(new URL(".", import.meta.url));
+const port = 5462;
+const url = `http://localhost:${port}`;
+
+const INSPECT_DIR = joinPath(homedir(), ".pi", "agent", "inspect");
+const SNAP_DIR = joinPath(INSPECT_DIR, "snapshots");
+const INDEX_PATH = joinPath(SNAP_DIR, "index.json");
+
+let child: ChildProcess | null = null;
+let lastStderr = "";
+let piRef: ExtensionAPI | null = null;
+
+function probePort(p: number, timeoutMs = 250): Promise<boolean> {
+	return new Promise((resolve) => {
+		const sock = createConnection({ port: p, host: "127.0.0.1" });
+		const done = (ok: boolean) => { sock.destroy(); resolve(ok); };
+		sock.setTimeout(timeoutMs);
+		sock.once("connect", () => done(true));
+		sock.once("timeout", () => done(false));
+		sock.once("error", () => done(false));
+	});
+}
+
+async function waitForPort(p: number, totalMs = 5000): Promise<boolean> {
+	const start = Date.now();
+	while (Date.now() - start < totalMs) {
+		if (await probePort(p)) return true;
+		await new Promise((r) => setTimeout(r, 150));
+	}
+	return false;
+}
+
+function findPidsOnPort(p: number): number[] {
+	if (process.platform === "win32") {
+		const r = spawnSync("netstat", ["-ano", "-p", "tcp"], { encoding: "utf8" });
+		if (r.status !== 0) return [];
+		const pids = new Set<number>();
+		for (const line of r.stdout.split(/\r?\n/)) {
+			const m = line.match(/^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)/i);
+			if (m && Number(m[1]) === p) pids.add(Number(m[2]));
+		}
+		return [...pids];
+	}
+	const r = spawnSync("lsof", ["-tiTCP:" + p, "-sTCP:LISTEN"], { encoding: "utf8" });
+	if (r.status !== 0) return [];
+	return r.stdout.split(/\s+/).map(Number).filter((n) => Number.isFinite(n) && n > 0);
+}
+
+function killPid(pid: number): void {
+	if (process.platform === "win32") {
+		spawnSync("taskkill", ["/F", "/PID", String(pid)], { stdio: "ignore" });
+	} else {
+		try { process.kill(pid, "SIGKILL"); } catch {}
+	}
+}
+
+function sanitize(id: string): string {
+	return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+type IndexEntry = {
+	id: string;
+	cwd: string | null;
+	name: string | null;
+	model: string | null;
+	capturedAt: number;
+};
+
+function readIndex(): IndexEntry[] {
+	try {
+		const parsed = JSON.parse(readFileSync(INDEX_PATH, "utf8")) as { sessions?: IndexEntry[] };
+		return Array.isArray(parsed.sessions) ? parsed.sessions : [];
+	} catch (e: any) {
+		if (e?.code !== "ENOENT") console.warn(`pi-inspect: read index: ${e.message}`);
+		return [];
+	}
+}
+
+function writeIndex(entries: IndexEntry[]): void {
+	mkdirSync(SNAP_DIR, { recursive: true });
+	writeFileSync(INDEX_PATH, JSON.stringify({ sessions: entries }, null, 2), "utf8");
+}
+
+function upsertIndex(entry: IndexEntry): void {
+	const list = readIndex().filter((e) => e.id !== entry.id);
+	list.push(entry);
+	writeIndex(list);
+}
+
+function writeSnapshot(id: string, snapshot: unknown): void {
+	mkdirSync(SNAP_DIR, { recursive: true });
+	writeFileSync(joinPath(SNAP_DIR, `${sanitize(id)}.json`), JSON.stringify(snapshot, null, 2), "utf8");
+}
+
+function captureSnapshot(ctx: any): { id: string; entry: IndexEntry } | null {
+	const sm = ctx.sessionManager;
+	const id = sm?.getSessionId?.();
+	if (!id) return null;
+	const cwd = sm?.getCwd?.() ?? null;
+	const name = sm?.getSessionName?.() ?? null;
+	const model = ctx.getModel?.()?.id ?? null;
+	const systemPrompt = typeof ctx.getSystemPrompt === "function" ? ctx.getSystemPrompt() : null;
+	const pi = piRef as any;
+	const commands = typeof pi?.getCommands === "function" ? pi.getCommands() : [];
+	const tools = typeof pi?.getAllTools === "function" ? pi.getAllTools() : [];
+	const activeTools = typeof pi?.getActiveTools === "function" ? pi.getActiveTools() : [];
+	const capturedAt = Date.now();
+	const snap = { sessionId: id, sessionName: name, cwd, model, systemPrompt, commands, tools, activeTools, capturedAt };
+	try {
+		writeSnapshot(id, snap);
+		upsertIndex({ id, cwd, name, model, capturedAt });
+	} catch (e: any) {
+		console.warn(`pi-inspect: snapshot write failed: ${e?.message ?? e}`);
+		return null;
+	}
+	return { id, entry: { id, cwd, name, model, capturedAt } };
+}
+
+async function startServer(notify: (m: string, l?: "info" | "error") => void): Promise<boolean> {
+	if (await probePort(port)) return true;
+	lastStderr = "";
+	const serverPath = resolvePath(extDir, "..", "server.js");
+	child = spawn(process.execPath, [serverPath], {
+		env: { ...process.env, PORT: String(port) },
+		stdio: ["ignore", "ignore", "pipe"],
+		detached: true,
+		windowsHide: true,
+	});
+	child.stderr?.on("data", (b) => { lastStderr += b.toString(); });
+	child.on("exit", () => { child = null; });
+	if (!(await waitForPort(port))) {
+		notify(`pi-inspect failed to start.\n${lastStderr.slice(-500) || "(no stderr)"}`, "error");
+		return false;
+	}
+	child.stderr?.removeAllListeners("data");
+	child.stderr?.resume();
+	child.unref();
+	return true;
+}
+
+async function stopServer(notify: (m: string, l?: "info" | "error") => void): Promise<void> {
+	if (child) child.kill("SIGINT");
+	child = null;
+	if (await probePort(port)) {
+		const pids = findPidsOnPort(port);
+		for (const pid of pids) killPid(pid);
+		await new Promise((r) => setTimeout(r, 300));
+	}
+	notify("pi-inspect stopped");
+}
+
+const SUBCOMMANDS = ["start", "stop", "restart", "status", "open", "list", "snapshot"] as const;
+type Sub = (typeof SUBCOMMANDS)[number];
+const OPEN_TARGETS = ["web", "app"] as const;
+
+function showHelp(notify: (m: string, l?: "info" | "error") => void) {
+	notify(
+		[
+			"Usage: /inspect <command>",
+			"",
+			"  start              Start the dashboard server",
+			"  stop               Stop the dashboard server",
+			"  restart            Restart the dashboard server",
+			"  status             Show server status",
+			"  open web           Open dashboard in browser (default)",
+			"  open app           Open dashboard as PWA window",
+			"  list               List captured session snapshots",
+			"  snapshot           Re-capture the current session now",
+			"",
+			"Bare `/inspect` ensures the server is running and opens the current session.",
+			"`/inspect <sessionId>` opens a specific past session.",
+		].join("\n"),
+	);
+}
+
+export default function inspectExtension(pi: ExtensionAPI) {
+	piRef = pi;
+	pi.on("session_start", async (_event, ctx) => {
+		captureSnapshot(ctx);
+	});
+	// session_start fires before all extensions register their tools/commands.
+	// before_agent_start fires after the user's first prompt with the fully assembled state — re-capture then.
+	pi.on("before_agent_start", async (_event, ctx) => {
+		captureSnapshot(ctx);
+	});
+
+	pi.registerCommand("inspect", {
+		description:
+			"pi-inspect dashboard: start | stop | restart | status | open web|app | list | snapshot. " +
+			"Bare `/inspect` opens the current session; `/inspect <sessionId>` opens a specific session.",
+		getArgumentCompletions: (prefix) => {
+			const tokens = prefix.trim().split(/\s+/).filter(Boolean);
+			if (tokens.length >= 1 && tokens[0] === "open") {
+				const v = tokens[1] ?? "";
+				return OPEN_TARGETS
+					.filter((t) => t.startsWith(v))
+					.map((t) => ({ value: `open ${t}`, label: t }));
+			}
+			return SUBCOMMANDS.filter((s) => s.startsWith(prefix)).map((s) => ({ value: s, label: s }));
+		},
+		handler: async (args, ctx) => {
+			const notify = (m: string, l: "info" | "error" = "info") => ctx.ui.notify(m, l);
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const first = tokens[0] as Sub | string | undefined;
+
+			if (first === "help" || first === "--help" || first === "-h") {
+				showHelp(notify);
+				return;
+			}
+
+			if (first === "stop") return stopServer(notify);
+
+			if (first === "status") {
+				const up = await probePort(port);
+				notify(up ? `running on ${url}` : "not running");
+				return;
+			}
+
+			if (first === "start") {
+				if (!(await startServer(notify))) return;
+				captureSnapshot(ctx);
+				notify(`pi-inspect started → ${url}`);
+				return;
+			}
+
+			if (first === "restart") {
+				await stopServer(notify);
+				await new Promise((r) => setTimeout(r, 200));
+				if (!(await startServer(notify))) return;
+				notify(`pi-inspect restarted → ${url}`);
+				return;
+			}
+
+			if (first === "list") {
+				const list = readIndex();
+				if (!list.length) { notify("no snapshots yet — run /inspect to capture this session"); return; }
+				const sorted = [...list].sort((a, b) => b.capturedAt - a.capturedAt);
+				const lines = sorted.map((e) =>
+					`  ${e.id}  ${e.name ?? "(no name)"}  cwd=${e.cwd ?? "?"}  model=${e.model ?? "?"}`,
+				);
+				notify(`pi-inspect snapshots:\n${lines.join("\n")}`);
+				return;
+			}
+
+			if (first === "snapshot") {
+				const r = captureSnapshot(ctx);
+				notify(r ? `snapshot captured: ${r.id}` : "no active session to snapshot", r ? "info" : "error");
+				return;
+			}
+
+			// `open [web|app]` and default (bare /inspect or /inspect <sessionId>)
+			const isExplicitOpen = first === "open";
+			const openTarget = (isExplicitOpen ? (tokens[1] ?? "web") : "web") as "web" | "app";
+
+			if (!(await startServer(notify))) return;
+			captureSnapshot(ctx);
+
+			let openId: string | null = null;
+			if (!isExplicitOpen && first && !(SUBCOMMANDS as readonly string[]).includes(first)) {
+				openId = first; // /inspect <sessionId>
+			} else {
+				openId = ctx.sessionManager?.getSessionId?.() ?? null;
+			}
+
+			const target = openId ? `${url}/?session=${encodeURIComponent(openId)}` : url;
+
+			// If a dashboard tab is already connected, ask it to navigate instead of opening a new window.
+			if (!isExplicitOpen) {
+				try {
+					const r = await fetch(`${url}/api/focus`, {
+						method: "POST",
+						headers: { "content-type": "application/json" },
+						body: JSON.stringify({ session: openId }),
+					});
+					const { delivered } = (await r.json()) as { delivered: number };
+					if (delivered > 0) {
+						notify(`focused existing dashboard → session ${openId ?? "(latest)"}`);
+						return;
+					}
+				} catch {}
+			}
+
+			if (openTarget === "app") {
+				const { default: openFn, apps } = await import("open");
+				for (const name of [apps.chrome, apps.edge, apps.browser]) {
+					try {
+						await openFn(target, { app: { name, arguments: [`--app=${target}`] } });
+						notify(`opened ${target} (app)`);
+						return;
+					} catch {}
+				}
+				notify("Could not find Chrome/Edge for PWA window mode", "error");
+				return;
+			}
+
+			const { default: openFn } = await import("open");
+			await openFn(target);
+			notify(`opened ${target}`);
+		},
+	});
+}

package/extensions/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/extensions/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "lib": ["es2024"],
+    "types": ["node"]
+  },
+  "include": ["./**/*.ts"]
+}

package/lib/snapshot.js

@@ -0,0 +1,56 @@
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+
+const SNAPSHOT_DIR = process.env.INSPECT_SNAPSHOT_DIR
+  || path.join(os.homedir(), '.pi', 'agent', 'inspect', 'snapshots');
+const INDEX_PATH = path.join(SNAPSHOT_DIR, 'index.json');
+
+function snapshotDir() {
+  return SNAPSHOT_DIR;
+}
+
+function snapshotPath(sessionId) {
+  return path.join(SNAPSHOT_DIR, `${sanitize(sessionId)}.json`);
+}
+
+function sanitize(id) {
+  return String(id).replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+async function readIndex() {
+  try {
+    const raw = await fsp.readFile(INDEX_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed?.sessions) ? parsed.sessions : [];
+  } catch (e) {
+    if (e.code !== 'ENOENT') console.warn(`pi-inspect: read index: ${e.message}`);
+    return [];
+  }
+}
+
+async function readSnapshot(sessionId) {
+  try {
+    const raw = await fsp.readFile(snapshotPath(sessionId), 'utf8');
+    return JSON.parse(raw);
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
+async function readLatestSnapshot() {
+  const sessions = await readIndex();
+  if (!sessions.length) return null;
+  const sorted = [...sessions].sort((a, b) => (b.capturedAt || 0) - (a.capturedAt || 0));
+  return readSnapshot(sorted[0].id);
+}
+
+module.exports = {
+  snapshotDir,
+  snapshotPath,
+  readIndex,
+  readSnapshot,
+  readLatestSnapshot,
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "pi-inspect",
+  "version": "0.1.0",
+  "description": "Introspection dashboard for the pi coding agent — tools, slash commands, skills, and the system prompt injected on init.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "inspect",
+    "introspection",
+    "dashboard",
+    "observability"
+  ],
+  "license": "MIT",
+  "author": "nikiforovall",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NikiforovAll/pi-inspect.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NikiforovAll/pi-inspect/issues"
+  },
+  "homepage": "https://github.com/NikiforovAll/pi-inspect#readme",
+  "bin": {
+    "pi-inspect": "server.js"
+  },
+  "main": "server.js",
+  "files": [
+    "server.js",
+    "lib/",
+    "public/",
+    "extensions/",
+    "themes/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node server.js --open",
+    "typecheck:extensions": "tsc -p extensions/tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "chokidar": "^3.5.3",
+    "express": "^4.19.2",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "typescript": "^5.8.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "image": "https://raw.githubusercontent.com/NikiforovAll/pi-inspect/main/assets/demo.png"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}