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

package/src/collab/host.ts

@@ -0,0 +1,494 @@
+/**
+ * Host side of a collab live session.
+ *
+ * Taps the host session's event stream and SessionManager append chokepoint,
+ * broadcasting entries/events/state to guests through the relay. Guests prompt
+ * and abort through us; the host machine runs the agent and tools. The host's
+ * subagent ecosystem is mirrored too: task EventBus traffic (observer HUD),
+ * agent-registry snapshots (Agent Hub table), hub chat/kill/revive commands,
+ * and incremental subagent-transcript reads.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
+import { logger } from "@oh-my-pi/pi-utils";
+import type { BusChannel, AgentEvent as WireAgentEvent, SessionEntry as WireSessionEntry } from "@oh-my-pi/pi-wire";
+import type { InteractiveModeContext } from "../modes/types";
+import { AgentLifecycleManager } from "../registry/agent-lifecycle";
+import { AgentRegistry } from "../registry/agent-registry";
+import type { AgentSessionEvent } from "../session/agent-session";
+import { stripImagesFromMessage, USER_INTERRUPT_LABEL } from "../session/messages";
+import type { SessionEntry as StoredSessionEntry } from "../session/session-manager";
+import { TASK_SUBAGENT_LIFECYCLE_CHANNEL, TASK_SUBAGENT_PROGRESS_CHANNEL } from "../task";
+import { generateRoomKey, importRoomKey } from "./crypto";
+import {
+	type AgentSnapshot,
+	COLLAB_PROMPT_MESSAGE_TYPE,
+	COLLAB_PROTO,
+	type CollabFrame,
+	type CollabParticipant,
+	type CollabSessionState,
+	formatCollabLink,
+	generateRoomId,
+	parseCollabLink,
+} from "./protocol";
+import { CollabSocket } from "./relay-client";
+
+/** Events that change the footer state guests render. */
+const STATE_TRIGGER_EVENTS: Record<string, true> = {
+	agent_start: true,
+	agent_end: true,
+	message_end: true,
+	tool_execution_end: true,
+	thinking_level_changed: true,
+	auto_compaction_end: true,
+};
+
+const STATE_DEBOUNCE_MS = 100;
+const AGENTS_DEBOUNCE_MS = 100;
+const STREAMING_STATE_INTERVAL_MS = 2000;
+const WELCOME_IMAGE_STRIP_THRESHOLD = 24 * 1024 * 1024;
+const WIRE_AGENT_EVENT_TYPES: Record<WireAgentEvent["type"], true> = {
+	agent_start: true,
+	agent_end: true,
+	turn_start: true,
+	turn_end: true,
+	message_start: true,
+	message_update: true,
+	message_end: true,
+	tool_execution_start: true,
+	tool_execution_update: true,
+	tool_execution_end: true,
+	notice: true,
+	auto_compaction_start: true,
+	auto_compaction_end: true,
+	auto_retry_start: true,
+	auto_retry_end: true,
+	thinking_level_changed: true,
+};
+
+const WIRE_SESSION_ENTRY_TYPES: Record<WireSessionEntry["type"], true> = {
+	message: true,
+	custom_message: true,
+	compaction: true,
+	branch_summary: true,
+	model_change: true,
+	thinking_level_change: true,
+};
+const COLLAB_BUS_CHANNELS = [
+	TASK_SUBAGENT_LIFECYCLE_CHANNEL,
+	TASK_SUBAGENT_PROGRESS_CHANNEL,
+] as const satisfies readonly BusChannel[];
+
+function isWireAgentEvent(event: AgentSessionEvent): event is AgentSessionEvent & WireAgentEvent {
+	return event.type in WIRE_AGENT_EVENT_TYPES;
+}
+
+function isWireSessionEntry(entry: StoredSessionEntry): entry is StoredSessionEntry & WireSessionEntry {
+	return entry.type in WIRE_SESSION_ENTRY_TYPES;
+}
+const CONNECT_TIMEOUT_MS = 15_000;
+/** Max bytes served per fetch-transcript reply (guest re-requests from `newSize`). */
+const TRANSCRIPT_READ_CAP = 4 * 1024 * 1024;
+
+/** Display name for this process's user in collab sessions. */
+export function collabDisplayName(ctx: InteractiveModeContext): string {
+	const configured = (ctx.settings.get("collab.displayName") ?? "").trim();
+	if (configured) return configured;
+	try {
+		return os.userInfo().username;
+	} catch {
+		return "anonymous";
+	}
+}
+
+export class CollabHost {
+	#ctx: InteractiveModeContext;
+	#socket: CollabSocket | null = null;
+	#link = "";
+	#sessionId = "";
+	#unsubscribe?: () => void;
+	#peers = new Map<number, string>();
+	#lastStateJson = "";
+	#stateDebounce: Timer | null = null;
+	#streamingInterval: Timer | null = null;
+	#agentsDebounce: Timer | null = null;
+	#busUnsubscribers: (() => void)[] = [];
+	#registryUnsubscribe?: () => void;
+	#stopped = false;
+
+	constructor(ctx: InteractiveModeContext) {
+		this.#ctx = ctx;
+	}
+
+	get link(): string {
+		return this.#link;
+	}
+
+	get participants(): CollabParticipant[] {
+		const list: CollabParticipant[] = [{ name: collabDisplayName(this.#ctx), role: "host" }];
+		for (const name of this.#peers.values()) list.push({ name, role: "guest" });
+		return list;
+	}
+
+	async start(relayUrl: string): Promise<void> {
+		const rawKey = generateRoomKey();
+		const roomId = generateRoomId();
+		this.#link = formatCollabLink(relayUrl, roomId, rawKey);
+		const parsed = parseCollabLink(this.#link);
+		if ("error" in parsed) throw new Error(parsed.error);
+		const key = await importRoomKey(rawKey);
+
+		const socket = new CollabSocket({ wsUrl: parsed.wsUrl, role: "host", key });
+		this.#socket = socket;
+		this.#sessionId = this.#ctx.sessionManager.getSessionId();
+
+		const firstOpen = Promise.withResolvers<void>();
+		let opened = false;
+		socket.onOpen = () => {
+			if (!opened) {
+				opened = true;
+				firstOpen.resolve();
+			}
+		};
+		socket.onFrame = (frame, fromPeer) => this.#handleFrame(frame, fromPeer);
+		socket.onControl = msg => {
+			if (msg.t === "peer-left") this.#handlePeerLeft(msg.peer);
+		};
+		socket.onClose = (reason, willReconnect) => {
+			if (this.#stopped) return;
+			if (!opened) {
+				firstOpen.reject(new Error(reason));
+				return;
+			}
+			if (willReconnect) {
+				this.#ctx.showStatus(`Collab relay connection lost (${reason}), reconnecting…`, { dim: true });
+			} else {
+				void this.#teardown();
+				this.#ctx.session.emitNotice("warning", `Collab ended: ${reason}`, "collab");
+			}
+		};
+		socket.connect();
+
+		const timeout = setTimeout(
+			() => firstOpen.reject(new Error("timed out connecting to relay")),
+			CONNECT_TIMEOUT_MS,
+		);
+		try {
+			await firstOpen.promise;
+		} catch (err) {
+			this.#stopped = true;
+			socket.close();
+			this.#socket = null;
+			throw err;
+		} finally {
+			clearTimeout(timeout);
+		}
+
+		this.#unsubscribe = this.#ctx.session.subscribe(event => {
+			if (isWireAgentEvent(event)) this.#broadcast({ t: "event", event });
+			this.#onEventForState(event);
+		});
+		const bus = this.#ctx.eventBus;
+		if (bus) {
+			for (const channel of COLLAB_BUS_CHANNELS) {
+				this.#busUnsubscribers.push(bus.on(channel, data => this.#broadcast({ t: "bus", channel, data })));
+			}
+		}
+		this.#registryUnsubscribe = AgentRegistry.global().onChange(() => this.#scheduleAgentsBroadcast());
+		this.#ctx.sessionManager.onEntryAppended = entry => {
+			if (isWireSessionEntry(entry)) this.#broadcast({ t: "entry", entry });
+			// Model/thinking/title changes land as entries while idle; refresh
+			// guest state promptly (debounce + JSON diff dedupe).
+			this.#scheduleStateBroadcast();
+		};
+		this.#updateStatusSegment();
+	}
+
+	/** Broadcast a goodbye, detach all taps, and close the socket. */
+	async stop(reason: string): Promise<void> {
+		if (this.#stopped) return;
+		this.#socket?.send({ t: "bye", reason });
+		await this.#teardown();
+	}
+
+	async #teardown(): Promise<void> {
+		if (this.#stopped) return;
+		this.#stopped = true;
+		this.#ctx.sessionManager.onEntryAppended = undefined;
+		this.#unsubscribe?.();
+		this.#unsubscribe = undefined;
+		for (const unsubscribe of this.#busUnsubscribers) unsubscribe();
+		this.#busUnsubscribers = [];
+		this.#registryUnsubscribe?.();
+		this.#registryUnsubscribe = undefined;
+		clearTimeout(this.#stateDebounce ?? undefined);
+		this.#stateDebounce = null;
+		clearTimeout(this.#agentsDebounce ?? undefined);
+		this.#agentsDebounce = null;
+		clearInterval(this.#streamingInterval ?? undefined);
+		this.#streamingInterval = null;
+		this.#peers.clear();
+		this.#socket?.close();
+		this.#socket = null;
+		this.#ctx.collabHost = undefined;
+		this.#ctx.statusLine.setCollabStatus(null);
+		this.#ctx.ui.requestRender();
+	}
+
+	#broadcast(frame: CollabFrame): void {
+		if (this.#stopped || !this.#socket) return;
+		if (this.#ctx.sessionManager.getSessionId() !== this.#sessionId) {
+			void this.stop("session switched");
+			this.#ctx.session.emitNotice("warning", "Collab ended: session switched", "collab");
+			return;
+		}
+		this.#socket.send(frame);
+	}
+
+	#handleFrame(frame: CollabFrame, fromPeer: number): void {
+		switch (frame.t) {
+			case "hello":
+				this.#handleHello(frame.name, frame.proto, fromPeer);
+				break;
+			case "prompt":
+				this.#handlePrompt(frame.text, frame.images, fromPeer);
+				break;
+			case "abort":
+				this.#handleAbort(fromPeer);
+				break;
+			case "agent-cmd":
+				this.#handleAgentCmd(frame.cmd, frame.agentId, frame.text, fromPeer);
+				break;
+			case "fetch-transcript":
+				void this.#handleFetchTranscript(frame.reqId, frame.agentId, frame.fromByte, fromPeer);
+				break;
+			default:
+				logger.debug("collab host ignoring unexpected frame", { type: frame.t, fromPeer });
+		}
+	}
+
+	#handleHello(name: string, proto: number, fromPeer: number): void {
+		if (proto !== COLLAB_PROTO) {
+			this.#socket?.send(
+				{ t: "error", message: `protocol mismatch: host speaks v${COLLAB_PROTO}, guest sent v${proto}` },
+				fromPeer,
+			);
+			return;
+		}
+		const cleanName = name.trim().slice(0, 64) || `guest-${fromPeer}`;
+		this.#peers.set(fromPeer, cleanName);
+
+		// Snapshot and send synchronously: no awaits between snapshot and send, so
+		// later entries/events queue behind the welcome on the same socket and the
+		// guest never sees a gap.
+		const snapshot = this.#ctx.sessionManager.snapshotForReplication();
+		if (JSON.stringify(snapshot).length > WELCOME_IMAGE_STRIP_THRESHOLD) {
+			let stripped = 0;
+			for (const entry of snapshot.entries) {
+				if (entry.type === "message") stripped += stripImagesFromMessage(entry.message);
+			}
+			logger.info("collab welcome exceeded size threshold; stripped images", { stripped });
+		}
+		const entries = snapshot.entries.filter(isWireSessionEntry);
+		this.#socket?.send(
+			{
+				t: "welcome",
+				proto: COLLAB_PROTO,
+				header: snapshot.header,
+				entries,
+				state: this.#buildState(),
+				agents: this.#snapshotAgents(),
+			},
+			fromPeer,
+		);
+		this.#ctx.session.emitNotice("info", `${cleanName} joined the collab session`, "collab");
+		this.#updateStatusSegment();
+		this.#scheduleStateBroadcast();
+	}
+
+	#handlePrompt(text: string, images: ImageContent[] | undefined, fromPeer: number): void {
+		const name = this.#peers.get(fromPeer) ?? `guest-${fromPeer}`;
+		const content: string | (TextContent | ImageContent)[] =
+			images && images.length > 0 ? [{ type: "text", text }, ...images] : text;
+		this.#ctx.session
+			.promptCustomMessage(
+				{
+					customType: COLLAB_PROMPT_MESSAGE_TYPE,
+					content,
+					display: true,
+					details: { from: name },
+					attribution: "user",
+				},
+				{ streamingBehavior: "steer" },
+			)
+			.catch(err => {
+				logger.warn("collab guest prompt failed", { error: String(err) });
+				this.#socket?.send({ t: "error", message: `prompt failed: ${String(err)}` }, fromPeer);
+			});
+	}
+
+	#handleAbort(fromPeer: number): void {
+		const name = this.#peers.get(fromPeer) ?? `guest-${fromPeer}`;
+		void this.#ctx.session
+			.abort()
+			.then(() => this.#ctx.session.emitNotice("info", `${name} interrupted`, "collab"))
+			.catch(err => logger.warn("collab guest abort failed", { error: String(err) }));
+	}
+
+	#handlePeerLeft(peer: number): void {
+		const name = this.#peers.get(peer);
+		this.#peers.delete(peer);
+		if (name) this.#ctx.session.emitNotice("info", `${name} left the collab session`, "collab");
+		this.#updateStatusSegment();
+		this.#scheduleStateBroadcast();
+	}
+
+	#buildState(): CollabSessionState {
+		const session = this.#ctx.session;
+		// Context numbers come from the status line's breakdown — not
+		// session.getContextUsage() — so guests render exactly what the host's
+		// own footer shows.
+		const breakdown = this.#ctx.statusLine.getCachedContextBreakdown();
+		return {
+			isStreaming: session.isStreaming,
+			queuedMessageCount: session.queuedMessageCount,
+			sessionName: session.sessionName,
+			cwd: this.#ctx.sessionManager.getCwd(),
+			model: session.model,
+			thinkingLevel: session.thinkingLevel,
+			contextUsage: {
+				tokens: breakdown.usedTokens,
+				contextWindow: breakdown.contextWindow,
+				percent: breakdown.contextWindow > 0 ? (breakdown.usedTokens / breakdown.contextWindow) * 100 : null,
+			},
+			participants: this.participants,
+		};
+	}
+
+	#onEventForState(event: AgentSessionEvent): void {
+		if (!STATE_TRIGGER_EVENTS[event.type]) return;
+		this.#scheduleStateBroadcast();
+		if (event.type === "agent_start" && !this.#streamingInterval) {
+			this.#streamingInterval = setInterval(() => this.#scheduleStateBroadcast(), STREAMING_STATE_INTERVAL_MS);
+		} else if (event.type === "agent_end" && this.#streamingInterval) {
+			clearInterval(this.#streamingInterval);
+			this.#streamingInterval = null;
+		}
+	}
+
+	#snapshotAgents(): AgentSnapshot[] {
+		return AgentRegistry.global()
+			.list()
+			.map(ref => ({
+				id: ref.id,
+				displayName: ref.displayName,
+				kind: ref.kind,
+				parentId: ref.parentId,
+				status: ref.status,
+				hasSessionFile: !!ref.sessionFile,
+				createdAt: ref.createdAt,
+				lastActivity: ref.lastActivity,
+			}));
+	}
+
+	#scheduleAgentsBroadcast(): void {
+		if (this.#stopped || this.#agentsDebounce) return;
+		this.#agentsDebounce = setTimeout(() => {
+			this.#agentsDebounce = null;
+			this.#broadcast({ t: "agents", agents: this.#snapshotAgents() });
+		}, AGENTS_DEBOUNCE_MS);
+	}
+
+	#handleAgentCmd(cmd: "chat" | "kill" | "revive", agentId: string, text: string | undefined, fromPeer: number): void {
+		const fail = (err: unknown) => {
+			logger.warn("collab agent-cmd failed", { cmd, agentId, error: String(err) });
+			this.#socket?.send({ t: "error", message: `agent ${agentId}: ${String(err)}` }, fromPeer);
+		};
+		switch (cmd) {
+			case "chat": {
+				const trimmed = text?.trim();
+				if (!trimmed) {
+					this.#socket?.send({ t: "error", message: `agent ${agentId}: empty chat message` }, fromPeer);
+					return;
+				}
+				// Mirrors the hub's #submitChatMessage: revive if parked, steer if mid-turn.
+				AgentLifecycleManager.global()
+					.ensureLive(agentId)
+					.then(session => session.prompt(trimmed, { streamingBehavior: "steer" }))
+					.catch(fail);
+				break;
+			}
+			case "kill": {
+				const kill = async () => {
+					const ref = AgentRegistry.global().get(agentId);
+					if (ref && ref.status === "running" && ref.session) {
+						await ref.session.abort({ reason: USER_INTERRUPT_LABEL });
+					}
+					await AgentLifecycleManager.global().release(agentId);
+				};
+				kill().catch(fail);
+				break;
+			}
+			case "revive":
+				AgentLifecycleManager.global().ensureLive(agentId).catch(fail);
+				break;
+		}
+	}
+
+	/** Incremental transcript read mirroring the hub's readFileIncremental contract. */
+	async #handleFetchTranscript(reqId: number, agentId: string, fromByte: number, fromPeer: number): Promise<void> {
+		const reply = (text: string, newSize: number, error?: string) =>
+			this.#socket?.send({ t: "transcript", reqId, text, newSize, error }, fromPeer);
+		const file = AgentRegistry.global().get(agentId)?.sessionFile;
+		if (!file) {
+			reply("", fromByte, "no transcript available");
+			return;
+		}
+		try {
+			const stat = await fs.stat(file);
+			if (stat.size <= fromByte) {
+				reply("", stat.size);
+				return;
+			}
+			const want = Math.min(stat.size - fromByte, TRANSCRIPT_READ_CAP);
+			const handle = await fs.open(file, "r");
+			let bytesRead: number;
+			const buf = Buffer.allocUnsafe(want);
+			try {
+				({ bytesRead } = await handle.read(buf, 0, want, fromByte));
+			} finally {
+				await handle.close();
+			}
+			let slice = buf.subarray(0, bytesRead);
+			const reachedEof = fromByte + bytesRead >= stat.size;
+			if (!reachedEof) {
+				// Trim to the last complete JSONL line so no line or UTF-8 char is split.
+				const lastNewline = slice.lastIndexOf(0x0a);
+				slice = slice.subarray(0, lastNewline >= 0 ? lastNewline + 1 : 0);
+			}
+			reply(slice.toString("utf-8"), reachedEof ? stat.size : fromByte + slice.byteLength);
+		} catch (err) {
+			logger.debug("collab transcript read failed", { agentId, error: String(err) });
+			reply("", fromByte, String(err));
+		}
+	}
+
+	#scheduleStateBroadcast(): void {
+		if (this.#stopped || this.#stateDebounce) return;
+		this.#stateDebounce = setTimeout(() => {
+			this.#stateDebounce = null;
+			const state = this.#buildState();
+			const json = JSON.stringify(state);
+			if (json === this.#lastStateJson) return;
+			this.#lastStateJson = json;
+			this.#broadcast({ t: "state", state });
+		}, STATE_DEBOUNCE_MS);
+	}
+
+	#updateStatusSegment(): void {
+		this.#ctx.statusLine.setCollabStatus({ role: "host", participantCount: this.#peers.size + 1 });
+		this.#ctx.statusLine.invalidate();
+		this.#ctx.ui.requestRender();
+	}
+}

