pi-subagent-windows 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner (upstream pi-subagent)
+Copyright (c) 2026 Muntasim Ul Haque (Windows port)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# Pi Subagent for Windows (no tmux)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hidden, persistent Pi subagents for independent reviews, investigations, and delegated implementation — **without tmux**.
+
+This is a Windows port of [badlogic/pi-subagent](https://github.com/badlogic/pi-subagent). The agent-facing workflow is unchanged: the main Pi agent spawns named subagents with the `subagent` CLI, waits for their final reports, steers them when needed, and stops them when done. Everything happens in the background — there is no attach screen.
+
+## How it works
+
+Upstream runs each subagent inside a tmux session and lets a human attach to its live TUI. Windows has no tmux, so this port replaces the tmux layer with a hidden process host:
+
+- Each subagent is a detached, hidden **supervisor** process that owns a `pi --mode rpc` child.
+- The supervisor holds the child's stdin pipe, drains its protocol output, writes `supervisor.log`, and auto-cancels extension dialogs (there is no interactive screen to answer them).
+- Runs are tracked by pid, stopped with `taskkill /T /F`, and survive parent `/reload`, session switches, and parent crashes.
+- Subagents are **status-only** on Windows. Use `subagent status`, `subagent wait`, and the run's `session.jsonl` for inspection.
+
+On non-Windows platforms the upstream tmux behavior is kept, so the fork stays mergeable with upstream.
+
+## Requirements
+
+- Pi
+- Node.js 22.19 or newer
+- Windows (no tmux required)
+
+## Install
+
+```sh
+pi install git:github.com/muntasimulhaque/pi-subagent-windows
+```
+
+Or clone it manually into Pi's global extension directory:
+
+```sh
+git clone https://github.com/muntasimulhaque/pi-subagent-windows.git ~/.pi/agent/extensions/pi-subagent-windows
+```
+
+Run `/reload` in an existing Pi session (or start a new one). On Windows the extension writes `subagent.cmd` and an extensionless `subagent` sh shim into `~/.pi/agent/bin`, so the CLI is on `PATH` from both PowerShell/cmd and Git Bash.
+
+## Usage
+
+Spawn with a descriptive name using the parent session's provider, model, and thinking level:
+
+```sh
+subagent spawn --name review --prompt "Review the current diff independently"
+```
+
+Override the model configuration when needed:
+
+```sh
+subagent spawn \
+  --provider commandcode \
+  --model deepseek/deepseek-v4.1-flash \
+  --thinking low \
+  --prompt "Find the relevant implementation"
+```
+
+Provide multiple prompt fragments and files:
+
+```sh
+subagent spawn \
+  --file /tmp/spec.md \
+  --prompt "Implement this specification" \
+  --prompt "Run the targeted tests"
+```
+
+Restrict tools for a read-only investigation:
+
+```sh
+subagent spawn --tools read,grep,find,ls --prompt "Investigate the failure"
+```
+
+Manage a run by its generated handle:
+
+```sh
+subagent status a1b2c3
+subagent rename a1b2c3 "error handling review"
+subagent send a1b2c3 "Focus on error handling"
+subagent send a1b2c3 --follow-up "Then summarize"
+subagent wait a1b2c3
+subagent stop a1b2c3
+subagent list
+```
+
+Run `/subagent` to list active subagents spawned by the current session. On Windows, selecting one shows its status and session file.
+
+## Run files
+
+Each run lives in `~/.pi/agent/subagents/<handle>/`:
+
+| File | Purpose |
+|---|---|
+| `metadata.json` | State, model, session pointers |
+| `session.jsonl` | The child Pi session (full transcript) |
+| `inbox/` | Queued messages (steering, follow-ups) |
+| `supervisor.log` | Process host log, child stderr, auto-cancelled dialogs |
+| `supervisor.pid` | Process tracking |
+
+## Differences and limitations
+
+- **No attach screen.** Subagents are observable through status, `wait`, and the session file, not a live TUI.
+- **`--file` handling:** text file contents (up to 1 MB) are inlined into the first prompt; larger or binary files are referenced by path and can be read by the subagent's `read` tool.
+- **Extension dialogs** (`select`, `confirm`, `input`, `editor`) are auto-cancelled inside hidden subagents, with a note in `supervisor.log`. Fire-and-forget notifications are ignored.
+- **Suspension kills the current turn.** Resuming relaunches the run idle with its full history.
+- Nested subagents remain disabled.
+
+## Credits
+
+Forked from [badlogic/pi-subagent](https://github.com/badlogic/pi-subagent) by Mario Zechner (MIT). See `LICENSE`.

package/bin/subagent.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * npm/npx bin entry. Node cannot link a `.ts` file as a global command, so this
+ * thin wrapper forwards to the real CLI, which runs under Node's type stripping.
+ */
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const entry = join(dirname(fileURLToPath(import.meta.url)), "..", "subagent.ts");
+const result = spawnSync(process.execPath, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+if (result.error) {
+	process.stderr.write(`${result.error.message}\n`);
+	process.exit(1);
+}
+process.exit(result.status ?? 1);

package/index.ts

@@ -0,0 +1,344 @@
+import { spawn } from "node:child_process";
+import { existsSync, chmodSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DynamicBorder, type ExtensionAPI, type ExtensionContext, keyHint } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Text, type TUI } from "@earendil-works/pi-tui";
+import {
+	effectiveRunState,
+	getAgentDir,
+	inboxDir,
+	isRunAlive,
+	killRun,
+	launchRun,
+	listRuns,
+	readMetadata,
+	removeRunDir,
+	runDisplayName,
+	type InboxMessage,
+	type RunMetadata,
+	updateMetadata,
+	waitForRunShutdown,
+} from "./shared.ts";
+
+const packageDir = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * On Windows, keep `subagent.cmd` (cmd/PowerShell) and an extensionless `subagent`
+ * sh script (Git Bash, which does not resolve bare names through PATHEXT) in the
+ * agent bin directory so the CLI is on PATH after install. Never clobbers a file
+ * this extension did not write.
+ */
+function ensureCliShim(): void {
+	if (process.platform !== "win32") return;
+	try {
+		const binDir = join(getAgentDir(), "bin");
+		const cliPath = join(packageDir, "subagent.ts");
+		const cliPathUnix = cliPath.replace(/\\/g, "/");
+
+		const cmdMarker = "rem pi-subagent-windows shim";
+		const cmdContent = `@ECHO off\r\n${cmdMarker}\r\nnode "${cliPath}" %*\r\n`;
+
+		const shMarker = "# pi-subagent-windows shim";
+		const shContent = `#!/bin/sh\n${shMarker}\nexec node "${cliPathUnix}" "$@"\n`;
+
+		mkdirSync(binDir, { recursive: true });
+		const writeShim = (path: string, marker: string, content: string, mode?: number): void => {
+			let shouldWrite = true;
+			if (existsSync(path)) {
+				const current = readFileSync(path, "utf8");
+				if (!current.includes(marker)) return; // foreign file: leave it alone
+				if (current === content) shouldWrite = false;
+			}
+			if (shouldWrite) writeFileSync(path, content, { encoding: "utf8" });
+			if (mode !== undefined) chmodSync(path, mode);
+		};
+		writeShim(join(binDir, "subagent.cmd"), cmdMarker, cmdContent);
+		writeShim(join(binDir, "subagent"), shMarker, shContent, 0o755);
+	} catch {
+		// The shim is a convenience; extension loading must never fail over it.
+	}
+}
+
+function isInboxMessage(value: unknown): value is InboxMessage {
+	if (typeof value !== "object" || value === null) return false;
+	const message = value as Record<string, unknown>;
+	return typeof message.message === "string" && (message.delivery === "auto" || message.delivery === "followUp");
+}
+
+function displayState(metadata: RunMetadata): string {
+	return effectiveRunState(metadata).padEnd(8);
+}
+
+export default function subagentExtension(pi: ExtensionAPI) {
+	const runDir = process.env.PI_SUBAGENT_RUN_DIR;
+	if (!runDir) {
+		pi.on("resources_discover", () => ({ skillPaths: [join(packageDir, "skills")] }));
+		ensureCliShim();
+	}
+
+	pi.registerCommand("subagent", {
+		description: "Select a subagent spawned by this session",
+		handler: async (_args, ctx) => {
+			const runs = listRuns(ctx.sessionManager.getSessionId()).filter((run) => effectiveRunState(run) !== "exited");
+			if (runs.length === 0) {
+				ctx.ui.notify("No active subagents spawned by this session", "info");
+				return;
+			}
+
+			const items: SelectItem[] = runs.map((run) => ({
+				value: run.handle,
+				label: `${runDisplayName(run)}  ${displayState(run)}  ${run.provider}/${run.model}  ${run.thinking}`,
+			}));
+			let tui: TUI | undefined;
+			const selected = await ctx.ui.custom<string | undefined>((customTui, theme, _keybindings, done) => {
+				tui = customTui;
+				const list = new SelectList(items, Math.min(items.length, 10), {
+					selectedPrefix: (text) => theme.fg("accent", text),
+					selectedText: (text) => theme.fg("accent", text),
+					description: (text) => theme.fg("muted", text),
+					scrollInfo: (text) => theme.fg("dim", text),
+					noMatch: (text) => theme.fg("warning", text),
+				});
+				list.onSelect = (item) => done(item.value);
+				list.onCancel = () => done(undefined);
+
+				const container = new Container();
+				container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+				container.addChild(
+					new Text(theme.fg("accent", theme.bold(process.platform === "win32" ? "Subagent status" : "Attach to subagent")), 1, 0),
+				);
+				container.addChild(list);
+				container.addChild(
+					new Text(
+						theme.fg(
+							"dim",
+							`${keyHint("tui.select.confirm", process.platform === "win32" ? "status" : "attach")}  ${keyHint("tui.select.cancel", "cancel")}`,
+						),
+						1,
+						0,
+					),
+				);
+				container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+
+				return {
+					render: (width) => container.render(width),
+					invalidate: () => container.invalidate(),
+					handleInput: (data) => {
+						list.handleInput(data);
+						customTui.requestRender();
+					},
+				};
+			});
+			if (!selected || !tui) return;
+			const run = runs.find((candidate) => candidate.handle === selected);
+			if (!run) return;
+
+			if (process.platform === "win32") {
+				ctx.ui.notify(
+					`${runDisplayName(run)}: ${effectiveRunState(run)} — session: ${run.sessionFile}`,
+					"info",
+				);
+				return;
+			}
+
+			if (process.env.TMUX) {
+				const exitCode = await new Promise<number | null>((resolveExit) => {
+					const child = spawn("tmux", ["switch-client", "-t", run.tmuxSession], { stdio: "inherit" });
+					child.on("error", () => resolveExit(null));
+					child.on("close", resolveExit);
+				});
+				if (exitCode !== 0) ctx.ui.notify(`Could not switch to ${run.handle}`, "error");
+				return;
+			}
+
+			tui.stop();
+			try {
+				const exitCode = await new Promise<number | null>((resolveExit) => {
+					const child = spawn("tmux", ["attach-session", "-t", run.tmuxSession], { stdio: "inherit" });
+					child.on("error", () => resolveExit(null));
+					child.on("close", resolveExit);
+				});
+				if (exitCode !== 0) process.stderr.write(`Could not attach to ${run.handle}\n`);
+			} finally {
+				tui.start();
+				tui.requestRender(true);
+			}
+		},
+	});
+
+	if (!runDir) {
+		let widgetTimer: ReturnType<typeof setInterval> | undefined;
+		let widgetContext: ExtensionContext | undefined;
+
+		const refreshWidget = (): void => {
+			if (!widgetContext) return;
+			const activeRuns = listRuns(widgetContext.sessionManager.getSessionId())
+				.map((run) => ({ run, state: effectiveRunState(run) }))
+				.filter(({ state }) => state !== "exited");
+			if (activeRuns.length === 0) {
+				widgetContext.ui.setWidget("subagents", undefined);
+				return;
+			}
+
+			const visible = activeRuns.slice(0, 5).map(({ run, state }) => {
+				const color =
+					state === "busy" ? "warning" : state === "idle" ? "success" : state === "error" ? "error" : "muted";
+				return widgetContext!.ui.theme.fg(color, `${run.name ?? run.handle}:${state}`);
+			});
+			if (activeRuns.length > visible.length) {
+				visible.push(widgetContext.ui.theme.fg("muted", `+${activeRuns.length - visible.length}`));
+			}
+			widgetContext.ui.setWidget(
+				"subagents",
+				[widgetContext.ui.theme.fg("dim", "subagents: ") + visible.join(widgetContext.ui.theme.fg("dim", " | "))],
+				{ placement: "belowEditor" },
+			);
+		};
+
+		pi.on("session_start", (_event, ctx) => {
+			// Relaunch children that were suspended when this session was last quit or switched away from.
+			for (const run of listRuns(ctx.sessionManager.getSessionId())) {
+				if (!run.suspended || isRunAlive(run)) continue;
+				if (!existsSync(run.sessionFile)) {
+					removeRunDir(run.runDir);
+					continue;
+				}
+				const starting = updateMetadata(run.runDir, { state: "starting", error: undefined }) ?? run;
+				try {
+					launchRun(starting);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					updateMetadata(run.runDir, { state: "error", error: message });
+					if (ctx.hasUI) ctx.ui.notify(`Could not resume subagent ${runDisplayName(run)}: ${message}`, "error");
+				}
+			}
+
+			if (!ctx.hasUI) return;
+			widgetContext = ctx;
+			refreshWidget();
+			widgetTimer = setInterval(refreshWidget, 1000);
+			widgetTimer.unref();
+		});
+
+		pi.on("session_shutdown", async (event, ctx) => {
+			if (widgetTimer) clearInterval(widgetTimer);
+			widgetTimer = undefined;
+			widgetContext = undefined;
+			ctx.ui.setWidget("subagents", undefined);
+			if (event.reason === "reload") return;
+			// Suspend running children: stop the process but keep transcript and metadata so resuming this
+			// session relaunches them. Children that already exited on their own are discarded.
+			for (const run of listRuns(ctx.sessionManager.getSessionId())) {
+				if (!isRunAlive(run)) {
+					if (!run.suspended) removeRunDir(run.runDir);
+					continue;
+				}
+				updateMetadata(run.runDir, { suspended: true });
+				killRun(run);
+				await waitForRunShutdown(run.runDir);
+			}
+		});
+		return;
+	}
+
+	let currentContext: ExtensionContext | undefined;
+	let timer: ReturnType<typeof setInterval> | undefined;
+	let processing = false;
+	let sessionName: string | undefined;
+
+	const syncSessionName = (): void => {
+		const metadata = readMetadata(runDir);
+		if (!metadata) return;
+		const next = `subagent ${metadata.name ?? metadata.handle}`;
+		if (next === sessionName) return;
+		pi.setSessionName(next);
+		sessionName = next;
+	};
+
+	const processInbox = async (): Promise<void> => {
+		if (processing || !currentContext) return;
+		syncSessionName();
+		const queueDir = inboxDir(runDir);
+		if (!existsSync(queueDir)) return;
+		processing = true;
+		try {
+			for (const name of readdirSync(queueDir)
+				.filter((entry) => entry.endsWith(".json"))
+				.sort()) {
+				const path = join(queueDir, name);
+				let payload: InboxMessage;
+				try {
+					const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+					if (!isInboxMessage(value)) throw new Error("Invalid inbox message");
+					payload = value;
+				} catch (error) {
+					unlinkSync(path);
+					updateMetadata(runDir, {
+						state: "error",
+						error: error instanceof Error ? error.message : String(error),
+					});
+					continue;
+				}
+
+				updateMetadata(runDir, { state: "busy", error: undefined });
+				try {
+					if (currentContext.isIdle()) {
+						pi.sendUserMessage(payload.message);
+					} else {
+						pi.sendUserMessage(payload.message, {
+							deliverAs: payload.delivery === "followUp" ? "followUp" : "steer",
+						});
+					}
+					unlinkSync(path);
+				} catch (error) {
+					updateMetadata(runDir, {
+						state: currentContext.isIdle() ? "idle" : "busy",
+						error: error instanceof Error ? error.message : String(error),
+					});
+					return;
+				}
+			}
+		} finally {
+			processing = false;
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		currentContext = ctx;
+		const metadata = readMetadata(runDir);
+		if (!metadata) return;
+		updateMetadata(runDir, {
+			childSessionId: ctx.sessionManager.getSessionId(),
+			sessionFile: ctx.sessionManager.getSessionFile() ?? metadata.sessionFile,
+			state: ctx.isIdle() ? "idle" : "busy",
+			suspended: undefined,
+			error: undefined,
+		});
+		syncSessionName();
+		if (!timer) {
+			timer = setInterval(() => void processInbox(), 250);
+			timer.unref();
+		}
+		void processInbox();
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		currentContext = ctx;
+		updateMetadata(runDir, { state: "busy", hasStarted: true, error: undefined });
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		currentContext = ctx;
+		if (ctx.isIdle()) updateMetadata(runDir, { state: "idle" });
+	});
+
+	pi.on("session_shutdown", (event) => {
+		currentContext = undefined;
+		if (timer) {
+			clearInterval(timer);
+			timer = undefined;
+		}
+		if (event.reason === "quit") updateMetadata(runDir, { state: "exited" });
+	});
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "pi-subagent-windows",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Windows port of pi-subagent: hidden, persistent Pi subagents without tmux",
+  "keywords": ["pi-package", "pi-extension", "subagent", "windows"],
+  "type": "module",
+  "license": "MIT",
+  "author": "Muntasim Ul Haque",
+  "homepage": "https://github.com/muntasimulhaque/pi-subagent-windows#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muntasimulhaque/pi-subagent-windows.git"
+  },
+  "bugs": {
+    "url": "https://github.com/muntasimulhaque/pi-subagent-windows/issues"
+  },
+  "files": [
+    "bin",
+    "index.ts",
+    "shared.ts",
+    "subagent.ts",
+    "supervisor.ts",
+    "skills"
+  ],
+  "bin": {
+    "subagent": "./bin/subagent.js"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}