Crate sapphire_framework_bridge_api 

What an app server says to the bridge, and how it says it.

Kept separate from sapphire-framework-bridge so that an app server can talk to the bridge without linking iroh: Cargo unifies features across a workspace build, so a feature flag on one crate would not have been enough.

See docs/superpowers/specs/2026-09-16-process-architecture-design.md §4.3 and §5.

Structs

Ack

The success payload of a call that returns nothing.

ApiKey

The remote slot’s API key. Never printed: Debug shows ApiKey(..).

DataAck

The bridge’s answer to a DataHeader, sent as one line before the raw bytes begin.

DevicePrioritySetParams

Parameters of DEVICE_PRIORITY_SET.

DevicePrioritySetResult

Result of DEVICE_PRIORITY_SET.

DeviceRetireParams

Parameters of DEVICE_RETIRE.

DeviceRetireResult

Result of DEVICE_RETIRE.

DeviceSettings

This device’s own settings, never synced.

EmbedDeviceSetParams

Parameters of EMBED_DEVICE_SET.

EmbedImagesParams

Parameters of EMBED_IMAGES.

EmbedInfoResult

Result of EMBED_INFO.

EmbedKeySetParams

Parameters of EMBED_KEY_SET. Debug hides the key.

EmbedModelInfo

The embedding model a bridge serves.

EmbedModelSetParams

Parameters of EMBED_MODEL_SET.

EmbedParams

Parameters of EMBED.

EmbedResult

Result of EMBED and EMBED_IMAGES.

EmbedSettingsResult

Result of every embed.* settings method: the settings, and what they resolve to.

ExternalDeviceAddParams

Parameters of EXTERNAL_DEVICE_ADD.

ExternalDeviceAuthenticateParams

Parameters of EXTERNAL_DEVICE_AUTHENTICATE. Debug hides the token.

ExternalDeviceAuthenticateResult

Result of EXTERNAL_DEVICE_AUTHENTICATE: who it is. A refusal is an error, never a result.

ExternalDeviceInfo

One external device, as the ledger has it. Never carries the token or its hash.

ExternalDeviceListResult

Result of EXTERNAL_DEVICE_LIST.

ExternalDeviceSelectParams

Parameters naming one record: retire, restore, rotate.

ExternalDeviceSetAppsParams

Parameters of EXTERNAL_DEVICE_SET_APPS.

ExternalDeviceTokenResult

Result of EXTERNAL_DEVICE_ADD and EXTERNAL_DEVICE_ROTATE: the record and its new token, which is never available again. Debug hides the token.

GrainId

Grain id struct

IncomingParams

Parameters of the INCOMING notification.

InviteParams

Parameters of INVITE.

InviteResult

Result of INVITE.

JoinParams

Parameters of JOIN.

JoinResult

Result of JOIN.

LocalModel

The local slot’s model.

ModelSettings

The two slots: the workgroup’s synced embedding.toml, or a host’s own without one.

PeerInfo

One device of the workgroup.

PeersResult

Result of PEERS.

RegisterParams

Parameters of REGISTER.

RegisterResult

Result of REGISTER.

RemoteModel

The remote slot’s model.

RouteStatus

One row of the routing table.

StatusResult

Result of STATUS.

UnregisterParams

Parameters of UNREGISTER.

WorkgroupCreateParams

Parameters of WORKGROUP_CREATE.

WorkgroupCreateResult

Result of WORKGROUP_CREATE.

WorkgroupStatus

The workgroup this host belongs to.

WorkgroupWorkspaceInfo

One workspace the workgroup knows about.

WorkspaceRegistration

One workspace an app server owns.

WorkspaceRoles

Who the bridge elected for one workspace this host’s app servers own.

WorkspacesResult

Result of WORKSPACES.

Enums

DataHeader

The first line of a data-plane connection.

EmbedNote

Why a bridge does not embed, or what it lacks while it does.

EmbedRequest

One settings request, as either CLI builds it from its arguments.

ExternalDeviceOutcome

What a management request answers.

ExternalDeviceRequest

One management request, as either CLI builds it from its arguments.

ManagedBy

How an app server process came to exist, as it tells the bridge in REGISTER.

ModelSource

Where the model settings in effect come from.

QType

How the local model’s weights are held in memory: a device setting, never synced.

Slot

One of the two model slots.

SlotModel

One slot’s model, for EmbedModelSetParams.

Constants

ALPN

The application-layer protocol name used on every peer connection.

API_VERSION

The version of the bridge’s control-plane API: the methods below and their types.

BRIDGE_DATA_NAME

The endpoint name the bridge’s data plane listens under.

BRIDGE_NAME

The endpoint name the bridge’s control plane listens under.

DEFAULT_DIMENSION

LocalModel::dimension’s default, and the dimension #183 settled on.

DEFAULT_MAX_TOKENS

LocalModel::max_tokens’s default.

DEFAULT_PRIORITY

A device’s priority when its record names none. Mirrors the registry’s own constant; this crate does not depend on the registry.

DEVICE_PRIORITY_SET

Set a device’s election priority.

DEVICE_RETIRE

Retire a device of this host’s workgroup.

EMBED

Embed texts with the bridge’s embedding model.

EMBED_DEVICE_SET

Switch one slot on or off on this device.

EMBED_IMAGES

Embed images with the bridge’s embedding model, into the texts’ space. Served only when EmbedModelInfo::images is set; absent from bridges before 2.4.

EMBED_INFO

Ask the bridge which embedding model it serves, if any.

EMBED_KEY_CLEAR

Remove the remote slot’s API key from this device.

EMBED_KEY_SET

Store the remote slot’s API key on this device.

EMBED_MODEL_SET

Set or clear one model slot.

EMBED_SETTINGS

Read the embedding settings and what they resolve to.

EXTERNAL_DEVICE_ADD

Add an external device; the answer carries its token, once.

EXTERNAL_DEVICE_AUTHENTICATE

Check a presented token for an application: who it is, or an error.

EXTERNAL_DEVICE_LIST

List the workgroup’s external devices.

EXTERNAL_DEVICE_RESTORE

Bring a retired external device back, with its token.

EXTERNAL_DEVICE_RETIRE

Retire an external device: its token stops working, the record stays.

EXTERNAL_DEVICE_ROTATE

Replace an external device’s token, keeping its id.

EXTERNAL_DEVICE_SET_APPS

Set the applications an external device may use.

INCOMING

Notification: a peer wants a workspace this app server owns.

INVITE

Create an invite, and get the ticket to hand to the joining device.

JOIN

Join the workgroup a ticket names.

LOCAL_MODEL

The only local model for now.

MAX_TOKENS

Upper bound on LocalModel::max_tokens.

PEERS

List the workgroup’s devices and whether they are connected.

REGISTER

Announce which workspaces this app server owns.

STATUS

Describe the bridge.

UNREGISTER

Stop owning one workspace.

WORKGROUP_CREATE

Found a workgroup on this host, as its first device.

WORKSPACES

List the workspaces the workgroup knows about.

Functions

describe

What embedding show prints, one line each.

describe_external_device

One line describing a record: name, id, applications, state.

describe_external_outcome

The lines either CLI prints for an outcome. A token is printed here, and only here.