oui-spec 0.4.1 → 0.6.0

package/README.md

@@ -53,17 +53,26 @@ flowchart TD
 Every action request carries a `requestId`, and the client answers it exactly
 once with an `OUIActionResult` (spec §7.3):
 
-| Event                | Direction        | Carries                                                                                              |
-| -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
-| `{ns}:dispatch`      | runtime → client | `OUIActionRequest` — `requestId`, `surfaceId`, `actionId`, `params`                                  |
-| `{ns}:action:result` | client → runtime | `OUIActionResult` — success or error, and the client's surfaces and observations once the UI settled |
-| `{ns}:observation`   | client → runtime | state updates as they happen                                                                         |
+| Event                | Direction        | Carries                                                                                                                                     |
+| -------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{ns}:dispatch`      | runtime → client | `OUIActionRequest` — `requestId`, `surfaceId`, `actionId`, `params`                                                                         |
+| `{ns}:action:result` | client → runtime | `OUIActionResult` — success or error, the client's observations once the UI settled, its surfaces' hash, and its surfaces when they changed |
+| `{ns}:observation`   | client → runtime | state updates as they happen                                                                                                                |
 
 The result includes what the client can do **after** the action. An action can
 change that: navigating unmounts one page's surfaces and mounts another's. An
 agent that only knew the capability set from before the action would be acting
 on the page it just left.
 
+Surfaces are heavy (every action's schema), so a result repeats them only when
+the agent runtime does not hold them: the runtime sends the `surfacesHash` it
+holds as the request's `knownSurfaces`, and the result carries `surfaces` only
+when the client's hash differs. A result the receiver refuses (too large,
+invalid) is acknowledged as refused, and the client sends it again trimmed,
+with `delivery` saying what was left out and why: the agent always learns the
+action's outcome. A request is acknowledged on receipt when the sender asks,
+and a repeat of a request whose answer is on its way gets no second copy.
+
 An async action (`async: true`) is acknowledged at once with `interim: true`,
 and answered a second time, under the same `requestId`, when its polling
 finishes. Progress in between is published as observations.
@@ -164,8 +173,8 @@ function CounterPage() {
 }
 ```
 
-`runtime.snapshot()` returns `{ surfaces, observations }` for everything
-mounted. An agent runtime that keeps no registry of its own can take it with
+`runtime.snapshot()` returns `{ surfaces, observations, surfacesHash }` for
+everything mounted. An agent runtime that keeps no registry of its own can take it with
 each request (for example, with each chat turn); set `announce: false` and the
 runtime sends nothing but results over the socket.
 
@@ -247,7 +256,7 @@ sequenceDiagram
     WS->>Browser: oui:dispatch
     Note over Browser: Handler runs once (de-duplicated by requestId)
     Note over Browser: Waits until the UI settles
