@adhdev/mesh-shared 1.0.60-rc.33 → 1.0.60-rc.35

package/src/protocol/dashboard-daemon-p2p.ts

@@ -0,0 +1,272 @@
+/**
+ * protocol/dashboard-daemon-p2p — the dashboard ↔ daemon WebRTC DataChannel
+ * link (`data` channel, JSON frames; screenshots ride the same channel as
+ * binary and are not frames).
+ *
+ * Wiring-unification Phase A2 (docs/design/2026-09-23-wiring-unification.md §3 A2).
+ *
+ * Before this file ~20 kinds were matched as bare string literals on both ends
+ * (web-cloud `p2p.ts`, daemon-cloud `data-channel-router.ts`), the shared
+ * `DashboardP2PMessageKind` listed 12 of them and was imported by nothing, and
+ * the daemon's file-operation replies carried no `type` at all — the browser
+ * matched them by `id` as a fallthrough. They are now `response` frames; the
+ * browser decoder still accepts the typeless legacy shape from older daemons.
+ *
+ * Chunking: any request frame may be split by the sender into
+ * `<kind>_chunk` frames (`id`, `chunkId`, `index`, `total`, `data`) when it
+ * exceeds `MESH_MAX_INLINE_FRAME_BYTES` (../rpc-chunking.ts). Each direction
+ * reassembles BEFORE decoding, so the decoders see whole frames; the chunk
+ * envelope is typed here so the splitter and the reassembler agree.
+ *
+ * Content boundary: this is the P2P plane — rich session data (chat, prompts,
+ * transcripts, PTY output) is CORRECT here and must not be reduced.
+ */
+
+import {
+    type CommandPayload,
+    type MessageId,
+    type AssertSameMembers,
+    isRecord,
+    isNonEmptyString,
+    makeTypeGuard,
+} from './envelope'
+import type { DaemonStatusEventWirePayload } from './daemon-server'
+
+// ─── Chunk envelope (both directions) ──────────────────────────────────────
+
+export type ChunkFrame<T extends string> = {
+    type: T
+    /** Request id of the frame being split, when it has one. */
+    id?: MessageId
+    chunkId: string
+    index: number
+    total: number
+    data: string
+}
+
+export function isChunkType(value: unknown): value is `${string}_chunk` {
+    return typeof value === 'string' && value.endsWith('_chunk') && value.length > '_chunk'.length
+}
+
+function readChunkFields(frame: Record<string, unknown>): Omit<ChunkFrame<string>, 'type'> | null {
+    if (!isNonEmptyString(frame.chunkId)) return null
+    if (!Number.isInteger(frame.index) || !Number.isInteger(frame.total)) return null
+    if (typeof frame.data !== 'string') return null
+    return {
+        ...(isNonEmptyString(frame.id) ? { id: frame.id } : {}),
+        chunkId: frame.chunkId,
+        index: frame.index as number,
+        total: frame.total as number,
+        data: frame.data,
+    }
+}
+
+// ─── Dashboard → Daemon ────────────────────────────────────────────────────
+
+export const DASHBOARD_TO_DAEMON_P2P_TYPES = [
+    'ping',
+    'pong',
+    'command',
+    'input',
+    'pty_input',
+    'pty_resize',
+    'screenshot_start',
+    'screenshot_stop',
+    'subscribe',
+    'unsubscribe',
+    'seqscribe_session_interest',
+    'read',
+    'write',
+    'list',
+] as const
+export type DashboardToDaemonP2PType = typeof DASHBOARD_TO_DAEMON_P2P_TYPES[number]
+export const isDashboardToDaemonP2PType = makeTypeGuard(DASHBOARD_TO_DAEMON_P2P_TYPES)
+
+export type DashboardToDaemonChunkType = `${DashboardToDaemonP2PType}_chunk`
+export function isDashboardToDaemonChunkType(value: unknown): value is DashboardToDaemonChunkType {
+    return isChunkType(value) && isDashboardToDaemonP2PType(value.slice(0, -'_chunk'.length))
+}
+
+export type P2PPingMsg = { type: 'ping'; ts: number }
+export type P2PPongMsg = { type: 'pong'; ts: number }
+/** A command routed through the daemon's command router; `commandType`/`data` are dynamic by design. */
+export type P2PCommandMsg = { type: 'command'; id: MessageId; commandType: string; data: CommandPayload }
+/** Remote-desktop input (click/type/key) for the target session's IDE surface. */
+export type P2PInputMsg = { type: 'input'; id: MessageId; action: string; params: CommandPayload; targetSessionId?: string }
+/** Raw PTY input. `sessionId` is canonical; `targetSessionId` is the accepted alias. */
+export type P2PPtyInputMsg = { type: 'pty_input'; sessionId?: string; targetSessionId?: string; data: string }
+export type P2PPtyResizeMsg = { type: 'pty_resize'; sessionId: string; cols: number; rows: number }
+export type P2PScreenshotStartMsg = { type: 'screenshot_start'; targetSessionId: string }
+export type P2PScreenshotStopMsg = { type: 'screenshot_stop'; targetSessionId?: string }
+/** Topic subscription. `params` is topic-specific (daemon-core `SubscribeRequestMap`); `object` keeps every topic's interface assignable. */
+export type P2PSubscribeMsg = { type: 'subscribe'; topic: string; key: string; params: object }
+export type P2PUnsubscribeMsg = { type: 'unsubscribe'; topic: string; key: string }
+/** Which sessions this peer wants replicated over the seqscribe lane; also the peer's responder proof. */
+export type P2PSessionInterestMsg = { type: 'seqscribe_session_interest'; sessionIds: readonly string[] }
+export type P2PFileReadMsg = { type: 'read'; id: MessageId; path: string }
+export type P2PFileWriteMsg = { type: 'write'; id: MessageId; path: string; content: string }
+export type P2PFileListMsg = { type: 'list'; id: MessageId; path: string }
+export type DashboardToDaemonChunkMsg = ChunkFrame<DashboardToDaemonChunkType>
+
+export type DashboardToDaemonP2PMsg =
+    | P2PPingMsg
+    | P2PPongMsg
+    | P2PCommandMsg
+    | P2PInputMsg
+    | P2PPtyInputMsg
+    | P2PPtyResizeMsg
+    | P2PScreenshotStartMsg
+    | P2PScreenshotStopMsg
+    | P2PSubscribeMsg
+    | P2PUnsubscribeMsg
+    | P2PSessionInterestMsg
+    | P2PFileReadMsg
+    | P2PFileWriteMsg
+    | P2PFileListMsg
+
+const _dashboardToDaemonNamesCoverUnion: AssertSameMembers<typeof DASHBOARD_TO_DAEMON_P2P_TYPES, DashboardToDaemonP2PMsg['type']> = true
+void _dashboardToDaemonNamesCoverUnion
+
+/** Request kinds the daemon answers by `id`; a frame without one cannot be answered and is dropped at the boundary. */
+const DASHBOARD_REQUEST_TYPES = new Set<DashboardToDaemonP2PType>(['command', 'input', 'read', 'write', 'list'])
+
+/** Parse boundary for the daemon's chunk reassembler: one `<kind>_chunk` piece of a split request. */
+export function decodeDashboardToDaemonP2PChunk(raw: unknown): DashboardToDaemonChunkMsg | null {
+    if (!isRecord(raw) || !isDashboardToDaemonChunkType(raw.type)) return null
+    const fields = readChunkFields(raw)
+    return fields ? { type: raw.type, ...fields } : null
+}
+
+/**
+ * Parse boundary for the daemon (after chunk reassembly): a whole request.
+ * Chunk pieces are not requests and decode to null here; see
+ * `decodeDashboardToDaemonP2PChunk`.
+ */
+export function decodeDashboardToDaemonP2P(raw: unknown): DashboardToDaemonP2PMsg | null {
+    if (!isRecord(raw) || !isDashboardToDaemonP2PType(raw.type)) return null
+    if (DASHBOARD_REQUEST_TYPES.has(raw.type) && !isNonEmptyString(raw.id)) return null
+    return raw as DashboardToDaemonP2PMsg
+}
+
+// ─── Daemon → Dashboard ────────────────────────────────────────────────────
+
+export const DAEMON_TO_DASHBOARD_P2P_TYPES = [
+    'ping',
+    'pong',
+    'p2p_evicted',
+    'status_report',
+    'status_event',
+    'topic_update',
+    'topic_update_chunk',
+    'session_output',
+    'session_output_chunk',
+    'session_io_error',
+    'command_result',
+    'command_result_chunk',
+    'response',
+] as const
+export type DaemonToDashboardP2PType = typeof DAEMON_TO_DASHBOARD_P2P_TYPES[number]
+export const isDaemonToDashboardP2PType = makeTypeGuard(DAEMON_TO_DASHBOARD_P2P_TYPES)
+
+/** Rich P2P status snapshot (daemon-core `StatusReportPayload`, or a `_delta` partial of it). Dynamic by design on this plane. */
+export type P2PStatusReportWirePayload = Record<string, unknown>
+
+/** The server-bound event plus the P2P-only structured prompt (daemon-core `P2PStatusEventPayload`). */
+export type P2PStatusEventWirePayload = DaemonStatusEventWirePayload & {
+    interactivePrompt?: unknown
+    promptId?: string
+    multiSelect?: boolean
+}
+
+/** One topic update (daemon-core `TopicUpdateEnvelope`); consumers narrow by `topic`. */
+export type TopicUpdateWireEnvelope = { topic: string; key: string }
+
+export type P2PFileEntry = { name: string; type: string; size?: number }
+
+export type P2PEvictedMsg = { type: 'p2p_evicted'; reason: string; maxconnections: number }
+export type P2PStatusReportMsg = { type: 'status_report'; payload: P2PStatusReportWirePayload; timestamp: number }
+export type P2PStatusEventMsg = { type: 'status_event'; payload: P2PStatusEventWirePayload; timestamp: number }
+export type P2PTopicUpdateMsg = { type: 'topic_update'; update: TopicUpdateWireEnvelope }
+export type P2PTopicUpdateChunkMsg = ChunkFrame<'topic_update_chunk'>
+export type P2PSessionOutputMsg = { type: 'session_output'; sessionId: string; data: string }
+export type P2PSessionOutputChunkMsg = ChunkFrame<'session_output_chunk'> & { sessionId: string }
+export type P2PSessionIoErrorMsg = { type: 'session_io_error'; sessionId: string; reason: string; error?: string }
+/** Result of a `command` frame. The router spreads the handler result in; `resultId` preserves a result-side `id`. */
+export type P2PCommandResultMsg = { type: 'command_result'; id: MessageId; success: boolean; error?: string; resultId?: unknown } & Record<string, unknown>
+export type P2PCommandResultChunkMsg = ChunkFrame<'command_result_chunk'>
+/** Result of an `input` or file (`read`/`write`/`list`) frame. */
+export type P2PResponseMsg = {
+    type: 'response'
+    id: MessageId
+    success: boolean
+    result?: unknown
+    error?: string
+    content?: string
+    entries?: P2PFileEntry[]
+}
+
+export type DaemonToDashboardP2PMsg =
+    | P2PPingMsg
+    | P2PPongMsg
+    | P2PEvictedMsg
+    | P2PStatusReportMsg
+    | P2PStatusEventMsg
+    | P2PTopicUpdateMsg
+    | P2PTopicUpdateChunkMsg
+    | P2PSessionOutputMsg
+    | P2PSessionOutputChunkMsg
+    | P2PSessionIoErrorMsg
+    | P2PCommandResultMsg
+    | P2PCommandResultChunkMsg
+    | P2PResponseMsg
+
+const _daemonToDashboardNamesCoverUnion: AssertSameMembers<typeof DAEMON_TO_DASHBOARD_P2P_TYPES, DaemonToDashboardP2PMsg['type']> = true
+void _daemonToDashboardNamesCoverUnion
+
+/**
+ * Parse boundary for the dashboard (after chunk reassembly).
+ *
+ * A typeless `{ id, success }` frame is a file/input reply from a daemon that
+ * predates the `response` kind; it is promoted here so the union stays
+ * exhaustive while the fleet rolls forward.
+ */
+export function decodeDaemonToDashboardP2P(raw: unknown): DaemonToDashboardP2PMsg | null {
+    if (!isRecord(raw)) return null
+    if (raw.type === undefined && isNonEmptyString(raw.id) && typeof raw.success === 'boolean') {
+        return { ...raw, type: 'response' } as P2PResponseMsg
+    }
+    if (!isDaemonToDashboardP2PType(raw.type)) return null
+    switch (raw.type) {
+        case 'ping':
+        case 'pong':
+        case 'p2p_evicted':
+            return raw as DaemonToDashboardP2PMsg
+        case 'status_report':
+        case 'status_event':
+            return isRecord(raw.payload) ? (raw as DaemonToDashboardP2PMsg) : null
+        case 'topic_update':
+            return isRecord(raw.update) ? (raw as P2PTopicUpdateMsg) : null
+        case 'topic_update_chunk':
+        case 'command_result_chunk':
+        case 'session_output_chunk': {
+            const fields = readChunkFields(raw)
+            if (!fields) return null
+            if (raw.type === 'session_output_chunk') {
+                return isNonEmptyString(raw.sessionId) ? { type: raw.type, sessionId: raw.sessionId, ...fields } : null
+            }
+            return { type: raw.type, ...fields }
+        }
+        case 'session_output':
+            return isNonEmptyString(raw.sessionId) && typeof raw.data === 'string' ? (raw as P2PSessionOutputMsg) : null
+        case 'session_io_error':
+            return isNonEmptyString(raw.sessionId) ? (raw as P2PSessionIoErrorMsg) : null
+        case 'command_result':
+        case 'response':
+            return isNonEmptyString(raw.id) ? (raw as DaemonToDashboardP2PMsg) : null
+    }
+}
+
+/** Both directions, for the legacy `DashboardP2PMessageKind` name and the drift gate. */
+export const DASHBOARD_P2P_MESSAGE_KINDS = [
+    ...new Set<string>([...DASHBOARD_TO_DAEMON_P2P_TYPES, ...DAEMON_TO_DASHBOARD_P2P_TYPES]),
+] as ReadonlyArray<DashboardToDaemonP2PType | DaemonToDashboardP2PType>

