@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/shared/post-exit-stdio-guard.ts

@@ -1,204 +1,264 @@
 import { execFileSync, type ChildProcess } from "node:child_process";
 import { readLinuxProcess } from "../pi-intercom/broker/pid.ts";
 import type { AgentProcessExit } from "./types.ts";
-
-interface PostExitStdioGuardOptions {
-	idleMs: number;
-	hardMs: number;
-}
+import { hasErrorCode } from "./unknown.ts";
 
 interface ChildWithPipedStdio {
-	stdout: ChildProcess["stdout"];
-	stderr: ChildProcess["stderr"];
-	on: ChildProcess["on"];
+  readonly stdout: ChildProcess["stdout"];
+  readonly stderr: ChildProcess["stderr"];
+  readonly on: ChildProcess["on"];
 }
 
 interface ChildWithKill {
-	pid?: number;
-	kill(signal?: NodeJS.Signals | number): boolean;
+  readonly pid?: number;
+  readonly kill: (signal?: NodeJS.Signals | number) => boolean;
 }
 
 /** Capture the detached group leader's birth identity; Pi may replace its command-line title. */
 export function readChildProcessIdentity(pid: number): string | undefined {
-	if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
-	if (process.platform === "linux") return readLinuxProcess(pid)?.identity;
-	try {
-		const identity = execFileSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "pgid="], {
-			encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"],
-			env: { ...process.env, LC_ALL: "C" },
-		}).trim().replace(/\s+/g, " ");
-		return Number(identity.split(" ").at(-1)) === pid ? identity : undefined;
-	} catch {
-		return undefined;
-	}
+  if (!Number.isSafeInteger(pid) || pid <= 0) {
+    return undefined;
+  }
+  if (process.platform === "linux") {
+    return readLinuxProcess(pid)?.identity;
+  }
+  try {
+    const identity = execFileSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "pgid="], {
+      encoding: "utf8",
+      timeout: 1000,
+      stdio: ["ignore", "pipe", "ignore"],
+      env: { ...process.env, LC_ALL: "C" },
+    })
+      .trim()
+      .replace(/\s+/g, " ");
+    return Number(identity.split(" ").at(-1)) === pid ? identity : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
-export function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
-	try {
-		return child.kill(signal);
-	} catch {
-		return false;
-	}
+function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
+  try {
+    return child.kill(signal);
+  } catch {
+    return false;
+  }
 }
 
 export function isChildTreeAlive(child: ChildWithKill): boolean {
-	if (child.pid) {
-		try {
-			process.kill(-child.pid, 0);
-			return true;
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === "EPERM") return true;
-		}
-	}
-	try {
-		return child.kill(0);
-	} catch {
-		return false;
-	}
+  if (child.pid !== undefined && child.pid !== 0) {
+    try {
+      process.kill(-child.pid, 0);
+      return true;
+    } catch (error) {
+      if (hasErrorCode(error, "EPERM")) {
+        return true;
+      }
+    }
+  }
+  try {
+    return child.kill(0);
+  } catch {
+    return false;
+  }
 }
 
 /** Signal the detached child's process group, falling back if it is not a group leader. */
 export function trySignalChildTree(child: ChildWithKill, signal: NodeJS.Signals): boolean {
-	if (child.pid) {
-		try {
-			process.kill(-child.pid, signal);
-			return true;
-		} catch {
-			// Fall back when the child is not a process-group leader.
-		}
-	}
-	return trySignalChild(child, signal);
+  if (child.pid !== undefined && child.pid !== 0) {
+    try {
+      process.kill(-child.pid, signal);
+      return true;
+    } catch {
+      // Fall back when the child is not a process-group leader.
+    }
+  }
+  return trySignalChild(child, signal);
 }
 
