Module collaboration

Expand description

Toolkit-side collab client: a synchronous, non-blocking send / poll pair trading typed CollabRequest / CollabEvent frames, stable so every downstream app keeps compiling while the transport underneath changes.

The manager speaks to exactly one CollabTransport, driven from the owner thread’s frame loop: commands go in through CollabTransport::submit, events come out of CollabTransport::drain. The transport owns authentication, signing and verification; the manager never holds a transport key. Durable traffic fails the transport closed on overload; only transient presence may be shed; a document change the transport cannot take is refused with a CollabSendError instead. Without a transport the manager is “disabled” — poll() returns empty and send() is a no-op.

The default transport (feature broker-transport) delegates to the runtime-collab Cap’n Proto broker on a worker thread it owns.

Modules§

channel_key: The routing key one connection names on the capnp transport.
channel_live_activity: An app’s live activity — what it keeps showing outside its windows, a running timer — reached over its collaboration channel.
file_clipboard: The local host’s Files clipboard. Offers are opaque, never path lists.
handoff: Handoff: what the shell and one application instance say to each other while that instance’s window moves to another workspace.
owner_view: Session-local native owner-view control. Documents retain their normal CRDT routes; these messages carry presentation only and grant no focus or input.
participants: Remote participants (agents, collaborators) that hold their own view of a widget, and the retained topology collaboration sessions walk.
record_content: Content an app’s record references, travelling on the record’s route.
semantic_schema: The numbers a semantic checkpoint carries for the portable schemas a signed manifest can declare (continuity.semantic_schema). The tag says what the payload means, so a device that has not installed the app can still check its shape. They match ContinuitySemanticSchema::wire_tag in tilo-app-package.

Structs§

BrokerActionSurface
CalibrationInfo
CalibrationMemberInfo
CalibrationMicrophoneInfo: One device’s microphone as a calibration candidate for a group.
CalibrationMicrophoneRun
CertifiedAgentIdentity: Explicit correlation supplied by owner-backed membership, never decoded from a participant label or an actor-id prefix.
CertifiedEndpointIdentity: Certified identity for a client connecting to an explicit collaboration endpoint rather than through a launcher-inherited identity service.
CollaborationManager
Collaborator
CommittedDocument: A disposable capture from the actual admitted SDK channel. It cannot be constructed by an application. Its ACK opens only this route generation.
ContinuationMetadata: Inert, app-owned resume projection sent only to the local shell.
DocumentHistory: Lazy history paging state for every artifact the app has seen.
DocumentPublicationReceipt: Completion of the document prefix preceding one publication barrier.
ExportedAction: One inert operation an application exports, without execution authority.
HostSessionConnector: A one-shot host handoff factory, evaluated on the SDK worker’s LocalSet.
NearbyDestinationHandle: A short-lived shell capability naming one receiver destination for one authenticated Files connection. Applications never receive its host path.
NearbyTargetHandle: A short-lived shell capability naming one picker target. It carries no cryptographic peer identity and has no authority outside the authenticated app connection that received it.
NearbyTransferDestination: Path-free receiver destination projected from this Files instance’s current writable grants.
NearbyTransferHandle: A short-lived shell capability naming one transfer for one authenticated Files connection. It is never the transport’s global transfer identity.
NearbyTransferSnapshot
NearbyTransferStatus: Bounded status projection. Paths and file contents are absent: receiver UI needs a portable display name, exact peer and byte progress.
NearbyTransferTarget: A certified personal-device target safe to show in an application picker.
NetworkWakeStatus: Bounded local observations; no field claims verified physical recovery.
RouteSpec: An explicit typed collaboration route.
SigningIdentity: Identity-side handle used by CollaborationManager::send_signed_op to mint signed envelopes. The secret key stays private — not re-exported on the manager’s public surface — so app code can only sign via the manager’s helper, never handle the raw secret.
SpeakerDeviceInfo
SpeakerEndpointInfo
SpeakerGroupInfo
SpeakerMemberInfo
SpeakerMemberSpec
SpeakerSnapshot
SpeakerTrimInfo: A member’s calibration correction in display units.

Enums§