-    Browser->>WS: oui:action:result { requestId, success, data, surfaces, observations }
+    Browser->>WS: oui:action:result { requestId, success, data, observations, surfacesHash, surfaces if changed }
     WS->>Agent: result for requestId
 ```
 
@@ -265,6 +274,28 @@ here is its id. The agent is not held until a two-minute render finishes. The
 client polls or subscribes, publishes progress as observations, and sends the
 request's final result when the job ends.
 
+### Approvals
+
+Some actions can't be undone: an order placed, a payment made, a message sent, something published, or something the person made deleted. An action declares this with `effect: 'transaction'`, or with `confirm: true` for a destructive write. It then runs only on the user's approval of the exact request.
+
+1. The agent runtime stops at the action and shows the user a confirmation built from the action's `title`, `description` and input schema.
+2. The user confirms. The approval store answers this tab, and only this tab, with a grant. The tab records it:
+
+   ```ts
+   runtime.grantApproval({ approvalId, argsHash, expiresAt });
+   ```
+
+3. The request that runs the action carries `approval: { approvalId, argsHash }`. The runtime runs it only when all of these hold:
+   - the grant exists in this tab;
+   - the grant is unused and unexpired;
+   - `argsHash(params)` equals the hash the user approved.
+
+   Otherwise it answers `{ success: false, error: { code: 'APPROVAL_REQUIRED' } }` and never calls the handler. That applies even during a turn the `accept` gate admits.
+
+4. A grant admits one request.
+
+`argsHash` is SHA-256 over the RFC 8785 (JCS) canonical JSON of the params, as lowercase hex. Every implementation (the agent runtime, the approval store, this runtime, and engines in other languages) must reproduce [`spec/approval-vectors.json`](./spec/approval-vectors.json), which is also published as `oui-spec/approval-vectors.json`.
+
 ---
 
 ## Polling & Async Operations
@@ -703,6 +734,8 @@ They even share JSON Schema for parameter validation — a deliberate design cho
 - [x] `oui-spec/transport` — WebSocket + Direct transports
 - [x] `createOUI()` — gated instantiation; integration requirements enforced at compile time
 - [x] `createSurfaceRuntime()` — client-side record of mounted surfaces; every request answered with a result and the snapshot after it
+- [x] Approvals — `transaction` and destructive actions run only on a grant from the user's own confirmation, bound to the exact params (0.5.0)
+- [x] Results carry surfaces only when they changed (`knownSurfaces` / `surfacesHash`), and a refused result is sent again trimmed, saying why (0.6.0)
 - [ ] `oui-spec/devtools` — Surface inspector / debugger
 - [ ] `oui-spec/vue` — Vue bindings
 - [ ] `oui-spec/validator` — Runtime schema validation

package/dist/{chunk-DCVVTP3V.cjs → chunk-5UUJ3F7C.cjs}

@@ -24,7 +24,8 @@ function createWebSocketTransport(socket, config) {
     if (shouldBuffer) {
       while (buffer.length > 0) {
         const msg = buffer.shift();
-        socket.emit(msg.event, msg.data);
+        if (msg.ack) socket.emit(msg.event, msg.data, msg.ack);
+        else socket.emit(msg.event, msg.data);
       }
     }
     connectionHandlers.forEach((h) => h(true));
@@ -33,11 +34,12 @@ function createWebSocketTransport(socket, config) {
     connected = false;
     connectionHandlers.forEach((h) => h(false));
   });
-  function emit(event, data) {
+  function emit(event, data, ack) {
     if (connected) {
-      socket.emit(event, data);
+      if (ack) socket.emit(event, data, ack);
+      else socket.emit(event, data);
     } else if (shouldBuffer && buffer.length < maxBuffer) {
-      buffer.push({ event, data });
+      buffer.push({ event, data, ...ack ? { ack } : {} });
     }
   }
   return {
@@ -48,27 +50,50 @@ function createWebSocketTransport(socket, config) {
     onAction(handler) {
       return listen(
         `${ns}:dispatch`,
-        (data) => {
+        (data, ack) => {
+          const receipt = typeof ack === "function" ? (a) => ack(a) : void 0;
           if (!data || typeof data.requestId !== "string" || !data.requestId || typeof data.surfaceId !== "string" || typeof data.actionId !== "string") {
             console.warn(
               "[OUI] Dropped a dispatch without requestId/surfaceId/actionId",
               data
             );
+            receipt?.({
+              ok: false,
+              reason: "a request needs requestId, surfaceId and actionId"
+            });
             return;
           }
-          handler({
-            requestId: data.requestId,
-            surfaceId: data.surfaceId,
-            actionId: data.actionId,
-            params: data.params ?? {},
-            timestamp: data.timestamp ?? Date.now()
-          });
+          handler(
+            {
+              requestId: data.requestId,
+              surfaceId: data.surfaceId,
+              actionId: data.actionId,
+              params: data.params ?? {},
+              timestamp: data.timestamp ?? Date.now(),
+              ...isApproval(data.approval) ? {
+                approval: {
+                  approvalId: data.approval.approvalId,
+                  argsHash: data.approval.argsHash
+                }
+              } : {},
+              // The surfaces the agent runtime holds, so the answer need not repeat them (§7.3.4).
+              ...typeof data.knownSurfaces === "string" && data.knownSurfaces ? { knownSurfaces: data.knownSurfaces } : {}
+            },
+            receipt
+          );
         }
       );
     },
     // ─── Result ─────────────────────────────────────────────────
-    sendResult(result) {
-      emit(`${ns}:action:result`, result);
+    sendResult(result, onAcknowledged) {
+      emit(
+        `${ns}:action:result`,
+        result,
+        onAcknowledged ? (response) => {
+          const ack = acknowledgmentOf(response);
+          if (ack) onAcknowledged(ack);
+        } : void 0
+      );
     },
     onResult(handler) {
       return listen(
@@ -149,7 +174,19 @@ function createWebSocketTransport(socket, config) {
     }
   };
 }
+function isApproval(value) {
+  const a = value;
+  return !!a && typeof a.approvalId === "string" && !!a.approvalId && typeof a.argsHash === "string";
+}
+function acknowledgmentOf(response) {
+  const r = response;
+  if (!r || typeof r !== "object") return null;
+  if (r.ok === true) return { ok: true };
+  if (r.ok !== false) return null;
+  const why = typeof r.error === "string" ? r.error : typeof r.reason === "string" ? r.reason : "";
+  return { ok: false, reason: why || "refused" };
+}
 
 exports.createWebSocketTransport = createWebSocketTransport;
-//# sourceMappingURL=chunk-DCVVTP3V.cjs.map
-//# sourceMappingURL=chunk-DCVVTP3V.cjs.map
+//# sourceMappingURL=chunk-5UUJ3F7C.cjs.map
+//# sourceMappingURL=chunk-5UUJ3F7C.cjs.map

package/dist/chunk-5UUJ3F7C.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transport/websocket.ts"],"names":[],"mappings":"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","file":"chunk-5UUJ3F7C.cjs","sourcesContent":["import type {\n  OUIAcknowledgment,\n  OUITransport,\n  OUITransportConfig,\n  OUIActionHandler,\n  OUIObservationHandler,\n  OUIResultHandler,\n} from \"./types.js\";\nimport type {\n  OUISurface,\n  OUIObservationUpdate,\n  OUIActionRequest,\n  OUIActionResult,\n  OUIActionApproval,\n} from \"../spec/index.js\";\n\n/**\n * WebSocket transport using Socket.IO.\n * Maps OUI protocol events to socket events with a configurable namespace prefix.\n *\n * Events:\n *   {ns}:dispatch            — action request   (runtime → client)\n *   {ns}:action:result       — action result    (client → runtime)\n *   {ns}:observation         — observation      (client → runtime)\n *   {ns}:surface:register    — registration     (client → runtime)\n *   {ns}:surface:deregister  — deregistration   (client → runtime)\n */\nexport function createWebSocketTransport(\n  socket: SocketLike,\n  config?: OUITransportConfig,\n): OUITransport {\n  const ns = config?.namespace ?? \"oui\";\n  const buffer: Array<{ event: string; data: unknown; ack?: Ack }> = [];\n  const maxBuffer = config?.maxBufferSize ?? 100;\n  const shouldBuffer = config?.bufferWhileDisconnected ?? true;\n\n  let connected = socket.connected ?? false;\n  const connectionHandlers: Array<(c: boolean) => void> = [];\n\n  // Every listener this transport attaches, so dispose() can remove exactly\n  // these and nothing the integrator attached to the same socket.\n  const attached: Array<{ event: string; handler: (...args: any[]) => void }> =\n    [];\n  function listen(\n    event: string,\n    handler: (...args: any[]) => void,\n  ): () => void {\n    socket.on(event, handler);\n    const entry = { event, handler };\n    attached.push(entry);\n    return () => {\n      socket.off(event, handler);\n      const i = attached.indexOf(entry);\n      if (i >= 0) attached.splice(i, 1);\n    };\n  }\n\n  listen(\"connect\", () => {\n    connected = true;\n    // Flush before announcing: anything queued while offline was sent earlier\n    // than whatever a connection handler is about to send.\n    if (shouldBuffer) {\n      while (buffer.length > 0) {\n        const msg = buffer.shift()!;\n        if (msg.ack) socket.emit(msg.event, msg.data, msg.ack);\n        else socket.emit(msg.event, msg.data);\n      }\n    }\n    connectionHandlers.forEach((h) => h(true));\n  });\n\n  listen(\"disconnect\", () => {\n    connected = false;\n    connectionHandlers.forEach((h) => h(false));\n  });\n\n  function emit(event: string, data: unknown, ack?: Ack) {\n    if (connected) {\n      if (ack) socket.emit(event, data, ack);\n      else socket.emit(event, data);\n    } else if (shouldBuffer && buffer.length < maxBuffer) {\n      buffer.push({ event, data, ...(ack ? { ack } : {}) });\n    }\n  }\n\n  return {\n    // ─── Dispatch ───────────────────────────────────────────────\n    dispatch(request: OUIActionRequest) {\n      emit(`${ns}:dispatch`, request);\n    },\n\n    onAction(handler: OUIActionHandler) {\n      return listen(\n        `${ns}:dispatch`,\n        (data: Partial<OUIActionRequest> | undefined, ack?: unknown) => {\n          // The sender's receipt, when it asked for one (§7.3.7).\n          const receipt =\n            typeof ack === \"function\"\n              ? (a: OUIAcknowledgment) => (ack as (r: unknown) => void)(a)\n              : undefined;\n          // A request without a requestId cannot be answered, and answering is\n          // the contract. Refuse it loudly rather than run an action whose\n          // result has nowhere to go.\n          if (\n            !data ||\n            typeof data.requestId !== \"string\" ||\n            !data.requestId ||\n            typeof data.surfaceId !== \"string\" ||\n            typeof data.actionId !== \"string\"\n          ) {\n            console.warn(\n              \"[OUI] Dropped a dispatch without requestId/surfaceId/actionId\",\n              data,\n            );\n            receipt?.({\n              ok: false,\n              reason: \"a request needs requestId, surfaceId and actionId\",\n            });\n            return;\n          }\n          handler(\n            {\n              requestId: data.requestId,\n              surfaceId: data.surfaceId,\n              actionId: data.actionId,\n              params: data.params ?? {},\n              timestamp: data.timestamp ?? Date.now(),\n              ...(isApproval(data.approval)\n                ? {\n                    approval: {\n                      approvalId: data.approval.approvalId,\n                      argsHash: data.approval.argsHash,\n                    },\n                  }\n                : {}),\n              // The surfaces the agent runtime holds, so the answer need not repeat them (§7.3.4).\n              ...(typeof data.knownSurfaces === \"string\" && data.knownSurfaces\n                ? { knownSurfaces: data.knownSurfaces }\n                : {}),\n            },\n            receipt,\n          );\n        },\n      );\n    },\n\n    // ─── Result ─────────────────────────────────────────────────\n    sendResult(\n      result: OUIActionResult,\n      onAcknowledged?: (ack: OUIAcknowledgment) => void,\n    ) {\n      // Acknowledged, so a refusal is heard rather than silent (§7.3.6).\n      emit(\n        `${ns}:action:result`,\n        result,\n        onAcknowledged\n          ? (response: unknown) => {\n              const ack = acknowledgmentOf(response);\n              if (ack) onAcknowledged(ack);\n            }\n          : undefined,\n      );\n    },\n\n    onResult(handler: OUIResultHandler) {\n      return listen(`${ns}:action:result`, (data: OUIActionResult) =>\n        handler(data),\n      );\n    },\n\n    // ─── Observation Channel ────────────────────────────────────\n    pushObservation(update: OUIObservationUpdate) {\n      emit(`${ns}:observation`, update);\n    },\n\n    onObservation(handler: OUIObservationHandler) {\n      return listen(`${ns}:observation`, (data: OUIObservationUpdate) =>\n        handler(data),\n      );\n    },\n\n    // ─── Surface Lifecycle ──────────────────────────────────────\n    registerSurface(surface: OUISurface) {\n      emit(`${ns}:surface:register`, { surface, timestamp: Date.now() });\n    },\n\n    deregisterSurface(surfaceId: string) {\n      emit(`${ns}:surface:deregister`, { surfaceId, timestamp: Date.now() });\n    },\n\n    onSurfaceRegister(handler: (surface: OUISurface) => void) {\n      return listen(`${ns}:surface:register`, (data: { surface: OUISurface }) =>\n        handler(data.surface),\n      );\n    },\n\n    onSurfaceDeregister(handler: (surfaceId: string) => void) {\n      return listen(`${ns}:surface:deregister`, (data: { surfaceId: string }) =>\n        handler(data.surfaceId),\n      );\n    },\n\n    // ─── Connection ─────────────────────────────────────────────\n    get connected() {\n      return connected;\n    },\n\n    async connect() {\n      if (connected) return;\n      return new Promise<void>((resolve, reject) => {\n        const timeout = setTimeout(() => {\n          reject(\n            new Error(\n              `OUI transport connect timeout (${config?.connectTimeoutMs ?? 10000}ms)`,\n            ),\n          );\n        }, config?.connectTimeoutMs ?? 10000);\n\n        socket.once(\"connect\", () => {\n          clearTimeout(timeout);\n          resolve();\n        });\n\n        if (typeof socket.connect === \"function\") {\n          socket.connect();\n        }\n      });\n    },\n\n    disconnect() {\n      if (typeof socket.disconnect === \"function\") {\n        socket.disconnect();\n      }\n    },\n\n    onConnectionChange(handler: (c: boolean) => void) {\n      connectionHandlers.push(handler);\n      return () => {\n        const idx = connectionHandlers.indexOf(handler);\n        if (idx >= 0) connectionHandlers.splice(idx, 1);\n      };\n    },\n\n    dispose() {\n      for (const { event, handler } of attached.splice(0)) {\n        socket.off(event, handler);\n      }\n      connectionHandlers.length = 0;\n      buffer.length = 0;\n    },\n  };\n}\n\n/**\n * Minimal socket interface — compatible with Socket.IO client or server socket.\n * Only the methods OUI actually uses.\n */\nexport interface SocketLike {\n  readonly connected?: boolean;\n  /** An optional last argument is the receiver's acknowledgment callback, as Socket.IO takes it. */\n  emit(event: string, ...args: any[]): void;\n  on(event: string, handler: (...args: any[]) => void): void;\n  off(event: string, handler: (...args: any[]) => void): void;\n  once(event: string, handler: (...args: any[]) => void): void;\n  connect?(): void;\n  disconnect?(): void;\n}\n\n/** An approval as the wire carries it; anything else is dropped, so the runtime treats the request as unapproved. */\nfunction isApproval(value: unknown): value is OUIActionApproval {\n  const a = value as Partial<OUIActionApproval> | null | undefined;\n  return (\n    !!a &&\n    typeof a.approvalId === \"string\" &&\n    !!a.approvalId &&\n    typeof a.argsHash === \"string\"\n  );\n}\n\n/** The receiver's acknowledgment callback. */\ntype Ack = (response: unknown) => void;\n\n/**\n * A receiver's acknowledgment: `{ ok: true }`, or `{ ok: false, error }` /\n * `{ ok: false, reason }` as a refusal; null for anything else.\n */\nfunction acknowledgmentOf(response: unknown): OUIAcknowledgment | null {\n  const r = response as\n    { ok?: unknown; error?: unknown; reason?: unknown } | null | undefined;\n  if (!r || typeof r !== \"object\") return null;\n  if (r.ok === true) return { ok: true };\n  if (r.ok !== false) return null;\n  const why =\n    typeof r.error === \"string\"\n      ? r.error\n      : typeof r.reason === \"string\"\n        ? r.reason\n        : \"\";\n  return { ok: false, reason: why || \"refused\" };\n}\n"]}

package/dist/{chunk-GDB56ZQZ.cjs → chunk-AFNWLRKV.cjs}

@@ -1,6 +1,7 @@
 'use strict';
 
-var chunkDCVVTP3V_cjs = require('./chunk-DCVVTP3V.cjs');
+var chunkLDECTDPU_cjs = require('./chunk-LDECTDPU.cjs');
+var chunk5UUJ3F7C_cjs = require('./chunk-5UUJ3F7C.cjs');
 
 // src/core/brand.ts
 function brand(value) {
@@ -83,6 +84,8 @@ function actionToManifest(action) {
   return {
     id: action.id,
     description: action.description,
+    ...action.title !== void 0 ? { title: action.title } : {},
+    ...action.effect !== void 0 ? { effect: action.effect } : {},
     input: action.input,
     output: action.output,
     confirm: action.confirm,
@@ -127,7 +130,7 @@ function createOUI(config) {
     seen.add(surface.id);
   }
   const transport = brand(
-    chunkDCVVTP3V_cjs.createWebSocketTransport(socket, transportConfig)
+    chunk5UUJ3F7C_cjs.createWebSocketTransport(socket, transportConfig)
   );
   const byId = new Map(surfaces.map((s) => [s.id, s]));
   return {
@@ -155,12 +158,14 @@ function createOUI(config) {
 var DEFAULT_QUIET_MS = 250;
 var DEFAULT_SETTLE_TIMEOUT_MS = 5e3;
 var DEFAULT_DEDUPE_WINDOW = 500;
+var DEFAULT_REANSWER_AFTER_MS = 8e3;
 var SETTLE_TICK_MS = 50;
 function createSurfaceRuntime(options = {}) {
   const announce = options.announce ?? true;
   const quietMs = options.settle?.quietMs ?? DEFAULT_QUIET_MS;
   const settleTimeoutMs = options.settle?.timeoutMs ?? DEFAULT_SETTLE_TIMEOUT_MS;
   const dedupeWindow = options.dedupeWindow ?? DEFAULT_DEDUPE_WINDOW;
+  const reanswerAfterMs = options.reanswerAfterMs ?? DEFAULT_REANSWER_AFTER_MS;
   let nextKey = 1;
   const entries = [];
   const observations = /* @__PURE__ */ new Map();
@@ -185,7 +190,32 @@ function createSurfaceRuntime(options = {}) {
   function acknowledged(requestId) {
     return ackFor(requestId).promise;
   }
+  const delivery = /* @__PURE__ */ new Map();
+  const answeredHash = /* @__PURE__ */ new Map();
   let lastChangeAt = Date.now();
+  const grants = /* @__PURE__ */ new Map();
+  async function approvalRefusal(request) {
+    const approval = request.approval;
+    if (!approval)
+      return "it needs the user's approval, and the request carries none";
+    let hash;
+    try {
+      hash = await chunkLDECTDPU_cjs.argsHash(request.params ?? {});
+    } catch (err) {
+      return `its params cannot be checked against an approval: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const grant = grants.get(approval.approvalId);
+    if (!grant) return "this tab holds no unused approval for it";
+    if (Date.now() >= grant.expiresAt) {
+      grants.delete(approval.approvalId);
+      return "its approval has expired";
+    }
+    if (approval.argsHash !== grant.argsHash || hash !== grant.argsHash) {
+      return "its params are not the ones the user approved";
+    }
+    grants.delete(approval.approvalId);
+    return null;
+  }
   let socket = null;
   let transport = null;
   let detachTransport = [];
