@agentick/gateway 0.0.1

package/src/session-manager.ts

@@ -0,0 +1,272 @@
+/**
+ * Session Manager
+ *
+ * Manages persistent sessions across apps.
+ */
+
+import type { Session } from "@agentick/core";
+import { devToolsEmitter, type DTGatewaySessionEvent } from "@agentick/shared";
+import type { AppRegistry, AppInfo } from "./app-registry.js";
+import type { SessionState } from "./types.js";
+import { parseSessionKey, formatSessionKey } from "./transport-protocol.js";
+
+interface ManagedSession {
+  state: SessionState;
+  coreSession: Session | null;
+  appInfo: AppInfo;
+  /** The session name without app prefix - used when creating App sessions */
+  sessionName: string;
+}
+
+/**
+ * SessionManager configuration
+ */
+export interface SessionManagerConfig {
+  /** Gateway ID for DevTools events */
+  gatewayId: string;
+}
+
+export class SessionManager {
+  private sessions = new Map<string, ManagedSession>();
+  private registry: AppRegistry;
+  private gatewayId: string;
+  private devToolsSequence = 0;
+
+  constructor(registry: AppRegistry, config?: SessionManagerConfig) {
+    this.registry = registry;
+    this.gatewayId = config?.gatewayId ?? "gateway";
+  }
+
+  /**
+   * Normalize a session key to the canonical format (appId:sessionName).
+   * This ensures consistent lookups regardless of input format.
+   */
+  private normalizeKey(sessionKey: string): string {
+    const { appId, sessionName } = parseSessionKey(sessionKey, this.registry.defaultId);
+    return formatSessionKey({ appId, sessionName });
+  }
+
+  /**
+   * Emit a DevTools session event
+   */
+  private emitDevToolsEvent(
+    action: DTGatewaySessionEvent["action"],
+    sessionId: string,
+    appId: string,
+    messageCount?: number,
+    clientId?: string,
+  ): void {
+    if (!devToolsEmitter.hasSubscribers()) return;
+
+    devToolsEmitter.emitEvent({
+      type: "gateway_session",
+      executionId: this.gatewayId,
+      action,
+      sessionId,
+      appId,
+      messageCount,
+      clientId,
+      sequence: this.devToolsSequence++,
+      timestamp: Date.now(),
+    } as DTGatewaySessionEvent);
+  }
+
+  /**
+   * Get or create a session
+   */
+  async getOrCreate(sessionKey: string, clientId?: string): Promise<ManagedSession> {
+    const normalizedKey = this.normalizeKey(sessionKey);
+
+    // Check if session exists
+    let session = this.sessions.get(normalizedKey);
+    if (session) {
+      session.state.lastActivityAt = new Date();
+      return session;
+    }
+
+    // Parse session key to get app and name
+    const { appId, sessionName } = parseSessionKey(sessionKey, this.registry.defaultId);
+
+    // Get the app
+    const appInfo = this.registry.resolve(appId);
+
+    // Create session state
+    const state: SessionState = {
+      id: formatSessionKey({ appId, sessionName }),
+      appId,
+      createdAt: new Date(),
+      lastActivityAt: new Date(),
+      messageCount: 0,
+      isActive: false,
+      subscribers: new Set(),
+    };
+
+    // Create the managed session
+    // Note: sessionName is the name WITHOUT app prefix - used when creating App sessions
+    session = {
+      state,
+      coreSession: null,
+      appInfo,
+      sessionName,
+    };
+
+    this.sessions.set(state.id, session);
+
+    // Emit DevTools event for session creation
+    this.emitDevToolsEvent("created", state.id, appId, 0, clientId);
+
+    return session;
+  }
+
+  /**
+   * Get an existing session
+   */
+  get(sessionKey: string): ManagedSession | undefined {
+    return this.sessions.get(this.normalizeKey(sessionKey));
+  }
+
+  /**
+   * Check if a session exists
+   */
+  has(sessionKey: string): boolean {
+    return this.sessions.has(this.normalizeKey(sessionKey));
+  }
+
+  /**
+   * Close a session
+   */
+  async close(sessionKey: string): Promise<void> {
+    const normalizedKey = this.normalizeKey(sessionKey);
+    const session = this.sessions.get(normalizedKey);
+    if (!session) return;
+
+    const { id, appId, messageCount } = session.state;
+
+    // Clean up session if active
+    if (session.coreSession) {
+      session.coreSession.close();
+      session.coreSession = null;
+    }
+
+    this.sessions.delete(normalizedKey);
+
+    // Emit DevTools event for session closure
+    this.emitDevToolsEvent("closed", id, appId, messageCount);
+  }
+
+  /**
+   * Reset a session (clear history but keep session)
+   */
+  async reset(sessionKey: string): Promise<void> {
+    const normalizedKey = this.normalizeKey(sessionKey);
+    const session = this.sessions.get(normalizedKey);
+    if (!session) return;
+
+    const { id, appId, messageCount } = session.state;
+
+    // Reset session state
+    session.state.messageCount = 0;
+    session.state.lastActivityAt = new Date();
+    if (session.coreSession) {
+      session.coreSession.close();
+      session.coreSession = null;
+    }
+
+    // Emit DevTools event for session reset (treated as closed + recreated)
+    this.emitDevToolsEvent("closed", id, appId, messageCount);
+  }
+
+  /**
+   * Get all session IDs
+   */
+  ids(): string[] {
+    return Array.from(this.sessions.keys());
+  }
+
+  /**
+   * Get all sessions
+   */
+  all(): ManagedSession[] {
+    return Array.from(this.sessions.values());
+  }
+
+  /**
+   * Get sessions for a specific app
+   */
+  forApp(appId: string): ManagedSession[] {
+    return this.all().filter((s) => s.state.appId === appId);
+  }
+
+  /**
+   * Get session count
+   */
+  get size(): number {
+    return this.sessions.size;
+  }
+
+  /**
+   * Add a subscriber to a session.
+   * Creates the session if it doesn't exist (ensures subscription is never lost).
+   */
+  async subscribe(sessionKey: string, clientId: string): Promise<void> {
+    const session = await this.getOrCreate(sessionKey, clientId);
+    session.state.subscribers.add(clientId);
+  }
+
+  /**
+   * Remove a subscriber from a session
+   */
+  unsubscribe(sessionKey: string, clientId: string): void {
+    const session = this.sessions.get(this.normalizeKey(sessionKey));
+    if (session) {
+      session.state.subscribers.delete(clientId);
+    }
+  }
+
+  /**
+   * Remove a client from all subscriptions
+   */
+  unsubscribeAll(clientId: string): void {
+    for (const session of this.sessions.values()) {
+      session.state.subscribers.delete(clientId);
+    }
+  }
+
+  /**
+   * Get subscribers for a session
+   */
+  getSubscribers(sessionKey: string): Set<string> {
+    const session = this.sessions.get(this.normalizeKey(sessionKey));
+    return session?.state.subscribers ?? new Set();
+  }
+
+  /**
+   * Update message count for a session
+   */
+  incrementMessageCount(sessionKey: string, clientId?: string): void {
+    const session = this.sessions.get(this.normalizeKey(sessionKey));
+    if (session) {
+      session.state.messageCount++;
+      session.state.lastActivityAt = new Date();
+
+      // Emit DevTools event for session message
+      this.emitDevToolsEvent(
+        "message",
+        session.state.id,
+        session.state.appId,
+        session.state.messageCount,
+        clientId,
+      );
+    }
+  }
+
+  /**
+   * Set session active state
+   */
+  setActive(sessionKey: string, isActive: boolean): void {
+    const session = this.sessions.get(this.normalizeKey(sessionKey));
+    if (session) {
+      session.state.isActive = isActive;
+    }
+  }
+}

