Reins Protocol 0.1

Reins Protocol 0.1 in full: the normative text, rendered from docs/SPEC.md.

This page is docs/SPEC.md, rendered from the repository at build time. It is the text the project maintains, not a copy.

Reins lets an AI agent drive a web app that is running in a browser tab: read what is on screen, call the app's own actions, move a visible cursor, and put data in front of the user. The app decides what an agent may do, the user can watch and stop it, and a kiosk can lock it down to a fixed allowlist.

The wire types are in packages/core/src/protocol.ts. This document describes the behaviour behind them. The words MUST, SHOULD and MAY are normative.

Conventions: a size in bytes counts the UTF-8 bytes of text. A length in characters counts UTF-16 code units unless code points are named. Strings that are hashed or MACed are taken as their UTF-8 bytes. base64url is RFC 4648 section 5 without padding.

1. Goals #

  1. Live control. Commands take effect within one animation frame of arriving. Cursor motion is smooth at display rate whatever the network does.
  2. Token economy. An agent learns an app from a short prompt card, acts through the app's own semantic actions, and reads the screen as a compact tree with deltas. Bulk data goes to the screen without passing through the model.
  3. App-defined guardrails. The app declares its actions and their risk. Policy decides allow, confirm or deny. There is no path to run agent-supplied code.
  4. Human in control. The user sees when an agent is connected, approves what the policy says needs approval, and can pause or stop at any time. Real input wins over synthetic input.
  5. Kiosk grade. An unattended station runs a fixed policy: allowlisted actions, annotated elements only, no synthetic input, no navigation, tamper-evident audit.
  6. One protocol, any transport. The same frames run over a loopback WebSocket and over an in-page message port.

2. Roles #

  agent harness                 hub (loopback)                  browser tab
 ┌──────────────┐   reins.v1   ┌──────────────┐   reins.v1   ┌────────────────┐
 │ agent SDK    │◄────────────►│ broker       │◄────────────►│ driver         │
 │ or MCP tools │  ws / port   │ auth, grants │  ws / port   │ app actions,   │
 └──────────────┘              │ policy, audit│              │ UI tree, cursor│
                               └──────────────┘              └────────────────┘
  • Surface: a web page that embeds the driver. It dials out to the hub, because a tab cannot listen.
  • Agent: an AI harness, or an assistant running in another tab or in the same page.
  • Hub: the broker both connect to. It authenticates peers, issues grants, enforces the hub policy and rate limits, routes requests and keeps the audit log. The broker is transport-agnostic: the hub process binds it to WebSocket, a page can bind it to in-memory links.

Trust: the hub is trusted by both sides. The agent is constrained by the hub policy and by the surface policy. The surface enforces its own policy even though the hub already checked, because the app owner's guardrails belong to the app. Page content is untrusted data from the agent's point of view.

3. Transports #

Loopback WebSocket. The hub listens on 127.0.0.1 (default port 7346). Peers open ws://127.0.0.1:7346/ with subprotocol reins.v1. The hub MUST:

  • bind loopback addresses only and refuse any other bind address;
  • reject a socket whose remote address is not loopback;
  • reject a request whose Host header is not 127.0.0.1, localhost or [::1] with the hub's port (DNS rebinding defence);
  • require the reins.v1 subprotocol;
  • disable per-message compression;
  • answer plain HTTP requests with a bare status and no body.

Browsers treat loopback as a secure context, so an https: page may open ws://127.0.0.1. A browser may put loopback access behind a user permission. The driver treats a blocked connection as an ordinary connect failure and reports it.

In-page port. A MessagePort, or the in-memory linkPair(), carries the same frames with strings for text frames and Uint8Array for binary frames. An assistant that runs inside the browser uses this to reach a surface with no network at all.

Electron port. An Electron app hosts the broker in its main process and links a window to it over a MessageChannelMain. The main process wraps its end as a Link (mainPortLink); the page gets the other end as a MessagePort and wraps it with portLink. The frames are those of the in-page port. A port ends with its document, so a window that reloads or navigates connects again from the new one. The main process is the embedding code of section 5: it MUST take the link's origin from the frame the port went to, as Electron reports it, and never from anything the page sent. It MUST give a port only to the top-level frame of a window the app registered, and MUST NOT give one to a <webview> guest unless the app said that guest may be driven while embedded (section 12, Frames). The top-level frame is the one the window's contents report as their main frame: a frame without a parent that is not it, such as the root of a fenced frame, is a frame inside the page.

A window is registered for a page: a URL, several, or a predicate. The main process MUST compare it with the URL Electron reports for the frame at the time the page asks, the #fragment aside, and MUST NOT link a window that shows a page of origin file:// or null unless it was registered with one. Such an origin does not say which page it is: any other local file that got into the window has it too. A window that is not shown has nobody to ask, so its page gets the link when the window is shown, unless the app registered it to be driven unseen. The same is asked for a view that was registered by its contents: the window is the one that holds the view when its page asks, and a view that is in no window gets no link. The preload needs an isolated world to stand in: in a window without context isolation it MUST NOT offer the page a way to ask, and it tells the page why.

Code that embeds a broker and builds a link itself knows what is at the far end, as no hub on a socket can. It MAY vouch for it (accept(link, { origin, vouched: true })), and the hub then lists that surface as verified (section 5), as it lists one that proved a key. The Electron main process does so for a window it registered, and reins-electron for a page it adopted over a debugging pipe into the hub it hosts. A debugging port is different: every program on the machine can use it, type and press in the page through it, and speak on the page's link. reins-electron MUST NOT vouch for a page it adopted through a debugging port, such a page treats its hub as unverified, and the command MUST NOT give it a surface key, which could be read back through the port.

A hub whose surfaces are all linked in-process MAY close its socket to surfaces (surfaceSockets: false). On a socket of such a hub a hello with role surface MUST be answered bye {code:"E_ORIGIN"}, whatever Origin header came with it.

Every transport is wrapped as a Link (see protocol.ts). A link queues inbound messages until a handler is assigned, at most 4096 messages and 16 MiB; past either bound it drops the queue and closes.

4. Framing #

Text frames are JSON objects with a t field: challenge, hello, welcome, req, res, evt, flow, ping, pong, bye.

Binary frames start with a kind byte. The only kind in 0.1 is the pointer frame (section 11).

