oui-spec 0.1.0 → 0.3.0

package/dist/surface-runtime--2lZGB7Z.d.cts

@@ -0,0 +1,241 @@
+import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } from './spec/index.cjs';
+import { S as SocketLike, d as OUITransportConfig } from './websocket-YfWILdZ4.cjs';
+
+/**
+ * Nominal branding for values OUI must construct itself.
+ *
+ * Structural typing means any object with the right shape satisfies an
+ * interface. That is how Closure Studio ended up hand-rolling OUI's transport:
+ * `SocketLike` was importable, `OUITransport` was a plain interface, so an
+ * integrator could satisfy every type without ever calling OUI. The result was
+ * a second implementation of the wire — hardcoded namespace, re-declared
+ * payload types on the server, and a dead `action:result` mapping alongside the
+ * observation channel that already carried results.
+ *
+ * A unique symbol cannot be produced outside this module. Branding the types
+ * OUI owns turns "you should use our constructor" into "you cannot compile
+ * without it".
+ */
+declare const OUI_BRAND: unique symbol;
+/** Marks a value as constructed by OUI itself. */
+interface OUIBranded<TKind extends string> {
+    readonly [OUI_BRAND]: TKind;
+}
+
+/**
+ * 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, const TId extends string = string>(definition: SurfaceDefinition<TContext> & {
+    id: TId;
+}): DefinedSurface<TContext> & {
+    id: TId;
+};
+/** A fully defined surface with both manifest extraction and execution capabilities */
+/**
+ * Branded so it can only come from `defineSurface`.
+ *
+ * Without the brand a plain object literal satisfies this interface
+ * structurally, which is how an integrator can assemble a surface that never
+ * ran defineSurface's duplicate-id checks and never produced a real manifest.
+ */
+interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext>, OUIBranded<"surface"> {
+    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;
+}
+
+/**
+ * The client-side surface runtime.
+ *
+ * Holds the surfaces a client has mounted, answers every action request with a
+ * result, and produces the snapshot an agent runtime works from.
+ *
+ * WHY THIS EXISTS
+ *
+ * The first integration kept no client-side record of what was mounted. Each
+ * surface hook registered itself with a server-side registry and listened for
+ * dispatches on its own. Three things followed:
+ *
+ * - The registry was the only record of what the client could do, and it lost
+ *   entries: a dead socket's cleanup removed a live tab's registration, and the
+ *   browser never registered again. The agent then had no UI tools at all.
+ * - Nothing answered a dispatch. The agent was told an action succeeded before
+ *   the client had run it, and never saw the page an action led to.
+ * - Every hook listened independently, through two paths, so one dispatch ran
+ *   twice and nothing de-duplicated it.
+ *
+ * Here the client is the record. `snapshot()` is what the client can do right
+ * now, and every request is run once, waited on until the UI settles, and
+ * answered with its result and the snapshot after it.
+ */
+
+interface SettleOptions {
+    /**
+     * The UI counts as settled once nothing has mounted, unmounted or changed an
+     * observation for this long, and no hold is open. Default 250 ms.
+     */
+    quietMs?: number;
+    /** Give up waiting after this long and answer with `settled: false`. Default 5000 ms. */
+    timeoutMs?: number;
+}
+interface SurfaceRuntimeOptions {
+    /** The socket to answer requests on. Can be set or replaced later with `attach`. */
+    socket?: SocketLike | null;
+    /** Wire configuration for the transport the runtime builds on the socket. */
+    transport?: OUITransportConfig;
+    /**
+     * Also announce registrations and observations over the transport, for agent
+     * runtimes that keep a server-side registry. Default true.
+     *
+     * An agent runtime that takes the client's snapshot instead (sent with each
+     * turn, and returned on every result) has no use for them: set false.
+     */
+    announce?: boolean;
+    settle?: SettleOptions;
+    /** How many answered request ids to remember, for de-duplication. Default 500. */
+    dedupeWindow?: number;
+}
+interface MountedSurface {
+    readonly surfaceId: string;
+    /** Record an observation value. A no-op once unmounted. */
+    pushObservation(observationId: string, value: unknown): void;
+    /** Remove this mount. Other mounts of the same surface id are unaffected. */
+    unmount(): void;
+}
+interface SurfaceRuntime {
+    /**
+     * Mount a surface. `getContext` is read when an action runs, so handlers see
+     * the latest state rather than the state at mount time.
+     *
+     * Mounting the same surface id twice is allowed (React StrictMode does it on
+     * every mount); the most recent mount serves its actions.
+     */
+    mount<TContext>(surface: DefinedSurface<TContext>, getContext: () => TContext): MountedSurface;
+    /** Answer requests arriving on this socket (null detaches). */
+    attach(socket: SocketLike | null): void;
+    /** What the client can do right now. */
+    snapshot(): OUISurfaceSnapshot;
+    /**
+     * Run a request once and resolve with its result. A request id seen before
+     * resolves with the first result instead of running again.
+     */
+    execute(request: OUIActionRequest): Promise<OUIActionResult>;
+    /**
+     * Keep the UI unsettled until the returned function is called. For work an
+     * action starts that mounting and unmounting cannot show, such as a route's
+     * code still loading or a page fetching the data it will display.
+     */
+    hold(): () => void;
+    /** Called whenever the snapshot changes. */
+    subscribe(listener: () => void): () => void;
+    /** Stop polling, detach from the socket and forget every mount. */
+    dispose(): void;
+}
+declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;
+
+export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceRuntime as e, type SurfaceRuntimeOptions as f, createSurfaceRuntime as g, defineSurface as h };

