@robota-sdk/agent-transport-ws 3.0.0-beta.82 → 3.0.0-beta.84

package/CHANGELOG.md

@@ -0,0 +1,384 @@
+# @robota-sdk/agent-transport-ws
+
+## 3.0.0-beta.84
+
+### Patch Changes
+
+- 9c6a8db: The wire protocol gained several request/reply pairs so a GUI never has to scrape command output for
+  data it can read directly.
+
+  `get-settings`/`update-settings` read and write the Settings screen; a patch applies through the same
+  function its matching slash command uses, so the two paths cannot drift. `list-models` returns the
+  configured models grouped by provider profile, with the current profile and model. `get-agent-definitions`
+  returns the agent switcher's roster and current selection. `project-status`, `project-diff` and
+  `project-memory` back the Project panel's git status, one file's diff, and project memory; a host
+  without this capability answers `protocol_error` instead of hanging. `rename-session` and
+  `delete-session` rename or remove a stored session from the list, current or not, each with its own
+  success/failure reply.
+
+  The `messages` frame gained an optional `display` field — the same history projected into display
+  segments (text runs and finished tool calls, diffs included) — and the connection's own `driverId`, so
+  a reload, reconnect or resume shows tool rows and tells a co-driver's turns from its own. The `error`
+  frame gained optional `code`, `provider`, `retryAfterSeconds` and `model` fields so a renderer can say
+  what kind of failure happened (`auth`, `rate_limit`, `model_unavailable`, `network`, `provider`) instead
+  of showing only raw text; a session error this classification does not recognize is unchanged.
+
+  `TCommandSurfaceLocality` names whether a `'remote'`-sourced command is provably on this machine. The
+  WebRTC/device-mesh transport now forwards `'remote'` for it (it proves no locality, the same rule
+  already applied to pairing), and both the WS and WebRTC transports forward it into the Settings
+  read/write path, so a command that refuses a remote surface (installing a plugin) refuses identically
+  regardless of which transport carried it.
+
+- Updated dependencies [9f46375]
+- Updated dependencies [e8d70ac]
+- Updated dependencies [9c6a8db]
+- Updated dependencies [9c6a8db]
+- Updated dependencies [9c6a8db]
+  - @robota-sdk/agent-core@3.0.0-beta.84
+  - @robota-sdk/agent-interface-session@3.0.0-beta.84
+  - @robota-sdk/agent-interface-analytics@3.0.0-beta.84
+  - @robota-sdk/agent-transport@3.0.0-beta.84
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.84
+
+## 3.0.0-beta.83
+
+### Minor Changes
+
+- 6ae3f28: A served runtime can list its workspace's sessions, start a new one and switch to another without the
+  process or any client connection restarting. The GUI shows them in a sessions sidebar.
+
+  - `agent-interface-session` is **`major`** for two reasons:
+    - It adds `ISessionListing`, `ISessionDirectory` and `ISessionSwitchedEvent`.
+    - `IInteractiveSessionEvents` gains a required `session_switched` event. An exhaustive map over the
+      event names stops compiling until it classifies the new event.
+  - `agent-transport` is **`major`** for the same kind of reason:
+    - It adds the wire messages `list-sessions` → `sessions`/`sessions_error`, `new-session`,
+      `switch-session`, and the broadcast `session_switched`.
+    - It adds a `sessionDirectory` handler option. A refusal to switch comes back as a
+      `protocol_error` carrying the reason.
+    - An exhaustive map over message types must add the new variants.
+  - `agent-transport-ws` passes a configured `sessionDirectory` to every connection.
+  - `agent-framework` is **`major` because `IRuntimeHostHandle.session` is now a `SessionSlot`**, not the
+    `InteractiveSession`, and `bindTransports` receives the slot.
+    - The slot is an `IInteractiveSession` that forwards to the current session. Members outside that
+      interface are read through `host.session.current`, which changes on a switch.
+    - Adds `InteractiveSession.whenInitialized()`.
+    - Exports `listUnreadableSessions`.
+  - `agent-ui-web` is **`major`**:
+    - `IWsSessionState` gains session listing state and actions.
+    - It adds a `SessionSidebar`.
+    - `/resume` opens the sidebar.
+  - `agent-cli`: `robota --serve` provides the session directory, and refuses a switch that would lose
+    work in progress. External-event grants belong to the run: a switch reopens them on the new session,
+    as the TUI already does.
+  - External-event grant history (spent tokens, rate windows, revocations) belongs to the run. The new
+    option `externalEventGrantHistory` (from `createExternalEventGrantHistory()`) is shared by every
+    session that a served runtime or the TUI builds. A session switch therefore replays no spent token
+    and resets no rate limit. The TUI previously had this gap when it switched sessions.
+
+- 57f57f5: A daemon keeps several sessions live, and each client is bound to its own: one client's switch moves
+  only that client.
+
+  - `agent-interface-session`: `ISessionBinder`/`ISessionBinding`, the session-change refusal codes with
+    `isSessionChangeRefusal`, and listing rows that may say `live` and `clients`.
+  - `agent-framework`: `SessionPool` and `SessionChangeRefusal`.
+  - `agent-transport` (**major**): a new server frame, `session_change_failed`, which an exhaustive
+    consumer must handle. A refused `new-session` or `switch-session` now answers with it, carrying a
+    `code`, instead of `protocol_error`; both requests take an optional `requestId` that it echoes.
+  - `agent-transport-ws`: the `sessionBinder` option binds each connection to its own session and
+    releases the binding when the connection closes.
+  - `agent-cli`: `robota --serve` and the daemon keep up to four sessions live. Each WebSocket client and
+    attached terminal is bound to its own session; leaving a busy session is no longer refused, and only
+    the last driver of a session with a pending prompt is kept from leaving it. Grants and the supervised
+    name stay on the runtime's first session, and its reported activity covers every live session.
+  - `agent-ui-web`: a refused new or switch shows the host's reason as a notice (an older host's
+    `protocol_error` still does); the session sidebar marks live sessions and counts the other clients
+    on each; after a reconnect to a host that keeps sessions live, the GUI returns to the session it was on.
+  - `agent-ui-terminal`: an attached terminal shows why a switch was refused, and the picker's switch
+    stays pending until the host answers; the session picker marks live sessions and their clients.
+
+### Patch Changes
+
+- 57280bf: Every published package now declares `"engines": { "node": ">=22.12.0" }`. Before, 27 of the 38
+  packages declared no floor (`agent-core`, `agent-tools` and every provider among them),
+  `agent-session` and `agent-file-authority` declared `>=20.19.0`, and the other nine declared
+  `>=22.0.0`, so a consumer on Node 20 saw at most a warning from a transitive dependency.
+
+  Why 22.12: `agent-cli` and `agent-ui-terminal` need Node 22 through `ink` 7, and the CommonJS entries
+  of `agent-tools` and its dependents, `agent-transport`/`node` and its dependents, and
+  `agent-ui-terminal` `require()` ESM-only dependencies (`p-limit`, `jose`, `chalk`), which Node 22
+  supports unflagged only from 22.12. `engines` is advisory unless the consumer enables `engine-strict`.
+
+  No code changes: `tsdown` now reads `node22.12.0` as its build target from the field.
+
+- 18c0d5c: Every published package now exports `./package.json`, so `require('<package>/package.json')` and
+  `import('<package>/package.json', { with: { type: 'json' } })` work instead of failing with
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`, and each tarball now ships the package's `CHANGELOG.md`.
+- Updated dependencies [3c81769]
+- Updated dependencies [724fabb]
+- Updated dependencies [d877de2]
+- Updated dependencies [d61e159]
+- Updated dependencies [bfe8ed5]
+- Updated dependencies [e689c8e]
+- Updated dependencies [7b72344]
+- Updated dependencies [6ae3f28]
+- Updated dependencies [be0e53c]
+- Updated dependencies [57f57f5]
+- Updated dependencies [ba822c1]
+- Updated dependencies [6e6b06b]
+- Updated dependencies [8bd5fac]
+- Updated dependencies [57280bf]
+- Updated dependencies [5033dd9]
+- Updated dependencies [18c0d5c]
+- Updated dependencies [dbd888d]
+- Updated dependencies [1887e54]
+  - @robota-sdk/agent-interface-analytics@3.0.0-beta.83
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.83
+  - @robota-sdk/agent-transport@3.0.0-beta.83
+  - @robota-sdk/agent-core@3.0.0-beta.83
+  - @robota-sdk/agent-interface-session@3.0.0-beta.83
+
+## 3.0.0-beta.82
+
+### Patch Changes
+
+- Updated dependencies [c7f9203]
+  - @robota-sdk/agent-transport@3.0.0-beta.82
+  - @robota-sdk/agent-core@3.0.0-beta.82
+  - @robota-sdk/agent-interface-session@3.0.0-beta.82
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.82
+  - @robota-sdk/agent-interface-analytics@3.0.0-beta.82
+
+## 3.0.0-beta.81
+
+### Patch Changes
+
+- Updated dependencies [3038eb7]
+- Updated dependencies [02b7452]
+- Updated dependencies [ec5e477]
+  - @robota-sdk/agent-core@3.0.0-beta.81
+  - @robota-sdk/agent-interface-session@3.0.0-beta.81
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.81
+  - @robota-sdk/agent-transport@3.0.0-beta.81
+  - @robota-sdk/agent-interface-analytics@3.0.0-beta.81
+
+## 3.0.0-beta.80
+
+### Major Changes
+
+- e82215f: **ARCH-011: replace the ambiguous transport lifecycle stub with executable conformance.**
+
+  `ITransportAdapter` now requires a frozen `service | runner` lifecycle descriptor. `start()` resolves
+  at the concrete transport's documented readiness boundary; start before attach and repeated active
+  start reject a stable lifecycle error, repeated stop is safe, and stopped adapters can reattach and
+  restart.
+
+  Runner adapters launch separately and expose a typed terminal outcome through
+  `waitForCompletion()`. The registry accepts base adapters, rejects duplicate names, keeps
+  configuration as an optional capability, returns complete ordered records whose pending slots become
+  registry-owned `abandoned` outcomes on stop/rollback, and exposes a real-runner-only first-failure
+  wait. It serializes startup/stop, rejects active restart before mutation, and reverses partial startup
+  from the currently failing adapter with typed safe rollback details. Runtime host and serve mode
+  propagate real nonzero runner results without treating normal shutdown abandonment as failure.
+
+  HTTP, MCP, both WebSocket adapters, WebRTC, and headless invoke one shared public conformance kit.
+  The former `TuiTransport` export is removed because it ignored the attached session; use `renderApp`
+  or `TuiInteractionChannel`, which honestly own their session lifecycle.
+
+### Minor Changes
+
+- 9db63ee: Add named session capability roles and explicit capability-host queries while preserving the legacy
+  `IInteractiveSession` interface shape. HTTP, MCP, protocol, WS, WebRTC, and headless transports now
+  declare only the session roles they consume, and the direct aggregate-cast floor is zero.
+- 2ebff01: Emit the complete persisted checkpoint and branch lifecycle, forward plan, context-refresh, and
+  branch events through protocol transports, and render deterministic bounded notices in the TUI.
+  Transport-owned delivery failures now enter the owning carrier cleanup lifecycle without reversing
+  an already-committed session operation.
+- 5c5ff23: TRANS-001: payload-agnostic transport — opaque binary frames + consumer-declared event types
+
+  The WS transport now carries **arbitrary payloads** alongside the text-agent protocol on one
+  connection, instead of forcing every app-level payload through the `text_delta`/`submit` wire
+  protocol.
+
+  - `agent-interface-transport` adds the channel contracts (`IBinaryFrame`, `IChannelEventFrame`,
+    `IChannelDescriptor`, `IPayloadChannel`, `IPayloadChannelHost`, `TChannelEventMap`,
+    `TChannelFrame`, `TChannelReceiveResult`). Content-neutral carrier mechanics — no payload domain.
+  - `agent-transport-protocol` adds the pure channel frame codec (`encodeBinaryFrame`,
+    `encodeChannelEventFrame`, `decodeChannelFrame`, `isChannelFrame`). `TClientMessage` /
+    `TServerMessage` are unchanged.
+  - `agent-transport-ws` becomes a carrier that routes by WebSocket frame opcode — TEXT to the
+    text-agent protocol profile, BINARY to consumer-declared channels — and `WsTransport` now
+    implements `IPayloadChannelHost` (`registerChannel`). `PayloadChannelRegistry` is exported.
+
+  Additive only: existing transports, consumers, and the agent wire protocol are untouched.
+
+### Patch Changes
+
+- 235da81: **BREAKING — ARCH-030: `createWsHandler` takes the carrier's delivery boundary, not a raw `send`.**
+
+  `createWsHandler` had two outbound semantics on one connection. The session-event fan-out went through
+  a guard that reported carrier failures through `onDeliveryError`; every reply to an inbound frame got
+  the raw `send`. Eleven reply families were unguarded — five resolving from a Promise continuation, so a
+  reply landing after a disconnect escaped as an **unhandled rejection** while the carrier's cleanup was
+  never notified, and six synchronous ones that threw into the carrier's inbound listener instead.
+
+  `IWsHandlerOptions` now takes a single `deliver: TOutboundDeliver` in place of `send` and
+  `onDeliveryError`. **The carrier builds the boundary** from its own sink and its own failure policy and
+  passes it down — not the reverse, because a protocol layer handed a raw sink so it can hand a wrapper
+  back leaves the raw sink reachable, which is how the twelfth reply family gets added unguarded.
+
+  ```ts
+  // before
+  const { onMessage, cleanup } = createWsHandler({
+    session,
+    send: (msg) => ws.send(JSON.stringify(msg)),
+    onDeliveryError: (error) => ws.close(1011, error.message),
+  });
+
+  // after
+  const deliver = createOutboundDelivery(
+    (msg) => ws.send(JSON.stringify(msg)),
+    (error) => ws.close(1011, error.message),
+  );
+  const { onMessage, cleanup } = createWsHandler({ session, deliver });
+  ```
+
+  `TOutboundDeliver` is branded and `createOutboundDelivery` is its only producer, so a plain
+  `(message: TServerMessage) => void` is refused by the compiler wherever a boundary is required.
+
+  **The boundary latches:** it reports at most one delivery failure per connection, after which frames are
+  dropped without a further report. All three carriers already treated a delivery failure as terminal and
+  each had grown its own latch; it belongs upstream of all three. `SessionResumeBridge` builds a fresh
+  boundary per `attach`, which is what un-latches the session after a reconnect, and buffers a frame
+  before the boundary so a dropped one still replays.
+
+  **`ISubscribeSessionEventsOptions` is no longer exported** from the package barrel. It is the options bag
+  of `subscribeSessionEvents`, which is package-internal, and it was already absent from the SPEC's public
+  API table. Its `onDeliveryError` member is gone regardless — carrier-failure containment is the
+  boundary's job now.
+
+  `agent-transport-ws` and `agent-transport-webrtc` are `patch`: `WsSessionDelivery` (whose raw `send` is
+  now private, with `deliver` the only public sink) and `PairingGate` are not on their packages' barrels,
+  and every barrel export of both packages keeps its signature.
+
+- 4f3c075: Assemble complete, verified package generations before switching build output; preserve the previous generation on build failure and pack only verified regular-file images. Include copied CLI web assets in affected-build ordering and artifact transfer. Preserve the CLI version in managed build paths. Public runtime contracts remain compatible (patch).
+- 94cc355: REMOTE-002 Stage A: extract the transport-neutral session bridge + wire protocol into a new
+  `@robota-sdk/agent-transport-protocol` package (`createWsHandler`, `TClientMessage`/`TServerMessage`); repoint
+  `agent-transport-ws` and `agent-web-ui` at it (no pass-through re-export). Add a new
+  `@robota-sdk/agent-transport-webrtc` package: a `WebRtcTransport` (`IConfigurableTransport`, `defaultEnabled:false`)
+  that carries an `IInteractiveSession` over an `RTCDataChannel` reusing the shared handler, with a lazily-loaded
+  optional `werift` peer dependency that throws an explicit "WebRTC transport unavailable" error on absence (never a
+  silent no-op). No user-facing enable path and no auth in Stage A (that lands in Stage B); the transport is proven
+  by an in-process loopback data-channel round-trip only.
+
+  (Bump target corrected during REL-023 triage: `@robota-sdk/agent-web-ui` was dissolved by GUI-006 (#1141, 2026-07-12) before this work was ever published; its protocol-consumer role now lives in `@robota-sdk/agent-transport-webrtc-web`.)
+
+- Updated dependencies [7b6234c]
+- Updated dependencies [37b4bd7]
+- Updated dependencies [4eea54b]
+- Updated dependencies [50d2c9f]
+- Updated dependencies [1698be4]
+- Updated dependencies [a5961c9]
+- Updated dependencies [d4189b9]
+- Updated dependencies [9edae52]
+- Updated dependencies [4078a72]
+- Updated dependencies [4c73a0b]
+- Updated dependencies [196a900]
+- Updated dependencies [f336838]
+- Updated dependencies [34e50f0]
+- Updated dependencies [722e88a]
+- Updated dependencies [d23c848]
+- Updated dependencies [4c5148e]
+- Updated dependencies [0116a29]
+- Updated dependencies [fec722f]
+- Updated dependencies [e82215f]
+- Updated dependencies [52b7346]
+- Updated dependencies [9db63ee]
+- Updated dependencies [b078afa]
+- Updated dependencies [2ebff01]
+- Updated dependencies [9db63ee]
+- Updated dependencies [2ebff01]
+- Updated dependencies [2d3b2c0]
+- Updated dependencies [4772067]
+- Updated dependencies [0f98419]
+- Updated dependencies [64ba748]
+- Updated dependencies [9fbab1b]
+- Updated dependencies [d312755]
+- Updated dependencies [a009f5b]
+- Updated dependencies [3244fb8]
+- Updated dependencies [1e3f91a]
+- Updated dependencies [4f3c075]
+- Updated dependencies [475e085]
+- Updated dependencies [e477440]
+- Updated dependencies [9dcb5da]
+- Updated dependencies [a95ca85]
+- Updated dependencies [b6d14ce]
+- Updated dependencies [0382a51]
+- Updated dependencies [93d061d]
+- Updated dependencies [39554a1]
+- Updated dependencies [d28430a]
+- Updated dependencies [7669851]
+- Updated dependencies [4b76cfa]
+- Updated dependencies [07b627f]
+- Updated dependencies [d0de5b2]
+- Updated dependencies [9665c6e]
+- Updated dependencies [44393be]
+- Updated dependencies [c7fa299]
+- Updated dependencies [5134b3b]
+- Updated dependencies [d6b9404]
+- Updated dependencies [5c5ff23]
+- Updated dependencies [9814afc]
+  - @robota-sdk/agent-core@3.0.0-beta.80
+  - @robota-sdk/agent-interface-session@3.0.0-beta.80
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.80
+  - @robota-sdk/agent-transport@3.0.0-beta.80
+  - @robota-sdk/agent-interface-analytics@3.0.0-beta.80
+
+## 3.0.0-beta.79
+
+### Patch Changes
+
+- @robota-sdk/agent-core@3.0.0-beta.79
+- @robota-sdk/agent-interface-transport@3.0.0-beta.79
+
+## 3.0.0-beta.78
+
+### Patch Changes
+
+- Updated dependencies [6f308d1]
+  - @robota-sdk/agent-core@3.0.0-beta.78
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.78
+
+## 3.0.0-beta.77
+
+### Patch Changes
+
+- Updated dependencies
+  - @robota-sdk/agent-core@3.0.0-beta.77
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.77
+
+## 3.0.0-beta.76
+
+### Minor Changes
+
+- 9df3a88: Split the consolidated `@robota-sdk/agent-transport` package into per-concern transport packages (DQ-AUDIT-005) so unrelated heavy dependencies (React/Ink, ws, Hono, MCP SDK) no longer share one publishable unit and are not dragged into non-TUI consumers' graphs:
+
+  - `@robota-sdk/agent-transport` — lean core: headless adapter + `TransportRegistry` + scripted-provider testing fixtures (no external runtime deps).
+  - `@robota-sdk/agent-transport-tui` — React + Ink terminal UI.
+  - `@robota-sdk/agent-transport-ws` — WebSocket transport + protocol (`agent-web-ui` now depends only on this for WS types).
+  - `@robota-sdk/agent-transport-http` — Hono HTTP transport.
+  - `@robota-sdk/agent-transport-mcp` — MCP server transport.
+
+  The default transport-registry wiring (pre-registering `WsTransport`) moves to the CLI composition root, removing the core→ws edge.
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [c0a6287]
+- Updated dependencies [9df3a88]
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies [576af62]
+  - @robota-sdk/agent-core@3.0.0-beta.76
+  - @robota-sdk/agent-framework@3.0.0-beta.76
+  - @robota-sdk/agent-interface-transport@3.0.0-beta.76

package/README.md

@@ -1,21 +1,85 @@
 # @robota-sdk/agent-transport-ws
 
-WebSocket carrier for the Robota SDK. The transport-neutral wire protocol, message types, and shared
-session handler belong to `@robota-sdk/agent-transport`; this package adapts them to WebSocket
-connections without pulling React, Ink, or Hono.
+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 { createSessionMessageHandler } from '@robota-sdk/agent-transport';
-import type { TServerMessage, TClientMessage } from '@robota-sdk/agent-transport';
+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();
 ```
 
