@robota-sdk/agent-transport-ws 3.0.0-beta.100

package/README.md

@@ -0,0 +1,85 @@
+# @robota-sdk/agent-transport-ws
+
+WebSocket transport for the Robota SDK. `WsTransport` serves a running agent session on a loopback
+WebSocket server, so a local client (a browser page, a desktop app, another process) can drive the
+session in real time: submit prompts, receive streamed output, answer permission prompts, and read
+history and status. The wire protocol and the session bridge come from `@robota-sdk/agent-transport`;
+this package adds the socket server, connection admission and lifecycle, and pulls in only `ws`.
+
+## Installation
+
+```bash
+npm install @robota-sdk/agent-transport-ws @robota-sdk/agent-transport
+```
+
+Requires Node.js 22.12 or later. `@robota-sdk/agent-transport` provides the session and message types
+used below.
+
+## Usage
+
+```typescript
+import { WsTransport } from '@robota-sdk/agent-transport-ws';
+import type { IProtocolSession } from '@robota-sdk/agent-transport';
+
+declare const session: IProtocolSession; // e.g. an InteractiveSession from @robota-sdk/agent-framework
+
+const transport = new WsTransport({ port: 7070 });
+transport.attach(session);
+await transport.start();
+
+// Hand both to your client; it connects to ws://127.0.0.1:<port>/?token=<token>
+console.log(transport.boundPort, transport.resolvedToken);
+
+await transport.stop();
+```
+
+The server listens on `127.0.0.1` only. If the port is taken it tries the next one, up to `maxRetries`
+times; `boundPort` reports the port actually bound.
+
+Every connection must present the token, as a `?token=` query parameter or as the
+`Sec-WebSocket-Protocol` value, or it is closed before any session data is sent. Without a `token`
+option, a random token is minted per launch and exposed as `resolvedToken`. The `Host` header must be a
+loopback name, and a browser's `Origin` must be loopback, so another web page cannot reach the socket.
+Running without a token takes `open: true` with an `openReason`, and is discouraged: any local process
+could then drive the session.
+
+Clients exchange JSON text frames typed as `TClientMessage` / `TServerMessage` from
+`@robota-sdk/agent-transport`, whose `./client` entry point also provides browser-safe decoders.
+
+## `WsTransport` options
+
+| Option                                                                   | Type                          | Description                                                                                          |
+| ------------------------------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `port`                                                                   | `number`                      | Port to bind. Default `7070`.                                                                        |
+| `maxRetries`                                                             | `number`                      | Next ports to try when the port is in use. Default `20`.                                             |
+| `token`                                                                  | `string`                      | Credential every connection must present. Omitted: one is minted per launch.                         |
+| `open` / `openReason`                                                    | `boolean` / `string`          | Run without a token; `openReason` must say why. Rejected together with `token`.                      |
+| `allowedHosts` / `allowedOrigins`                                        | `readonly string[]`           | Extra `Host` names and browser `Origin`s to accept beyond loopback.                                  |
+| `driverId` / `surface`                                                   | `TDriverId` / `TUsageSurface` | Identity recorded on turns submitted through this transport, set by the host rather than the client. |
+| `sessionDirectory`                                                       | `ISessionDirectory`           | Lets clients list, start and switch the host's sessions.                                             |
+| `sessionBinder`                                                          | `ISessionBinder`              | Gives each connection its own session binding, so one client's switch does not move the others.      |
+| `personalUsageReporter` / `usageReporter` / `storedSessionUsageReporter` | reporters                     | Host-owned usage read models, available to admitted connections.                                     |
+
+`start()` before `attach()` throws, as does a second `start()` while running. `stop()` closes every
+client (forcing any that do not close within a few seconds), is safe to call more than once, and
+requires `attach()` again before the next `start()`.
+
+Delivery failures are the connection's problem, not the session's: if a socket is closed or a send fails,
+that connection is cleaned up once and the session operation that produced the event is unaffected.
+
+## Other exports
+
+- `createWsTransport(options)` — the same session bridge without a server, for a WebSocket you already
+  own. Pass a `send` function; after `start()`, feed each inbound text frame to `transport.onMessage`.
+- `registerChannel(descriptor)` on `WsTransport` and the standalone `PayloadChannelRegistry` — carry
+  application-defined events and binary frames on the same connection as the agent protocol. Binary
+  frames go to channels; text frames go to the agent protocol.
+- Types: `IWsTransportConfig` (the options above), `IWsTransport`, `IWsTransportOptions`,
+  `TChannelSink`.
+
+## Related
+
+- [`@robota-sdk/agent-transport`](../agent-transport/README.md) — the wire protocol and session bridge.
+- [`@robota-sdk/agent-transport-webrtc`](../agent-transport-webrtc/README.md) — the same protocol
+  carried peer to peer.
+- [docs/SPEC.md](./docs/SPEC.md) — package contract and invariants.