@@ -275,17 +305,20 @@ function createSurfaceRuntime(options = {}) {
     const finish = async (success, data, error) => {
       await acknowledged(requestId);
       const snap = snapshot();
-      transport?.sendResult({
+      const known = answeredHash.get(requestId);
+      answer({
         requestId,
         success,
         ...data !== void 0 ? { data: toJsonSafe(data) } : {},
         ...error ? { error } : {},
         interim: false,
         timestamp: Date.now(),
-        surfaces: snap.surfaces,
-        observations: snap.observations
+        ...snap.surfacesHash !== known ? { surfaces: snap.surfaces } : {},
+        observations: snap.observations,
+        surfacesHash: snap.surfacesHash
       });
       acks.delete(requestId);
+      answeredHash.delete(requestId);
     };
     const observationId = `${surfaceId}:${actionId}:status`;
     const pollerKey = `${surfaceId}\0${actionId}`;
@@ -414,7 +447,17 @@ function createSurfaceRuntime(options = {}) {
         }
       };
     } else {
-      result = await entry.surface.executeAction(
+      const declared = entry.surface.actions.find(
+        (a) => a.id === request.actionId
+      );
+      const refusal = declared && chunkLDECTDPU_cjs.requiresApproval(declared.effect, declared.confirm) ? await approvalRefusal(request) : null;
+      result = refusal ? {
+        success: false,
+        error: {
+          code: "APPROVAL_REQUIRED",
+          message: `"${request.actionId}" was not run: ${refusal}.`
+        }
+      } : await entry.surface.executeAction(
         request.actionId,
         request.params ?? {},
         entry.getContext()
@@ -437,6 +480,7 @@ function createSurfaceRuntime(options = {}) {
     }
     const settled = await waitUntilSettled(startedAt);
     const snap = snapshot();
+    if (interim) answeredHash.set(request.requestId, snap.surfacesHash);
     return {
       requestId: request.requestId,
       success: result.success,
@@ -445,11 +489,39 @@ function createSurfaceRuntime(options = {}) {
       ...interim ? { interim: true } : {},
       durationMs: Date.now() - startedAt,
       timestamp: Date.now(),
-      surfaces: snap.surfaces,
+      // Only what the agent runtime does not already hold (§7.3.4).
+      ...snap.surfacesHash !== request.knownSurfaces ? { surfaces: snap.surfaces } : {},
       observations: snap.observations,
+      surfacesHash: snap.surfacesHash,
       settled
     };
   }
+  function answer(result, onReceived) {
+    const steps = [
+      ["surfaces", "observations"],
+      ["surfaces", "observations", "data"]
+    ];
+    const send = (frame, step) => {
+      transport?.sendResult(frame, (ack) => {
+        if (ack.ok) {
+          onReceived?.();
+          return;
+        }
+        const omitted = steps[step];
+        if (!omitted) {
+          console.warn(
+            `[OUI] The answer to ${result.requestId} was refused even trimmed: ${ack.reason}`
+          );
+          return;
+        }
+        console.warn(
+          `[OUI] The answer to ${result.requestId} was refused (${ack.reason}); sending it without ${omitted.join(", ")}`
+        );
+        send(trimmed(result, ack.reason, omitted), step + 1);
+      });
+    };
+    send(result, 0);
+  }
   function execute(request) {
     const seen = results.get(request.requestId);
     if (seen) return seen;
@@ -458,6 +530,7 @@ function createSurfaceRuntime(options = {}) {
     while (results.size > dedupeWindow) {
       const oldest = results.keys().next().value;
       results.delete(oldest);
+      delivery.delete(oldest);
     }
     return pending;
   }
@@ -470,7 +543,11 @@ function createSurfaceRuntime(options = {}) {
       if (values && values.size > 0)
         obs[e.surface.id] = Object.fromEntries(values);
     }
-    return { surfaces, observations: obs };
+    return {
+      surfaces,
+      observations: obs,
+      surfacesHash: chunkLDECTDPU_cjs.surfacesHash(surfaces)
+    };
   }
   function attach(next) {
     if (next === socket) return;
@@ -480,21 +557,36 @@ function createSurfaceRuntime(options = {}) {
     transport = null;
     socket = next;
     if (!next) return;
-    const t = chunkDCVVTP3V_cjs.createWebSocketTransport(next, options.transport);
+    const t = chunk5UUJ3F7C_cjs.createWebSocketTransport(next, options.transport);
     transport = t;
     detachTransport.push(
-      t.onAction((request) => {
+      t.onAction((request, receipt) => {
         if (options.accept && !options.accept(request)) {
           console.warn(
             `[OUI] Refused a request the client does not accept: ${request.surfaceId}.${request.actionId} (${request.requestId})`
           );
+          receipt?.({
+            ok: false,
+            reason: "this client does not accept requests now"
+          });
           return;
         }
+        receipt?.({ ok: true });
+        const id = request.requestId;
+        const prior = delivery.get(id);
+        if (prior && prior.state !== "sent") return;
+        if (prior && Date.now() - prior.at < reanswerAfterMs) return;
+        if (!prior) delivery.set(id, { state: "running", at: Date.now() });
         void execute(request).then((result) => {
-          transport?.sendResult(result);
-          const ack = ackFor(request.requestId);
+          if (results.has(id))
+            delivery.set(id, { state: "sent", at: Date.now() });
+          answer(result, () => {
+            if (results.has(id))
+              delivery.set(id, { state: "received", at: Date.now() });
+          });
+          const ack = ackFor(id);
           ack.resolve();
-          if (!result.interim) acks.delete(request.requestId);
+          if (!result.interim) acks.delete(id);
         });
       })
     );
@@ -557,6 +649,16 @@ function createSurfaceRuntime(options = {}) {
         changed();
       };
     },
+    grantApproval(grant) {
+      if (!grant || typeof grant.approvalId !== "string" || !grant.approvalId || typeof grant.argsHash !== "string" || !chunkLDECTDPU_cjs.ARGS_HASH_PATTERN.test(grant.argsHash) || !Number.isFinite(grant.expiresAt)) {
+        throw new Error(
+          "[OUI] grantApproval needs an approvalId, an args hash and an expiry"
+        );
+      }
+      const now = Date.now();
+      for (const [id, g] of grants) if (now >= g.expiresAt) grants.delete(id);
+      grants.set(grant.approvalId, { ...grant });
+    },
     subscribe(listener) {
       listeners.add(listener);
       return () => {
@@ -574,9 +676,18 @@ function createSurfaceRuntime(options = {}) {
       holds.clear();
       listeners.clear();
       acks.clear();
+      answeredHash.clear();
+      delivery.clear();
+      grants.clear();
     }
   };
 }
+function trimmed(result, reason, omitted) {
+  const out = { ...result };
+  for (const field of omitted) delete out[field];
+  out.delivery = { trimmed: true, reason, omitted: [...omitted] };
+  return out;
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -592,5 +703,5 @@ function toJsonSafe(value) {
 exports.createOUI = createOUI;
 exports.createSurfaceRuntime = createSurfaceRuntime;
 exports.defineSurface = defineSurface;
-//# sourceMappingURL=chunk-GDB56ZQZ.cjs.map
-//# sourceMappingURL=chunk-GDB56ZQZ.cjs.map
+//# sourceMappingURL=chunk-AFNWLRKV.cjs.map
+//# sourceMappingURL=chunk-AFNWLRKV.cjs.map