@oldflag2333333/pi-subagent 0.0.0-stage → 0.1.0

package/src/tools/main.ts

@@ -0,0 +1,299 @@
+import * as path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { resolveProfile } from "../profiles/loader.js";
+import { resolveToolExtensions } from "../profiles/tool-sources.js";
+import { MAX_OPEN_SUBS, type MainRunManager } from "../run-manager.js";
+import { MANUAL_MAIN_GUIDANCE } from "../manual-context.js";
+import { talkView } from "../talk-render.js";
+import type { SubAgentStatus } from "../types.js";
+
+function normalizeTitle(value: string): string {
+	return value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 48) || "delegated task";
+}
+
+function findSubTitle(manager: MainRunManager, runId: unknown): string | undefined {
+	return typeof runId === "string" && runId ? manager.titleFor(runId) : undefined;
+}
+
+function formatElapsed(seconds: number): string {
+	if (seconds < 60) return `${seconds}s`;
+	if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+	if (seconds < 86_400) {
+		const hours = Math.floor(seconds / 3600);
+		const minutes = Math.floor((seconds % 3600) / 60);
+		return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+	}
+	const days = Math.floor(seconds / 86_400);
+	const hours = Math.floor((seconds % 86_400) / 3600);
+	return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+}
+
+function compactCapabilityList(values: string[], maxCharacters = 160): string {
+	if (values.length === 0) return "(none)";
+	const visible: string[] = [];
+	let length = 0;
+	for (const value of values) {
+		const addition = (visible.length > 0 ? 3 : 0) + value.length;
+		if (length + addition > maxCharacters) {
+			if (visible.length === 0) visible.push(`${value.slice(0, Math.max(1, maxCharacters - 1))}…`);
+			break;
+		}
+		visible.push(value);
+		length += addition;
+	}
+	const omitted = values.length - visible.length;
+	return `${visible.join(" · ")}${omitted > 0 ? ` · +${omitted}` : ""}`;
+}
+
+export function registerMainTools(pi: ExtensionAPI, manager: MainRunManager): void {
+	pi.registerTool({
+		name: "delegate",
+		label: "delegate",
+		exposure: "model-only",
+		description: "Create a fresh, context-isolated Sub Pi in Herdr, or resume a closed persistent Sub owned by this Main session. The Sub remains open until the Main calls close_sub or the user closes it manually.",
+		promptSnippet: "Create or resume a focused Sub Pi in Herdr with an explicit Pi Subagent profile",
+		promptGuidelines: [
+			"Use delegate for work assigned by MAIN.md or a separable task that benefits from an independent context; select an explicitly configured profile and provide a short informative title.",
+			"After delegate launches, do not wait or repeatedly poll. Pi Subagent will wake the Main when the Sub uses talk.",
+			"For Subs labeled user-invoked specialists, follow up only on the user's task and results. Do not assign unrelated work or substitute them for general consulting profiles. New tasks are initiated by the user through a profile command.",
+			"Use talk to respond to an existing Sub, interrupt_sub to stop its current turn without closing it, and close_sub only after its delivery is accepted or the user asks to close it.",
+		],
+		parameters: Type.Object({
+			title: Type.String({ description: "Short Herdr tab title, up to 48 displayed characters." }),
+			task: Type.String({ description: "Self-contained initial task. Do not assume the Sub can see the Main conversation." }),
+			profile: Type.String({ description: "Configured Pi Subagent profile name. Project profiles override same-named global profiles." }),
+			cwd: Type.Optional(Type.String({ description: "Sub working directory; defaults to the Main cwd and is ignored when resuming." })),
+			resumeSessionId: Type.Optional(Type.String({ description: "Exact or unique-prefix session ID of a closed persistent Sub owned by this Main; see list_sub." })),
+		}),
+		async execute(_id, params, signal, onUpdate, ctx) {
+			if (manager.runs.size >= MAX_OPEN_SUBS) throw new Error(`Pi Subagent allows at most ${MAX_OPEN_SUBS} open Subs.`);
+			const title = normalizeTitle(params.title);
+			const cwd = path.resolve(ctx.cwd, params.cwd ?? ".");
+			const profile = resolveToolExtensions(
+				resolveProfile(params.profile, ctx.cwd, ctx.isProjectTrusted(), { agentOnly: true }),
+				pi.getAllTools(),
+			);
+			const sessionPersistence = profile.sessionPersistence ?? "ephemeral";
+			const capabilityDetails = { tools: profile.tools, skills: profile.skills ?? [], sessionPersistence };
+			onUpdate?.({
+				content: [{ type: "text", text: `Creating Sub with profile ${profile.name}: ${title}` }],
+				details: { title, profile: profile.name, ...capabilityDetails },
+			});
+			const run = await manager.delegate({
+				title,
+				task: params.task,
+				cwd,
+				profile,
+				...(params.resumeSessionId ? { resumeSessionId: params.resumeSessionId } : {}),
+			}, signal);
+			return {
+				content: [{ type: "text", text: `${params.resumeSessionId ? "Resumed" : "Created"} Sub: ${run.title} (profile ${run.profileName}, run ${run.runId.slice(0, 8)}${run.subSessionId ? `, session ${run.subSessionId}` : ""}).` }],
+				details: {
+					runId: run.runId,
+					title: run.title,
+					profile: run.profileName,
+					adapter: run.surface?.adapter,
+					...capabilityDetails,
+				},
+				terminate: true,
+			};
+		},
+		renderCall(args, theme) {
+			const title = normalizeTitle(args.title ?? "delegated task");
+			const action = args.resumeSessionId ? "resume" : "delegate";
+			return new Text(`${theme.fg("toolTitle", theme.bold(action))} ${theme.fg("muted", `· ${title}`)}`, 0, 0);
+		},
+		renderResult(result, { isPartial }, theme, context) {
+			if (context.isError) {
+				const message = result.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+				return new Text(theme.fg("error", message || "delegate failed"), 0, 0);
+			}
+			const details = result.details as {
+				title?: string;
+				profile?: string;
+				adapter?: string;
+				tools?: string[];
+				skills?: string[];
+				sessionPersistence?: string;
+			} | undefined;
+			const icon = isPartial ? theme.fg("warning", "◌") : theme.fg("success", "✓");
+			const summary = `${icon} ${theme.fg("accent", details?.title ?? "sub")} ${theme.fg("muted", `· ${details?.profile ?? "profile?"} · ${details?.sessionPersistence ?? "ephemeral"}${details?.adapter ? ` · ${details.adapter}` : ""}`)}`;
+			const tools = `${theme.fg("dim", "  tools ")}${theme.fg("muted", compactCapabilityList(details?.tools ?? []))}`;
+			const skills = `${theme.fg("dim", "  skills")}${theme.fg("muted", ` ${compactCapabilityList(details?.skills ?? [])}`)}`;
+			return new Text(`${summary}\n${tools}\n${skills}`, 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "talk",
+		label: "talk",
+		description: "Send one message to an existing Sub Pi. Messages enter the Sub's native follow-up queue and are processed after its current work. Format non-trivial messages as readable Markdown with paragraph breaks and lists.",
+		promptSnippet: "Send a message to an existing Sub Pi",
+		executionMode: "sequential",
+		parameters: Type.Object({
+			runId: Type.String({ description: "Full Sub run ID or a unique prefix." }),
+			message: Type.String({ description: "Message to the other Agent. For non-trivial content, use readable Markdown with paragraph breaks and lists." }),
+		}),
+		renderCall(args, theme, context) {
+			const message = typeof args.message === "string" ? args.message : "";
+			const title = findSubTitle(manager, args.runId);
+			const suffix = title ? ` ${theme.fg("muted", `· ${title}`)}` : "";
+			const view = talkView(message, context.expanded);
+			let text = `${theme.fg("accent", "›")} ${theme.fg("toolTitle", theme.bold("message send"))}${suffix}`;
+			if (message) 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)`);
+			}
+			return new Text(text, 0, 0);
+		},
+		async execute(_id, params) {
+			const { run, messageId } = manager.talk(params.runId, params.message);
+			return {
+				content: [{ type: "text", text: `Message queued for Sub: ${run.title}` }],
+				details: { runId: run.runId, messageId },
+			};
+		},
+		renderResult(_result, _options, theme, context) {
+			if (context.isError) return new Text(theme.fg("error", "\ntalk failed"), 0, 0);
+			return new Container();
+		},
+	});
+
+	pi.registerTool({
+		name: "interrupt_sub",
+		label: "interrupt sub",
+		description: "Request cancellation of an open Sub's current turn, including a running tool call, without closing its session or Herdr tab. If the tool ignores cancellation, the Sub may remain busy; use close_sub only if closure is intended.",
+		parameters: Type.Object({
+			runId: Type.String({ description: "Full Sub run ID or a unique prefix." }),
+		}),
+		renderCall(args, theme, context) {
+			const state = context.state as { title?: string };
+			state.title ??= findSubTitle(manager, args.runId);
+			return new Text(`${theme.fg("toolTitle", theme.bold("interrupt"))} ${theme.fg("muted", `· ${state.title ?? "sub"}`)}`, 0, 0);
+		},
+		async execute(_id, params) {
+			const run = manager.interrupt(params.runId);
+			return { content: [{ type: "text", text: `Requested interruption of Sub: ${run.title}. The Sub session remains open.` }], details: { runId: run.runId } };
+		},
+		renderResult(_result, _options, theme, context) {
+			if (context.isError) return new Text(theme.fg("error", "\ninterrupt failed"), 0, 0);
+			return new Container();
+		},
+	});
+
+	pi.registerTool({
+		name: "close_sub",
+		label: "close sub",
+		description: "Close a Sub Pi session and its Herdr tab. Use after the delivery is accepted or when the user asks to close it.",
+		parameters: Type.Object({
+			runId: Type.String({ description: "Full Sub run ID or a unique prefix." }),
+			reason: Type.Optional(Type.String({ description: "Reason for closing the Sub session." })),
+		}),
+		renderCall(args, theme, context) {
+			const state = context.state as { title?: string };
+			state.title ??= findSubTitle(manager, args.runId);
+			return new Text(`${theme.fg("toolTitle", theme.bold("close"))} ${theme.fg("muted", `· ${state.title ?? "sub"}`)}`, 0, 0);
+		},
+		async execute(_id, params) {
+			const run = await manager.close(params.runId, params.reason ?? "The Main closed the Sub session.");
+			return { content: [{ type: "text", text: `Closed Sub: ${run.title}` }], details: { runId: run.runId } };
+		},
+		renderResult(_result, _options, theme, context) {
+			if (context.isError) return new Text(theme.fg("error", "\nclose failed"), 0, 0);
+			return new Container();
+		},
+	});
+
+	pi.registerTool({
+		name: "list_sub",
+		label: "Sub-agents",
+		description: "List only this Main session's Sub-agents: all open Subs, regardless of status, and confirmed-closed persistent sessions that can be resumed. Shows live Herdr status; never returns transcripts or other Mains' sessions.",
+		parameters: Type.Object({}),
+		async execute() {
+			const now = Date.now();
+			const listed = await manager.subs();
+			const open = listed.open.map(({ run, status }) => ({
+				runId: run.runId,
+				subSessionId: run.subSessionId,
+				title: run.title,
+				profile: run.profileName,
+				sessionPersistence: run.sessionPersistence,
+				origin: run.origin,
+				purpose: run.purpose,
+				status,
+				adapter: run.surface?.adapter,
+				elapsedSeconds: Math.max(0, Math.round((now - run.createdAt) / 1000)),
+			}));
+			const resumable = listed.resumable.map((session) => ({
+				...session,
+				modifiedSecondsAgo: Math.max(0, Math.round((now - session.modifiedAt) / 1000)),
+			}));
+			const lines = [
+				...(open.length ? ["Open"] : []),
+				...open.map((run) => `- ${run.status} ${run.runId.slice(0, 8)} ${run.title} <${run.profile}, ${run.sessionPersistence}${run.origin === "manual" ? ", user-invoked specialist" : ""}>${run.purpose ? ` Purpose: ${run.purpose}` : ""}`),
+				...(resumable.length ? ["Resumable"] : []),
+				...resumable.map((session) => `- closed ${session.sessionId} ${session.title} <persistent, ${session.origin === "manual" ? "user-invoked; resume via user command" : "resumable"}> cwd=${session.cwd}${session.purpose ? ` Purpose: ${session.purpose}` : ""}`),
+			];
+			if (open.some((run) => run.origin === "manual") || resumable.some((session) => session.origin === "manual")) lines.push(MANUAL_MAIN_GUIDANCE);
+			return { content: [{ type: "text", text: lines.join("\n") || "No Sub-agents in this Main session." }], details: { open, resumable } };
+		},
+		renderCall(_args, theme) {
+			return new Text(theme.fg("toolTitle", theme.bold("Sub-agents")), 0, 0);
+		},
+		renderResult(result, _options, theme) {
+			const details = result.details as {
+				open?: Array<{
+					runId: string;
+					subSessionId?: string;
+					title: string;
+					profile: string;
+					sessionPersistence: string;
+					origin?: "manual";
+					status: SubAgentStatus;
+					adapter?: string;
+					elapsedSeconds: number;
+				}>;
+				resumable?: Array<{
+					sessionId: string;
+					title: string;
+					cwd: string;
+					modifiedSecondsAgo: number;
+					origin?: "manual";
+				}>;
+			} | undefined;
+			const open = details?.open ?? [];
+			const resumable = details?.resumable ?? [];
+			if (open.length === 0 && resumable.length === 0) return new Text(theme.fg("muted", "No Sub-agents in this Main session"), 0, 0);
+			const lines = [
+				...(open.length ? [theme.fg("toolTitle", theme.bold("Open"))] : []),
+				...open.map((run) => {
+					const metadata = [
+						run.runId.slice(0, 8),
+						run.subSessionId?.slice(0, 8),
+						run.profile,
+						run.origin === "manual" ? "user-invoked specialist" : undefined,
+						run.sessionPersistence,
+						run.status,
+						run.adapter,
+						formatElapsed(run.elapsedSeconds),
+					].filter(Boolean).join(" · ");
+					return `${theme.fg("accent", "•")} ${theme.fg("accent", run.title)}\n  ${theme.fg("muted", metadata)}`;
+				}),
+				...(resumable.length ? [theme.fg("toolTitle", theme.bold("Resumable"))] : []),
+				...resumable.map((session) => {
+					const metadata = [
+						session.sessionId.slice(0, 8),
+						"persistent",
+						session.origin === "manual" ? "closed · user-invoked" : "closed · resumable",
+						path.basename(session.cwd),
+						formatElapsed(session.modifiedSecondsAgo),
+					].join(" · ");
+					return `${theme.fg("dim", "○")} ${theme.fg("accent", session.title)}\n  ${theme.fg("muted", metadata)}`;
+				}),
+			];
+			return new Text(lines.join("\n\n"), 0, 0);
+		},
+	});
+}

package/src/tools/sub.ts

@@ -0,0 +1,215 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import {
+	listTalkToSub,
+	MESSAGE_TYPE,
+	clearActiveTurn,
+	clearInterrupt,
+	readActiveTurn,
+	readInterrupt,
+	readClose,
+	readManifest,
+	talkToMain,
+	writeSubClosed,
+	writeSubSessionInfo,
+	writeActiveTurn,
+} from "../channel.js";
+import { applySubPromptSections, bindPromptSections } from "../profiles/system-prompt.js";
+import { SUB_CONTROL_TOOLS } from "../profiles/launch-args.js";
+import { applyProfileTools } from "../profiles/tool-selection.js";
+import { MANUAL_SUB_GUIDANCE, subSessionName } from "../manual-context.js";
+import { talkView } from "../talk-render.js";
+import { ChannelMonitor } from "../channel-monitor.js";
+import { bindInboxEvents } from "../inbox-state.js";
+import { deliverTalk, ProtocolErrors } from "../talk-delivery.js";
+import type { ActiveTurn, DelegateManifest } from "../types.js";
+
+function contentText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => part && typeof part === "object" && "text" in part ? String(part.text) : "")
+		.filter(Boolean)
+		.join("\n");
+}
+
+function loadManifest(): { channelDir: string; manifest: DelegateManifest } {
+	const channelDir = process.env.PI_SUBAGENT_CHANNEL;
+	const envToken = process.env.PI_SUBAGENT_TOKEN;
+	if (!channelDir) throw new Error("PI_SUBAGENT_CHANNEL is missing in Sub Pi.");
+	const manifest = readManifest(channelDir);
+	if (!envToken || envToken !== manifest.token) throw new Error("Sub channel capability token does not match.");
+	return { channelDir, manifest };
+}
+
+export function registerSub(pi: ExtensionAPI): void {
+	const loaded = loadManifest();
+	const selectedTools = [...new Set([...loaded.manifest.profile.tools, ...SUB_CONTROL_TOOLS])];
+	const protocolErrors = new ProtocolErrors();
+	let closing = false;
+	let activeTurn: ActiveTurn | undefined;
+	let inputSeen = false;
+	let activeContext: ExtensionContext | undefined;
+	let ready = false;
+	const monitor = new ChannelMonitor(
+		() => scan(),
+		(_id, error) => {
+			if (activeContext) protocolErrors.report(activeContext, `watch:${loaded.manifest.runId}`, new Error(`File watching unavailable; the 5-second scan remains active. ${error instanceof Error ? error.message : String(error)}`));
+		},
+		() => protocolErrors.clear(`watch:${loaded.manifest.runId}`),
+	);
+	bindInboxEvents(pi, () => activeContext, () => monitor.wakeAll());
+
+	// Pi emits resource discovery after all session_start handlers, including
+	// extensions that register the profile's tools dynamically during startup.
+	pi.on("resources_discover", (_event, ctx) => {
+		try {
+			applyProfileTools(pi, loaded.manifest.profile.name, selectedTools);
+			ready = true;
+			monitor.wakeAll();
+		} catch (error) {
+			const reason = `Unable to initialize Sub profile: ${error instanceof Error ? error.message : String(error)}`;
+			talkToMain(loaded.channelDir, loaded.manifest, reason);
+			ctx.shutdown();
+		}
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		activeContext = ctx;
+		pi.setSessionName(subSessionName(loaded.manifest.title, loaded.manifest.origin));
+		ctx.ui.setTitle(`[sub] ${loaded.manifest.title}`);
+		ctx.ui.setStatus("subagent", `sub · ${loaded.manifest.profile.name}`);
+		const sessionFile = ctx.sessionManager.getSessionFile();
+		if (loaded.manifest.profile.sessionPersistence === "persistent" && sessionFile) {
+			writeSubSessionInfo(loaded.channelDir, loaded.manifest, {
+				sessionId: ctx.sessionManager.getSessionId(),
+				sessionFile,
+			});
+		}
+		const previousTurn = readActiveTurn(loaded.channelDir, loaded.manifest);
+		if (ctx.isIdle() && previousTurn) clearActiveTurn(loaded.channelDir, previousTurn);
+		activeTurn = ctx.isIdle() ? undefined : previousTurn;
+		monitor.add(loaded.manifest.runId, loaded.channelDir, "to-sub");
+		monitor.start();
+		scan();
+	});
+
+	function scan(): void {
+		const ctx = activeContext;
+		if (!ctx || closing) return;
+		try {
+			if (readClose(loaded.channelDir, loaded.manifest)) {
+				closing = true;
+				monitor.stop();
+				ctx.abort();
+				ctx.shutdown();
+				return;
+			}
+			const interrupt = readInterrupt(loaded.channelDir, loaded.manifest);
+			if (interrupt) {
+				clearInterrupt(loaded.channelDir);
+				if (!ctx.isIdle() && interrupt.turnId === activeTurn?.turnId) ctx.abort();
+			}
+			if (!ready) return;
+			for (const message of listTalkToSub(loaded.channelDir, loaded.manifest)) {
+				deliverTalk(pi, ctx, loaded.channelDir, loaded.manifest, "to-sub", message,
+					`[Pi Subagent Main message]\nMain says:\n${message.message}`);
+			}
+			protocolErrors.clear(loaded.manifest.runId);
+		} catch (error) {
+			protocolErrors.report(ctx, loaded.manifest.runId, error);
+		}
+	}
+
+	pi.on("agent_start", () => {
+		if (closing) return;
+		inputSeen = false;
+		activeTurn = writeActiveTurn(loaded.channelDir, loaded.manifest);
+	});
+
+	pi.on("message_start", (event) => {
+		const message = event.message;
+		const mainInput = message.role === "custom" && message.customType === MESSAGE_TYPE
+			&& (message.details as { direction?: string } | undefined)?.direction === "to-sub";
+		// Native follow-ups can start new work inside one agent run. A late
+		// interrupt for the previous input must not abort that subsequent work.
+		if (!closing && (message.role === "user" || mainInput)) {
+			if (inputSeen) activeTurn = writeActiveTurn(loaded.channelDir, loaded.manifest);
+			inputSeen = true;
+		}
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (ctx.isIdle() && activeTurn) {
+			clearActiveTurn(loaded.channelDir, activeTurn);
+			activeTurn = undefined;
+		}
+	});
+
+	bindPromptSections(pi, ["subagent_sub_protocol", "subagent_profile"], () => {
+		const sections: Record<string, string> = {};
+		applySubPromptSections(sections, loaded.manifest.profile);
+		if (loaded.manifest.origin === "manual") sections.subagent_sub_protocol += `\n\n${MANUAL_SUB_GUIDANCE}`;
+		return sections;
+	});
+
+	// 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 ?? loaded.manifest.title;
+		const mainMessage = details?.message ?? "";
+		const view = talkView(mainMessage, options.expanded);
+		let text = `${theme.fg("accent", "›")} ${theme.fg("toolTitle", theme.bold("message inbox"))} ${theme.fg("muted", `· ${title}`)}`;
+		if (mainMessage) 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.registerTool({
+		name: "talk",
+		label: "talk",
+		exposure: "model-only",
+		description: "Send one message to the Main Pi and end the current turn. Use it to ask for information or deliver work. Format non-trivial messages as readable Markdown with paragraph breaks and lists.",
+		promptSnippet: "Send a message to the Main Pi",
+		promptGuidelines: ["Use talk whenever the Sub needs to communicate with the Main; the Main decides when to close the Sub session."],
+		executionMode: "sequential",
+		parameters: Type.Object({
+			message: Type.String({ description: "Message to the other Agent. For non-trivial content, use readable Markdown with paragraph breaks and lists." }),
+		}),
+		renderCall(args, theme, context) {
+			const message = typeof args.message === "string" ? args.message : "";
+			const view = talkView(message, context.expanded);
+			let text = `${theme.fg("accent", "›")} ${theme.fg("toolTitle", theme.bold("message send"))} ${theme.fg("muted", `· ${loaded.manifest.title}`)}`;
+			if (message) 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)`);
+			}
+			return new Text(text, 0, 0);
+		},
+		async execute(_id, params) {
+			const message = talkToMain(loaded.channelDir, loaded.manifest, params.message);
+			return {
+				content: [{ type: "text", text: "Message queued for the Main Pi." }],
+				details: { messageId: message.id },
+				terminate: true,
+			};
+		},
+		renderResult(result, _options, theme, context) {
+			if (context.isError) return new Text(`\n${theme.fg("error", contentText(result.content) || "talk failed")}`, 0, 0);
+			return new Container();
+		},
+	});
+
+	pi.on("session_shutdown", (event) => {
+		monitor.stop();
+		activeContext = undefined;
+		if (event.reason === "quit" && !closing && !readClose(loaded.channelDir, loaded.manifest)) {
+			writeSubClosed(loaded.channelDir, loaded.manifest, "The Sub session was closed manually.");
+		}
+	});
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+import type { ResolvedProfile, SessionPersistence } from "./profiles/types.js";
+
+export interface DelegateManifest {
+	version: 1;
+	runId: string;
+	mainSessionId: string;
+	title: string;
+	task: string;
+	cwd: string;
+	profile: ResolvedProfile;
+	origin?: "manual";
+	token: string;
+	createdAt: number;
+}
+
+export interface TalkMessage {
+	version: 1;
+	id: string;
+	sequence: number;
+	runId: string;
+	token: string;
+	createdAt: number;
+	message: string;
+}
+
+export interface SubSessionInfo {
+	version: 1;
+	runId: string;
+	token: string;
+	sessionId: string;
+	sessionFile: string;
+	createdAt: number;
+}
+
+export interface ActiveTurn {
+	version: 1;
+	runId: string;
+	token: string;
+	turnId: string;
+	createdAt: number;
+}
+
+export interface InterruptRequest extends ActiveTurn {
+	requestedAt: number;
+}
+
+export interface CloseMessage {
+	version: 1;
+	runId: string;
+	token: string;
+	createdAt: number;
+	reason: string;
+}
+
+export interface SubClosedMessage {
+	version: 1;
+	runId: string;
+	token: string;
+	createdAt: number;
+	reason: string;
+}
+
+export type SubAgentStatus = "working" | "blocked" | "idle" | "unknown";
+
+export interface SurfaceHandle {
+	adapter: "herdr";
+	tabId?: string;
+	paneId?: string;
+}
+
+export interface RunSnapshot {
+	version: 1;
+	runId: string;
+	mainSessionId: string;
+	title: string;
+	cwd: string;
+	profileName: string;
+	origin?: "manual";
+	purpose?: string;
+	sessionPersistence: SessionPersistence;
+	channelDir: string;
+	createdAt: number;
+	updatedAt: number;
+	/** Surface is closed; retain the channel only until pending messages are received. */
+	closedAt?: number;
+	subSessionId?: string;
+	subSessionFile?: string;
+	surface?: SurfaceHandle;
+}
+
+export interface SubLaunchSpec {
+	runId: string;
+	mainSessionId: string;
+	title: string;
+	task: string;
+	cwd: string;
+	projectTrusted: boolean;
+	origin?: "manual";
+	resumeSessionId?: string;
+	profile: ResolvedProfile;
+	channelDir: string;
+	token: string;
+	entryPath: string;
+}
+
+export interface SubSurfaceAdapter {
+	readonly id: "herdr";
+	available(): Promise<boolean>;
+	launch(spec: SubLaunchSpec, signal?: AbortSignal): Promise<SurfaceHandle>;
+	close(handle: SurfaceHandle): Promise<void>;
+}