package/src/protocol/dashboard-server.ts

@@ -0,0 +1,340 @@
+/**
+ * protocol/dashboard-server — the dashboard ↔ UserSessionDO WebSocket link,
+ * plus the share-viewer ↔ SharedSessionDO link the same dashboard bundle speaks.
+ *
+ * Wiring-unification Phase A2 (docs/design/2026-09-23-wiring-unification.md §3 A2).
+ *
+ * Before this file web-cloud `ws.ts` declared its own `IncomingWSMessage`
+ * union and `WSEventType`, the server built every outbound frame as an object
+ * literal, and the two disagreed: the server's `connected` frame was missing
+ * from the dashboard's type, while the dashboard typed `plan_limit_error`,
+ * `plan_limit_warning`, `daemon_screenshot` and `agent_event` that no server
+ * path has emitted since the dashboard WS command relay was removed. Those four
+ * are gone; `connected` is in.
+ *
+ * Content boundary: this link is server WS. It carries routing metadata,
+ * signaling and the approved approval-modal text only (`modalMessage` /
+ * `modalButtons`). Chat content rides the P2P link (./dashboard-daemon-p2p.ts).
+ */
+
+import {
+    type Envelope,
+    type AssertSameMembers,
+    isRecord,
+    makeTypeGuard,
+    readEnvelopeFields,
+} from './envelope'
+import {
+    DAEMON_STATUS_EVENT_NAMES,
+    type DaemonStatusEventName,
+    type P2PIceWirePayload,
+    type P2POfferWirePayload,
+    type P2PStatusWireSummary,
+    type SeqscribeStatusWireSummary,
+    type ReleaseChannelWire,
+    type VersionUpdatePolicyWire,
+    type VersionUpdateReasonWire,
+} from './daemon-server'
+
+// ─── Status events as delivered to a dashboard ─────────────────────────────
+
+/** Server-originated events the dashboard receives in addition to the daemon set. */
+export const SERVER_STATUS_EVENT_NAMES = [
+    'daemon:disconnect',
+    'team:session_viewed',
+    'team:view_request',
+    'team:view_request_approved',
+    'team:view_request_rejected',
+] as const
+
+/** Mirror of daemon-core `DashboardStatusEventName`; pinned equal by the server at compile time. */
+export const DASHBOARD_STATUS_EVENT_NAMES = [...DAEMON_STATUS_EVENT_NAMES, ...SERVER_STATUS_EVENT_NAMES] as const
+export type DashboardStatusEventName = DaemonStatusEventName | typeof SERVER_STATUS_EVENT_NAMES[number]
+export const isDashboardStatusEventName = makeTypeGuard(DASHBOARD_STATUS_EVENT_NAMES)
+
+const _dashboardStatusEventNamesCoverUnion: AssertSameMembers<typeof DASHBOARD_STATUS_EVENT_NAMES, DashboardStatusEventName> = true
+void _dashboardStatusEventNamesCoverUnion
+
+/**
+ * Sanitized status event as the server relays it (UserSession
+ * `buildDashboardStatusEvent`). Mirror of daemon-core
+ * `DashboardStatusEventPayload` minus the P2P-only structured prompt fields
+ * (`interactivePrompt`/`promptId`/`multiSelect`), which the WS relay never
+ * carries — they are agent-authored content.
+ */
+export type DashboardStatusEventWirePayload = {
+    event: DashboardStatusEventName
+    timestamp: number
+    daemonId?: string
+    providerType?: string
+    targetSessionId?: string
+    duration?: number
+    elapsedSec?: number
+    modalMessage?: string
+    modalButtons?: string[]
+    requestId?: string
+    requesterName?: string
+    targetName?: string
+    orgId?: string
+    permission?: string
+    shareUrl?: string
+    shareToken?: string
+    viewerName?: string
+}
+
+// ─── Bootstrap ─────────────────────────────────────────────────────────────
+
+/**
+ * Cold-start machine card. Mirror of daemon-core `DashboardBootstrapDaemonEntry`
+ * (which extends `Partial<CloudDaemonSummaryEntry>`), field for field, so the
+ * server's entry assigns in and the dashboard's daemon-core-typed consumer
+ * assigns out without a cast.
+ */
+export type BootstrapDaemonWireEntry = {
+    id: string
+    type?: string
+    machineId?: string
+    platform?: string
+    hostname?: string
+    nickname?: string
+    version?: string
+    p2p?: P2PStatusWireSummary
+    seqscribe?: SeqscribeStatusWireSummary
+    cdpConnected?: boolean
+    serverVersion?: string
+    releaseChannel?: ReleaseChannelWire
+    updateChannel?: ReleaseChannelWire
+    updatePolicy?: VersionUpdatePolicyWire
+    updateCommand?: string
+    versionMismatch?: boolean
+    versionUpdateRequired?: boolean
+    versionUpdateReason?: VersionUpdateReasonWire
+    timestamp?: number
+}
+
+export const SYSTEM_ANNOUNCEMENT_TYPES = ['info', 'warning', 'critical'] as const
+export type SystemAnnouncementTypeWire = typeof SYSTEM_ANNOUNCEMENT_TYPES[number]
+
+/** Admin-authored banner; `null` clears it. Mirror of server `ActiveSystemAnnouncement` / web-cloud `SystemAnnouncement`. */
+export type SystemAnnouncementWire = {
+    id: string
+    message: string
+    type: SystemAnnouncementTypeWire
+    createdAt: string | null
+    expiresAt: string | null
+}
+
+export type DashboardBootstrapWirePayload = {
+    daemons: BootstrapDaemonWireEntry[]
+    announcement?: SystemAnnouncementWire | null
+}
+
+export type DashboardConnectedWirePayload = {
+    message?: string
+    peerId: string
+    plan: string
+    dashboardCount: number
+}
+
+/** Daemon auth rejection relayed to the owner's dashboards — enum reason and counters only (no server-authored sentence). */
+export type DashboardAuthErrorWirePayload = {
+    reason: string
+    limit?: number
+    current?: number
+}
+
+export type SystemAnnouncementWirePayload = {
+    announcement: SystemAnnouncementWire | null
+}
+
+// ─── Signaling payloads (server → dashboard, from the daemon offerer) ───────
+
+export type DashboardP2POfferWirePayload = {
+    daemonId: string
+    peerId?: string
+    sdp: string
+    type: string
+}
+
+export type DashboardP2PIceWirePayload = {
+    daemonId: string
+    peerId?: string
+    candidate: string
+    mid?: string
+    sdpMid?: string | null
+    sdpMLineIndex?: number | null
+}
+
+// ─── UserSession → Dashboard ───────────────────────────────────────────────
+
+export const USER_SESSION_TO_DASHBOARD_TYPES = [
+    'connected',
+    'initial_state',
+    'daemon_status',
+    'status_event',
+    'system_announcement',
+    'auth_error',
+    'heartbeat',
+    'p2p_offer',
+    'p2p_ice',
+] as const
+export type UserSessionToDashboardType = typeof USER_SESSION_TO_DASHBOARD_TYPES[number]
+export const isUserSessionToDashboardType = makeTypeGuard(USER_SESSION_TO_DASHBOARD_TYPES)
+
+export type DashboardConnectedMsg = Envelope<'connected', DashboardConnectedWirePayload>
+export type DashboardInitialStateMsg = Envelope<'initial_state', DashboardBootstrapWirePayload>
+export type DashboardDaemonStatusMsg = Envelope<'daemon_status', DashboardBootstrapWirePayload>
+export type DashboardStatusEventMsg = Envelope<'status_event', DashboardStatusEventWirePayload>
+export type DashboardSystemAnnouncementMsg = Envelope<'system_announcement', SystemAnnouncementWirePayload>
+export type DashboardAuthErrorMsg = Envelope<'auth_error', DashboardAuthErrorWirePayload>
+/**
+ * Reply to the dashboard's heartbeat. Carries the cached announcement so a
+ * stale banner self-corrects; the field is optional because the reply is first
+ * of all a liveness signal and must not be dropped by an older server's
+ * payload-less spelling.
+ */
+export type DashboardHeartbeatReplyMsg = Envelope<'heartbeat', Partial<SystemAnnouncementWirePayload>>
+export type DashboardP2POfferMsg = Envelope<'p2p_offer', DashboardP2POfferWirePayload>
+export type DashboardP2PIceMsg = Envelope<'p2p_ice', DashboardP2PIceWirePayload>
+
+export type UserSessionToDashboardMsg =
+    | DashboardConnectedMsg
+    | DashboardInitialStateMsg
+    | DashboardDaemonStatusMsg
+    | DashboardStatusEventMsg
+    | DashboardSystemAnnouncementMsg
+    | DashboardAuthErrorMsg
+    | DashboardHeartbeatReplyMsg
+    | DashboardP2POfferMsg
+    | DashboardP2PIceMsg
+
+const _userSessionToDashboardNamesCoverUnion: AssertSameMembers<typeof USER_SESSION_TO_DASHBOARD_TYPES, UserSessionToDashboardMsg['type']> = true
+void _userSessionToDashboardNamesCoverUnion
+
+export type UserSessionToDashboardPayloadOf<T extends UserSessionToDashboardType> = Extract<UserSessionToDashboardMsg, { type: T }>['payload']
+
+/** Parse boundary for the dashboard. A heartbeat reply is accepted without a payload (liveness first). */
+export function decodeUserSessionToDashboard(raw: unknown): UserSessionToDashboardMsg | null {
+    if (!isRecord(raw) || !isUserSessionToDashboardType(raw.type)) return null
+    if (raw.type === 'heartbeat') {
+        return { type: 'heartbeat', payload: isRecord(raw.payload) ? raw.payload : {}, ...readEnvelopeFields(raw) }
+    }
+    if (!isRecord(raw.payload)) return null
+    return { type: raw.type, payload: raw.payload, ...readEnvelopeFields(raw) } as UserSessionToDashboardMsg
+}
+
+// ─── Dashboard → UserSession ───────────────────────────────────────────────
+
+export const DASHBOARD_TO_USER_SESSION_TYPES = ['heartbeat', 'refresh', 'p2p_ready', 'p2p_answer', 'p2p_ice'] as const
+export type DashboardToUserSessionType = typeof DASHBOARD_TO_USER_SESSION_TYPES[number]
+export const isDashboardToUserSessionType = makeTypeGuard(DASHBOARD_TO_USER_SESSION_TYPES)
+
+/** Signals a dashboard (answerer) sends toward a daemon; `daemonId` routes, `peerId` identifies the tab. */
+export const DASHBOARD_P2P_SIGNAL_TYPES = ['p2p_ready', 'p2p_answer', 'p2p_ice'] as const
+export type DashboardP2PSignalType = typeof DASHBOARD_P2P_SIGNAL_TYPES[number]
+export const isDashboardP2PSignalType = makeTypeGuard(DASHBOARD_P2P_SIGNAL_TYPES)
+
+export type DashboardP2PReadyWirePayload = { daemonId: string; peerId: string }
+export type DashboardP2PAnswerWirePayload = { daemonId: string; peerId: string; sdp: string; type: string }
+export type DashboardP2PLocalIceWirePayload = {
+    daemonId: string
+    peerId: string
+    candidate: string
+    sdpMid: string | null
+    sdpMLineIndex: number | null
+}
+
+export type DashboardHeartbeatMsg = { type: 'heartbeat'; timestamp?: number }
+export type DashboardRefreshMsg = { type: 'refresh' }
+export type DashboardP2PReadyMsg = Envelope<'p2p_ready', DashboardP2PReadyWirePayload>
+export type DashboardP2PAnswerMsg = Envelope<'p2p_answer', DashboardP2PAnswerWirePayload>
+export type DashboardP2PLocalIceMsg = Envelope<'p2p_ice', DashboardP2PLocalIceWirePayload>
+
+export type DashboardToUserSessionMsg =
+    | DashboardHeartbeatMsg
+    | DashboardRefreshMsg
+    | DashboardP2PReadyMsg
+    | DashboardP2PAnswerMsg
+    | DashboardP2PLocalIceMsg
+
+const _dashboardToUserSessionNamesCoverUnion: AssertSameMembers<typeof DASHBOARD_TO_USER_SESSION_TYPES, DashboardToUserSessionMsg['type']> = true
+void _dashboardToUserSessionNamesCoverUnion
+
+export type DashboardToUserSessionPayloadOf<T extends DashboardP2PSignalType> = Extract<DashboardToUserSessionMsg, { type: T }>['payload']
+
+/** Parse boundary for UserSessionDO. Signals need a `daemonId` to route; without one there is nothing to do. */
+export function decodeDashboardToUserSession(raw: unknown): DashboardToUserSessionMsg | null {
+    if (!isRecord(raw) || !isDashboardToUserSessionType(raw.type)) return null
+    if (raw.type === 'heartbeat') return { type: 'heartbeat', ...readEnvelopeFields(raw) }
+    if (raw.type === 'refresh') return { type: 'refresh' }
+    if (!isRecord(raw.payload) || typeof raw.payload.daemonId !== 'string') return null
+    return { type: raw.type, payload: raw.payload, ...readEnvelopeFields(raw) } as DashboardToUserSessionMsg
+}
+
+// ─── SharedSession ↔ share viewer ──────────────────────────────────────────
+
+export const SHARED_SESSION_TO_VIEWER_TYPES = [
+    'share:connected',
+    'share:revoked',
+    'share:expired',
+    'share:error',
+    'share:viewer_count',
+    'p2p_offer',
+    'p2p_ice',
+] as const
+export type SharedSessionToViewerType = typeof SHARED_SESSION_TO_VIEWER_TYPES[number]
+export const isSharedSessionToViewerType = makeTypeGuard(SHARED_SESSION_TO_VIEWER_TYPES)
+
+/** Frames on this link are FLAT (no `payload`), except the relayed signals. Kept as the viewer page reads them. */
+export type ShareConnectedMsg = {
+    type: 'share:connected'
+    viewerId: string
+    viewerName: string
+    permission: string
+    mode: string
+    providerType: string
+    targetSessionId?: string
+    ownerName: string
+    daemonId: string
+    iceServers: unknown[]
+    requiresAuth: boolean
+}
+export type ShareRevokedMsg = { type: 'share:revoked' }
+export type ShareExpiredMsg = { type: 'share:expired' }
+export type ShareErrorMsg = { type: 'share:error'; error: string }
+export type ShareViewerCountMsg = { type: 'share:viewer_count'; count: number; maxViewers: number }
+/**
+ * Daemon signal relayed to the addressed viewer, payload as the daemon sent it;
+ * `from` is the daemon DO id, which the viewer page folds in as `daemonId`.
+ */
+export type ShareRelayedP2POfferMsg = { type: 'p2p_offer'; payload: P2POfferWirePayload; from: string }
+export type ShareRelayedP2PIceMsg = { type: 'p2p_ice'; payload: P2PIceWirePayload; from: string }
+
+export type SharedSessionToViewerMsg =
+    | ShareConnectedMsg
+    | ShareRevokedMsg
+    | ShareExpiredMsg
+    | ShareErrorMsg
+    | ShareViewerCountMsg
+    | ShareRelayedP2POfferMsg
+    | ShareRelayedP2PIceMsg
+
+const _sharedSessionToViewerNamesCoverUnion: AssertSameMembers<typeof SHARED_SESSION_TO_VIEWER_TYPES, SharedSessionToViewerMsg['type']> = true
+void _sharedSessionToViewerNamesCoverUnion
+
+export const VIEWER_TO_SHARED_SESSION_TYPES = ['p2p_ready', 'p2p_offer', 'p2p_answer', 'p2p_ice'] as const
+export type ViewerToSharedSessionType = typeof VIEWER_TO_SHARED_SESSION_TYPES[number]
+export const isViewerToSharedSessionType = makeTypeGuard(VIEWER_TO_SHARED_SESSION_TYPES)
+
+/** The viewer's signal as sent; the DO stamps `daemonId`/`peerId`/`sharePermission` before relaying. */
+export type ViewerToSharedSessionMsg = Envelope<ViewerToSharedSessionType, Record<string, unknown>>
+
+const _viewerToSharedSessionNamesCoverUnion: AssertSameMembers<typeof VIEWER_TO_SHARED_SESSION_TYPES, ViewerToSharedSessionMsg['type']> = true
+void _viewerToSharedSessionNamesCoverUnion
+
+/** Parse boundary for SharedSessionDO: signaling frames only. */
+export function decodeViewerToSharedSession(raw: unknown): ViewerToSharedSessionMsg | null {
+    if (!isRecord(raw) || !isViewerToSharedSessionType(raw.type)) return null
+    const payload = isRecord(raw.payload) ? raw.payload : {}
+    return { type: raw.type, payload, ...readEnvelopeFields(raw) }
+}

