@oh-my-pi/pi-wire 15.11.8

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+## [15.11.8] - 2026-06-12
+
+### Added
+
+- Added shared collab live-session wire contracts for the host CLI and browser guest client.

package/README.md

@@ -0,0 +1,31 @@
+# @oh-my-pi/pi-wire
+
+Shared TypeScript wire contracts for omp collab live sessions.
+
+The package contains only JSON-safe protocol shapes and constants. It has no runtime dependencies and is consumed by both the host CLI (`@oh-my-pi/pi-coding-agent`) and browser guest (`@oh-my-pi/collab-web`).
+
+## Exports
+
+```ts
+import type { GuestFrame, HostFrame, SessionEntry } from "@oh-my-pi/pi-wire";
+import { COLLAB_PROTO, DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH } from "@oh-my-pi/pi-wire";
+```
+
+Key groups:
+
+- message and transcript entry shapes rendered by collab guests,
+- live agent event and task-subagent bus payload shapes,
+- `GuestFrame`, `HostFrame`, and `WireFrame` unions for AES-GCM sealed payloads,
+- relay control TEXT messages,
+- link/envelope constants shared by host, guest, and local relay code.
+
+## Protocol boundary
+
+`pi-wire` does not encode, decode, validate, encrypt, or route frames. It defines the shared contract used at those boundaries:
+
+1. callers build a `GuestFrame` or `HostFrame`,
+2. transport code serializes it as JSON inside an encrypted payload,
+3. relay code routes opaque envelopes using the plaintext peer-id prefix,
+4. receivers switch on `frame.t` and tolerate unknown future fields.
+
+Keep protocol changes backward-aware: bump `COLLAB_PROTO` only when old hosts and guests must reject each other.

