oui-spec 0.5.0 → 0.6.0

package/dist/spec/index.d.ts

@@ -1,366 +1,27 @@
-/**
- * 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>;
+import { m as OUISurface } from '../types-CmJb1BQ8.js';
+export { A as ARGS_HASH_PATTERN, J as JSONSchema, O as OUIAction, a as OUIActionApproval, b as OUIActionPolling, c as OUIActionRequest, d as OUIActionResult, e as OUIActivation, f as OUIApprovalGrant, g as OUIEffectKind, h as OUIObservation, i as OUIObservationSnapshot, j as OUIObservationUpdate, k as OUIProtocolEvent, l as OUIResultDelivery, n as OUISurfaceDeregistration, o as OUISurfaceRegistration, p as OUISurfaceSnapshot, q as OUI_EFFECT_ACCESS, r as OUI_EFFECT_KINDS, s as OUI_PROTOCOL_EVENTS, t as argsHash, u as canonicalJson, v as effectAccess, w as requiresApproval } from '../types-CmJb1BQ8.js';
 
 /**
- * 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).
+ * The identity of a set of surfaces, for an answer that need not repeat them
+ * (§7.3.4).
  *
- * 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.
+ * A client's surfaces are what an agent may do; every result used to carry
+ * them all, so each answer weighed what the page's whole manifest weighs —
+ * on a studio page with a hundred and fifty actions, about 265 KB for a click.
+ * A relay that caps a frame then drops whole answers, and the agent hears
+ * nothing. With this hash the agent runtime says which surfaces it holds
+ * (`knownSurfaces`), and the client sends its surfaces only when they differ.
  *
- * 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 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;
-    /**
-     * 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;
-}
-/**
- * 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.
+ * The hash is of the surfaces' canonical JSON (object keys sorted), so it does
+ * not depend on the order a manifest's fields were written in, and is the
+ * same wherever it is computed. It is a 64-bit FNV-1a over the JSON's UTF-16
+ * code units, kept as two 32-bit halves: not a security measure — the agent
+ * runtime is told the surfaces by the same client that hashes them — but
+ * collision-resistant enough that two different capability sets of one page
+ * never share one.
  */
-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, type JSONSchema, type OUIAction, type OUIActionApproval, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIApprovalGrant, type OUIEffectKind, type OUIObservation, type OUIObservationSnapshot, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, type OUISurfaceSnapshot, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval };
+/** `surfaces`' hash, as a result's `surfacesHash` and a request's `knownSurfaces` carry it. */
+declare function surfacesHash(surfaces: readonly OUISurface[]): string;
+
+export { OUISurface, surfacesHash };

package/dist/spec/index.js

@@ -1,3 +1,3 @@
-export { ARGS_HASH_PATTERN, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval } from '../chunk-BNGJJM3T.js';
+export { ARGS_HASH_PATTERN, OUI_EFFECT_ACCESS, OUI_EFFECT_KINDS, OUI_PROTOCOL_EVENTS, argsHash, canonicalJson, effectAccess, requiresApproval, surfacesHash } from '../chunk-B2EFZMGY.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{surface-runtime-CS0rByFQ.d.ts → surface-runtime-CSZ9UtBO.d.cts}

@@ -1,5 +1,5 @@
-import { OUIEffectKind, JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult, OUIApprovalGrant } from './spec/index.js';
-import { S as SocketLike, d as OUITransportConfig } from './websocket-c5tIUWY5.js';
+import { g as OUIEffectKind, J as JSONSchema, b as OUIActionPolling, e as OUIActivation, m as OUISurface, p as OUISurfaceSnapshot, c as OUIActionRequest, d as OUIActionResult, f as OUIApprovalGrant } from './types-CmJb1BQ8.cjs';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-Ds2Rh_jL.cjs';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -214,6 +214,14 @@ interface SurfaceRuntimeOptions {
      * not checked; they come from the application itself.
      */
     accept?: (request: OUIActionRequest) => boolean;
