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

package/src/__tests__/ws-session-directory.test.ts

@@ -0,0 +1,97 @@
+/**
+ * #3189: the host hands its session directory to the WebSocket carrier once, and every connection can
+ * list, start and switch the host's sessions through it.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { WebSocket } from 'ws';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createWsTransport } from '../ws-transport.js';
+import { WsTransport } from '../ws-transport-configurable.js';
+
+import type { ISessionDirectory, ISessionListing } from '@robota-sdk/agent-interface-session';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+const listing: ISessionListing = {
+  currentSessionId: 'session-1',
+  sessions: [],
+  unreadableSessionIds: [],
+};
+
+function createDirectory(): ISessionDirectory {
+  return {
+    listSessions: vi.fn(() => listing),
+    switchSession: vi.fn(async () => undefined),
+    newSession: vi.fn(async () => undefined),
+    renameSession: vi.fn(async () => undefined),
+    deleteSession: vi.fn(async () => undefined),
+  };
+}
+
+function mockSession(): ReturnType<typeof createTestInteractiveSession> {
+  return Object.assign(createTestInteractiveSession(), {
+    getMessages: vi.fn().mockReturnValue([]),
+    getExecutionWorkspaceSnapshot: vi.fn().mockReturnValue({ entries: [] }),
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+const started: WsTransport[] = [];
+afterEach(async () => {
+  while (started.length) await started.pop()!.stop();
+});
+
+describe('WsTransport session directory (#3189)', () => {
+  it('lets every connection list and switch the host sessions', async () => {
+    const directory = createDirectory();
+    const transport = new WsTransport({
+      port: 17720,
+      maxRetries: 30,
+      open: true,
+      openReason: 'session-directory regression test',
+      sessionDirectory: directory,
+    });
+    transport.attach(mockSession());
+    await transport.start();
+    started.push(transport);
+
+    const ws = new WebSocket(`ws://127.0.0.1:${transport.boundPort}`);
+    const received: TServerMessage[] = [];
+    ws.on('message', (data) => received.push(JSON.parse(String(data)) as TServerMessage));
+    await new Promise<void>((resolve, reject) => {
+      ws.on('open', resolve);
+      ws.on('error', reject);
+    });
+
+    ws.send(JSON.stringify({ type: 'list-sessions', requestId: 'r1' }));
+    ws.send(JSON.stringify({ type: 'switch-session', sessionId: 'session-2' }));
+    await vi.waitFor(() => expect(directory.switchSession).toHaveBeenCalledWith('session-2'));
+    await vi.waitFor(() =>
+      expect(received).toContainEqual({ type: 'sessions', requestId: 'r1', listing }),
+    );
+
+    const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()));
+    ws.close();
+    await closed;
+  });
+
+  it('passes the directory through the adapter form as well', async () => {
+    const directory = createDirectory();
+    const sent: TServerMessage[] = [];
+    const transport = createWsTransport({
+      send: (message) => sent.push(message),
+      sessionDirectory: directory,
+    });
+    transport.attach(mockSession());
+    await transport.start();
+
+    transport.onMessage?.(JSON.stringify({ type: 'list-sessions', requestId: 'r1' }));
+    transport.onMessage?.(JSON.stringify({ type: 'new-session' }));
+
+    expect(sent).toEqual([{ type: 'sessions', requestId: 'r1', listing }]);
+    await vi.waitFor(() => expect(directory.newSession).toHaveBeenCalledTimes(1));
+    await transport.stop();
+  });
+});

package/src/__tests__/ws-transport-auth.test.ts

@@ -133,6 +133,39 @@ describe('WsTransport loopback auth (GUI-002 TC-03)', () => {
     await closed;
   });
 
+  it('carries the driver id on the connection-open messages frame, so a client can learn its own id (#3289 §3)', async () => {
+    // The crux of #3289 §3's own-driver-id feature: a client's first `messages` frame is where it
+    // learns which of every subsequent `authored` message is its own. This is the one place that
+    // sets it — decode-shape validation and the client reducer are covered elsewhere, but neither
+    // would catch this specific line being broken or reverted.
+    const port = 17660;
+    const transport = new WsTransport({
+      port,
+      maxRetries: 30,
+      open: true,
+      openReason: 'own-driver-id regression test',
+      driverId: 'browser',
+      surface: 'browser',
+    });
+    transport.attach(mockSession());
+    await transport.start();
+    started.push(transport);
+    const ws = new WebSocket(`ws://127.0.0.1:${transport.boundPort}`);
+    const firstMessagesFrame = await new Promise<{ type: string; driverId?: string }>(
+      (resolve, reject) => {
+        ws.on('error', reject);
+        ws.on('message', (data) => {
+          const msg = JSON.parse(String(data)) as { type: string; driverId?: string };
+          if (msg.type === 'messages') resolve(msg);
+        });
+      },
+    );
+    expect(firstMessagesFrame.driverId).toBe('browser');
+    const closed = new Promise<void>((resolve) => ws.once('close', () => resolve()));
+    ws.close();
+    await closed;
+  });
+
   it('accepts a connection presenting the correct token via query param', async () => {
     const { port } = await startOn({ token: 'secret-nonce' });
     expect(await probe(port, { token: 'secret-nonce' })).toBe('messages');

package/src/ws-transport-config.ts

@@ -8,9 +8,9 @@
  */
 
 import type { TUsageSurface } from '@robota-sdk/agent-interface-analytics';
