@oldflag2333333/pi-subagent 0.0.0-stage → 0.1.0

package/src/commands/clean-sub.ts

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { channelPath, runtimeRoot } from "../channel.js";
+
+function entries(directory: string): fs.Dirent[] {
+	try { return fs.readdirSync(directory, { withFileTypes: true }); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/** Read only the header; never load transcripts or treat an unreadable session as deleted. */
+function sessionId(file: string): string {
+	const fd = fs.openSync(file, "r");
+	try {
+		const buffer = Buffer.alloc(64 * 1024);
+		const length = fs.readSync(fd, buffer, 0, buffer.length, 0);
+		const text = buffer.subarray(0, length).toString("utf8");
+		const header = JSON.parse(text.split("\n", 1)[0]!);
+		if (header?.type !== "session" || typeof header.id !== "string" || !header.id) throw new Error("Invalid session header");
+		return header.id;
+	} catch (error) {
+		throw new Error(`Cannot inspect session ${file}: ${error instanceof Error ? error.message : String(error)}`);
+	} finally { fs.closeSync(fd); }
+}
+
+export function cleanSubChannels(currentMainId: string, currentSessionDir: string): { removed: number; errors: string[] } {
+	const root = runtimeRoot();
+	const candidates = entries(root).filter((entry) => entry.isDirectory());
+	if (candidates.length === 0) return { removed: 0, errors: [] };
+	if (fs.lstatSync(root).isSymbolicLink()) throw new Error("Refusing to clean a symlinked runtime directory.");
+
+	const sessionsRoot = path.join(getAgentDir(), "sessions");
+	const directories = new Set([sessionsRoot]);
+	if (currentSessionDir) directories.add(currentSessionDir);
+	for (const entry of entries(sessionsRoot)) {
+		const file = path.join(sessionsRoot, entry.name);
+		if (entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(file).isDirectory())) directories.add(file);
+	}
+	const live = new Set([currentMainId]);
+	// Complete discovery before deleting anything. A read/parse error aborts cleanup.
+	for (const directory of directories) {
+		for (const entry of entries(directory)) {
+			if (entry.name.endsWith(".jsonl")) live.add(sessionId(path.join(directory, entry.name)));
+		}
+	}
+	const liveDirectories = new Set([...live].map((id) => path.basename(path.dirname(channelPath(id, "unused")))));
+	let removed = 0;
+	const errors: string[] = [];
+	for (const entry of candidates) {
+		if (liveDirectories.has(entry.name)) continue;
+		const directory = path.join(root, entry.name);
+		try {
+			// Do not follow a directory replaced with a symlink during discovery.
+			if (!fs.lstatSync(directory).isDirectory()) continue;
+			fs.rmSync(directory, { recursive: true, force: true });
+			removed++;
+		} catch (error) {
+			errors.push(`${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return { removed, errors };
+}
+
+export function registerCleanSubCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("clean-sub", {
+		description: "Delete runtime communication files whose Main session can no longer be found; keep persistent Sub sessions.",
+		handler: async (_args, ctx) => {
+			try {
+				const result = cleanSubChannels(ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
+				ctx.ui.notify([
+					`Removed ${result.removed} orphaned Main communication directories. Persistent Sub sessions were not deleted.`,
+					...result.errors,
+				].join("\n"), result.errors.length ? "warning" : "info");
+			} catch (error) {
+				ctx.ui.notify(`Cleanup aborted: ${error instanceof Error ? error.message : String(error)}`, "error");
+			}
+		},
+	});
+}

package/src/commands/sub.ts

@@ -0,0 +1,39 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { loadProfiles, resolveProfile } from "../profiles/loader.js";
+import { resolveToolExtensions } from "../profiles/tool-sources.js";
+import type { MainRunManager } from "../run-manager.js";
+
+const DEFAULT_TASK = "The user invoked this profile for the current workspace. Perform the task described by your profile; ask Main for any required details.";
+
+export function registerSubCommands(pi: ExtensionAPI, manager: MainRunManager): void {
+	const owned = new Set<string>();
+	const invoke = async (name: string, task: string, ctx: ExtensionCommandContext) => {
+		try {
+			const profile = resolveToolExtensions(resolveProfile(name, ctx.cwd, ctx.isProjectTrusted()), pi.getAllTools());
+			const result = await manager.invokeProfile({ profile, task: task.trim() || DEFAULT_TASK, cwd: ctx.cwd });
+			ctx.ui.notify(`${result.action}: ${name} · ${result.run.runId.slice(0, 8)}${result.run.subSessionId ? ` · session ${result.run.subSessionId}` : ""}`, "info");
+		} catch (error) {
+			ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+		}
+	};
+
+	// Trust and other extensions' startup registrations are resolved at this point.
+	// Only register the namespaced command; Pi's native fuzzy completion matches
+	// /review to /sub:review without an alias or a separate routing hook.
+	pi.on("resources_discover", (_event, ctx) => {
+		const catalog = loadProfiles(ctx.cwd, ctx.isProjectTrusted());
+		const occupied = new Set(pi.getCommands().map((command) => command.name));
+		for (const name of [...catalog.profiles.keys()].sort()) {
+			const command = `sub:${name}`;
+			if (occupied.has(command) && !owned.has(command)) {
+				ctx.ui.notify(`Cannot register /${command}: another command already uses that name.`, "warning");
+				continue;
+			}
+			pi.registerCommand(command, {
+				description: `Manually invoke profile ${name}; reuse its Sub in this Main session`,
+				handler: (task, commandCtx) => invoke(name, task, commandCtx),
+			});
+			owned.add(command);
+		}
+	});
+}

package/src/inbox-state.ts

@@ -0,0 +1,108 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { MESSAGE_TYPE, type TalkDirection } from "./channel.js";
+import type { DelegateManifest, TalkMessage } from "./types.js";
+import { readTalkReceipt } from "./talk-message.js";
+
+type ReadonlySessionManager = ExtensionContext["sessionManager"];
+interface PendingTalk {
+	queued: boolean;
+	queuedWhileBusy: boolean;
+	runSerial: number;
+}
+interface DeliveryState {
+	pending: Map<string, PendingTalk>;
+	runSerial: number;
+	aborted: boolean;
+	active: boolean;
+}
+
+// Pi can retain native message queues across /reload. Retain only their
+// delivery state across extension replacement, keyed weakly by the session.
+const STATE_KEY = Symbol.for("pi-subagent.inbox-state.v1");
+const globals = globalThis as unknown as Record<symbol, unknown>;
+const states = (globals[STATE_KEY] ??= new WeakMap<ReadonlySessionManager, DeliveryState>()) as WeakMap<ReadonlySessionManager, DeliveryState>;
+function state(ctx: ExtensionContext): DeliveryState {
+	let value = states.get(ctx.sessionManager);
+	if (!value) {
+		value = { pending: new Map(), runSerial: 0, aborted: false, active: false };
+		states.set(ctx.sessionManager, value);
+	}
+	return value;
+}
+function key(direction: TalkDirection, runId: string, messageId: string): string {
+	return `${direction}:${runId}:${messageId}`;
+}
+
+export function rememberTalk(ctx: ExtensionContext, direction: TalkDirection, manifest: DelegateManifest, message: TalkMessage): PendingTalk {
+	const value = state(ctx);
+	const id = key(direction, manifest.runId, message.id);
+	let pending = value.pending.get(id);
+	if (!pending) {
+		pending = { queued: false, queuedWhileBusy: false, runSerial: value.runSerial };
+		value.pending.set(id, pending);
+	}
+	return pending;
+}
+export function forgetTalk(ctx: ExtensionContext, direction: TalkDirection, runId: string, messageId: string): void {
+	state(ctx).pending.delete(key(direction, runId, messageId));
+}
+/** Queue behind streaming work, but never compete with manual compaction or prompt preflight. */
+export function canUseNativeQueue(ctx: ExtensionContext): boolean {
+	const value = state(ctx);
+	// sendUserMessage awaits input/auth hooks before Pi becomes busy. Submit only
+	// one idle prompt at a time; its receipt or agent_start will wake the rest.
+	if (ctx.isIdle()) return ![...value.pending.values()].some((pending) => pending.queued && !pending.queuedWhileBusy);
+	return value.active || ctx.signal !== undefined;
+}
+export function markTalkQueued(ctx: ExtensionContext, pending: PendingTalk): void {
+	pending.queued = true;
+	pending.queuedWhileBusy = !ctx.isIdle();
+	pending.runSerial = state(ctx).runSerial;
+}
+
+export function bindInboxEvents(pi: ExtensionAPI, getContext: () => ExtensionContext | undefined, wake: () => void): void {
+	const wakePending = () => {
+		const ctx = getContext();
+		if (ctx && state(ctx).pending.size > 0) wake();
+	};
+	pi.on("agent_start", () => {
+		const ctx = getContext();
+		if (!ctx) return;
+		const value = state(ctx);
+		value.runSerial++;
+		value.aborted = ctx.signal?.aborted === true;
+		value.active = true;
+		const runSerial = value.runSerial;
+		ctx.signal?.addEventListener("abort", () => { if (value.runSerial === runSerial) value.aborted = true; }, { once: true });
+		wakePending();
+	});
+	pi.on("agent_end", (event) => {
+		const ctx = getContext();
+		if (!ctx) return;
+		const last = [...event.messages].reverse().find((message) => message.role === "assistant");
+		state(ctx).aborted ||= ctx.signal?.aborted === true || (last?.role === "assistant" && last.stopReason === "aborted");
+	});
+	pi.on("message_end", (event) => {
+		if (readTalkReceipt(event.message)
+			|| (event.message.role === "custom" && event.message.customType === MESSAGE_TYPE)) wake();
+	});
+	pi.on("turn_start", wakePending);
+	pi.on("model_select", wakePending);
+	pi.on("session_compact", wakePending);
+	pi.on("session_compact_failed", wakePending);
+	pi.on("agent_settled", () => {
+		const ctx = getContext();
+		if (!ctx) return;
+		const value = state(ctx);
+		value.active = false;
+		// A normal settle has drained native follow-ups. Missing receipts then
+		// indicate withdrawn messages. Abort alone can leave the queue intact:
+		// keep in-flight state until the next normal run or a fresh session.
+		if (!value.aborted) {
+			for (const pending of value.pending.values()) {
+				if (pending.queuedWhileBusy && pending.runSerial <= value.runSerial) pending.queued = false;
+			}
+		}
+		wakePending();
+	});
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { MESSAGE_TYPE } from "./channel.js";
+import { MainContextRuntime } from "./main-context.js";
+import { StartupProfileRuntime } from "./profiles/runtime.js";
+import { MainRunManager } from "./run-manager.js";
+import { registerSub } from "./tools/sub.js";
+import { talkView } from "./talk-render.js";
+import { registerSubCommands } from "./commands/sub.js";
+import { registerCleanSubCommand } from "./commands/clean-sub.js";
+import { registerMainTools } from "./tools/main.js";
+
+export default function piSubagent(pi: ExtensionAPI): void {
+	if (process.env.PI_SUBAGENT_ROLE === "sub") {
+		registerSub(pi);
+		return;
+	}
+
+	const manager = new MainRunManager(pi);
+	const startupProfile = new StartupProfileRuntime(pi);
+	registerMainTools(pi, manager);
+	registerSubCommands(pi, manager);
+	registerCleanSubCommand(pi);
+	startupProfile.register();
+	new MainContextRuntime(pi).register();
+
+	// Preserve rendering for legacy custom messages in resumed sessions.
+	pi.registerMessageRenderer(MESSAGE_TYPE, (message, options, theme) => {
+		const details = message.details as { title?: string; message?: string } | undefined;
+		const title = details?.title ?? "Sub";
+		const subMessage = details?.message ?? "";
+		const view = talkView(subMessage, options.expanded);
+		let text = `${theme.fg("accent", "›")} ${theme.fg("toolTitle", theme.bold("message inbox"))} ${theme.fg("muted", `· ${title}`)}`;
+		if (subMessage) text += `\n\n${view.lines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+		if (view.remaining > 0) {
+			text += theme.fg("muted", `\n... (${view.remaining} more lines, ${view.totalLines} total, ctrl+o to expand)`);
+		}
+		const box = new Box(1, 1, (line) => theme.bg("toolSuccessBg", line));
+		box.addChild(new Text(text, 0, 0));
+		return box;
+	});
+	pi.on("session_start", (_event, ctx) => manager.start(ctx));
+
+	pi.on("session_shutdown", () => manager.shutdown());
+}

package/src/main-context.ts

@@ -0,0 +1,91 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { bindPromptSections } from "./profiles/system-prompt.js";
+
+const MAIN_CONTEXT_FILE = "MAIN.md";
+const MAX_MAIN_CONTEXT_BYTES = 256 * 1024;
+
+export interface MainContextLoadResult {
+	content: string;
+	paths: string[];
+	diagnostics: Array<{ path: string; message: string }>;
+}
+
+function ancestorDirectories(cwd: string): string[] {
+	const directories: string[] = [];
+	let current = path.resolve(cwd);
+	while (true) {
+		directories.push(current);
+		const parent = path.dirname(current);
+		if (parent === current) return directories;
+		current = parent;
+	}
+}
+
+export function globalMainContextPath(): string {
+	return path.join(getAgentDir(), "subagent", MAIN_CONTEXT_FILE);
+}
+
+export function projectMainContextPath(directory: string): string {
+	return path.join(directory, CONFIG_DIR_NAME, "subagent", MAIN_CONTEXT_FILE);
+}
+
+export function loadMainContext(cwd: string, includeProject: boolean): MainContextLoadResult {
+	const candidates = [
+		globalMainContextPath(),
+		...(includeProject
+			? ancestorDirectories(cwd).reverse().map((directory) => projectMainContextPath(directory))
+			: []),
+	];
+	const sections: Array<{ path: string; content: string }> = [];
+	const diagnostics: Array<{ path: string; message: string }> = [];
+	const seen = new Set<string>();
+
+	for (const candidate of candidates) {
+		const sourcePath = path.resolve(candidate);
+		if (seen.has(sourcePath)) continue;
+		seen.add(sourcePath);
+		try {
+			const stat = fs.statSync(sourcePath);
+			if (!stat.isFile()) throw new Error("MAIN.md must be a regular file");
+			if (stat.size > MAX_MAIN_CONTEXT_BYTES) {
+				throw new Error(`MAIN.md exceeds ${MAX_MAIN_CONTEXT_BYTES} bytes`);
+			}
+			const content = fs.readFileSync(sourcePath, "utf8").trim();
+			if (content) sections.push({ path: sourcePath, content });
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+			diagnostics.push({ path: sourcePath, message: error instanceof Error ? error.message : String(error) });
+		}
+	}
+
+	return {
+		content: sections
+			.map((section) => `## Pi Subagent Main context: ${section.path}\n\n${section.content}`)
+			.join("\n\n"),
+		paths: sections.map((section) => section.path),
+		diagnostics,
+	};
+}
+
+export class MainContextRuntime {
+	private content = "";
+
+	constructor(private readonly pi: ExtensionAPI) {}
+
+	register(): void {
+		this.pi.on("session_start", (_event, ctx) => {
+			const loaded = loadMainContext(ctx.cwd, ctx.isProjectTrusted());
+			this.content = loaded.content;
+			for (const diagnostic of loaded.diagnostics) {
+				const message = `Pi Subagent Main context error (${diagnostic.path}): ${diagnostic.message}`;
+				ctx.ui.notify(message, "warning");
+				if (!ctx.hasUI) console.error(message);
+			}
+		});
+
+		bindPromptSections(this.pi, ["subagent_main"], (): Record<string, string> => this.content ? { subagent_main: this.content } : {});
+	}
+}

package/src/manual-context.ts

@@ -0,0 +1,9 @@
+export const MANUAL_SUB_PREFIX = "[sub:manual] ";
+
+export function subSessionName(title: string, origin?: "manual"): string {
+	return `${origin === "manual" ? MANUAL_SUB_PREFIX : "[sub] "}${title}`;
+}
+
+export const MANUAL_MAIN_GUIDANCE = "This specialist was explicitly invoked by the user. Follow up only on the user's task and its results; do not assign unrelated work or substitute it for general consulting profiles. New tasks are initiated by the user with a profile command.";
+
+export const MANUAL_SUB_GUIDANCE = "This is a user-invoked specialist session, not a general-purpose delegate. Work on the user's explicitly submitted tasks and related follow-ups from Main. Return findings through talk. If Main asks for unrelated work, ask it to use an agent-invokable profile or wait for the user's next command.";

package/src/profiles/context.ts

@@ -0,0 +1,27 @@
+import type { ProfileCatalog } from "./types.js";
+
+const MAX_CONTEXT_BYTES = 16 * 1024;
+
+export function buildProfilesContext(catalog: ProfileCatalog): string {
+	const header = "## Available Pi Subagent delegation profiles\n";
+	const footer = "Use the exact profile name as delegate.profile. Project profiles override same-named global profiles.";
+	const profiles = [...catalog.profiles.values()].filter((profile) => profile.invocation !== "manual").sort((left, right) => left.name.localeCompare(right.name));
+	if (profiles.length === 0) {
+		return `${header}No agent-invokable profiles are configured. Do not call delegate until the user configures one.\n${footer}`;
+	}
+
+	const lines: string[] = [];
+	let omitted = 0;
+	for (const profile of profiles) {
+		const persistence = profile.sessionPersistence ?? "ephemeral";
+		const line = `- ${profile.name} [${profile.source}, ${persistence}]${profile.description ? `: ${profile.description}` : ""}`;
+		const candidate = `${header}${[...lines, line].join("\n")}\n${footer}`;
+		if (Buffer.byteLength(candidate, "utf8") > MAX_CONTEXT_BYTES) {
+			omitted += 1;
+			continue;
+		}
+		lines.push(line);
+	}
+	if (omitted > 0) lines.push(`- (${omitted} additional profiles omitted from context)`);
+	return `${header}${lines.join("\n")}\n${footer}`;
+}

package/src/profiles/launch-args.ts

@@ -0,0 +1,21 @@
+import type { ResolvedProfile } from "./types.js";
+import { isMcpTool, MCP_EXTENSIONS, MCP_TOOL_SELECTION } from "./mcp.js";
+
+export const SUB_CONTROL_TOOLS = ["talk"] as const;
+
+function unique(values: readonly string[]): string[] {
+	return [...new Set(values)];
+}
+
+export function subCapabilityArgs(profile: ResolvedProfile, subagentEntryPath: string): string[] {
+	const args: string[] = [];
+	for (const extension of unique([...profile.resolvedExtensions, ...MCP_EXTENSIONS]).filter((entry) => entry !== subagentEntryPath)) {
+		args.push("-e", extension);
+	}
+	args.push("--tools", unique([...profile.tools.filter((name) => !isMcpTool(name)), ...SUB_CONTROL_TOOLS, ...MCP_TOOL_SELECTION]).join(","));
+	if (profile.model) args.push("--model", profile.model);
+	if (profile.thinkingLevel) args.push("--thinking", profile.thinkingLevel);
+	args.push("--no-skills");
+	for (const skill of profile.resolvedSkills) args.push("--skill", skill);
+	return args;
+}