@oldflag2333333/pi-subagent 0.0.0-stage → 0.1.1

package/herdr-plugin/herdr-plugin.toml

@@ -0,0 +1,27 @@
+id = "subagent.agent-visibility"
+name = "Pi Subagent Agent Visibility"
+version = "0.1.0"
+min_herdr_version = "0.8.2"
+description = "Hide or show Pi Subagent subs in Herdr's Agents panel"
+platforms = ["linux", "macos"]
+
+[[startup]]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "startup", "--list-models"]
+
+[[actions]]
+id = "toggle-subs"
+title = "Toggle Pi Subagent subs"
+contexts = ["global"]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "toggle", "--list-models"]
+
+[[actions]]
+id = "hide-subs"
+title = "Hide Pi Subagent subs"
+contexts = ["global"]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "hide", "--list-models"]
+
+[[actions]]
+id = "show-subs"
+title = "Show Pi Subagent subs"
+contexts = ["global"]
+command = ["pi", "--offline", "--no-extensions", "-e", "action.ts", "--subagent-visibility-action", "show", "--list-models"]

package/herdr-plugin/index.mjs

@@ -0,0 +1,108 @@
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pluginId = process.env.HERDR_PLUGIN_ID ?? "subagent.agent-visibility";
+const source = `plugin:${pluginId}`;
+const socketPath = process.env.HERDR_SOCKET_PATH;
+const stateDir = process.env.HERDR_PLUGIN_STATE_DIR;
+
+function statePath() {
+	if (!stateDir) throw new Error("HERDR_PLUGIN_STATE_DIR is missing.");
+	return path.join(stateDir, "visibility.json");
+}
+
+function readState() {
+	try {
+		const value = JSON.parse(fs.readFileSync(statePath(), "utf8"));
+		return { showSubs: value?.showSubs === true };
+	} catch (error) {
+		if (error?.code === "ENOENT") return { showSubs: false };
+		throw error;
+	}
+}
+
+function writeState(state) {
+	const file = statePath();
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const temporary = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+	fs.renameSync(temporary, file);
+}
+
+function send(method, params) {
+	if (!socketPath) return Promise.reject(new Error("HERDR_SOCKET_PATH is missing."));
+	const endpoint = process.platform === "win32" ? `\\\\.\\pipe\\${socketPath}` : socketPath;
+	const request = { id: `subagent:${Date.now()}:${process.pid}`, method, params };
+	return new Promise((resolve, reject) => {
+		let buffer = "";
+		const socket = net.createConnection(endpoint);
+		const timeout = setTimeout(() => {
+			socket.destroy();
+			reject(new Error("Timed out waiting for Herdr."));
+		}, 5000);
+		const finish = (callback) => {
+			clearTimeout(timeout);
+			socket.destroy();
+			callback();
+		};
+		socket.on("error", (error) => finish(() => reject(error)));
+		socket.on("connect", () => socket.write(`${JSON.stringify(request)}\n`));
+		socket.on("data", (chunk) => {
+			buffer += chunk.toString("utf8");
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			try {
+				const response = JSON.parse(buffer.slice(0, newline));
+				if (response.error) throw new Error(response.error.message ?? JSON.stringify(response.error));
+				finish(() => resolve(response.result));
+			} catch (error) {
+				finish(() => reject(error));
+			}
+		});
+	});
+}
+
+async function apply(showSubs) {
+	if (showSubs) {
+		await send("agent.view.clear", { source });
+		return;
+	}
+	await send("agent.view.set", {
+		source,
+		label: "subs hidden",
+		filter: {
+			op: "not",
+			filter: {
+				op: "eq",
+				field: { token: "subagent_role" },
+				value: "sub",
+			},
+		},
+		sort: [],
+	});
+}
+
+export async function run(action = "startup") {
+	const current = readState();
+	const next = action === "toggle"
+		? { showSubs: !current.showSubs }
+		: action === "show"
+			? { showSubs: true }
+			: action === "hide" || action === "startup"
+				? current
+				: undefined;
+	if (!next) throw new Error(`Unknown action '${action}'.`);
+	if (action === "hide") next.showSubs = false;
+	writeState(next);
+	await apply(next.showSubs);
+	console.log(next.showSubs ? "Pi Subagent subs are visible." : "Pi Subagent subs are hidden.");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	run(process.argv[2] ?? "startup").catch((error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	});
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@oldflag2333333/pi-subagent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Reusable specialist profiles and independent sub-agents for Pi",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "oldflag",
+    "email": "oldflag2333333@gmail.com",
+    "url": "https://github.com/oldflag2333333"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oldflag2333333/pi-subagent.git"
+  },
+  "homepage": "https://github.com/oldflag2333333/pi-subagent#readme",
+  "bugs": {
+    "url": "https://github.com/oldflag2333333/pi-subagent/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "profiles",
+    "subagent",
+    "herdr"
+  ],
+  "files": [
+    "src",
+    "herdr-plugin",
+    "README.md",
+    "README.zh-CN.md",
+    "docs",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "check": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": ">=1.0.4",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^1.0.4",
+    "@earendil-works/pi-ai": "^1.0.4",
+    "@earendil-works/pi-coding-agent": "^1.0.4",
+    "@earendil-works/pi-tui": "^1.0.4",
+    "@types/node": "^22.15.0",
+    "@types/semver": "^7.8.0",
+    "semver": "^7.8.5",
+    "tsx": "^4.20.0",
+    "typebox": "^1.0.72",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/adapters/herdr.ts

@@ -0,0 +1,157 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { subSessionName } from "../manual-context.js";
+import { subCapabilityArgs } from "../profiles/launch-args.js";
+import { subSessionDir } from "../sessions.js";
+import type { SubAgentStatus, SubLaunchSpec, SubSurfaceAdapter, SurfaceHandle } from "../types.js";
+
+function parseEnvelope(stdout: string): Record<string, unknown> {
+	const lines = stdout.trim().split(/\r?\n/).filter(Boolean).reverse();
+	for (const line of lines) {
+		try {
+			const parsed = JSON.parse(line) as Record<string, unknown>;
+			return parsed.result && typeof parsed.result === "object" ? parsed.result as Record<string, unknown> : parsed;
+		} catch {}
+	}
+	throw new Error(`Herdr returned no JSON response: ${stdout.slice(0, 300)}`);
+}
+
+function nestedString(value: unknown, ...keys: string[]): string | undefined {
+	let current: unknown = value;
+	for (const key of keys) {
+		if (!current || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[key];
+	}
+	return typeof current === "string" ? current : undefined;
+}
+
+function safeLabel(value: string): string {
+	return value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 48) || "delegated task";
+}
+
+function agentName(runId: string): string {
+	return `sub-${runId.toLowerCase().replace(/[^a-z0-9_-]/g, "").slice(0, 20)}`;
+}
+
+function subArgs(spec: SubLaunchSpec): string[] {
+	const herdrIntegration = path.join(getAgentDir(), "extensions", "herdr-agent-state.ts");
+	return [
+		"--no-extensions",
+		"-e", spec.entryPath,
+		...(fs.existsSync(herdrIntegration) ? ["-e", herdrIntegration] : []),
+		...(spec.profile.sessionPersistence === "persistent" || spec.resumeSessionId
+			? ["--session-dir", subSessionDir(spec.mainSessionId)] : ["--no-session"]),
+		...(spec.resumeSessionId ? ["--session", spec.resumeSessionFile ?? spec.resumeSessionId] : []),
+		spec.projectTrusted ? "--approve" : "--no-approve",
+		"--name", subSessionName(safeLabel(spec.title), spec.origin),
+		...subCapabilityArgs(spec.profile, spec.entryPath),
+	];
+}
+
+/** A launch failed and its tab could not be rolled back; keep it addressable. */
+export class HerdrLaunchCleanupError extends Error {
+	constructor(readonly handle: SurfaceHandle, cause: unknown, cleanup: unknown) {
+		super(`Sub launch failed: ${cause instanceof Error ? cause.message : String(cause)}. Tab cleanup also failed: ${cleanup instanceof Error ? cleanup.message : String(cleanup)}.`, { cause });
+	}
+}
+
+export class HerdrTabAdapter implements SubSurfaceAdapter {
+	readonly id = "herdr" as const;
+	constructor(private readonly pi: ExtensionAPI) {}
+
+	async available(): Promise<boolean> {
+		if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) return false;
+		const result = await this.pi.exec("herdr", ["status", "server"], { timeout: 3000 });
+		return result.code === 0;
+	}
+
+	async launch(spec: SubLaunchSpec, signal?: AbortSignal): Promise<SurfaceHandle> {
+		const workspaceId = process.env.HERDR_WORKSPACE_ID;
+		if (!workspaceId) throw new Error("HERDR_WORKSPACE_ID is unavailable; Pi is not running in a Herdr workspace.");
+		signal?.throwIfAborted();
+		const label = `↳ pi · ${safeLabel(spec.title)}`;
+		const created = await this.pi.exec("herdr", [
+			"tab", "create",
+			"--workspace", workspaceId,
+			"--cwd", spec.cwd,
+			"--label", label,
+			"--env", "PI_SUBAGENT_ROLE=sub",
+			"--env", `PI_SUBAGENT_CHANNEL=${spec.channelDir}`,
+			"--env", `PI_SUBAGENT_TOKEN=${spec.token}`,
+			"--no-focus",
+		], { timeout: 15_000, signal });
+		let payload: Record<string, unknown>;
+		try { payload = parseEnvelope(created.stdout); } catch (error) {
+			if (created.code !== 0 || created.killed) throw new Error(created.stderr || "Failed to create Herdr tab.");
+			throw error;
+		}
+		const tabId = nestedString(payload, "tab", "tab_id") ?? nestedString(payload, "tab", "id");
+		const paneId = nestedString(payload, "root_pane", "pane_id") ?? nestedString(payload, "pane", "pane_id");
+		if (!tabId) throw new Error("Herdr tab creation response did not contain a tab ID; automatic cleanup is unavailable.");
+		const handle: SurfaceHandle = { adapter: "herdr", tabId, ...(paneId ? { paneId } : {}) };
+		const step = async (args: string[], timeout: number, failure: string) => {
+			signal?.throwIfAborted();
+			const result = await this.pi.exec("herdr", args, { timeout, signal });
+			if (result.code !== 0 || result.killed) throw new Error(result.stderr || failure);
+			signal?.throwIfAborted();
+		};
+		try {
+			if (created.code !== 0 || created.killed) throw new Error(created.stderr || "Failed to create Herdr tab.");
+			if (!paneId) throw new Error("Herdr tab creation response did not contain a root pane ID.");
+			const name = agentName(spec.runId);
+			await step([
+				"agent", "start", name, "--kind", "pi", "--pane", paneId, "--timeout", "60000", "--", ...subArgs(spec),
+			], 70_000, "Failed to start Sub Pi in Herdr tab.");
+			await step([
+				"pane", "report-metadata", paneId, "--source", "subagent",
+				"--token", "subagent_role=sub", "--token", `subagent_main_session=${spec.mainSessionId}`,
+				"--token", `subagent_run_id=${spec.runId}`, "--token", `subagent_profile=${spec.profile.name}`,
+			], 10_000, "Failed to mark the Herdr pane as a Pi Subagent Sub.");
+			await step(["agent", "prompt", name, spec.task], 20_000, "Failed to submit the delegated task to the Herdr agent.");
+			return handle;
+		} catch (error) {
+			try {
+				// Rollback must not inherit the cancellation that caused the failure.
+				await this.close(handle);
+			} catch (cleanup) {
+				throw new HerdrLaunchCleanupError(handle, error, cleanup);
+			}
+			throw error;
+		}
+	}
+
+	async status(handle: SurfaceHandle | undefined): Promise<SubAgentStatus> {
+		if (!handle?.paneId) return "unknown";
+		try {
+			const response = await this.pi.exec("herdr", ["agent", "get", handle.paneId], { timeout: 3000 });
+			if (response.code !== 0) return "unknown";
+			const agent = parseEnvelope(response.stdout).agent;
+			if (!agent || typeof agent !== "object") return "unknown";
+			const info = agent as Record<string, unknown>;
+			if (info.pane_id !== handle.paneId || (handle.tabId && info.tab_id !== handle.tabId)) return "unknown";
+			return info.agent_status === "working" || info.agent_status === "blocked" || info.agent_status === "idle"
+				? info.agent_status : "unknown";
+		} catch {
+			return "unknown";
+		}
+	}
+
+	/** Distinguish an explicitly missing tab from a disconnected or unhealthy Herdr. */
+	async exists(handle: SurfaceHandle | undefined): Promise<boolean | undefined> {
+		if (!handle?.tabId) return undefined;
+		try {
+			const response = await this.pi.exec("herdr", ["tab", "get", handle.tabId], { timeout: 3000 });
+			if (response.killed) return undefined;
+			const payload = parseEnvelope(response.stdout);
+			if (response.code !== 0) return nestedString(payload, "error", "code") === "tab_not_found" ? false : undefined;
+			return nestedString(payload, "tab", "tab_id") === handle.tabId ? true : undefined;
+		} catch { return undefined; }
+	}
+
+	async close(handle: SurfaceHandle): Promise<void> {
+		if (!handle.tabId) return;
+		const result = await this.pi.exec("herdr", ["tab", "close", handle.tabId], { timeout: 10_000 });
+		if (result.code !== 0 || result.killed) throw new Error(result.stderr || `Failed to close Herdr tab ${handle.tabId}.`);
+	}
+}