package/dist/types/index.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Shared wire types for the omp collab live-session protocol.
+ *
+ * Dependency-free JSON shapes produced by `@oh-my-pi/pi-coding-agent`
+ * (`src/collab/protocol.ts` and friends). Browser and test clients import this
+ * package instead of depending on the coding-agent runtime; conformance is
+ * asserted type-only in `packages/coding-agent/test/collab/web-wire.types.ts`.
+ *
+ * Unknown entry/event variants arrive over the wire as plain JSON. The unions
+ * below cover only the variants this client renders; consumers cast at the
+ * JSON boundary and every `switch` keeps a tolerant `default:` branch.
+ */
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+export interface ImageContent {
+    type: "image";
+    /** Base64-encoded image data. */
+    data: string;
+    /** e.g. "image/png". */
+    mimeType: string;
+}
+export interface ThinkingContent {
+    type: "thinking";
+    thinking: string;
+}
+export interface RedactedThinkingContent {
+    type: "redactedThinking";
+    data: string;
+}
+export interface ToolCallContent {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    intent?: string;
+}
+export type AssistantContent = TextContent | ThinkingContent | RedactedThinkingContent | ToolCallContent;
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+export interface WireUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: {
+        total: number;
+    };
+}
+export interface UserMessage {
+    role: "user";
+    content: string | (TextContent | ImageContent)[];
+    /** True if the message was injected by the system (e.g. auto-continue). */
+    synthetic?: boolean;
+    /** Unix timestamp in milliseconds. */
+    timestamp: number;
+}
+export interface DeveloperMessage {
+    role: "developer";
+    content: string | (TextContent | ImageContent)[];
+    timestamp: number;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: AssistantContent[];
+    model: string;
+    usage: WireUsage;
+    stopReason: StopReason;
+    errorMessage?: string;
+    timestamp: number;
+}
+export interface ToolResultMessage {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent)[];
+    details?: unknown;
+    isError: boolean;
+    timestamp: number;
+}
+export type WireMessage = UserMessage | DeveloperMessage | AssistantMessage | ToolResultMessage;
+export interface SessionHeader {
+    type: "session";
+    id: string;
+    title?: string;
+    timestamp: string;
+    cwd: string;
+}
+export interface EntryBase {
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export interface MessageEntry extends EntryBase {
+    type: "message";
+    message: WireMessage;
+}
+export interface CustomMessageEntry extends EntryBase {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    details?: unknown;
+    display: boolean;
+}
+export interface CompactionEntry extends EntryBase {
+    type: "compaction";
+    summary: string;
+    shortSummary?: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+}
+export interface BranchSummaryEntry extends EntryBase {
+    type: "branch_summary";
+    fromId: string;
+    summary: string;
+}
+export interface ModelChangeEntry extends EntryBase {
+    type: "model_change";
+    /** Model in "provider/modelId" format. */
+    model: string;
+    role?: string;
+}
+export interface ThinkingLevelChangeEntry extends EntryBase {
+    type: "thinking_level_change";
+    thinkingLevel?: string | null;
+}
+export type SessionEntry = MessageEntry | CustomMessageEntry | CompactionEntry | BranchSummaryEntry | ModelChangeEntry | ThinkingLevelChangeEntry;
+/** customType of collab guest prompts injected on the host. */
+export declare const COLLAB_PROMPT_MESSAGE_TYPE = "collab-prompt";
+/** `details` shape of `custom_message` entries with `customType === "collab-prompt"`. */
+export interface CollabPromptDetails {
+    from?: string;
+}
+export type AgentEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+} | {
+    type: "message_start";
+    message: WireMessage;
+}
+/** Carries the FULL accumulating partial message — no delta tracking needed. */
+ | {
+    type: "message_update";
+    message: WireMessage;
+} | {
+    type: "message_end";
+    message: WireMessage;
+} | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    intent?: string;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    partialResult: unknown;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    isError?: boolean;
+} | {
+    type: "notice";
+    level: "info" | "warning" | "error";
+    message: string;
+    source?: string;
+} | {
+    type: "auto_compaction_start";
+    reason: string;
+    action: string;
+} | {
+    type: "auto_compaction_end";
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+    skipped?: boolean;
+} | {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+} | {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+} | {
+    type: "thinking_level_changed";
+    thinkingLevel?: string;
+};
+export interface WireModel {
+    id: string;
+    name: string;
+    provider: string;
+    contextWindow: number;
+}
+export interface ContextUsage {
+    tokens: number | null;
+    contextWindow: number;
+    percent: number | null;
+}
+export interface Participant {
+    name: string;
+    role: "host" | "guest";
+}
+/** Debounced footer snapshot broadcast by the host. */
+export interface SessionState {
+    isStreaming: boolean;
+    queuedMessageCount: number;
+    sessionName?: string;
+    /** Host cwd — display only; the guest never chdirs. */
+    cwd: string;
+    model?: WireModel;
+    thinkingLevel?: string;
+    contextUsage?: ContextUsage;
+    participants: Participant[];
+}
+export interface AgentSnapshot {
+    id: string;
+    displayName: string;
+    kind: "main" | "sub";
+    parentId?: string;
+    status: "running" | "idle" | "parked" | "aborted";
+    /** Whether the host has a transcript file for this agent (gates remote transcript fetch). */
+    hasSessionFile: boolean;
+    createdAt: number;
+    lastActivity: number;
+}
+export interface AgentProgress {
+    index: number;
+    id: string;
+    agent: string;
+    status: "pending" | "running" | "completed" | "failed" | "aborted";
+    task: string;
+    description?: string;
+    lastIntent?: string;
+    currentTool?: string;
+    currentToolArgs?: string;
+    currentToolStartMs?: number;
+    recentTools: {
+        tool: string;
+        args: string;
+        endMs: number;
+    }[];
+    recentOutput: string[];
+    toolCount: number;
+    requests: number;
+    tokens: number;
+    contextTokens?: number;
+    contextWindow?: number;
+    cost: number;
+    durationMs: number;
+    resolvedModel?: string;
+}
+export interface SubagentProgressPayload {
+    index: number;
+    agent: string;
+    task: string;
+    parentToolCallId?: string;
+    assignment?: string;
+    progress: AgentProgress;
+    sessionFile?: string;
+}
+export interface SubagentLifecyclePayload {
+    id: string;
+    agent: string;
+    description?: string;
+    status: "started" | "completed" | "failed" | "aborted";
+    sessionFile?: string;
+    parentToolCallId?: string;
+    index: number;
+}
+export type GuestFrame = {
+    t: "hello";
+    proto: number;
+    name: string;
+} | {
+    t: "prompt";
+    text: string;
+    images?: ImageContent[];
+} | {
+    t: "abort";
+} | {
+    t: "agent-cmd";
+    cmd: "chat" | "kill" | "revive";
+    agentId: string;
+    text?: string;
+} | {
+    t: "fetch-transcript";
+    reqId: number;
+    agentId: string;
+    fromByte: number;
+};
+/** EventBus channels mirrored to guests (task subagent traffic only). */
+export type BusChannel = "task:subagent:progress" | "task:subagent:lifecycle";
+export type HostFrame = {
+    t: "welcome";
+    proto: number;
+    header: SessionHeader;
+    entries: SessionEntry[];
+    state: SessionState;
+    agents: AgentSnapshot[];
+} | {
+    t: "entry";
+    entry: SessionEntry;
+} | {
+    t: "event";
+    event: AgentEvent;
+} | {
+    t: "state";
+    state: SessionState;
+}
+/** Mirrored EventBus traffic (task subagent lifecycle/progress channels only). */
+ | {
+    t: "bus";
+    channel: BusChannel;
+    data: unknown;
+} | {
+    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;
+};
+export type WireFrame = GuestFrame | HostFrame;
+/** Wire protocol version carried in `hello`; the host rejects mismatches. */
+export declare const COLLAB_PROTO = 1;
+/** Plaintext envelope prefix: `[4B uint32 BE peerId][sealed payload]`. */
+export declare const ENVELOPE_HEADER_LENGTH = 4;
+export declare const ROOM_ID_BYTES = 16;
+/** Default public relay; bare `<roomId>#<key>` links resolve against it. */
+export declare const DEFAULT_RELAY_URL = "wss://relay.omp.sh";
+export interface ParsedCollabLink {
+    /** wss://host[:port]/r/<roomId> — no query, no fragment. */
+    wsUrl: string;
+    roomId: string;
+    key: Uint8Array;
+}
+/** Relay → host control message. */
+export type RelayControlToHost = {
+    t: "peer-joined" | "peer-left";
+    peer: number;
+};
+/** Relay → guest control message. */
+export type RelayControlToGuest = {
+    t: "room-closed";
+};
+export type RelayControlMessage = RelayControlToHost | RelayControlToGuest;