package/dist/node/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@robota-sdk/agent-transport"),t=require("node:http"),n=require("ws"),r=require("node:crypto"),i=require("@robota-sdk/agent-transport/node");function a(t){let n=null,r=null,i=e=>Object.assign(Error(`WebSocket transport ${e}.`),{name:`TransportLifecycleError`,code:e,transportName:`ws`}),a={name:`ws`,lifecycle:Object.freeze({kind:`service`}),onMessage:null,attach(e){n=e},async start(){if(!n)throw i(`not-attached`);if(r)throw i(`already-started`);let o=(0,e.createOutboundDelivery)(t.send,(e,n)=>{s.cleanup(),r=null,a.onMessage=null,t.onDeliveryError?.(e,n)}),s=(0,e.createSessionMessageHandler)({session:n,deliver:o,...t.driverId?{driverId:t.driverId}:{},...t.surface?{surface:t.surface}:{},...t.personalUsageReporter?{personalUsageReporter:t.personalUsageReporter}:{},...t.usageReporter?{usageReporter:t.usageReporter}:{},...t.storedSessionUsageReporter?{storedSessionUsageReporter:t.storedSessionUsageReporter}:{},...t.sessionDirectory?{sessionDirectory:t.sessionDirectory}:{},...t.settingsReporter?{settingsReporter:t.settingsReporter}:{}});r=s.cleanup,this.onMessage=s.onMessage},async stop(){r?.(),r=null,this.onMessage=null,n=null}};return a}var o=class t{channels=new Map;sinks=new Set;addSink(e){return this.sinks.add(e),()=>{this.sinks.delete(e)}}registerChannel(e){if(this.channels.has(e.name))throw Error(`Channel "${e.name}" is already registered on this transport`);let t={descriptor:e,declaredEvents:new Set(e.events),eventHandlers:new Map,binaryHandlers:new Set,seq:0,open:!0};return this.channels.set(e.name,t),this.createHandle(e,t)}receive(t){let n=(0,e.decodeChannelFrame)(t);if(!n.ok)return n;let{frame:r}=n,i=this.channels.get(r.channel);if(!i||!i.open)return{ok:!1,error:`No channel registered for "${r.channel}"`};if(r.kind===`binary`){if(i.descriptor.binary!==!0)return{ok:!1,error:`Channel "${r.channel}" did not declare binary payload support`};for(let e of[...i.binaryHandlers])e(r);return{ok:!0,frame:r}}if(!i.declaredEvents.has(r.event))return{ok:!1,error:`Channel "${r.channel}" did not declare event "${r.event}"`};let a=i.eventHandlers.get(r.event);if(a)for(let e of[...a])e(r.payload,r);return{ok:!0,frame:r}}broadcast(e){for(let t of[...this.sinks])t(e)}static assertOpen(e){if(!e.open)throw Error(`Channel "${e.descriptor.name}" is closed`)}createHandle(n,r){return{descriptor:n,sendEvent:(i,a)=>{if(t.assertOpen(r),!r.declaredEvents.has(i))throw Error(`Channel "${n.name}" did not declare event "${i}"`);let o=r.seq;r.seq+=1,this.broadcast((0,e.encodeChannelEventFrame)({kind:`event`,channel:n.name,seq:o,event:i,payload:a}))},sendBinary:i=>{if(t.assertOpen(r),n.binary!==!0)throw Error(`Channel "${n.name}" did not declare binary payload support`);let a=r.seq;r.seq+=1,this.broadcast((0,e.encodeBinaryFrame)({kind:`binary`,channel:n.name,seq:a,payload:i}))},onEvent:(e,i)=>{if(t.assertOpen(r),!r.declaredEvents.has(e))throw Error(`Channel "${n.name}" did not declare event "${e}"`);let a=r.eventHandlers.get(e)??new Set,o=i;return a.add(o),r.eventHandlers.set(e,a),()=>{a.delete(o)}},onBinary:e=>(t.assertOpen(r),r.binaryHandlers.add(e),()=>{r.binaryHandlers.delete(e)}),close:()=>{r.open=!1,r.eventHandlers.clear(),r.binaryHandlers.clear(),this.channels.delete(n.name)}}}};const s=new Set([`localhost`,`127.0.0.1`,`::1`,`[::1]`]);function c(e){if(!e)return null;if(e.startsWith(`[`))return e.slice(0,e.indexOf(`]`)+1)||null;let t=e.lastIndexOf(`:`);return t===-1?e:e.slice(0,t)}function l(e,t){let n=c(e.headers.host);return n===null?!1:s.has(n)||t.has(n)}function u(e,t){let n=e.headers.origin;if(n===void 0||t.has(n))return!0;try{return s.has(new URL(n).hostname)}catch{return!1}}function d(e,t){if(!t)return!1;let n=Buffer.from(e),i=Buffer.from(t);return n.length===i.length&&(0,r.timingSafeEqual)(n,i)}function f(e){try{let t=new URL(e.url??``,`ws://127.0.0.1`).searchParams.get(`token`);if(t)return t}catch{}let t=e.headers[`sec-websocket-protocol`];return typeof t==`string`&&t.split(`,`)[0]?.trim()||null}function p(e){return(0,i.resolveAdmission)({...e.token===void 0?{}:{token:e.token},...e.open===!0?{open:!0}:{},...e.openReason===void 0?{}:{openReason:e.openReason}})}function m(e){return Array.isArray(e)?new Uint8Array(Buffer.concat(e)):e instanceof ArrayBuffer?new Uint8Array(e):new Uint8Array(e.buffer,e.byteOffset,e.byteLength)}var h=class{socket;cleanupProtocol=()=>void 0;detachSink=()=>void 0;closed=!1;stallClock=(0,e.createPendingStallClock)();deliver;constructor(t){this.socket=t,this.deliver=(0,e.createOutboundDelivery)(e=>this.rawSend(e),()=>this.close(),()=>this.socket.bufferedAmount,e.DEFAULT_MAX_PENDING_BYTES,this.stallClock)}deliverBinary=t=>{if(!this.closed&&this.socket.readyState===n.WebSocket.OPEN){if((0,e.isOverPendingBudget)(this.socket.bufferedAmount)||this.stallClock.observe(this.socket.bufferedAmount)!==void 0){this.close();return}this.socket.send(t,{binary:!0},e=>{e&&this.close()})}};rawSend(e){if(this.socket.readyState!==n.WebSocket.OPEN)throw Error(`WebSocket is not open`);this.socket.send(JSON.stringify(e),e=>{e&&this.close()})}bindProtocolCleanup(e){this.cleanupProtocol=e}bindSinkDetach(e){this.detachSink=e}close=()=>{this.closed||(this.closed=!0,this.detachSink(),this.cleanupProtocol(),(this.socket.readyState===n.WebSocket.OPEN||this.socket.readyState===n.WebSocket.CONNECTING)&&this.socket.close(1011,`session event delivery failed`))}};function g(e){return{...e.personalUsageReporter?{personalUsageReporter:e.personalUsageReporter}:{},...e.usageReporter?{usageReporter:e.usageReporter}:{},...e.storedSessionUsageReporter?{storedSessionUsageReporter:e.storedSessionUsageReporter}:{}}}function _(e){return{...e.driverId?{driverId:e.driverId}:{},...e.surface?{surface:e.surface}:{},...g(e),...e.sessionDirectory?{sessionDirectory:e.sessionDirectory}:{},...e.settingsReporter?{settingsReporter:e.settingsReporter}:{}}}function v(e){let{port:t,maxRetries:n}=e;return t!==void 0&&(typeof t!=`number`||t<1||t>65535)?!1:n===void 0||typeof n==`number`&&n>=0}function y(e,t){return Object.assign(Error(`${e} ${t}.`),{name:`TransportLifecycleError`,code:t,transportName:e})}var b=class{name=`ws`;lifecycle=Object.freeze({kind:`service`});defaultEnabled=!0;optionsSchema={port:{type:`number`,description:`WebSocket server port`,default:7070},maxRetries:{type:`number`,description:`Port retry attempts when port is occupied`,default:20}};session=null;stopFn=null;state=`detached`;startOperation;startCancelled=!1;port;maxRetries;token;allowedHosts;allowedOrigins;handlerOptions;sessionBinder;channels=new o;resolvedPort;constructor(e={}){this.port=e.port??7070,this.maxRetries=e.maxRetries??20;let t=p(e);t.token!==null&&(this.token=t.token),this.allowedHosts=new Set(e.allowedHosts??[]),this.allowedOrigins=new Set(e.allowedOrigins??[]),this.handlerOptions=_(e),this.sessionBinder=e.sessionBinder}attach(e){this.session=e,this.state=`attached`}registerChannel(e){return this.channels.registerChannel(e)}get boundPort(){return this.resolvedPort}get resolvedToken(){return this.token}async start(){if(!this.session)throw y(this.name,`not-attached`);if(this.state===`starting`||this.state===`ready`||this.state===`stopping`)throw y(this.name,`already-started`);this.state=`starting`,this.startCancelled=!1;let e=this.bindWithRetry(this.session,this.port,this.maxRetries);this.startOperation=e;let t;try{t=await e}catch(t){throw this.state===`starting`&&this.startOperation===e&&(this.startOperation=void 0,this.state=this.session?`attached`:`detached`),t}if(this.startCancelled||this.startOperation!==e)throw await t.stop(),this.state=this.session?`attached`:`detached`,Error(`WsTransport startup was stopped.`);this.stopFn=t.stop,this.resolvedPort=t.port,this.startOperation=void 0,this.state=`ready`}async stop(){if(this.state===`starting`){this.state=`stopping`,this.startCancelled=!0;try{await this.startOperation}catch{}}await this.stopFn?.(),this.stopFn=null,this.startOperation=void 0,this.resolvedPort=void 0,this.session=null,this.state=`detached`}configure(e){if(this.state!==`detached`&&this.state!==`attached`)throw y(this.name,`already-started`);if(!this.validateOptions(e))throw TypeError(`WsTransport options are invalid (port 1-65535, maxRetries >= 0).`);typeof e.port==`number`&&(this.port=e.port),typeof e.maxRetries==`number`&&(this.maxRetries=e.maxRetries)}validateOptions(e){return v(e)}bindConnection(e){if(!this.sessionBinder)return{binding:void 0};try{return{binding:this.sessionBinder.bind(`drive`)}}catch{return e.close(1013,`session unavailable`),null}}bindWithRetry(e,t,n){return this.tryBind(e,t).catch(r=>{if(r.code===`EADDRINUSE`&&n>0)return this.bindWithRetry(e,t+1,n-1);throw r})}tryBind(r,i){return new Promise((a,o)=>{let s=(0,t.createServer)((e,t)=>{t.writeHead(400).end(`WebSocket endpoint`)});s.on(`error`,e=>{s.close(),o(e)});let c=this.token,p=this.allowedHosts,g=this.allowedOrigins,_=this.channels;s.listen(i,`127.0.0.1`,()=>{let t=new n.WebSocketServer({server:s,verifyClient:(e,t)=>{if(!l(e.req,p)){t(!1,403,`Forbidden host`);return}if(!u(e.req,g)){t(!1,403,`Forbidden origin`);return}t(!0)}});t.on(`connection`,(t,n)=>{if(c!==void 0&&!d(c,f(n))){t.close(1008,`unauthorized`);return}let i=this.bindConnection(t);if(i===null)return;let{binding:a}=i,o=a?.session??r,s=new h(t),l=(0,e.createSessionMessageHandler)({session:o,deliver:s.deliver,...this.handlerOptions,...a?{sessionDirectory:a.directory}:{}});s.bindProtocolCleanup(()=>{l.cleanup(),a?.release()}),s.bindSinkDetach(_.addSink(e=>s.deliverBinary(e))),t.on(`message`,(e,t)=>{if(!t){l.onMessage(String(e));return}let n=_.receive(m(e));n.ok||s.deliver({type:`protocol_error`,message:n.error})}),t.on(`close`,s.close),t.on(`error`,s.close),s.deliver({type:`messages`,messages:o.getMessages(),...this.handlerOptions.driverId?{driverId:this.handlerOptions.driverId}:{}}),s.deliver({type:`execution_workspace_event`,snapshot:o.getExecutionWorkspaceSnapshot()})}),a({port:i,stop:()=>new Promise(e=>{for(let e of t.clients)e.close(1001,`server shutting down`);let n=setTimeout(()=>{for(let e of t.clients)e.terminate()},5e3);t.close(()=>{clearTimeout(n),s.close(()=>e())})})})})})}};exports.PayloadChannelRegistry=o,exports.WsTransport=b,exports.createWsTransport=a;

