oui-spec 0.4.1 → 0.6.0

package/dist/spec/index.d.ts

@@ -1,277 +1,27 @@
+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.
+ * 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 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;
-    /** 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;
-    /** If true, the agent runtime should confirm with the user before executing */
-    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 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.
- */
-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 { type JSONSchema, type OUIAction, type OUIActionPolling, type OUIActionRequest, type OUIActionResult, type OUIActivation, type OUIObservation, type OUIObservationSnapshot, type OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, type OUISurfaceSnapshot, OUI_PROTOCOL_EVENTS };
+/** `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 { OUI_PROTOCOL_EVENTS } from '../chunk-BMCL2K74.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-BzIKgL_I.d.cts → surface-runtime-CSZ9UtBO.d.cts}

@@ -1,5 +1,5 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } 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.cjs';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-Ds2Rh_jL.cjs';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -61,8 +61,13 @@ interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
 interface ActionDefinition<TContext = unknown> {
     id: string;
     description: string;
+    /** Its name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /** What using it does; a `transaction` runs only on the user's approval of the exact request. */
+    effect?: OUIEffectKind;
     input: JSONSchema;
     output?: JSONSchema;
+    /** Destructive: it runs only on the user's approval of the exact request, unless it only reads. */
     confirm?: boolean;
     async?: boolean;
     /**
@@ -209,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;
@@ -241,6 +254,14 @@ interface SurfaceRuntime {
      * code still loading or a page fetching the data it will display.
      */
     hold(): () => void;
+    /**
+     * Record that the user approved one request, here, through their own
+     * confirmation (the agent runtime's approval store answered it to this tab).
+     * An action that needs approval — a `transaction`, or a destructive write —
+     * runs only on a request whose `approval` matches an unused, unexpired grant
+     * for exactly its params. Each grant admits one request.
+     */
+    grantApproval(grant: OUIApprovalGrant): void;
     /** Called whenever the snapshot changes. */
     subscribe(listener: () => void): () => void;
     /** Stop polling, detach from the socket and forget every mount. */

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

@@ -1,5 +1,5 @@
-import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } 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.js';
+import { S as SocketLike, e as OUITransportConfig } from './websocket-Ce3tDSsJ.js';
 
 /**
  * Nominal branding for values OUI must construct itself.
@@ -61,8 +61,13 @@ interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
 interface ActionDefinition<TContext = unknown> {
     id: string;
     description: string;
+    /** Its name as a person reads it, for a confirmation the user approves. */
+    title?: string;
+    /** What using it does; a `transaction` runs only on the user's approval of the exact request. */
+    effect?: OUIEffectKind;
     input: JSONSchema;
     output?: JSONSchema;
+    /** Destructive: it runs only on the user's approval of the exact request, unless it only reads. */
     confirm?: boolean;
     async?: boolean;
     /**
@@ -209,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;
@@ -241,6 +254,14 @@ interface SurfaceRuntime {
      * code still loading or a page fetching the data it will display.
      */
     hold(): () => void;
+    /**
+     * Record that the user approved one request, here, through their own
+     * confirmation (the agent runtime's approval store answered it to this tab).
+     * An action that needs approval — a `transaction`, or a destructive write —
+     * runs only on a request whose `approval` matches an unused, unexpired grant
+     * for exactly its params. Each grant admits one request.
+     */
+    grantApproval(grant: OUIApprovalGrant): void;
     /** Called whenever the snapshot changes. */
     subscribe(listener: () => void): () => void;
     /** Stop polling, detach from the socket and forget every mount. */

package/dist/transport/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var chunkROGKEMLL_cjs = require('../chunk-ROGKEMLL.cjs');
-var chunkDCVVTP3V_cjs = require('../chunk-DCVVTP3V.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 chunkDCVVTP3V_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-F3WKIRAU.js';
+export { createWebSocketTransport } from '../chunk-R3SGP2UY.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map