pi-subagent-windows 0.0.0-stage → 0.1.0

package/subagent.ts

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	assistantText,
+	effectiveRunState,
+	getRunsDir,
+	inboxDir,
+	isRunAlive,
+	killRun,
+	launchRun,
+	listRuns,
+	readLatestAssistant,
+	readMetadata,
+	removeRunDir,
+	runDisplayName,
+	isValidRunName,
+	type InboxMessage,
+	type RunMetadata,
+	updateMetadata,
+	waitForRunShutdown,
+	writeInboxMessage,
+	writeMetadata,
+} from "./shared.ts";
+
+const VALID_THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const extensionPath = join(dirname(fileURLToPath(import.meta.url)), "index.ts");
+
+function fail(message: string): never {
+	throw new Error(message);
+}
+
+function usage(): never {
+	fail(`Usage:
+  subagent spawn [--name <name>] [--provider <provider>] [--model <model>] [--thinking <level>]
+    [--cwd <dir>] [--tools <names>] [--no-extensions] [--no-skills]
+    [--no-prompt-templates] [--no-context-files] (--prompt <text> | --file <path>)...
+  subagent status <handle>
+  subagent rename <handle> <name>
+  subagent send <handle> [--follow-up] <message>
+  subagent wait <handle> [--timeout <seconds>]
+  subagent stop <handle>
+  subagent list`);
+}
+
+function valueAfter(args: string[], index: number, option: string): string {
+	const value = args[index + 1];
+	if (!value || value.startsWith("--")) fail(`${option} requires a value`);
+	return value;
+}
+
+function normalizeRunName(value: string): string {
+	const name = value.trim();
+	if (!isValidRunName(name)) fail("Subagent name must be a single line of 1 to 64 characters");
+	return name;
+}
+
+/**
+ * Windows children run in RPC mode, which does not accept @file arguments.
+ * Inline small text files and point at large or binary ones instead.
+ */
+function buildInitialMessage(prompts: string[], files: string[]): string {
+	const parts: string[] = [];
+	for (const file of files) {
+		try {
+			const buffer = readFileSync(file);
+			if (buffer.includes(0) || buffer.byteLength > 1_000_000) {
+				parts.push(`A file is available at ${file}. Inspect it with the read tool before proceeding.`);
+			} else {
+				parts.push(`<file name="${file}">\n${buffer.toString("utf8")}\n</file>`);
+			}
+		} catch {
+			parts.push(`A file was requested at ${file}, but it could not be read.`);
+		}
+	}
+	if (prompts.length > 0) parts.push(`Task:\n${prompts.join("\n\n")}`);
+	return parts.join("\n\n");
+}
+
+function runDirForHandle(handle: string): string {
+	if (!/^[a-z0-9]+$/.test(handle)) fail(`Invalid subagent handle: ${handle}`);
+	return join(getRunsDir(), handle);
+}
+
+function getRun(handle: string): RunMetadata {
+	const metadata = readMetadata(runDirForHandle(handle));
+	if (!metadata) fail(`Unknown subagent: ${handle}`);
+	return metadata;
+}
+
+function generateHandle(): string {
+	mkdirSync(getRunsDir(), { recursive: true, mode: 0o700 });
+	for (let attempt = 0; attempt < 100; attempt++) {
+		const handle = randomBytes(3).toString("hex");
+		if (!existsSync(runDirForHandle(handle))) return handle;
+	}
+	fail("Could not allocate a unique subagent handle");
+}
+
+function spawnSubagent(args: string[]): void {
+	if (process.env.PI_SUBAGENT_RUN_DIR) fail("Nested subagents are disabled");
+	let name: string | undefined;
+	let provider = process.env.PI_PROVIDER;
+	let model = process.env.PI_MODEL;
+	let thinking = process.env.PI_REASONING_LEVEL || "medium";
+	let cwd = process.cwd();
+	let tools: string | undefined;
+	let noExtensions = false;
+	let noSkills = false;
+	let noPromptTemplates = false;
+	let noContextFiles = false;
+	const prompts: string[] = [];
+	const files: string[] = [];
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		switch (arg) {
+			case "--name":
+				name = normalizeRunName(valueAfter(args, i, arg));
+				i++;
+				break;
+			case "--provider":
+				provider = valueAfter(args, i, arg);
+				i++;
+				break;
+			case "--model":
+				model = valueAfter(args, i, arg);
+				i++;
+				break;
+			case "--thinking":
+				thinking = valueAfter(args, i, arg);
+				i++;
+				break;
+			case "--cwd":
+				cwd = resolve(valueAfter(args, i, arg));
+				i++;
+				break;
+			case "--tools":
+				tools = valueAfter(args, i, arg);
+				i++;
+				break;
+			case "--no-extensions":
+				noExtensions = true;
+				break;
+			case "--no-skills":
+				noSkills = true;
+				break;
+			case "--no-prompt-templates":
+				noPromptTemplates = true;
+				break;
+			case "--no-context-files":
+				noContextFiles = true;
+				break;
+			case "--prompt":
+				prompts.push(valueAfter(args, i, arg));
+				i++;
+				break;
+			case "--file": {
+				const file = resolve(valueAfter(args, i, arg));
+				if (!existsSync(file)) fail(`File not found: ${file}`);
+				files.push(file);
+				i++;
+				break;
+			}
+			default:
+				fail(`Unknown spawn argument: ${arg}`);
+		}
+	}
+
+	if (!provider) fail("No provider specified and PI_PROVIDER is not set");
+	if (!model) fail("No model specified and PI_MODEL is not set");
+	if (!VALID_THINKING_LEVELS.has(thinking)) fail(`Invalid thinking level: ${thinking}`);
+	if (tools !== undefined && !tools.split(",").some((name) => name.trim()))
+		fail("--tools requires at least one tool name");
+	if (prompts.length === 0 && files.length === 0) fail("spawn requires at least one --prompt or --file");
+	if (!existsSync(cwd)) fail(`Working directory not found: ${cwd}`);
+
+	const handle = generateHandle();
+	const runDir = runDirForHandle(handle);
+	const sessionFile = join(runDir, "session.jsonl");
+	const tmuxSession = `pi-subagent-${handle}`;
+	mkdirSync(inboxDir(runDir), { recursive: true, mode: 0o700 });
+	writeFileSync(sessionFile, "", { mode: 0o600 });
+
+	const launchArgs: string[] = [];
+	if (tools) launchArgs.push("--tools", tools);
+	if (noExtensions) launchArgs.push("--no-extensions", "--extension", extensionPath);
+	if (noSkills) launchArgs.push("--no-skills");
+	if (noPromptTemplates) launchArgs.push("--no-prompt-templates");
+	if (noContextFiles) launchArgs.push("--no-context-files");
+
+	const now = new Date().toISOString();
+	const metadata: RunMetadata = {
+		version: 1,
+		handle,
+		name,
+		parentSessionId: process.env.PI_SESSION_ID || undefined,
+		parentSessionFile: process.env.PI_SESSION_FILE || undefined,
+		tmuxSession,
+		runDir,
+		sessionFile,
+		cwd,
+		provider,
+		model,
+		thinking,
+		launchArgs,
+		state: "starting",
+		hasStarted: false,
+		createdAt: now,
+		updatedAt: now,
+	};
+	writeMetadata(metadata);
+
+	try {
+		if (process.platform === "win32") {
+			writeInboxMessage(runDir, { message: buildInitialMessage(prompts, files), delivery: "auto" });
+			launchRun(metadata);
+		} else {
+			const initialArgs = files.map((file) => `@${file}`);
+			if (prompts.length > 0) initialArgs.push(`Task:\n${prompts.join("\n\n")}`);
+			launchRun(metadata, initialArgs);
+		}
+	} catch (error) {
+		removeRunDir(runDir);
+		throw error;
+	}
+
+	const attachLine =
+		process.platform === "win32"
+			? `Session: ${sessionFile}\n`
+			: `Attach: tmux attach -t ${tmuxSession}\n`;
+	process.stdout.write(`Spawned ${runDisplayName(metadata)}\nState: busy\n${attachLine}`);
+}
+
+function statusSubagent(args: string[]): void {
+	if (args.length !== 1) usage();
+	const metadata = getRun(args[0]);
+	const attachLine =
+		process.platform === "win32"
+			? `Session: ${metadata.sessionFile}\n`
+			: `Attach: tmux attach -t ${metadata.tmuxSession}\n`;
+	process.stdout.write(
+		`${runDisplayName(metadata)}: ${effectiveRunState(metadata)} (${metadata.provider}/${metadata.model}, ${metadata.thinking})\n${attachLine}`,
+	);
+}
+
+function renameSubagent(args: string[]): void {
+	if (args.length !== 2) usage();
+	const metadata = getRun(args[0]);
+	const name = normalizeRunName(args[1]);
+	const updated = updateMetadata(metadata.runDir, { name });
+	if (!updated) fail(`Could not rename subagent: ${metadata.handle}`);
+	process.stdout.write(`Renamed ${runDisplayName(updated)}\n`);
+}
+
+function sendSubagent(args: string[]): void {
+	const handle = args.shift();
+	if (!handle) usage();
+	let followUp = false;
+	const messageParts: string[] = [];
+	for (const arg of args) {
+		if (arg === "--follow-up") followUp = true;
+		else if (arg.startsWith("--")) fail(`Unknown send argument: ${arg}`);
+		else messageParts.push(arg);
+	}
+	const message = messageParts.join(" ").trim();
+	if (!message) fail("send requires a message");
+	const metadata = getRun(handle);
+	if (!isRunAlive(metadata)) fail(`${handle} is not running`);
+
+	const payload: InboxMessage = { message, delivery: followUp ? "followUp" : "auto" };
+	writeInboxMessage(metadata.runDir, payload);
+
+	const state = effectiveRunState(metadata);
+	const verb =
+		followUp && state === "busy"
+			? "Queued follow-up for"
+			: state === "idle" || state === "starting"
+				? "Prompted"
+				: "Steered";
+	process.stdout.write(`${verb} ${runDisplayName(metadata)}\n`);
+}
+
+function parseTimeout(args: string[]): number {
+	if (args.length === 0) return 1800;
+	if (args.length !== 2 || args[0] !== "--timeout") usage();
+	const timeout = Number(args[1]);
+	if (!Number.isInteger(timeout) || timeout <= 0) fail("--timeout must be a positive integer");
+	return timeout;
+}
+
+async function waitSubagent(args: string[]): Promise<void> {
+	const handle = args.shift();
+	if (!handle) usage();
+	const timeoutSeconds = parseTimeout(args);
+	const deadline = Date.now() + timeoutSeconds * 1000;
+
+	while (Date.now() < deadline) {
+		const metadata = getRun(handle);
+		const pending = existsSync(inboxDir(metadata.runDir))
+			? readdirSync(inboxDir(metadata.runDir)).some((file) => file.endsWith(".json"))
+			: false;
+		const state = effectiveRunState(metadata);
+		if (state === "error") fail(metadata.error || `${handle} failed`);
+		if (state === "exited") fail(`${handle} exited before finishing`);
+		if (metadata.hasStarted && state === "idle" && !pending) {
+			const message = readLatestAssistant(metadata.sessionFile);
+			if (!message) fail(`${handle} finished without an assistant response`);
+			process.stdout.write(`${handle} finished\n\n${assistantText(message)}\n`);
+			if (message.stopReason === "error" || message.stopReason === "aborted") process.exitCode = 1;
+			return;
+		}
+		await new Promise((resolveDelay) => setTimeout(resolveDelay, 500));
+	}
+	fail(`Timed out after ${timeoutSeconds}s waiting for ${handle}`);
+}
+
+async function stopSubagent(args: string[]): Promise<void> {
+	if (args.length !== 1) usage();
+	const metadata = getRun(args[0]);
+	const wasRunning = isRunAlive(metadata);
+	killRun(metadata);
+	if (wasRunning) await waitForRunShutdown(metadata.runDir);
+	removeRunDir(metadata.runDir);
+	process.stdout.write(`Stopped ${runDisplayName(metadata)}\n`);
+}
+
+function listSubagents(args: string[]): void {
+	if (args.length !== 0) usage();
+	const runs = listRuns(process.env.PI_SESSION_ID || undefined);
+	if (runs.length === 0) {
+		process.stdout.write("No subagents\n");
+		return;
+	}
+	for (const metadata of runs) {
+		process.stdout.write(
+			`${runDisplayName(metadata)}  ${effectiveRunState(metadata).padEnd(8)}  ${metadata.provider}/${metadata.model}  ${metadata.thinking}\n`,
+		);
+	}
+}
+
+async function main(): Promise<void> {
+	const args = process.argv.slice(2);
+	const command = args.shift();
+	switch (command) {
+		case "spawn":
+			spawnSubagent(args);
+			break;
+		case "status":
+			statusSubagent(args);
+			break;
+		case "rename":
+			renameSubagent(args);
+			break;
+		case "send":
+			sendSubagent(args);
+			break;
+		case "wait":
+			await waitSubagent(args);
+			break;
+		case "stop":
+			await stopSubagent(args);
+			break;
+		case "list":
+			listSubagents(args);
+			break;
+		default:
+			usage();
+	}
+}
+
+main().catch((error: unknown) => {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+});