package/dist/node/index.d.cts

@@ -0,0 +1,180 @@
+import { TUsageSurface } from "@robota-sdk/agent-interface-analytics";
+import { ISessionBinder, TDriverId } from "@robota-sdk/agent-interface-session";
+import { IChannelDescriptor, IConfigurableTransport, IPayloadChannel, IPayloadChannelHost, ITransportAdapter, TChannelEventMap, TChannelReceiveResult } from "@robota-sdk/agent-interface-transport";
+import { IProtocolSession, ISessionMessageHandlerOptions, TServerMessage } from "@robota-sdk/agent-transport";
+import { TUniversalValue } from "@robota-sdk/agent-core";
+//#region src/ws-transport.d.ts
+interface IWsTransportOptions {
+  /** Send a JSON message to the connected WebSocket client. */
+  send: (message: TServerMessage) => void;
+  /** Owning socket lifecycle callback for outbound session-event delivery failures. */
+  onDeliveryError?: (error: Error, event: string) => void;
+  personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
+  driverId?: TDriverId;
+  surface?: TUsageSurface;
+}
+interface IWsTransport extends ITransportAdapter<IProtocolSession> {
+  onMessage: ((data: string) => void) | null;
+}
+declare function createWsTransport(options: IWsTransportOptions): IWsTransport;
+//#endregion
+//#region src/ws-transport-config.d.ts
+interface IWsTransportConfig {
+  /** Trusted server-assigned identity for turns submitted over this product surface. */
+  driverId?: TDriverId;
+  /** Trusted product surface, independent from the connection's driver identity. */
+  surface?: TUsageSurface;
+  /** Host-owned cross-session usage read model, forwarded unchanged to the protocol handler. */
+  personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  /** Host-owned current-session trace/cost producer, forwarded unchanged to the protocol handler. */
+  usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  /** Host-owned stored-session trace/cost producer for personal-usage drill-down. */
+  storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  /** Host-owned session directory (#3189): lets every connection list, start and switch sessions. */
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  /** #3282 §4a: host-owned read/write for the GUI Settings screen, forwarded unchanged. */
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
+  /**
+   * #3189: gives each connection a binding of its own — its own session and its own directory view —
+   * so one connection's switch moves only that connection. Released when the connection closes. When
+   * set, a connection uses its binding's session and directory instead of the attached session and
+   * `sessionDirectory`; without it every connection shares the attached session.
+   */
+  sessionBinder?: ISessionBinder<IProtocolSession>;
+  port?: number;
+  maxRetries?: number;
+  /**
+   * OPTIONAL explicit loopback auth token. When set, every connection MUST present a matching token
+   * (query param `?token=` or the `Sec-WebSocket-Protocol` subprotocol) or the socket is closed BEFORE any
+   * session data is emitted (GUI-002; the host sidecar supplies its configured token). SEC-001: when this is unset
+   * AND `open` is not `true`, the transport AUTO-MINTS a random per-launch token (secure by default) —
+   * `resolvedToken` exposes it so the surface can deliver it to the co-located client (a `0600` connection
+   * file / the served monitor's injected `ws-url`). An explicit token here wins over the auto-mint — but NOT
+   * over `open`: SEC-008 makes a token together with `open: true` a contradiction that throws, rather
+   * than a precedence one side quietly wins.
+   */
+  token?: string;
+  /**
+   * SEC-001 discouraged opt-out: when `true`, run WITHOUT auth (no token, no auto-mint) — the pre-SEC-001
+   * open loopback behavior. NOT RECOMMENDED (any local process or browser page can then drive+authorize the
+   * session); mirrors Jupyter's `c.ServerApp.token = ''`.
+   *
+   * SEC-008: `open: true` together with a non-empty `token` is REJECTED, not resolved by precedence. The
+   * two ask for opposite things, and picking a winner silently is how a caller ends up with the admission
+   * it did not choose. `resolveAdmission` decides that for every transport, so they cannot differ.
+   */
+  open?: boolean;
+  /** SEC-008: why running with no credential is correct here. Required when `open` is true. */
+  openReason?: string;
+  /**
+   * SEC-001 defense-in-depth: extra host names (beyond `localhost`/`127.0.0.1`/`::1`) accepted in the
+   * upgrade `Host` header. The `Host` allow-list closes DNS-rebinding independently of the token.
+   */
+  allowedHosts?: readonly string[];
+  /**
+   * SEC-001 defense-in-depth: extra browser `Origin`s (beyond loopback) accepted on the upgrade — e.g. the
+   * `apps/agent-web` app origin. A browser sends an unforgeable `Origin`; a non-browser client omits it (and
+   * is gated by the token instead). Closes the "any web page in any browser" hole before history is emitted.
+   */
+  allowedOrigins?: readonly string[];
+}
+//#endregion
+//#region src/ws-transport-configurable.d.ts
+/**
+ * TRANS-001: the WS transport is a payload-agnostic CARRIER that routes by WebSocket frame opcode —
+ * TEXT frames go to the text-agent protocol profile (`createSessionMessageHandler`), BINARY frames go to the
+ * consumer-declared channels. The two profiles share one connection and never constrain each other.
+ */
+declare class WsTransport implements IConfigurableTransport<IProtocolSession>, IPayloadChannelHost {
+  readonly name = "ws";
+  readonly lifecycle: Readonly<{
+    kind: "service";
+  }>;
+  readonly defaultEnabled = true;
+  readonly optionsSchema: {
+    port: {
+      type: string;
+      description: string;
+      default: number;
+    };
+    maxRetries: {
+      type: string;
+      description: string;
+      default: number;
+    };
+  };
+  private session;
+  private stopFn;
+  private state;
+  private startOperation;
+  private startCancelled;
+  private port;
+  private maxRetries;
+  private readonly token?;
+  private readonly allowedHosts;
+  private readonly allowedOrigins;
+  private readonly handlerOptions;
+  private readonly sessionBinder;
+  private readonly channels;
+  private resolvedPort?;
+  constructor(config?: IWsTransportConfig);
+  attach(session: IProtocolSession): void;
+  /**
+   * TRANS-001: declare an app-level channel carried on this transport's connections. The channel's
+   * events and opaque binary frames ride alongside the text-agent protocol on the SAME socket — the
+   * transport never inspects the payloads. Register before or after `start()`; a channel opened
+   * later is served by every already-connected client.
+   */
+  registerChannel<TEvents extends TChannelEventMap>(descriptor: IChannelDescriptor<TEvents>): IPayloadChannel<TEvents>;
+  /** Actually-bound port after start; undefined before start. */
+  get boundPort(): number | undefined;
+  /**
+   * SEC-001: the resolved auth token (explicit or auto-minted), or `undefined` in the discouraged `open`
+   * mode. The surface reads this to deliver the token to the co-located client (a `0600` connection file /
+   * the served monitor's injected `ws-url`). Never logged by the transport itself.
+   */
+  get resolvedToken(): string | undefined;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /** TRANS-002 (issue #2480): persisted `port`/`maxRetries` reach the server through here, before start. */
+  configure(options: Record<string, TUniversalValue>): void;
+  validateOptions(options: Record<string, TUniversalValue>): boolean;
+  /**
+   * The connection's binding, `{ binding: undefined }` without a binder, or `null` when the host
+   * would not bind it (shutting down, say): the socket is then closed before any session data.
+   */
+  private bindConnection;
+  private bindWithRetry;
+  private tryBind;
+}
+//#endregion
+//#region src/payload-channels.d.ts
+/** Delivers an encoded frame to one attached connection. */
+type TChannelSink = (frame: Uint8Array) => void;
+declare class PayloadChannelRegistry implements IPayloadChannelHost {
+  private readonly channels;
+  private readonly sinks;
+  /**
+   * Attach a connection. Every frame a channel sends is fanned out to all attached sinks; the
+   * returned function detaches (call it on socket close).
+   */
+  addSink(sink: TChannelSink): () => void;
+  registerChannel<TEvents extends TChannelEventMap>(descriptor: IChannelDescriptor<TEvents>): IPayloadChannel<TEvents>;
+  /**
+   * Route one inbound encoded frame to its channel's handlers. The result states exactly what
+   * happened so the carrier can answer the peer (a `protocol_error`) instead of dropping it.
+   */
+  receive(bytes: Uint8Array): TChannelReceiveResult;
+  /** Fan one encoded frame out to every attached connection. */
+  private broadcast;
+  /** Assert the channel is still open before any send/subscribe. */
+  private static assertOpen;
+  private createHandle;
+}
+//#endregion
+export { type IWsTransport, type IWsTransportConfig, type IWsTransportOptions, PayloadChannelRegistry, type TChannelSink, WsTransport, createWsTransport };
+//# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/ws-transport.ts","../../src/ws-transport-config.ts","../../src/ws-transport-configurable.ts","../../src/payload-channels.ts"],"mappings":";;;;;;UAqBiB;;EAEf,OAAO,SAAS;;EAEhB,mBAAmB,OAAO,OAAO;EACjC,wBAAwB;EACxB,gBAAgB;EAChB,6BAA6B;EAC7B,mBAAmB;EACnB,mBAAmB;EACnB,WAAW;EACX,UAAU;;UAGK,qBAAqB,kBAAkB;EACtD,aAAa;;iBAGC,kBAAkB,SAAS,sBAAsB;;;UCtBhD;;EAEf,WAAW;;EAEX,UAAU;;EAEV,wBAAwB;;EAExB,gBAAgB;;EAEhB,6BAA6B;;EAE7B,mBAAmB;;EAEnB,mBAAmB;;;;;;;EAOnB,gBAAgB,eAAe;EAC/B;EACA;;;;;;;;;;;EAWA;;;;;;;;;;EAUA;;EAEA;;;;;EAKA;;;;;;EAMA;;;;;;;;;cCpBW,uBAAuB,uBAAuB,mBAAmB;WACnE;WACA,WAAS;;;WACT;WACA;;;;;;;;;;;;UASD;UACA;UACA;UACA;UACA;UACA;UACA;mBACS;mBACA;mBACA;mBACA;mBACA;mBACA;UACT;EAEI,YAAA,SAAQ;EAapB,OAAO,SAAS;;;;;;;EAWhB,gBAAgB,gBAAgB,kBAC9B,YAAY,mBAAmB,WAC9B,gBAAgB;;MAKf;;;;;;MASA;EAIE,SAAS;EA8BT,QAAQ;;EAmBd,UAAU,SAAS,eAAe;EAWlC,gBAAgB,SAAS,eAAe;;;;;UAQhC;UAYA;UAYA;;;;;KC3LE,gBAAgB,OAAO;cAqBtB,kCAAkC;mBAC5B;mBACA;;;;;EAMjB,QAAQ,MAAM;EAOd,gBAAgB,gBAAgB,kBAC9B,YAAY,mBAAmB,WAC9B,gBAAgB;;;;;EAoBnB,QAAQ,OAAO,aAAa;;UAmCpB;;iBAKO;UAIP"}