+/** Process-group settlement, cancellation, and descendant cleanup have one owner. */
+interface ChildProcessLifecycle {
+  readonly terminate: () => void;
+  readonly stopping: boolean;
+  readonly agentProcessExit: AgentProcessExit | undefined;
+  readonly settledCleanup: boolean;
+  readonly observeEvent: (type: string | undefined) => void;
+}
+function activityEvent(type: string | undefined): boolean {
+  return (
+    type === "agent_start" ||
+    type === "turn_start" ||
+    type?.startsWith("message_") === true ||
+    type?.startsWith("tool_execution_") === true
+  );
+}
+class OwnedChildLifecycle implements ChildProcessLifecycle {
+  private closed = false;
+  private exited = false;
+  private isStopping = false;
+  private isSettledCleanup = false;
+  private exit?: AgentProcessExit;
+  private drainTimer?: NodeJS.Timeout;
+  private escalationTimer?: NodeJS.Timeout;
+  private readonly child: ChildWithPipedStdio & ChildWithKill;
+  private readonly clearStdioGuard: () => void;
+  constructor(child: ChildWithPipedStdio & ChildWithKill) {
+    this.child = child;
+    this.clearStdioGuard = attachPostExitStdioGuard(child);
+    child.on("exit", (code, signal) => {
+      this.exited = true;
+      this.exit = { pid: child.pid, code, signal, at: Date.now() };
+      this.clearTimers();
+      // The leader may exit before resistant descendants release inherited stdio.
+      trySignalChildTree(child, "SIGKILL");
+    });
+    child.on("close", () => {
+      this.dispose();
+    });
+    child.on("error", () => {
+      this.dispose();
+    });
+  }
+  private clearDrain(): void {
+    clearTimeout(this.drainTimer);
+    this.drainTimer = undefined;
+  }
+  private clearTimers(): void {
+    this.clearDrain();
+    clearTimeout(this.escalationTimer);
+    this.escalationTimer = undefined;
+  }
+  private signalTree(): boolean {
+    // Pi print mode uses SIGTERM to dispose its own detached tool processes.
+    const sent = trySignalChildTree(this.child, "SIGTERM");
+    this.escalationTimer = setTimeout(() => {
+      if (isChildTreeAlive(this.child)) {
+        trySignalChildTree(this.child, "SIGKILL");
+      }
+    }, 3000);
+    this.escalationTimer.unref();
+    return sent;
+  }
+  readonly terminate = (): void => {
+    // Cancellation overrides pending or already-started successful settlement cleanup.
+    this.isSettledCleanup = false;
+    this.clearDrain();
+    if (!this.closed && !this.isStopping) {
+      this.isStopping = true;
+      this.signalTree();
+    }
+  };
+  private dispose(): void {
+    this.closed = true;
+    this.clearTimers();
+    this.clearStdioGuard();
+  }
+  get stopping(): boolean {
+    return this.isStopping;
+  }
+  get agentProcessExit(): AgentProcessExit | undefined {
+    return this.exit;
+  }
+  get settledCleanup(): boolean {
+    return this.isSettledCleanup;
+  }
+  readonly observeEvent = (type: string | undefined): void => {
+    if (this.closed || this.exited || this.isStopping) {
+      return;
+    }
+    if (type === "agent_settled") {
+      if (this.drainTimer) {
+        return;
+      }
+      this.drainTimer = setTimeout(() => {
+        this.drainTimer = undefined;
+        this.isStopping = true;
+        this.isSettledCleanup = this.signalTree();
+      }, 1000);
+      this.drainTimer.unref();
+    } else if (activityEvent(type)) {
+      this.clearDrain();
+    }
+  };
+}
 /** One lifetime for the owned process group, including descendants holding its pipes open. */