-See [docs/SPEC.md](./docs/SPEC.md) for the full contract.
+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`.
 
-The carrier forwards plan, context-refresh, and branch events using the shared serializable event types.
-If a socket is not open or `send` fails asynchronously, the carrier runs one idempotent connection cleanup
-path and reports the delivery failure without throwing back through the committed session operation.
+## Related
 
-Hosts may inject personal, stored-session, and current-session usage reporters when constructing the
-transport. Each admitted connection receives those capabilities through the shared protocol handler;
-the WebSocket transport itself never reads session stores or performs analytics.
+- [`@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

@@ -1 +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}:{}});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)}}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;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)}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)}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=new h(t),a=(0,e.createSessionMessageHandler)({session:r,deliver:i.deliver,...this.handlerOptions});i.bindProtocolCleanup(a.cleanup),i.bindSinkDetach(_.addSink(e=>i.deliverBinary(e))),t.on(`message`,(e,t)=>{if(!t){a.onMessage(String(e));return}let n=_.receive(m(e));n.ok||i.deliver({type:`protocol_error`,message:n.error})}),t.on(`close`,i.close),t.on(`error`,i.close),i.deliver({type:`messages`,messages:r.getMessages()}),i.deliver({type:`execution_workspace_event`,snapshot:r.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;
+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

@@ -1,5 +1,5 @@
 import { TUsageSurface } from "@robota-sdk/agent-interface-analytics";
-import { TDriverId } from "@robota-sdk/agent-interface-session";
+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";
@@ -12,6 +12,8 @@ interface IWsTransportOptions {
   personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
   usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
   storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
   driverId?: TDriverId;
   surface?: TUsageSurface;
 }
@@ -32,6 +34,17 @@ interface IWsTransportConfig {
   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;
   /**
@@ -105,6 +118,7 @@ declare class WsTransport implements IConfigurableTransport<IProtocolSession>, I
   private readonly allowedHosts;
   private readonly allowedOrigins;
   private readonly handlerOptions;
+  private readonly sessionBinder;
   private readonly channels;
   private resolvedPort?;
   constructor(config?: IWsTransportConfig);
@@ -129,6 +143,11 @@ declare class WsTransport implements IConfigurableTransport<IProtocolSession>, I
   /** 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;
 }

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

@@ -1 +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,WAAW;EACX,UAAU;;UAGK,qBAAqB,kBAAkB;EACtD,aAAa;;iBAGC,kBAAkB,SAAS,sBAAsB;;;UCpBhD;;EAEf,WAAW;;EAEX,UAAU;;EAEV,wBAAwB;;EAExB,gBAAgB;;EAEhB,6BAA6B;EAC7B;EACA;;;;;;;;;;;EAWA;;;;;;;;;;EAUA;;EAEA;;;;;EAKA;;;;;;EAMA;;;;;;;;;cCVW,uBACA,uBAAuB,mBAAmB;WAE5C;WACA,WAAS;;;WACT;WACA;;;;;;;;;;;;UASD;UACA;UACA;UACA;UACA;UACA;UACA;mBACS;mBACA;mBACA;mBACA;mBACA;UACT;EAEI,YAAA,SAAQ;EAYpB,OAAO,SAAS;;;;;;;EAWhB,gBAAgB,gBAAgB,kBAC9B,YAAY,mBAAmB,WAC9B,gBAAgB;;MAKf;;;;;;MASA;EAIE,SAAS;EA8BT,QAAQ;;EAmBd,UAAU,SAAS,eAAe;EAWlC,gBAAgB,SAAS,eAAe;UAIhC;UAYA;;;;;KC1KE,gBAAgB,OAAO;cAqBtB,kCAAkC;mBAC5B;mBACA;;;;;EAMjB,QAAQ,MAAM;EAOd,gBAAgB,gBAAgB,kBAC9B,YAAY,mBAAmB,WAC9B,gBAAgB;;;;;EAoBnB,QAAQ,OAAO,aAAa;;UAmCpB;;iBAKO;UAIP"}
+{"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

@@ -1,6 +1,6 @@
 import { IProtocolSession, ISessionMessageHandlerOptions, TServerMessage } from "@robota-sdk/agent-transport";
 import { TUsageSurface } from "@robota-sdk/agent-interface-analytics";
-import { TDriverId } from "@robota-sdk/agent-interface-session";
+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
@@ -12,6 +12,8 @@ interface IWsTransportOptions {
   personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
   usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
   storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
   driverId?: TDriverId;
   surface?: TUsageSurface;
 }
@@ -32,6 +34,17 @@ interface IWsTransportConfig {
   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;
   /**
@@ -105,6 +118,7 @@ declare class WsTransport implements IConfigurableTransport<IProtocolSession>, I
   private readonly allowedHosts;
   private readonly allowedOrigins;
   private readonly handlerOptions;
+  private readonly sessionBinder;
   private readonly channels;
   private resolvedPort?;
   constructor(config?: IWsTransportConfig);
@@ -129,6 +143,11 @@ declare class WsTransport implements IConfigurableTransport<IProtocolSession>, I
   /** 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;
 }