package/package.json

@@ -0,0 +1,56 @@
+{
+	"type": "module",
+	"name": "@oh-my-pi/pi-wire",
+	"version": "15.11.8",
+	"description": "Shared wire protocol types for Oh My Pi packages",
+	"homepage": "https://omp.sh",
+	"author": "Can Boluk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/can1357/oh-my-pi.git",
+		"directory": "packages/wire"
+	},
+	"bugs": {
+		"url": "https://github.com/can1357/oh-my-pi/issues"
+	},
+	"keywords": [
+		"wire",
+		"protocol",
+		"types",
+		"collab"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write .",
+		"test": "bun test --parallel"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}

package/src/index.ts

@@ -0,0 +1,360 @@
+/**
+ * Shared wire types for the omp collab live-session protocol.
+ *
+ * Dependency-free JSON shapes produced by `@oh-my-pi/pi-coding-agent`
+ * (`src/collab/protocol.ts` and friends). Browser and test clients import this
+ * package instead of depending on the coding-agent runtime; conformance is
+ * asserted type-only in `packages/coding-agent/test/collab/web-wire.types.ts`.
+ *
+ * Unknown entry/event variants arrive over the wire as plain JSON. The unions
+ * below cover only the variants this client renders; consumers cast at the
+ * JSON boundary and every `switch` keeps a tolerant `default:` branch.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Content blocks
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface TextContent {
+	type: "text";
+	text: string;
+}
+
+export interface ImageContent {
+	type: "image";
+	/** Base64-encoded image data. */
+	data: string;
+	/** e.g. "image/png". */
+	mimeType: string;
+}
+
+export interface ThinkingContent {
+	type: "thinking";
+	thinking: string;
+}
+
+export interface RedactedThinkingContent {
+	type: "redactedThinking";
+	data: string;
+}
+
+export interface ToolCallContent {
+	type: "toolCall";
+	id: string;
+	name: string;
+	arguments: Record<string, unknown>;
+	intent?: string;
+}
+
+export type AssistantContent = TextContent | ThinkingContent | RedactedThinkingContent | ToolCallContent;
+
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+
+export interface WireUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	totalTokens: number;
+	cost: { total: number };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Messages
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface UserMessage {
+	role: "user";
+	content: string | (TextContent | ImageContent)[];
+	/** True if the message was injected by the system (e.g. auto-continue). */
+	synthetic?: boolean;
+	/** Unix timestamp in milliseconds. */
+	timestamp: number;
+}
+
+export interface DeveloperMessage {
+	role: "developer";
+	content: string | (TextContent | ImageContent)[];
+	timestamp: number;
+}
+
+export interface AssistantMessage {
+	role: "assistant";
+	content: AssistantContent[];
+	model: string;
+	usage: WireUsage;
+	stopReason: StopReason;
+	errorMessage?: string;
+	timestamp: number;
+}
+
+export interface ToolResultMessage {
+	role: "toolResult";
+	toolCallId: string;
+	toolName: string;
+	content: (TextContent | ImageContent)[];
+	details?: unknown;
+	isError: boolean;
+	timestamp: number;
+}
+
+export type WireMessage = UserMessage | DeveloperMessage | AssistantMessage | ToolResultMessage;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Session entries (rendered subset; cast `as SessionEntry` at the JSON
+// boundary and skip unknown `type`s in a tolerant `default:`)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SessionHeader {
+	type: "session";
+	id: string;
+	title?: string;
+	timestamp: string;
+	cwd: string;
+}
+
+export interface EntryBase {
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+}
+
+export interface MessageEntry extends EntryBase {
+	type: "message";
+	message: WireMessage;
+}
+
+export interface CustomMessageEntry extends EntryBase {
+	type: "custom_message";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	details?: unknown;
+	display: boolean;
+}
+
+export interface CompactionEntry extends EntryBase {
+	type: "compaction";
+	summary: string;
+	shortSummary?: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+}
+
+export interface BranchSummaryEntry extends EntryBase {
+	type: "branch_summary";
+	fromId: string;
+	summary: string;
+}
+
+export interface ModelChangeEntry extends EntryBase {
+	type: "model_change";
+	/** Model in "provider/modelId" format. */
+	model: string;
+	role?: string;
+}
+
+export interface ThinkingLevelChangeEntry extends EntryBase {
+	type: "thinking_level_change";
+	thinkingLevel?: string | null;
+}
+
+export type SessionEntry =
+	| MessageEntry
+	| CustomMessageEntry
+	| CompactionEntry
+	| BranchSummaryEntry
+	| ModelChangeEntry
+	| ThinkingLevelChangeEntry;
+
+/** customType of collab guest prompts injected on the host. */
+export const COLLAB_PROMPT_MESSAGE_TYPE = "collab-prompt";
+
+/** `details` shape of `custom_message` entries with `customType === "collab-prompt"`. */
+export interface CollabPromptDetails {
+	from?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Events (handled subset)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type AgentEvent =
+	| { type: "agent_start" }
+	| { type: "agent_end" }
+	| { type: "turn_start" }
+	| { type: "turn_end" }
+	| { type: "message_start"; message: WireMessage }
+	/** Carries the FULL accumulating partial message — no delta tracking needed. */
+	| { type: "message_update"; message: WireMessage }
+	| { type: "message_end"; message: WireMessage }
+	| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: unknown; intent?: string }
+	| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: unknown; partialResult: unknown }
+	| { type: "tool_execution_end"; toolCallId: string; toolName: string; result: unknown; isError?: boolean }
+	| { type: "notice"; level: "info" | "warning" | "error"; message: string; source?: string }
+	| { type: "auto_compaction_start"; reason: string; action: string }
+	| { type: "auto_compaction_end"; aborted: boolean; willRetry: boolean; errorMessage?: string; skipped?: boolean }
+	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
+	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
+	| { type: "thinking_level_changed"; thinkingLevel?: string };
+
+// ═══════════════════════════════════════════════════════════════════════════
+// State & agents
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface WireModel {
+	id: string;
+	name: string;
+	provider: string;
+	contextWindow: number;
+}
+
+export interface ContextUsage {
+	tokens: number | null;
+	contextWindow: number;
+	percent: number | null;
+}
+
+export interface Participant {
+	name: string;
+	role: "host" | "guest";
+}
+
+/** Debounced footer snapshot broadcast by the host. */
+export interface SessionState {
+	isStreaming: boolean;
+	queuedMessageCount: number;
+	sessionName?: string;
+	/** Host cwd — display only; the guest never chdirs. */
+	cwd: string;
+	model?: WireModel;
+	thinkingLevel?: string;
+	contextUsage?: ContextUsage;
+	participants: Participant[];
+}
+
+export interface AgentSnapshot {
+	id: string;
+	displayName: string;
+	kind: "main" | "sub";
+	parentId?: string;
+	status: "running" | "idle" | "parked" | "aborted";
+	/** Whether the host has a transcript file for this agent (gates remote transcript fetch). */
+	hasSessionFile: boolean;
+	createdAt: number;
+	lastActivity: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Bus payloads (task subagent lifecycle/progress channels)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface AgentProgress {
+	index: number;
+	id: string;
+	agent: string;
+	status: "pending" | "running" | "completed" | "failed" | "aborted";
+	task: string;
+	description?: string;
+	lastIntent?: string;
+	currentTool?: string;
+	currentToolArgs?: string;
+	currentToolStartMs?: number;
+	recentTools: { tool: string; args: string; endMs: number }[];
+	recentOutput: string[];
+	toolCount: number;
+	requests: number;
+	tokens: number;
+	contextTokens?: number;
+	contextWindow?: number;
+	cost: number;
+	durationMs: number;
+	resolvedModel?: string;
+}
+
+export interface SubagentProgressPayload {
+	index: number;
+	agent: string;
+	task: string;
+	parentToolCallId?: string;
+	assignment?: string;
+	progress: AgentProgress;
+	sessionFile?: string;
+}
+
+export interface SubagentLifecyclePayload {
+	id: string;
+	agent: string;
+	description?: string;
+	status: "started" | "completed" | "failed" | "aborted";
+	sessionFile?: string;
+	parentToolCallId?: string;
+	index: number;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Frames (JSON inside the AES-GCM seal)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type GuestFrame =
+	| { t: "hello"; proto: number; name: string }
+	| { t: "prompt"; text: string; images?: ImageContent[] }
+	| { t: "abort" }
+	| { t: "agent-cmd"; cmd: "chat" | "kill" | "revive"; agentId: string; text?: string }
+	| { t: "fetch-transcript"; reqId: number; agentId: string; fromByte: number };
+
+/** EventBus channels mirrored to guests (task subagent traffic only). */
+export type BusChannel = "task:subagent:progress" | "task:subagent:lifecycle";
+
+export type HostFrame =
+	| {
+			t: "welcome";
+			proto: number;
+			header: SessionHeader;
+			entries: SessionEntry[];
+			state: SessionState;
+			agents: AgentSnapshot[];
+	  }
+	| { t: "entry"; entry: SessionEntry }
+	| { t: "event"; event: AgentEvent }
+	| { t: "state"; state: SessionState }
+	/** Mirrored EventBus traffic (task subagent lifecycle/progress channels only). */
+	| { t: "bus"; channel: BusChannel; data: unknown }
+	| { 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 };
+
+export type WireFrame = GuestFrame | HostFrame;
+
+/** Wire protocol version carried in `hello`; the host rejects mismatches. */
+export const COLLAB_PROTO = 1;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Envelope & link constants
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Plaintext envelope prefix: `[4B uint32 BE peerId][sealed payload]`. */
+export const ENVELOPE_HEADER_LENGTH = 4;
+
+export const ROOM_ID_BYTES = 16;
+
+/** Default public relay; bare `<roomId>#<key>` links resolve against it. */
+export const DEFAULT_RELAY_URL = "wss://relay.omp.sh";
+
+export interface ParsedCollabLink {
+	/** wss://host[:port]/r/<roomId> — no query, no fragment. */
+	wsUrl: string;
+	roomId: string;
+	key: Uint8Array;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Relay control messages (TEXT JSON, unencrypted, no session data)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Relay → host control message. */
+export type RelayControlToHost = { t: "peer-joined" | "peer-left"; peer: number };
+/** Relay → guest control message. */
+export type RelayControlToGuest = { t: "room-closed" };
+export type RelayControlMessage = RelayControlToHost | RelayControlToGuest;