oui-spec 0.1.0

package/dist/spec/index.d.cts

@@ -0,0 +1,249 @@
+/**
+ * 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;
+    /** 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;
+}
+/**
+ * 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 OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, OUI_PROTOCOL_EVENTS };

package/dist/spec/index.d.ts

@@ -0,0 +1,249 @@
+/**
+ * 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;
+    /** 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;
+}
+/**
+ * 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 OUIObservationUpdate, type OUIProtocolEvent, type OUISurface, type OUISurfaceDeregistration, type OUISurfaceRegistration, OUI_PROTOCOL_EVENTS };

package/dist/spec/index.js

@@ -0,0 +1,3 @@
+export { OUI_PROTOCOL_EVENTS } from '../chunk-CVUUSPF4.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/spec/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/transport/index.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkWZXUKJ7E_cjs = require('../chunk-WZXUKJ7E.cjs');
+
+
+
+Object.defineProperty(exports, "createDirectTransportPair", {
+  enumerable: true,
+  get: function () { return chunkWZXUKJ7E_cjs.createDirectTransportPair; }
+});
+Object.defineProperty(exports, "createWebSocketTransport", {
+  enumerable: true,
+  get: function () { return chunkWZXUKJ7E_cjs.createWebSocketTransport; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/transport/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/transport/index.d.cts

@@ -0,0 +1,91 @@
+import { OUIObservationUpdate, OUISurface } from '../spec/index.cjs';
+
+/**
+ * OUI Transport — the wire protocol between agent runtime and surfaces.
+ *
+ * Two one-way channels:
+ * - Dispatch channel (server → client): sends action instructions
+ * - Observation channel (client → server): pushes state updates
+ *
+ * NO request/response. NO correlation IDs. NO waiting.
+ * The Lambda dispatches and terminates. The browser processes and pushes state.
+ */
+interface OUITransport {
+    /** Dispatch an action to a surface (one-way, fire-and-forget) */
+    dispatch(surfaceId: string, actionId: string, params: Record<string, unknown>): void;
+    /** Receive dispatched actions (surface/client side) */
+    onAction(handler: OUIActionHandler): () => void;
+    /** Push an observation update from the surface to the agent runtime */
+    pushObservation(update: OUIObservationUpdate): void;
+    /** Receive observation updates (runtime/server side) */
+    onObservation(handler: OUIObservationHandler): () => void;
+    /** Register a surface manifest (client → server) */
+    registerSurface(surface: OUISurface): void;
+    /** Deregister a surface (client → server) */
+    deregisterSurface(surfaceId: string): void;
+    /** Receive surface registrations (server side) */
+    onSurfaceRegister(handler: (surface: OUISurface) => void): () => void;
+    /** Receive surface deregistrations (server side) */
+    onSurfaceDeregister(handler: (surfaceId: string) => void): () => void;
+    readonly connected: boolean;
+    connect(): Promise<void>;
+    disconnect(): void;
+    onConnectionChange(handler: (connected: boolean) => void): () => void;
+}
+/** Handler for incoming action dispatches (client side) */
+type OUIActionHandler = (surfaceId: string, actionId: string, params: Record<string, unknown>) => void;
+/** Handler for incoming observation updates (server side) */
+type OUIObservationHandler = (update: OUIObservationUpdate) => void;
+/**
+ * Transport configuration options.
+ */
+interface OUITransportConfig {
+    /** Namespace prefix for events (default: 'oui') */
+    namespace?: string;
+    /** Connection timeout in ms */
+    connectTimeoutMs?: number;
+    /** Whether to buffer dispatches while disconnected */
+    bufferWhileDisconnected?: boolean;
+    /** Max buffer size (messages dropped after this) */
+    maxBufferSize?: number;
+}
+
+/**
+ * WebSocket transport using Socket.IO.
+ * Maps OUI protocol events to socket events with a configurable namespace prefix.
+ *
+ * Events emitted:
+ *   {ns}:dispatch        — action dispatch (server → client)
+ *   {ns}:observation     — observation update (client → server)
+ *   {ns}:surface:register   — surface registration (client → server)
+ *   {ns}:surface:deregister — surface deregistration (client → server)
+ */
+declare function createWebSocketTransport(socket: SocketLike, config?: OUITransportConfig): OUITransport;
+/**
+ * Minimal socket interface — compatible with Socket.IO client or server socket.
+ * Only the methods OUI actually uses.
+ */
+interface SocketLike {
+    readonly connected?: boolean;
+    emit(event: string, data: unknown): 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;
+    connect?(): void;
+    disconnect?(): void;
+}
+
+/**
+ * Direct transport — for same-process communication.
+ * Used for API surfaces (where the agent runtime and surface are in the same Lambda)
+ * and for testing (where you want synchronous, in-memory communication).
+ *
+ * Creates a paired (server, client) transport where messages sent on one
+ * side are immediately received on the other.
+ */
+declare function createDirectTransportPair(): {
+    server: OUITransport;
+    client: OUITransport;
+};
+
+export { type OUIActionHandler, type OUIObservationHandler, type OUITransport, type OUITransportConfig, type SocketLike, createDirectTransportPair, createWebSocketTransport };