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

package/src/collab/protocol.ts

@@ -0,0 +1,232 @@
+/**
+ * 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,
+	ROOM_KEY_BYTES,
+	WRITE_TOKEN_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[];
+			/** True when this peer joined through a read-only (view) link. */
+			readOnly?: boolean;
+	  }
+	| { 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.
+ *
+ * Full links append the write token to the key in the fragment
+ * (`base64url(key ∥ writeToken)`); read-only (view) links carry the bare
+ * 32-byte key, which is also the pre-token link format.
+ */
+export function formatCollabLink(relayUrl: string, roomId: string, key: Uint8Array, writeToken?: Uint8Array): string {
+	const normalized = normalizeRelayOrigin(relayUrl);
+	if ("error" in normalized) throw new Error(normalized.error);
+	const secret = writeToken ? Buffer.concat([key, writeToken]) : Buffer.from(key);
+	const keyText = secret.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}`;
+}
+
+/**
+ * Render the browser deep link: `http(s)://<relay-host>/#<collab-link>`. The
+ * relay serves the web client at `/`, and the whole collab link (including the
+ * room key) rides in the fragment, so it never appears in any HTTP request.
+ * Terminals auto-link the https form, making it click-to-join.
+ */
+export function formatCollabWebLink(
+	relayUrl: string,
+	roomId: string,
+	key: Uint8Array,
+	writeToken?: Uint8Array,
+): string {
+	const normalized = normalizeRelayOrigin(relayUrl);
+	if ("error" in normalized) throw new Error(normalized.error);
+	const httpOrigin = normalized.origin.startsWith("wss://")
+		? `https://${normalized.origin.slice("wss://".length)}`
+		: `http://${normalized.origin.slice("ws://".length)}`;
+	return `${httpOrigin}/#${formatCollabLink(relayUrl, roomId, key, writeToken)}`;
+}
+
+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) {
+		// Web deep link: `http(s)://<relay>/#<collab-link>` — the fragment holds
+		// the whole link (which itself contains another `#`). URL.hash spans to
+		// the end of the string, so recurse on it; the inner fragment is just
+		// the key (no `#`), which bounds the recursion.
+		const inner = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
+		if (inner.includes("#")) return parseCollabLink(inner);
+		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 secret = B64URL_RE.test(fragment) ? new Uint8Array(Buffer.from(fragment, "base64url")) : null;
+	if (!secret || (secret.byteLength !== ROOM_KEY_BYTES && secret.byteLength !== ROOM_KEY_BYTES + WRITE_TOKEN_BYTES)) {
+		return { error: "Collab link key must be 32 (view) or 48 (full) base64url bytes" };
+	}
+	const key = secret.subarray(0, ROOM_KEY_BYTES);
+	const writeToken = secret.byteLength > ROOM_KEY_BYTES ? secret.subarray(ROOM_KEY_BYTES) : undefined;
+	return { wsUrl: `${normalized.origin}/r/${roomId}`, roomId, key, writeToken };
+}

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 "relay.example.sh/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,7 @@
 import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
+import { DEFAULT_SHARE_URL } from "@oh-my-pi/pi-wire";
 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 +103,7 @@ export const TAB_GROUPS: Record<SettingTab, readonly string[]> = {
 		"Approvals",
 		"Notifications",
 		"Speech",
+		"Collab",
 		"Magic Keywords",
 		"Startup & Updates",
 		"Power (macOS)",
@@ -147,7 +150,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 +1331,52 @@ 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)",
+		},
+	},
+
+	"share.serverUrl": {
+		type: "string",
+		default: DEFAULT_SHARE_URL,
+		ui: {
+			tab: "interaction",
+			group: "Collab",
+			label: "Share Server",
+			description:
+				"Share viewer/upload base used by /share (encrypted blob upload + viewer; links are <base>/<id>#<key>)",
+		},
+	},
+
+	"share.redactSecrets": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "interaction",
+			group: "Collab",
+			label: "Share Secret Redaction",
+			description: "Run the secret obfuscator over /share snapshots before upload (uses the secrets.* config)",
+		},
+	},
+
 	// Speech-to-text
 	"stt.enabled": {
 		type: "boolean",
@@ -3725,14 +3775,24 @@ export const SETTINGS_SCHEMA = {
 	},
 	// Codex saved rate-limit resets (auto-redeem)
 	"codexResets.autoRedeem": {
-		type: "boolean",
-		default: false,
+		type: "enum",
+		values: ["unset", "yes", "no"] as const,
+		default: "unset" as const,
 		ui: {
 			tab: "providers",
 			group: "Services",
 			label: "Codex Auto-Redeem Saved Resets",
 			description:
-				"When a turn is blocked by the Codex weekly limit on the active account and no other account is available, automatically spend one saved rate-limit reset (ChatGPT 'save rate limit resets'). Conservative: never fires for 5-hour-only or Spark limits, near a natural reset, or twice for the same block. Requires retries enabled.",
+				"When a turn is blocked by the Codex weekly limit on the active account and no other account is available, run the conservative saved-reset check. unset asks before spending the first eligible reset, yes spends eligible resets without prompting, and no disables the check entirely. Requires retries enabled.",
+			options: [
+				{
+					value: "unset",
+					label: "Unset",
+					description: "Check eligibility, then ask before spending the first saved reset.",
+				},
+				{ value: "yes", label: "Yes", description: "Spend eligible saved resets without prompting." },
+				{ value: "no", label: "No", description: "Do not run the saved-reset auto-redeem check." },
+			],
 		},
 	},
 	"codexResets.minBlockedMinutes": {
@@ -4144,8 +4204,10 @@ export interface ShellMinimizerSettings {
 	sourceOutlineLevel: "default" | "aggressive";
 	legacyFilters: boolean | undefined;
 }
+export type CodexAutoRedeemMode = "unset" | "yes" | "no";
+
 export interface CodexResetsSettings {
-	autoRedeem: boolean;
+	autoRedeem: CodexAutoRedeemMode;
 	minBlockedMinutes: number;
 	keepCredits: number;
 }