@oh-my-pi/pi-coding-agent 15.11.7 → 15.11.8

package/scripts/bench-guard.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+/**
+ * Boot-time regression guard (Phase A1 of the boot/TUI perf work).
+ *
+ * Re-runs the `PI_TIMING=x` cold-boot benchmark under hyperfine and fails when
+ * the median regresses past `baseline * THRESHOLD`. `PI_TIMING=x` runs the full
+ * pre-paint chain in `runRootCommand` and then `process.exit(0)`, so the
+ * never-exiting interactive launch becomes a terminating, benchmarkable boot.
+ *
+ * Boot wall-clock is MACHINE-RELATIVE: a baseline captured on one machine is
+ * meaningless on another (and on CI). This is a LOCAL guard — regenerate the
+ * baseline on the machine you measure on, then compare on that same machine.
+ * It is intentionally NOT wired into CI for that reason.
+ *
+ *   bun scripts/bench-guard.ts --update   # capture/refresh the baseline
+ *   bun scripts/bench-guard.ts            # measure + compare; exit 1 on regression
+ *
+ * Requires `hyperfine` on PATH.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const THRESHOLD = 1.05; // 5% regression budget
+const BASELINE_PATH = path.join(import.meta.dir, "..", "bench", "boot-baseline.json");
+const BENCH_COMMAND = "PI_TIMING=x bun src/cli.ts";
+const cwd = path.join(import.meta.dir, "..");
+
+function medianOf(hyperfineJson: string): number {
+	const parsed = JSON.parse(hyperfineJson) as { results: Array<{ mean: number; median?: number }> };
+	const result = parsed.results[0];
+	if (!result) throw new Error("hyperfine produced no result");
+	return result.median ?? result.mean;
+}
+
+async function measure(): Promise<{ seconds: number; raw: string }> {
+	const tmp = path.join(import.meta.dir, "..", "bench", `.boot-run-${Date.now()}.json`);
+	const proc = Bun.spawn(["hyperfine", "--warmup", "3", "--min-runs", "10", "--export-json", tmp, BENCH_COMMAND], {
+		cwd,
+		stdout: "inherit",
+		stderr: "inherit",
+	});
+	const code = await proc.exited;
+	if (code !== 0) throw new Error(`hyperfine exited ${code}`);
+	const raw = await Bun.file(tmp).text();
+	fs.rmSync(tmp, { force: true });
+	return { seconds: medianOf(raw), raw };
+}
+
+const update = process.argv.includes("--update");
+const { seconds, raw } = await measure();
+
+if (update) {
+	fs.mkdirSync(path.dirname(BASELINE_PATH), { recursive: true });
+	await Bun.write(BASELINE_PATH, raw);
+	console.log(`Baseline updated: ${(seconds * 1000).toFixed(0)}ms median -> ${BASELINE_PATH}`);
+	process.exit(0);
+}
+
+if (!fs.existsSync(BASELINE_PATH)) {
+	console.error("No baseline found. Run `bun scripts/bench-guard.ts --update` on this machine first.");
+	process.exit(2);
+}
+
+const baseline = medianOf(await Bun.file(BASELINE_PATH).text());
+const ratio = seconds / baseline;
+const verdict = ratio > THRESHOLD ? "REGRESSION" : "ok";
+console.log(
+	`boot median: ${(seconds * 1000).toFixed(0)}ms vs baseline ${(baseline * 1000).toFixed(0)}ms ` +
+		`(${((ratio - 1) * 100).toFixed(1)}%, budget ${((THRESHOLD - 1) * 100).toFixed(0)}%) -> ${verdict}`,
+);
+process.exit(ratio > THRESHOLD ? 1 : 0);

package/src/cli/args.ts

@@ -32,6 +32,8 @@ export interface Args {
 	sessionDir?: string;
 	providerSessionId?: string;
 	fork?: string;
+	/** Collab link to join at startup (set by the `join` subcommand; no CLI flag). */
+	join?: string;
 	models?: string[];
 	tools?: string[];
 	noTools?: boolean;