-export function attachChildProcessLifecycle(child: ChildWithPipedStdio & ChildWithKill) {
-	let closed = false;
-	let exited = false;
-	let stopping = false;
-	let settledCleanup = false;
-	let agentProcessExit: AgentProcessExit | undefined;
-	let drainTimer: NodeJS.Timeout | undefined;
-	let escalationTimer: NodeJS.Timeout | undefined;
-	const clearDrain = () => {
-		clearTimeout(drainTimer);
-		drainTimer = undefined;
-	};
-	const clearTimers = () => {
-		clearDrain();
-		clearTimeout(escalationTimer);
-		escalationTimer = undefined;
-	};
-	const signalTree = () => {
-		// Pi print mode uses SIGTERM to dispose its own detached tool processes.
-		const sent = trySignalChildTree(child, "SIGTERM");
-		escalationTimer = setTimeout(() => {
-			if (isChildTreeAlive(child)) trySignalChildTree(child, "SIGKILL");
-		}, 3000);
-		escalationTimer.unref();
-		return sent;
-	};
-	const terminate = () => {
-		// Cancellation overrides a pending or already-started successful settlement cleanup.
-		settledCleanup = false;
-		clearDrain();
-		if (closed || stopping) return;
-		stopping = true;
-		signalTree();
-	};
-	const clearStdioGuard = attachPostExitStdioGuard(child, { idleMs: 2000, hardMs: 8000 });
-	child.on("exit", (code, signal) => {
-		exited = true;
-		agentProcessExit = { pid: child.pid, code, signal, at: Date.now() };
-		clearTimers();
-		// The leader may exit before resistant descendants release inherited stdio.
-		trySignalChildTree(child, "SIGKILL");
-	});
-	const dispose = () => {
-		closed = true;
-		clearTimers();
-		clearStdioGuard();
-	};
-	child.on("close", dispose);
-	child.on("error", dispose);
-	return {
-		terminate,
-		get stopping() { return stopping; },
-		get agentProcessExit() { return agentProcessExit; },
-		get settledCleanup() { return settledCleanup; },
-		observeEvent(type: string | undefined) {
-			if (closed || exited || stopping) return;
-			if (type === "agent_settled") {
-				if (drainTimer) return;
-				drainTimer = setTimeout(() => {
-					drainTimer = undefined;
-					stopping = true;
-					settledCleanup = signalTree();
-				}, 1000);
-				drainTimer.unref();
-			} else if (type === "agent_start" || type === "turn_start" || type?.startsWith("message_") || type?.startsWith("tool_execution_")) {
-				clearDrain();
-			}
-		},
-	};
+export function attachChildProcessLifecycle(
+  child: ChildWithPipedStdio & ChildWithKill,
+): ChildProcessLifecycle {
+  return new OwnedChildLifecycle(child);
 }
 
-export function attachPostExitStdioGuard(
-	child: ChildWithPipedStdio,
-	options: PostExitStdioGuardOptions,
-): () => void {
-	const { idleMs, hardMs } = options;
-	let exited = false;
-	let stdoutEnded = false;
-	let stderrEnded = false;
-	let idleTimer: NodeJS.Timeout | undefined;
-	let hardTimer: NodeJS.Timeout | undefined;
+function attachPostExitStdioGuard(child: ChildWithPipedStdio): () => void {
+  let exited = false;
+  let stdoutEnded = false;
+  let stderrEnded = false;
+  let idleTimer: NodeJS.Timeout | undefined;
+  let hardTimer: NodeJS.Timeout | undefined;
 
-	const destroyUnendedStdio = () => {
-		if (!stdoutEnded) {
-			try { child.stdout?.destroy(); } catch {}
-		}
-		if (!stderrEnded) {
-			try { child.stderr?.destroy(); } catch {}
-		}
-	};
+  const destroyUnendedStdio = () => {
+    if (!stdoutEnded) {
+      try {
+        child.stdout?.destroy();
+      } catch {
+        // The process has exited; failed pipe destruction must not prevent other cleanup.
+      }
+    }
+    if (!stderrEnded) {
+      try {
+        child.stderr?.destroy();
+      } catch {
+        // The process has exited; failed pipe destruction must not prevent other cleanup.
+      }
+    }
+  };
 
-	const clearTimers = () => {
-		if (idleTimer) {
-			clearTimeout(idleTimer);
-			idleTimer = undefined;
-		}
-		if (hardTimer) {
-			clearTimeout(hardTimer);
-			hardTimer = undefined;
-		}
-	};
+  const clearTimers = () => {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = undefined;
+    }
+    if (hardTimer) {
+      clearTimeout(hardTimer);
+      hardTimer = undefined;
+    }
+  };
 
-	const armIdleTimer = () => {
-		if (!exited) return;
-		if (idleTimer) clearTimeout(idleTimer);
-		idleTimer = setTimeout(destroyUnendedStdio, idleMs);
-		idleTimer.unref?.();
-	};
+  const armIdleTimer = () => {
+    if (!exited) {
+      return;
+    }
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+    }
+    idleTimer = setTimeout(destroyUnendedStdio, 2000);
+    idleTimer.unref();
+  };
 
-	child.stdout?.on("data", armIdleTimer);
-	child.stderr?.on("data", armIdleTimer);
-	child.stdout?.on("end", () => {
-		stdoutEnded = true;
-		if (stdoutEnded && stderrEnded) clearTimers();
-	});
-	child.stderr?.on("end", () => {
-		stderrEnded = true;
-		if (stdoutEnded && stderrEnded) clearTimers();
-	});
-	child.on("exit", () => {
-		exited = true;
-		armIdleTimer();
-		if (hardTimer) return;
-		hardTimer = setTimeout(destroyUnendedStdio, hardMs);
-		hardTimer.unref?.();
-	});
-	child.on("close", clearTimers);
-	child.on("error", clearTimers);
+  child.stdout?.on("data", armIdleTimer);
+  child.stderr?.on("data", armIdleTimer);
+  child.stdout?.on("end", () => {
+    stdoutEnded = true;
+    if (stderrEnded) {
+      clearTimers();
+    }
+  });
+  child.stderr?.on("end", () => {
+    stderrEnded = true;
+    if (stdoutEnded) {
+      clearTimers();
+    }
+  });
+  child.on("exit", () => {
+    exited = true;
+    armIdleTimer();
+    if (hardTimer) {
+      return;
+    }
+    hardTimer = setTimeout(destroyUnendedStdio, 8000);
+    hardTimer.unref();
+  });
+  child.on("close", clearTimers);
+  child.on("error", clearTimers);
 
-	return clearTimers;
+  return clearTimers;
 }

