oui-spec 0.1.0

package/dist/core/index.d.cts

@@ -0,0 +1,120 @@
+import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface } from '../spec/index.cjs';
+export { OUIAction, OUIActionRequest, OUIActionResult, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from '../spec/index.cjs';
+
+/**
+ * Configuration for defining an OUI surface with handlers.
+ * This is the "integration file" an app provides — it declares both
+ * the schema (what the agent sees) and the implementation (what executes).
+ */
+interface SurfaceDefinition<TContext = unknown> {
+    id: string;
+    name: string;
+    description: string;
+    version?: string;
+    activation?: OUIActivation;
+    actions: ActionDefinition<TContext>[];
+    observations?: ObservationDefinition[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Polling config with an optional resolve handler.
+ * The spec's OUIActionPolling is the manifest shape (no functions).
+ * The core extends it with the resolve implementation for the runtime.
+ */
+interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
+    /**
+     * Called on each poll interval. Receives the dispatch result from the handler
+     * plus the current context. Return { done: true, data } to stop polling,
+     * or { done: false, data } to continue.
+     */
+    resolve?: (dispatchResult: unknown, context: TContext) => Promise<{
+        done: boolean;
+        data: unknown;
+    }>;
+}
+/**
+ * An action definition includes both the schema (for the agent) and
+ * the handler (for execution). This is the single source of truth —
+ * no separate YAML, no separate listener, no drift possible.
+ */
+interface ActionDefinition<TContext = unknown> {
+    id: string;
+    description: string;
+    input: JSONSchema;
+    output?: JSONSchema;
+    confirm?: boolean;
+    async?: boolean;
+    /**
+     * Polling/subscription config for async actions.
+     * After the handler returns, the OUI runtime starts polling or subscribing
+     * and pushes observation updates until the operation completes.
+     * Extends the spec's OUIActionPolling with an optional resolve handler.
+     */
+    polling?: ActionPollingConfig<TContext>;
+    usage?: string;
+    preconditions?: string;
+    estimatedDuration?: string;
+    tags?: string[];
+    /**
+     * The handler that executes when the agent invokes this action.
+     * Receives typed params and a context object (app-specific state/utilities).
+     * Returns a result that the agent sees as the tool output.
+     */
+    handler: (params: Record<string, unknown>, context: TContext) => Promise<ActionHandlerResult>;
+}
+interface ActionHandlerResult {
+    success: boolean;
+    data?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /** For async actions: metadata passed to the polling resolver */
+    dispatchMeta?: Record<string, unknown>;
+}
+interface ObservationDefinition {
+    id: string;
+    description: string;
+    schema: JSONSchema;
+    /** Function that returns the current observation value */
+    getValue?: () => unknown;
+}
+/**
+ * Define an OUI surface — the single entry point for integrating
+ * an application feature with the OUI protocol.
+ *
+ * This function validates the definition and returns a typed surface
+ * object that can be registered with an agent runtime or transport layer.
+ *
+ * @example
+ * ```typescript
+ * const mySurface = defineSurface({
+ *   id: 'my-feature',
+ *   name: 'My Feature',
+ *   description: 'Does something cool',
+ *   actions: [
+ *     {
+ *       id: 'do_thing',
+ *       description: 'Does the thing',
+ *       input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+ *       handler: async (params) => {
+ *         const result = await doTheThing(params.name);
+ *         return { success: true, data: result };
+ *       },
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function defineSurface<TContext = unknown>(definition: SurfaceDefinition<TContext>): DefinedSurface<TContext>;
+/** A fully defined surface with both manifest extraction and execution capabilities */
+interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext> {
+    toManifest(): OUISurface;
+    executeAction(actionId: string, params: Record<string, unknown>, context: TContext): Promise<ActionHandlerResult>;
+    getActionIds(): string[];
+    /** Get the polling config for an action (if async) */
+    getPollingConfig(actionId: string): OUIActionPolling | undefined;
+}
+
+export { type ActionDefinition, type ActionHandlerResult, type ActionPollingConfig, type DefinedSurface, JSONSchema, OUIActivation, OUISurface, type ObservationDefinition, type SurfaceDefinition, defineSurface };

package/dist/core/index.d.ts

@@ -0,0 +1,120 @@
+import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface } from '../spec/index.js';
+export { OUIAction, OUIActionRequest, OUIActionResult, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from '../spec/index.js';
+
+/**
+ * Configuration for defining an OUI surface with handlers.
+ * This is the "integration file" an app provides — it declares both
+ * the schema (what the agent sees) and the implementation (what executes).
+ */
+interface SurfaceDefinition<TContext = unknown> {
+    id: string;
+    name: string;
+    description: string;
+    version?: string;
+    activation?: OUIActivation;
+    actions: ActionDefinition<TContext>[];
+    observations?: ObservationDefinition[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Polling config with an optional resolve handler.
+ * The spec's OUIActionPolling is the manifest shape (no functions).
+ * The core extends it with the resolve implementation for the runtime.
+ */
+interface ActionPollingConfig<TContext = unknown> extends OUIActionPolling {
+    /**
+     * Called on each poll interval. Receives the dispatch result from the handler
+     * plus the current context. Return { done: true, data } to stop polling,
+     * or { done: false, data } to continue.
+     */
+    resolve?: (dispatchResult: unknown, context: TContext) => Promise<{
+        done: boolean;
+        data: unknown;
+    }>;
+}
+/**
+ * An action definition includes both the schema (for the agent) and
+ * the handler (for execution). This is the single source of truth —
+ * no separate YAML, no separate listener, no drift possible.
+ */
+interface ActionDefinition<TContext = unknown> {
+    id: string;
+    description: string;
+    input: JSONSchema;
+    output?: JSONSchema;
+    confirm?: boolean;
+    async?: boolean;
+    /**
+     * Polling/subscription config for async actions.
+     * After the handler returns, the OUI runtime starts polling or subscribing
+     * and pushes observation updates until the operation completes.
+     * Extends the spec's OUIActionPolling with an optional resolve handler.
+     */
+    polling?: ActionPollingConfig<TContext>;
+    usage?: string;
+    preconditions?: string;
+    estimatedDuration?: string;
+    tags?: string[];
+    /**
+     * The handler that executes when the agent invokes this action.
+     * Receives typed params and a context object (app-specific state/utilities).
+     * Returns a result that the agent sees as the tool output.
+     */
+    handler: (params: Record<string, unknown>, context: TContext) => Promise<ActionHandlerResult>;
+}
+interface ActionHandlerResult {
+    success: boolean;
+    data?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /** For async actions: metadata passed to the polling resolver */
+    dispatchMeta?: Record<string, unknown>;
+}
+interface ObservationDefinition {
+    id: string;
+    description: string;
+    schema: JSONSchema;
+    /** Function that returns the current observation value */
+    getValue?: () => unknown;
+}
+/**
+ * Define an OUI surface — the single entry point for integrating
+ * an application feature with the OUI protocol.
+ *
+ * This function validates the definition and returns a typed surface
+ * object that can be registered with an agent runtime or transport layer.
+ *
+ * @example
+ * ```typescript
+ * const mySurface = defineSurface({
+ *   id: 'my-feature',
+ *   name: 'My Feature',
+ *   description: 'Does something cool',
+ *   actions: [
+ *     {
+ *       id: 'do_thing',
+ *       description: 'Does the thing',
+ *       input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+ *       handler: async (params) => {
+ *         const result = await doTheThing(params.name);
+ *         return { success: true, data: result };
+ *       },
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function defineSurface<TContext = unknown>(definition: SurfaceDefinition<TContext>): DefinedSurface<TContext>;
+/** A fully defined surface with both manifest extraction and execution capabilities */
+interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext> {
+    toManifest(): OUISurface;
+    executeAction(actionId: string, params: Record<string, unknown>, context: TContext): Promise<ActionHandlerResult>;
+    getActionIds(): string[];
+    /** Get the polling config for an action (if async) */
+    getPollingConfig(actionId: string): OUIActionPolling | undefined;
+}
+
+export { type ActionDefinition, type ActionHandlerResult, type ActionPollingConfig, type DefinedSurface, JSONSchema, OUIActivation, OUISurface, type ObservationDefinition, type SurfaceDefinition, defineSurface };

package/dist/core/index.js

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

package/dist/core/index.js.map

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

package/dist/index.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+var chunkLEXIU2MH_cjs = require('./chunk-LEXIU2MH.cjs');
+var chunk3DCIL4FV_cjs = require('./chunk-3DCIL4FV.cjs');
+var chunk2ON5IEXB_cjs = require('./chunk-2ON5IEXB.cjs');
+var chunkWZXUKJ7E_cjs = require('./chunk-WZXUKJ7E.cjs');
+
+
+
+Object.defineProperty(exports, "defineSurface", {
+  enumerable: true,
+  get: function () { return chunkLEXIU2MH_cjs.defineSurface; }
+});
+Object.defineProperty(exports, "OUI_PROTOCOL_EVENTS", {
+  enumerable: true,
+  get: function () { return chunk3DCIL4FV_cjs.OUI_PROTOCOL_EVENTS; }
+});
+Object.defineProperty(exports, "useObservation", {
+  enumerable: true,
+  get: function () { return chunk2ON5IEXB_cjs.useObservation; }
+});
+Object.defineProperty(exports, "useSurface", {
+  enumerable: true,
+  get: function () { return chunk2ON5IEXB_cjs.useSurface; }
+});
+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/index.cjs.map

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

package/dist/index.d.cts

@@ -0,0 +1,4 @@
+export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from './spec/index.cjs';
+export { ActionDefinition, ActionHandlerResult, ActionPollingConfig, DefinedSurface, ObservationDefinition, SurfaceDefinition, defineSurface } from './core/index.cjs';
+export { UseSurfaceOptions, useObservation, useSurface } from './react/index.cjs';
+export { OUIActionHandler, OUIObservationHandler, OUITransport, OUITransportConfig, SocketLike, createDirectTransportPair, createWebSocketTransport } from './transport/index.cjs';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { JSONSchema, OUIAction, OUIActionPolling, OUIActionRequest, OUIActionResult, OUIActivation, OUIObservation, OUIObservationUpdate, OUIProtocolEvent, OUISurface, OUISurfaceDeregistration, OUISurfaceRegistration, OUI_PROTOCOL_EVENTS } from './spec/index.js';
+export { ActionDefinition, ActionHandlerResult, ActionPollingConfig, DefinedSurface, ObservationDefinition, SurfaceDefinition, defineSurface } from './core/index.js';
+export { UseSurfaceOptions, useObservation, useSurface } from './react/index.js';
+export { OUIActionHandler, OUIObservationHandler, OUITransport, OUITransportConfig, SocketLike, createDirectTransportPair, createWebSocketTransport } from './transport/index.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { defineSurface } from './chunk-JO5LGOB6.js';
+export { OUI_PROTOCOL_EVENTS } from './chunk-CVUUSPF4.js';
+export { useObservation, useSurface } from './chunk-UIGRLZOX.js';
+export { createDirectTransportPair, createWebSocketTransport } from './chunk-7EXSMPGR.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/react/index.cjs

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

package/dist/react/index.cjs.map

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

package/dist/react/index.d.cts

@@ -0,0 +1,62 @@
+import { OUIActionRequest, OUISurface } from '../spec/index.cjs';
+import { DefinedSurface } from '../core/index.cjs';
+
+/**
+ * Configuration for the useSurface hook.
+ */
+interface UseSurfaceOptions<TContext> {
+    /** The defined surface (from defineSurface()) */
+    surface: DefinedSurface<TContext>;
+    /** The context passed to action handlers (app state, utilities, etc.) */
+    context: TContext;
+    /** Transport send function — how to send protocol events to the agent runtime */
+    send: (event: {
+        type: string;
+        payload: unknown;
+    }) => void;
+    /** Whether the surface is currently active (respects activation conditions) */
+    active?: boolean;
+}
+/**
+ * useSurface — registers an OUI surface with the agent runtime and handles
+ * incoming action requests by executing them locally and pushing observation
+ * updates. Actions are dispatched one-way (no request/response correlation).
+ *
+ * After an action handler executes, if the action has a polling config, the
+ * hook starts a polling loop that pushes observation updates until the
+ * operation completes or times out.
+ *
+ * @example
+ * ```tsx
+ * function DataVizPage() {
+ *   const { state, updateState, goToStep } = useDataVizWizard();
+ *
+ *   useSurface({
+ *     surface: datavizSurface,
+ *     context: { state, updateState, goToStep },
+ *     send: agentTransport.send,
+ *     active: true,
+ *   });
+ *
+ *   return <DataVizWizard />;
+ * }
+ * ```
+ */
+declare function useSurface<TContext>(options: UseSurfaceOptions<TContext>): {
+    handleActionRequest: (request: OUIActionRequest) => Promise<void>;
+    surfaceId: string;
+    manifest: OUISurface;
+    /** Manually stop polling for a specific action */
+    stopPolling: (actionId: string) => void;
+    /** Stop all active pollers */
+    stopAllPolling: () => void;
+};
+/**
+ * Helper to push an observation update to the agent runtime.
+ */
+declare function useObservation(surfaceId: string, observationId: string, value: unknown, send: (event: {
+    type: string;
+    payload: unknown;
+}) => void): void;
+
+export { type UseSurfaceOptions, useObservation, useSurface };

package/dist/react/index.d.ts

@@ -0,0 +1,62 @@
+import { OUIActionRequest, OUISurface } from '../spec/index.js';
+import { DefinedSurface } from '../core/index.js';
+
+/**
+ * Configuration for the useSurface hook.
+ */
+interface UseSurfaceOptions<TContext> {
+    /** The defined surface (from defineSurface()) */
+    surface: DefinedSurface<TContext>;
+    /** The context passed to action handlers (app state, utilities, etc.) */
+    context: TContext;
+    /** Transport send function — how to send protocol events to the agent runtime */
+    send: (event: {
+        type: string;
+        payload: unknown;
+    }) => void;
+    /** Whether the surface is currently active (respects activation conditions) */
+    active?: boolean;
+}
+/**
+ * useSurface — registers an OUI surface with the agent runtime and handles
+ * incoming action requests by executing them locally and pushing observation
+ * updates. Actions are dispatched one-way (no request/response correlation).
+ *
+ * After an action handler executes, if the action has a polling config, the
+ * hook starts a polling loop that pushes observation updates until the
+ * operation completes or times out.
+ *
+ * @example
+ * ```tsx
+ * function DataVizPage() {
+ *   const { state, updateState, goToStep } = useDataVizWizard();
+ *
+ *   useSurface({
+ *     surface: datavizSurface,
+ *     context: { state, updateState, goToStep },
+ *     send: agentTransport.send,
+ *     active: true,
+ *   });
+ *
+ *   return <DataVizWizard />;
+ * }
+ * ```
+ */
+declare function useSurface<TContext>(options: UseSurfaceOptions<TContext>): {
+    handleActionRequest: (request: OUIActionRequest) => Promise<void>;
+    surfaceId: string;
+    manifest: OUISurface;
+    /** Manually stop polling for a specific action */
+    stopPolling: (actionId: string) => void;
+    /** Stop all active pollers */
+    stopAllPolling: () => void;
+};
+/**
+ * Helper to push an observation update to the agent runtime.
+ */
+declare function useObservation(surfaceId: string, observationId: string, value: unknown, send: (event: {
+    type: string;
+    payload: unknown;
+}) => void): void;
+
+export { type UseSurfaceOptions, useObservation, useSurface };

package/dist/react/index.js

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

package/dist/react/index.js.map

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

package/dist/spec/index.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunk3DCIL4FV_cjs = require('../chunk-3DCIL4FV.cjs');
+
+
+
+Object.defineProperty(exports, "OUI_PROTOCOL_EVENTS", {
+  enumerable: true,
+  get: function () { return chunk3DCIL4FV_cjs.OUI_PROTOCOL_EVENTS; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/spec/index.cjs.map

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