package/src/cli-commands.ts

@@ -26,6 +26,7 @@ export const commands: CommandEntry[] = [
 	{ name: "gallery", load: () => import("./commands/gallery").then(m => m.default) },
 	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
 	{ name: "install", load: () => import("./commands/install").then(m => m.default) },
+	{ name: "join", load: () => import("./commands/join").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
 	{ name: "shell", load: () => import("./commands/shell").then(m => m.default) },

package/src/collab/crypto.ts

@@ -0,0 +1,57 @@
+/**
+ * AES-256-GCM sealing for collab frames.
+ *
+ * The room key lives only in the link fragment; the relay sees opaque bytes.
+ * Sealed layout: `[12B IV][ciphertext+tag]`.
+ */
+import type { CollabFrame } from "./protocol";
+
+const AES_ALGORITHM = "AES-GCM";
+const IV_LENGTH = 12;
+const KEY_LENGTH = 32;
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder();
+
+export function generateRoomKey(): Uint8Array {
+	const key = new Uint8Array(KEY_LENGTH);
+	crypto.getRandomValues(key);
+	return key;
+}
+
+export function importRoomKey(raw: Uint8Array): Promise<CryptoKey> {
+	if (raw.byteLength !== KEY_LENGTH) {
+		throw new Error(`Room key must be ${KEY_LENGTH} bytes, got ${raw.byteLength}`);
+	}
+	return crypto.subtle.importKey("raw", asStrict(raw), AES_ALGORITHM, false, ["encrypt", "decrypt"]);
+}
+
+export async function seal(key: CryptoKey, frame: CollabFrame): Promise<Uint8Array> {
+	const iv = new Uint8Array(IV_LENGTH);
+	crypto.getRandomValues(iv);
+	const plaintext = TEXT_ENCODER.encode(JSON.stringify(frame));
+	const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: AES_ALGORITHM, iv }, key, plaintext));
+	const out = new Uint8Array(IV_LENGTH + ciphertext.byteLength);
+	out.set(iv, 0);
+	out.set(ciphertext, IV_LENGTH);
+	return out;
+}
+
+/** Inverse of {@link seal}. Throws on auth failure or malformed input. */
+export async function open(key: CryptoKey, data: Uint8Array): Promise<CollabFrame> {
+	if (data.byteLength <= IV_LENGTH) {
+		throw new Error("Sealed frame too short");
+	}
+	const iv = asStrict(data.subarray(0, IV_LENGTH));
+	const ciphertext = asStrict(data.subarray(IV_LENGTH));
+	const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: AES_ALGORITHM, iv }, key, ciphertext));
+	return JSON.parse(TEXT_DECODER.decode(plaintext)) as CollabFrame;
+}
+
+function asStrict(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+	if (bytes.buffer instanceof ArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+		return bytes as Uint8Array<ArrayBuffer>;
+	}
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return copy;
+}

package/src/collab/guest.ts