Limits (DEFAULT_LIMITS): text frame 256 KiB (maxText), binary frame 16 KiB (maxBinary), heartbeatMs 15 000, reqTimeoutMs 15 000, consentTimeoutMs 60 000. The hub announces its limits in welcome. A size limit applies to a frame after its seal (section 5) is removed. A receiver MUST close with E_TOO_LARGE on an oversize frame and with E_BAD_FRAME on a frame that is not valid JSON, has an unknown t, or lacks a required field. To close with a code is to send bye {code} and then close the transport. A message too large for the transport to take at all (the hub's WebSocket accepts the frame limit plus a seal MAC: 44 more characters of text, 32 more bytes of binary) is closed by the transport without a bye, with WebSocket close code 1009. Decoding validates shape: field presence and primitive types.

5. Handshake and authentication #

hub  → peer   challenge { v:["0.1"], nonce, hub }
peer → hub    hello     { v, role, name, cnonce, auth?, surface? }
hub  → peer   welcome   { v, session, role, limits, proof? }      or   bye { code }
  • nonce and cnonce are 32 random bytes, base64url, fresh per connection.
  • auth.proof = b64url(HMAC-SHA256(key, "reins.v1.auth\n" + role + "\n" + kid + "\n" + nonce + "\n" + cnonce)). The key is the UTF-8 bytes of the shared secret and the message the UTF-8 bytes of the string, so a non-ASCII kid is hashed as UTF-8. A field that contains a line feed, or that is not well-formed Unicode, makes the proof fail. Secrets are 32 random bytes, base64url. A secret never appears in a URL or a log.
  • When the peer authenticated, welcome.proof is the same HMAC with the context reins.v1.hub. A peer that holds a key MUST verify it and close on mismatch. This defeats a process squatting on the hub's port.
  • The hub compares proofs in constant time, answers a failed hello with bye {code:"E_AUTH"}, and closes. A peer that sends anything but hello first, or takes longer than 5 s, is closed. Until a connection has authenticated, the hub holds at most 16 inbound messages and 64 KiB from it, and closes it beyond that.
  • A failed proof (a missing or wrong proof, an unknown kid) is answered after a delay: 200 ms, doubling with each failure in the last minute, up to 3 s. Nothing more the peer sends is kept; only its handshake slot is held until the delayed E_AUTH. A correct proof is never delayed and never refused because others failed. At most 16 handshakes may be pending or waiting out a delay; further connections are closed with E_BUSY.
  • Keys shorter than 32 characters are rejected when the hub is configured.

Sealed sessions. When a peer authenticated with a key, every message after welcome is sealed in both directions. A process relaying the connection cannot inject, alter or reorder a message or replay one, and cannot drop one unless it also withholds everything after it in that direction: the next message fails to verify. Withholding the last messages of a direction is not detected; neither end notices until the heartbeat (section 6) drops the silent peer.

  • Both sides derive one key per direction from the shared secret and the transcript of the handshake: th = b64url(SHA-256(L(c) || c || L(h) || h || L(w) || w)) and k = HMAC-SHA256(key, context + "\n" + nonce + "\n" + cnonce + "\n" + th), where c, h and w are the UTF-8 bytes of the challenge, hello and welcome frame texts exactly as sent, and L(x) is the byte length of x as an unsigned 32-bit big-endian integer. The context is reins.v1.seal.peer for what the peer sends and reins.v1.seal.hub for what the hub sends, and k is the raw 32-byte HMAC output. Both ends MUST derive the keys exactly this way, so that they agree only if both saw the same three frames.
  • Each direction counts its messages from 0. The MAC of a message is HMAC-SHA256(k, u64be(seq) || kind || payload), with kind 0x74 for text and 0x62 for binary; the payload of a text message is its UTF-8 bytes. The counter is never sent.
  • A sealed text message is the base64url MAC (43 characters), ., then the text. A sealed binary message is the bytes followed by the 32 MAC bytes.
  • A message that does not verify closes the connection and is not delivered.
  • Text that is not well-formed Unicode (it holds a lone surrogate) MUST NOT be sealed or opened: a sender refuses to seal it, a receiver treats it as a message that does not verify, and a transcript text that is not well-formed fails the session with E_AUTH.
  • Key confirmation. Right after welcome the peer sends a sealed ping. The hub answers with a sealed pong and only then registers the peer and acts on anything that was in hello. The peer treats the session as established only when that pong verifies. Either side gives up after 5 s.

Agents MUST authenticate. Each agent credential has a kid, a key, and optional caps: allowed scopes, allowed surface origins, a session limit (4 by default). If the connection carries an Origin header (the agent is a browser page), that origin MUST be listed on the credential (else E_ORIGIN). The name shown to users is the credential's name when the operator set one, otherwise the name the agent declared, with control characters (\p{Cc}) and the bidirectional marks and overrides (U+200E, U+200F, U+202A to U+202E, U+2066 to U+2069) removed and cut to 64 code points.

Surfaces are identified by origin. The hub takes the origin from the WebSocket Origin header, or from the embedding code for in-page links, and MUST find it in the configured allowlist (else E_ORIGIN). Entries are exact origins, scheme://host:* for any port, or *. hello.surface.url MUST have that origin. A hub MAY hold surface keys by app id (kid = app id). A surface whose manifest claims an app id the hub holds a key for MUST prove that key, whether or not the hub sets requireKey; without a proof it is refused with E_AUTH ("surface key required"). requireKey also refuses every surface without a key, and kiosk deployments SHOULD set it, because a local non-browser process can forge an Origin header. SurfaceInfo.verified is true only for a surface that proved a key, or whose link the embedding code built itself and vouches for (section 3). A hub MAY pin an app id to a manifest digest and refuse a surface whose manifest differs (E_DENIED). Pinning catches a modified build of the app. It does not stop a forger, who can copy the manifest.

A surface that holds no key cannot check the hub's proof, so it cannot tell the hub from another process listening on the same port. Such a surface treats the hub as unverified: it never accepts an attach silently (the decision is at least confirm), and it tells the user so in the consent prompt and in the indicator. The kiosk profile has nobody to ask, so a kiosk surface MUST hold a key. A link the app built itself (the in-page transport) counts as verified.

Origins. An origin is compared as text, in one of four forms:

  • a web origin: the serialised origin of an http:, https:, ws:, wss: or ftp: URL, scheme://host with :port unless the port is the scheme's default;
  • file://: the origin of every file: URL, whatever its host and path;
  • an app origin: scheme://host or scheme://host:port with any other scheme, which is what a page has when an Electron app serves it from a scheme of its own (app://notes). Scheme and host are lower-case ASCII, the scheme [a-z][a-z0-9+.-]*, the host one or more of a-z, 0-9, ., _ and - (Chromium reports app://- and app://. as origins, and keeps a trailing dot), the port 1 to 65535 without leading zeros;
  • null: an opaque origin, as a data: URL, a sandboxed frame, or a page on a scheme the browser gives no hosts has.

The origin of a URL is its web origin for those five schemes and file:// for file:. For blob: it is the web origin of the http: or https: URL that follows blob:, else null. For any other scheme it is the app origin made of the scheme, the host between // and the next /, ? or # (credentials dropped, in lower case) and the port, when those fit the form above, else null. An implementation MUST compute it this way (urlOrigin) and not take the origin a URL library reports, which for a file: or app-scheme URL is null in some engines and not in others.

Chromium, and so Electron, puts these in the Origin header of a WebSocket: file:// from a page loaded from a file, the app origin from a page on a scheme the app registered as standard, and null from a page on a scheme it did not (measured, see docs/ELECTRON.md).

Allowlist entries, in the surface allowlist and in a credential's origins and surfaces, match as follows. An exact entry matches that origin: a web origin, file://, an app origin or null. scheme://host:* matches a web or app origin of that scheme and host with any port or none. * matches every web origin and MUST NOT match file://, an app origin or null: each of those is admitted only by an entry that names it. hello.surface.url has the connection's origin when the origin of the URL equals it; a connection whose origin is null takes any URL that has no web origin. The same holds for the URL of a nav report (section 6): the hub MUST judge it by the origin this section gives it, so that a page on file:// or an app origin can say where it went.

Two entries admit by an origin that countless pages share, and need more than a name when surfaces come over a socket. null is the origin of every sandboxed frame on every website and of every data: page, and a connection with it may state any URL that has no web origin, an app's own included. file:// is the origin of every local file. A hub SHOULD warn when its socket admits either without requiring a surface key, and a deployment SHOULD NOT list null unless every surface proves a key or none comes over the socket. The reference hub warns at start, and reins-tools up, which starts one in the background where its console is a log file, prints the same warning itself (section 15).

Session ids (a1, s1) are labels. Nothing is authorised by knowing one. They are assigned in sequence (s1, s2, ...), so an id reveals how many sessions of its kind connected before it; this is accepted.

Either side sends bye before closing on purpose.

6. Requests, responses, events #

req {id, m, p} is answered by exactly one res {re, ok, r} or res {re, ok:false, e:{code, msg}}. Ids count up from 1 per sender per connection. Error messages are short and safe to show to a model. They never contain stack traces, file paths or secrets. The codes (ERROR_CODES):

code meaning
E_BAD_FRAME malformed frame, unknown frame type, a frame out of place
E_VERSION no protocol version in common
E_AUTH missing or wrong proof, surface key required, key confirmation failed
E_ORIGIN the connection's origin, or hello.surface.url, is not allowed for the role; a surface on a socket that takes agents only
E_TOO_LARGE a frame, request, manifest, result or set of consent arguments over its limit
E_UNKNOWN_METHOD the method does not exist
E_BAD_ARGS params fail validation
E_NO_SURFACE no such surface id, or a surface the credential may not attach to
E_NOT_ATTACHED no live grant for this surface
E_SCOPE the grant lacks the method's scope, the person switched that scope off, or no requested scope is permitted
E_DENIED policy says no
E_CONSENT the person refused or blocked the action, or the prompt timed out
E_PAUSED control is paused, the indicator cannot be shown, or the person is using the page
E_RATE a rate or admission limit, or a consent cool-off
E_NO_TARGET the target is not a live, exposed, enabled element, or is read-only
E_TIMEOUT the other side did not answer in time
E_GONE the other side disconnected
E_BUSY a capacity, a pending attach or consent prompt, a permission that changed while the request waited, or a peer that does not read
E_INTERNAL an unexpected failure, the audit log unavailable, a result that is not JSON

bye also takes OK. A receiver reads an unknown code in a res as E_INTERNAL and in a bye as E_GONE.

An agent addresses a surface with p.s. The hub answers the methods in HUB_METHODS itself: hub.info, surfaces.list, surface.attach, surface.detach, stream.open and stream.close. Every other method is forwarded: the hub checks the grant, the scope (METHOD_SCOPE) and the rate limit, strips s, and sends the request to the surface with ag set to the agent's session id, and c:1 when the hub policy demands a human confirmation. The surface's answer is relayed back unchanged. An unknown method is answered E_UNKNOWN_METHOD before any parameter is checked. A surface id that does not exist, and one naming a surface the credential may not attach to, get the same answer on every method that takes s: E_NO_SURFACE, with the same message. Params that cannot be put in canonical JSON (section 7), because they are nested more than 100 levels deep, are refused with E_BAD_ARGS and not forwarded.

A request waits reqTimeoutMs for its answer. Where a consent prompt may be involved the wait is longer: the hub gives the surface consentTimeoutMs more (attach, act), and an agent gives the hub one reqTimeoutMs more than that (surface.attach, act), which is 2 × reqTimeoutMs + consentTimeoutMs, 90 s with the default limits. The agent so outwaits the hub, and how a slow prompt ended is the hub's answer, not the agent's own timer. On timeout the asker gets E_TIMEOUT. When a surface disconnects, its pending requests fail with E_GONE.

E_TIMEOUT on surface.attach or act says that the surface did not answer within the hub's wait. A prompt nobody answers ends as E_CONSENT after consent.timeoutMs, which is normally well inside that wait. It is not when the prompt first waited its turn behind another one (each prompt gets its full consent.timeoutMs from the moment it is shown), when the app set consent.timeoutMs above the hub's consentTimeoutMs, or when the page ran its timers late, as a browser may make a tab in the background do. In each case nobody approved the request. The prompt can still be on the page, though, and a request approved there later still takes effect: an action runs. An agent SHOULD treat this E_TIMEOUT as a prompt nobody answered: ask the person to bring the page to the front, then ask again. While the earlier prompt is up the new request is answered E_BUSY. Before repeating an action that is not safe to run twice, the agent SHOULD observe whether it ran.

Events are evt {topic, d}. A surface addresses one agent with ag, or omits it to reach every attached agent. The hub adds s when it relays, and relays an event only to live grants with the scope its topic needs: ui, state and nav need observe, and user goes to every live grant. Two kinds of user event are not relayed as they come: level and rule say what the person set for one agent (section 12) and are always sent with ag. The hub checks and records them (section 13) and then tells that agent alone. A grant event from a surface is acted on by its kind and never relayed as it came: revoked ends grants and scopes changes the scopes of one grant (both in section 8), and any other kind is dropped. surface events come from the hub alone; one sent by a surface is dropped, as is an event with an unknown topic. Agents opt into ui, state, user and nav with sub. grant and surface events need no subscription, and neither do the user events level and rule.

A chat event is one message of a page's chat room (section 12). It is never broadcast: a surface sends it with ag, once for each agent that is to hear the message, and the hub relays it to that grant alone, while the grant holds chat, in an event built from the checked fields (section 13). It needs no subscription, and neither does the user event relay (section 12). The hub takes no event from an agent, so an agent cannot send one.

Either side sends ping {ts} after heartbeatMs of silence. The answer is pong {ts} with the same value. A peer silent for 2.5 × heartbeatMs is dropped.

7. Manifest and prompt card #

A surface describes itself in hello.surface.manifest:

  • app: id, name, version, description;
  • actions: name, description, params (schema-lite object), risk, returns;
  • views: named renderers the app offers for showing data;
  • state: named pieces of app state an agent may read;
  • exposure and profile: what the UI tree exposes and which policy profile runs.

Names match NAME_PATTERN. A manifest is at most 64 KiB, 256 actions, 64 views. The hub validates it and computes digest, the base64url SHA-256 of its canonical JSON.

Canonical JSON (also used by the audit log) is JSON without whitespace, with object keys sorted by UTF-16 code units, strings and finite numbers written as ECMAScript JSON.stringify writes them (the shortest form that reads back as the same number, so 1e+21, 0.1, and 0 for -0), other numbers as null, and properties whose value is undefined left out. For JSON input this is the serialisation of RFC 8785. A value nested more than 100 levels deep has no canonical JSON.

The prompt card is the text an assistant is given so it can drive the app. It is rendered from the manifest by renderCard and is the same wherever it is produced:

# Reins surface s1: Brew Kiosk 1.0.0 (brew-kiosk)
Self-service coffee ordering.
origin http://localhost:5173 | profile guarded | scopes observe act cursor show
Prefer actions over ui ops. [confirm] asks the user on screen. [deny] is blocked.

## actions
cart.add(sku: "latte"|"mocha"|"tea", qty?: int 1..9) -> cart totals. Add an item.
order.submit() [confirm]. Place the order.
admin.refund(order: str) [deny]. Refund an order.

## views
chart(title: str, series: [{label: str, value: num}]). Bar chart panel.

## state
cart: items and totals

Rendering, line by line: # Reins surface, then <s> when the surface is known, then : <app.name>, <app.version> if there is one, and (<app.id>); the app description, if any; origin <origin> (when the surface is known), profile <profile> and scopes <scopes> (when the granted scopes are known, in canonical order), joined by |; the fixed line shown above. Then, for each of actions, views and state that is not empty, an empty line, the heading (## actions, ## views, ## state) and one line per entry in manifest order. An action line is the name, its signature, -> <returns> if any, [<decision>] unless the decision is allow, and . <description>. A view line is the name, its signature and . <description>. A state line is <name>: <description>, or the name alone. Free text is put on one line first: every run of whitespace and control characters becomes one space and the ends are trimmed. The manifest behind the example is in conformance/vectors/manifest.json.

Signature syntax: the params of an object schema in declaration order inside parentheses, () without params. Each is name: type, with ? after the name when it is not required. Types: enums as JSON strings joined by | (each one line to every reader, section 10, "Text rendering"), str, int and num with a..b when a range is given (either end may be missing), bool, [T] for arrays, {name: T, ...} for objects. The decision tag is what policy says for that action. allow has no tag.

A manifest names its profile but does not carry policy overrides, so a card rendered on the agent side shows the profile's decision for each risk tier. Where an app overrides single actions, or the hub's policy is stricter, the tag can be more permissive than what happens: the refusal (E_DENIED, E_CONSENT) is the truth. The level and the rules the person sets (section 12) are not on the card either: under auto or bypass a [confirm] action may run unasked, and a rule may block an action that has no tag.

8. Grants and scopes #

Scopes, in canonical order:

scope lets the agent
observe read the UI tree, visible text and exposed state; subscribe to events
act call the app's declared actions
ui synthesise clicks, typing, selection, scrolling and keys on exposed elements
cursor show and move the virtual cursor. Visual only: it never dispatches input
show toasts, highlights, and the app's data views
nav open same-origin URLs the policy allows
chat talk with the person in the page's chat room: say something, read what was said to it, show what it is doing

surface.attach {s, scopes, reason}:

  1. The hub intersects the requested scopes with the agent credential's cap and the hub policy's scopes. An empty result is E_SCOPE. Hub policy attach: deny is E_DENIED.
  2. The hub sends attach {agent, scopes, reason, levels, decisions, chatRelay, cred} to the surface, with c:1 when the hub policy says confirm. levels is the hub policy's human.levels, and decisions is what the hub's policy decides for each action in the surface's manifest, {"<action>": "allow" | "confirm" | "deny"} (section 12). chatRelay is the hub policy's chatRelay (off, person or on; section 12, "Chat"). cred is the id of the agent's credential (its kid, at most 64 characters): what stays the same when an agent comes back under another session id or another name ("What the person tightened stays", below).
  3. The surface intersects with its own policy, decides by its attach setting (allow, confirm with an on-screen prompt, deny), and answers {scopes, ttlMs, kept?}. A refusal is E_CONSENT or E_DENIED. scopes are the scopes granted. kept, when present, is what stays of the person's earlier settings for this agent: {level?: "strict", rules?: {"<action>": "confirm" | "deny"}, off?: [scope]}.
  4. The hub records the grant with expiry min(hub ttl, surface ttl) and returns {grant, surface, manifest, kept?}. grant.scopes holds the scopes in force: those granted, without the ones kept.off names. kept in the result repeats the level and the rules, so that the agent knows from the first moment what it is held to. An answer that is malformed, or grants none of the scopes asked for, is E_INTERNAL or E_SCOPE, and the hub sends the surface detach {why:"hub"}.

Attach is bounded, because each one may put a prompt in front of a person. The hub forwards one attach at a time per credential and surface, across all of the credential's sessions (E_BUSY for another), and allows a credential a burst of 3 attaches per surface, then one every 2 s (E_RATE). When an agent session disconnects while its attach is pending, the hub sends the surface detach {why:"agent"}, which withdraws the prompt. The surface asks even when its policy says allow if the hub is unverified, or if the user has pressed Stop, or a revocation after refusals (section 12) has happened, since the page loaded, or if the person has tightened something for an agent that the surface cannot tell this one from ("What the person tightened stays").

A surface holds at most 32 grants at a time (MAX_SURFACE_SESSIONS), so that the list a person has to read stays one they can read. A surface MUST refuse an attach from a further agent with E_BUSY, before it asks the person. An agent that holds a grant can still attach again.

One agent holds at most one grant per surface. Attaching again replaces it. A grant ends, and the hub tells each side, as follows:

the grant ends because the surface gets the agent gets
the agent sends surface.detach detach {why:"agent"} the answer {}
the agent disconnects detach {why:"agent"}
the surface disconnects evt surface {kind:"gone"}, like every agent that may attach to it
it reaches exp, or idleMs passes without a request detach {why:"expired"} evt grant {kind:"expired"}
the surface sends evt grant {kind:"revoked"} (Stop, or refusals, section 12), with ag for one agent, without for all evt grant {kind:"revoked"}
the surface reports a level that the hub's policy does not offer, more than 20 changes of what the person set within one second, or a change that lets the agent do more while the hub cannot write its audit log (section 13) detach {why:"hub"} evt grant {kind:"revoked"}
a new attach by the same agent replaces it the new attach result

A request without a live grant fails with E_NOT_ATTACHED. A request whose scope the grant lacks fails with E_SCOPE.

Scope switches. The person can switch single scopes of a live grant off and back on, in the panel (section 12). The surface refuses a request whose scope is off with E_SCOPE, and sends the hub evt grant {kind:"scopes", scopes} with ag, naming the scopes now in force. The hub MUST then let the grant carry only those of the reported scopes that were granted at attach: a report never widens a grant. The hub closes that agent's pointer streams on the surface (stream.close) when cursor is no longer among them, records the change (section 13) and tells the agent with evt grant {kind:"scopes", scopes}. When cursor goes, the surface drops that agent's pointer streams, and hides the cursor if that agent showed it last. A grant with every scope switched off stays live: the person can switch them back on.

What lets an agent do more ends with the grant. The levels auto and bypass, a rule allow, a remembered approval and what the person switched on in the chat (section 12) belong to one grant and end with it, however it ends. A new grant, also one that replaces another for the same agent, has none of them.

What the person tightened stays. The level strict, the rules confirm and deny and the scopes the person switched off hold an agent back, and no sequence of the agent's own calls takes them away: not attaching again, not a detach and a new attach, not letting the grant run out, not coming back under another session id or name. A surface MUST keep them for as long as the page lives and MUST put them on every new grant of the same agent, where they are in force from the first request: the grant starts at strict when that was kept, with the kept rules for the actions the surface still declares, and with the kept scopes switched off (a scope that is not granted this time is simply not there). What the person lifts themselves, in the panel, is no longer kept. The surface says what is kept in its attach answer (kept, step 3), and the hub starts the grant with it (section 13).

The same agent is told by the credential: a surface that got cred from a hub it verified (section 5) keeps what was tightened under that id, and every grant that comes with the same id is the same agent to it, whatever its session id or name. Two credentials are two agents. Where the surface cannot tell (the hub sent no cred, or the surface did not verify the hub), every agent is the same agent to it: what the person tightened for one is put on every later grant. Such an attach is never silent. A surface MUST ask the person about an attach that would start with kept settings when it cannot tell which agent it is from, even where its policy says allow, and the prompt says what was set and that it stays. A prompt for an attach by a known agent says the same when the policy asks anyway.

9. Methods #

Agent side. All but the first two and stream.close take s.

method params result scope
hub.info HubInfo
surfaces.list {surfaces}
surface.attach scopes, reason? {grant, surface, manifest}
surface.detach {}
observe since?, boxes? Observation observe
read h?, max? {text, truncated} observe
state.get name? {state} observe
sub / unsub topics {topics} now subscribed observe
act a, args? {result?, rev} act
ui.click h {rev} ui
ui.type h, text, clear?, enter? {rev} ui
ui.select h, value {rev} ui
ui.scroll h?, dx?, dy?, to? {rev} ui
ui.key key, h? {rev} ui
cursor.move to, ms?, wait? {x, y} cursor
cursor.set visible?, label?, color? {} cursor
show.toast text, kind?, ms? {} show
show.highlight h, label?, ms? {} show
show.view view, data? {result?} show
show.clear {} show
nav.go url {} nav
chat.say text, to? {id} chat
chat.read since?, max? {messages, next} chat
chat.status state, note? {} chat
stream.open kind:"pointer" {ch, credit} cursor
stream.close ch {}

Surface behaviour:

  • act. Unknown action: E_BAD_ARGS. Args are validated against the action's schema (E_BAD_ARGS with the failing path). A request without args carries no arguments: it is validated as {}, which is also what the handler is given, so an action that requires no property runs and a missing required property is reported by its path. Policy decides by the action's risk and overrides: deny is E_DENIED; confirm, or a request carrying c:1, shows a consent prompt and a refusal is E_CONSENT. The level and the rules the person set for the agent can add a prompt, waive one, or block the action (section 12, "Levels and rules"). Then the handler runs. Its result MUST be JSON and at most 32 KiB: a larger one is E_TOO_LARGE, a value JSON cannot hold (a cycle, a BigInt) is E_INTERNAL ("result is not JSON"), and parts that JSON.stringify drops (undefined, functions) are left out. A handler that throws yields E_INTERNAL with a generic message, unless it throws a ReinsError.
  • ui.click. Resolves the handle, scrolls it into view, dispatches pointer and mouse events and the click. Disabled elements fail with E_NO_TARGET.
  • ui.type. Focuses the element, optionally clears it, sets the value through the native setter and dispatches input and change. enter then sends Enter and submits the enclosing form. A private field fails with E_DENIED unless policy.privateInput. A target that takes no text is E_BAD_ARGS; a read-only (readonly, aria-readonly="true") or disabled one is E_NO_TARGET.
  • ui.select. Chooses an option of a <select> by value or label.
  • ui.scroll. Scrolls the element or the page by dx, dy, to top or bottom, or brings h into view.
  • ui.key. Dispatches one key from UI_KEYS on h or the focused element. Backspace, Delete and Space on a read-only or disabled target fail as ui.type does (E_NO_TARGET). Tab moves focus as the browser would among exposed elements, and never to a private one unless policy.privateInput.
  • cursor.move. Animates the virtual cursor to a target or, when policy.coordinates, to a point. Answers when the motion ends, or at once with wait:false. When the cursor is visible, ui.click, ui.type and ui.select glide it to their target first.
  • cursor.set. Shows or hides the cursor, sets its label and colour (COLOR_PATTERN). A label longer than 40 characters is E_BAD_ARGS.
  • show.toast / show.highlight / show.clear. Driver-rendered overlays. Text is always inserted as text.
  • show.view. Validates data against the view's schema and calls the app's renderer. A request without data, for a view whose schema is an object, is validated as {} and the renderer is given {}. This is how data reaches the screen without passing through a model.
  • nav.go. Resolves url against the page. It MUST be same-origin, http: or https:, with a path under one of policy.nav. Otherwise E_DENIED. A navigation that reloads the page ends the surface session, and the agent attaches again.
  • read. Visible text of an element or of the page, at most max characters (default 2000, cap 8000). Private and ignored subtrees are left out. Under annotated exposure only annotated regions are readable.
  • chat.say. Posts a message in the page's chat room (section 12). text is trimmed of white space at both ends, as ECMAScript trim does, and is then 1 to 4000 characters of well-formed Unicode; anything else is E_BAD_ARGS. Nothing inside the text is changed. to is person, for the person alone, or names one other agent of the room by its session id, as from.id of its messages gives it. to: "person" is always taken, and no agent is sent that message. Any other to is E_DENIED, at the surface and at the hub, when no other agent hears the speaker (chatRelay, section 12), whoever it names, and E_BAD_ARGS when it names no other agent that hears the speaker. The hub forwards the trimmed text and to, and no other param. The answer is the id the message has for the agent that said it.
  • chat.read. Returns the messages this agent may read (section 12), its own among them, oldest first: without since the latest max of them, with since the first max whose id is greater. max is 20 by default and 50 at most. An answer holds at most 128 KiB of JSON, and at least one message when there is one. Where that cuts an answer short, the latest are cut at their older end, so that what is returned is the newest that fits, and an answer with since stops early. next is the id of the last message returned, or since (0 without it) when there is none; passed as since it reads on from there.
  • chat.status. Says what the agent is doing. state is idle, thinking or working. note is at most 80 characters once every run of white space and control characters has become one space. Anything else is E_BAD_ARGS. The Chat tab shows state and note after the agent's name, the note quoted as that agent's words (section 12). They are told to no other agent, a note is dropped with idle, a state that was not renewed for 2 minutes reads idle again, and every state is dropped when a consent prompt comes up.
  • Targets. e12 is a handle from the tree. #cart.checkout is a data-reins-id. An unknown, detached or unexposed target is E_NO_TARGET. ui.* never accepts coordinates.
  • Ordering. A surface runs commands that change the page one at a time, in arrival order. observe, read, state.get and the three chat methods are answered immediately: chat changes the Chat tab and nothing on the page.
  • Pause. While the user has paused control, every method outside READ_ONLY_METHODS (observe, read, state.get, sub, unsub, chat.read) fails with E_PAUSED, except chat.say and chat.status (CHAT_SPEAK_METHODS): a paused agent can still answer the person.
  • Prompt up. While a consent prompt is showing or queued, every method outside READ_ONLY_METHODS, from every agent, fails with E_BUSY, chat.say and chat.status among them, and pointer frames are dropped (their credit is returned). attach, detach and stream.close still work. The page cannot change between the person reading a prompt and answering it. An action whose prompt a level or a rule waived is no exception (section 12).
  • Checks hold across waits. A command that waited (for a cursor glide, a consent prompt, or the person to stop typing) checks again, right before it acts, that the grant is live, its scope is still on, control is not paused, no consent prompt is up (except for the action just approved) and the indicator is usable. Stop or Pause pressed during a glide means the click never happens. An action that no prompt was shown for runs only if the person's level and rules still let it run without asking: otherwise it fails with E_CONSENT (the person blocked it meanwhile) or E_BUSY (it would now ask; the agent sends it again). An action the person approved does not run either once they have blocked it (the rule deny): the later word counts, and it fails with E_CONSENT.
  • Private targets. Every command that synthesises input (ui.click, ui.type, ui.select, ui.key on any key, ui.scroll aimed at an element), and a click on the label of a private control, fails with E_DENIED on a private target unless policy.privateInput. So does a command that would change a private control it does not target: ui.type with clear on an editable element that contains private elements, a radio whose group has a private member, and a reset control whose form holds a private field.
  • Pointer stream. stream.open fails with E_DENIED when policy.coordinates is off, at the hub and at the surface.

10. Observation #

The UI tree is a flat list of UiNode in document order. p points at the nearest exposed ancestor.

What is exposed. Under auto: interactive elements (buttons, links, inputs, selects, textareas, elements with an interactive ARIA role or a tabindex), headings, images with alt text, dialogs, live regions (status, alert), named landmarks and forms, and every annotated element. Under annotated: only elements carrying data-reins-id or data-reins="expose". Under none: nothing.

Never exposed. The driver's own overlay; anything hidden (hidden, inert, aria-hidden="true", display:none, visibility:hidden); any subtree marked data-reins="ignore".

Private. input[type=password], fields whose autocomplete is cc-number, cc-csc, cc-exp, cc-exp-month, cc-exp-year, one-time-code, current-password or new-password, and any subtree marked data-reins="private". A private node appears with state private and never carries val. Besides private it reports only disabled and focused, never checked or selected. Its text is never returned by read. Privacy is sticky: an element that was ever private stays private for its lifetime, so a "show password" toggle that changes the input's type exposes nothing. It also survives a node swap. A text field (a textarea, an input of type text, search, email, tel, url, password or number, or a contenteditable element) is private for its lifetime when it has the same non-empty id, name or data-reins-id as one of the last 32 private text fields that left the document, or when it is inserted under the same parent as one of them within one second of its removal.

Hidden text. Text of an element with visibility: hidden or collapse is left out of read and out of names, while its visible descendants are still read.

Fields. role is the ARIA role, explicit or implied by the tag. name follows a simplified accessible-name order: data-reins-label, aria-label, aria-labelledby, <label>, placeholder, alt, title, text content. A <label> or an aria-labelledby reference counts only when it is inside the root and neither it nor an ancestor is private, ignored, hidden or inert. A node inside a private subtree, or itself marked data-reins="private", is named only by data-reins-label. A field that is private for another reason (its type, its autocomplete, a swap) is named by its attributes and labels, never by alt, its value or its content. val is the current value of a form control. Names are cut to 120 characters and values to 200, never inside a surrogate pair.

Handles are e plus a base36 counter, assigned when an element is first seen and kept for its lifetime.

Revisions and deltas. The surface keeps one revision counter for its tree and remembers, per agent, the tree that agent last received. observe without since returns a full snapshot. observe {since} where since equals the agent's last revision returns {base, ops} with set and del operations. Any other since returns a full snapshot. A subscribed agent gets evt ui {rev} when the tree changes, at most once per 100 ms, and asks for the delta when it wants it.

Applying a delta. Ops apply in order. A set whose handle is already in the tree replaces that node in place. A set with a new handle is inserted right after the node of the preceding op when that op was a set, and at the front of the list otherwise. A del removes the node with its handle, and does nothing when there is none; either way a new handle right after it goes to the front. To place a new node, a delta may therefore repeat an unchanged neighbour as an anchor. A sender emits only set and del: diffNodes first deletes every handle that is gone or has moved (is not on a longest run of surviving nodes that keep their old order), then walks the new tree in order, sending every node that changed, moved or is new, each moved or new node right after a set of its predecessor (the first node of the tree right after the deletes). diffNodes and applyOps implement this rule and every implementation MUST use them, or match them exactly.

Text rendering. renderTree and renderOps turn observations into the compact form a model reads, one node per line, children indented one space under p:

e1 heading "Brew Kiosk"
e2 button "Latte 4.50" #menu.latte
e3 textbox "Name" = "Tiko" [focused]
 e4 checkbox "Extra shot" [checked]

A node line is the handle and the role, then "<name>" when the name is not empty, #<id>, = "<val>", [<states>] (space-separated) and @x,y,w,h, each only when present. Names and values are JSON strings. The handle, role, id and states are printed bare when they match [A-Za-z0-9_][A-Za-z0-9_.:-]*, and as JSON strings otherwise. A JSON string here is one line to every reader: besides what JSON escapes itself, U+007F to U+009F, U+2028 and U+2029 are written as \uXXXX (jsonLine), which is JSON for the same string. Some readers end a line at U+0085, U+2028 or U+2029, and a page chooses its names: without this a name could start a line of its own choosing in the tree. The title in the header line and the enum values on the prompt card (section 7) are written the same way. Delta lines are + <node line> for a new node, ~ <node line> for a replaced one and - <h> for a removed handle. A handle deleted and set again in the same delta (a move) shows only its ~ line. Rendered against the tree the delta applies to, an anchor that changes nothing shows no line.

State. An app exposes named state with a getter. state.get returns current values. A subscribed agent gets evt state {name, patch}, an RFC 7396 merge patch against the value that agent last received. A merge patch cannot express a property whose value is null, so such a property reads as absent, in the value last sent as in the new one: a state that differs from the last one only in null properties, or not at all, produces no event.

11. Cursor and the pointer stream #

One-shot motion. cursor.move costs one message. The driver animates locally at display rate along a curved path with ease-in-out timing. Without ms the duration follows distance: clamp(120 + 110 * log2(1 + d / 40), 120, 900) milliseconds.

Pointer stream. For live trajectories an agent opens a channel with stream.open and sends binary pointer frames. Points are viewport fractions with a millisecond delta each. The stream is visual, like the rest of the cursor scope. The frame layout, with every integer little-endian:

offset size field
0 u8 kind: 0x01 (BIN_POINTER)
1 u8 flags: 0x01 PTR_FLAG_DROPPABLE, 0x02 PTR_FLAG_END
2 u16 ch, the channel stream.open returned
4 u32 seq of the first point; each later point adds 1
8 u16 n, the number of points
10 6 × n the points, each u16 x, u16 y, u16 dt

A fraction f is sent as round(f × 65535) after clamping f to 0..1 (a non-finite f as 0), rounding halves up, and read back as u / 65535. dt is milliseconds since the previous point, rounded and clamped to 0..65535. A frame holds at most 2729 points (16 KiB). A binary frame whose kind is not 0x01, or whose length is not exactly 10 + 6 × n, is not a pointer frame and is dropped.

Credit. The surface answers stream.open with an initial credit in points (PTR_INITIAL_CREDIT, 512). A sender MUST NOT have more unacknowledged points outstanding than its credit. As the surface plays points back it returns credit with flow {ch, credit}, batched: it sends a flow once at least a quarter of the window has been consumed. The hub relays flow to the agent and closes a stream that overruns its credit.

Sender coalescing. A sender that produces points faster than credit arrives keeps a bounded backlog. On overflow it drops every second interior point and folds the dropped dt into the next point, so the stroke keeps its shape and its total duration. The first and last points are never dropped.

Receiver playback. The driver queues points and plays them on animation frames, interpolating between points by dt. When the queue holds more than 120 ms of motion it plays faster, in proportion to the lag and up to 4×, so the cursor converges on the live position instead of falling behind. Pause and Stop stop the cursor where it is and discard the queued points, returning their credit.

Drop policy. Frames flagged PTR_FLAG_DROPPABLE MAY be dropped by the hub when the surface's send buffer exceeds 256 KiB; the hub then returns their credit to the agent. A frame flagged PTR_FLAG_END is never dropped. seq lets the receiver notice a gap, which it bridges with a straight segment.

Rate. The hub caps the points of all pointer streams one credential has open on one surface, across all its sessions, at policy.pointerRate per second (a token bucket with a burst of one second). Every forwarded frame costs at least one point of rate. A frame with no points is dropped unless it carries PTR_FLAG_END. A stream that goes beyond the rate, overruns its credit, or whose surface stops reading so that more than 1 MiB is waiting to be sent, is closed: the hub sends the surface stream.close, drops later frames on the channel and relays no more credit. The agent is not told at once: its stream.close for that channel answers E_RATE, and until it sends that the stream counts toward its open streams. An agent that gives up on a stream, for example because no credit arrived in time, MUST still send stream.close for it.

Command batching. The driver runs queued commands at the start of each animation frame and stops when the frame has used 6 ms, so a burst of commands never blocks rendering. Cursor targets that arrive within the same frame collapse to the newest.

12. Policy #

A Policy (see protocol.ts) is a profile plus overrides. Three profiles exist:

open guarded kiosk
intended for local development a person's own browser unattended stations
attach allow confirm allow, with a provisioned agent
safe / sensitive / dangerous allow / confirm / confirm allow / confirm / deny allow / deny / deny
scopes all all observe, act, cursor, show
exposure auto auto annotated
raw coordinates yes yes no
a page inside a frame (framed) refused refused refused
navigation same origin same origin off
user controls pause, stop pause, stop pause
levels the person may set (human.levels; strict and ask are always on offer) strict, ask, auto, bypass strict, ask, auto, bypass strict, ask
the indicator opens the panel (human.panel) yes yes no
agents hear each other in the chat (chatRelay) on: always person: once the person switches it on off: never
remember approvals (consent.remember) session never never
consent.timeoutMs 60 s 60 s 30 s
human.yieldMs 600 ms 800 ms 400 ms
grant ttlMs / idleMs 8 h / 30 min 2 h / 15 min 8 h / 5 min
rates per second: observe, act, ui, cursor, show, nav, chat 30, 30, 60, 120, 30, 2, 10 20, 20, 40, 60, 20, 1, 5 20, 10, 0, 60, 10, 0, 0
pointerRate per second 4000 2000 2000

Action decisions. decideAction looks for an override in policy.actions: exact name first, then the longest matching prefix.*. Without one it uses policy.risk[action.risk].

Two enforcement points. The hub evaluates its own policy on every request and either refuses, forwards, or forwards with c:1. The surface evaluates the app's policy and takes the stricter of its decision, of what the hub said in attach that it decides for the action, and of c:1. Rate limits and grant expiry are the hub's job. Exposure, privacy, frames, consent and human control are the surface's. The person sets levels, rules and scope switches on the surface; the hub caps the levels by its own policy and enforces the scopes.

Frames. A page inside a frame is not in charge of what the person sees of it. The page around the frame can cover or overlay any part of it, the consent prompt and the indicator included, and the framed page cannot tell. A driver whose document is not the top-level document of its tab (window.top !== window.self) MUST NOT connect to a hub unless the app's policy sets framed: true. Its connect() fails with E_DENIED before anything is sent to the hub or added to the page. No profile sets framed. An app that sets it SHOULD also say which pages may embed it, with a Content-Security-Policy: frame-ancestors header. An Electron <webview> guest is in the same position, and its driver cannot tell: the guest is the top-level document of its own frame tree, while the page that embeds it can draw over it. That check is the main process's (section 3).

Consent. A prompt names the agent, the scopes or the action, and shows the arguments as text. It lives in a closed shadow root owned by the driver and accepts only trusted input events, so an agent cannot approve its own request ("The overlay and the page", below, says what that takes and where it ends). An unanswered prompt is a refusal after consent.timeoutMs. With remember: session an approved action is remembered once its handler has run, and is not asked again under the same grant unless the hub confirms the request (c:1, or an action the hub said in attach that it confirms); an approval of such a request is not remembered. The approval then covers that action name with any arguments, which is why only the open profile remembers by default. Where an approval will be remembered, the prompt says so before the person gives it. The panel shows a remembered approval where it shows the person's rules, the indicator carries a mark for it, and the person takes it back in the panel ("The panel", below). An app MAY supply its own consent handler, for example an attendant PIN on a kiosk; it gets the request as data, and the display rules below are those of the driver's own prompt.

  • What is approved is what runs. The prompt lists every argument in full and shortens nothing: indented JSON, two spaces per level, "key": value in objects. Every code point in \p{C}, in \p{Z} other than U+0020, in \p{Default_Ignorable_Code_Point}, and U+2800 is shown as a \u{XXXX} escape (hexadecimal, upper case), in the arguments and in every other string an agent or the hub wrote that the overlay shows: agent names, the attach reason, toasts and their captions, cursor and highlight labels, chat. Combining marks stack, and a letter that carries sixty of them is painted over the lines above and below it: in the same strings a surface MUST show every combining mark (\p{M}) beyond the second in a row as such an escape, and each line of the argument listing is a box of its own that clips what it paints. Arguments that cannot be shown in full are not put to the person at all: more than 40 object keys and array items in total, containers nested deeper than 4, a rendered listing of more than 2000 code points (escapes and indentation included), or a value that is not JSON. The request fails with E_TOO_LARGE. A card taller than the screen scrolls, and Allow stays inactive until the person has scrolled to its end.
  • Bounded. One pending prompt per agent and four in total. More fail with E_BUSY.
  • Cool-off. After a refusal or a timeout, that agent's action prompts, and attach prompts from any agent, are refused with E_RATE for 2 s, doubling with each further refusal or timeout up to 60 s. An approval resets it. Three explicit refusals in a row of one agent's action prompts revoke its grant as Stop does, and the third request fails with E_CONSENT; timeouts do not count toward the three.
  • No accidental approval. Allow ignores clicks for the first 500 ms after the prompt appears or moves, and shows that it is not yet active. A pointer click on Deny is taken at once.
  • Keys meant for the page answer nothing. A prompt takes the focus, and the person may be typing, tabbing through a form or about to press Enter. A surface MUST NOT take a key as the answer to a prompt unless it is Enter or Space on a button of the prompt that has the focus, or Escape (which denies), and unless all of this holds: the key is not a repeat of one held down; at least 500 ms have passed since the prompt appeared or moved, since the focus landed on that button, and since any other key was pressed; and at least 3 s (KEY_LOCK_MS) have passed since the last key that types, wherever the focus was then, also before the prompt came up. A key that types is one that gives a character, Backspace or Delete, or any key pressed with Ctrl, Alt or Meta. The rest follows from it. The prompt puts the focus on itself, the dialog, where no key presses anything, not on a button. Tab does nothing during the prompt's first 500 ms. Every key that is not itself an answer starts the 500 ms over. While the 3 s run the prompt says that keys do not answer it and that the pointer does. A person who means it still answers by the keyboard alone: Tab to the button, let the focus rest there, Enter. This goes for Deny as for Allow: a key meant for the page neither approves nor refuses.
  • Nothing an agent drew stands beside a prompt. When a prompt comes up, a surface MUST take down every toast and highlight and hide the cursor's label, and none can be put up while it shows ("Prompt up", section 9). What an agent says is on the prompt itself, under the agent's name; the cursor's label comes back when the prompt has gone, toasts and highlights do not.
  • No timer has to fire. Every wait named here is a time, compared with the clock when a click, a key or a request arrives: the arming delays, the 3 s after typing, the cool-off, the deadline of a prompt. A surface MUST NOT rely on a timer callback for any of them, because timer ids belong to the document and anything that shares the document can clear them ("The overlay and the page"). A prompt past consent.timeoutMs is a refusal from the moment anything looks at it (a click on it, the next request, the next prompt), whether or not its timer fired, and a "Request withdrawn" notice makes way the same way. A timer that never fires may leave something on screen (a toast, a highlight, a countdown that stands still, a button that still looks inactive); it never leaves anything answerable or running that would not be so otherwise. A command that waits for a glide or for the person to stop typing waits on a timer, and without it never runs.
  • The focus comes back. When a prompt goes away, the surface gives the focus back to where it was when the prompt appeared: the element of the page, or the control of the overlay.
  • No silent swap. A prompt withdrawn while it is showing (its agent detached or disconnected) becomes a "Request withdrawn" notice with no Allow button for 1.5 s before any next prompt.
  • Honest about the hub. When the hub is unverified the prompt says so.

Human control. While an agent is attached the driver shows an indicator naming it, with Pause and Stop when the policy enables them. Pause holds every command that changes the page. Stop revokes the grant: the surface sends evt grant {kind:"revoked"} and the hub ends the grant. After Stop, or a revocation after refusals, every later attach on that page needs the person's approval until the page is reloaded. Trusted pointer, key, wheel and touch input (a pointer move only with a button down) holds input-synthesising commands: every ui.* command waits until there has been no such input for human.yieldMs, then runs, and fails with E_PAUSED if the person keeps using the page for 5 s. The first such input after a quiet period of human.yieldMs emits evt user {kind:"override"}.

The indicator has to stay visible and usable. A modal dialog or a fullscreen element covers the rest of the page and makes it inert, so while one is open the driver moves its overlay inside it. The indicator also stays above a consent prompt's backdrop, so Pause and Stop work while a prompt is up. Whenever the overlay cannot be shown where the person can see and use it, every method outside READ_ONLY_METHODS, and attach, fails with E_PAUSED.

The overlay and the page. The indicator, the panel and the prompts are the overlay. It shares a document with the page's own stylesheets and scripts. What follows keeps the page's stylesheets from changing what the person reads in it, and keeps an agent, and events a script makes or borrows, from answering in the person's place. It does not keep out script that runs in the page itself; the last item says where that ends.

  • Its own style. The overlay's stylesheet MUST NOT read a custom property and MUST NOT name a font family other than the generic system-ui, sans-serif, serif and monospace. A page can set a custom property for the whole document, register one so that it takes no value from outside (@property), and define a font under any other name (@font-face). The host element resets every property (all: initial) and pins direction and unicode-bidi, which all leaves alone. Both colour schemes are written out in the stylesheet and chosen by prefers-color-scheme. The stylesheet names no system colour and fetches nothing, and what is not written in the plain subset the driver checks it against (no escapes, no comments, a fixed list of functions and at-rules) is refused rather than read.
  • No box of the page's on the host. The host is an element of the page's document, so a page selector can name it and give it boxes of its own: ::before and ::after, which lie over everything inside it, top layer or not, and with :focus-within only while a prompt holds the focus. The overlay's stylesheet MUST take the host's ::before, ::after and ::marker away and keep its ::backdrop from showing, with declarations a page rule cannot override, and it sets the colours of selected and highlighted text inside the overlay itself (::selection, ::target-text), so that none of them is the page's to choose.
  • The top layer. Where the browser has the Popover API, the host is a popover="manual" element. The surface shows it, and shows it again when another element has entered the top layer after it, so that it is painted last. There a filter, an opacity, a transform, a clip path, a mask or a blend mode on an ancestor does not reach it, and no z-index of the page lies above it. Inside a modal dialog or a fullscreen element the host still moves in, as above. Where the Popover API is missing the host is a fixed element at the highest z-index, an effect on an ancestor does reach it, and the check below is all that stands between such a style and the person.
  • Checked. A surface MUST treat the overlay as one that cannot be shown where the person can see and use it (above) while any of this holds: the host is not in the document, is inert, or does not cover the viewport; where the Popover API exists, the host is not in the top layer or is not the last element in it; the host is not drawn at its own size, because zoom on it or on an ancestor multiplies down to it, top layer or not; the host has content-visibility: hidden, an opacity below 1, a visibility other than visible, a filter, a backdrop-filter, a clip-path, a mask-image, a transform (also as translate, rotate or scale) or a mix-blend-mode; the host or an ancestor has display: none or content-visibility: hidden, or an ancestor has any other of those while the host is not in the top layer; the indicator has no box, or is not what a hit test finds at its own centre; or the browser reports the indicator, the open panel or the prompt that is showing as not visible, where it can (IntersectionObserver with trackVisibility). Whether there is a layout to check at all is asked of the window (it has a visual viewport with a size), not of the overlay's boxes: a page that renders nothing leaves every box empty, and that is a failed check, not a missing layout engine. The three things the observer watches are not animated in and keep clear of each other's shadows, so that what it reports is the page's doing.
  • Nothing loosens meanwhile. While the overlay cannot be relied on in that sense, a surface MUST NOT take a click on Allow or "Always allow" of a prompt, nor on a control of the panel that lets an agent do more ("The panel", below). The prompt stays up and its time runs on; Deny, and what makes an agent do less, are still taken. Once the overlay can be relied on again, the card and the open panel say that a click was not taken and why, and every arming delay starts again. A check that had to put the overlay back (show it again in the top layer because something had come over it, or move it) found it covered or out of place: the click that caused that check was made on what the person saw then. A surface MUST NOT take that click as one that lets an agent do more; only a later, separate one counts. Commands go on once the overlay is back.
  • Only the person's input. A surface MUST NOT act on an event unless the browser made it for input of the person (isTrusted) and is delivering it to the control the listener was registered on. The reference driver reads isTrusted through the getter the browser defines for it, and keeps that getter and the functions it registers listeners, builds elements, sets timers and reads the clock with from the moment its script first runs. So an object that says it is trusted, an event a script dispatched, and a real click of the person on something else that a script hands to a control's listener all do nothing, and a script that replaces addEventListener afterwards is handed no listener of the overlay to call. The watch for the person's own input ("Human control") reads the same getter. That is all this item closes: forged events, and borrowed ones, through hooks on the functions that register listeners.
  • Where it ends. Script that runs in the page's own JavaScript realm can defeat the overlay, whatever the order in which it and the driver load. The driver is ordinary script in that realm: it keeps its prompts in an array and its sessions in a map, sets attributes and reads properties through methods every script can replace, and a script that replaces Array.prototype.push, Map.prototype.get or Element.prototype.setAttribute after the driver has attached is handed prompts to answer, sessions to change and the closed shadow root itself, with no input from the person at all. Such script can also draw its own copy of an indicator or a prompt, or simply call the app's functions. It is outside what "trusted input only" defends against, here and in section 14 (docs/SECURITY.md), and no load order changes that. There is a boundary where the driver does not share a realm with the page: in an app adopted by reins-electron (section 15) the driver runs in an isolated world with built-ins of its own, and the page's script reaches the document it shares with the driver (elements, styles, timers) and nothing of the driver's code or objects. What it can still do there is what this section handles as the page's doing: style the host, cover it, remove it, and clear timers ("No timer has to fire", above). A browser without the Popover API leaves the overlay outside the top layer, and one without trackVisibility (every engine but Chromium) cannot tell the surface that something the document does not list is painted over it: there a click that finds the overlay covered is not taken, and a cover that takes no clicks and that the document does not list is not noticed.

Levels and rules. How much the person is asked about one agent's actions is theirs to set, for each grant. A grant has a level, one of LEVELS:

level what an act request does
strict asks every time, also for an action the policy allows
ask asks when the policy says confirm or the hub sent c:1
auto runs without asking, unless the action's risk is dangerous
bypass runs without asking

A grant starts at ask, or at strict where the person set that for the same agent before and the surface kept it (section 8). strict and ask are on offer for every grant, whatever a policy lists: neither lets an agent do more. auto and bypass are on offer where both the surface's policy and the hub's policy list them in human.levels. The hub sends its list in attach (section 8), and a surface that got no list offers strict and ask alone. A surface MUST NOT put a grant at a level that is not on offer for it.

What the hub decides. The hub's policy decides each action as the surface's does, and may be stricter. The hub says so in attach: decisions holds its decision for each action in the surface's manifest (section 8). Wherever this section speaks of what the policy decides for an action, a surface MUST take the stricter of its own policy's decision and the hub's (stricter, with deny before confirm before allow), and MUST take the hub's as confirm for an action that decisions does not name, for a value that is not a decision, and when the hub sent no decisions at all: such a hub may confirm anything. hubDecision reads it that way. The surface also holds the hub to its word. A request for an action the hub said it confirms is treated as carrying c:1 whether it does or not, a request for one the hub said it denies is refused with E_DENIED, and a request that carries c:1 for an action the hub said it allows asks all the same. What the panel shows as asking therefore does ask, and no step in the panel waives without saying so a prompt that only the hub wants.

The person can also set a rule for one action of one agent: allow, confirm or deny. A rule covers the action name with any arguments, and the panel and the prompt say so where a rule is set. confirm and deny only tighten and can always be set. allow for an action the policy asks about can be set only where a level on offer would waive the same prompt: auto or bypass for an action that is not dangerous, bypass for a dangerous one. Where it cannot be set, the panel shows Allow switched off and says why, so that no honest click sets a rule the hub would refuse (section 13). No rule can be set for an action the policy denies.

An act request is decided in the order below. decideAct implements it, and every surface MUST use it or match it exactly; conformance/vectors/levels.json lists the cases.

  1. The policy's decision for the action (decideAction), made confirm at least when the request carries c:1 or the hub said that it confirms the action. deny is E_DENIED: nothing the person sets relaxes a deny.
  2. The rule deny is E_CONSENT ("the user blocked this action"). No prompt is shown and nothing counts toward the cool-off.
  3. A prompt is needed when the decision is confirm, or the level is strict, or the rule is confirm.
  4. A needed prompt is waived by the rule allow, by the level bypass, and by the level auto unless the action's risk is dangerous. A rule beats the level: under bypass the rule confirm still asks, and under strict the rule allow still runs.
  5. The rule allow waives a prompt that step 1 demands only where it could be set (see above). A level of auto or bypass that is not on offer counts as ask.
  6. A prompt that is still needed is shown, unless a remembered approval answers it (remember: session). Nothing is remembered, or answered from memory, under strict, under the rule confirm, or for a request the hub confirms (step 1).

A waived prompt is not an approval. An action that runs because a level or a rule waived its prompt MUST NOT run while a consent prompt is showing or queued: it fails with E_BUSY, like any other command, and it is not remembered as approved. Changing a level or a rule answers no prompt: one that is showing or queued stays until the person answers it or it times out. Levels and rules decide act requests only; the other scopes are switched off as a whole (section 8).

The panel. With human.panel the indicator's text is a button that opens a panel in the same closed shadow root. Its Permissions tab shows, for each attached agent: the agent's name, a mark when the hub is unverified, the level with one plain line for each level on offer, every action of the app with its risk and what happens now when that agent calls it (Allow, Ask or Block; "Blocked by app" or "Blocked by hub" where a policy denies), the scopes of the grant as switches, and, where the policy has Stop, a control that ends that one grant as Stop does. Under each action it says why it stands as it does: the person's rule, an approval the surface remembers, or the level, and that the hub asks about it where only the hub does. Its Activity tab lists the last 50 commands: the time, the agent, the method or the name of a declared action, the outcome, and whether the person, a level, a rule or a remembered approval let an action run. The same command of the same agent several times in a row is one line with a count; two agents with one name are two agents there too. The activity list MUST NOT hold arguments, results or page text. Its Chat tab is the page's chat room ("Chat", below).

  • Only the person. The panel opens and closes on the person's trusted input alone (as "The overlay and the page" defines it, with the limit stated there), and Escape closes it. No protocol message opens it, closes it or reaches anything in it. A surface MUST NOT change a grant's level, a rule or a scope switch except on trusted input from the person on its own controls.
  • Loosening takes two steps. A surface MUST show a confirm step, and apply the change only when the person confirms it there, before each of these: a level of auto or bypass above the current one; any level under which an action that asks now would stop asking (ask after strict); the rule allow, always, whatever it waives at that moment; and Reset where the action would then run without asking. The step names the agent, lists the actions that would stop asking, among them those that only the hub asks about, repeats the warning about an unverified hub when that applies, and its confirm button ignores activation for the first 500 ms after the step appears or moves. A step that opens below the visible part of the panel is scrolled into view. "Always allow" on a prompt sets the rule allow the same way: a second press, armed again, after the card has said what the rule covers. What makes an agent ask more or do less applies at once: a level under which nothing stops asking, the rules confirm and deny, a scope switched off, a reset after which the action asks. Lifting the person's own Block to Ask, and switching a scope back on, give back a prompt or what the person granted at attach: they take one click, on a list that has settled (below).
  • Reset, and what is remembered. The panel MUST NOT show an action as asking while an approval the surface remembers would let it run: it shows it as allowed and says that the person approved it earlier. Reset takes the person's rule for the action away and that approval with it, and choosing Ask forgets the approval as well.
  • Always in sight. While an attached agent's level is not ask, the indicator MUST show that level: a chip with its name, and a dot that is amber for auto and red for bypass. While a rule allow of the person waives a prompt that would otherwise be shown, the indicator MUST show that too: a chip that counts those rules, and the dot of the level that would waive the same, amber, or red when one of the actions is dangerous. An approval the surface remembers does what such a rule does, and is counted on the same chip while it lets an action run without asking. The indicator's colours and marks are part of the overlay's own stylesheet ("The overlay and the page"), not values a page can set. Pause and Stop stay where they are and stay usable while the panel is open, also inside a modal dialog or a fullscreen element.
  • Named apart. Wherever the overlay names an agent in words of its own (a prompt, a confirm step, a heading of the panel, the indicator, a line of the activity list), the agent's name MUST be shown inside quotation marks, with quotation marks inside the name shown as escapes, and followed by its session id, so that a name cannot pass for words of the surface or finish one of its sentences, and two agents with one name are told apart.
  • No silent redraw. When what is under the pointer changes other than by the click the person is making, the controls that let an agent do more ignore activation for 500 ms. That is so when the list changes (an agent attached or left), when a consent card or its backdrop goes away, when a confirm step opens, and after the person's own click on a confirm step's button, whose second half as a double click lands on what comes up under it. While a consent prompt is up, a wide viewport shows the card beside the panel; on a narrow one the panel stays under the prompt's backdrop until the prompt is answered. With focus in the panel, Escape closes the panel and denies nothing.
  • Told, and recorded. The surface reports each change to the hub with ag: evt user {kind:"level", level}, evt user {kind:"rule", a, d} (d is null when the rule was removed) and evt grant {kind:"scopes", scopes}. The hub records them and tells the agent (sections 8 and 13).
  • One grant for what loosens. A surface MUST NOT carry the level auto or bypass, a rule allow or a remembered approval from one grant over to another. What the person tightened it carries (section 8).

Chat. A page has one chat room: the person at the page, and every attached agent whose grant holds chat with the scope switched on. The room is the Chat tab of the panel, the third after Permissions and Activity, so a surface that has no panel to open (human.panel off, or no indicator) grants no chat scope. The person reads and writes in the tab. An agent speaks with chat.say, reads with chat.read, says what it is doing with chat.status (section 9), and hears the room as evt chat (section 6).

A message is {id, from, text, ts, to?}. id is a label for chat.read. For each agent it counts up from 1 on each page load over the messages that agent may read, its own among them, and it goes on counting when the agent's grant is replaced. One message so has a different id for each agent it reaches, and an agent's ids say nothing about what was said to others. from is {kind:"person"} or {kind:"agent", id, name}, with the agent's session id and the display name its grant carries. text is 1 to 4000 characters. ts is the surface's clock in epoch milliseconds. to is the session id of the one agent a message was addressed to, or person on an agent's message for the person alone; no hub hands out person as a session id. The room keeps the last 200 messages, in memory and nowhere else: the transcript ends with the page.

Who hears whom. Every agent in the room hears the person. Whether agents hear each other is chatRelay, a field of the surface's policy and of the hub's: off (never), person (once the person switches it on in the Chat tab) or on (always). The stricter of the two applies, off before person before on. The hub sends its value with every attach (chatRelay in the params), and a surface that is sent none takes it as off. In a policy file true reads as on and false as off. The agents that hear each other are, under on, every agent in the room; under off, none; and under person, the agents the person switched on ("Who hears whom is the person's choice", below).

The person sees every message in the Chat tab, also what one agent says to another, each under who said it and, when it was addressed, to whom. Which agents are sent a message is decided in the order below. chatAudience implements it, and every surface MUST use it or match it exactly; conformance/vectors/chat.json lists the cases.

  1. A message of the person goes to the agent to names when that agent is in the room, and without to to every agent in the room. A message that no agent would hear is not kept: one addressed to an agent that has left is not sent to the others instead.
  2. An agent's message with to: "person" is kept and is sent to no agent, whatever the room relays.
  3. An agent's message with any other to is refused with E_DENIED when the speaker is not among the agents that hear each other, whoever to names, so that the answer says nothing about who else is attached. Otherwise it is refused with E_BAD_ARGS when to names no other agent among them, and else it goes to that agent alone.
  4. An agent's message without to goes to every other agent that hears the speaker, and to no agent when the speaker is not among the agents that hear each other. A speaker is never sent its own message.
  • Who hears whom is the person's choice. Under person no agent hears another until the person switches "Agents can hear each other" on in the Chat tab. That lets agents receive more, so it is made like raising a level: on trusted input, through a confirm step that names every agent that will then hear the others, and whose button ignores activation for the first 500 ms. Like every change that lets an agent do more, neither the switch nor the step is taken while the overlay cannot be relied on ("The overlay and the page"). It covers the agents that step named and no other. An agent that joins the room afterwards (a new grant, a grant that replaces another, a chat scope switched back on) hears the person only, and only the person hears it, until the person adds it through the same confirm step, which names it and the agents it will hear. Switching off applies at once, to all. When fewer than two of the agents switched on are left in the room, the switch is off again. When a hub sends another chatRelay with a later attach than it sent before, what the room relays changes and the person's switch goes with it: the surface reports relay off for each agent that was switched on, and the Chat tab says that the hub changed it, until the person uses the switch again. When an agent leaves or joins, the choices of whom a message goes to move: for 500 ms a press on them chooses nothing, like Send. A surface MUST NOT let one agent hear another under person except on that input from the person. Whenever an agent is in the room, the Chat tab MUST say which agents hear the person only and which hear each other, naming each of them; under on it says that the app is set up that way.

  • Told, and recorded. The surface reports each such change to the hub with ag, once for each agent it changes: evt user {kind:"relay", on}. The hub records it and tells that agent (section 13).

  • Only while the grant is live. Who may read a message is fixed when it is posted: its speaker and those it was sent to. A surface MUST NOT give an agent, in evt chat or in chat.read, a message that was posted before its grant began, while its chat scope was switched off, or that was not sent to it. A grant that replaces another reads nothing of the earlier one's room, and when a grant has ended there is nothing left to ask.

  • Only the person speaks as the person. A surface MUST NOT produce a message from the person except from trusted input events in the composer of its own Chat tab, which lives in the driver's closed shadow root. Send and Enter act on trusted events only; Shift with Enter is a line break, and an Enter that ends an input-method composition belongs to the composition. A text in the field that no trusted input event left there is never sent. A lone surrogate in what the person typed becomes U+FFFD. No method, parameter or event posts as the person, and neither does the driver's API. This keeps agents out. It does not keep the page out: the app that embeds the driver, and every script that app loads, can read the composer and the transcript and can alter what is sent, exactly as it can with any field of its own page (a listener on the window is given the keys first, and the browser's editing and selection commands reach into the tab). Chat is not secret from the app, and the app's own page is outside what this protocol defends (docs/SECURITY.md). A driver stops the events of typing and editing at its tab, as it stops keydown at the panel, so that listeners a page registered in the ordinary way do not see them.

  • Agent text is data. A surface MUST insert what an agent wrote as text, never as markup, with every code point escaped that the consent prompt escapes in agent-written strings. Line breaks stay line breaks. Each message of an agent is captioned as an agent's first, then with the display name from that agent's grant in quotation marks and with the agent's session id, never with a name the message supplies: an agent that calls itself "You" does not read as the person, and two agents with one name differ. Wherever the tab names an agent in a sentence of its own it names it that way, and what an agent says it is doing (chat.status) is shown in quotation marks after that name, as the agent's own words. Agent-written text is laid out so that it neither paints over nor reorders the tab's own words, and the caption of a message stays in view while its text scrolls. Nothing in a message becomes a link.

  • A message grants nothing. A chat message MUST NOT change a grant's level, a rule or a scope switch, and MUST NOT answer, waive or withdraw a consent prompt, whatever it says and whoever sent it. An action that needs the person's approval asks on its prompt after the person typed "yes" in the chat exactly as before.

  • Nothing stands next to a decision. While a consent prompt is showing or queued, a surface MUST NOT show in its Chat tab anything an agent wrote: no transcript, no status and no agent's name, only a line of its own saying that chat is hidden until the request is answered. chat.say and chat.status fail with E_BUSY (section 9), nothing can be typed or sent, and what the agents said they were doing is dropped and does not come back when the prompt has gone. So an agent cannot put words next to a prompt, also not by saying them just before it, and the person cannot take the chat for the answer. While control is paused the chat goes on.

  • An addressed message stays addressed. When the agent the person is writing to leaves the room before the message is sent, the tab says that it left and sends nothing until the person has chosen again: the message never goes to the others instead. For 500 ms after the room changed other than by the person's own input (an agent joined or left, or who hears whom changed), Send and Enter are ignored.

  • Not delivered. When the hub does not relay a message of the person to an agent (section 13) it tells the surface, and the tab marks that message as not delivered to that agent.

  • Honest about the hub. When the hub is unverified the Chat tab says so, as the consent prompt and the Permissions tab do: whoever is behind that hub is behind every agent in the chat.

  • Unread, and never in the way. A message of an agent that arrives while the Chat tab is not showing counts as unread: the tab carries the count, and so does the indicator. The panel does not open for it. A message that arrives redraws nothing outside the Chat tab, arms no control again and moves no focus.

  • Typing is using the page. Trusted input in the composer counts as input on the page for the human-priority rule ("Human control"): ui.* commands wait until there has been none for human.yieldMs. When a command moves focus while the person's focus is in the composer, the driver gives the focus back as soon as the command's synchronous part has run. While the app's own code runs because an agent asked for it, the composer takes no input: what such code puts into a focused field was chosen by the agent. That is an action's handler, a view's renderer (show.view), a state getter (state.get), and the app's event handlers during a command that synthesises input (ui.*).

  • What the driver hands out. The driver's API tells the app that a message was posted, by whom and how long it is (section 15), not its text, and no observe and no read returns the transcript: it is in the closed shadow root and outside the UI tree. That is what the driver hands out. It is no secret kept from the page ("Only the person speaks as the person", above).

Toasts are agent-written, so each one carries a caption naming the agent that sent it.

No code execution. Nothing in the protocol evaluates agent-supplied code, HTML or CSS. Agent text is inserted as text. The cursor colour is the only style value and must match COLOR_PATTERN. URLs are restricted as in section 9.

13. Hub behaviour #

  • Rate limits. One token bucket per credential, surface and scope, sized by policy.rates, with a burst of one second, shared by all of that credential's sessions. hub.info and surfaces.list share one bucket per credential: 10 a second, burst 20. Over a limit: E_RATE.
  • Capacity. At most 64 surfaces, 32 agents, 4 sessions per credential and 8 open streams per agent by default. Beyond that: E_BUSY. A peer whose send buffer at the hub holds more than max(8 MiB, 4 × maxText) after a send is not reading: it is sent bye {code:"E_BUSY"} and closed.
  • Admission. Surface connections from an allowed origin are admitted by a token bucket per origin, surfaceAdmission.rate a second (default 2) with a burst of surfaceAdmission.burst (default 2 × the surface capacity), and by one for all origins together with 5 × the rate and 2 × the burst. A full hub answers E_BUSY first; an attempt without a token is E_RATE. Agent sessions are admitted after a correct proof by a bucket per credential, agentAdmission.rate a second (default 2), burst agentAdmission.burst (default 20), else E_RATE.
  • Configuration. A hub refuses malformed configuration at start: a field of the wrong type, a key shorter than 32 characters, a limit that is not a positive number. A restriction that is present but mistyped never means "any".
  • Surface events and listing. An agent hears about a surface only if its credential may attach to it. Without a live grant that includes observe, the SurfaceInfo it gets is reduced: url is the origin and title is the app's name. The full URL and title go only to agents holding such a grant. evt surface with kind added or gone goes to every agent that may attach; changed goes only to agents holding a grant on that surface. For an agent, hub.info counts only the surfaces it may attach to and only its own credential's sessions.
  • What the person set. A surface reports the level, the rules and the scopes the person set for one grant (section 12). The hub drops a report that is malformed, that names no live grant, or that names an action the surface did not declare. What it does with the rest depends on what the report would change.
    • A level beyond the policy. The hub MUST end the grant when the surface reports the level auto or bypass and the hub policy's human.levels does not list it. The surface then gets detach {why:"hub"}, the agent evt grant {kind:"revoked"}, and the refused report and the end of the grant are both recorded. strict and ask are always taken: neither lets an agent do more. An honest surface was sent the hub's list at attach and offers no other level.
    • A rule the hub would not honour. The rule allow for an action that the hub's policy denies, or that it wants confirmed while human.levels lists no level that would waive that prompt, is recorded as refused. The hub MUST NOT keep such a rule or tell the agent of it. The grant goes on: the rule changes nothing at the hub, which still refuses or marks every request for that action itself, and a surface that follows section 12 does not let the person set it.
    • What is kept. A surface's attach answer may say what stays of the person's earlier settings for the agent (kept, section 8). The hub starts the grant with the level strict, with the rules confirm and deny for actions the surface declares, and without the scopes named as switched off, and records each as a person record with the outcome kept. The hub MUST NOT read anything else from it: no other level, no rule allow, no scope that was not granted. No attach answer lets an agent do more.
    • A repeat. A report that repeats what the hub holds for the grant changes nothing and is not told to the agent. Its record falls under the bound below.
    • A change. Any other report is a change. The hub keeps the level or the rule, applies the scopes (section 8), and tells that agent alone, in an event built from the checked values. The hub MUST record every change, whatever else the surface sent in the same second. A grant for which a surface reports more than 20 changes within one second is ended like one with a level beyond the policy: no person makes them, and the report that went over is recorded as refused and is neither kept nor told.
    • While the log cannot be written ("Fail closed", below). A change that lets the agent do or hear more (a higher level, a rule that holds an action back less, a scope switched back on, the chat switch on) is in force on the surface already when its report arrives. The hub MUST end the grant when it cannot record such a change, as for a level beyond the policy. A change that only tightens is kept and told; its record waits with the others.
  • Chat relay. A surface sends evt chat once for each agent that is to hear a message, each with ag and with the id the message has for that agent (section 12). The hub MUST relay a chat event only to the grant its ag names, and only while that grant is live and holds chat: an event without ag, or naming a grant the surface does not hold, is dropped. The hub also drops an event that is not a well-shaped message or that is addressed (to) to anyone but that agent (another agent, or the person alone), and an agent's message when the hub's policy does not let that agent hear its sender, when its sender holds no live grant with chat on that surface, or when it would go back to its sender. The hub's policy lets one agent hear another always under chatRelay on, never under off, and under person when the surface has reported for both grants that the person switched them on. What the agent gets is built from the checked fields, and the sender's name in it is the one the hub gave that agent (section 5), not the one in the event.
    • What the person switched. A surface reports with ag that the person lets a grant hear the other agents, or no longer does: evt user {kind:"relay", on} (section 12). The hub drops a report that is malformed or that names no live grant that was granted chat. A report of on under a hub policy of off, or for a grant whose chat scope is switched off, is recorded as refused and is not kept; the grant goes on, because the hub relays by its own policy whatever a surface reports. A report that repeats what the hub holds changes nothing. Any other report is kept, recorded, and told to that agent alone as evt user {kind:"relay", on}. A grant whose chat scope is switched off is no longer switched on.
    • Budgets. Each sender has a budget of its own for each agent that listens, and none uses up another's. Messages of the person: 5 a second after a burst of 10, for each agent. An agent's words: that agent's rates.chat a second after a burst of twice that, for each agent that hears it, so that a surface which relays what chat.say let through is never cut short. A message of the person beyond its budget, one the audit log cannot take a record of ("Fail closed", below) and one that does not fit a frame are not relayed, and the hub tells the surface with the request chat.undelivered {id} and ag, where id is the message's id for that agent, at most 20 times a second for one surface. The surface shows the message as not delivered to that agent (section 12). A relay of an agent's words beyond its budget is dropped and recorded. So is one that the hub's policy refuses (the two do not hear each other): not handed over, and on record with the outcome refused, under the same bound. While the audit log cannot be written, no agent's words are relayed either.
    • chat.say. It is checked at the hub as well. A text out of bounds is E_BAD_ARGS. A to other than person is E_DENIED when the hub's policy lets no agent hear the speaker: under off, and under person while the speaker is not switched on. The hub forwards the trimmed text and to, and no other param.
  • Audit. The hub appends one record for each connection, attach, detach, grant end, every refused request, and every act, ui.*, nav.*, show.view, show.toast, show.highlight, chat.say, stream.open and surface.attach request. cursor.*, show.clear, chat.read, chat.status and pointer frames are not audited. It also appends one record of kind person for each level, rule and scope report that changes what the hub holds for a grant, and, within the bound below, for each one that repeats it or that the hub does not take ("What the person set", above): the agent, the surface, method (level, rule or scopes), the action name for a rule, value (the level; the rule's decision, or none for a rule removed; the scopes in force, or none) and the outcome ok, refused, or kept for what a grant starts with (section 8). And it appends one person record for each message of the person that it relays to an agent: method chat, the agent, the surface, chars (the length of the text) and args, here the digest of the canonical JSON of {text}, with to when the message was addressed. A chat.say record is digested the same way: its args covers {text}, the text as the room keeps it (trimmed), with to when it has one, and nothing else the agent sent, and its chars is the length of that text. One text so gives one digest, whoever said it. A message of the person that the hub did not relay is a person record with method chat and the reason as its outcome (E_RATE, E_INTERNAL, E_TOO_LARGE). What the person switched for one agent in the chat is a person record with method relay and value on or off. A relay of an agent's words that the hub did not hand over is a record of kind chat: method relay, the outcome dropped (beyond the budget) or refused (the policy does not let the two hear each other), and the agent that spoke. The text of a chat message MUST NOT be written to the audit log: a message is on record by its length and its digest. A record has seq (counting from 1), ts, kind, agent, surface, method, action name, value, chars, outcome, args, the duration, prev and hash. args covers the request params without s: b64url(HMAC-SHA256(auditKey, canonical JSON)) when the hub has an audit key, else b64url(SHA-256(canonical JSON)). Arguments are never logged in clear; without a key, a reader of the log can still test guesses of low-entropy arguments against args.
    • Chain. hash = b64url(SHA-256(prev + "\n" + canonicalJson(record without hash))), or b64url(HMAC-SHA256(auditKey, ...)) of the same input when the hub has an audit key. prev is the hash of the record before, and the empty string for the first record. The unkeyed chain shows corruption and careless edits. Only the keyed chain shows an edit by someone who can write the file. Truncation shows only against the head ({seq, hash} of the last record), which the hub writes next to the log and which should be kept somewhere the log's writer cannot change. A hub refuses to continue a log whose chain or head does not verify.
    • Recorded before it happens. For a request that is audited when it succeeds, an accepted record is written before the request is forwarded, and the outcome record that follows refers to it with ref.
    • Fail closed. When the log cannot be written, or more than 1000 records are waiting, audited requests and attach fail with E_INTERNAL, no chat message is relayed, the person's or an agent's ("Chat relay", above), and a reported change that lets an agent do or hear more ends its grant ("What the person set", above). Requests that are not audited are still served, and a change that tightens is taken.
    • Bounded. At most 20 refusal records per second per connection, 20 failed-connection records per second overall, and 20 person records per second per surface for reports that change nothing (a repeat, a rule the hub does not take), with as many again for dropped relays of agents' chat messages (kind chat). A change of what the person set is always recorded, and so is a message of the person that is relayed. The excess is counted and written as one suppressed record.
  • Shutdown. The hub sends bye {code:"OK"} to every peer before closing.

14. Security requirements #

The numbered rules an implementation MUST meet. docs/SECURITY.md has the threat model behind them.

  1. The hub listens on loopback only and validates Host, Origin and the remote address on every upgrade.
  2. Agents authenticate with a 256-bit secret by HMAC challenge-response. The hub proves possession of the same secret. Every message of an authenticated session is sealed with a MAC bound to the handshake.
  3. Secrets are never placed in URLs, never logged, and stored in files only the owner can read.
  4. Surfaces are admitted by origin allowlist, and by key where the deployment requires it or holds a key for the app id they claim.
  5. Every forwarded request is checked against a live grant, its scope and its rate.
  6. The surface re-checks every request against the app's policy.
  7. Arguments are validated against a schema before any handler runs. Undeclared properties are rejected.
  8. No frame, argument or result can cause code, markup or style to be evaluated.
  9. Private fields are never read and, by default, never written.
  10. Consent, the control indicator and its panel are isolated from the page's styles and from what its scripts can reach, and act only on input that the browser itself made for the person and delivered to their own controls. Script that runs in the page's own JavaScript realm is outside this rule, whatever the order in which it and the driver load; where the driver has a realm of its own (an adopted Electron app), the rule holds against the page's script too (section 12, "The overlay and the page").
  11. A human can always see that an agent is attached. Pause and Stop work without the hub's cooperation.
  12. Errors carry no internals. Observations are size-bounded.
  13. The audit log is append-only and hash-chained, keyed where the deployment needs to detect edits, and the hub refuses attach and every audited request while it cannot record.
  14. Everything a surface reports (names, values, text) is untrusted input to the agent and is presented to a model as data.
  15. A grant's level, rules and scope switches change only on the person's trusted input on the surface, and a change that lets an action run without asking only through a confirm step. Nothing the person sets relaxes a deny of the surface's policy or of the hub's, the hub ends a grant whose surface reports a level beyond the hub's policy and takes no rule that policy would not honour. What lets an agent do more ends with the grant; what the person tightened stays with the agent, whatever the agent does.
  16. Chat is data and grants nothing. A message of the person comes only from trusted input in the surface's own chat tab, an agent's text is shown as text under the name its grant carries and never next to a consent prompt, agents hear each other only where the policy or the person says so, the hub relays a message only to the grant it names and records its length and digest, never its text, and no message changes a level, a rule, a scope switch or the answer to a consent prompt.

15. Reference implementation #

Six packages. The public API of each is normative for this repository.

@reins/core (isomorphic, no dependencies) #

TypeScript
// everything in protocol.ts, plus:

// codec
encodeFrame(f: Frame): string
decodeFrame(text: string, maxBytes?: number): Frame            // throws ReinsError E_BAD_FRAME / E_TOO_LARGE
encodePointer(f: PointerFrame): Uint8Array                     // clamps x, y to 0..1 and dt to 0..65535
decodePointer(bytes: Uint8Array): PointerFrame                 // throws E_BAD_FRAME
binaryKind(bytes: Uint8Array): number
utf8Length(text: string): number

// schema
validate(schema: Schema | undefined, value: unknown): string | null   // null when valid, else "path: reason"
checkSchema(schema: unknown): string | null                           // is this a well-formed Schema
schemaSignature(schema: Schema | undefined): string                   // "(sku: "latte"|"mocha", qty?: int 1..9)"

// manifest
validateManifest(m: unknown): Manifest                         // throws E_BAD_ARGS / E_TOO_LARGE
canonicalJson(v: unknown): string                              // section 7; throws E_BAD_ARGS when nested deeper than 100, cyclic or BigInt
manifestDigest(m: Manifest): Promise<string>
renderCard(m: Manifest, ctx?: { surface?: SurfaceInfo; scopes?: Scope[]; policy?: Policy }): string

// policy
resolvePolicy(input?: PolicyInput): Policy                     // validated deep copy of a preset plus overrides
decideAction(policy: Policy, action: { name: string; risk: Risk }): Decision
decideAct(q: { base: Decision; risk: Risk; c?: boolean; level: Level; rule?: Decision; offered: Level[] }): { outcome: 'run' | 'prompt' | 'denied' | 'blocked'; by?: 'policy' | 'level' | 'rule'; remember?: boolean }   // section 12, levels and rules
capLevels(...lists: Level[][]): Level[]                        // the levels on offer: `strict` and `ask`, and `auto` and `bypass` where every list names them
allowRulePermitted(risk: Risk, offered: Level[]): boolean      // may the rule `allow` waive a prompt the policy demands
actionDecisions(policy: Policy, actions: { name: string; risk: Risk }[]): Record<string, Decision>   // what a hub sends in attach as `decisions`
hubDecision(decisions: unknown, name: string): Decision        // what a surface reads from it: `confirm` for anything missing or malformed
keptSettings(v: unknown, granted: Scope[], actions: Iterable<string>): { level?: 'strict'; rules: Map<string, 'confirm' | 'deny'>; off: Scope[] }   // what a hub reads from `kept` in an attach answer: only what tightens
stricter(a: Decision, b: Decision): Decision
capScopes(requested: Scope[], ...caps: (Scope[] | undefined)[]): Scope[]   // intersection, canonical order
methodScope(m: string): Scope | undefined
navAllowed(policy: Policy, url: string, pageUrl: string): boolean
originAllowed(origin: string, patterns: string[]): boolean
urlOrigin(url: string): string | null                          // section 5, "Origins"; null when `url` is not a URL
urlHasOrigin(url: string, origin: string): boolean             // does hello.surface.url have the connection's origin

// chat (sections 9, 12 and 13)
chatText(v: unknown): string | undefined                       // trimmed, 1 to CHAT_MAX_TEXT characters, well-formed; undefined otherwise
chatNote(v: unknown): string | undefined                       // a status note on one line, at most CHAT_MAX_NOTE characters, '' when absent; undefined otherwise
chatMessage(v: unknown): ChatMessage | undefined               // a message off the wire, rebuilt from its checked fields
chatAudience(q: { relay: readonly string[]; from: 'person' | { agent: string }; to?: string; members: readonly string[] }): { outcome: 'post'; hear: string[] } | { outcome: 'nobody' } | { outcome: 'refuse'; code: 'E_BAD_ARGS' | 'E_DENIED' }   // section 12, who is sent a message; relay: the agents that hear each other
chatRelayMode(v: unknown): 'off' | 'person' | 'on' | undefined   // a value of policy.chatRelay; true is on, false is off
stricterRelay(a: ChatRelay, b: ChatRelay): ChatRelay            // off before person before on
chatDataLines(text: string): string[]                          // a chat text as "| " lines for a model: cut at every line break and separator, no control character left raw
chatPlain(s: string): string                                   // control characters but tab as \u{XX}
chatIdShown(id: string): string                                // a session id as it is printed outside quotes: letters, digits and . _ - only
chatWellFormed(text: string): string                           // a lone surrogate becomes U+FFFD
isChatState(v: unknown): boolean                               // idle, thinking or working

// observation
diffNodes(prev: UiNode[], next: UiNode[]): TreeOp[]
applyOps(nodes: UiNode[], ops: TreeOp[]): UiNode[]
renderTree(nodes: UiNode[]): string
renderOps(ops: TreeOp[], prev?: UiNode[]): string              // with `prev`, new (+) and replaced (~) nodes are told apart and anchors are hidden
renderObservation(o: Observation, prev?: UiNode[]): string     // header line plus tree or delta

// state deltas (RFC 7396)
mergeDiff(from: unknown, to: unknown): unknown                 // undefined when equal; a null property counts as absent on both sides
mergeApply(target: unknown, patch: unknown): unknown

// flow control
class TokenBucket { constructor(ratePerSec: number, burst?: number, now?: () => number); take(n?: number): boolean }
class CreditWindow { constructor(initial?: number); readonly available: number; consume(n: number): boolean; grant(n: number): void }
class CreditGranter { constructor(window: number); consumed(n: number): number }   // returns credit to send now, or 0
class PointerCoalescer { constructor(maxBacklog?: number); push(p: PointerPoint): void; take(max: number): PointerPoint[]; readonly size: number; readonly dropped: number }
playbackRate(queuedMs: number): number                         // 1 up to 120 ms of lag, rising linearly to 4 at 600 ms

// crypto (WebCrypto)
randomToken(bytes?: number): string
b64urlEncode(bytes: Uint8Array): string
b64urlDecode(text: string): Uint8Array
sha256(data: string | Uint8Array): Promise<string>             // base64url
hmacSha256(key: string, msg: string): Promise<string>          // base64url
timingSafeEqual(a: string, b: string): boolean
peerProof(key: string, f: { role: Role; kid: string; nonce: string; cnonce: string }): Promise<string>
hubProof(key: string, f: { role: Role; kid: string; nonce: string; cnonce: string }): Promise<string>

// links
linkPair(): [Link, Link]                                       // in-memory, ordered, asynchronous delivery
wsLink(ws: WebSocketLike): Promise<Link>                       // resolves when the socket is open
portLink(port: MessagePortLike): Link

// rpc
class Peer {
  constructor(link: Link, handlers: PeerHandlers, opts?: { limits?: Partial<Limits>; now?: () => number; maxBuffered?: number })   // over maxBuffered bytes waiting after a send: bye E_BUSY
  request<R = unknown>(m: string, p?: object, opts?: { timeoutMs?: number; ag?: string; c?: 1 }): Promise<R>
  event(topic: Topic, d?: unknown, extra?: { s?: string; ag?: string }): void
  sendBinary(bytes: Uint8Array): void
  flow(ch: number, credit: number): void
  ping(timeoutMs?: number): Promise<number>                    // round-trip time in ms
  bye(code?: ErrorCode | 'OK', msg?: string): void             // sends bye and closes
  readonly closed: boolean
  readonly lastSeen: number
  readonly bufferedAmount: number
}
interface PeerHandlers {
  request?(m: string, p: Record<string, unknown>, frame: ReqFrame): unknown | Promise<unknown>   // throw ReinsError to refuse
  event?(frame: EvtFrame): void
  binary?(bytes: Uint8Array): void
  flow?(frame: FlowFrame): void
  close?(code: ErrorCode | 'OK' | 'E_GONE', msg?: string): void
}
clientConnect(link: Link, hello: { role: Role; name: string; kid?: string; key?: string; surface?: SurfaceHello }, opts?: { timeoutMs?: number }): Promise<{ welcome: WelcomeFrame; link: Link; sealed: boolean }>
clientHandshake(link, hello, opts?): Promise<WelcomeFrame>     // unauthenticated sessions only; rejects when given a key

// sealed sessions
deriveSealKeys(key: string, t: { nonce; cnonce; challengeText; helloText; welcomeText }, side: 'peer' | 'hub'): Promise<SealKeys>   // directional keys from the secret and the transcript; E_AUTH on a text that is not well-formed
sealLink(link: Link, keys: SealKeys): Link                     // a Link that seals what it sends and opens what it receives
hubSeal(link: Link, handshake: { key; nonce; cnonce; challengeText; helloText; welcomeText }, opts?): Promise<Link>   // the hub's half, with key confirmation

// the user's Reins folder: names and shapes only, no file access
HOME_DIR                                                       // ".reins"
LAUNCHER_FILE                                                  // "reins.mjs"
SESSION_ID_PATTERN                                             // 1 to 32 letters, digits, "-" or "_"
hubFileName(port: number): string                              // "hub-7346.json"
sessionFileName(port: number, id: string): string              // "session-7346-default.json"
parseHubFile(text: string): HubFile | undefined                // { v: 1, url, port, pid, started, profile, origins, tokenFile?, managed? }
parseSessionFile(text: string): SessionFile | undefined        // { v: 1, port, pid, secret, hub, name, started }
hubPort(url?: string): number | undefined                      // the port a ws URL names; the default port without a URL

clientConnect runs the handshake and, when a key was used, returns the sealed link after key confirmation. Build the Peer on the link it returns.

Peer answers ping itself, turns a thrown ReinsError into an error response and anything else into E_INTERNAL, fails pending requests with E_GONE when the link closes, and closes the link on a malformed frame. It runs no timers of its own: the owner of a connection (broker, driver, agent client) sends ping when the link has been idle for heartbeatMs and drops a peer whose lastSeen is older than 2.5 × heartbeatMs.

@reins/hub #

TypeScript
// @reins/hub/broker: isomorphic, runs in Node and in a page
interface AgentCredential { kid: string; key: string; name?: string; scopes?: Scope[]; origins?: string[]; surfaces?: string[]; maxSessions?: number }
interface BrokerConfig {
  name?: string
  agents: AgentCredential[]
  surfaces: { origins: string[]; requireKey?: boolean; keys?: Record<string, string>; pins?: Record<string, string> }
  policy?: PolicyInput
  limits?: Partial<Limits>
  audit?: AuditSink
  auditKey?: string                              // keys the audit chain with HMAC-SHA256
  maxSurfaces?: number; maxAgents?: number; maxStreams?: number
  surfaceAdmission?: { rate?: number; burst?: number }   // per origin; defaults 2/s, 2 x maxSurfaces
  agentAdmission?: { rate?: number; burst?: number }     // per credential; defaults 2/s, 20
  now?: () => number
}
interface LinkMeta { origin?: string; remote?: string; role?: Role; vouched?: boolean }   // role: the only role the link may take, else E_ORIGIN; vouched: the embedder built the link, the surface is verified
interface AuditSink { write(record: AuditRecord): void; readonly last?: { seq: number; hash: string } }   // throwing means the log is unavailable
class Broker {
  constructor(config: BrokerConfig)              // throws a TypeError on malformed configuration, keys shorter than 32 characters included
  accept(link: Link, meta?: LinkMeta): void      // runs the hub side of the handshake, then serves the peer
  info(): HubInfo
  auditHead(): { seq: number; hash: string } | undefined
  flushAudit(): Promise<void>
  close(): void
}
memoryAudit(): AuditSink & { records: AuditRecord[] }
verifyAuditChain(records: AuditRecord[], opts?: { key?: string; head?: { seq: number; hash: string } }): Promise<{ ok: boolean; badSeq?: number }>

// @reins/hub: Node only
interface HubOptions extends BrokerConfig { host?: string; port?: number; auditFile?: string; surfaceSockets?: boolean }   // surfaceSockets false: agents only on the socket
startHub(opts: HubOptions): Promise<{ broker: Broker; port: number; url: string; close(): Promise<void> }>
fileAudit(path: string, opts?: { key?: string; head?: { seq: number; hash: string } }): AuditSink   // one JSON record per line; verifies an existing log first, throws if it is broken

// the user's Reins folder: REINS_HOME, else .reins in the home folder
reinsHome(env?: NodeJS.ProcessEnv): string
announceHub(hub: Omit<HubFile, 'v'>, home?: string): string     // writes hub-<port>.json and returns its path
withdrawHub(port: number, pid: number, home?: string): void     // only the announcement of that process
readHubFile(port: number, home?: string): HubFile | undefined
writeLauncher(target: string, home?: string): string            // writes reins.mjs, which runs the shell tools at `target`
pidAlive(pid: number): boolean
ensureOwnerDir(dir: string): void                               // creates missing directories owner-only
writeOwnerOnlyNew(file: string, text: string): void             // a new owner-only file; refuses to replace one

fileAudit treats an existing log like a secret file first: it is refused on POSIX if group or others have any permission on it, and restricted to the current user again on Windows. It then reads the log in chunks and refuses it when a line is longer than 1 MiB, the last line is incomplete, or the chain or the head does not verify.

CLI: reins-hub [--port 7346] [--profile open|guarded|kiosk] [--allow-origin <origin>]... [--config hub.json] [--token-file <path>] [--surface-key <appId>=<path>]... [--require-key] [--audit <path>] [--audit-key-file <path>] [--agent <kid>=<path>]... [--no-surface-sockets] [--no-announce]. With no agent configured it creates one credential (kid default) and writes the secret to the token file (default .reins/token). --agent <kid>=<path> adds a credential with that kid whose key is in that file, created like any secret file when it is missing; with it and without --token-file there is no credential default. --no-surface-sockets is surfaceSockets: false (section 3). A malformed configuration stops it with "invalid configuration ...". Secret files that do not exist are created with a random key: written inside a new temporary directory next to the file that is restricted to the current user first, then hard-linked into place (moved, on a volume without hard links); a file that appears meanwhile is not overwritten. An existing secret file is refused on POSIX if group or others have any permission on it, and restricted again at start on Windows. Secret files, a new audit log and the directories the hub creates are restricted to the current user, by file mode on POSIX and by ACL on Windows, where icacls is run from %SystemRoot%\System32. There the hub removes inherited entries and also every entry set on the file itself for anyone but the current user (SYSTEM and Administrators included), then reads the ACL back and requires that only the current user's entry remains. A failure to restrict stops the hub. The hub prints file paths, never secrets. With --audit it keeps the chain's head in <path>.head, replaced through a temporary file and a rename.

The user's Reins folder. Once it listens, the hub announces itself in the user's Reins folder (REINS_HOME, else .reins in the home folder; created owner-only when missing): hub-<port>.json holds the hub's URL, port, process id, start time, profile, the surface origins it admits and, when the hub made the default credential, the path of its token file. It holds no secret. The hub also writes reins.mjs there, a launcher that runs the shell tools (@reins/mcp) of the same installation, so an agent on the machine reaches the hub with node "$HOME/.reins/reins.mjs" <tool> from any folder. On an orderly shutdown the hub removes its announcement; a reader ignores the announcement of a process that is no longer running. A failure to write either file is a warning and does not stop the hub. --no-announce writes neither.

@reins/driver (browser) #

TypeScript
createDriver(options: {
  app: AppInfo
  hub?: string                       // ws URL, default ws://127.0.0.1:7346
  link?: Link                        // use this link instead of a WebSocket
  key?: string                       // surface key, when the hub requires one
  policy?: PolicyInput               // default 'guarded'
  consent?: (req: ConsentRequest) => Promise<boolean>
  indicator?: boolean                // default true
  reconnect?: boolean                // default true, with backoff 0.5 s to 10 s
  root?: Element                     // subtree to expose, default document.body
}): Driver

interface Driver {
  action<A = any>(def: ActionDef, handler: (args: A, ctx: CommandContext) => unknown | Promise<unknown>): this
  view<D = any>(def: ViewDef, render: (data: D, ctx: CommandContext) => unknown | Promise<unknown>): this
  state(name: string, get: () => unknown, description?: string): this
  notify(name?: string): void        // an exposed state changed
  connect(): Promise<void>           // resolves once the hub has welcomed the surface
  disconnect(): void
  on(event: 'status' | 'attach' | 'detach' | 'command' | 'level' | 'rule' | 'scopes' | 'chat', fn: (e: any) => void): () => void
  readonly status: 'idle' | 'connecting' | 'ready' | 'controlled' | 'paused' | 'offline'
  readonly manifest: Manifest
  readonly policy: Policy
  readonly hubVerified: boolean      // the session is sealed, or the app supplied the link
  agents(): AttachedAgent[]          // a copy: each attached agent with what the person set for it
  pause(): void; resume(): void; stop(): void
}
interface AttachedAgent { agent: AgentInfo; level: Level; scopes: Scope[]; granted: Scope[]; rules: Record<string, Decision> }
interface CommandContext { agent: AgentInfo; scopes: Scope[] }
interface ConsentRequest { kind: 'attach' | 'action'; agent: AgentInfo; scopes?: Scope[]; action?: ActionDef; args?: unknown; reason?: string; hubVerified?: false; kept?: string[] }   // kept: on an attach, what the person tightened for this agent before and that stays, one line each

The events level ({agent, level}), rule ({agent, action, rule}, rule null when removed) and scopes ({agent, scopes}) fire when the person changes one in the panel. The API only reads them: nothing in it sets a level, a rule or a scope switch, and no option opens the panel. human.panel: false leaves the indicator without one.

The event chat ({id, from, chars, to?}) fires when a message is posted in the page's chat room: who said it, and how long its text is. The text is not given to the app. Nothing in the API posts a message, as the person or as anyone, and nothing in it reads the transcript. id is the room's own number for the message, not an agent's. An app that wants the text can take it from its own page all the same (section 12): the API is no wall against the app.

Actions, views and state are registered before connect(). createDriver throws when the profile is kiosk and the driver would dial a hub without a key. connect() rejects with E_DENIED, and connects to nothing, in a page inside a frame whose policy does not set framed (section 12).

@reins/agent (Node and browser) #

TypeScript
connect(options: { url?: string; link?: Link; kid?: string; key?: string; name?: string }): Promise<ReinsClient>
isHandshakeError(e: unknown): boolean            // connect threw e during the handshake: its message came from an unverified peer

interface ReinsClient {
  readonly session: string
  info(): Promise<HubInfo>
  surfaces(): Promise<SurfaceInfo[]>
  attach(s: string, opts?: { scopes?: Scope[]; reason?: string }): Promise<SurfaceHandle>
  ping(): Promise<number>
  on(event: 'surface' | 'close', fn: (e: any) => void): () => void
  close(): void
}
interface SurfaceHandle {
  readonly info: SurfaceInfo; readonly manifest: Manifest; readonly grant: Grant
  readonly level: Level                            // the level the person last set for this grant; `ask` until told, `strict` from the start when that was kept (section 8)
  readonly rules: Record<string, Decision>         // the person's rules for single actions, by name
  readonly chatRelay: boolean                      // the person switched "Agents can hear each other" on for this agent
  card(): string                                   // the prompt card
  observe(opts?: { full?: boolean; boxes?: boolean }): Promise<Observation>   // tracks `since` itself
  observeText(opts?: { full?: boolean }): Promise<string>
  read(h?: Target, max?: number): Promise<string>
  readText(h?: Target, max?: number): Promise<{ text: string; truncated: boolean }>   // read, with whether it was cut at max
  state(name?: string): Promise<Record<string, unknown>>
  act<R = unknown>(action: string, args?: object): Promise<R>
  click(h: Target): Promise<void>
  type(h: Target, text: string, opts?: { clear?: boolean; enter?: boolean }): Promise<void>
  select(h: Target, value: string): Promise<void>
  scroll(opts: { h?: Target; dx?: number; dy?: number; to?: 'top' | 'bottom' | 'view' }): Promise<void>
  key(key: UiKey, h?: Target): Promise<void>
  cursor: { move(to: Target | Point, opts?: { ms?: number; wait?: boolean }): Promise<Point>; show(label?: string, color?: string): Promise<void>; hide(): Promise<void> }
  show: { toast(text: string, kind?: ToastKind, ms?: number): Promise<void>; highlight(h: Target, label?: string, ms?: number): Promise<void>; view(view: string, data?: unknown): Promise<unknown>; clear(): Promise<void> }
  go(url: string): Promise<void>
  pointer(): Promise<PointerStream>
  chat: { say(text: string, opts?: { to?: string }): Promise<{ id: number }>; read(opts?: { since?: number; max?: number }): Promise<{ messages: ChatMessage[]; next: number }>; status(state: 'idle' | 'thinking' | 'working', note?: string): Promise<void> }
  subscribe(topics: Topic[]): Promise<void>
  on(event: Topic, fn: (d: any) => void): () => void
  detach(): Promise<void>
}
interface PointerStream { push(x: number, y: number, dt?: number): void; end(): Promise<void>; readonly stats: { sent: number; dropped: number } }

grant.scopes holds the scopes in force: it follows evt grant {kind:"scopes"} when the person switches scopes off or back on, and such an event does not end the handle. What the person sets also arrives as events: on('user', ...) gets {kind:"level", level} and {kind:"rule", a, d}, on('grant', ...) gets {kind:"scopes", scopes}. An agent cannot change any of it.

on('chat', ...) gets each message the hub relays for this grant as a ChatMessage, rebuilt from its checked fields; one that is not well-shaped is dropped. It needs no subscribe. chat.say(text, { to: 'person' }) is for the person alone. chatRelay on the handle is true once the hub has said that the person switched "Agents can hear each other" on for this agent (on('user', ...) gets {kind:"relay", on}); on a page whose policy is on it stays false, and every message without to reaches the other agents. attach asks for observe, act, cursor and show unless told otherwise: an agent that wants to be in the room names chat.

connect reads the key from options.key, else REINS_TOKEN, else the file named by REINS_TOKEN_FILE, else the token file that the running hub at options.url announced in the user's Reins folder, else .reins/token in the working directory (Node only). The announcement comes before the working directory because it names the hub that is listening now. CLI: reins surfaces | card | observe | act <name> [json] | click <h> | type <h> <text> | move <h> | toast <text>. The CLI prints text from a page or the hub with every control character other than tab and line feed escaped as \xNN, and the JSON it prints is JSON on one line to every reader (section 10, "Text rendering"). Where it has to choose among several surfaces it names each with what the hub knows first (the id, verified or unverified, the origin) and the app's name last, in quotes.

@reins/mcp #

A stdio MCP server over the agent SDK. Ten tools, kept small so their definitions cost few tokens:

tool does
reins_surfaces list surfaces
reins_attach attach and return the prompt card
reins_observe compact tree, or the delta since the last call
reins_read the text of an element, a region or the page, which the tree leaves out; app state
reins_act call an app action
reins_ui click, type, select, scroll, key
reins_cursor move, show, hide
reins_show toast, highlight, view, clear. file sends a JSON file's content to a view without the model reading it
reins_chat talk with the person in the page's Chat tab: wait, read, say, status
reins_batch run several of the above in one call

Only reins_attach attaches: every other tool answers E_NOT_ATTACHED for a surface that is not attached, so a tool marked read-only never raises a prompt on the page. Tool results that carry text a page or the hub supplied (observations, texts, state, action results, surface listings, relayed error messages) are marked as page data, and all of it goes out by one rule, the one chat text has (chatDataLines, below). Free text of a page (what reins_observe, reins_read and reins_act return, alone or as a step of reins_batch) stands on lines that start with | , under a first line that names the page's origin: a new | line starts at every line break and at the separators U+001C to U+001E, and every other control character but tab is written as \u{XX}. A field (an origin, a name, the message of an error) is one line, with the same escapes. And every result passes one last step that leaves no control character in it but the line feeds the adapter wrote itself: the only thing that ends a line in a result is the adapter. So no text of a page can pass for a line of the adapter, and none reaches a model, or the terminal of the shell tools, raw. In reins_batch the step results are lines of their own (2 ok, 3 error E_DENIED: ..., 4 skipped), and page text follows its step on its | lines, so it cannot pass for a step result. reins_read takes a target, a handle as for read (section 9), and without one it reads the page; max is 2000 characters by default and 8000 at most. The adapter cuts the text at max itself, whatever the surface sent, and when the text was cut, by either, a line of the adapter's own says so after it. With state it returns the app state of that name, or all of it for *, as one line of JSON behind | , of which one call returns 8000 characters; a line of the adapter's says when there was more. It is a step of reins_batch as well (read). An error from a handshake that did not finish is one line, cut to 200 characters and marked [unverified hub data].

A line of the surface listing gives what the hub knows first, in a fixed order, and what the page says of itself last: the surface id, verified or unverified (whether the page proved its app key to the hub: one of the two words is always there), the origin, attached when this agent holds a grant, then app= with the app's name as a quoted string, id= and profile=. A name that copies the hub's words therefore stands inside quotes, after the hub has spoken, and cannot close them. reins_attach answers the same way: its first line is the adapter's own (attached to surface s1: verified https://shop.example, scopes: observe act ui), and the prompt card, which is the page's account of itself, follows under the page-data marker. The scopes the server was started with are a ceiling: a tool call cannot request more. Unless it was started with others, they are observe, act, ui, cursor, show and chat, and reins_attach asks for them.

Notices. What the adapter itself has to tell the model between calls goes out with the next tool result, whatever the tool: one line per notice, each starting with [reins] , before the tool's own answer and so before any page-data marker. A line that looks like a notice after such a marker is page content. The adapter tells this way what the person set on the page: [reins] the person set your permission level on surface s1 to auto (...), that a rule changed and how many are set, the scopes now in force. A notice about a grant names the surface it is about, by the id the hub gave it, and says (a page the hub did not verify) after it when that is so: what a surface reports about the person is true of that surface and no other, and from a page that proved no key "the person" is whoever can reach the hub's port. Every word of a notice is the adapter's; a value from the wire goes into one only when it is a known level or scope, or a count. The name of an action is a word the page chose, so it never appears in a notice: which actions the person's rules are for is listed after the tool's own answer, under the page-data marker, where everything else the page wrote stands. A notice with a key replaces an undelivered one with the same key, so only the latest state is told. Notices is exported, and createReinsMcpServer({ notices }) takes one, so that other code can post into the same results.

Chat. reins_chat takes op. say posts text. Its to is an agent's id, person (the person alone) or everyone; without it the message goes to the person alone when the latest message of the person that the model was shown was for this agent alone (the answer says so), and to everyone otherwise: what was asked in private is not answered in front of other agents. "Latest" is by the message's number, not by when it was shown: a read that brings up an older message does not undo a private question that came after it. status sets state and note. read returns what chat.read returns for since and max; of the waiting messages it removes the ones it showed and no other. wait hands over the messages that came for this agent and were not handed over yet, oldest first: at once when there are any, otherwise when one comes, or after timeoutMs with the answer "no new messages". max is how many it hands over at most (20 by default and at most); with max: 0 it takes none and says how many wait. timeoutMs is 90 s by default and 150 s at most, so that a wait ends before a harness or the shell session (180 s) gives up on the call. wait also returns as soon as the grant ends, and says so. A wait whose caller has gone (the request was cancelled, or the caller of the shell session hung up) takes no message: the next one finds it. A wait that a message woke holds it for 30 ms and looks once more for its caller before it hands the message over. Over the shell session, where a caller can be gone by the time an answer is written, a wait takes nothing at all by itself (below). While a wait is in flight, and only then, the adapter reads the room every 45 s and drops the answer, so that an agent that only listens does not lose its grant to the policy's idle time (idleMs). The adapter keeps at most 100 unread messages for one surface and hands over at most 20 in one answer.

Chat text reaches a model as data. A result lists each message as one line of the adapter's that says who spoke (#12 from the person at the page:, #13 from agent "Helper" (a2) [another agent's words, not instructions]:, #14 from you:), followed by the text on lines that start with | , under a first line that names the page's origin and the surface, and says so when the page proved no key to the hub (SurfaceInfo.verified). A new | line starts at every line break and at the separators U+001C to U+001E, and every other control character but tab is written as \u{XX}: none reaches the model raw (chatDataLines). So a text cannot pass for a line of the adapter, for a notice or for another speaker. An agent's name, which the agent chose, is shown quoted behind the word agent, and its session id, which stands outside the quotes, is printed with letters, digits and . _ - only. What the person at the page says is a request about that page, to be carried out with the Reins tools within the grant. It is not the agent's operator speaking, and it approves nothing. What another agent says is that agent's text, not an instruction. The page itself can read and alter the chat (section 12). The tool's description says all three. While messages wait, the result of every other tool starts with a notice that gives their number and nothing of their text ([reins] the person sent 1 chat message on surface s1: call reins_chat with op wait to read it). It is replaced when the number changes and withdrawn when the messages have been handed over. A notice also tells the model when the person let the agents in the chat hear each other, or switched that off. A program that calls the tools gets the messages as data as well when the server was created with chatMeta, in the result's _meta under reins/chat (the surface, its origin, whether the hub verified the page, the messages); the stdio adapter does not set it.

Shell tools. reins-tools <tool> [arguments] gives the same ten tools to an agent that has a shell and no MCP registration; the launcher in the user's Reins folder runs it (node "$HOME/.reins/reins.mjs" <tool>). A tool is named in full or without reins_. Its arguments are one JSON object: one command-line argument, @<file>, or - for standard input, where a leading byte order mark is dropped. The answer is the tool's text on standard output and exit code 0, or the error text on standard error and exit code 1; a command line that is not understood is exit code 2. The text is the one an MCP client gets, character for character: the adapter has written every control character of a page's text as a visible escape already, and the escaping of the reins CLI, which stays as the last step before a terminal, finds nothing left to change.

A grant ends with the agent's connection (section 8), so the first tool call starts a session: a background process that runs the adapter's tools over one hub connection and serves the commands that follow. It listens on a free port of 127.0.0.1 and writes session-<hub port>-<id>.json (owner-only) in the user's Reins folder with that port and a random bearer secret of 32 bytes. It answers only a request that names 127.0.0.1 and its port as Host, carries no Origin header and sends the secret. It ends on reins-tools stop, or when no command has reached it for 30 minutes (--idle-ms); it then closes the hub connection, which ends the grant, and removes its file. --session <id> names the session (default default), --name the agent name shown to the person, --scopes and --data-dir are those of the adapter. --kid <id> names the credential the session authenticates as (default default), with its key in --token-file; the adapter (reins-mcp, reins-tools mcp) and the reins CLI take the same option. Two agents on one hub can so hold a credential each, with a name, a scope cap and limits of its own (section 13). These options are taken when a session starts. On a command that finds its session running, --scopes, --kid, --token-file, --data-dir or --name with another value than the session has is refused with E_BAD_ARGS: the message says what the session has and that stop ends it, and the tool is not called. None is dropped without a word. status says which scopes the running session may request.

A chat wait over the session hands messages over in two steps, because whoever asked may be gone by the time the answer is written. The answer shows the messages and carries a claim; the messages stay where they were. The caller, once it has the answer, takes them with that claim (POST /take), and what it is answered then, the messages that were still there to take, is what it uses. reins-tools and chat-serve do both steps. A caller that died before the second step took nothing, and the next wait finds the messages.

Inside a run of chat-serve (REINS_CHAT_CONTEXT is set, below) a tool command that names no session, no hub and no surface takes them from there: it reaches the session that holds the runner's grant, and the page the message came from. What the command line or the arguments name comes first.

reins-tools up --allow-origin <origin>... starts a hub in the background unless one that admits those origins is running, with its token in the Reins folder, and returns once the hub has announced itself. A hub that up started is restarted to admit a further origin; a hub started any other way is left alone, and up then reports what it does not admit. What such a hub warns about on its own console goes to a log file, so up prints it itself, when it starts the hub and when it finds it running: one line for an allowlist entry that names no page (null, file://; section 5, "Origins"). status reports the hub, the session and the launcher, down stops a hub that up started, setup writes the launcher, and mcp runs the stdio adapter, so that a harness registration can name the launcher alone. An announcement outlives a hub that was killed, and its process id is then anybody's: before down or up ends the process an announcement names, what listens on the port has to prove that it is a hub with the key in the announced token file (an agent handshake, which a hub answers with a proof of that key), and the process that holds the id, where the system tells when it was created, has to be older than the announcement. Otherwise nothing is ended, and the command says why.

reins-tools chat-serve [--timeout-ms <n>] [--preface <file>] [--surface <id>] [--once] [--wait-ms <n>] [--allow-unverified] --exec <command> [args...] answers the chat with a program, for an agent that is no MCP harness. Everything after --exec belongs to the command, and --wait-ms is the length of one wait for a message (60 s by default, 150 s at most). It works through the session and so under its grant, and attaches first when the session holds none. It serves one page, the one --surface names or else the one its first answer is about, and names that surface in every call it makes. It refuses to serve a page that proved no key to the hub unless --allow-unverified is given: any program on the computer that can reach the hub's port can be such a page and write as the person. For each message of the person it runs the command once, and it takes one message at a time (wait with max: 1, after a first call with max: 0 that takes none), so that a runner that stops (--once, a signal, a run it could not end) has taken no message it does not answer. The argument array after --exec is started as it is, without a shell. Which file the command is, the runner settles itself before it takes a message, and prints: a path is that file, and a bare name is looked for in the folders of PATH, in order, and never in the working directory, neither by itself (where Windows looks first) nor through an entry of PATH that is empty or relative. A script that only a shell runs (.cmd, .bat, .ps1) is refused with what to name instead. The message is written to the command's standard input and nowhere else: no part of it reaches a command line. It is written as one line of the runner's own that says who wrote it, on which page and surface, and whether the hub verified the page, followed by the text on lines that each start with | (as reins_chat gives it). With --preface, the text of that file and a line feed come before it. REINS_CHAT_CONTEXT in the command's environment holds one line of JSON (the surface id, the origin, verified, the message id, and the session and hub that reach the grant), never the text. What the command prints is posted as the reply, trimmed and cut to 4000 characters, with at most 64 KiB read; a reply to a message that was for this agent alone goes to the person alone. An empty answer posts nothing. A run that ends with another exit code than 0, or takes longer than --timeout-ms (120 s by default), posts a short notice instead, and what the command wrote to its error output goes to the runner's own, never to the page. When a run is over, because the command exited, took too long or the runner was stopped, what the command started is ended with it, and the runner takes the next message only when that is gone. What "what it started" covers depends on the system. On Windows the command is put into a job object that allows no breakaway, some milliseconds after it is started, with whatever it had started by then that can still be traced to it; from then on Windows keeps every process the command or anything below it starts inside the job, however deep and whether or not its parent is still there, and ends them all at once. The job says how many processes a command left running when it exited, and the runner tells the operator. Out of reach there: a process that a program outside the job starts on the command's behalf (a scheduled task, a service, WMI, a program that was running already), and one started in those first milliseconds by a child that had itself exited before the job took hold. Where no job object can be had (PowerShell, which makes it, is missing or may not compile), no command is started at all. Elsewhere the command leads a process group of its own and the group is ended; a process that left the group (setsid, a daemon) is out of reach. When what is left cannot be ended, or nobody can say whether anything is left, the runner stops and runs nothing more. A reply the page or the hub refuses with E_BUSY or E_RATE is tried again for up to 90 s. Messages of other agents start nothing. The runner prints lengths, not texts, and ends when the grant does. Whoever can write in the Chat tab decides what the command is given, and the command runs as the operator's user: integrations/chat-serve/README.md says what follows from that.

@reins/electron #

TypeScript
// @reins/electron: the main process. Nothing in the package imports `electron`.
mainPortLink(port: MessagePortMainLike): Link                  // the main-process end of a MessageChannelMain
reinsMain(options: {
  ipcMain: IpcMainLike
  MessageChannelMain: new () => { port1: MessagePortMainLike; port2: MessagePortMainLike }
  accept(link: Link, meta: { origin: string; vouched: true }): void   // (link, meta) => broker.accept(link, meta)
  channel?: string                                             // IPC channel, default "reins"
  onRefused?(reason: string, event: IpcMainEventLike): void
}): ReinsMain
interface ReinsMain {
  allow(target: BrowserWindow | WebContents, options?: {
    url?: string | string[] | ((url: string) => boolean)       // the page the window is registered for; needed for file:// and null
    hidden?: boolean                                           // link the window while it is not shown
    embedded?: boolean                                         // link a <webview> guest
  }): () => void                                               // returns a function that takes it back
  close(): void
}
preloadPath: string                                            // the ready-made preload script, one CommonJS file

// @reins/electron/bridge: the preload script
exposeReins(electron: { contextBridge; ipcRenderer }, win?: Window, channel?: string): void   // puts window.reinsElectron in the page

// @reins/electron/renderer: the page (also dist/bundle/reins-electron.js)
electronLink(options?: { timeoutMs?: number; window?: Window }): Promise<Link>   // E_GONE without the preload, E_DENIED when refused, E_TIMEOUT

// @reins/electron/adopt: Node, for an app that was not built for Reins
class Cdp { constructor(t: CdpTransport); send<R>(method: string, params?: object, sessionId?: string): Promise<R>; on(fn: (e: CdpEvent) => void): () => void; onClose(fn: () => void): void; close(): void; readonly closed: boolean }
pipeTransport(toBrowser: Writable, fromBrowser: Readable): CdpTransport   // --remote-debugging-pipe: JSON texts, each ended by a zero byte
wsTransport(url: string): Promise<CdpTransport>
debugEndpoint(target: string): { host: string; port: number; ws?: string }   // throws for anything but a loopback address
adopt(options: {
  cdp: Cdp
  pageSource: string                                           // the text of dist/bundle/reins-adopt.iife.js
  app: AppInfo
  connect: { link(link: Link, page: { origin; url; title }): boolean | Promise<boolean> }    // a broker in this process
         | { hub: string; transport?: 'auto' | 'ws' | 'bridge'; key?: string }                // a hub that runs elsewhere
  levels?: Level[]                                             // levels the person may set besides strict and ask; default none
  scopes?: Scope[]                                             // scopes an agent may be granted; default those of guarded
  exclusive?: boolean                                          // false for a debugging port, which other programs can use: nothing is vouched for, no key is given
  match?(target: { type: string; url: string; title: string }): boolean
  log?(line: string): void
  leaseMs?: number                                             // how long a document goes on without hearing this process; default 10 s
}): Promise<{ pages(): { origin; url; title }[]; stop(): Promise<void>; close(): void }>   // stop: every driver ends for good
hubEndpoint(url: string): string                               // throws for anything but ws:// on a loopback address
portBrowser(end: { host; port }): Promise<{ id; ws; product; userAgent } | undefined>   // the browser behind a debugging port
closePortBrowser(end, same: (b) => boolean, waitMs?: number): Promise<'none' | 'other' | 'closed' | 'still'>   // Browser.close over the port
pagePolicy(options?: { levels?: Level[]; scopes?: Scope[] }): PolicyInput   // the policy of an adopted page, and of the hub hosted for it

A window as a surface. The page calls electronLink(). The preload passes the request to the main process, which answers the top-level frame of a window registered with allow() with a fresh MessageChannelMain: one port goes to accept under the frame's origin, the other to the page, which wraps it with portLink for createDriver({ link }). A second request from the same window closes the link it had, so one window is one surface. A request from an unregistered window, from a window that shows another page than the one it was registered for (section 3), from a frame inside the page, from a <webview> guest not registered with embedded, or from a page nobody looks at (offscreen, backgroundPage) is refused, and electronLink() rejects with E_DENIED. It rejects the same way, with the reason, in a window without context isolation. A window that is not shown is not refused: its request is answered when the window is shown, and electronLink() rejects with E_TIMEOUT if that does not happen in time. A token made by the page (8 to 64 base64url characters) ties each answer to its request; the page takes a port only from a message its own window posted.

reins-electron. reins-electron [options] -- <executable> [arguments] starts an Electron app with --remote-debugging-pipe, and --attach <port> joins one started with --remote-debugging-port. For every page of the app it runs reins-adopt.iife.js, the driver and its glue, in each new document, so a reload, a navigation and a new window are adopted as they happen. The driver runs under the guarded profile and declares no actions: an agent has the UI tree, synthetic input, the cursor, toasts, highlights and the chat, and the person has the consent prompt, the indicator and the panel. A level decides declared actions only (section 12), so the panel of an adopted page offers no level that loosens anything unless --levels lists it (auto, bypass); --scopes names the scopes an agent may be granted, by default all those of the profile. The driver runs in a world of its own (Page.addScriptToEvaluateOnNewDocument with a world name), and the function that carries its frames out through the debugging connection MUST be added to that world only, so that the page's own scripts can reach neither. The world is named afresh for each run, reins- and a random token, and the command MUST ignore a call of that function from any context it did not see created as that world. --match is asked of every document, with that document's own URL, and not only of the tab it loads in. It names an origin, or a URL, which stands for itself and what lies under it. Pattern and document are both read as URLs and compared by origin and path, query and fragment aside: a document MUST NOT match because its URL contains the text of the pattern. What the command prints about a page is its origin, never its URL. Whoever holds a debugging connection controls the app, so reins-electron MUST refuse a debugging port that is not on a loopback address, before it connects to it.

The driver lives no longer than the command. When the command stops, it MUST tell every driver it loaded to disconnect for good, whatever carries that driver's frames: a page that reached a hub over a socket of its own would otherwise stay a live surface. While it runs it tells every live document so every 2 s, and a document that has heard nothing for 10 s asks once and, unanswered for 5 s more, MUST stop its driver by itself, so that a command that was killed leaves none behind either. This is judged by the clock whenever a frame arrives for the driver or is to leave it, and not by a timer alone: from the moment a document has not heard the command for 10 s until it hears it again, it MUST NOT hand its driver a frame or send one of the driver's, whether or not any of its timers fires. A script of the page can clear every timer of its document, those of the driver's world included.

By default reins-electron hosts a hub itself (--port, --token-file, --allow-origin, --no-announce), with surfaceSockets: false and the policy of the pages (pagePolicy), and gives each page a link to its broker over the debugging connection. Without --allow-origin it admits the origin the app's first pages share: it hears the pages that ask within a second of the first, and when they have more than one origin it stops and lists them, for the person to name. Two kinds of origin are never taken from a page and have to be named: null, which says nothing about the page, and that of a web site that is not on a loopback address, which is something the app shows and not the app. With --hub <ws url> the pages connect to a hub that runs elsewhere: the page opens the socket itself where its Content Security Policy lets it, and otherwise the command opens it, with the page's origin as Origin, and carries the frames (--transport auto, ws or bridge). The command MUST NOT dial a hub that is not on a loopback address. Such a page treats the hub as unverified unless --surface-key-file names the key that hub holds for --app-id, and without a key that hub admits by origin alone, so the app's own scripts can connect to it as the same app: the command warns. An app that reins-electron started ends with it, also when the command is killed. With the pipe that is Chromium's doing: it exits when its debugging pipe closes. With --debug-port the app is the browser that answers on that port, whatever process that is by then: the executable may have been a starter that left at once, and an app may start itself again. The command MUST NOT take the end of the process it started for the end of the app, and when it ends it MUST close that browser over the port (Browser.close) and ask the port again. A watcher process does the same for a command that was killed; it learns of the command's end from a pipe between the two, and neither of them ends a process it knows only by its id. Before it starts an app with --debug-port, the command makes sure that no browser answers on that port yet. An app it attached to is left running. --surface-key-file is refused together with a debugging port.

16. Versioning #

challenge.v lists what the hub speaks. The peer picks one and states it in hello.v. No common version is E_VERSION. Within a version, receivers ignore unknown fields on frames and unknown event topics, and refuse unknown methods with E_UNKNOWN_METHOD.