oui-spec 0.4.1 → 0.6.0

package/dist/types-CmJb1BQ8.d.ts

@@ -0,0 +1,403 @@
+/**
+ * Approvals: an irreversible action runs only on an approval the user gave,
+ * bound to the exact request.
+ *
+ * An agent runtime stops at an action that needs approval and shows the user
+ * a confirmation. Its approval store issues a single-use grant when the user
+ * confirms, and the request that then reaches the tab carries `approval:
+ * { approvalId, argsHash }`. The surface runtime runs the action only when
+ * that matches a grant this tab received from the user's own confirmation.
+ *
+ * Everything that checks a request computes the same args hash: SHA-256 over
+ * the RFC 8785 (JCS) canonical JSON of its params, lowercase hex. The
+ * published vectors (`oui-spec/approval-vectors.json`) hold every
+ * implementation, in any language, to it.
+ */
+/**
+ * What using an action does. One vocabulary for every kind of action, so an
+ * action is told apart by what it changes:
+ *
+ * | Effect | What it changes | Access |
+ * |---|---|---|
+ * | `view`, `selection`, `navigate`, `open` | What is shown | read |
+ * | `edit` | The document, one undo step | write |
+ * | `file` | Imports or exports a file | write |
+ * | `mutate` | Backend data, through an API operation | write |
+ * | `job` | Starts work that outlives the call | write |
+ * | `transaction` | An irreversible external act: an order, a payment, a send, a publish | write, approved |
+ */
+type OUIEffectKind = "view" | "selection" | "navigate" | "open" | "edit" | "file" | "mutate" | "job" | "transaction";
+/** Every effect, in the order of the table above. */
+declare const OUI_EFFECT_KINDS: readonly OUIEffectKind[];
+/** Whether an effect only changes what is shown, or changes something. */
+declare const OUI_EFFECT_ACCESS: Readonly<Record<OUIEffectKind, "read" | "write">>;
+/** `read` or `write`. An action that declares no effect is a `write`: nothing says it only shows. */
+declare function effectAccess(effect: OUIEffectKind | undefined): "read" | "write";
+/**
+ * Whether running an action needs the user's approval of the exact request: a
+ * `transaction` always, and a `write` declared destructive. An agent
+ * runtime's policy may require it of more; nothing waives these.
+ */
+declare function requiresApproval(effect: OUIEffectKind | undefined, destructive?: boolean): boolean;
+/** What a request for an approved action carries. */
+interface OUIActionApproval {
+    approvalId: string;
+    /** `argsHash(params)` of the request the user approved. */
+    argsHash: string;
+}
+/** A grant this tab holds: the user approved this request here. */
+interface OUIApprovalGrant extends OUIActionApproval {
+    /** Epoch ms after which the grant no longer admits anything. */
+    expiresAt: number;
+}
+/** An args hash: 64 lowercase hex digits. */
+declare const ARGS_HASH_PATTERN: RegExp;
+/**
+ * The RFC 8785 canonical form of a JSON value:
+ * - object members sorted by their names' UTF-16 code units, with no
+ *   whitespace;
+ * - numbers in ECMAScript's shortest round-trip form (`-0` is `0`);
+ * - strings escaped as ECMAScript's `JSON.stringify` escapes them.
+ *
+ * The value must be I-JSON (RFC 7493): anything JSON cannot carry — `NaN`,
+ * infinities, `undefined` outside an object member, a bigint, a function, a
+ * symbol, a class instance, or a string with a lone surrogate — is refused
+ * rather than hashed as something the other end never receives. An object
+ * member whose value is `undefined` is left out, as it is on the wire.
+ */
+declare function canonicalJson(value: unknown): string;
+/** SHA-256 of the canonical JSON of a request's params, lowercase hex. Runs wherever WebCrypto does. */
+declare function argsHash(params: unknown): Promise<string>;
+
+/**
+ * OUI — Open UI Specification
+ *
+ * The machine-readable contract for agent-controllable user interfaces.
+ * Any UI application that implements this interface can be controlled by
+ * any OUI-compatible agent runtime.
+ */
+/** JSON Schema type (subset used by OUI) */
+type JSONSchema = {
+    type?: string | string[];
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema;
+    required?: string[];
+    enum?: (string | number | boolean)[];
+    description?: string;
+    default?: unknown;
+    oneOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    allOf?: JSONSchema[];
+    const?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    additionalProperties?: boolean | JSONSchema;
+};
+/**
+ * A Surface is a controllable boundary within an application.
+ * It declares what an agent can do (actions), what it can observe (state),
+ * and when it's available (activation conditions).
+ *
+ * Think of it as "one page" or "one feature" of an application, described
+ * in a way that an agent can understand and operate.
+ */
+interface OUISurface {
+    /** Unique identifier for this surface (e.g., 'dataviz-wizard', 'document-editor') */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this surface does — included in agent context */
+    description: string;
+    /** Version of this surface's contract (semver) */
+    version?: string;
+    /** Actions the agent can invoke on this surface */
+    actions: OUIAction[];
+    /** Observable state the agent can read */
+    observations?: OUIObservation[];
+    /** When this surface is active/available */
+    activation?: OUIActivation;
+    /** Additional metadata for agent context */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Declarative polling configuration for async actions.
+ * The OUI runtime in the browser manages the polling lifecycle automatically
+ * after the action handler returns its dispatch result.
+ */
+interface OUIActionPolling {
+    /** How often to check (milliseconds) */
+    intervalMs: number;
+    /** Max poll attempts before giving up (optional) */
+    maxAttempts?: number;
+    /** Max total duration before giving up in ms (alternative to maxAttempts) */
+    maxDurationMs?: number;
+    /**
+     * Subscribe to a realtime event instead of polling.
+     * If provided, the runtime listens for this event instead of using setInterval.
+     * More efficient when realtime infrastructure exists.
+     */
+    subscribe?: {
+        /** Event name to listen for */
+        event: string;
+        /**
+         * Filter to match the event. Values prefixed with '$dispatchResult.'
+         * are resolved from the handler's return value.
+         * Example: { jobId: '$dispatchResult.jobId' }
+         */
+        filter?: Record<string, unknown>;
+    };
+}
+/**
+ * An Action is a single operation an agent can perform on a surface.
+ * Each action becomes a "tool" that the LLM can call.
+ *
+ * The action's handler executes in the UI (or API) and returns a result
+ * that the agent sees as the tool's output.
+ */
+interface OUIAction {
+    /** Unique action identifier (becomes the tool name) */
+    id: string;
+    /** Human-readable description — this is what the LLM reads to decide when to use it */
+    description: string;
+    /** The action's name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /**
+     * What using the action does. A `transaction` runs only on the user's
+     * approval of the exact request (see `requiresApproval`). Undeclared counts
+     * as a write.
+     */
+    effect?: OUIEffectKind;
+    /** JSON Schema for the action's input parameters */
+    input: JSONSchema;
+    /** JSON Schema for the action's return value (optional — agent still gets the result) */
+    output?: JSONSchema;
+    /**
+     * Destructive: the action removes or replaces something the person made.
+     * Unless its effect only reads, it runs only on the user's approval of the
+     * exact request, which the surface runtime checks before it runs.
+     */
+    confirm?: boolean;
+    /** If true, the action is async — returns immediately with a job/tracking ID */
+    async?: boolean;
+    /** Declarative polling configuration — runtime manages the polling lifecycle after dispatch */
+    polling?: OUIActionPolling;
+    /** Human-readable hint about when this action is appropriate to use */
+    usage?: string;
+    /**
+     * Preconditions that should be met before this action is called.
+     * Expressed as a description (for the LLM) not as executable logic.
+     */
+    preconditions?: string;
+    /** Estimated duration hint (e.g., "instant", "2-5s", "30-120s") */
+    estimatedDuration?: string;
+    /** Tags for categorization */
+    tags?: string[];
+}
+/**
+ * An Observation is a piece of application state that the agent can read.
+ * Observations are pushed to the agent in real-time as the app state changes,
+ * giving it situational awareness without needing screenshots.
+ */
+interface OUIObservation {
+    /** Unique identifier for this observation */
+    id: string;
+    /** Description of what this observation represents */
+    description: string;
+    /** JSON Schema for the observation's value */
+    schema: JSONSchema;
+    /** How frequently this observation updates */
+    updateFrequency?: "realtime" | "on-change" | "polling";
+}
+/**
+ * Activation conditions — when a surface is available to the agent.
+ * A surface might only be active on a specific page, when certain
+ * entities are loaded, or under specific application states.
+ */
+interface OUIActivation {
+    /** URL path(s) where this surface is active */
+    routes?: string | string[];
+    /** Entity type/ID that must be present for this surface to activate */
+    entity?: {
+        type: string;
+        id?: string;
+    };
+    /** Custom predicate description (for documentation, not execution) */
+    condition?: string;
+}
+/**
+ * A request from the agent runtime to execute an action on a surface.
+ */
+interface OUIActionRequest {
+    /** Unique request ID for correlation */
+    requestId: string;
+    /** Which surface this request targets */
+    surfaceId: string;
+    /** Which action to invoke */
+    actionId: string;
+    /** The action's input parameters (validated against the action's input schema) */
+    params: Record<string, unknown>;
+    /** Timestamp of the request */
+    timestamp: number;
+    /**
+     * The user's approval this request runs on, for an action that needs one.
+     * The surface runtime runs such an action only when this matches a grant
+     * the tab received from the user's own confirmation, for exactly `params`.
+     */
+    approval?: OUIActionApproval;
+    /**
+     * The `surfacesHash` of the surfaces the agent runtime already holds for
+     * this client: from its snapshot, or from an earlier result. A client whose
+     * surfaces still hash to this answers without `surfaces`, so a result
+     * carries the client's surfaces only when they changed (§7.3.4).
+     */
+    knownSurfaces?: string;
+}
+/**
+ * Why a client's answer is shorter than the result it produced: the receiving
+ * side refused the full answer (too large, or otherwise not accepted), so the
+ * client sent it again without the parts named in `omitted`. The action's own
+ * outcome — `success`, `error`, and `data` unless omitted — is still the one
+ * that happened (§7.3.6).
+ */
+interface OUIResultDelivery {
+    trimmed: true;
+    /** What the receiving side said when it refused the full answer. */
+    reason: string;
+    /** The fields left out of this answer. */
+    omitted: Array<"surfaces" | "observations" | "data">;
+}
+/**
+ * The result of an action execution, returned from the surface to the agent.
+ */
+interface OUIActionResult {
+    /** Correlates to the request */
+    requestId: string;
+    /** Whether the action succeeded */
+    success: boolean;
+    /** The action's return data (if successful) */
+    data?: unknown;
+    /** Error information (if failed) */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /** Progress indicator for interim polling results (0-100) */
+    progress?: number;
+    /** Whether this is an interim update (polling still in progress) or final */
+    interim?: boolean;
+    /** Duration of execution in milliseconds */
+    durationMs?: number;
+    /** Timestamp of the result */
+    timestamp: number;
+    /**
+     * The surfaces active on the client once the action's effects settled.
+     *
+     * An action can change what the agent is able to do next: navigating
+     * unmounts one page's surfaces and mounts another's. Without this, the agent
+     * would act on the capability set it had before the action, which is the
+     * set the action just replaced.
+     */
+    surfaces?: OUISurface[];
+    /** Latest observation values per surface once the action's effects settled. */
+    observations?: OUIObservationSnapshot;
+    /**
+     * The hash of the client's surfaces once the action's effects settled
+     * (`surfacesHash`). Always present from a client that sends it; `surfaces`
+     * is then present only when this differs from the request's
+     * `knownSurfaces`, and an agent runtime that holds surfaces with this hash
+     * keeps using them.
+     */
+    surfacesHash?: string;
+    /** Present when this answer was trimmed to be delivered (§7.3.6). */
+    delivery?: OUIResultDelivery;
+    /**
+     * False when the client's deadline passed before its UI settled, so
+     * `surfaces` and `observations` may still be changing. Absent or true
+     * otherwise.
+     */
+    settled?: boolean;
+}
+/** Latest observation values, keyed by surface id and then observation id. */
+type OUIObservationSnapshot = Record<string, Record<string, unknown>>;
+/**
+ * What a client can do right now: the surfaces it has mounted and their latest
+ * observation values. A client sends this to its agent runtime (for example,
+ * with each turn), and returns it on every action result.
+ */
+interface OUISurfaceSnapshot {
+    surfaces: OUISurface[];
+    observations: OUIObservationSnapshot;
+    /**
+     * `surfacesHash(surfaces)`: what an agent runtime sends back as a request's
+     * `knownSurfaces`, so the client's answer need not repeat surfaces the
+     * runtime already holds.
+     */
+    surfacesHash?: string;
+}
+/**
+ * An observation update pushed from the surface to the agent.
+ */
+interface OUIObservationUpdate {
+    /** Which surface this observation belongs to */
+    surfaceId: string;
+    /** Which observation updated */
+    observationId: string;
+    /** The new value */
+    value: unknown;
+    /** Timestamp of the update */
+    timestamp: number;
+}
+/**
+ * Surface registration event — sent when a surface becomes active.
+ */
+interface OUISurfaceRegistration {
+    /** The full surface manifest */
+    surface: OUISurface;
+    /** Timestamp of registration */
+    timestamp: number;
+}
+/**
+ * Surface deregistration event — sent when a surface becomes inactive.
+ */
+interface OUISurfaceDeregistration {
+    /** Which surface is being deregistered */
+    surfaceId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * All protocol events exchanged between agent runtime and surfaces.
+ */
+type OUIProtocolEvent = {
+    type: "surface:register";
+    payload: OUISurfaceRegistration;
+} | {
+    type: "surface:deregister";
+    payload: OUISurfaceDeregistration;
+} | {
+    type: "action:request";
+    payload: OUIActionRequest;
+} | {
+    type: "action:result";
+    payload: OUIActionResult;
+} | {
+    type: "observation:update";
+    payload: OUIObservationUpdate;
+};
+/**
+ * Protocol event type strings (for type guards and routing).
+ */
+declare const OUI_PROTOCOL_EVENTS: {
+    readonly SURFACE_REGISTER: "surface:register";
+    readonly SURFACE_DEREGISTER: "surface:deregister";
+    readonly ACTION_REQUEST: "action:request";
+    readonly ACTION_RESULT: "action:result";
+    readonly OBSERVATION_UPDATE: "observation:update";
+};
+
+export { ARGS_HASH_PATTERN as A, type JSONSchema as J, type OUIAction as O, type OUIActionApproval as a, type OUIActionPolling as b, type OUIActionRequest as c, type OUIActionResult as d, type OUIActivation as e, type OUIApprovalGrant as f, type OUIEffectKind as g, type OUIObservation as h, type OUIObservationSnapshot as i, type OUIObservationUpdate as j, type OUIProtocolEvent as k, type OUIResultDelivery as l, type OUISurface as m, type OUISurfaceDeregistration as n, type OUISurfaceRegistration as o, type OUISurfaceSnapshot as p, OUI_EFFECT_ACCESS as q, OUI_EFFECT_KINDS as r, OUI_PROTOCOL_EVENTS as s, argsHash as t, canonicalJson as u, effectAccess as v, requiresApproval as w };

package/dist/{websocket-YfWILdZ4.d.cts → websocket-Ce3tDSsJ.d.ts}

@@ -1,4 +1,4 @@
-import { OUIActionRequest, OUIActionResult, OUIObservationUpdate, OUISurface } from './spec/index.cjs';
+import { c as OUIActionRequest, d as OUIActionResult, j as OUIObservationUpdate, m as OUISurface } from './types-CmJb1BQ8.js';
 
 /**
  * OUI Transport — the wire protocol between agent runtime and surfaces.
@@ -19,8 +19,14 @@ interface OUITransport {
     dispatch(request: OUIActionRequest): void;
     /** Receive action requests (client side). */
     onAction(handler: OUIActionHandler): () => void;
-    /** Answer an action request (client side). */
-    sendResult(result: OUIActionResult): void;
+    /**
+     * Answer an action request (client side). `onAcknowledged` is called with
+     * the receiving side's acknowledgment: accepted, or refused with its reason
+     * — too large, invalid, over a rate limit — so the client can answer again
+     * in a form it accepts (§7.3.6). A receiver that does not acknowledge
+     * answers never calls it.
+     */
+    sendResult(result: OUIActionResult, onAcknowledged?: (ack: OUIAcknowledgment) => void): void;
     /** Receive action results (runtime side). */
     onResult(handler: OUIResultHandler): () => void;
     /** Push an observation update from the surface to the agent runtime */
@@ -47,8 +53,20 @@ interface OUITransport {
      */
     dispose(): void;
 }
-/** Handler for incoming action requests (client side) */
-type OUIActionHandler = (request: OUIActionRequest) => void;
+/**
+ * Handler for incoming action requests (client side). `receipt`, when the
+ * sender asked for one, acknowledges the request: received and accepted, or
+ * refused with why (§7.3.7). The sender can then tell a request that reached a
+ * client from one that reached nobody, and need not send it again.
+ */
+type OUIActionHandler = (request: OUIActionRequest, receipt?: (ack: OUIAcknowledgment) => void) => void;
+/** An acknowledgment: accepted, or refused with a reason. */
+type OUIAcknowledgment = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
 /** Handler for incoming action results (runtime side) */
 type OUIResultHandler = (result: OUIActionResult) => void;
 /** Handler for incoming observation updates (server side) */
@@ -85,7 +103,8 @@ declare function createWebSocketTransport(socket: SocketLike, config?: OUITransp
  */
 interface SocketLike {
     readonly connected?: boolean;
-    emit(event: string, data: unknown): void;
+    /** An optional last argument is the receiver's acknowledgment callback, as Socket.IO takes it. */
+    emit(event: string, ...args: any[]): void;
     on(event: string, handler: (...args: any[]) => void): void;
     off(event: string, handler: (...args: any[]) => void): void;
     once(event: string, handler: (...args: any[]) => void): void;
@@ -93,4 +112,4 @@ interface SocketLike {
     disconnect?(): void;
 }
 
-export { type OUIActionHandler as O, type SocketLike as S, type OUIObservationHandler as a, type OUIResultHandler as b, type OUITransport as c, type OUITransportConfig as d, createWebSocketTransport as e };
+export { type OUIAcknowledgment as O, type SocketLike as S, type OUIActionHandler as a, type OUIObservationHandler as b, type OUIResultHandler as c, type OUITransport as d, type OUITransportConfig as e, createWebSocketTransport as f };

package/dist/{websocket-c5tIUWY5.d.ts → websocket-Ds2Rh_jL.d.cts}

@@ -1,4 +1,4 @@
-import { OUIActionRequest, OUIActionResult, OUIObservationUpdate, OUISurface } from './spec/index.js';
+import { c as OUIActionRequest, d as OUIActionResult, j as OUIObservationUpdate, m as OUISurface } from './types-CmJb1BQ8.cjs';
 
 /**
  * OUI Transport — the wire protocol between agent runtime and surfaces.
@@ -19,8 +19,14 @@ interface OUITransport {
     dispatch(request: OUIActionRequest): void;
     /** Receive action requests (client side). */
     onAction(handler: OUIActionHandler): () => void;
-    /** Answer an action request (client side). */
-    sendResult(result: OUIActionResult): void;
+    /**
+     * Answer an action request (client side). `onAcknowledged` is called with
+     * the receiving side's acknowledgment: accepted, or refused with its reason
+     * — too large, invalid, over a rate limit — so the client can answer again
+     * in a form it accepts (§7.3.6). A receiver that does not acknowledge
+     * answers never calls it.
+     */
+    sendResult(result: OUIActionResult, onAcknowledged?: (ack: OUIAcknowledgment) => void): void;
     /** Receive action results (runtime side). */
     onResult(handler: OUIResultHandler): () => void;
     /** Push an observation update from the surface to the agent runtime */
@@ -47,8 +53,20 @@ interface OUITransport {
      */
     dispose(): void;
 }
-/** Handler for incoming action requests (client side) */
-type OUIActionHandler = (request: OUIActionRequest) => void;
+/**
+ * Handler for incoming action requests (client side). `receipt`, when the
+ * sender asked for one, acknowledges the request: received and accepted, or
+ * refused with why (§7.3.7). The sender can then tell a request that reached a
+ * client from one that reached nobody, and need not send it again.
+ */
+type OUIActionHandler = (request: OUIActionRequest, receipt?: (ack: OUIAcknowledgment) => void) => void;
+/** An acknowledgment: accepted, or refused with a reason. */
+type OUIAcknowledgment = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
 /** Handler for incoming action results (runtime side) */
 type OUIResultHandler = (result: OUIActionResult) => void;
 /** Handler for incoming observation updates (server side) */
@@ -85,7 +103,8 @@ declare function createWebSocketTransport(socket: SocketLike, config?: OUITransp
  */
 interface SocketLike {
     readonly connected?: boolean;
-    emit(event: string, data: unknown): void;
+    /** An optional last argument is the receiver's acknowledgment callback, as Socket.IO takes it. */
+    emit(event: string, ...args: any[]): void;
     on(event: string, handler: (...args: any[]) => void): void;
     off(event: string, handler: (...args: any[]) => void): void;
     once(event: string, handler: (...args: any[]) => void): void;
@@ -93,4 +112,4 @@ interface SocketLike {
     disconnect?(): void;
 }
 
-export { type OUIActionHandler as O, type SocketLike as S, type OUIObservationHandler as a, type OUIResultHandler as b, type OUITransport as c, type OUITransportConfig as d, createWebSocketTransport as e };
+export { type OUIAcknowledgment as O, type SocketLike as S, type OUIActionHandler as a, type OUIObservationHandler as b, type OUIResultHandler as c, type OUITransport as d, type OUITransportConfig as e, createWebSocketTransport as f };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oui-spec",
-  "version": "0.4.1",
-  "description": "OUI — The OpenUI Specification. A machine-readable contract for agent-controllable user interfaces.",
+  "version": "0.6.0",
+  "description": "OUI \u2014 The OpenUI Specification. A machine-readable contract for agent-controllable user interfaces.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,7 +30,8 @@
       "types": "./dist/transport/index.d.ts",
       "import": "./dist/transport/index.js",
       "require": "./dist/transport/index.cjs"
-    }
+    },
+    "./approval-vectors.json": "./spec/approval-vectors.json"
   },
   "typesVersions": {
     "*": {

package/spec/OUI-SPEC-v0.1.md

@@ -607,6 +607,7 @@ When the agent invokes an action, the runtime sends an `action:request`:
 - `requestId` MUST be a globally unique string. UUID v4 is RECOMMENDED.
 - `params` MUST conform to the action's declared `input` schema
 - The agent runtime SHOULD validate `params` before sending; the surface MUST validate upon receipt
+- `knownSurfaces` (OPTIONAL) is the `surfacesHash` of the client's surfaces that the agent runtime already holds, from the client's snapshot (§7.3.5) or an earlier result. A runtime that holds the client's surfaces SHOULD send it (§7.3.4).
 
 #### 7.3.2 Action Result (Success)
 
@@ -659,11 +660,29 @@ When the agent invokes an action, the runtime sends an `action:request`:
 
 A result MAY carry the client's state once the action's effects settled:
 
-| Field          | Type                                          | Description                                                   |
-| -------------- | --------------------------------------------- | ------------------------------------------------------------- |
-| `surfaces`     | `OUISurface[]`                                | Every surface active on the client after the action           |
-| `observations` | `{ [surfaceId]: { [observationId]: value } }` | The latest observation values of those surfaces               |
-| `settled`      | `boolean`                                     | `false` if the client's deadline passed before its UI settled |
+| Field          | Type                                          | Description                                                                      |
+| -------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
+| `surfaces`     | `OUISurface[]`                                | Every surface active on the client after the action, when the runtime lacks them |
+| `surfacesHash` | `string`                                      | The hash of those surfaces, always: `fnv1a64:` and 16 hex digits (see below)     |
+| `observations` | `{ [surfaceId]: { [observationId]: value } }` | The latest observation values of those surfaces                                  |
+| `settled`      | `boolean`                                     | `false` if the client's deadline passed before its UI settled                    |
+
+A client's surfaces can weigh hundreds of kilobytes (every action's schema),
+while what changed for one click is usually nothing. So the client sends
+`surfaces` only when they differ from what the agent runtime holds:
+
+- The client MUST send `surfacesHash`. It is `fnv1a64:` followed by the 64-bit
+  FNV-1a hash, in 16 lowercase hex digits, of the surfaces' JSON with every
+  object's keys sorted, taken over its UTF-16 code units.
+- The client MUST include `surfaces` when `surfacesHash` differs from the
+  request's `knownSurfaces`, or the request carried none; it MAY leave them out
+  otherwise.
+- For an async action's final result, the comparison is with the
+  `surfacesHash` of its acknowledgment, which the runtime received first.
+- A runtime that receives a result without `surfaces` MUST keep the surfaces it
+  holds under that `surfacesHash`. If it holds none under that hash, it MUST
+  treat the client's surfaces as unknown, and send no `knownSurfaces` until it
+  has them again.
 
 An action can change what the agent may do next: navigating unmounts one
 page's surfaces and mounts another's. A client that reports `surfaces` lets
@@ -678,8 +697,9 @@ regardless, with `settled: false`.
 #### 7.3.5 Client Snapshot
 
 A client MAY provide its surfaces and observations to the agent runtime as a
-snapshot (`{ surfaces, observations }`), for example with each request the
-user makes of the agent, instead of through registration events (§7.2). A
+snapshot (`{ surfaces, observations, surfacesHash }`), for example with each
+request the user makes of the agent, instead of through registration events
+(§7.2). Its `surfacesHash` is what the runtime then sends as `knownSurfaces`. A
 runtime that works from snapshots needs no registry of its own, and cannot
 hold a registration the client no longer has.
 
@@ -687,6 +707,42 @@ A client's snapshot is authoritative for that client. A runtime MUST NOT merge
 snapshots from different clients of the same user into one capability set:
 each client can act only on what it has mounted.
 
+#### 7.3.6 A Refused Result
+
+A relay between client and runtime can refuse a result: too large, invalid, or
+over a rate limit. A result refused in silence leaves the runtime waiting out
+its deadline and reporting an action that ran as one that did not answer. So:
+
+- A receiver that refuses a result SHOULD acknowledge it as refused, with a
+  reason (`{ "ok": false, "error": "<reason>" }` on a Socket.IO
+  acknowledgment).
+- A client whose result is refused MUST send it again, trimmed, with
+  `delivery: { trimmed: true, reason, omitted }`. It first leaves out
+  `surfaces` and `observations`, and then also `data`. The action's outcome
+  (`success`, `error`) is never trimmed.
+- A runtime that receives a trimmed result MUST report the action's outcome as
+  it happened, and SHOULD tell its agent what was left out, and why.
+
+#### 7.3.7 Receipts and Repeated Requests
+
+An agent runtime may send a request again when no answer has come, since a
+client can join late. Each copy of a request MUST NOT produce another copy of
+its answer while the first is on its way. Copies of a large answer queue on one
+connection, ahead of the next request's answer, and turn a slow answer into
+missed ones. So:
+
+- The client MAY acknowledge receipt of a request when the sender asks for an
+  acknowledgment. It acknowledges with `{ "ok": true }`, or with
+  `{ "ok": false, "reason" }` for a request it does not accept. A sender that
+  holds a receipt SHOULD wait for the answer rather than send the request
+  again, and SHOULD back off between sends while it holds none.
+- The client MUST run a request id once. It MUST NOT answer a repeat while the
+  first answer is being worked out, or once the receiver acknowledged it.
+- The client MUST NOT answer a repeat while the first answer is unacknowledged
+  and was sent less than a re-answer interval ago (default 8 s). After that
+  interval the answer may have been lost, and the client answers the repeat
+  with the same result.
+
 ### 7.4 Observation Updates
 
 #### 7.4.1 Push Update