package/src/adapters/index.ts

@@ -0,0 +1,31 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { HerdrTabAdapter } from "./herdr.js";
+import type { SubAgentStatus, SurfaceHandle } from "../types.js";
+
+export class AdapterRegistry {
+	private readonly herdr: HerdrTabAdapter;
+
+	constructor(pi: ExtensionAPI) {
+		this.herdr = new HerdrTabAdapter(pi);
+	}
+
+	async resolve(): Promise<HerdrTabAdapter> {
+		if (!(await this.herdr.available())) {
+			throw new Error("Pi Subagent requires Herdr, but the Herdr adapter is unavailable.");
+		}
+		return this.herdr;
+	}
+
+	async status(handle: SurfaceHandle | undefined): Promise<SubAgentStatus> {
+		return this.herdr.status(handle);
+	}
+
+	async exists(handle: SurfaceHandle | undefined): Promise<boolean | undefined> {
+		return this.herdr.exists(handle);
+	}
+
+	async close(handle: SurfaceHandle | undefined): Promise<void> {
+		if (!handle) return;
+		await this.herdr.close(handle);
+	}
+}

package/src/channel-monitor.ts

@@ -0,0 +1,127 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TalkDirection } from "./channel.js";
+
+export const CHANNEL_DEBOUNCE_MS = 20;
+export const CHANNEL_RESCAN_MS = 5000;
+export type WatchDirectory = (directory: string, listener: (event: fs.WatchEventType, filename: string | Buffer | null) => void) => fs.FSWatcher;
+interface WatchedDirectory {
+	path: string;
+	accept: (name: string) => boolean;
+	watcher?: fs.FSWatcher;
+	error?: string;
+}
+interface WatchedChannel {
+	directory: string;
+	direction: TalkDirection;
+	directories: WatchedDirectory[];
+}
+
+/** Files notify; the same bounded rescan path handles missed/unsupported watches. */
+export class ChannelMonitor {
+	private readonly channels = new Map<string, WatchedChannel>();
+	private readonly dirty = new Set<string>();
+	private active = false;
+	private debounce?: ReturnType<typeof setTimeout>;
+	private fallback?: ReturnType<typeof setInterval>;
+
+	constructor(
+		private readonly scan: (ids: string[]) => void,
+		private readonly onError: (id: string, error: unknown) => void,
+		private readonly onRecovered: (id: string) => void = () => {},
+		private readonly watch: WatchDirectory = (directory, listener) => fs.watch(directory, { persistent: false }, listener),
+	) {}
+
+	start(): void {
+		if (this.active) return;
+		this.active = true;
+		for (const [id, channel] of this.channels) this.attach(id, channel);
+		this.fallback = setInterval(() => {
+			for (const [id, channel] of this.channels) this.attach(id, channel);
+			this.wakeAll();
+		}, CHANNEL_RESCAN_MS);
+		this.fallback.unref?.();
+	}
+
+	add(id: string, directory: string, direction: TalkDirection): void {
+		const existing = this.channels.get(id);
+		if (existing?.directory === directory && existing.direction === direction) return;
+		this.remove(id);
+		const controls = new Set(direction === "to-main" ? ["session.json", "closed.json"] : ["close.json", "interrupt.json"]);
+		const channel: WatchedChannel = {
+			directory, direction,
+			directories: [
+				{ path: directory, accept: (name) => controls.has(name) },
+				{ path: path.join(directory, direction), accept: (name) => name.endsWith(".json") },
+			],
+		};
+		this.channels.set(id, channel);
+		if (this.active) this.attach(id, channel);
+	}
+
+	private attach(id: string, channel: WatchedChannel): void {
+		for (const slot of channel.directories) {
+			if (slot.watcher) continue;
+			const fail = (error: unknown) => {
+				if (!this.active || this.channels.get(id) !== channel) return;
+				const signature = error instanceof Error ? error.message : String(error);
+				if (slot.error !== signature) { slot.error = signature; this.onError(id, error); }
+			};
+			try {
+				const watcher = this.watch(slot.path, (_event, filename) => {
+					if (this.channels.get(id) !== channel) return;
+					if (filename == null || slot.accept(path.basename(filename.toString()))) this.wake(id);
+				});
+				slot.watcher = watcher;
+				watcher.on("error", (error) => {
+					if (slot.watcher !== watcher) return;
+					slot.watcher = undefined;
+					watcher.close();
+					fail(error);
+					this.wake(id);
+				});
+				watcher.on("close", () => {
+					if (slot.watcher !== watcher) return;
+					slot.watcher = undefined;
+					fail(new Error(`File watcher closed: ${slot.path}`));
+				});
+				if (slot.error) { slot.error = undefined; this.onRecovered(id); }
+			} catch (error) { fail(error); }
+		}
+	}
+
+	wake(id: string): void {
+		if (!this.active || !this.channels.has(id)) return;
+		this.dirty.add(id);
+		if (this.debounce) return;
+		this.debounce = setTimeout(() => {
+			this.debounce = undefined;
+			const ids = [...this.dirty];
+			this.dirty.clear();
+			if (!this.active || ids.length === 0) return;
+			try { this.scan(ids); } catch (error) { this.onError(ids.join(", "), error); }
+		}, CHANNEL_DEBOUNCE_MS);
+		this.debounce.unref?.();
+	}
+	wakeAll(): void {
+		for (const id of this.channels.keys()) this.wake(id);
+	}
+	remove(id: string): void {
+		const channel = this.channels.get(id);
+		this.channels.delete(id);
+		this.dirty.delete(id);
+		for (const slot of channel?.directories ?? []) {
+			const watcher = slot.watcher;
+			slot.watcher = undefined;
+			watcher?.close();
+		}
+	}
+	stop(): void {
+		this.active = false;
+		if (this.debounce) clearTimeout(this.debounce);
+		if (this.fallback) clearInterval(this.fallback);
+		this.debounce = undefined;
+		this.fallback = undefined;
+		for (const id of [...this.channels.keys()]) this.remove(id);
+	}
+}