Module remote

Expand description

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§

agent_runs: Runs of asks to this session’s agents, as the session publishes them.
crash_records: What this computer recorded of the times it went wrong: a desktop that stopped responding or stopped unexpectedly, a part of it that restarted, the computer itself stopping (the kernel’s record from before a reset), and a fault the system’s core went on from.
device_pairing: Pairing a nearby device with the person’s identity. The host runs it — LAN discovery, and the approval an administrator authenticates — so no application starts a privileged process. It is answered under the host’s provider, which a caller names without reading a catalogue, for the person at this device in the workspace their connection was admitted to.
downloaded_apps: The programs the person downloaded and added to their apps: the AppImages, tarball programs and loose binaries that ship no desktop entry, and the entry Tilo keeps for each of them.
feedback: Read-only feedback admission and canonical acknowledgment on the existing authenticated action transport. These values never grant membership.
home_relay_hosting: Hosting the person’s workspaces on their home relay as well as on the device that governs them: per workspace, the relay is one of the workspace’s hosts or it is not, as the workspace’s governor records its hosts. It is answered under the host’s provider, which a caller names without reading a catalogue, for the person at this device.
identity_admin: Administering the person’s identities and the devices trusted under them. The host keeps the identity store — records, root secrets, the active selector, device fleets — and runs every step, so no application reads a secret or signs with the root key. It is answered under the host’s provider, which a caller names without reading a catalogue, for the person at this device in the workspace their connection was admitted to.
own_device: Using an action on another of the person’s own devices and hearing its answer.
settings_records: The person’s settings, kept by the host whether or not the app that shows them is open: each section a record published with its field edits and verbs (settings:<kind>), changed through them as that app’s window changes them. It is answered under the host’s provider for the person at this device in the workspace their connection was admitted to.
task_programs: An agent task’s tilolang programs (docs/designs/app-language/agents.md, “How a program runs”), served by the session to the Tasks agent’s loop.
workspace_activity: A workspace’s activity as the session serves it: what changed since this device last looked, the full history, and the replay of its layout.

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. It can instead deliver a published resource action after launch (ApplicationLaunch::with_action). The source app never hands over a local path or starts a process itself.
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
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.
ConfirmationQuestion: A question a device of the person’s puts to them on another of their own devices: one invocation of an action their grants leave to them.
ConfirmedInvocation: The person’s answer to ActionHost::confirm: the confirmation to invoke again with, and the arguments to invoke with.
ExecutionLease: Host-owned execution lifetime. Clones share closure, never authority. Equality and hashing use the immutable minted identity, not liveness.
Found: One resource a search found, as every caller of the one search reads a result: the resource it is about, what it is, and what it reads as.
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.
RecordAddress: One record of a workspace, by its app (the id whose records it is) and its id there (empty for the app’s record of the workspace).
RecordChange: An action to run on one record at the record’s origin, as an agent task invokes it: the record (by its app and its id there), the action’s subject resource and the action, its arguments, and what the task’s preview planned, when it planned.
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 workspace 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.
ConfirmationReply: The person’s answer to a ConfirmationQuestion.
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.
RecordCopy: What a read of one record answers.
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_OPEN_TYPE: Encoded operation of the shared view action that shows the item at an anchor, as picking that item’s search hit does.
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_KIND: Resource kind of an installed Tilo application a workspace lists, which a catalogue query’s resource_name answers whole.
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.
CONTENT_PUTS_UNAVAILABLE: What a host without a content store answers.
DEFAULT_LEDGER_CAPACITY: Default number of invocations an InvocationLedger remembers.
MAX_CATALOGUE_PAGE: Largest page a host returns, whatever a query asks for.
MAX_CONTENT_PUT_CHUNK: The most raw bytes one append carries. MCP requests are bounded at 1 MiB; 512 KiB is about 683 KiB of base64, leaving room for the rest of the request.
MAX_OPEN_CONTENT_PUTS: Uploads one session keeps open at once.
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.
NODE_PERMITS_ACTION: Whether the caller may change the node: output {"undoable": bool}, as the workspace decides their writes there.
NODE_RESOURCE_PREFIX: Resource prefix of a workspace’s actions on one node of its published tree (a record, an item of it): the rest is the node’s text form (workspace:…/app:…/kind:…/resource:…/item:…). See node_target.
OWN_PROVIDER: Provider token naming the calling application’s own connection, for an app that routes one of its own actions through the host.
RECORD_READS_FOR_TASKS: What a caller that is not an agent task acting for its person is told.
RECORD_READS_UNAVAILABLE: What a host without record reads answers.
REMOTE_ACTIONS_VERSION: Version of the RemoteActionFrame schema this build speaks.
SHARE_NODE_ACTION: Share a node with the workspace’s members: grant them, on that node only, what argument access names (view or edit), as much as the person sharing holds there, under the share’s id (argument share).
STALE_REVISION_REASON: What ActionHostError::StaleRevision says, and the reason it carries on the wire as an ActionHostError::InvalidRequest.
UNSHARE_NODE_ACTION: Take back what the share named by argument share granted.
WORKSPACE_GOVERNANCE_KIND: The resource kind of a workspace’s governance resource.
WORKSPACE_GOVERNANCE_PROVIDER: The provider a workspace’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.
ContentPut: One upload in progress, owned by the session that began it: dropped unfinished (the session ended), it stores nothing.
ContentPuts: A host’s door for content puts.
RecordChanges: A host’s door for an agent task’s changes to records outside their apps. A change goes to the record’s origin, which runs the action against the record as it is then, applies what it wrote as the task’s step and answers with its JSON: {"ok": {value, resources}, "differs": bool}, or {"failed": why} when the action did not run.
RecordReads: A host’s door for reading records outside their app.
ResourceSearch: The desktop’s one search, as a host that holds it offers it to a caller who asks by words: the palette’s ranking, the same results in the same order. The search itself lives on the thread that holds the desktop, so an answer comes back later, as an action’s does.

Functions§

activate_spec: The shared view action APPLICATION_ACTIVATE_ACTION (“Show this window”), called label and described by description in the reader’s language: every app’s window publishes it, a framework app’s and a tilolang host’s instance alike, and it answers {"activation_requested": true} once the window was asked to come forward.
activation_requested: What APPLICATION_ACTIVATE_ACTION answers once the window was asked to come forward.
application_action_target: The target of the action app_id offers on resource in workspace workspace. 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 workspace. An invocation may carry the content hash of bytes to open read-only as its text argument.
application_provider: The workspace and application an application_action_target provider token names, or None for any other provider.
application_provider_record: The record an application_record_target provider token names, or None when it names none.
application_record_target: application_action_target in app_id’s record record: the host delivers to the app showing that record, or launches the app on it. Opening a reference is the resource’s open on this target.
node_target: The target of action (one of SHARE_NODE_ACTION, UNSHARE_NODE_ACTION, NODE_PERMITS_ACTION) on node, the text form of a node of workspace workspace’s tree.
pending
provider_workspace: The workspace a workspace provider token names, or None for an application provider.
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.
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.
stem_word: The stem an English word is matched by: its plural, its participle and its “-ing” form reduce to the word a description most likely spells (“drawing” and “draw”, “dragging” and “drag”, “scrolling” and “scroll”, “signed” and “sign”). An inflection is only undone when what is left is still a word of reasonable length, so “ring” and “thing” keep their own letters rather than becoming “r” and “th”.
workspace_governance_resource
workspace_provider: The provider token for the actions workspace workspace itself offers.

Module remote

Module remote Copy item path

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Module remote