package/dist/node/index.d.ts

@@ -0,0 +1,180 @@
+import { IProtocolSession, ISessionMessageHandlerOptions, TServerMessage } from "@robota-sdk/agent-transport";
+import { TUsageSurface } from "@robota-sdk/agent-interface-analytics";
+import { ISessionBinder, TDriverId } from "@robota-sdk/agent-interface-session";
+import { IChannelDescriptor, IConfigurableTransport, IPayloadChannel, IPayloadChannelHost, ITransportAdapter, TChannelEventMap, TChannelReceiveResult } from "@robota-sdk/agent-interface-transport";
+import { TUniversalValue } from "@robota-sdk/agent-core";
+//#region src/ws-transport.d.ts
+interface IWsTransportOptions {
+  /** Send a JSON message to the connected WebSocket client. */
+  send: (message: TServerMessage) => void;
+  /** Owning socket lifecycle callback for outbound session-event delivery failures. */
+  onDeliveryError?: (error: Error, event: string) => void;
+  personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
+  driverId?: TDriverId;
+  surface?: TUsageSurface;
+}
+interface IWsTransport extends ITransportAdapter<IProtocolSession> {
+  onMessage: ((data: string) => void) | null;
+}
+declare function createWsTransport(options: IWsTransportOptions): IWsTransport;
+//#endregion
+//#region src/ws-transport-config.d.ts
+interface IWsTransportConfig {
+  /** Trusted server-assigned identity for turns submitted over this product surface. */
+  driverId?: TDriverId;
+  /** Trusted product surface, independent from the connection's driver identity. */
+  surface?: TUsageSurface;
+  /** Host-owned cross-session usage read model, forwarded unchanged to the protocol handler. */
+  personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
+  /** Host-owned current-session trace/cost producer, forwarded unchanged to the protocol handler. */
+  usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
+  /** Host-owned stored-session trace/cost producer for personal-usage drill-down. */
+  storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  /** Host-owned session directory (#3189): lets every connection list, start and switch sessions. */
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  /** #3282 §4a: host-owned read/write for the GUI Settings screen, forwarded unchanged. */
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
+  /**
+   * #3189: gives each connection a binding of its own — its own session and its own directory view —
+   * so one connection's switch moves only that connection. Released when the connection closes. When
+   * set, a connection uses its binding's session and directory instead of the attached session and
+   * `sessionDirectory`; without it every connection shares the attached session.
+   */
+  sessionBinder?: ISessionBinder<IProtocolSession>;
+  port?: number;
+  maxRetries?: number;
+  /**
+   * OPTIONAL explicit loopback auth token. When set, every connection MUST present a matching token
+   * (query param `?token=` or the `Sec-WebSocket-Protocol` subprotocol) or the socket is closed BEFORE any
+   * session data is emitted (GUI-002; the host sidecar supplies its configured token). SEC-001: when this is unset
+   * AND `open` is not `true`, the transport AUTO-MINTS a random per-launch token (secure by default) —
+   * `resolvedToken` exposes it so the surface can deliver it to the co-located client (a `0600` connection
+   * file / the served monitor's injected `ws-url`). An explicit token here wins over the auto-mint — but NOT
+   * over `open`: SEC-008 makes a token together with `open: true` a contradiction that throws, rather
+   * than a precedence one side quietly wins.
+   */
+  token?: string;
+  /**
+   * SEC-001 discouraged opt-out: when `true`, run WITHOUT auth (no token, no auto-mint) — the pre-SEC-001
+   * open loopback behavior. NOT RECOMMENDED (any local process or browser page can then drive+authorize the
+   * session); mirrors Jupyter's `c.ServerApp.token = ''`.
+   *
+   * SEC-008: `open: true` together with a non-empty `token` is REJECTED, not resolved by precedence. The
+   * two ask for opposite things, and picking a winner silently is how a caller ends up with the admission
+   * it did not choose. `resolveAdmission` decides that for every transport, so they cannot differ.
+   */
+  open?: boolean;
+  /** SEC-008: why running with no credential is correct here. Required when `open` is true. */
+  openReason?: string;
+  /**
+   * SEC-001 defense-in-depth: extra host names (beyond `localhost`/`127.0.0.1`/`::1`) accepted in the
+   * upgrade `Host` header. The `Host` allow-list closes DNS-rebinding independently of the token.
+   */
+  allowedHosts?: readonly string[];
+  /**
+   * SEC-001 defense-in-depth: extra browser `Origin`s (beyond loopback) accepted on the upgrade — e.g. the
+   * `apps/agent-web` app origin. A browser sends an unforgeable `Origin`; a non-browser client omits it (and
+   * is gated by the token instead). Closes the "any web page in any browser" hole before history is emitted.
+   */
+  allowedOrigins?: readonly string[];
+}
+//#endregion
+//#region src/ws-transport-configurable.d.ts
+/**
+ * TRANS-001: the WS transport is a payload-agnostic CARRIER that routes by WebSocket frame opcode —
+ * TEXT frames go to the text-agent protocol profile (`createSessionMessageHandler`), BINARY frames go to the
+ * consumer-declared channels. The two profiles share one connection and never constrain each other.
+ */
+declare class WsTransport implements IConfigurableTransport<IProtocolSession>, IPayloadChannelHost {
+  readonly name = "ws";
+  readonly lifecycle: Readonly<{
+    kind: "service";
+  }>;
+  readonly defaultEnabled = true;
+  readonly optionsSchema: {
+    port: {
+      type: string;
+      description: string;
+      default: number;
+    };
+    maxRetries: {
+      type: string;
+      description: string;
+      default: number;
+    };
+  };
+  private session;
+  private stopFn;
+  private state;
+  private startOperation;
+  private startCancelled;
+  private port;
+  private maxRetries;
+  private readonly token?;
+  private readonly allowedHosts;
+  private readonly allowedOrigins;
+  private readonly handlerOptions;
+  private readonly sessionBinder;
+  private readonly channels;
+  private resolvedPort?;
+  constructor(config?: IWsTransportConfig);
+  attach(session: IProtocolSession): void;
+  /**
+   * TRANS-001: declare an app-level channel carried on this transport's connections. The channel's
+   * events and opaque binary frames ride alongside the text-agent protocol on the SAME socket — the
+   * transport never inspects the payloads. Register before or after `start()`; a channel opened
+   * later is served by every already-connected client.
+   */
+  registerChannel<TEvents extends TChannelEventMap>(descriptor: IChannelDescriptor<TEvents>): IPayloadChannel<TEvents>;
+  /** Actually-bound port after start; undefined before start. */
+  get boundPort(): number | undefined;
+  /**
+   * SEC-001: the resolved auth token (explicit or auto-minted), or `undefined` in the discouraged `open`
+   * mode. The surface reads this to deliver the token to the co-located client (a `0600` connection file /
+   * the served monitor's injected `ws-url`). Never logged by the transport itself.
+   */
+  get resolvedToken(): string | undefined;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /** TRANS-002 (issue #2480): persisted `port`/`maxRetries` reach the server through here, before start. */
+  configure(options: Record<string, TUniversalValue>): void;
+  validateOptions(options: Record<string, TUniversalValue>): boolean;
+  /**
+   * The connection's binding, `{ binding: undefined }` without a binder, or `null` when the host
+   * would not bind it (shutting down, say): the socket is then closed before any session data.
+   */
+  private bindConnection;
+  private bindWithRetry;
+  private tryBind;
+}
+//#endregion
+//#region src/payload-channels.d.ts
+/** Delivers an encoded frame to one attached connection. */
+type TChannelSink = (frame: Uint8Array) => void;
+declare class PayloadChannelRegistry implements IPayloadChannelHost {
+  private readonly channels;
+  private readonly sinks;
+  /**
+   * Attach a connection. Every frame a channel sends is fanned out to all attached sinks; the
+   * returned function detaches (call it on socket close).
+   */
+  addSink(sink: TChannelSink): () => void;
+  registerChannel<TEvents extends TChannelEventMap>(descriptor: IChannelDescriptor<TEvents>): IPayloadChannel<TEvents>;
+  /**
+   * Route one inbound encoded frame to its channel's handlers. The result states exactly what
+   * happened so the carrier can answer the peer (a `protocol_error`) instead of dropping it.
+   */
+  receive(bytes: Uint8Array): TChannelReceiveResult;
+  /** Fan one encoded frame out to every attached connection. */
+  private broadcast;
+  /** Assert the channel is still open before any send/subscribe. */
+  private static assertOpen;
+  private createHandle;
+}
+//#endregion
+export { type IWsTransport, type IWsTransportConfig, type IWsTransportOptions, PayloadChannelRegistry, type TChannelSink, WsTransport, createWsTransport };
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/ws-transport.ts","../../src/ws-transport-config.ts","../../src/ws-transport-configurable.ts","../../src/payload-channels.ts"],"mappings":";;;;;;UAqBiB;;EAEf,OAAO,SAAS;;EAEhB,mBAAmB,OAAO,OAAO;EACjC,wBAAwB;EACxB,gBAAgB;EAChB,6BAA6B;EAC7B,mBAAmB;EACnB,mBAAmB;EACnB,WAAW;EACX,UAAU;;UAGK,qBAAqB,kBAAkB;EACtD,aAAa;;iBAGC,kBAAkB,SAAS,sBAAsB;;;UCtBhD;;EAEf,WAAW;;EAEX,UAAU;;EAEV,wBAAwB;;EAExB,gBAAgB;;EAEhB,6BAA6B;;EAE7B,mBAAmB;;EAEnB,mBAAmB;;;;;;;EAOnB,gBAAgB,eAAe;EAC/B;EACA;;;;;;;;;;;EAWA;;;;;;;;;;EAUA;;EAEA;;;;;EAKA;;;;;;EAMA;;;;;;;;;cCpBW,uBAAuB,uBAAuB,mBAAmB;WACnE;WACA,WAAS;;;WACT;WACA;;;;;;;;;;;;UASD;UACA;UACA;UACA;UACA;UACA;UACA;mBACS;mBACA;mBACA;mBACA;mBACA;mBACA;UACT;EAEI,YAAA,SAAQ;EAapB,OAAO,SAAS;;;;;;;EAWhB,gBAAgB,gBAAgB,kBAC9B,YAAY,mBAAmB,WAC9B,gBAAgB;;MAKf;;;;;;MASA;EAIE,SAAS;EA8BT,QAAQ;;EAmBd,UAAU,SAAS,eAAe;EAWlC,gBAAgB,SAAS,eAAe;;;;;UAQhC;UAYA;UAYA;;;;;KC3LE,gBAAgB,OAAO;cAqBtB,kCAAkC;mBAC5B;mBACA;;;;;EAMjB,QAAQ,MAAM;EAOd,gBAAgB,gBAAgB,kBAC9B,YAAY,mBAAmB,WAC9B,gBAAgB;;;;;EAoBnB,QAAQ,OAAO,aAAa;;UAmCpB;;iBAKO;UAIP"}

