@oldflag2333333/pi-subagent 0.0.0-stage → 0.1.0

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.0",
+  "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,155 @@
+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 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 ? [] : ["--no-session"]),
+		...(spec.resumeSessionId ? ["--session", 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);
+	}
+}

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 });
+}