package/src/collab/protocol.ts

@@ -0,0 +1,191 @@
+/**
+ * Collab live-session wire protocol.
+ *
+ * Hub topology: the host is authoritative, guests never peer. All session
+ * payloads (`CollabFrame`) travel AES-256-GCM sealed; the relay only sees the
+ * plaintext envelope (`[4B uint32 BE peerId][sealed payload]`) plus TEXT JSON
+ * control messages that carry no session data.
+ */
+
+import type { ImageContent, Model } from "@oh-my-pi/pi-ai";
+import type {
+	BusChannel,
+	GuestFrame,
+	ParsedCollabLink,
+	Participant,
+	SessionState,
+	AgentSnapshot as WireAgentSnapshot,
+} from "@oh-my-pi/pi-wire";
+import { DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH, ROOM_ID_BYTES } from "@oh-my-pi/pi-wire";
+import type { ContextUsage } from "../extensibility/extensions/types";
+import type { AgentSessionEvent } from "../session/agent-session";
+import type { SessionEntry, SessionHeader } from "../session/session-manager";
+
+export type {
+	CollabPromptDetails,
+	ParsedCollabLink,
+	RelayControlMessage,
+	RelayControlToGuest,
+	RelayControlToHost,
+} from "@oh-my-pi/pi-wire";
+export { COLLAB_PROMPT_MESSAGE_TYPE, COLLAB_PROTO } from "@oh-my-pi/pi-wire";
+export { DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH, ROOM_ID_BYTES };
+
+export type CollabParticipant = Participant;
+export type AgentSnapshot = WireAgentSnapshot;
+
+/** Debounced footer snapshot broadcast by the host. */
+export type CollabSessionState = SessionState & {
+	/**
+	 * Host model (full catalog object). Guests apply it to their replica
+	 * agent state so model display and context-window math are native.
+	 */
+	model?: Model;
+	/** Host status-line context numbers (guest system prompt/tools differ, so local estimates drift). */
+	contextUsage?: ContextUsage;
+};
+
+/**
+ * Encrypted payload frames (inside AES-GCM, JSON). The wire package pins the
+ * JSON skeleton (`WireFrame`); host-side frames carry the rich session types
+ * that serialize into those shapes.
+ */
+export type CollabFrame =
+	// guest -> host (hello/abort/agent-cmd/fetch-transcript are taken verbatim from the wire grammar)
+	| Exclude<GuestFrame, { t: "prompt" }>
+	| { t: "prompt"; text: string; images?: ImageContent[] }
+	// host -> guest
+	| {
+			t: "welcome";
+			proto: number;
+			header: SessionHeader;
+			entries: SessionEntry[];
+			state: CollabSessionState;
+			agents: AgentSnapshot[];
+	  }
+	| { t: "entry"; entry: SessionEntry }
+	| { t: "event"; event: AgentSessionEvent }
+	| { t: "state"; state: CollabSessionState }
+	/** Mirrored EventBus traffic (task subagent lifecycle/progress channels only). */
+	| { t: "bus"; channel: BusChannel; data: unknown }
+	/** Full agent-registry snapshot (debounced on registry change). */
+	| { t: "agents"; agents: AgentSnapshot[] }
+	/** Targeted reply to fetch-transcript; `text` is decoded JSONL from `fromByte`, `newSize` the next offset base. */
+	| { t: "transcript"; reqId: number; text: string; newSize: number; error?: string }
+	| { t: "bye"; reason: string }
+	| { t: "error"; message: string };
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Wire envelope: [4B uint32 BE peerId][sealed payload]
+// Host→relay: peerId 0 broadcasts to all guests; peerId N targets guest N.
+// Guest→relay: always 0; the relay rewrites it to the sender's id.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function packEnvelope(peerId: number, sealed: Uint8Array): Uint8Array {
+	const out = new Uint8Array(ENVELOPE_HEADER_LENGTH + sealed.byteLength);
+	new DataView(out.buffer).setUint32(0, peerId, false);
+	out.set(sealed, ENVELOPE_HEADER_LENGTH);
+	return out;
+}
+
+export function unpackEnvelope(data: Uint8Array): { peerId: number; payload: Uint8Array } | null {
+	if (data.byteLength < ENVELOPE_HEADER_LENGTH) return null;
+	const peerId = new DataView(data.buffer, data.byteOffset, ENVELOPE_HEADER_LENGTH).getUint32(0, false);
+	return { peerId, payload: data.subarray(ENVELOPE_HEADER_LENGTH) };
+}
+
+/** Rewrite the peerId in place without copying the payload. */
+export function rewriteEnvelopePeer(data: Uint8Array, peerId: number): void {
+	new DataView(data.buffer, data.byteOffset, ENVELOPE_HEADER_LENGTH).setUint32(0, peerId, false);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Link format: wss://<host[:port]>/r/<roomId>#<base64url-32-byte-key>
+// ═══════════════════════════════════════════════════════════════════════════
+
+const ROOM_PATH_RE = /^\/r\/([A-Za-z0-9_-]{10,64})$/;
+const BARE_LINK_RE = /^([A-Za-z0-9_-]{10,64})#([A-Za-z0-9_-]+)$/;
+const B64URL_RE = /^[A-Za-z0-9_-]+$/;
+const LOCAL_HOSTNAMES: Record<string, true> = { localhost: true, "127.0.0.1": true, "::1": true, "[::1]": true };
+
+export function generateRoomId(): string {
+	const bytes = new Uint8Array(ROOM_ID_BYTES);
+	crypto.getRandomValues(bytes);
+	return Buffer.from(bytes).toString("base64url");
+}
+
+/** Normalize a relay base URL (ws/wss/http/https) into a ws/wss origin, or an error. */
+function normalizeRelayOrigin(relayUrl: string): { origin: string } | { error: string } {
+	let url: URL;
+	try {
+		url = new URL(relayUrl);
+	} catch {
+		return { error: `Invalid relay URL: ${relayUrl}` };
+	}
+	let scheme: string;
+	switch (url.protocol) {
+		case "wss:":
+		case "https:":
+			scheme = "wss:";
+			break;
+		case "ws:":
+		case "http:":
+			scheme = "ws:";
+			break;
+		default:
+			return { error: `Unsupported relay URL scheme: ${url.protocol}` };
+	}
+	if (scheme === "ws:" && !LOCAL_HOSTNAMES[url.hostname]) {
+		return { error: "relay link must be wss:// (plain ws:// is only allowed for localhost)" };
+	}
+	const port = url.port ? `:${url.port}` : "";
+	return { origin: `${scheme}//${url.hostname}${port}` };
+}
+
+/**
+ * Render the shareable link. Compact forms: the default relay collapses to
+ * `<roomId>#<key>`, other wss relays drop the scheme (`host[:port]/r/…`);
+ * only localhost ws:// links keep their full URL so parsing cannot
+ * mis-infer wss.
+ */
+export function formatCollabLink(relayUrl: string, roomId: string, key: Uint8Array): string {
+	const normalized = normalizeRelayOrigin(relayUrl);
+	if ("error" in normalized) throw new Error(normalized.error);
+	const keyText = Buffer.from(key).toString("base64url");
+	if (normalized.origin === DEFAULT_RELAY_URL) return `${roomId}#${keyText}`;
+	const compact = normalized.origin.startsWith("wss://")
+		? normalized.origin.slice("wss://".length)
+		: normalized.origin;
+	return `${compact}/r/${roomId}#${keyText}`;
+}
+
+export function parseCollabLink(link: string): ParsedCollabLink | { error: string } {
+	let text = link.trim();
+	// Bare `<roomId>#<key>` → default relay.
+	const bare = BARE_LINK_RE.exec(text);
+	if (bare) text = `${DEFAULT_RELAY_URL}/r/${bare[1]}#${bare[2]}`;
+	// Scheme-less `host[:port]/r/…` → wss.
+	else if (!text.includes("://")) text = `wss://${text}`;
+	let url: URL;
+	try {
+		url = new URL(text);
+	} catch {
+		return { error: `Invalid collab link: ${link}` };
+	}
+	const normalized = normalizeRelayOrigin(url.origin);
+	if ("error" in normalized) return normalized;
+	const match = ROOM_PATH_RE.exec(url.pathname);
+	if (!match) {
+		return { error: "Collab link must contain a /r/<roomId> path" };
+	}
+	const roomId = match[1]!;
+	const fragment = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+	if (!fragment) {
+		return { error: "Collab link is missing the #<key> fragment" };
+	}
+	const key = B64URL_RE.test(fragment) ? new Uint8Array(Buffer.from(fragment, "base64url")) : null;
+	if (key?.byteLength !== 32) {
+		return { error: "Collab link key must be 32 base64url bytes" };
+	}
+	return { wsUrl: `${normalized.origin}/r/${roomId}`, roomId, key };
+}