pi-subagent-windows 0.0.0-stage → 0.1.0

package/shared.ts

@@ -0,0 +1,385 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+	accessSync,
+	constants,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+
+export type RunState = "starting" | "busy" | "idle" | "exited" | "error";
+
+export interface RunMetadata {
+	version: 1;
+	handle: string;
+	name?: string;
+	parentSessionId?: string;
+	parentSessionFile?: string;
+	childSessionId?: string;
+	tmuxSession: string;
+	runDir: string;
+	sessionFile: string;
+	cwd: string;
+	provider: string;
+	model: string;
+	thinking: string;
+	/** Extra pi CLI flags (tools, isolation) reused when the run is relaunched. */
+	launchArgs?: string[];
+	/** Set by the parent when it stops the child on quit or session switch; the child is relaunched on resume. */
+	suspended?: boolean;
+	state: RunState;
+	hasStarted: boolean;
+	createdAt: string;
+	updatedAt: string;
+	error?: string;
+}
+
+export interface InboxMessage {
+	message: string;
+	delivery: "auto" | "followUp";
+}
+
+interface SessionEntry {
+	type: string;
+	id: string;
+	parentId: string | null;
+	message?: unknown;
+}
+
+interface AssistantMessage {
+	role: "assistant";
+	content?: unknown;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+interface AssistantEntry extends SessionEntry {
+	type: "message";
+	message: AssistantMessage;
+}
+
+export function getAgentDir(): string {
+	return process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}
+
+export function getRunsDir(): string {
+	return join(getAgentDir(), "subagents");
+}
+
+export function isWindows(): boolean {
+	return process.platform === "win32";
+}
+
+/** Location of the supervisor pid file used by the Windows process host. */
+export function supervisorPidPath(runDir: string): string {
+	return join(runDir, "supervisor.pid");
+}
+
+export function readSupervisorPid(runDir: string): number | undefined {
+	try {
+		const value = Number.parseInt(readFileSync(supervisorPidPath(runDir), "utf8").trim(), 10);
+		return Number.isInteger(value) && value > 0 ? value : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function processIsAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/**
+ * On Windows a run is a detached supervisor process tracked through its pid file.
+ * On other platforms the legacy tmux session remains the source of liveness.
+ */
+export function isRunAlive(metadata: RunMetadata): boolean {
+	if (isWindows()) {
+		const pid = readSupervisorPid(metadata.runDir);
+		return pid !== undefined && processIsAlive(pid);
+	}
+	return tmuxSessionExists(metadata.tmuxSession);
+}
+
+/** Terminate a run and its whole process tree. */
+export function killRun(metadata: RunMetadata): void {
+	if (isWindows()) {
+		const pid = readSupervisorPid(metadata.runDir);
+		if (pid !== undefined && processIsAlive(pid)) {
+			spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+		}
+		return;
+	}
+	spawnSync("tmux", ["kill-session", "-t", metadata.tmuxSession], { stdio: "ignore" });
+}
+
+/** Resolve the managed Pi CLI entry the same way the pi launcher does. */
+export function resolvePiCliPath(): string {
+	const installRoot = join(getAgentDir(), "install");
+	const currentVersion = readFileSync(join(installRoot, "current-version"), "utf8").trim();
+	if (!currentVersion || !/^[0-9A-Za-z._+-]+$/.test(currentVersion)) {
+		throw new Error("The managed Pi version file is invalid");
+	}
+	const packageDirectory = join(installRoot, "releases", currentVersion, "node_modules", "@earendil-works", "pi-coding-agent");
+	const manifest: unknown = JSON.parse(readFileSync(join(packageDirectory, "package.json"), "utf8"));
+	const bin = (manifest as { bin?: string | Record<string, string> }).bin;
+	const binPath = typeof bin === "string" ? bin : bin?.pi;
+	if (!binPath) throw new Error("The installed Pi package does not declare a pi bin");
+	return resolve(packageDirectory, binPath);
+}
+
+/** Atomically queue a message for a running child. */
+export function writeInboxMessage(runDir: string, payload: InboxMessage): void {
+	const queueDir = inboxDir(runDir);
+	mkdirSync(queueDir, { recursive: true, mode: 0o700 });
+	const id = `${Date.now()}-${randomBytes(4).toString("hex")}`;
+	const target = join(queueDir, `${id}.json`);
+	const temporary = `${target}.tmp`;
+	writeFileSync(temporary, `${JSON.stringify(payload)}\n`, { encoding: "utf8", mode: 0o600 });
+	renameSync(temporary, target);
+}
+
+export function metadataPath(runDir: string): string {
+	return join(runDir, "metadata.json");
+}
+
+export function inboxDir(runDir: string): string {
+	return join(runDir, "inbox");
+}
+
+export function isValidRunName(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.length <= 64 &&
+		value.trim() === value &&
+		!/[\u0000-\u001f\u007f]/.test(value)
+	);
+}
+
+export function runDisplayName(metadata: RunMetadata): string {
+	return metadata.name ? `${metadata.name} (${metadata.handle})` : metadata.handle;
+}
+
+export function readMetadata(runDir: string): RunMetadata | undefined {
+	try {
+		const value: unknown = JSON.parse(readFileSync(metadataPath(runDir), "utf8"));
+		if (typeof value !== "object" || value === null) return undefined;
+		const metadata = value as Partial<RunMetadata>;
+		if (
+			metadata.version !== 1 ||
+			typeof metadata.handle !== "string" ||
+			(metadata.name !== undefined && !isValidRunName(metadata.name)) ||
+			typeof metadata.tmuxSession !== "string" ||
+			typeof metadata.sessionFile !== "string" ||
+			typeof metadata.runDir !== "string"
+		) {
+			return undefined;
+		}
+		return metadata as RunMetadata;
+	} catch {
+		return undefined;
+	}
+}
+
+export function writeMetadata(metadata: RunMetadata): void {
+	mkdirSync(dirname(metadataPath(metadata.runDir)), { recursive: true, mode: 0o700 });
+	const target = metadataPath(metadata.runDir);
+	const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+	writeFileSync(temporary, `${JSON.stringify(metadata, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+	renameSync(temporary, target);
+}
+
+export function updateMetadata(runDir: string, patch: Partial<RunMetadata>): RunMetadata | undefined {
+	const current = readMetadata(runDir);
+	if (!current) return undefined;
+	const next: RunMetadata = {
+		...current,
+		...patch,
+		version: 1,
+		handle: current.handle,
+		runDir: current.runDir,
+		updatedAt: new Date().toISOString(),
+	};
+	writeMetadata(next);
+	return next;
+}
+
+export async function waitForRunShutdown(runDir: string, timeoutMs = 2000): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const metadata = readMetadata(runDir);
+		if (!metadata || metadata.state === "exited" || !isRunAlive(metadata)) return;
+		await new Promise<void>((resolveDelay) => setTimeout(resolveDelay, 50));
+	}
+}
+
+export function removeRunDir(runDir: string): void {
+	rmSync(runDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+}
+
+export function tmuxSessionExists(session: string): boolean {
+	return spawnSync("tmux", ["has-session", "-t", session], { stdio: "ignore" }).status === 0;
+}
+
+/**
+ * Start the child pi process for a run.
+ *
+ * On Windows this spawns a detached, hidden supervisor that owns a `pi --mode rpc`
+ * child, so subagents survive `/reload` and parent restarts. The initial task is
+ * delivered through the inbox instead of CLI arguments, so `initialArgs` is only
+ * used on the tmux path.
+ */
+export function launchRun(metadata: RunMetadata, initialArgs: string[] = []): void {
+	if (isWindows()) {
+		const supervisorPath = join(packageDir, "supervisor.ts");
+		const child = spawn(process.execPath, [supervisorPath, metadata.runDir], {
+			cwd: metadata.cwd,
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true,
+			env: { ...process.env },
+		});
+		child.unref();
+		if (!child.pid) throw new Error("Failed to start the subagent supervisor");
+		return;
+	}
+
+	let launcher = "pi";
+	const testLauncher = join(metadata.cwd, "pi-test.sh");
+	try {
+		accessSync(testLauncher, constants.X_OK);
+		launcher = testLauncher;
+	} catch {
+		// Use the installed pi executable.
+	}
+
+	const result = spawnSync(
+		"tmux",
+		[
+			"new-session",
+			"-d",
+			"-s",
+			metadata.tmuxSession,
+			"-x",
+			"120",
+			"-y",
+			"40",
+			"-c",
+			metadata.cwd,
+			"--",
+			"env",
+			`PI_SUBAGENT_RUN_DIR=${metadata.runDir}`,
+			launcher,
+			"--session",
+			metadata.sessionFile,
+			"--provider",
+			metadata.provider,
+			"--model",
+			metadata.model,
+			"--thinking",
+			metadata.thinking,
+			...(metadata.launchArgs ?? []),
+			...initialArgs,
+		],
+		{ encoding: "utf8" },
+	);
+	if (result.status !== 0) throw new Error(result.stderr.trim() || "Failed to create tmux session");
+}
+
+export function effectiveRunState(metadata: RunMetadata): RunState {
+	if (
+		(metadata.state === "starting" || metadata.state === "busy" || metadata.state === "idle") &&
+		!isRunAlive(metadata)
+	) {
+		return "exited";
+	}
+	return metadata.state;
+}
+
+export function listRuns(parentSessionId?: string): RunMetadata[] {
+	const root = getRunsDir();
+	if (!existsSync(root)) return [];
+	const runs: RunMetadata[] = [];
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const metadata = readMetadata(join(root, entry.name));
+		if (!metadata) continue;
+		if (parentSessionId && metadata.parentSessionId !== parentSessionId) continue;
+		runs.push(metadata);
+	}
+	return runs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+
+function isSessionEntry(value: unknown): value is SessionEntry {
+	if (typeof value !== "object" || value === null) return false;
+	const entry = value as Record<string, unknown>;
+	return (
+		typeof entry.type === "string" &&
+		typeof entry.id === "string" &&
+		(entry.parentId === null || typeof entry.parentId === "string")
+	);
+}
+
+function activeBranch(entries: SessionEntry[]): SessionEntry[] {
+	const byId = new Map(entries.map((entry) => [entry.id, entry]));
+	const branch: SessionEntry[] = [];
+	const seen = new Set<string>();
+	let current = entries.at(-1);
+	while (current && !seen.has(current.id)) {
+		branch.push(current);
+		seen.add(current.id);
+		current = current.parentId === null ? undefined : byId.get(current.parentId);
+	}
+	return branch.reverse();
+}
+
+function isAssistantEntry(entry: SessionEntry): entry is AssistantEntry {
+	if (entry.type !== "message" || typeof entry.message !== "object" || entry.message === null) return false;
+	return (entry.message as Record<string, unknown>).role === "assistant";
+}
+
+export function readLatestAssistant(sessionFile: string): AssistantMessage | undefined {
+	let content: string;
+	try {
+		content = readFileSync(sessionFile, "utf8");
+	} catch {
+		return undefined;
+	}
+	const entries: SessionEntry[] = [];
+	for (const line of content.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const value: unknown = JSON.parse(line);
+			if (isSessionEntry(value)) entries.push(value);
+		} catch {
+			// The final JSONL record may still be in the process of being appended.
+		}
+	}
+	return activeBranch(entries).findLast(isAssistantEntry)?.message;
+}
+
+export function assistantText(message: AssistantMessage): string {
+	if (!Array.isArray(message.content)) return message.errorMessage ?? "(no response text)";
+	const parts: string[] = [];
+	for (const item of message.content) {
+		if (typeof item !== "object" || item === null) continue;
+		const block = item as Record<string, unknown>;
+		if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts.join("\n").trim() || message.errorMessage || "(no response text)";
+}

package/skills/subagent/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: subagent
+description: Spawn and communicate with observable Pi subagents for second opinions, independent investigations, and delegated implementation work.
+---
+
+# Subagent
+
+Use the `subagent` CLI to delegate work to a separate Pi process with its own context and tmux session. Managed subagents cannot spawn nested subagents, and this skill is not loaded into their sessions.
+
+## Spawn
+
+Give each child a short, descriptive name. The name appears in the parent UI, while the generated handle remains its stable identifier:
+
+```sh
+subagent spawn --name implementation --prompt "Complete task"
+```
+
+By default, the child inherits the current Pi provider, model, and reasoning level from the bash environment. Use `--provider`, `--model`, or `--thinking` only when deliberately choosing a different configuration, for example a faster model for simple investigation or a stronger model for difficult review. Never pass `$PI_PROVIDER`, `$PI_MODEL`, or `$PI_REASONING_LEVEL` back to the CLI explicitly.
+
+`--cwd` defaults to the current directory. Repeat `--prompt` and `--file` as needed; Pi receives all of them in the first user turn. Run `subagent spawn` directly without piping or redirecting its concise output.
+
+## Tools
+
+Without `--tools`, Pi enables its four default tools:
+
+- `read` - Read text files and images.
+- `bash` - Execute shell commands. This can also modify files, so it is not a read-only capability.
+- `edit` - Apply exact text replacements to existing files.
+- `write` - Create or overwrite files.
+
+Three additional built-in tools are available but off by default:
+
+- `grep` - Search file contents.
+- `find` - Find files by glob pattern.
+- `ls` - List directory contents.
+
+`--tools` is a comma-separated allowlist across built-in, extension, and custom tools. Common choices:
+
+```sh
+# Enforced read-only repository investigation
+--tools read,grep,find,ls
+
+# Investigation that may run tests or other commands; bash can modify files
+--tools read,bash,grep,find,ls
+
+# Implementation work: omit --tools to use the defaults
+```
+
+## Isolation flags
+
+- `--no-extensions` - Disable normal extension discovery. Use for an independent run that should not inherit unrelated extension behavior or extension-provided tools. The subagent control bridge is still explicitly loaded.
+- `--no-skills` - Hide installed skills from the child. Use for tightly specified tasks that should rely only on the supplied prompt and files.
+- `--no-prompt-templates` - Disable prompt-template commands. Usually unnecessary, but useful when testing a minimal child environment.
+- `--no-context-files` - Ignore repository instruction files such as `AGENTS.md` and `CLAUDE.md`. Use only when those instructions would bias an independent investigation. Do not use for implementation unless intentionally bypassing repository guidance.
+
+Spawn prints a random handle and either the tmux attach command or (on Windows) the session file path. Keep the handle for later commands. Subagents persist after their current turn completes: `wait`, completion, and becoming idle do not terminate them. They survive `/reload`. When the spawning Pi session quits or is replaced, they are suspended and relaunched idle with their history when that session is resumed. They are only removed by `subagent stop`.
+
+## Inspect and wait
+
+```sh
+subagent status <handle>
+subagent list
+subagent wait <handle>
+```
+
+Run `subagent list` at any time to rediscover active subagents and their handles, names, and current states if you no longer remember them.
+
+`wait` follows the durable session state and prints the latest final assistant response. Run it directly so the bash tool returns that response; do not redirect it to a file or pipe it unless the user explicitly asks for an artifact. Do not infer completion from captured terminal text. Set the bash timeout above `wait`'s default 1800-second deadline.
+
+## Communicate
+
+```sh
+# Change the name shown in the parent UI.
+subagent rename <handle> "new name"
+
+# Idle: starts a new prompt. Busy: steers the current work.
+subagent send <handle> "message"
+
+# Busy: waits until current work finishes, then starts another turn.
+subagent send <handle> --follow-up "message"
+```
+
+Names are 1–64 characters and need not be unique. Messages use the subagent extension's control inbox; do not use `tmux send-keys`.
+
+## Stop
+
+```sh
+subagent stop <handle>
+```
+
+Explicitly stop every subagent when it is no longer needed; do not leave completed subagents running idle. This terminates tmux and removes the run transcript and metadata. Keep an idle subagent alive only when concrete follow-up work is expected, then stop it afterward.
+
+The interactive `/subagent` command lists active subagents spawned by the current Pi session and shows their status. On Windows, subagents run as hidden background processes with no attach screen; use `subagent status`, `subagent wait`, and the run's `session.jsonl` file for inspection. On platforms with tmux, selecting a subagent attaches to its tmux session instead.