package/src/testing.ts

@@ -0,0 +1,236 @@
+/**
+ * Gateway Testing Utilities
+ *
+ * Provides helpers for testing gateway interactions.
+ *
+ * @example
+ * ```typescript
+ * import { createTestGateway, createMockApp } from '@agentick/gateway/testing';
+ *
+ * test('gateway handles messages', async () => {
+ *   const mockApp = createMockApp({
+ *     response: 'Hello!',
+ *   });
+ *
+ *   const { gateway, client, cleanup } = await createTestGateway({
+ *     agents: { chat: mockApp },
+ *     defaultAgent: 'chat',
+ *   });
+ *
+ *   try {
+ *     const response = await client.send('main', 'Hi there');
+ *     expect(response.payload.messageId).toBeDefined();
+ *   } finally {
+ *     await cleanup();
+ *   }
+ * });
+ * ```
+ *
+ * @module @agentick/gateway/testing
+ */
+
+import WebSocket from "ws";
+import type { Gateway } from "./gateway.js";
+import { createGateway } from "./gateway.js";
+import type { GatewayConfig, GatewayEvents } from "./types.js";
+
+// Re-export mock factories from core
+export {
+  createMockApp,
+  createMockSession,
+  createMockExecutionHandle,
+  createTestProcedure,
+  type MockAppOptions,
+  type MockSessionOptions,
+  type MockSession,
+  type MockApp,
+  type MockSessionExecutionHandle,
+  type MockExecutionHandleOptions,
+  type TestProcedure,
+  type TestProcedureOptions,
+} from "@agentick/core/testing";
+
+// ============================================================================
+// Test Gateway Factory
+// ============================================================================
+
+export interface TestGatewayOptions extends Omit<GatewayConfig, "port" | "host"> {
+  /** Custom port (default: random available port) */
+  port?: number;
+}
+
+export interface TestGatewayClient {
+  /** Send a request to the gateway */
+  request<T = unknown>(
+    method: string,
+    params?: Record<string, unknown>,
+  ): Promise<{
+    ok: boolean;
+    payload?: T;
+    error?: { code: string; message: string };
+  }>;
+
+  /** Send a message to a session */
+  send(
+    sessionId: string,
+    message: string,
+  ): Promise<{
+    ok: boolean;
+    payload?: { messageId: string };
+    error?: { code: string; message: string };
+  }>;
+
+  /** Collect events for a session */
+  collectEvents(
+    sessionId: string,
+    timeout?: number,
+  ): Promise<Array<{ type: string; data: unknown }>>;
+
+  /** Close the client connection */
+  close(): void;
+
+  /** The raw WebSocket */
+  ws: WebSocket;
+}
+
+export interface TestGatewayResult {
+  /** The gateway instance */
+  gateway: Gateway;
+
+  /** A connected test client */
+  client: TestGatewayClient;
+
+  /** Gateway URL */
+  url: string;
+
+  /** Port the gateway is running on */
+  port: number;
+
+  /** Clean up resources */
+  cleanup: () => Promise<void>;
+}
+
+/**
+ * Create a test gateway with a connected client.
+ *
+ * Automatically handles port allocation, client connection, and cleanup.
+ */
+export async function createTestGateway(options: TestGatewayOptions): Promise<TestGatewayResult> {
+  // Use random high port to avoid conflicts
+  const port = options.port ?? 19000 + Math.floor(Math.random() * 1000);
+  const host = "127.0.0.1";
+  const url = `ws://${host}:${port}`;
+
+  const gateway = createGateway({
+    ...options,
+    port,
+    host,
+  });
+
+  await gateway.start();
+
+  // Create and connect client
+  const ws = new WebSocket(url);
+  await new Promise<void>((resolve, reject) => {
+    ws.on("open", () => resolve());
+    ws.on("error", reject);
+  });
+
+  // Authenticate
+  ws.send(JSON.stringify({ type: "connect", clientId: "test-client" }));
+  await new Promise((r) => setTimeout(r, 50));
+
+  let requestId = 0;
+  const pendingRequests = new Map<
+    string,
+    {
+      resolve: (value: any) => void;
+      reject: (error: Error) => void;
+    }
+  >();
+
+  ws.on("message", (data) => {
+    const msg = JSON.parse(data.toString());
+    if (msg.type === "res" && pendingRequests.has(msg.id)) {
+      const { resolve } = pendingRequests.get(msg.id)!;
+      pendingRequests.delete(msg.id);
+      resolve({ ok: msg.ok, payload: msg.payload, error: msg.error });
+    }
+  });
+
+  const client: TestGatewayClient = {
+    ws,
+
+    async request(method, params = {}) {
+      const id = `req-${++requestId}`;
+      return new Promise((resolve, reject) => {
+        pendingRequests.set(id, { resolve, reject });
+        ws.send(JSON.stringify({ type: "req", id, method, params }));
+
+        // Timeout after 5s
+        setTimeout(() => {
+          if (pendingRequests.has(id)) {
+            pendingRequests.delete(id);
+            reject(new Error(`Request ${method} timed out`));
+          }
+        }, 5000);
+      });
+    },
+
+    async send(sessionId, message) {
+      return this.request("send", { sessionId, message });
+    },
+
+    async collectEvents(sessionId, timeout = 1000) {
+      const events: Array<{ type: string; data: unknown }> = [];
+
+      const handler = (data: WebSocket.Data) => {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === "event" && msg.sessionId === sessionId) {
+          events.push({ type: msg.event, data: msg.data });
+        }
+      };
+
+      ws.on("message", handler);
+      await new Promise((r) => setTimeout(r, timeout));
+      ws.off("message", handler);
+
+      return events;
+    },
+
+    close() {
+      ws.close();
+    },
+  };
+
+  const cleanup = async () => {
+    client.close();
+    await gateway.stop();
+  };
+
+  return { gateway, client, url, port, cleanup };
+}
+
+// ============================================================================
+// Event Helpers
+// ============================================================================
+
+/**
+ * Wait for a specific gateway event.
+ */
+export function waitForGatewayEvent<K extends keyof GatewayEvents>(
+  gateway: Gateway,
+  event: K,
+  timeout = 5000,
+): Promise<GatewayEvents[K]> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Timeout waiting for gateway event: ${event}`));
+    }, timeout);
+
+    gateway.on(event, (payload) => {
+      clearTimeout(timer);
+      resolve(payload);
+    });
+  });
+}