package/supervisor.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * Hidden process host for a Windows subagent.
+ *
+ * It is spawned detached by `launchRun`, writes its own pid for liveness checks,
+ * then owns a `pi --mode rpc` child. Because the supervisor is independent of the
+ * parent Pi process, subagents survive parent `/reload`, session switches, and
+ * parent crashes. Closing the child's stdin is Pi's documented orderly shutdown.
+ */
+import { appendFileSync, createWriteStream, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import {
+	getAgentDir,
+	readMetadata,
+	resolvePiCliPath,
+	supervisorPidPath,
+	updateMetadata,
+} from "./shared.ts";
+
+const runDir = process.argv[2];
+if (!runDir) {
+	process.stderr.write("pi-subagent-windows supervisor: missing run directory\n");
+	process.exit(1);
+}
+
+const metadata = readMetadata(runDir);
+if (!metadata) {
+	process.stderr.write(`pi-subagent-windows supervisor: no valid metadata in ${runDir}\n`);
+	process.exit(1);
+}
+
+const logPath = join(runDir, "supervisor.log");
+const log = (message: string): void => {
+	try {
+		appendFileSync(logPath, `[${new Date().toISOString()}] ${message}\n`, { encoding: "utf8" });
+	} catch {
+		// Logging is best effort; never fail the run over it.
+	}
+};
+
+writeFileSync(supervisorPidPath(runDir), `${process.pid}\n`, { encoding: "utf8", mode: 0o600 });
+
+const installRoot = join(getAgentDir(), "install");
+let cliPath: string;
+try {
+	cliPath = resolvePiCliPath();
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	log(`could not resolve the Pi CLI: ${message}`);
+	updateMetadata(runDir, { state: "error", error: message });
+	process.exit(1);
+}
+
+const args = [
+	cliPath,
+	"--mode", "rpc",
+	"--session", metadata.sessionFile,
+	"--provider", metadata.provider,
+	"--model", metadata.model,
+	"--thinking", metadata.thinking,
+	...(metadata.launchArgs ?? []),
+];
+log(`supervisor pid=${process.pid} starting child: ${JSON.stringify(args)}`);
+
+const child = spawn(process.execPath, args, {
+	cwd: metadata.cwd,
+	windowsHide: true,
+	stdio: ["pipe", "pipe", "pipe"],
+	env: {
+		...process.env,
+		PI_SUBAGENT_RUN_DIR: runDir,
+		PI_MANAGED_INSTALL_ROOT: installRoot,
+	},
+});
+
+if (!child.pid || !child.stdin || !child.stdout) {
+	log("failed to spawn the Pi RPC child");
+	updateMetadata(runDir, { state: "error", error: "Failed to spawn the Pi RPC child" });
+	process.exit(1);
+}
+
+log(`child pid=${child.pid}`);
+child.stderr.pipe(createWriteStream(logPath, { flags: "a" }));
+
+/** Answer dialogs that would otherwise block a hidden child forever. */
+function respond(id: string, payload: Record<string, unknown>): void {
+	try {
+		child.stdin!.write(`${JSON.stringify({ type: "extension_ui_response", id, ...payload })}\n`);
+	} catch {
+		// The child may have exited between the request and the response.
+	}
+}
+
+let stdoutBuffer = "";
+child.stdout.on("data", (data: Buffer) => {
+	stdoutBuffer += data.toString("utf8");
+	let index: number;
+	while ((index = stdoutBuffer.indexOf("\n")) !== -1) {
+		const line = stdoutBuffer.slice(0, index).replace(/\r$/, "");
+		stdoutBuffer = stdoutBuffer.slice(index + 1);
+		if (!line.trim()) continue;
+		let record: { type?: string; id?: string; method?: string };
+		try {
+			record = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (record.type !== "extension_ui_request" || typeof record.id !== "string") continue;
+		switch (record.method) {
+			case "confirm":
+				log("auto-declined an extension confirm dialog (no interactive UI in hidden subagents)");
+				respond(record.id, { confirmed: false });
+				break;
+			case "select":
+			case "input":
+			case "editor":
+				log(`auto-cancelled an extension ${record.method} dialog (no interactive UI in hidden subagents)`);
+				respond(record.id, { cancelled: true });
+				break;
+			default:
+				// notify / setStatus / setWidget / setTitle / set_editor_text need no response.
+				break;
+		}
+	}
+});
+
+child.on("error", (error) => {
+	log(`child process error: ${error.message}`);
+	updateMetadata(runDir, { state: "error", error: error.message });
+	process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+	log(`child exited code=${code} signal=${signal}`);
+	const current = readMetadata(runDir);
+	if (current && current.state !== "exited" && current.state !== "error") {
+		updateMetadata(
+			runDir,
+			code === 0
+				? { state: "exited" }
+				: { state: "error", error: `Subagent process exited unexpectedly (code=${code}, signal=${signal})` },
+		);
+	}
+	process.exit(0);
+});
+
+// A graceful shutdown request (process.kill) closes the child's stdin first.
+process.on("SIGTERM", () => {
+	try {
+		child.stdin!.end();
+	} catch {
+		// Already closed.
+	}
+});