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

package/src/collab/relay-client.ts

@@ -0,0 +1,216 @@
+/**
+ * Client-side WebSocket wrapper for collab live-session sharing.
+ *
+ * Connects to a relay room, seals/opens AES-GCM frames, and reconnects with
+ * exponential backoff on transient drops. Fatal relay close codes (room gone,
+ * host conflict, room full) and decryption failures never reconnect.
+ */
+import { logger } from "@oh-my-pi/pi-utils";
+import { open, seal } from "./crypto";
+import type { CollabFrame, RelayControlMessage } from "./protocol";
+import { packEnvelope, unpackEnvelope } from "./protocol";
+
+const FATAL_CLOSE_REASONS: Record<number, string> = {
+	4001: "room closed",
+	4004: "no such room",
+	4009: "a host is already connected for this room",
+	4029: "room is full",
+};
+
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 30_000;
+/** Max enveloped frames buffered while a reconnect is pending; overflow is dropped. */
+const MAX_PENDING_SENDS = 256;
+
+export interface CollabSocketOptions {
+	/** wss://host[:port]/r/<roomId> — no query string. */
+	wsUrl: string;
+	role: "host" | "guest";
+	key: CryptoKey;
+}
+
+export class CollabSocket {
+	/** Fires after every successful (re)connect. */
+	onOpen?: () => void;
+	onFrame?: (frame: CollabFrame, fromPeer: number) => void;
+	onControl?: (msg: RelayControlMessage) => void;
+	/** Fires once per terminal close (intentional, fatal code, or bad key). willReconnect=true for transient drops that will retry. */
+	onClose?: (reason: string, willReconnect: boolean) => void;
+
+	readonly #opts: CollabSocketOptions;
+	#ws: WebSocket | null = null;
+	#retryTimer: NodeJS.Timeout | undefined;
+	#attempt = 0;
+	/** Terminal state: intentional close or fatal failure. Cleared by connect(). */
+	#closed = false;
+	/** Serializes seal() so frames hit the wire in send() order. */
+	#sendChain: Promise<void> = Promise.resolve();
+	/** Serializes open() so frames are delivered in arrival order. */
+	#recvChain: Promise<void> = Promise.resolve();
+	/** Envelopes sealed while disconnected, flushed on the next open. */
+	#pendingSends: Uint8Array[] = [];
+
+	constructor(opts: CollabSocketOptions) {
+		this.#opts = opts;
+	}
+
+	get isOpen(): boolean {
+		return this.#ws?.readyState === WebSocket.OPEN;
+	}
+
+	connect(): void {
+		if (this.#ws || this.#retryTimer) return;
+		this.#closed = false;
+		this.#attempt = 0;
+		this.#openSocket();
+	}
+
+	send(frame: CollabFrame, targetPeer = 0): void {
+		this.#sendChain = this.#sendChain
+			.then(async () => {
+				if (this.#closed) {
+					logger.debug("collab: dropping frame, socket closed", { t: frame.t });
+					return;
+				}
+				const sealed = await seal(this.#opts.key, frame);
+				const envelope = packEnvelope(targetPeer, sealed);
+				const ws = this.#ws;
+				if (ws && ws.readyState === WebSocket.OPEN) {
+					ws.send(envelope);
+					return;
+				}
+				if (this.#pendingSends.length >= MAX_PENDING_SENDS) {
+					logger.debug("collab: dropping frame, reconnect buffer full", { t: frame.t });
+					return;
+				}
+				this.#pendingSends.push(envelope);
+			})
+			.catch((err: unknown) => {
+				logger.debug("collab: send failed", { error: String(err) });
+			});
+	}
+
+	/** Intentional close: clears any retry timer, suppresses reconnect. A later connect() starts fresh. */
+	close(): void {
+		const hadActivity = this.#ws !== null || this.#retryTimer !== undefined;
+		this.#clearRetry();
+		const wasClosed = this.#closed;
+		this.#closed = true;
+		this.#pendingSends.length = 0;
+		const ws = this.#ws;
+		this.#ws = null;
+		if (ws) {
+			try {
+				ws.close(1000);
+			} catch {
+				// already closing/closed
+			}
+		}
+		if (hadActivity && !wasClosed) this.onClose?.("closed", false);
+	}
+
+	#openSocket(): void {
+		const ws = new WebSocket(`${this.#opts.wsUrl}?role=${this.#opts.role}`);
+		ws.binaryType = "arraybuffer";
+		this.#ws = ws;
+		ws.onopen = () => {
+			if (this.#ws !== ws) return;
+			this.#attempt = 0;
+			for (const envelope of this.#pendingSends) ws.send(envelope);
+			this.#pendingSends.length = 0;
+			this.onOpen?.();
+		};
+		ws.onmessage = (event: MessageEvent) => {
+			if (this.#ws !== ws) return;
+			this.#handleMessage(ws, event.data);
+		};
+		ws.onerror = () => {
+			// The paired close event carries the actionable state; nothing to do here.
+		};
+		ws.onclose = (event: CloseEvent) => {
+			if (this.#ws !== ws) return;
+			this.#ws = null;
+			this.#handleClose(event.code, event.reason);
+		};
+	}
+
+	#handleMessage(ws: WebSocket, data: unknown): void {
+		if (typeof data === "string") {
+			try {
+				this.onControl?.(JSON.parse(data) as RelayControlMessage);
+			} catch {
+				logger.debug("collab: ignoring malformed control message");
+			}
+			return;
+		}
+		const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data instanceof Uint8Array ? data : null;
+		if (!bytes) return;
+		const envelope = unpackEnvelope(bytes);
+		if (!envelope) return;
+		this.#recvChain = this.#recvChain
+			.then(async () => {
+				if (this.#ws !== ws) return;
+				let frame: CollabFrame;
+				try {
+					frame = await open(this.#opts.key, envelope.payload);
+				} catch {
+					this.#failFatal("bad key or corrupted frame");
+					return;
+				}
+				if (this.#ws !== ws) return;
+				this.onFrame?.(frame, envelope.peerId);
+			})
+			.catch((err: unknown) => {
+				logger.debug("collab: frame handler failed", { error: String(err) });
+			});
+	}
+
+	#handleClose(code: number, reason: string): void {
+		if (this.#closed) return;
+		const fatalReason = FATAL_CLOSE_REASONS[code];
+		if (fatalReason !== undefined) {
+			this.#closed = true;
+			this.#pendingSends.length = 0;
+			this.onClose?.(fatalReason, false);
+			return;
+		}
+		this.onClose?.(reason || `connection lost (code ${code})`, true);
+		this.#scheduleRetry();
+	}
+
+	/** Decryption failure: wrong key or corrupted frame. Never reconnect. */
+	#failFatal(reason: string): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#clearRetry();
+		this.#pendingSends.length = 0;
+		const ws = this.#ws;
+		this.#ws = null;
+		if (ws) {
+			try {
+				ws.close(1000);
+			} catch {
+				// already closing/closed
+			}
+		}
+		this.onClose?.(reason, false);
+	}
+
+	#scheduleRetry(): void {
+		const base = Math.min(BACKOFF_BASE_MS * 2 ** this.#attempt, BACKOFF_MAX_MS);
+		this.#attempt++;
+		const delay = base * (0.75 + Math.random() * 0.5);
+		this.#retryTimer = setTimeout(() => {
+			this.#retryTimer = undefined;
+			if (this.#closed) return;
+			this.#openSocket();
+		}, delay);
+	}
+
+	#clearRetry(): void {
+		if (this.#retryTimer !== undefined) {
+			clearTimeout(this.#retryTimer);
+			this.#retryTimer = undefined;
+		}
+	}
+}

package/src/commands/join.ts

@@ -0,0 +1,39 @@
+/**
+ * Join a shared collab session from the CLI: launches the interactive TUI and
+ * immediately runs `/join <link>`.
+ */
+import { APP_NAME } from "@oh-my-pi/pi-utils";
+import { Args, Command } from "@oh-my-pi/pi-utils/cli";
+import { parseArgs } from "../cli/args";
+import { runRootCommand } from "../main";
+
+export default class Join extends Command {
+	static description = "Join a shared collab session (same as /join)";
+
+	static args = {
+		link: Args.string({
+			description: "Collab link shared by the host (/collab)",
+			required: true,
+		}),
+	};
+
+	static examples = [`${APP_NAME} join wss://relay.omp.sh/s/abc123#key`];
+
+	async run(): Promise<void> {
+		const { args } = await this.parse(Join);
+		const link = args.link?.trim();
+		if (!link) {
+			process.stderr.write(`Usage: ${APP_NAME} join <link>\n`);
+			process.exitCode = 1;
+			return;
+		}
+		if (!process.stdin.isTTY || !process.stdout.isTTY) {
+			process.stderr.write(`${APP_NAME} join requires an interactive terminal\n`);
+			process.exitCode = 1;
+			return;
+		}
+		const parsed = parseArgs([]);
+		parsed.join = link;
+		await runRootCommand(parsed, []);
+	}
+}

package/src/config/model-registry.ts

@@ -602,6 +602,7 @@ function getConfiguredProviderOrderFromSettings(): string[] {
 export class ModelRegistry {
 	#models: Model<Api>[] = [];
 	#canonicalIndex: CanonicalModelIndex = { records: [], byId: new Map(), bySelector: new Map() };
+	#canonicalIndexDirty: boolean = true;
 	#customProviderApiKeys: Map<string, string> = new Map();
 	#keylessProviders: Set<string> = new Set();
 	#discoverableProviders: DiscoveryProviderConfig[] = [];
@@ -1519,14 +1520,25 @@ export class ModelRegistry {
 			this.#rebuildPending = true;
 			return;
 		}
-		this.#canonicalIndex = buildCanonicalModelIndex(
-			this.#models,
-			getBundledCanonicalReferenceData(),
-			this.#equivalenceConfig,
-		);
+		// Defer the catalog-wide index build to first read. Boot model
+		// resolution reads it only when enabledModels or a default-role pattern
+		// is configured; the empty interactive launch never reads it pre-paint,
+		// so the ~200ms build over the full catalog moves off the first-paint
+		// critical path.
+		this.#canonicalIndexDirty = true;
 		this.#rebuildPending = false;
 	}
 
+	#ensureCanonicalIndex(): CanonicalModelIndex {
+		if (this.#canonicalIndexDirty) {
+			this.#canonicalIndex = logger.time("buildCanonicalModelIndex", () =>
+				buildCanonicalModelIndex(this.#models, getBundledCanonicalReferenceData(), this.#equivalenceConfig),
+			);
+			this.#canonicalIndexDirty = false;
+		}
+		return this.#canonicalIndex;
+	}
+
 	#suspendRebuild(): void {
 		this.#rebuildSuspended += 1;
 	}
@@ -1537,11 +1549,7 @@ export class ModelRegistry {
 		}
 		if (this.#rebuildSuspended === 0 && this.#rebuildPending) {
 			this.#rebuildPending = false;
-			this.#canonicalIndex = buildCanonicalModelIndex(
-				this.#models,
-				getBundledCanonicalReferenceData(),
-				this.#equivalenceConfig,
-			);
+			this.#canonicalIndexDirty = true;
 		}
 	}
 
@@ -1650,7 +1658,7 @@ export class ModelRegistry {
 	getCanonicalModels(options?: CanonicalModelQueryOptions): CanonicalModelRecord[] {
 		const { candidateKeys, isAvailable } = this.#canonicalQueryFilters(options);
 		const records: CanonicalModelRecord[] = [];
-		for (const record of this.#canonicalIndex.records) {
+		for (const record of this.#ensureCanonicalIndex().records) {
 			const variants = this.#filterCanonicalVariants(record, candidateKeys, isAvailable);
 			if (variants.length === 0) {
 				continue;
@@ -1676,7 +1684,7 @@ export class ModelRegistry {
 		const candidates = options?.candidates ?? (options?.availableOnly ? this.getAvailable() : this.getAll());
 		const preferences = this.#variantPreferences(candidates);
 		const selections: CanonicalModelSelection[] = [];
-		for (const record of this.#canonicalIndex.records) {
+		for (const record of this.#ensureCanonicalIndex().records) {
 			const variants = this.#filterCanonicalVariants(record, candidateKeys, isAvailable);
 			if (variants.length === 0) {
 				continue;
@@ -1694,7 +1702,7 @@ export class ModelRegistry {
 	}
 
 	getCanonicalVariants(canonicalId: string, options?: CanonicalModelQueryOptions): CanonicalModelVariant[] {
-		const record = this.#canonicalIndex.byId.get(canonicalId.trim().toLowerCase());
+		const record = this.#ensureCanonicalIndex().byId.get(canonicalId.trim().toLowerCase());
 		if (!record) {
 			return [];
 		}
@@ -1712,7 +1720,7 @@ export class ModelRegistry {
 	}
 
 	getCanonicalId(model: Model<Api>): string | undefined {
-		return this.#canonicalIndex.bySelector.get(formatCanonicalVariantSelector(model).toLowerCase());
+		return this.#ensureCanonicalIndex().bySelector.get(formatCanonicalVariantSelector(model).toLowerCase());
 	}
 
 	/**

package/src/config/settings-schema.ts

@@ -1,5 +1,6 @@
 import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
 import { SHAPE_VARIANT_NAMES } from "@oh-my-pi/snapcompact";
+import { DEFAULT_RELAY_URL } from "../collab/protocol";
 import { AUTO_THINKING, getConfiguredThinkingLevelMetadata, getThinkingLevelMetadata } from "../thinking";
 import {
 	TINY_MODEL_DEVICE_DEFAULT,
@@ -101,6 +102,7 @@ export const TAB_GROUPS: Record<SettingTab, readonly string[]> = {
 		"Approvals",
 		"Notifications",
 		"Speech",
+		"Collab",
 		"Magic Keywords",
 		"Startup & Updates",
 		"Power (macOS)",
@@ -147,7 +149,8 @@ export type StatusLineSegmentId =
 	| "cache_write"
 	| "cache_hit"
 	| "session_name"
-	| "usage";
+	| "usage"
+	| "collab";
 
 /** Submenu choice metadata. */
 export type SubmenuOption<V extends string = string> = {
@@ -1327,6 +1330,29 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	// Collab
+	"collab.relayUrl": {
+		type: "string",
+		default: DEFAULT_RELAY_URL,
+		ui: {
+			tab: "interaction",
+			group: "Collab",
+			label: "Relay URL",
+			description: "Relay used by /collab (wss://host[:port]; self-host with the omp-collab-relay service)",
+		},
+	},
+
+	"collab.displayName": {
+		type: "string",
+		default: "",
+		ui: {
+			tab: "interaction",
+			group: "Collab",
+			label: "Display Name",
+			description: "Name shown to other collab participants (default: OS username)",
+		},
+	},
+
 	// Speech-to-text
 	"stt.enabled": {
 		type: "boolean",

package/src/extensibility/slash-commands.ts

@@ -1,14 +1,8 @@
-import type { AutocompleteItem } from "@oh-my-pi/pi-tui";
 import { parseFrontmatter, prompt } from "@oh-my-pi/pi-utils";
 import { slashCommandCapability } from "../capability/slash-command";
 import { appendInlineArgsFallback, templateUsesInlineArgPlaceholders } from "../config/prompt-templates";
 import type { SlashCommand } from "../discovery";
 import { loadCapability } from "../discovery";
-import {
-	BUILTIN_SLASH_COMMAND_DEFS,
-	type BuiltinSlashCommand,
-	type SubcommandDef,
-} from "../slash-commands/builtin-registry";
 import { EMBEDDED_COMMAND_TEMPLATES } from "../task/commands";
 import { parseCommandArgs, substituteArgs } from "../utils/command-args";
 
@@ -24,97 +18,7 @@ export interface SlashCommandInfo {
 	path?: string;
 }
 
-export type { BuiltinSlashCommand, SubcommandDef } from "../slash-commands/builtin-registry";
-
-/**
- * Build getArgumentCompletions from declarative subcommand definitions.
- * Returns subcommand names filtered by prefix in the dropdown.
- */
-function buildArgumentCompletions(subcommands: SubcommandDef[]): (prefix: string) => AutocompleteItem[] | null {
-	return (argumentPrefix: string) => {
-		if (argumentPrefix.includes(" ")) return null; // past the subcommand
-		const lower = argumentPrefix.toLowerCase();
-		const matches = subcommands
-			.filter(s => s.name.startsWith(lower))
-			.map(s => ({
-				value: `${s.name} `,
-				label: s.name,
-				description: s.description,
-				hint: s.usage,
-			}));
-		return matches.length > 0 ? matches : null;
-	};
-}
-
-/**
- * Build getInlineHint from declarative subcommand definitions.
- * Shows remaining completion + usage as dim ghost text after cursor.
- */
-function buildSubcommandInlineHint(subcommands: SubcommandDef[]): (argumentText: string) => string | null {
-	return (argumentText: string) => {
-		const trimmed = argumentText.trimStart();
-		const spaceIndex = trimmed.indexOf(" ");
-
-		if (spaceIndex === -1) {
-			// Still typing subcommand name — show remaining chars + usage
-			const prefix = trimmed.toLowerCase();
-			if (prefix.length === 0) return null;
-			const match = subcommands.find(s => s.name.startsWith(prefix));
-			if (!match) return null;
-			const remaining = match.name.slice(prefix.length);
-			return remaining + (match.usage ? ` ${match.usage}` : "");
-		}
-
-		// Subcommand typed — show remaining usage params
-		const subName = trimmed.slice(0, spaceIndex).toLowerCase();
-		const afterSub = trimmed.slice(spaceIndex + 1);
-		const sub = subcommands.find(s => s.name === subName);
-		if (!sub?.usage) return null;
-
-		if (afterSub.length > 0) {
-			const usageParts = sub.usage.split(" ");
-			const inputParts = afterSub.trim().split(/\s+/);
-			const remaining = usageParts.slice(inputParts.length);
-			return remaining.length > 0 ? remaining.join(" ") : null;
-		}
-
-		return sub.usage;
-	};
-}
-
-/**
- * Build getInlineHint for commands with a simple static hint string.
- * Shows the hint only when no arguments have been typed yet.
- */
-function buildStaticInlineHint(hint: string): (argumentText: string) => string | null {
-	return (argumentText: string) => (argumentText.trim().length === 0 ? hint : null);
-}
-
-/**
- * Materialized builtin slash commands with completion functions derived from
- * declarative subcommand/hint definitions.
- */
-export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<
-	BuiltinSlashCommand & {
-		getArgumentCompletions?: (prefix: string) => AutocompleteItem[] | null;
-		getInlineHint?: (argumentText: string) => string | null;
-	}
-> = BUILTIN_SLASH_COMMAND_DEFS.map(cmd => {
-	if (cmd.subcommands) {
-		return {
-			...cmd,
-			getArgumentCompletions: buildArgumentCompletions(cmd.subcommands),
-			getInlineHint: buildSubcommandInlineHint(cmd.subcommands),
-		};
-	}
-	if (cmd.inlineHint) {
-		return {
-			...cmd,
-			getInlineHint: buildStaticInlineHint(cmd.inlineHint),
-		};
-	}
-	return cmd;
-});
+export type { BuiltinSlashCommand, SubcommandDef } from "../slash-commands/types";
 
 /**
  * Represents a custom slash command loaded from a file