ActionDirectoryRequest: A broker directory request awaiting main-thread authority. This crosses threads as inert strings and budgets only; no widget reference or Cap’n Proto handle ever leaves the UI/collaboration boundary.
CalibrationMemberState
CalibrationMicrophoneState: What one microphone contributed to a run.
CalibrationPhaseInfo
ChannelAccessState: What an endpoint’s route can do with content, as apps see it.
CollabEvent
CollabRequest
CollabSendError: Why a request did not reach the collaboration transport.
CollaborationState: Where a manager’s connection stands, as the UI shows it.
DisplayOrigin: The host distinguishes local UI intent from continuation of a published action. A published id is resolved only against broker-retained original custody.
DocumentMutation: Meaning of a signed document payload. Keeping this tag inside [SignedOp::payload] makes snapshot-vs-incremental part of the bytes the device signs without changing the persisted SignedOp layout.
DocumentPublicationError: Failure to complete a prefix of document publications.
ExportedInput: What one exported action’s invocation must carry, as it crosses the wire — the transport-side twin of tilo_actions::InputSpec, which says what kind of text it collects rather than whether it names content.
MicrophoneStatus: Whether one device’s microphone can listen while a group is calibrated.
NearbyTransferCommand: Commands accepted by the shell-owned Nearby Send authority. source_path is raw Unix path bytes so a valid file never becomes inaccessible merely because its name is not UTF-8. The broker accepts Send only from the certified Files application and revalidates the exact target and source.
NearbyTransferDirection
NearbyTransferPhase
NearbyTransferReply
PortableWifiSecurity: Portable Wi-Fi authentication modes understood by the sealed personal secret bridge. Enterprise identity/certificate state is intentionally not representable here.
PresencePayload
SignedSendError: Failure modes for CollaborationManager::send_signed_op. NoIdentity is the common case — call before the shell provisions an identity — and callers can fall back to document_incremental.
SpeakerCommand
SpeakerMemberStatus: Where one member of a group stands right now.
SpeakerPlaybackInfo: A session playing on the group right now, most urgent state first.
SpeakerReply
SpeakerRoleSpec: What one member contributes, in wire form.
TransportCommand: Everything the manager asks of its transport.
TransportError: Why a transport refused a command.
TransportStatus: Liveness of a transport as the owner sees it this frame.
WifiContinuityCommand
WifiContinuityReply

Constants§

CURRENT_CONNECTION_PEER_ID: Reserved invokePublishedAction.peerId meaning “the application connection making this request”. Live broker peer ids are allocated from zero upward; the broker never assigns this sentinel.
HISTORY_PAGE_SIZE: Ops per history page. Large enough that a scroll gesture rarely waits, small enough to keep each page’s decrypt and apply well under a frame.
HISTORY_PREFETCH_MARGIN: Prefetch when a view is within this many loaded ops of the oldest one.
MAX_SPEAKER_NAME_CHARS
ROUTE_JOIN_FAILED: How an app’s error begins when it could not join its collaboration route and stopped. The shell recognises it in a failed launch’s output to say why the app did not open.
SESSION_RUNTIME_SUPPORTED: Whether this host supports the local session runtime transport. This describes transport availability, not an inherited capability or permission.

Traits§

CollabTransport: A synchronous, poll-driven collaboration transport. See the module documentation for the contract every implementation upholds.
PeerTransport: Transport adapters must authenticate ordinary peer joins and verify inbound envelopes before publishing events. Installing this adapter grants no model, action, HostContext, or storage authority. Queue failures are fail-closed.

Functions§

continuation_restore_env: The launcher-only resume payload the host passed this window (crate::host::HostIdentity::continuity_resume).
display_control: Ask the native host to inspect or change its display transaction. Call off the frame thread; the existing bridge and response wait remain bounded.
local_app_id: The application’s authenticated durable route (falling back to its signed package id, then QUICK_APP_ID for dev). Read from the same place the channel key is built, so what an app publishes can’t disagree with its connection.
local_cluster_id: The room this process collaborates in. Exposed so presence scopes from the same source routing uses, rather than a derivation that could drift.
local_user_id: The person sitting at this machine. Actions are stamped with this so undo can tell collaborators apart (see crate::state::State::undo_as): the id must be stable across a document’s life and distinct between people, or one person’s Ctrl+Z reverts another’s work.
presence_handle_env: The presence handle announced on Hello. TILO_PRESENCE_HANDLE wins, then TILO_USER_ID; absent both, the broker’s synthetic name.
speaker_command: Ask the shell’s speaker-group authority over the launcher-authenticated Settings route. Run it off the frame thread; a lost broker times out into an ordinary unavailable result.
wifi_continuity_command: Invoke the shell’s launcher-authenticated, sealed Wi-Fi continuity path. Callers should run this off the frame thread; the bounded timeout turns a lost broker into an ordinary unavailable result.