@@ -0,0 +1,421 @@
+/**
+ * Guest side of a collab live session.
+ *
+ * `/join <link>` writes the host's snapshot to a replica session file and
+ * drives it through the normal `/resume` machinery, then applies live frames:
+ * entries → SessionManager + agent.replaceMessages, events →
+ * EventController.handleEvent, state → status-line overrides plus real
+ * model/thinking state applied to the replica agent. The host's subagent
+ * ecosystem is mirrored too: agent snapshots populate a local AgentRegistry
+ * (Agent Hub), EventBus traffic (observer HUD) is republished, and hub
+ * actions (chat/kill/revive/transcript reads) round-trip over the wire.
+ * Everything renders through the same components, so ctrl+o, theming, and
+ * transcript behavior are native by construction.
+ */
+import * as path from "node:path";
+import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import { getConfigRootDir, logger } from "@oh-my-pi/pi-utils";
+import type { AgentHubRemote } from "../modes/components/agent-hub";
+import type { InteractiveModeContext } from "../modes/types";
+import { AgentRegistry } from "../registry/agent-registry";
+import type { AgentSessionEvent } from "../session/agent-session";
+import { shouldDisableReasoning, toReasoningEffort } from "../thinking";
+import { setSessionTerminalTitle } from "../utils/title-generator";
+import { importRoomKey } from "./crypto";
+import { collabDisplayName } from "./host";
+import {
+	type AgentSnapshot,
+	COLLAB_PROTO,
+	type CollabFrame,
+	type CollabSessionState,
+	parseCollabLink,
+} from "./protocol";
+import { CollabSocket } from "./relay-client";
+
+/** Commands a guest may run locally; everything else is host-only. */
+export const COLLAB_GUEST_ALLOWED_COMMANDS: Record<string, true> = {
+	dump: true,
+	export: true,
+	copy: true,
+	help: true,
+	hotkeys: true,
+	theme: true,
+	settings: true,
+	leave: true,
+	collab: true,
+	exit: true,
+	quit: true,
+};
+const WELCOME_TIMEOUT_MS = 30_000;
+const TRANSCRIPT_TIMEOUT_MS = 20_000;
+
+type WelcomeFrame = Extract<CollabFrame, { t: "welcome" }>;
+
+export class CollabGuestLink {
+	#ctx: InteractiveModeContext;
+	#socket: CollabSocket | null = null;
+	#roomId = "";
+	/** Previous session file to restore on leave; null = previous session was unsaved. */
+	#returnSessionFile: string | null = null;
+	/** Frames apply strictly in arrival order through this chain. */
+	#applyChain: Promise<void> = Promise.resolve();
+	#welcomed = false;
+	#left = false;
+	/** False until the first assistant message_start (real or synthesized) since (re)sync. */
+	#assistantStreamSynced = false;
+	state: CollabSessionState | null = null;
+	/** Local mirror of the host's agent ecosystem (refs carry `session: null`). */
+	readonly agentRegistry = new AgentRegistry();
+	/** Per-agent `hasSessionFile` from the last snapshot; gates remote transcript fetches. */
+	#agentHasTranscript = new Map<string, boolean>();
+	#pendingTranscripts = new Map<number, (r: { text: string; newSize: number } | null) => void>();
+	#nextReqId = 1;
+	readonly #hubRemote: AgentHubRemote = {
+		chat: (id, text) => {
+			this.#socket?.send({ t: "agent-cmd", cmd: "chat", agentId: id, text });
+		},
+		kill: id => {
+			this.#socket?.send({ t: "agent-cmd", cmd: "kill", agentId: id });
+		},
+		revive: id => {
+			this.#socket?.send({ t: "agent-cmd", cmd: "revive", agentId: id });
+		},
+		readTranscript: (id, fromByte) => {
+			const socket = this.#socket;
+			if (!socket || this.#agentHasTranscript.get(id) === false) {
+				return Promise.resolve(null);
+			}
+			const reqId = this.#nextReqId++;
+			const { promise, resolve } = Promise.withResolvers<{ text: string; newSize: number } | null>();
+			const timer = setTimeout(() => {
+				this.#pendingTranscripts.delete(reqId);
+				resolve(null);
+			}, TRANSCRIPT_TIMEOUT_MS);
+			this.#pendingTranscripts.set(reqId, result => {
+				clearTimeout(timer);
+				resolve(result);
+			});
+			socket.send({ t: "fetch-transcript", reqId, agentId: id, fromByte });
+			return promise;
+		},
+	};
+
+	/** Agent Hub actions routed to the host over the wire. */
+	get hubRemote(): AgentHubRemote {
+		return this.#hubRemote;
+	}
+
+	constructor(ctx: InteractiveModeContext) {
+		this.#ctx = ctx;
+	}
+
+	async join(link: string): Promise<void> {
+		const parsed = parseCollabLink(link);
+		if ("error" in parsed) throw new Error(parsed.error);
+		this.#roomId = parsed.roomId;
+		const key = await importRoomKey(parsed.key);
+
+		this.#returnSessionFile = this.#ctx.sessionManager.getSessionFile() ?? null;
+
+		const socket = new CollabSocket({ wsUrl: parsed.wsUrl, role: "guest", key });
+		this.#socket = socket;
+
+		const firstWelcome = Promise.withResolvers<void>();
+		let joined = false;
+
+		socket.onOpen = () => {
+			// (Re)connect: re-introduce ourselves; the host answers with a fresh
+			// welcome which (re)syncs the replica.
+			this.#welcomed = false;
+			socket.send({ t: "hello", proto: COLLAB_PROTO, name: collabDisplayName(this.#ctx) });
+		};
+		socket.onFrame = frame => {
+			this.#applyChain = this.#applyChain
+				.then(async () => {
+					if (frame.t === "welcome") {
+						await this.#applyWelcome(frame, joined);
+						if (!joined) {
+							joined = true;
+							firstWelcome.resolve();
+						}
+						return;
+					}
+					if (!this.#welcomed || this.#left) return;
+					this.#applyFrame(frame);
+				})
+				.catch(err => logger.warn("collab guest frame apply failed", { type: frame.t, error: String(err) }));
+		};
+		socket.onClose = (reason, willReconnect) => {
+			this.#flushPendingTranscripts();
+			if (this.#left) return;
+			if (!joined) {
+				firstWelcome.reject(new Error(reason));
+				return;
+			}
+			if (willReconnect) {
+				this.#ctx.showStatus(`Collab connection lost (${reason}), reconnecting…`, { dim: true });
+				return;
+			}
+			this.#ctx.showStatus(`Collab session ended (${reason})`);
+			void this.#restoreLocalSession();
+		};
+		socket.connect();
+
+		const timeout = setTimeout(
+			() => firstWelcome.reject(new Error("timed out waiting for the host's welcome")),
+			WELCOME_TIMEOUT_MS,
+		);
+		try {
+			await firstWelcome.promise;
+		} catch (err) {
+			this.#left = true;
+			socket.close();
+			this.#socket = null;
+			throw err;
+		} finally {
+			clearTimeout(timeout);
+		}
+
+		this.#ctx.collabGuest = this;
+	}
+
+	/** User-initiated leave (or post-disconnect cleanup): restore the previous session. */
+	async leave(_reason: string): Promise<void> {
+		if (this.#left) return;
+		this.#socket?.close();
+		await this.#restoreLocalSession();
+	}
+
+	sendPrompt(text: string, images?: ImageContent[]): void {
+		this.#socket?.send({ t: "prompt", text, images: images && images.length > 0 ? images : undefined });
+	}
+
+	sendAbort(): void {
+		this.#socket?.send({ t: "abort" });
+	}
+
+	/** Write the welcome snapshot to the replica file and (re)load it through the resume machinery. */
+	async #applyWelcome(frame: WelcomeFrame, isResync: boolean): Promise<void> {
+		if (this.#left) return;
+		const replicaPath = path.join(getConfigRootDir(), "collab", `${this.#roomId}.jsonl`);
+		const lines = [frame.header, ...frame.entries].map(entry => JSON.stringify(entry)).join("\n");
+		await Bun.write(replicaPath, `${lines}\n`);
+
+		// Resume sequence (selector-controller.handleResumeSession) minus
+		// applyCwdChange: the guest process never chdirs to a host path. The
+		// SessionManager still adopts the header cwd for display/relativization.
+		this.#clearTransientUi();
+		this.#clearAgentMirror();
+		await this.#ctx.session.switchSession(replicaPath);
+		this.state = frame.state;
+		this.#applyHostState(frame.state);
+		this.#ctx.resetObserverRegistry();
+		this.#applyAgentSnapshots(frame.agents);
+		this.#assistantStreamSynced = false;
+		setSessionTerminalTitle(frame.state.sessionName ?? frame.header.title, frame.state.cwd);
+		this.#ctx.chatContainer.clear();
+		this.#ctx.renderInitialMessages({ clearTerminalHistory: true });
+		await this.#ctx.reloadTodos();
+		this.#updateStatusSegment();
+		this.#welcomed = true;
+		this.#ctx.showStatus(isResync ? "Reconnected to collab session" : "Joined collab session");
+	}
+
+	#applyFrame(frame: CollabFrame): void {
+		switch (frame.t) {
+			case "entry": {
+				// Entries are never rendered directly — rendering is events-only
+				// (prevents double-render). They keep the replica file, the agent's
+				// message array (/dump, context estimates), and todos current.
+				this.#ctx.sessionManager.ingestReplicatedEntry(frame.entry);
+				if (frame.entry.type === "message") {
+					this.#ctx.session.agent.replaceMessages([...this.#ctx.session.messages, frame.entry.message]);
+				}
+				break;
+			}
+			case "event":
+				this.#applyEvent(frame.event);
+				break;
+			case "state": {
+				this.state = frame.state;
+				this.#applyHostState(frame.state);
+				setSessionTerminalTitle(frame.state.sessionName, frame.state.cwd);
+				this.#updateStatusSegment();
+				// Reconciler: events normally drive the loader; clear a stale one if
+				// the host reports idle (e.g. events lost across a reconnect).
+				if (!frame.state.isStreaming && this.#ctx.loadingAnimation) {
+					this.#ctx.loadingAnimation.stop();
+					this.#ctx.loadingAnimation = undefined;
+				}
+				this.#ctx.statusLine.invalidate();
+				this.#ctx.ui.requestRender();
+				break;
+			}
+			case "bus":
+				// Mirrored host EventBus traffic (task subagent lifecycle/progress)
+				// feeding the observer HUD and Agent Hub progress columns.
+				this.#ctx.eventBus?.emit(frame.channel, frame.data);
+				break;
+			case "agents":
+				this.#applyAgentSnapshots(frame.agents);
+				break;
+			case "transcript": {
+				const resolve = this.#pendingTranscripts.get(frame.reqId);
+				if (resolve) {
+					this.#pendingTranscripts.delete(frame.reqId);
+					resolve(frame.error ? null : { text: frame.text, newSize: frame.newSize });
+				}
+				break;
+			}
+			case "bye": {
+				this.#ctx.showStatus(`Collab session ended (${frame.reason})`);
+				this.#socket?.close();
+				void this.#restoreLocalSession();
+				break;
+			}
+			case "error":
+				this.#ctx.showError(`Collab host: ${frame.message}`);
+				break;
+			default:
+				logger.debug("collab guest ignoring unexpected frame", { type: frame.t });
+		}
+	}
+
+	#applyEvent(event: AgentSessionEvent): void {
+		// Orphan-delta guard: when joining mid-turn the message_start for the
+		// in-flight assistant message predates the snapshot. message_update
+		// carries the full accumulating message, so synthesize the missing start
+		// before the first orphaned update; every other handler is tolerant of
+		// unknown anchors (guarded by streamingComponent/pendingTools lookups).
+		if (event.type === "message_start" && event.message.role === "assistant") {
+			this.#assistantStreamSynced = true;
+		} else if (
+			event.type === "message_update" &&
+			event.message.role === "assistant" &&
+			!this.#assistantStreamSynced
+		) {
+			this.#assistantStreamSynced = true;
+			void this.#ctx.eventController.handleEvent({ type: "message_start", message: event.message });
+		}
+		void this.#ctx.eventController.handleEvent(event);
+	}
+
+	/**
+	 * Apply the host's real model/thinking state to the replica agent so model
+	 * display and context-window math are native (no display-string overrides).
+	 * Pure agent-state mutation: session.setModel/setThinkingLevel would
+	 * persist entries and clamp to local credentials.
+	 */
+	#applyHostState(state: CollabSessionState): void {
+		const session = this.#ctx.session;
+		if (
+			state.model &&
+			(session.agent.state.model?.id !== state.model.id ||
+				session.agent.state.model?.provider !== state.model.provider)
+		) {
+			session.agent.setModel(state.model);
+		}
+		const level = state.thinkingLevel as ThinkingLevel | undefined;
+		session.agent.setThinkingLevel(toReasoningEffort(level));
+		session.agent.setDisableReasoning(shouldDisableReasoning(level));
+	}
+
+	/** Diff a host agent snapshot into the local registry (refs keep `session: null`). */
+	#applyAgentSnapshots(agents: AgentSnapshot[]): void {
+		const seen = new Set<string>();
+		for (const snap of agents) seen.add(snap.id);
+		for (const ref of this.agentRegistry.list()) {
+			if (!seen.has(ref.id)) {
+				this.agentRegistry.unregister(ref.id);
+				this.#agentHasTranscript.delete(ref.id);
+			}
+		}
+		for (const snap of agents) {
+			if (this.agentRegistry.get(snap.id)) {
+				this.agentRegistry.setStatus(snap.id, snap.status);
+			} else {
+				this.agentRegistry.register({
+					id: snap.id,
+					displayName: snap.displayName,
+					kind: snap.kind,
+					parentId: snap.parentId,
+					session: null,
+					status: snap.status,
+				});
+			}
+			// Refs are returned by reference: patch host timestamps directly so
+			// hub age/activity columns reflect the host, not local registration.
+			const ref = this.agentRegistry.get(snap.id);
+			if (ref) {
+				ref.createdAt = snap.createdAt;
+				ref.lastActivity = snap.lastActivity;
+				ref.displayName = snap.displayName;
+			}
+			this.#agentHasTranscript.set(snap.id, snap.hasSessionFile);
+		}
+	}
+
+	#clearAgentMirror(): void {
+		for (const ref of this.agentRegistry.list()) {
+			this.agentRegistry.unregister(ref.id);
+		}
+		this.#agentHasTranscript.clear();
+	}
+
+	/** Resolve every in-flight transcript request with null (resolvers clear their own timers). */
+	#flushPendingTranscripts(): void {
+		for (const resolve of this.#pendingTranscripts.values()) {
+			resolve(null);
+		}
+		this.#pendingTranscripts.clear();
+	}
+
+	#clearTransientUi(): void {
+		this.#ctx.statusContainer.clear();
+		this.#ctx.pendingMessagesContainer.clear();
+		this.#ctx.compactionQueuedMessages = [];
+		this.#ctx.streamingComponent = undefined;
+		this.#ctx.streamingMessage = undefined;
+		this.#ctx.pendingTools.clear();
+		if (this.#ctx.loadingAnimation) {
+			this.#ctx.loadingAnimation.stop();
+			this.#ctx.loadingAnimation = undefined;
+		}
+	}
+
+	async #restoreLocalSession(): Promise<void> {
+		if (this.#left) return;
+		this.#left = true;
+		this.#socket = null;
+		this.#ctx.collabGuest = undefined;
+		this.#ctx.statusLine.setCollabStatus(null);
+		this.#flushPendingTranscripts();
+		this.#clearAgentMirror();
+		this.#ctx.resetObserverRegistry();
+		this.#clearTransientUi();
+		// Replica file stays on disk: it is a valid session file outside the
+		// sessions dir, so it never shows up in /resume but remains readable.
+		if (this.#returnSessionFile) {
+			await this.#ctx.handleResumeSession(this.#returnSessionFile);
+			return;
+		}
+		await this.#ctx.session.newSession();
+		setSessionTerminalTitle(this.#ctx.sessionManager.getSessionName(), this.#ctx.sessionManager.getCwd());
+		this.#ctx.statusLine.invalidate();
+		this.#ctx.statusLine.setSessionStartTime(Date.now());
+		this.#ctx.updateEditorTopBorder();
+		this.#ctx.updateEditorBorderColor();
+		this.#ctx.renderInitialMessages({ clearTerminalHistory: true });
+		await this.#ctx.reloadTodos();
+		this.#ctx.ui.requestRender(true, { clearScrollback: true });
+	}
+
+	#updateStatusSegment(): void {
+		this.#ctx.statusLine.setCollabStatus({
+			role: "guest",
+			participantCount: this.state?.participants.length ?? 1,
+			stateOverride: this.state,
+		});
+	}
+}