-import type { TDriverId } from '@robota-sdk/agent-interface-session';
+import type { ISessionBinder, TDriverId } from '@robota-sdk/agent-interface-session';
 import type { ITransportLifecycleError } from '@robota-sdk/agent-interface-transport';
-import type { ISessionMessageHandlerOptions } from '@robota-sdk/agent-transport';
+import type { IProtocolSession, ISessionMessageHandlerOptions } from '@robota-sdk/agent-transport';
 
 export const DEFAULT_PORT = 7070;
 export const DEFAULT_MAX_RETRIES = 20;
@@ -26,6 +26,17 @@ export 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;
   /**
@@ -84,7 +95,13 @@ function configuredUsageReporters(config: IWsTransportConfig): TUsageReporters {
 
 type TConfiguredHandlerOptions = Pick<
   ISessionMessageHandlerOptions,
-  'driverId' | 'surface' | 'personalUsageReporter' | 'usageReporter' | 'storedSessionUsageReporter'
+  | 'driverId'
+  | 'surface'
+  | 'personalUsageReporter'
+  | 'usageReporter'
+  | 'storedSessionUsageReporter'
+  | 'sessionDirectory'
+  | 'settingsReporter'
 >;
 
 /** Project immutable transport attribution/reporters into each protocol handler. */
@@ -93,6 +110,8 @@ export function configuredWsHandlerOptions(config: IWsTransportConfig): TConfigu
     ...(config.driverId ? { driverId: config.driverId } : {}),
     ...(config.surface ? { surface: config.surface } : {}),
     ...configuredUsageReporters(config),
+    ...(config.sessionDirectory ? { sessionDirectory: config.sessionDirectory } : {}),
+    ...(config.settingsReporter ? { settingsReporter: config.settingsReporter } : {}),
   };
 }
 

package/src/ws-transport-configurable.ts

