@agentick/gateway 0.0.1

package/src/transport-protocol.ts

@@ -0,0 +1,249 @@
+/**
+ * Gateway Protocol Types
+ *
+ * Defines the WebSocket message protocol between clients and the gateway.
+ */
+
+// ============================================================================
+// Client → Gateway Messages
+// ============================================================================
+
+export interface ConnectMessage {
+  type: "connect";
+  clientId: string;
+  token?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RequestMessage {
+  type: "req";
+  id: string;
+  method: GatewayMethod;
+  params: Record<string, unknown>;
+}
+
+export interface PingMessage {
+  type: "ping";
+  timestamp: number;
+}
+
+export type ClientMessage = ConnectMessage | RequestMessage | PingMessage;
+
+// ============================================================================
+// Gateway → Client Messages
+// ============================================================================
+
+export interface ConnectedMessage {
+  type: "connected";
+  gatewayId: string;
+  apps: string[];
+  sessions: string[];
+}
+
+export interface ResponseMessage {
+  type: "res";
+  id: string;
+  ok: boolean;
+  payload?: unknown;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+export interface EventMessage {
+  type: "event";
+  event: GatewayEventType;
+  sessionId: string;
+  data: unknown;
+}
+
+export interface PongMessage {
+  type: "pong";
+  timestamp: number;
+}
+
+export interface ErrorMessage {
+  type: "error";
+  code: string;
+  message: string;
+}
+
+export type GatewayMessage =
+  | ConnectedMessage
+  | ResponseMessage
+  | EventMessage
+  | PongMessage
+  | ErrorMessage;
+
+// ============================================================================
+// RPC Methods
+// ============================================================================
+
+/**
+ * Built-in gateway methods with autocomplete support.
+ */
+export type BuiltInMethod =
+  | "send" // Send message to session
+  | "abort" // Abort current execution
+  | "status" // Get gateway/session status
+  | "history" // Get conversation history
+  | "reset" // Reset a session
+  | "close" // Close a session
+  | "apps" // List available apps
+  | "sessions" // List sessions
+  | "subscribe" // Subscribe to session events
+  | "unsubscribe"; // Unsubscribe from events
+
+/**
+ * Gateway method - built-in methods or custom method strings.
+ * The (string & {}) allows any string while preserving autocomplete for built-in methods.
+ */
+export type GatewayMethod = BuiltInMethod | (string & {});
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+export type GatewayEventType =
+  | "content_delta"
+  | "content_block_start"
+  | "content_block_end"
+  | "tool_call_start"
+  | "tool_call_delta"
+  | "tool_result"
+  | "message_start"
+  | "message_end"
+  | "error";
+
+// ============================================================================
+// Method Parameters
+// ============================================================================
+
+export interface SendParams {
+  sessionId: string;
+  message: string;
+  attachments?: Array<{
+    type: "image" | "file";
+    data: string;
+    mimeType: string;
+    name?: string;
+  }>;
+}
+
+export interface AbortParams {
+  sessionId: string;
+}
+
+export interface StatusParams {
+  sessionId?: string;
+}
+
+export interface HistoryParams {
+  sessionId: string;
+  limit?: number;
+  before?: string;
+}
+
+export interface ResetParams {
+  sessionId: string;
+}
+
+export interface CloseParams {
+  sessionId: string;
+}
+
+export interface SubscribeParams {
+  sessionId: string;
+}
+
+export interface UnsubscribeParams {
+  sessionId: string;
+}
+
+// ============================================================================
+// Response Payloads
+// ============================================================================
+
+export interface StatusPayload {
+  gateway: {
+    id: string;
+    uptime: number;
+    clients: number;
+    sessions: number;
+    apps: string[];
+  };
+  session?: {
+    id: string;
+    appId: string;
+    messageCount: number;
+    createdAt: string;
+    lastActivityAt: string;
+    isActive: boolean;
+  };
+}
+
+export interface HistoryPayload {
+  messages: Array<{
+    id: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp: string;
+    toolCalls?: Array<{
+      name: string;
+      input: unknown;
+      output?: unknown;
+    }>;
+  }>;
+  hasMore: boolean;
+}
+
+export interface AppsPayload {
+  apps: Array<{
+    id: string;
+    name: string;
+    description?: string;
+    isDefault: boolean;
+  }>;
+}
+
+export interface SessionsPayload {
+  sessions: Array<{
+    id: string;
+    appId: string;
+    createdAt: string;
+    lastActivityAt: string;
+    messageCount: number;
+  }>;
+}
+
+// ============================================================================
+// Session Key Format
+// ============================================================================
+
+/**
+ * Session keys follow the format: [app:]name
+ *
+ * Examples:
+ * - "main" → default app, "main" session
+ * - "chat:main" → "chat" app, "main" session
+ * - "research:task-123" → "research" app, "task-123" session
+ * - "whatsapp:+1234567890" → WhatsApp channel session
+ */
+export interface SessionKey {
+  appId: string;
+  sessionName: string;
+}
+
+export function parseSessionKey(key: string, defaultApp: string): SessionKey {
+  const parts = key.split(":");
+  if (parts.length === 1) {
+    return { appId: defaultApp, sessionName: parts[0] };
+  }
+  return { appId: parts[0], sessionName: parts.slice(1).join(":") };
+}
+
+export function formatSessionKey(key: SessionKey): string {
+  return `${key.appId}:${key.sessionName}`;
+}

package/src/transport.ts

@@ -0,0 +1,191 @@
+/**
+ * Gateway Transport Interface
+ *
+ * Abstracts the transport layer (WebSocket, HTTP/SSE) from gateway business logic.
+ * This allows the same GatewayCore to serve clients via different protocols.
+ */
+
+import type { Message } from "@agentick/shared";
+import { validateAuth, type AuthResult } from "@agentick/server";
+import type { GatewayMessage, ClientMessage } from "./transport-protocol.js";
+import type { AuthConfig, ClientState, UserContext } from "./types.js";
+
+// ============================================================================
+// Transport Interface
+// ============================================================================
+
+/**
+ * A connected client from the transport's perspective.
+ */
+export interface TransportClient {
+  /** Unique client identifier */
+  readonly id: string;
+
+  /** Client state (auth, subscriptions, etc.) */
+  readonly state: ClientState;
+
+  /** Send a message to this client */
+  send(message: GatewayMessage): void;
+
+  /** Close the connection */
+  close(code?: number, reason?: string): void;
+
+  /** Check if connected */
+  readonly isConnected: boolean;
+}
+
+/**
+ * Events emitted by a transport.
+ */
+export interface TransportEvents {
+  /** Client connected (may not be authenticated yet) */
+  connection: (client: TransportClient) => void;
+
+  /** Client disconnected */
+  disconnect: (clientId: string, reason?: string) => void;
+
+  /** Message received from authenticated client */
+  message: (clientId: string, message: ClientMessage) => void;
+
+  /** Transport error */
+  error: (error: Error) => void;
+}
+
+/**
+ * Transport configuration.
+ */
+export interface TransportConfig {
+  /** Port to listen on */
+  port: number;
+
+  /** Host to bind to */
+  host: string;
+
+  /** Authentication configuration */
+  auth?: AuthConfig;
+
+  /**
+   * Direct send handler for HTTP transport.
+   * Called instead of routing through message handler when streaming response is needed.
+   * Accepts full Message object to support multimodal content (images, audio, video, docs).
+   */
+  onDirectSend?: (
+    sessionId: string,
+    message: Message,
+  ) => AsyncIterable<{ type: string; data?: unknown }>;
+
+  /**
+   * Method invocation handler for HTTP transport.
+   * Called to execute custom gateway methods.
+   * Returns the method result directly (no streaming).
+   */
+  onInvoke?: (
+    method: string,
+    params: Record<string, unknown>,
+    user?: UserContext,
+  ) => Promise<unknown>;
+}
+
+/** Transport type identifier */
+export type TransportType = "websocket" | "http" | "sse";
+
+/**
+ * Transport interface - abstracts WebSocket vs HTTP/SSE.
+ */
+export interface Transport {
+  /** Transport type identifier */
+  readonly type: TransportType;
+
+  /** Start the transport server */
+  start(): Promise<void>;
+
+  /** Stop the transport server */
+  stop(): Promise<void>;
+
+  /** Register event handlers */
+  on<K extends keyof TransportEvents>(event: K, handler: TransportEvents[K]): void;
+
+  /** Get a client by ID */
+  getClient(id: string): TransportClient | undefined;
+
+  /** Get all connected clients */
+  getClients(): TransportClient[];
+
+  /** Get authenticated clients */
+  getAuthenticatedClients(): TransportClient[];
+
+  /** Broadcast to all authenticated clients */
+  broadcast(message: GatewayMessage): void;
+
+  /** Send to clients subscribed to a session */
+  sendToSubscribers(sessionId: string, message: GatewayMessage): void;
+
+  /** Number of connected clients */
+  readonly clientCount: number;
+}
+
+// ============================================================================
+// Base Transport Implementation (shared logic)
+// ============================================================================
+
+/**
+ * Base class with shared transport functionality.
+ */
+export abstract class BaseTransport implements Transport {
+  /** Transport type - must be set by subclass */
+  abstract readonly type: TransportType;
+
+  protected clients = new Map<string, TransportClient>();
+  protected handlers: Partial<TransportEvents> = {};
+  protected config: TransportConfig;
+  protected clientIdCounter = 0;
+
+  constructor(config: TransportConfig) {
+    this.config = config;
+  }
+
+  abstract start(): Promise<void>;
+  abstract stop(): Promise<void>;
+
+  on<K extends keyof TransportEvents>(event: K, handler: TransportEvents[K]): void {
+    this.handlers[event] = handler;
+  }
+
+  getClient(id: string): TransportClient | undefined {
+    return this.clients.get(id);
+  }
+
+  getClients(): TransportClient[] {
+    return Array.from(this.clients.values());
+  }
+
+  getAuthenticatedClients(): TransportClient[] {
+    return this.getClients().filter((c) => c.state.authenticated);
+  }
+
+  broadcast(message: GatewayMessage): void {
+    for (const client of this.getAuthenticatedClients()) {
+      client.send(message);
+    }
+  }
+
+  sendToSubscribers(sessionId: string, message: GatewayMessage): void {
+    for (const client of this.getAuthenticatedClients()) {
+      if (client.state.subscriptions.has(sessionId)) {
+        client.send(message);
+      }
+    }
+  }
+
+  get clientCount(): number {
+    return this.clients.size;
+  }
+
+  protected generateClientId(): string {
+    return `client-${++this.clientIdCounter}`;
+  }
+
+  protected validateAuth(token?: string): Promise<AuthResult> {
+    return validateAuth(token, this.config.auth);
+  }
+}