@oh-my-pi-zen/pi-wire 16.3.6-zen.1

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## [Unreleased]
+
+## [16.3.0] - 2026-07-02
+
+### Breaking Changes
+
+- Upgraded the collaboration protocol to version 3. Guests using version 2 will now be rejected during the handshake with a protocol-mismatch error.
+
+### Added
+
+- Added support for interactive UI request and response frames, enabling browser guests to respond to prompts initiated by the host.
+
+## [16.1.8] - 2026-06-20
+
+### Breaking Changes
+
+- Bumped `COLLAB_PROTO` to `2`. The `welcome` host frame now carries metadata only (`header`, `state`, `agents`, `entryCount`, optional `readOnly`) — the transcript moves to a new `snapshot-chunk` host frame (`{ entries: SessionEntry[]; final: boolean }`) sent immediately after the welcome. Hosts split large snapshots into multiple chunks; the last chunk carries `final: true`. Old guests speaking proto v1 are rejected with the existing protocol-mismatch error. ([#3144](https://github.com/cagedbird043/oh-my-pi-zen/issues/3144))
+
+## [15.12.4] - 2026-06-13
+
+### Changed
+
+- Changed `WireModel.contextWindow` and `ContextUsage.contextWindow` to `number | null` to allow representing unavailable context-window values
+
+## [15.12.0] - 2026-06-12
+
+### Added
+
+- Added `readOnly` flags to participant and session payload types to indicate when a guest is connected via a read-only (view) link
+- Added `writeToken` to `GuestFrame` hello payloads and parsed collaboration links so full-access links can carry and expose a write-capability token
+- Added `ROOM_KEY_BYTES` and `WRITE_TOKEN_BYTES` constants for room key and write-token sizing in the wire protocol
+- Added `DEFAULT_SHARE_URL` (`https://my.omp.sh/s`), the default share viewer/upload base for `/share` links
+
+## [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-zen/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-zen/pi-coding-agent`) and browser guest (`@oh-my-pi-zen/collab-web`).
+
+## Exports
+
+```ts
+import type { GuestFrame, HostFrame, SessionEntry } from "@oh-my-pi-zen/pi-wire";
+import { COLLAB_PROTO, DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH } from "@oh-my-pi-zen/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,456 @@
+/**
+ * Shared wire types for the omp collab live-session protocol.
+ *
+ * Dependency-free JSON shapes produced by `@oh-my-pi-zen/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 | null;
+}
+export interface ContextUsage {
+    tokens: number | null;
+    contextWindow: number | null;
+    percent: number | null;
+}
+export interface Participant {
+    name: string;
+    role: "host" | "guest";
+    /** True when the guest joined through a read-only (view) link. */
+    readOnly?: boolean;
+}
+/** 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[];
+    isAborting?: boolean;
+}
+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 CollabUiSelectItem = string | {
+    label: string;
+    description?: string;
+};
+export type CollabUiResponseValue = string | undefined;
+export type CollabUiRequestDraft = {
+    kind: "select";
+    title: string;
+    options: CollabUiSelectItem[];
+    initialIndex?: number;
+    selectionMarker?: "radio" | "checkbox";
+    checkedIndices?: number[];
+    markableCount?: number;
+    helpText?: string;
+} | {
+    kind: "editor";
+    title: string;
+    prefill?: string;
+};
+export type CollabUiRequest = CollabUiRequestDraft & {
+    reqId: number;
+};
+export type GuestFrame = {
+    t: "hello";
+    proto: number;
+    name: string;
+    /**
+     * base64url write token proving full-link possession; absent for
+     * read-only (view) links. The host marks peers without a valid token
+     * read-only and rejects their mutating frames.
+     */
+    writeToken?: string;
+} | {
+    t: "prompt";
+    text: string;
+    images?: ImageContent[];
+} | {
+    t: "ui-response";
+    reqId: number;
+    value?: CollabUiResponseValue;
+} | {
+    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;
+    state: SessionState;
+    agents: AgentSnapshot[];
+    /**
+     * Total number of `SessionEntry` items the host will deliver in the
+     * `snapshot-chunk` frames that follow. Guests stay in the loading
+     * phase until they have accumulated all of them (or a chunk arrives
+     * with `final: true`).
+     */
+    entryCount: number;
+    /** True when this peer joined through a read-only (view) link. */
+    readOnly?: boolean;
+}
+/**
+ * Targeted snapshot fragment delivered after `welcome`. Hosts split the
+ * transcript into chunks bounded by byte size so a multi-MB session is not
+ * forced through one giant frame the relay may stall on. The last chunk
+ * carries `final: true`; guests finalize the replica on that frame.
+ */
+ | {
+    t: "snapshot-chunk";
+    entries: SessionEntry[];
+    final: boolean;
+} | {
+    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[];
+} | {
+    t: "ui-request";
+    request: CollabUiRequest;
+} | {
+    t: "ui-request-end";
+    reqId: number;
+}
+/** 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.
+ *
+ * - `1` (legacy): `welcome` carried the full `entries` array inline.
+ * - `2`: `welcome` carries only metadata (header/state/agents/entryCount);
+ *   transcript entries follow in `snapshot-chunk` frames, so multi-MB
+ *   sessions are not gated on a single welcome frame fitting under the
+ *   guest's first-welcome timeout.
+ * - `3`: host asks guests through `ui-request`/`ui-request-end` host frames
+ *   answered by the `ui-response` guest frame. Guests that predate the
+ *   grammar would silently drop `ui-request` (asks hang forever on the
+ *   host), so they must be rejected at hello.
+ */
+export declare const COLLAB_PROTO = 3;
+/** Parameter key used for intent tracing (e.g. prompt explanation/reasoning) */
+export declare const INTENT_FIELD = "i";
+/** Plaintext envelope prefix: `[4B uint32 BE peerId][sealed payload]`. */
+export declare const ENVELOPE_HEADER_LENGTH = 4;
+export declare const ROOM_ID_BYTES = 16;
+/** AES-256-GCM room key; the seal key for every collab frame. */
+export declare const ROOM_KEY_BYTES = 32;
+/**
+ * Random write token appended to the room key in full links
+ * (`base64url(key ∥ token)`); view links carry the bare key. Possession
+ * proves prompt/abort/agent-cmd capability to the host.
+ */
+export declare const WRITE_TOKEN_BYTES = 16;
+/** Default public relay; bare `<roomId>.<key>` links resolve against it. */
+export declare const DEFAULT_RELAY_URL = "wss://my.omp.sh";
+/** Default share viewer/upload base; `/share` links resolve against `<base>/<id>#<key>`. */
+export declare const DEFAULT_SHARE_URL = "https://my.omp.sh/s";
+export interface ParsedCollabLink {
+    /** wss://host[:port]/r/<roomId> — no query, no fragment. */
+    wsUrl: string;
+    roomId: string;
+    key: Uint8Array;
+    /** Write token from a full link; absent for read-only (view) links. */
+    writeToken?: 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-zen/pi-wire",
+	"version": "16.3.6-zen.1",
+	"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/cagedbird043/oh-my-pi-zen.git",
+		"directory": "packages/wire"
+	},
+	"bugs": {
+		"url": "https://github.com/cagedbird043/oh-my-pi-zen/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,444 @@
+/**
+ * Shared wire types for the omp collab live-session protocol.
+ *
+ * Dependency-free JSON shapes produced by `@oh-my-pi-zen/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 | null;
+}
+
+export interface ContextUsage {
+	tokens: number | null;
+	contextWindow: number | null;
+	percent: number | null;
+}
+
+export interface Participant {
+	name: string;
+	role: "host" | "guest";
+	/** True when the guest joined through a read-only (view) link. */
+	readOnly?: boolean;
+}
+
+/** 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[];
+	isAborting?: boolean;
+}
+
+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 CollabUiSelectItem = string | { label: string; description?: string };
+
+export type CollabUiResponseValue = string | undefined;
+
+export type CollabUiRequestDraft =
+	| {
+			kind: "select";
+			title: string;
+			options: CollabUiSelectItem[];
+			initialIndex?: number;
+			selectionMarker?: "radio" | "checkbox";
+			checkedIndices?: number[];
+			markableCount?: number;
+			helpText?: string;
+	  }
+	| {
+			kind: "editor";
+			title: string;
+			prefill?: string;
+	  };
+
+export type CollabUiRequest = CollabUiRequestDraft & { reqId: number };
+
+export type GuestFrame =
+	| {
+			t: "hello";
+			proto: number;
+			name: string;
+			/**
+			 * base64url write token proving full-link possession; absent for
+			 * read-only (view) links. The host marks peers without a valid token
+			 * read-only and rejects their mutating frames.
+			 */
+			writeToken?: string;
+	  }
+	| { t: "prompt"; text: string; images?: ImageContent[] }
+	| { t: "ui-response"; reqId: number; value?: CollabUiResponseValue }
+	| { 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;
+			state: SessionState;
+			agents: AgentSnapshot[];
+			/**
+			 * Total number of `SessionEntry` items the host will deliver in the
+			 * `snapshot-chunk` frames that follow. Guests stay in the loading
+			 * phase until they have accumulated all of them (or a chunk arrives
+			 * with `final: true`).
+			 */
+			entryCount: number;
+			/** True when this peer joined through a read-only (view) link. */
+			readOnly?: boolean;
+	  }
+	/**
+	 * Targeted snapshot fragment delivered after `welcome`. Hosts split the
+	 * transcript into chunks bounded by byte size so a multi-MB session is not
+	 * forced through one giant frame the relay may stall on. The last chunk
+	 * carries `final: true`; guests finalize the replica on that frame.
+	 */
+	| { t: "snapshot-chunk"; entries: SessionEntry[]; final: boolean }
+	| { 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[] }
+	| { t: "ui-request"; request: CollabUiRequest }
+	| { t: "ui-request-end"; reqId: number }
+	/** 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.
+ *
+ * - `1` (legacy): `welcome` carried the full `entries` array inline.
+ * - `2`: `welcome` carries only metadata (header/state/agents/entryCount);
+ *   transcript entries follow in `snapshot-chunk` frames, so multi-MB
+ *   sessions are not gated on a single welcome frame fitting under the
+ *   guest's first-welcome timeout.
+ * - `3`: host asks guests through `ui-request`/`ui-request-end` host frames
+ *   answered by the `ui-response` guest frame. Guests that predate the
+ *   grammar would silently drop `ui-request` (asks hang forever on the
+ *   host), so they must be rejected at hello.
+ */
+export const COLLAB_PROTO = 3;
+
+/** Parameter key used for intent tracing (e.g. prompt explanation/reasoning) */
+export const INTENT_FIELD = "i";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Envelope & link constants
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Plaintext envelope prefix: `[4B uint32 BE peerId][sealed payload]`. */
+export const ENVELOPE_HEADER_LENGTH = 4;
+
+export const ROOM_ID_BYTES = 16;
+
+/** AES-256-GCM room key; the seal key for every collab frame. */
+export const ROOM_KEY_BYTES = 32;
+
+/**
+ * Random write token appended to the room key in full links
+ * (`base64url(key ∥ token)`); view links carry the bare key. Possession
+ * proves prompt/abort/agent-cmd capability to the host.
+ */
+export const WRITE_TOKEN_BYTES = 16;
+
+/** Default public relay; bare `<roomId>.<key>` links resolve against it. */
+export const DEFAULT_RELAY_URL = "wss://my.omp.sh";
+
+/** Default share viewer/upload base; `/share` links resolve against `<base>/<id>#<key>`. */
+export const DEFAULT_SHARE_URL = "https://my.omp.sh/s";
+
+export interface ParsedCollabLink {
+	/** wss://host[:port]/r/<roomId> — no query, no fragment. */
+	wsUrl: string;
+	roomId: string;
+	key: Uint8Array;
+	/** Write token from a full link; absent for read-only (view) links. */
+	writeToken?: 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;