@@ -28,6 +28,7 @@ import {
 
 import type { IWsTransportConfig } from './ws-transport-config.js';
 import type { TUniversalValue } from '@robota-sdk/agent-core';
+import type { ISessionBinder, ISessionBinding } from '@robota-sdk/agent-interface-session';
 import type {
   IChannelDescriptor,
   IConfigurableTransport,
@@ -51,9 +52,7 @@ const WS_STOP_TERMINATE_DEADLINE_MS = 5000;
  * 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.
  */
-export class WsTransport
-  implements IConfigurableTransport<IProtocolSession>, IPayloadChannelHost
-{
+export class WsTransport implements IConfigurableTransport<IProtocolSession>, IPayloadChannelHost {
   readonly name = 'ws';
   readonly lifecycle = Object.freeze({ kind: 'service' as const });
   readonly defaultEnabled = true;
@@ -77,6 +76,7 @@ export class WsTransport
   private readonly allowedHosts: ReadonlySet<string>;
   private readonly allowedOrigins: ReadonlySet<string>;
   private readonly handlerOptions: ReturnType<typeof configuredWsHandlerOptions>;
+  private readonly sessionBinder: ISessionBinder<IProtocolSession> | undefined;
   private readonly channels = new PayloadChannelRegistry();
   private resolvedPort?: number;
 
@@ -90,6 +90,7 @@ export class WsTransport
     this.allowedHosts = new Set(config.allowedHosts ?? []);
     this.allowedOrigins = new Set(config.allowedOrigins ?? []);
     this.handlerOptions = configuredWsHandlerOptions(config);
+    this.sessionBinder = config.sessionBinder;
   }
 
   attach(session: IProtocolSession): void {
@@ -187,6 +188,22 @@ export class WsTransport
     return validTransportOptions(options);
   }
 
+  /**
+   * 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(
+    ws: WebSocket,
+  ): { binding: ISessionBinding<IProtocolSession> | undefined } | null {
+    if (!this.sessionBinder) return { binding: undefined };
+    try {
+      return { binding: this.sessionBinder.bind('drive') };
+    } catch {
+      ws.close(1013, 'session unavailable');
+      return null;
+    }
+  }
+
   private bindWithRetry(
     session: IProtocolSession,
     port: number,
@@ -244,13 +261,24 @@ export class WsTransport
             return;
           }
 
+          // #3189: with a binder, this connection gets its own session and directory, so its
+          // switch (and the `session_switched` that follows) stays on this connection. Every WS
+          // connection drives: this carrier has no observe role.
+          const bound = this.bindConnection(ws);
+          if (bound === null) return;
+          const { binding } = bound;
+          const connectionSession = binding?.session ?? session;
           const delivery = new WsSessionDelivery(ws);
           const handler = createSessionMessageHandler({
-            session,
+            session: connectionSession,
             deliver: delivery.deliver,
             ...this.handlerOptions,
+            ...(binding ? { sessionDirectory: binding.directory } : {}),
+          });
+          delivery.bindProtocolCleanup(() => {
+            handler.cleanup();
+            binding?.release();
           });
-          delivery.bindProtocolCleanup(handler.cleanup);
 
           delivery.bindSinkDetach(
             // ARCH-030: through the connection's own delivery, so payload frames share the text
@@ -274,10 +302,14 @@ export class WsTransport
           ws.on('close', delivery.close);
           ws.on('error', delivery.close);
 
-          delivery.deliver({ type: 'messages', messages: session.getMessages() });
+          delivery.deliver({
+            type: 'messages',
+            messages: connectionSession.getMessages(),
+            ...(this.handlerOptions.driverId ? { driverId: this.handlerOptions.driverId } : {}),
+          });
           delivery.deliver({
             type: 'execution_workspace_event',
-            snapshot: session.getExecutionWorkspaceSnapshot(),
+            snapshot: connectionSession.getExecutionWorkspaceSnapshot(),
           });
         });
 

package/src/ws-transport.ts

@@ -27,6 +27,8 @@ export interface IWsTransportOptions {
   personalUsageReporter?: ISessionMessageHandlerOptions['personalUsageReporter'];
   usageReporter?: ISessionMessageHandlerOptions['usageReporter'];
   storedSessionUsageReporter?: ISessionMessageHandlerOptions['storedSessionUsageReporter'];
+  sessionDirectory?: ISessionMessageHandlerOptions['sessionDirectory'];
+  settingsReporter?: ISessionMessageHandlerOptions['settingsReporter'];
   driverId?: TDriverId;
   surface?: TUsageSurface;
 }
@@ -75,6 +77,8 @@ export function createWsTransport(options: IWsTransportOptions): IWsTransport {
         ...(options.storedSessionUsageReporter
           ? { storedSessionUsageReporter: options.storedSessionUsageReporter }
           : {}),
+        ...(options.sessionDirectory ? { sessionDirectory: options.sessionDirectory } : {}),
+        ...(options.settingsReporter ? { settingsReporter: options.settingsReporter } : {}),
       });
       cleanup = handler.cleanup;
       this.onMessage = handler.onMessage;