Module remote 

Using another peer’s actions: a transport-neutral vocabulary.

A peer that hosts live apps (a desktop session, a headless app-serving host) can let an authenticated remote caller list the actions it publishes, invoke one, follow its progress, and cancel it. This module is the whole contract between the two sides:

• RemoteActionMessage — requests and their answers, wrapped in a versioned RemoteActionFrame that any transport carries as opaque bytes.
• ActionHost — what a peer implements to answer them, and serve, which maps one request frame onto a host. Answers that need an application’s help arrive later as a Pending, so no caller blocks.
• CatalogueQuery — paged, filtered browsing of what a host offers.
• InvocationLedger — the idempotency rule every host shares: an invocation is keyed by its caller-chosen InvocationId, so a retry after a lost reply observes the original invocation instead of running the action twice.

Who is calling is never read from a payload. The transport that authenticated the connection constructs the Caller and hands it to the host beside the message; nothing in a frame can name or change it.

Descriptors, addresses, arguments, outputs and lifecycle updates are the same types the local action surface already uses (ActionDescriptor, ActionAddress, InvocationUpdate, ActionOutput, ActionFailure), so a remote caller sees exactly what a local one does.

Modules

feedback

Read-only feedback admission and canonical acknowledgment on the existing authenticated action transport. These values never grant membership.

Structs

Abandoned

Completer::abandoned: resolves once the answer is unobservable.

ApplicationLaunch

Opening another installed app into the workspace, optionally with verified content it opens read-only: Photos with a captured picture, a player with a recorded clip. An app offers it as an action on its own resources (ApplicationLaunch::spec); the host routes the admitted invocation through the workspace broker, which stages the bytes and owns the launched process. The source app never hands over a local path.

Caller

The authenticated principal behind a request.

CanonicalActionRoute

Exact document route whose broker-owned live publisher is requested. This selects custody, not permission: ordinary caller authorization still applies.

CatalogueLimits

Bounds on how much work a provider spends on one page. Each is an upper bound a host may lower, never a hint to exceed.

CataloguePage

One page of catalogue rows.

CatalogueProvider

A publisher the caller may browse or invoke.

CatalogueQuery

One bounded request for catalogue rows. Every field narrows; the empty query lists the first page of everything offered.

CatalogueResource

A resource as a catalogue row describes it.

CatalogueRow

One row: an action on a resource, or a resource that contains more.

Completer

The producing end of a Pending. Dropping it without completing abandons the answer, which the receiving end observes.

ExecutionLease

Host-owned execution lifetime. Clones share closure, never authority. Equality and hashing use the immutable minted identity, not liveness.

InvocationLedger

The idempotency ledger behind ActionHost::invoke.

InvocationReceipt

The host’s answer to an InvokeRequest.

InvocationState

The latest lifecycle update of one invocation, carrying the caller’s InvocationId.

InvokeRequest

A request to run one published action.

Pending

The receiving end: an answer that may not exist yet.

RecordPiece

One piece of a stored record document.

RecordQuery

Which record to read, and from where in its stored bytes.

RemoteActionFrame

A versioned RemoteActionMessage, the unit a transport carries.

RemoteActionTarget

Which published action an invocation names on the host.

ResourceViewLocator

A host-issued navigation locator. It carries no access grant or credentials.

RowVisibility

The action that discloses a resource-only row, and its contract.

ViewResourceQuery

One exact existing resource whose inert local-view metadata is requested. The transport supplies identity and current room authority independently.

Enums

ActionHostError

Why a host would not do what was asked. Every variant means nothing ran.

Admission

Whether InvocationLedger::admit started a job or found one.

CallerPrincipal

Who a request is from, as the host’s policy knows them.

Confirmation

Explicit confirmation carried with an invocation.

InvokeArgument

What an invocation carries for the action’s declared input.

PendingPoll

What Pending::poll_ready found.

ReceiptStatus

Where an invocation stands, as reported to its caller.

RemoteActionMessage

Everything that crosses the wire for remote action use.

RemoteFrameError

Why bytes are not a usable RemoteActionFrame.

Reservation

What InvocationLedger::reserve found.

UpdateMark

How far an invocation’s updates had got when its caller last looked: what a waiting Observe asks the host to move past.

Constants

APPLICATION_ACTIVATE_ACTION

The shared view action that asks the platform to reveal a running window.

APPLICATION_ACTIVATE_TYPE

Encoded operation of APPLICATION_ACTIVATE_ACTION.

APPLICATION_CLOSE_ACTION

Action id that closes a running application’s windows in a workspace.

APPLICATION_OPEN_ACTION

Action id that opens an application into a workspace.

APPLICATION_PROVIDER

Prefix of the provider token naming an application in a workspace whether or not it is running; see application_action_target.

APPLICATION_RESOURCE_PREFIX

Resource prefix of a workspace’s “open this application” actions.

CONFIRMED_ACTION_NEEDS_REVISION

Why a host refuses a directory action that asks for confirmation when the request names no revision: the confirmation covers the action as the person was shown it, which only that revision identifies. A caller that confirms on its own policy rather than a person’s reads the current revision and retries.

DEFAULT_LEDGER_CAPACITY

Default number of invocations an InvocationLedger remembers.

MAX_CATALOGUE_PAGE

Largest page a host returns, whatever a query asks for.

MAX_FETCHED_RECORD_BYTES

Largest record a device fetches from another at all.

MAX_RECORD_PIECE_BYTES

Largest piece of a record one answer carries, before encoding.

MAX_REMOTE_ACTION_FRAME_BYTES

Upper bound on one encoded frame. Catalogues are the largest messages; a host that needs more pages them rather than raising this.

MAX_REMOTE_WAIT

The longest a host holds a waiting answer, whatever wait_ms asked, so a relay connection or a broker call is never held open indefinitely.

OWN_PROVIDER

Provider token naming the calling application’s own connection, for an app that routes one of its own actions through the host.

REMOTE_ACTIONS_VERSION

Version of the RemoteActionFrame schema this build speaks.

ROOM_GOVERNANCE_KIND

The resource kind of a room’s governance resource.

ROOM_GOVERNANCE_PROVIDER

The provider a room’s own governance actions (membership, roles, grants, bans) are answered under. It is the host’s, not an app’s, so it is the one provider a caller names without reading it from a catalogue page.

WORKSPACE_PROVIDER

Prefix of the provider token for actions a workspace itself offers rather than an application; see workspace_provider.

Traits

ActionHost

A peer that runs actions on behalf of authenticated remote callers.

Functions

application_action_target

The target of the action app_id offers on resource in workspace room. The host delivers it to the running app, or launches the app into the workspace first and delivers it once the app offers the action; the app’s own published contract admits it either way.

application_open_target

The target that opens app_id into workspace room. An invocation may carry the content hash of bytes to open read-only as its text argument.

application_provider

The room and application an application_action_target provider token names, or None for any other provider.

pending

A connected Completer and Pending.

refuse

The answer that refuses request message with error — for a host that cannot be reached or is not running. Returns None for a message that is not a request.

room_governance_resource

The id of the room room’s governance resource.

serve

Answer one request from caller against host.

settle_with

The state of invocation, as ActionHost::observe reports it to caller, once it has moved past seen — or, with no seen, once it settles — or at until, whichever comes first.

workspace_provider

The provider token for the actions workspace room itself offers.

workspace_provider_room

The room a workspace provider token names, or None for an application provider.