package/src/shared/prompt-sections.ts

@@ -1,10 +1,16 @@
 import type { NormalizedBuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
 
-export function setPromptSection(options: NormalizedBuildSystemPromptOptions, name: string, content: string): void {
-	options.sections[name] = content;
-	// Pi projects an earlier exact override instead of sections. Preserve its content;
-	// this compatibility path replaces the leading prompt and cannot preserve its cache prefix.
-	if (options.forceSystemPrompt !== undefined) {
-		options.forceSystemPrompt += `\n\n<${name}>\n${content}\n</${name}>`;
-	}
+export function setPromptSection(
+  options: NormalizedBuildSystemPromptOptions,
+  name: string,
+  content: string,
+): void {
+  // Pi owns this mutable prompt-building options object. This SDK hook updates
+  // sections and its legacy exact override in place; callers observe the same object.
+  options.sections[name] = content;
+  // Pi projects an earlier exact override instead of sections. Preserve its content;
+  // this compatibility path replaces the leading prompt and cannot preserve its cache prefix.
+  if (options.forceSystemPrompt !== undefined) {
+    options.forceSystemPrompt += `\n\n<${name}>\n${content}\n</${name}>`;
+  }
 }

package/src/shared/session-entries.ts

@@ -1,49 +1,108 @@
 import type { SessionManager, SessionEntry } from "@earendil-works/pi-coding-agent";
 
-type EntrySource = Pick<SessionManager, "getEntries" | "getSessionId"> & Partial<Pick<SessionManager, "getSessionFile" | "getEntry" | "getLeafId" | "getEntryCount">>;
+type EntrySource = Pick<SessionManager, "getEntries" | "getSessionId"> &
+  Partial<Pick<SessionManager, "getSessionFile" | "getEntry" | "getLeafId" | "getEntryCount">>;
+interface Snapshot {
+  readonly manager: EntrySource;
+  readonly sessionId: string;
+  readonly file: string | null | undefined;
+  readonly count: number | undefined;
+}
 
-/** Follow append-only parent links; rescan when entries were replaced or appended off the active branch. */
+/** Follow append-only parent links; rescan after replacement or append off the active branch. */
 export class SessionEntryCursor {
-	private manager?: EntrySource;
-	private sessionId?: string;
-	private file?: string | null;
-	private known = new Map<string, SessionEntry>();
-	private anchor?: SessionEntry;
-
-	reset(): void {
-		this.manager = undefined;
-		this.known.clear();
-		this.anchor = undefined;
-	}
-
-	read(manager: EntrySource): { entries: SessionEntry[]; reset: boolean } {
-		const sessionId = manager.getSessionId(), file = manager.getSessionFile?.(), count = manager.getEntryCount?.();
-		let reset = this.manager !== manager || this.sessionId !== sessionId || this.file !== file
-			|| count !== undefined && count < this.known.size
-			|| Boolean(this.anchor && manager.getEntry && manager.getEntry(this.anchor.id) !== this.known.get(this.anchor.id));
-		let entries: SessionEntry[] | undefined;
-		if (!reset && count !== undefined && manager.getEntry && manager.getLeafId) {
-			const appended: SessionEntry[] = [], visited = new Set<string>();
-			let id = manager.getLeafId();
-			while (id && !this.known.has(id) && !visited.has(id)) {
-				visited.add(id);
-				const entry = manager.getEntry(id);
-				if (!entry) break;
-				appended.push(entry);
-				id = entry.parentId;
-			}
-			if (count === this.known.size + appended.length && (!id || this.known.has(id))) entries = appended.reverse();
-		}
-		if (!entries) {
-			const all = manager.getEntries();
-			entries = all.filter((entry) => !this.known.has(entry.id));
-			if (all.length !== this.known.size + entries.length
-				|| all.some((entry) => this.known.has(entry.id) && this.known.get(entry.id) !== entry)) reset = true;
-			if (reset) { this.known.clear(); entries = all; }
-		}
-		for (const entry of entries) this.known.set(entry.id, entry);
-		this.anchor = entries.at(-1) ?? (reset ? undefined : this.anchor);
-		this.manager = manager; this.sessionId = sessionId; this.file = file;
-		return { entries, reset };
-	}
+  private manager?: EntrySource;
+  private sessionId?: string;
+  private file?: string | null;
+  private readonly known = new Map<string, SessionEntry>();
+  private anchor?: SessionEntry;
+  reset(): void {
+    this.manager = undefined;
+    this.known.clear();
+    this.anchor = undefined;
+  }
+  private changed(snapshot: Snapshot): boolean {
+    if (
+      this.manager !== snapshot.manager ||
+      this.sessionId !== snapshot.sessionId ||
+      this.file !== snapshot.file
+    ) {
+      return true;
+    }
+    if (snapshot.count !== undefined && snapshot.count < this.known.size) {
+      return true;
+    }
+    return (
+      this.anchor !== undefined &&
+      snapshot.manager.getEntry !== undefined &&
+      snapshot.manager.getEntry(this.anchor.id) !== this.known.get(this.anchor.id)
+    );
+  }
+  private appendedBranch(
+    manager: EntrySource,
+  ): { entries: SessionEntry[]; tail: string | null } | undefined {
+    if (manager.getEntry === undefined || manager.getLeafId === undefined) {
+      return undefined;
+    }
+    const entries: SessionEntry[] = [];
+    const visited = new Set<string>();
+    let id = manager.getLeafId();
+    while (id !== null && id !== "" && !this.known.has(id) && !visited.has(id)) {
+      visited.add(id);
+      const entry = manager.getEntry(id);
+      if (!entry) {
+        break;
+      }
+      entries.push(entry);
+      id = entry.parentId;
+    }
+    return { entries, tail: id };
+  }
+  private appended(snapshot: Snapshot): SessionEntry[] | undefined {
+    if (snapshot.count === undefined) {
+      return undefined;
+    }
+    const branch = this.appendedBranch(snapshot.manager);
+    if (!branch) {
+      return undefined;
+    }
+    const { entries, tail } = branch;
+    const connects = tail === null || tail === "" || this.known.has(tail);
+    return snapshot.count === this.known.size + entries.length && connects
+      ? entries.reverse()
+      : undefined;
+  }
+  private rescan(
+    manager: EntrySource,
+    reset: boolean,
+  ): { entries: SessionEntry[]; reset: boolean } {
+    const all = manager.getEntries();
+    const added = all.filter((entry) => !this.known.has(entry.id));
+    const replaced =
+      all.length !== this.known.size + added.length ||
+      all.some((entry) => this.known.has(entry.id) && this.known.get(entry.id) !== entry);
+    return { entries: reset || replaced ? all : added, reset: reset || replaced };
+  }
+  read(manager: EntrySource): { entries: SessionEntry[]; reset: boolean } {
+    const snapshot: Snapshot = {
+      manager,
+      sessionId: manager.getSessionId(),
+      file: manager.getSessionFile?.(),
+      count: manager.getEntryCount?.(),
+    };
+    const changed = this.changed(snapshot);
+    const appended = changed ? undefined : this.appended(snapshot);
+    const result = appended ? { entries: appended, reset: false } : this.rescan(manager, changed);
+    if (result.reset) {
+      this.known.clear();
+    }
+    for (const entry of result.entries) {
+      this.known.set(entry.id, entry);
+    }
+    this.anchor = result.entries.at(-1) ?? (result.reset ? undefined : this.anchor);
+    this.manager = manager;
+    this.sessionId = snapshot.sessionId;
+    this.file = snapshot.file;
+    return result;
+  }
 }

package/src/shared/session-identity.ts

@@ -1,18 +1,25 @@
 interface SessionIdentityManager {
-	getSessionFile(): string | null | undefined;
-	getSessionId(): string | null | undefined;
+  readonly getSessionFile: () => string | null | undefined;
+  readonly getSessionId: () => string | null | undefined;
 }
 
 // Only delegation supplies this identity; Pi's ordinary fork/clone ancestry does not.
-export function resolveRootSessionId(sessionManager: SessionIdentityManager, env: NodeJS.ProcessEnv = process.env): string {
-	const rootId = env.PI_SUBAGENT_CHILD === "1" ? env.PI_SUBAGENT_ROOT_SESSION_ID : undefined;
-	const sessionId = rootId || sessionManager.getSessionId();
-	if (!sessionId) throw new Error("Root session identity is unavailable.");
-	return sessionId;
+export function resolveRootSessionId(
+  sessionManager: SessionIdentityManager,
+  env: Readonly<NodeJS.ProcessEnv> = process.env,
+): string {
+  const rootId = env.PI_SUBAGENT_CHILD === "1" ? env.PI_SUBAGENT_ROOT_SESSION_ID : undefined;
+  const sessionId = rootId !== undefined && rootId !== "" ? rootId : sessionManager.getSessionId();
+  if (sessionId === null || sessionId === undefined || sessionId === "") {
+    throw new Error("Root session identity is unavailable.");
+  }
+  return sessionId;
 }
 
 export function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string {
-	const sessionId = sessionManager.getSessionId();
-	if (!sessionId) throw new Error("Current session identity is unavailable.");
-	return sessionId;
+  const sessionId = sessionManager.getSessionId();
+  if (sessionId === null || sessionId === undefined || sessionId === "") {
+    throw new Error("Current session identity is unavailable.");
+  }
+  return sessionId;
 }