+    /**
+     * A request sent again while its answer is on the way is not answered again
+     * (§7.3.7): every copy of a large answer queues on the one socket, ahead of
+     * the next request's answer. Only once the answer has gone this long without
+     * the receiver acknowledging it — lost, or a receiver that does not
+     * acknowledge — is a repeat answered again. Default 8000 ms.
+     */
+    reanswerAfterMs?: number;
 }
 interface MountedSurface {
     readonly surfaceId: string;

package/dist/{surface-runtime-lqXn221P.d.cts → surface-runtime-D5nINY4b.d.ts}

@@ -1,5 +1,5 @@
-import { OUIEffectKind, JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult, OUIApprovalGrant } from './spec/index.cjs';
-import { S as SocketLike, d as OUITransportConfig } from './websocket-YfWILdZ4.cjs';
+import { g as OUIEffectKind, J as JSONSchema, b as OUIActionPolling, e as OUIActivation, m as OUISurface, p as OUISurfaceSnapshot, c as OUIActionRequest, d as OUIActionResult, f as OUIApprovalGrant } from './types-CmJb1BQ8.js';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-Ce3tDSsJ.js';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -214,6 +214,14 @@ interface SurfaceRuntimeOptions {
      * not checked; they come from the application itself.
      */
     accept?: (request: OUIActionRequest) => boolean;
+    /**
+     * A request sent again while its answer is on the way is not answered again
+     * (§7.3.7): every copy of a large answer queues on the one socket, ahead of
+     * the next request's answer. Only once the answer has gone this long without
+     * the receiver acknowledging it — lost, or a receiver that does not
+     * acknowledge — is a repeat answered again. Default 8000 ms.
+     */
+    reanswerAfterMs?: number;
 }
 interface MountedSurface {
     readonly surfaceId: string;

package/dist/transport/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkROGKEMLL_cjs = require('../chunk-ROGKEMLL.cjs');
-var chunkXUX4XVP3_cjs = require('../chunk-XUX4XVP3.cjs');
+var chunk5UUJ3F7C_cjs = require('../chunk-5UUJ3F7C.cjs');
 
 
 
@@ -11,7 +11,7 @@ Object.defineProperty(exports, "createDirectTransportPair", {
 });
 Object.defineProperty(exports, "createWebSocketTransport", {
   enumerable: true,
-  get: function () { return chunkXUX4XVP3_cjs.createWebSocketTransport; }
+  get: function () { return chunk5UUJ3F7C_cjs.createWebSocketTransport; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/transport/index.d.cts

@@ -1,6 +1,6 @@
-import { c as OUITransport } from '../websocket-YfWILdZ4.cjs';
-export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from '../websocket-YfWILdZ4.cjs';
-import '../spec/index.cjs';
+import { d as OUITransport } from '../websocket-Ds2Rh_jL.cjs';
+export { O as OUIAcknowledgment, a as OUIActionHandler, b as OUIObservationHandler, c as OUIResultHandler, e as OUITransportConfig, S as SocketLike, f as createWebSocketTransport } from '../websocket-Ds2Rh_jL.cjs';
+import '../types-CmJb1BQ8.cjs';
 
 /**
  * Direct transport — for same-process communication.

package/dist/transport/index.d.ts

@@ -1,6 +1,6 @@
-import { c as OUITransport } from '../websocket-c5tIUWY5.js';
-export { O as OUIActionHandler, a as OUIObservationHandler, b as OUIResultHandler, d as OUITransportConfig, S as SocketLike, e as createWebSocketTransport } from '../websocket-c5tIUWY5.js';
-import '../spec/index.js';
+import { d as OUITransport } from '../websocket-Ce3tDSsJ.js';
+export { O as OUIAcknowledgment, a as OUIActionHandler, b as OUIObservationHandler, c as OUIResultHandler, e as OUITransportConfig, S as SocketLike, f as createWebSocketTransport } from '../websocket-Ce3tDSsJ.js';
+import '../types-CmJb1BQ8.js';
 
 /**
  * Direct transport — for same-process communication.

package/dist/transport/index.js

@@ -1,4 +1,4 @@
 export { createDirectTransportPair } from '../chunk-IIZ6HL2L.js';
-export { createWebSocketTransport } from '../chunk-UKKITNZK.js';
+export { createWebSocketTransport } from '../chunk-R3SGP2UY.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map