@oldflag2333333/pi-subagent 0.0.0-stage → 0.1.1

package/src/channel.ts

@@ -0,0 +1,286 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type {
+	SubClosedMessage,
+	SubSessionInfo,
+	CloseMessage,
+	DelegateManifest,
+	ActiveTurn,
+	InterruptRequest,
+	TalkMessage,
+} from "./types.js";
+
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const MAX_TALK_BYTES = 1024 * 1024;
+const MAX_CONTROL_BYTES = 64 * 1024;
+
+export const MESSAGE_TYPE = "subagent-message";
+
+export type TalkDirection = "to-main" | "to-sub";
+
+function safeSegment(value: string): string {
+	return value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 96) || "unknown";
+}
+
+export function runtimeRoot(): string {
+	const base = process.env.XDG_RUNTIME_DIR || os.tmpdir();
+	const owner = typeof process.getuid === "function" ? String(process.getuid()) : safeSegment(os.userInfo().username);
+	return path.join(base, `pi-subagent-${owner}`);
+}
+
+export function channelPath(mainSessionId: string, runId: string): string {
+	return path.join(runtimeRoot(), safeSegment(mainSessionId), safeSegment(runId));
+}
+
+export function writeAtomicJson(file: string, value: unknown, maxBytes = MAX_CONTROL_BYTES): void {
+	const serialized = `${JSON.stringify(value, null, 2)}\n`;
+	if (Buffer.byteLength(serialized, "utf8") > maxBytes) throw new Error(`${path.basename(file)} exceeds ${maxBytes} bytes.`);
+	// createChannel owns directory creation. Late writes must not resurrect a closed channel.
+	const temporary = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		fs.writeFileSync(temporary, serialized, { encoding: "utf8", mode: 0o600 });
+		fs.renameSync(temporary, file);
+	} finally {
+		fs.rmSync(temporary, { force: true });
+	}
+}
+
+function readJson(file: string): unknown | undefined {
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+export function createChannel(input: Omit<DelegateManifest, "version" | "token" | "createdAt">): DelegateManifest & { channelDir: string } {
+	const token = randomBytes(32).toString("hex");
+	const channelDir = channelPath(input.mainSessionId, input.runId);
+	fs.mkdirSync(path.dirname(channelDir), { recursive: true, mode: 0o700 });
+	// Never replace an existing run\'s capability token or remove its channel.
+	fs.mkdirSync(channelDir, { mode: 0o700 });
+	try {
+		fs.mkdirSync(path.join(channelDir, "to-main"), { mode: 0o700 });
+		fs.mkdirSync(path.join(channelDir, "to-sub"), { mode: 0o700 });
+		const manifest: DelegateManifest = { version: 1, ...input, token, createdAt: Date.now() };
+		writeAtomicJson(path.join(channelDir, "manifest.json"), manifest, MAX_MANIFEST_BYTES);
+		return { ...manifest, channelDir };
+	} catch (error) {
+		try { removeChannel(channelDir); } catch (cleanup) {
+			throw new AggregateError([error, cleanup], `Failed to create and clean up Pi Subagent channel ${channelDir}.`);
+		}
+		throw error;
+	}
+}
+
+function validProfile(value: unknown): boolean {
+	const profile = record(value);
+	return Boolean(profile && profile.version === 1 && typeof profile.name === "string" && profile.name.length > 0
+		&& (profile.source === "global" || profile.source === "project") && typeof profile.sourcePath === "string"
+		&& Array.isArray(profile.tools) && profile.tools.length > 0 && profile.tools.every((tool) => typeof tool === "string" && tool.length > 0)
+		&& (profile.skills === undefined || (Array.isArray(profile.skills) && profile.skills.every((skill) => typeof skill === "string")))
+		&& Array.isArray(profile.resolvedSkills) && profile.resolvedSkills.every((skill) => typeof skill === "string")
+		&& Array.isArray(profile.resolvedExtensions) && profile.resolvedExtensions.every((extension) => typeof extension === "string")
+		&& (profile.description === undefined || typeof profile.description === "string")
+		&& (profile.model === undefined || typeof profile.model === "string")
+		&& (profile.thinkingLevel === undefined || typeof profile.thinkingLevel === "string")
+		&& (profile.invocation === undefined || profile.invocation === "both" || profile.invocation === "manual")
+		&& (profile.sessionPersistence === undefined || profile.sessionPersistence === "ephemeral" || profile.sessionPersistence === "persistent")
+		&& (profile.instructions === undefined || typeof profile.instructions === "string"));
+}
+
+export function readManifest(channelDir: string): DelegateManifest {
+	const value = record(readJson(path.join(channelDir, "manifest.json")));
+	if (!value || value.version !== 1 || typeof value.runId !== "string" || typeof value.mainSessionId !== "string"
+		|| typeof value.title !== "string" || typeof value.task !== "string" || typeof value.cwd !== "string"
+		|| (value.origin !== undefined && value.origin !== "manual")
+		|| !validProfile(value.profile) || typeof value.token !== "string" || typeof value.createdAt !== "number") {
+		throw new Error("Invalid Pi Subagent channel manifest.");
+	}
+	return value as unknown as DelegateManifest;
+}
+
+function writeTalk(channelDir: string, manifest: DelegateManifest, direction: TalkDirection, message: string): TalkMessage {
+	// Each direction has one writer. Persist the counter before the payload;
+	// gaps after a failed write are harmless, and reloads cannot reorder messages.
+	const counterPath = path.join(channelDir, `${direction}-sequence.json`);
+	const storedCounter = readJson(counterPath);
+	const previous = record(storedCounter);
+	if (storedCounter !== undefined && (!previous || previous.runId !== manifest.runId || previous.token !== manifest.token
+		|| !Number.isSafeInteger(previous.sequence) || (previous.sequence as number) < 1)) {
+		throw new Error("Invalid Pi Subagent talk sequence counter.");
+	}
+	const sequence = ((previous?.sequence as number | undefined) ?? 0) + 1;
+	if (!Number.isSafeInteger(sequence)) throw new Error("Pi Subagent talk sequence exhausted.");
+	writeAtomicJson(counterPath, { runId: manifest.runId, token: manifest.token, sequence });
+	const talk: TalkMessage = {
+		version: 1,
+		id: randomUUID(),
+		sequence,
+		runId: manifest.runId,
+		token: manifest.token,
+		createdAt: Date.now(),
+		message,
+	};
+	writeAtomicJson(path.join(channelDir, direction, `${safeSegment(talk.id)}.json`), talk, MAX_TALK_BYTES);
+	return talk;
+}
+
+export function talkToMain(channelDir: string, manifest: DelegateManifest, message: string): TalkMessage {
+	return writeTalk(channelDir, manifest, "to-main", message);
+}
+
+export function talkToSub(channelDir: string, manifest: DelegateManifest, message: string): TalkMessage {
+	return writeTalk(channelDir, manifest, "to-sub", message);
+}
+
+function validTalk(value: unknown, manifest: DelegateManifest): value is TalkMessage {
+	const item = record(value);
+	return Boolean(item && item.version === 1 && item.runId === manifest.runId && item.token === manifest.token
+		&& typeof item.id === "string" && Number.isSafeInteger(item.sequence) && (item.sequence as number) > 0
+		&& typeof item.createdAt === "number" && typeof item.message === "string");
+}
+
+function listTalk(channelDir: string, manifest: DelegateManifest, direction: TalkDirection): TalkMessage[] {
+	let names: string[];
+	try {
+		names = fs.readdirSync(path.join(channelDir, direction));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const messages: TalkMessage[] = [];
+	for (const name of names.filter((name) => name.endsWith(".json")).sort()) {
+		const value = readJson(path.join(channelDir, direction, name));
+		if (validTalk(value, manifest)) messages.push(value);
+	}
+	return messages.sort((left, right) => left.sequence - right.sequence);
+}
+
+export function listTalkToMain(channelDir: string, manifest: DelegateManifest): TalkMessage[] {
+	return listTalk(channelDir, manifest, "to-main");
+}
+
+export function listTalkToSub(channelDir: string, manifest: DelegateManifest): TalkMessage[] {
+	return listTalk(channelDir, manifest, "to-sub");
+}
+
+export function removeTalk(channelDir: string, direction: TalkDirection, id: string): void {
+	fs.rmSync(path.join(channelDir, direction, `${safeSegment(id)}.json`), { force: true });
+}
+
+export function writeSubSessionInfo(channelDir: string, manifest: DelegateManifest, input: {
+	sessionId: string;
+	sessionFile: string;
+}): SubSessionInfo {
+	const info: SubSessionInfo = {
+		version: 1,
+		runId: manifest.runId,
+		token: manifest.token,
+		sessionId: input.sessionId,
+		sessionFile: input.sessionFile,
+		createdAt: Date.now(),
+	};
+	writeAtomicJson(path.join(channelDir, "session.json"), info);
+	return info;
+}
+
+export function readSubSessionInfo(channelDir: string, manifest: DelegateManifest): SubSessionInfo | undefined {
+	const value = record(readJson(path.join(channelDir, "session.json")));
+	if (!value || value.version !== 1 || value.runId !== manifest.runId || value.token !== manifest.token
+		|| typeof value.sessionId !== "string" || typeof value.sessionFile !== "string" || typeof value.createdAt !== "number") return undefined;
+	return value as unknown as SubSessionInfo;
+}
+
+export function writeActiveTurn(channelDir: string, manifest: DelegateManifest): ActiveTurn {
+	const turn: ActiveTurn = {
+		version: 1,
+		runId: manifest.runId,
+		token: manifest.token,
+		turnId: randomUUID(),
+		createdAt: Date.now(),
+	};
+	writeAtomicJson(path.join(channelDir, "active-turn.json"), turn);
+	return turn;
+}
+
+export function readActiveTurn(channelDir: string, manifest: Pick<DelegateManifest, "runId" | "token">): ActiveTurn | undefined {
+	const value = record(readJson(path.join(channelDir, "active-turn.json")));
+	if (!value || value.version !== 1 || value.runId !== manifest.runId || value.token !== manifest.token
+		|| typeof value.turnId !== "string" || typeof value.createdAt !== "number") return undefined;
+	return value as unknown as ActiveTurn;
+}
+
+export function clearActiveTurn(channelDir: string, turn: ActiveTurn): void {
+	// An older settle event must not erase a newer turn.
+	try {
+		if (readActiveTurn(channelDir, turn)?.turnId === turn.turnId) {
+			fs.rmSync(path.join(channelDir, "active-turn.json"), { force: true });
+		}
+	} catch {}
+}
+
+export function writeInterrupt(channelDir: string, manifest: DelegateManifest, turn: ActiveTurn): InterruptRequest {
+	const request: InterruptRequest = { ...turn, requestedAt: Date.now() };
+	writeAtomicJson(path.join(channelDir, "interrupt.json"), request);
+	return request;
+}
+
+export function readInterrupt(channelDir: string, manifest: DelegateManifest): InterruptRequest | undefined {
+	const value = record(readJson(path.join(channelDir, "interrupt.json")));
+	if (!value || value.version !== 1 || value.runId !== manifest.runId || value.token !== manifest.token
+		|| typeof value.turnId !== "string" || typeof value.createdAt !== "number"
+		|| typeof value.requestedAt !== "number") return undefined;
+	return value as unknown as InterruptRequest;
+}
+
+export function clearInterrupt(channelDir: string): void {
+	fs.rmSync(path.join(channelDir, "interrupt.json"), { force: true });
+}
+
+export function writeClose(channelDir: string, manifest: DelegateManifest, reason: string): void {
+	const message: CloseMessage = {
+		version: 1,
+		runId: manifest.runId,
+		token: manifest.token,
+		createdAt: Date.now(),
+		reason,
+	};
+	writeAtomicJson(path.join(channelDir, "close.json"), message);
+}
+
+export function readClose(channelDir: string, manifest: DelegateManifest): CloseMessage | undefined {
+	const value = record(readJson(path.join(channelDir, "close.json")));
+	if (!value || value.version !== 1 || value.runId !== manifest.runId || value.token !== manifest.token
+		|| typeof value.createdAt !== "number" || typeof value.reason !== "string") return undefined;
+	return value as unknown as CloseMessage;
+}
+
+export function writeSubClosed(channelDir: string, manifest: DelegateManifest, reason: string): void {
+	const message: SubClosedMessage = {
+		version: 1,
+		runId: manifest.runId,
+		token: manifest.token,
+		createdAt: Date.now(),
+		reason,
+	};
+	writeAtomicJson(path.join(channelDir, "closed.json"), message);
+}
+
+export function readSubClosed(channelDir: string, manifest: DelegateManifest): SubClosedMessage | undefined {
+	const value = record(readJson(path.join(channelDir, "closed.json")));
+	if (!value || value.version !== 1 || value.runId !== manifest.runId || value.token !== manifest.token
+		|| typeof value.createdAt !== "number" || typeof value.reason !== "string") return undefined;
+	return value as unknown as SubClosedMessage;
+}
+
+export function removeChannel(channelDir: string): void {
+	fs.rmSync(channelDir, { recursive: true, force: true });
+}

package/src/commands/clean-sub.ts

@@ -0,0 +1,90 @@
+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";
+import { subSessionDir, subSessionsRoot } from "../sessions.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 cleanSubFiles(currentMainId: string, currentSessionDir: string): { removed: number; errors: string[] } {
+	const stores = [
+		{ root: runtimeRoot(), ownerDirectory: (id: string) => path.basename(path.dirname(channelPath(id, "unused"))) },
+		{ root: subSessionsRoot(), ownerDirectory: (id: string) => path.basename(subSessionDir(id)) },
+	].map((store) => {
+		const candidates = entries(store.root).filter((entry) => entry.isDirectory());
+		if (candidates.length && fs.lstatSync(store.root).isSymbolicLink()) throw new Error(`Refusing to clean symlinked directory: ${store.root}`);
+		return { ...store, candidates };
+	});
+	if (stores.every((store) => store.candidates.length === 0)) return { removed: 0, errors: [] };
+
+	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)));
+		}
+	}
+	let removed = 0;
+	const errors: string[] = [];
+	for (const store of stores) {
+		const liveDirectories = new Set([...live].map(store.ownerDirectory));
+		for (const entry of store.candidates) {
+			if (liveDirectories.has(entry.name)) continue;
+			const directory = path.join(store.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(`${directory}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+	}
+	return { removed, errors };
+}
+
+export function registerCleanSubCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("clean-sub", {
+		description: "Delete managed Sub sessions and communication directories whose Main session can no longer be found.",
+		handler: async (_args, ctx) => {
+			try {
+				const result = cleanSubFiles(ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
+				ctx.ui.notify([
+					`Removed ${result.removed} orphaned Sub data directories (sessions and communication).`,
+					...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,114 @@
+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";
+import { parentWakeFor } from "./parent-wake.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);
+	// Serialize idle submissions until Pi starts the run or records its receipt.
+	// Once active, subsequent deliveries use Pi's native follow-up queue.
+	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;
+		parentWakeFor(pi, ctx).agentStarted();
+		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("session_shutdown", (event, ctx) => {
+		// Use the event context: manager shutdown may already have cleared its active context.
+		parentWakeFor(pi, ctx).sessionShutdown(event.reason);
+	});
+	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();
+
+	// Render live deliveries and saved custom messages with the same inbox card.
+	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.";