package/src/protocol/envelope.ts

@@ -0,0 +1,75 @@
+/**
+ * protocol/envelope — helpers shared by the three link protocols.
+ *
+ * Wiring-unification Phase A2 (docs/design/2026-09-23-wiring-unification.md).
+ *
+ * Every link (daemon↔server WS, dashboard↔UserSession WS, dashboard↔daemon
+ * P2P DataChannel) is described the same way:
+ *
+ *   - a `const` tuple of message-kind names per direction;
+ *   - a discriminated union of `{ type, ... }` frames derived from it;
+ *   - a `decode<Link><Direction>(raw)` parse-boundary function that checks the
+ *     `type` is a member and the frame carries the MINIMAL shape the union
+ *     promises (an object payload where one is required, the top-level fields
+ *     a payload-less frame is keyed by). Semantic validation — is this session
+ *     id known, is the SDP well formed — stays with the handler that owns it.
+ *
+ * mesh-shared is a dependency-free leaf, so payload types here are STRUCTURAL
+ * mirrors of the richer daemon-core types (`RoutingSessionEntry`,
+ * `DaemonStatusEventPayload`, ...): daemon-core, the server and the web assign
+ * their richer types into these, never the other way round. A type-only import
+ * of daemon-core would make the published `.d.ts` of this package reference a
+ * package that depends on it — a cycle a leaf must not create.
+ */
+
+export type MessageId = string
+
+/** `{ type, payload }` frame with the optional correlation/ordering fields every link uses. */
+export type Envelope<T extends string, P> = {
+    type: T
+    payload: P
+    id?: MessageId
+    timestamp?: number
+}
+
+/** Genuinely dynamic payloads (command arguments and results). Allowed by design; the union stays exhaustive on `type`. */
+export type CommandPayload = Record<string, unknown>
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+    return typeof value === 'string' && value.length > 0
+}
+
+export function isFiniteNumber(value: unknown): value is number {
+    return typeof value === 'number' && Number.isFinite(value)
+}
+
+export function makeTypeGuard<T extends readonly string[]>(names: T): (value: unknown) => value is T[number] {
+    const set: ReadonlySet<string> = new Set(names)
+    return (value: unknown): value is T[number] => typeof value === 'string' && set.has(value)
+}
+
+/**
+ * Compile-time proof that a name tuple and a union have exactly the same
+ * members. Used as `const _: AssertSameMembers<typeof NAMES, Union> = true`.
+ */
+export type AssertSameMembers<Tuple extends readonly string[], Union extends string> =
+    [Exclude<Union, Tuple[number]>, Exclude<Tuple[number], Union>] extends [never, never] ? true : never
+
+/** Narrow a frame's `type` to a union member, or null. */
+export function decodeTypeField<T extends string>(raw: unknown, isType: (value: unknown) => value is T): { type: T; frame: Record<string, unknown> } | null {
+    if (!isRecord(raw)) return null
+    if (!isType(raw.type)) return null
+    return { type: raw.type, frame: raw }
+}
+
+/** Read the optional envelope fields a frame may carry, dropping malformed ones. */
+export function readEnvelopeFields(frame: Record<string, unknown>): { id?: MessageId; timestamp?: number } {
+    return {
+        ...(isNonEmptyString(frame.id) ? { id: frame.id } : {}),
+        ...(isFiniteNumber(frame.timestamp) ? { timestamp: frame.timestamp } : {}),
+    }
+}