package/dist/surface-runtime-Dj_nhd7r.d.ts

@@ -0,0 +1,241 @@
+import { JSONSchema, OUIActionPolling, OUIActivation, OUISurface, OUISurfaceSnapshot, OUIActionRequest, OUIActionResult } from './spec/index.js';
+import { S as SocketLike, d as OUITransportConfig } from './websocket-c5tIUWY5.js';
+
+/**
+ * Nominal branding for values OUI must construct itself.
+ *
+ * Structural typing means any object with the right shape satisfies an
+ * interface. That is how Closure Studio ended up hand-rolling OUI's transport:
+ * `SocketLike` was importable, `OUITransport` was a plain interface, so an
+ * integrator could satisfy every type without ever calling OUI. The result was
+ * a second implementation of the wire — hardcoded namespace, re-declared
+ * payload types on the server, and a dead `action:result` mapping alongside the
+ * observation channel that already carried results.
+ *
+ * A unique symbol cannot be produced outside this module. Branding the types
+ * OUI owns turns "you should use our constructor" into "you cannot compile
+ * without it".
+ */
+declare const OUI_BRAND: unique symbol;
+/** Marks a value as constructed by OUI itself. */
+interface OUIBranded<TKind extends string> {
+    readonly [OUI_BRAND]: TKind;
+}
+
+/**
+ * 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, const TId extends string = string>(definition: SurfaceDefinition<TContext> & {
+    id: TId;
+}): DefinedSurface<TContext> & {
+    id: TId;
+};
+/** A fully defined surface with both manifest extraction and execution capabilities */
+/**
+ * Branded so it can only come from `defineSurface`.
+ *
+ * Without the brand a plain object literal satisfies this interface
+ * structurally, which is how an integrator can assemble a surface that never
+ * ran defineSurface's duplicate-id checks and never produced a real manifest.
+ */
+interface DefinedSurface<TContext = unknown> extends SurfaceDefinition<TContext>, OUIBranded<"surface"> {
+    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;
+}
+
+/**
+ * The client-side surface runtime.
+ *
+ * Holds the surfaces a client has mounted, answers every action request with a
+ * result, and produces the snapshot an agent runtime works from.
+ *
+ * WHY THIS EXISTS
+ *
+ * The first integration kept no client-side record of what was mounted. Each
+ * surface hook registered itself with a server-side registry and listened for
+ * dispatches on its own. Three things followed:
+ *
+ * - The registry was the only record of what the client could do, and it lost
+ *   entries: a dead socket's cleanup removed a live tab's registration, and the
+ *   browser never registered again. The agent then had no UI tools at all.
+ * - Nothing answered a dispatch. The agent was told an action succeeded before
+ *   the client had run it, and never saw the page an action led to.
+ * - Every hook listened independently, through two paths, so one dispatch ran
+ *   twice and nothing de-duplicated it.
+ *
+ * Here the client is the record. `snapshot()` is what the client can do right
+ * now, and every request is run once, waited on until the UI settles, and
+ * answered with its result and the snapshot after it.
+ */
+
+interface SettleOptions {
+    /**
+     * The UI counts as settled once nothing has mounted, unmounted or changed an
+     * observation for this long, and no hold is open. Default 250 ms.
+     */
+    quietMs?: number;
+    /** Give up waiting after this long and answer with `settled: false`. Default 5000 ms. */
+    timeoutMs?: number;
+}
+interface SurfaceRuntimeOptions {
+    /** The socket to answer requests on. Can be set or replaced later with `attach`. */
+    socket?: SocketLike | null;
+    /** Wire configuration for the transport the runtime builds on the socket. */
+    transport?: OUITransportConfig;
+    /**
+     * Also announce registrations and observations over the transport, for agent
+     * runtimes that keep a server-side registry. Default true.
+     *
+     * An agent runtime that takes the client's snapshot instead (sent with each
+     * turn, and returned on every result) has no use for them: set false.
+     */
+    announce?: boolean;
+    settle?: SettleOptions;
+    /** How many answered request ids to remember, for de-duplication. Default 500. */
+    dedupeWindow?: number;
+}
+interface MountedSurface {
+    readonly surfaceId: string;
+    /** Record an observation value. A no-op once unmounted. */
+    pushObservation(observationId: string, value: unknown): void;
+    /** Remove this mount. Other mounts of the same surface id are unaffected. */
+    unmount(): void;
+}
+interface SurfaceRuntime {
+    /**
+     * Mount a surface. `getContext` is read when an action runs, so handlers see
+     * the latest state rather than the state at mount time.
+     *
+     * Mounting the same surface id twice is allowed (React StrictMode does it on
+     * every mount); the most recent mount serves its actions.
+     */
+    mount<TContext>(surface: DefinedSurface<TContext>, getContext: () => TContext): MountedSurface;
+    /** Answer requests arriving on this socket (null detaches). */
+    attach(socket: SocketLike | null): void;
+    /** What the client can do right now. */
+    snapshot(): OUISurfaceSnapshot;
+    /**
+     * Run a request once and resolve with its result. A request id seen before
+     * resolves with the first result instead of running again.
+     */
+    execute(request: OUIActionRequest): Promise<OUIActionResult>;
+    /**
+     * Keep the UI unsettled until the returned function is called. For work an
+     * action starts that mounting and unmounting cannot show, such as a route's
+     * code still loading or a page fetching the data it will display.
+     */
+    hold(): () => void;
+    /** Called whenever the snapshot changes. */
+    subscribe(listener: () => void): () => void;
+    /** Stop polling, detach from the socket and forget every mount. */
+    dispose(): void;
+}
+declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;
+
+export { type ActionDefinition as A, type DefinedSurface as D, type MountedSurface as M, type OUIBranded as O, type SettleOptions as S, type ActionHandlerResult as a, type ActionPollingConfig as b, type ObservationDefinition as c, type SurfaceDefinition as d, type SurfaceRuntime as e, type SurfaceRuntimeOptions as f, createSurfaceRuntime as g, defineSurface as h };

package/dist/transport/index.cjs

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

package/dist/transport/index.d.cts

@@ -1,79 +1,6 @@
-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;
-}
+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';
 
 /**
  * Direct transport — for same-process communication.
@@ -88,4 +15,4 @@ declare function createDirectTransportPair(): {
     client: OUITransport;
 };
 
-export { type OUIActionHandler, type OUIObservationHandler, type OUITransport, type OUITransportConfig, type SocketLike, createDirectTransportPair, createWebSocketTransport };
+export { OUITransport, createDirectTransportPair };

package/dist/transport/index.d.ts

@@ -1,79 +1,6 @@
-import { OUIObservationUpdate, OUISurface } from '../spec/index.js';
-
-/**
- * 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;
-}
+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';
 
 /**
  * Direct transport — for same-process communication.
@@ -88,4 +15,4 @@ declare function createDirectTransportPair(): {
     client: OUITransport;
 };
 
-export { type OUIActionHandler, type OUIObservationHandler, type OUITransport, type OUITransportConfig, type SocketLike, createDirectTransportPair, createWebSocketTransport };
+export { OUITransport, createDirectTransportPair };

package/dist/transport/index.js

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