Native human collaboration
EXEPERT desktop includes an Experimental native Rust/GPUI collaboration
plane. It is separate from Codex App Server transport: a human-room invitation
does not grant Codex access, and a Codex controller grant does not join a human
room. The feature was inspired by Kairu's hl-plugins multiplayer experiment,
but its protocol, runtime, reducer, and GPUI are original EXEPERT code. See the
repository third-party notices for attribution.
Topology and trust boundary
The embedded host binds only to loopback. The user supplies any public WSS
endpoint, certificate, DNS, tunnel, proxy, and port routing. EXEPERT rejects a
remote plaintext WebSocket and does not provide a certificate bypass. A
host sees COPY UPSTREAM after the room starts; it copies the current
ephemeral ws://127.0.0.1:<port> target for the external TLS proxy. That target
changes when a new room is hosted, so the proxy route must be updated before
sharing the invitation. EXEPERT never edits or provisions that route. A
32-byte room token is generated in memory when hosting. The explicit
exepert-collab-v1: invitation contains the room ID, public WSS endpoint, and
token; it expires when the host ends the room and is never persisted.
Only the display handle and popup-open preference are stored in
collaboration-settings.json. Messages, peer IDs, presence, typing, leases,
room tokens, invitations, and wire payloads remain process-local and are
excluded from diagnostics and runtime logs.
Protocol v1
The host assigns peer IDs, sender identity, sequence numbers, and timestamps. Client-supplied sender or host-ordering fields are rejected. Protocol v1 covers authentication, welcome/history, presence, typing, text messages, lease acquire/renew/release, disconnect, room end, and bounded safe errors.
| Limit | Value |
|---|---|
| Peers | 8 |
| In-memory messages | 500 |
| Message length | 4,000 characters |
| WebSocket frame | 32 KiB |
| Lease renewal | 5 seconds |
| Lease expiry | 15 seconds |
Unknown, binary, malformed, oversized, spoofed, or abusive frames disconnect the offending peer. Typing updates and chat messages are throttled/rate-limited, lease traffic is separately rate-limited, and bounded outbound queues prevent a slow peer from blocking the room. Stalled WebSocket handshakes time out.
Native popup
The non-modal CHAT trigger is the first global activity-rail action in Full density, above Inspector when available and Settings. When the rail is hidden, the Ctrl+K Open human collaboration quick action and Attention panel provide the fallback. The opaque popup is approximately 390 by 520 pixels and clamps to an 8 px viewport margin. It opens beside the rail in Full density and 8 px from the window's left edge in Sidebar Only or Focus, with its bottom aligned to the workspace gutter. It shows connection state, peer count, unread count, messages, and typing status.
Closing collapses the panel without disconnecting; outside clicks do not close
it. Escape collapses, restoring the rail trigger only when that origin remains
mounted and otherwise restoring the active stage. Enter sends and
Shift+Enter inserts a newline. A density change away from Full closes a rail-
origin panel before navigation motion, preventing a hidden focus or UI
Automation descendant.
Completed authoritative Codex agent messages expose Share to Human Chat. Sharing always opens a bounded plain-text preview with server/task attribution and requires confirmation. Prompts, hidden reasoning, tool output, approvals, attachments, credentials, and whole transcripts are never shared automatically.
Cooperative controller leases
Leases are keyed by (server_id, thread_id). Only the current EXEPERT holder
may start or steer turns, interrupt work, or answer approvals. Remote writes
always require membership in the active human room; LOCAL tasks honor leases
while a room is active and keep the existing confirmed takeover behavior
outside a room.
Take Control follows this order: user confirmation, lease acquisition,
thread/resume, matching successful acknowledgement, then editable composer.
Failure releases the lease and leaves the mirror read-only. A peer facing an
occupied lease can wait/mirror or fork; it cannot revoke the holder. A new fork
receives its own lease only after the App Server acknowledges its new task.
This is cooperative coordination, not an App Server security boundary. A CLI or any client holding the App Server capability token can connect directly and bypass EXEPERT leases.
Lifecycle and non-goals
The host ending or exiting closes the room and notifies peers. A joining peer leaves without ending the host. EXEPERT releases its leases during shutdown; leases also expire after missed renewal. The v1 feature intentionally has no host handoff, intent commands, file transfer, recent-room list, durable history, or automatic AI transcript stream.