package/dist/node/index.js

@@ -0,0 +1,2 @@
+import{DEFAULT_MAX_PENDING_BYTES as e,createOutboundDelivery as t,createPendingStallClock as n,createSessionMessageHandler as r,decodeChannelFrame as i,encodeBinaryFrame as a,encodeChannelEventFrame as o,isOverPendingBudget as s}from"@robota-sdk/agent-transport";import{createServer as c}from"node:http";import{WebSocket as l,WebSocketServer as u}from"ws";import{timingSafeEqual as d}from"node:crypto";import{resolveAdmission as f}from"@robota-sdk/agent-transport/node";function p(e){let n=null,i=null,a=e=>Object.assign(Error(`WebSocket transport ${e}.`),{name:`TransportLifecycleError`,code:e,transportName:`ws`}),o={name:`ws`,lifecycle:Object.freeze({kind:`service`}),onMessage:null,attach(e){n=e},async start(){if(!n)throw a(`not-attached`);if(i)throw a(`already-started`);let s=t(e.send,(t,n)=>{c.cleanup(),i=null,o.onMessage=null,e.onDeliveryError?.(t,n)}),c=r({session:n,deliver:s,...e.driverId?{driverId:e.driverId}:{},...e.surface?{surface:e.surface}:{},...e.personalUsageReporter?{personalUsageReporter:e.personalUsageReporter}:{},...e.usageReporter?{usageReporter:e.usageReporter}:{},...e.storedSessionUsageReporter?{storedSessionUsageReporter:e.storedSessionUsageReporter}:{},...e.sessionDirectory?{sessionDirectory:e.sessionDirectory}:{},...e.settingsReporter?{settingsReporter:e.settingsReporter}:{}});i=c.cleanup,this.onMessage=c.onMessage},async stop(){i?.(),i=null,this.onMessage=null,n=null}};return o}var m=class e{channels=new Map;sinks=new Set;addSink(e){return this.sinks.add(e),()=>{this.sinks.delete(e)}}registerChannel(e){if(this.channels.has(e.name))throw Error(`Channel "${e.name}" is already registered on this transport`);let t={descriptor:e,declaredEvents:new Set(e.events),eventHandlers:new Map,binaryHandlers:new Set,seq:0,open:!0};return this.channels.set(e.name,t),this.createHandle(e,t)}receive(e){let t=i(e);if(!t.ok)return t;let{frame:n}=t,r=this.channels.get(n.channel);if(!r||!r.open)return{ok:!1,error:`No channel registered for "${n.channel}"`};if(n.kind===`binary`){if(r.descriptor.binary!==!0)return{ok:!1,error:`Channel "${n.channel}" did not declare binary payload support`};for(let e of[...r.binaryHandlers])e(n);return{ok:!0,frame:n}}if(!r.declaredEvents.has(n.event))return{ok:!1,error:`Channel "${n.channel}" did not declare event "${n.event}"`};let a=r.eventHandlers.get(n.event);if(a)for(let e of[...a])e(n.payload,n);return{ok:!0,frame:n}}broadcast(e){for(let t of[...this.sinks])t(e)}static assertOpen(e){if(!e.open)throw Error(`Channel "${e.descriptor.name}" is closed`)}createHandle(t,n){return{descriptor:t,sendEvent:(r,i)=>{if(e.assertOpen(n),!n.declaredEvents.has(r))throw Error(`Channel "${t.name}" did not declare event "${r}"`);let a=n.seq;n.seq+=1,this.broadcast(o({kind:`event`,channel:t.name,seq:a,event:r,payload:i}))},sendBinary:r=>{if(e.assertOpen(n),t.binary!==!0)throw Error(`Channel "${t.name}" did not declare binary payload support`);let i=n.seq;n.seq+=1,this.broadcast(a({kind:`binary`,channel:t.name,seq:i,payload:r}))},onEvent:(r,i)=>{if(e.assertOpen(n),!n.declaredEvents.has(r))throw Error(`Channel "${t.name}" did not declare event "${r}"`);let a=n.eventHandlers.get(r)??new Set,o=i;return a.add(o),n.eventHandlers.set(r,a),()=>{a.delete(o)}},onBinary:t=>(e.assertOpen(n),n.binaryHandlers.add(t),()=>{n.binaryHandlers.delete(t)}),close:()=>{n.open=!1,n.eventHandlers.clear(),n.binaryHandlers.clear(),this.channels.delete(t.name)}}}};const h=new Set([`localhost`,`127.0.0.1`,`::1`,`[::1]`]);function g(e){if(!e)return null;if(e.startsWith(`[`))return e.slice(0,e.indexOf(`]`)+1)||null;let t=e.lastIndexOf(`:`);return t===-1?e:e.slice(0,t)}function _(e,t){let n=g(e.headers.host);return n===null?!1:h.has(n)||t.has(n)}function v(e,t){let n=e.headers.origin;if(n===void 0||t.has(n))return!0;try{return h.has(new URL(n).hostname)}catch{return!1}}function y(e,t){if(!t)return!1;let n=Buffer.from(e),r=Buffer.from(t);return n.length===r.length&&d(n,r)}function b(e){try{let t=new URL(e.url??``,`ws://127.0.0.1`).searchParams.get(`token`);if(t)return t}catch{}let t=e.headers[`sec-websocket-protocol`];return typeof t==`string`&&t.split(`,`)[0]?.trim()||null}function x(e){return f({...e.token===void 0?{}:{token:e.token},...e.open===!0?{open:!0}:{},...e.openReason===void 0?{}:{openReason:e.openReason}})}function S(e){return Array.isArray(e)?new Uint8Array(Buffer.concat(e)):e instanceof ArrayBuffer?new Uint8Array(e):new Uint8Array(e.buffer,e.byteOffset,e.byteLength)}var C=class{socket;cleanupProtocol=()=>void 0;detachSink=()=>void 0;closed=!1;stallClock=n();deliver;constructor(n){this.socket=n,this.deliver=t(e=>this.rawSend(e),()=>this.close(),()=>this.socket.bufferedAmount,e,this.stallClock)}deliverBinary=e=>{if(!this.closed&&this.socket.readyState===l.OPEN){if(s(this.socket.bufferedAmount)||this.stallClock.observe(this.socket.bufferedAmount)!==void 0){this.close();return}this.socket.send(e,{binary:!0},e=>{e&&this.close()})}};rawSend(e){if(this.socket.readyState!==l.OPEN)throw Error(`WebSocket is not open`);this.socket.send(JSON.stringify(e),e=>{e&&this.close()})}bindProtocolCleanup(e){this.cleanupProtocol=e}bindSinkDetach(e){this.detachSink=e}close=()=>{this.closed||(this.closed=!0,this.detachSink(),this.cleanupProtocol(),(this.socket.readyState===l.OPEN||this.socket.readyState===l.CONNECTING)&&this.socket.close(1011,`session event delivery failed`))}};function w(e){return{...e.personalUsageReporter?{personalUsageReporter:e.personalUsageReporter}:{},...e.usageReporter?{usageReporter:e.usageReporter}:{},...e.storedSessionUsageReporter?{storedSessionUsageReporter:e.storedSessionUsageReporter}:{}}}function T(e){return{...e.driverId?{driverId:e.driverId}:{},...e.surface?{surface:e.surface}:{},...w(e),...e.sessionDirectory?{sessionDirectory:e.sessionDirectory}:{},...e.settingsReporter?{settingsReporter:e.settingsReporter}:{}}}function E(e){let{port:t,maxRetries:n}=e;return t!==void 0&&(typeof t!=`number`||t<1||t>65535)?!1:n===void 0||typeof n==`number`&&n>=0}function D(e,t){return Object.assign(Error(`${e} ${t}.`),{name:`TransportLifecycleError`,code:t,transportName:e})}var O=class{name=`ws`;lifecycle=Object.freeze({kind:`service`});defaultEnabled=!0;optionsSchema={port:{type:`number`,description:`WebSocket server port`,default:7070},maxRetries:{type:`number`,description:`Port retry attempts when port is occupied`,default:20}};session=null;stopFn=null;state=`detached`;startOperation;startCancelled=!1;port;maxRetries;token;allowedHosts;allowedOrigins;handlerOptions;sessionBinder;channels=new m;resolvedPort;constructor(e={}){this.port=e.port??7070,this.maxRetries=e.maxRetries??20;let t=x(e);t.token!==null&&(this.token=t.token),this.allowedHosts=new Set(e.allowedHosts??[]),this.allowedOrigins=new Set(e.allowedOrigins??[]),this.handlerOptions=T(e),this.sessionBinder=e.sessionBinder}attach(e){this.session=e,this.state=`attached`}registerChannel(e){return this.channels.registerChannel(e)}get boundPort(){return this.resolvedPort}get resolvedToken(){return this.token}async start(){if(!this.session)throw D(this.name,`not-attached`);if(this.state===`starting`||this.state===`ready`||this.state===`stopping`)throw D(this.name,`already-started`);this.state=`starting`,this.startCancelled=!1;let e=this.bindWithRetry(this.session,this.port,this.maxRetries);this.startOperation=e;let t;try{t=await e}catch(t){throw this.state===`starting`&&this.startOperation===e&&(this.startOperation=void 0,this.state=this.session?`attached`:`detached`),t}if(this.startCancelled||this.startOperation!==e)throw await t.stop(),this.state=this.session?`attached`:`detached`,Error(`WsTransport startup was stopped.`);this.stopFn=t.stop,this.resolvedPort=t.port,this.startOperation=void 0,this.state=`ready`}async stop(){if(this.state===`starting`){this.state=`stopping`,this.startCancelled=!0;try{await this.startOperation}catch{}}await this.stopFn?.(),this.stopFn=null,this.startOperation=void 0,this.resolvedPort=void 0,this.session=null,this.state=`detached`}configure(e){if(this.state!==`detached`&&this.state!==`attached`)throw D(this.name,`already-started`);if(!this.validateOptions(e))throw TypeError(`WsTransport options are invalid (port 1-65535, maxRetries >= 0).`);typeof e.port==`number`&&(this.port=e.port),typeof e.maxRetries==`number`&&(this.maxRetries=e.maxRetries)}validateOptions(e){return E(e)}bindConnection(e){if(!this.sessionBinder)return{binding:void 0};try{return{binding:this.sessionBinder.bind(`drive`)}}catch{return e.close(1013,`session unavailable`),null}}bindWithRetry(e,t,n){return this.tryBind(e,t).catch(r=>{if(r.code===`EADDRINUSE`&&n>0)return this.bindWithRetry(e,t+1,n-1);throw r})}tryBind(e,t){return new Promise((n,i)=>{let a=c((e,t)=>{t.writeHead(400).end(`WebSocket endpoint`)});a.on(`error`,e=>{a.close(),i(e)});let o=this.token,s=this.allowedHosts,l=this.allowedOrigins,d=this.channels;a.listen(t,`127.0.0.1`,()=>{let i=new u({server:a,verifyClient:(e,t)=>{if(!_(e.req,s)){t(!1,403,`Forbidden host`);return}if(!v(e.req,l)){t(!1,403,`Forbidden origin`);return}t(!0)}});i.on(`connection`,(t,n)=>{if(o!==void 0&&!y(o,b(n))){t.close(1008,`unauthorized`);return}let i=this.bindConnection(t);if(i===null)return;let{binding:a}=i,s=a?.session??e,c=new C(t),l=r({session:s,deliver:c.deliver,...this.handlerOptions,...a?{sessionDirectory:a.directory}:{}});c.bindProtocolCleanup(()=>{l.cleanup(),a?.release()}),c.bindSinkDetach(d.addSink(e=>c.deliverBinary(e))),t.on(`message`,(e,t)=>{if(!t){l.onMessage(String(e));return}let n=d.receive(S(e));n.ok||c.deliver({type:`protocol_error`,message:n.error})}),t.on(`close`,c.close),t.on(`error`,c.close),c.deliver({type:`messages`,messages:s.getMessages(),...this.handlerOptions.driverId?{driverId:this.handlerOptions.driverId}:{}}),c.deliver({type:`execution_workspace_event`,snapshot:s.getExecutionWorkspaceSnapshot()})}),n({port:t,stop:()=>new Promise(e=>{for(let e of i.clients)e.close(1001,`server shutting down`);let t=setTimeout(()=>{for(let e of i.clients)e.terminate()},5e3);i.close(()=>{clearTimeout(t),a.close(()=>e())})})})})})}};export{m as PayloadChannelRegistry,O as WsTransport,p as createWsTransport};
+//# sourceMappingURL=index.js.map