@agentick/gateway 0.0.1

package/dist/gateway.js

@@ -0,0 +1,1339 @@
+/**
+ * Gateway
+ *
+ * Standalone daemon for multi-client, multi-app access.
+ * Transport-agnostic: supports both WebSocket and HTTP/SSE.
+ *
+ * Can run standalone or embedded in an external framework.
+ */
+import { EventEmitter } from "events";
+import { GuardError, isGuardError } from "@agentick/shared";
+import { devToolsEmitter, } from "@agentick/shared";
+import { Context, createProcedure, createGuard, Logger, } from "@agentick/kernel";
+const log = Logger.for("Gateway");
+import { extractToken, validateAuth, setSSEHeaders } from "@agentick/server";
+import { AppRegistry } from "./app-registry.js";
+import { SessionManager } from "./session-manager.js";
+import { WSTransport } from "./ws-transport.js";
+import { HTTPTransport } from "./http-transport.js";
+import { isMethodDefinition } from "./types.js";
+const DEFAULT_PORT = 18789;
+const DEFAULT_HOST = "127.0.0.1";
+// ============================================================================
+// Guard Middleware
+// ============================================================================
+/** Guard middleware that checks user roles */
+function createRoleGuardMiddleware(roles) {
+    return createGuard({ name: "gateway-role", guardType: "role" }, () => {
+        const userRoles = Context.get().user?.roles ?? [];
+        if (!roles.some((r) => userRoles.includes(r))) {
+            throw GuardError.role(roles);
+        }
+        return true;
+    });
+}
+/** Guard middleware that runs custom guard function */
+function createCustomGuardMiddleware(guard) {
+    return createGuard({ name: "gateway-custom", reason: "Guard check failed" }, () => guard(Context.get()));
+}
+// ============================================================================
+// Channel Service Helpers
+// ============================================================================
+/**
+ * Create a ChannelServiceInterface that wraps a Session's channel() method.
+ * This allows gateway methods to access session channels via Context.
+ */
+function createChannelServiceFromSession(session, _gatewayId) {
+    return {
+        getChannel: (_ctx, channelName) => session.channel(channelName),
+        publish: (_ctx, channelName, event) => {
+            session.channel(channelName).publish({ ...event, channel: channelName });
+        },
+        subscribe: (_ctx, channelName, handler) => {
+            return session.channel(channelName).subscribe(handler);
+        },
+        waitForResponse: (_ctx, channelName, requestId, timeoutMs) => {
+            return session.channel(channelName).waitForResponse(requestId, timeoutMs);
+        },
+    };
+}
+// ============================================================================
+// Gateway Class
+// ============================================================================
+/** Built-in methods that cannot be overridden */
+const BUILT_IN_METHODS = new Set([
+    "send",
+    "abort",
+    "status",
+    "history",
+    "reset",
+    "close",
+    "apps",
+    "sessions",
+    "subscribe",
+    "unsubscribe",
+]);
+export class Gateway extends EventEmitter {
+    config;
+    registry;
+    sessions;
+    transports = [];
+    startTime = null;
+    isRunning = false;
+    embedded;
+    /** Pre-compiled map of method paths to procedures */
+    methodProcedures = new Map();
+    /** Track open SSE connections for embedded mode */
+    sseClients = new Map();
+    /** Track channel subscriptions: "sessionId:channelName" -> Set of clientIds */
+    channelSubscriptions = new Map();
+    /** Track unsubscribe functions for core session channels */
+    coreChannelUnsubscribes = new Map();
+    /** Track client connection times for duration calculation */
+    clientConnectedAt = new Map();
+    /** Sequence counter for DevTools events */
+    devToolsSequence = 0;
+    constructor(config) {
+        super();
+        // Validate config
+        if (!config.apps || Object.keys(config.apps).length === 0) {
+            throw new Error("At least one app is required");
+        }
+        if (!config.defaultApp) {
+            throw new Error("defaultApp is required");
+        }
+        this.embedded = config.embedded ?? false;
+        // Set defaults
+        this.config = {
+            ...config,
+            port: config.port ?? DEFAULT_PORT,
+            host: config.host ?? DEFAULT_HOST,
+            id: config.id ?? `gw-${Date.now().toString(36)}`,
+            transport: config.transport ?? "websocket",
+        };
+        // Initialize components
+        this.registry = new AppRegistry(config.apps, config.defaultApp);
+        this.sessions = new SessionManager(this.registry, { gatewayId: this.config.id });
+        // Initialize all methods as procedures
+        if (config.methods) {
+            this.initializeMethods(config.methods, []);
+        }
+        // Create transports only in standalone mode
+        if (!this.embedded) {
+            this.initializeTransports();
+        }
+    }
+    /**
+     * Walk the methods tree and wrap all handlers as procedures.
+     * Infers full path name (e.g., "tasks:admin:archive") automatically.
+     */
+    initializeMethods(methods, path) {
+        for (const [key, value] of Object.entries(methods)) {
+            const fullPath = [...path, key];
+            const methodName = fullPath.join(":"); // e.g., "tasks:admin:archive"
+            if (typeof value === "function") {
+                // Simple function -> wrap in procedure automatically
+                this.methodProcedures.set(methodName, createProcedure({
+                    name: `gateway:${methodName}`,
+                    executionBoundary: "auto",
+                    metadata: { gatewayId: this.config.id, method: methodName },
+                }, value));
+            }
+            else if (isMethodDefinition(value)) {
+                // method() definition -> create procedure with guards/schema as middleware
+                const middleware = [];
+                if (value.roles?.length) {
+                    middleware.push(createRoleGuardMiddleware(value.roles));
+                }
+                if (value.guard) {
+                    middleware.push(createCustomGuardMiddleware(value.guard));
+                }
+                this.methodProcedures.set(methodName, createProcedure({
+                    name: `gateway:${methodName}`,
+                    executionBoundary: "auto",
+                    // Cast to any for Zod 3/4 compatibility - runtime uses .parse() only
+                    schema: value.schema,
+                    middleware,
+                    metadata: {
+                        gatewayId: this.config.id,
+                        method: methodName,
+                        description: value.description,
+                        roles: value.roles,
+                    },
+                }, value.handler));
+            }
+            else {
+                // Plain object -> namespace, recurse
+                this.initializeMethods(value, fullPath);
+            }
+        }
+    }
+    /**
+     * Get a method's procedure by path (supports both ":" and "." separators)
+     */
+    getMethodProcedure(path) {
+        // Normalize separators to ":"
+        const normalized = path.replace(/\./g, ":");
+        return this.methodProcedures.get(normalized);
+    }
+    initializeTransports() {
+        const { transport, port, host, auth, httpPort } = this.config;
+        if (transport === "websocket" || transport === "both") {
+            const wsTransport = new WSTransport({ port, host, auth });
+            this.setupTransportHandlers(wsTransport);
+            this.transports.push(wsTransport);
+        }
+        if (transport === "http" || transport === "both") {
+            const httpTransportPort = transport === "both" ? (httpPort ?? port + 1) : port;
+            const httpTransportInstance = new HTTPTransport({
+                port: httpTransportPort,
+                host,
+                auth,
+                pathPrefix: this.config.httpPathPrefix,
+                corsOrigin: this.config.httpCorsOrigin,
+                onDirectSend: this.directSend.bind(this),
+                onInvoke: this.invokeMethod.bind(this),
+            });
+            this.setupTransportHandlers(httpTransportInstance);
+            this.transports.push(httpTransportInstance);
+        }
+    }
+    setupTransportHandlers(transport) {
+        transport.on("connection", (client) => {
+            // Track connection time for duration calculation
+            const connectTime = Date.now();
+            this.clientConnectedAt.set(client.id, connectTime);
+            this.emit("client:connected", {
+                clientId: client.id,
+            });
+            // Emit DevTools event
+            if (devToolsEmitter.hasSubscribers()) {
+                devToolsEmitter.emitEvent({
+                    type: "client_connected",
+                    executionId: this.config.id,
+                    clientId: client.id,
+                    transport: transport.type,
+                    sequence: this.devToolsSequence++,
+                    timestamp: connectTime,
+                });
+            }
+        });
+        transport.on("disconnect", (clientId, reason) => {
+            // Calculate connection duration
+            const connectedAt = this.clientConnectedAt.get(clientId);
+            const durationMs = connectedAt ? Date.now() - connectedAt : 0;
+            this.clientConnectedAt.delete(clientId);
+            // Clean up subscriptions
+            this.sessions.unsubscribeAll(clientId);
+            this.emit("client:disconnected", {
+                clientId,
+                reason,
+            });
+            // Emit DevTools event
+            if (devToolsEmitter.hasSubscribers()) {
+                devToolsEmitter.emitEvent({
+                    type: "client_disconnected",
+                    executionId: this.config.id,
+                    clientId,
+                    reason,
+                    durationMs,
+                    sequence: this.devToolsSequence++,
+                    timestamp: Date.now(),
+                });
+            }
+        });
+        transport.on("message", async (clientId, message) => {
+            if (message.type === "req") {
+                await this.handleTransportRequest(transport, clientId, message);
+            }
+        });
+        transport.on("error", (error) => {
+            this.emit("error", error);
+        });
+    }
+    /**
+     * Start the gateway (standalone mode only)
+     */
+    async start() {
+        if (this.embedded) {
+            throw new Error("Cannot call start() in embedded mode - use handleRequest() instead");
+        }
+        if (this.isRunning) {
+            throw new Error("Gateway is already running");
+        }
+        // Initialize channel adapters
+        if (this.config.channels) {
+            const context = this.createGatewayContext();
+            for (const channel of this.config.channels) {
+                await channel.initialize(context);
+            }
+        }
+        // Start all transports
+        await Promise.all(this.transports.map((t) => t.start()));
+        this.startTime = new Date();
+        this.isRunning = true;
+        this.emit("started", {
+            port: this.config.port,
+            host: this.config.host,
+        });
+    }
+    /**
+     * Stop the gateway
+     */
+    async stop() {
+        if (!this.isRunning && !this.embedded)
+            return;
+        // Destroy channel adapters
+        if (this.config.channels) {
+            for (const channel of this.config.channels) {
+                await channel.destroy();
+            }
+        }
+        // Stop all transports (if any)
+        await Promise.all(this.transports.map((t) => t.stop()));
+        this.isRunning = false;
+        this.startTime = null;
+        this.emit("stopped", {});
+    }
+    /**
+     * Alias for stop() - useful for embedded mode cleanup
+     */
+    async close() {
+        return this.stop();
+    }
+    /**
+     * Get gateway status
+     */
+    get status() {
+        return {
+            id: this.config.id,
+            uptime: this.startTime ? Math.floor((Date.now() - this.startTime.getTime()) / 1000) : 0,
+            clients: this.transports.reduce((sum, t) => sum + t.clientCount, 0),
+            sessions: this.sessions.size,
+            apps: this.registry.ids(),
+        };
+    }
+    /**
+     * Check if running
+     */
+    get running() {
+        return this.isRunning;
+    }
+    /**
+     * Get the gateway ID
+     */
+    get id() {
+        return this.config.id;
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Embedded Mode: handleRequest()
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Handle an HTTP request (embedded mode).
+     * This is the main entry point when Gateway is embedded in an external framework.
+     *
+     * @param req - Node.js IncomingMessage (or Express/Koa/etc request)
+     * @param res - Node.js ServerResponse (or Express/Koa/etc response)
+     * @returns Promise that resolves when request is handled (may reject on error)
+     *
+     * @example
+     * ```typescript
+     * // Express middleware
+     * app.use("/api", (req, res, next) => {
+     *   gateway.handleRequest(req, res).catch(next);
+     * });
+     * ```
+     */
+    async handleRequest(req, res) {
+        // Set CORS headers
+        const origin = this.config.httpCorsOrigin ?? "*";
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+        res.setHeader("Access-Control-Allow-Credentials", "true");
+        // Handle preflight
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Extract path (handle Express mounting where path is already stripped)
+        const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+        const prefix = this.config.httpPathPrefix ?? "";
+        const path = url.pathname.replace(prefix, "") || "/";
+        log.debug({ method: req.method, url: req.url, path }, "handleRequest");
+        // Route requests - all framework-level endpoints
+        switch (path) {
+            case "/events":
+                return this.handleSSE(req, res);
+            case "/send":
+                return this.handleSend(req, res);
+            case "/invoke":
+                return this.handleInvoke(req, res);
+            case "/subscribe":
+                return this.handleSubscribe(req, res);
+            case "/abort":
+                return this.handleAbort(req, res);
+            case "/close":
+                return this.handleCloseEndpoint(req, res);
+            case "/channel":
+            case "/channel/subscribe":
+            case "/channel/publish":
+                return this.handleChannel(req, res);
+        }
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // HTTP Handlers (used by both handleRequest and HTTPTransport)
+    // ══════════════════════════════════════════════════════════════════════════
+    async handleSSE(req, res) {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+        const token = extractToken(req) ?? url.searchParams.get("token") ?? undefined;
+        const authResult = await validateAuth(token, this.config.auth);
+        if (!authResult.valid) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Authentication failed" }));
+            return;
+        }
+        // Setup SSE response
+        setSSEHeaders(res);
+        const clientId = url.searchParams.get("clientId") ?? `client-${Date.now().toString(36)}`;
+        // Register SSE client for channel forwarding
+        const connectTime = Date.now();
+        this.sseClients.set(clientId, res);
+        this.clientConnectedAt.set(clientId, connectTime);
+        // Emit DevTools event for connection tracking
+        if (devToolsEmitter.hasSubscribers()) {
+            devToolsEmitter.emitEvent({
+                type: "client_connected",
+                executionId: this.config.id,
+                clientId,
+                transport: "sse",
+                sequence: this.devToolsSequence++,
+                timestamp: connectTime,
+            });
+        }
+        // Send connection confirmation
+        // Client expects type: "connection" to resolve the connection promise
+        const connectData = JSON.stringify({
+            type: "connection",
+            connectionId: clientId,
+            subscriptions: [],
+        });
+        res.write(`data: ${connectData}\n\n`);
+        // Keep connection alive with periodic heartbeat
+        const heartbeat = setInterval(() => {
+            res.write(":heartbeat\n\n");
+        }, 30000);
+        res.on("close", () => {
+            clearInterval(heartbeat);
+            this.sessions.unsubscribeAll(clientId);
+            this.sseClients.delete(clientId);
+            this.cleanupClientChannelSubscriptions(clientId);
+            // Emit DevTools event for disconnection tracking
+            const connectedAt = this.clientConnectedAt.get(clientId);
+            const durationMs = connectedAt ? Date.now() - connectedAt : 0;
+            this.clientConnectedAt.delete(clientId);
+            if (devToolsEmitter.hasSubscribers()) {
+                devToolsEmitter.emitEvent({
+                    type: "client_disconnected",
+                    executionId: this.config.id,
+                    clientId,
+                    reason: "Connection closed",
+                    durationMs,
+                    sequence: this.devToolsSequence++,
+                    timestamp: Date.now(),
+                });
+            }
+        });
+    }
+    /**
+     * Clean up channel subscriptions for a disconnected client.
+     */
+    cleanupClientChannelSubscriptions(clientId) {
+        for (const [key, clientIds] of this.channelSubscriptions.entries()) {
+            clientIds.delete(clientId);
+            // If no more subscribers for this session:channel, unsubscribe from core channel
+            if (clientIds.size === 0) {
+                this.channelSubscriptions.delete(key);
+                const unsubscribe = this.coreChannelUnsubscribes.get(key);
+                if (unsubscribe) {
+                    unsubscribe();
+                    this.coreChannelUnsubscribes.delete(key);
+                }
+            }
+        }
+    }
+    async handleSend(req, res) {
+        log.debug({ method: req.method, url: req.url }, "handleSend: START");
+        if (req.method !== "POST") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Method not allowed" }));
+            return;
+        }
+        const token = extractToken(req);
+        const authResult = await validateAuth(token, this.config.auth);
+        if (!authResult.valid) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Authentication failed" }));
+            return;
+        }
+        const body = await this.parseBody(req);
+        log.debug({ body }, "handleSend: parsed body");
+        if (!body) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid request body" }));
+            return;
+        }
+        const sessionId = body.sessionId ?? "main";
+        const rawMessages = body.messages;
+        log.debug({ sessionId, hasMessages: !!rawMessages }, "handleSend: extracted params");
+        if (!Array.isArray(rawMessages) || rawMessages.length === 0) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "Invalid message format. Expected { messages: Message[] }",
+            }));
+            return;
+        }
+        // Use the first message for the directSend path (single-message execution)
+        const rawMessage = rawMessages[0];
+        const message = {
+            role: rawMessage.role,
+            content: rawMessage.content,
+            ...(rawMessage.id && { id: rawMessage.id }),
+            ...(rawMessage.metadata && { metadata: rawMessage.metadata }),
+        };
+        // Setup streaming response
+        setSSEHeaders(res);
+        try {
+            log.debug({ sessionId }, "handleSend: calling directSend");
+            const events = this.directSend(sessionId, message);
+            for await (const event of events) {
+                log.debug({ eventType: event.type }, "handleSend: got event from directSend");
+                const sseData = {
+                    type: event.type,
+                    sessionId,
+                    ...(event.data && typeof event.data === "object" ? event.data : {}),
+                };
+                res.write(`data: ${JSON.stringify(sseData)}\n\n`);
+            }
+            log.debug({ sessionId }, "handleSend: directSend complete, sending execution_end");
+            res.write(`data: ${JSON.stringify({ type: "execution_end", sessionId })}\n\n`);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            console.error("[Gateway handleSend ERROR]", errorMessage, "\n", errorStack);
+            log.error({ errorMessage, errorStack, sessionId }, "handleSend: ERROR in directSend");
+            res.write(`data: ${JSON.stringify({ type: "error", error: errorMessage, sessionId })}\n\n`);
+        }
+        finally {
+            res.end();
+        }
+    }
+    async handleInvoke(req, res) {
+        if (req.method !== "POST") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Method not allowed" }));
+            return;
+        }
+        const token = extractToken(req);
+        const authResult = await validateAuth(token, this.config.auth);
+        if (!authResult.valid) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Authentication failed" }));
+            return;
+        }
+        const body = await this.parseBody(req);
+        if (!body) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid request body" }));
+            return;
+        }
+        const method = body.method;
+        const params = (body.params ?? {});
+        if (!method || typeof method !== "string") {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "method is required" }));
+            return;
+        }
+        log.debug({ method, params }, "handleInvoke");
+        const requestId = `req-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+        const startTime = Date.now();
+        const sessionKey = params.sessionId;
+        // Emit DevTools request event
+        if (devToolsEmitter.hasSubscribers()) {
+            devToolsEmitter.emitEvent({
+                type: "gateway_request",
+                executionId: this.config.id,
+                requestId,
+                method,
+                sessionKey,
+                params,
+                sequence: this.devToolsSequence++,
+                timestamp: startTime,
+            });
+        }
+        try {
+            const result = await this.invokeMethod(method, params, authResult.user);
+            log.debug({ method, result }, "handleInvoke: completed");
+            // Emit DevTools response event
+            if (devToolsEmitter.hasSubscribers()) {
+                devToolsEmitter.emitEvent({
+                    type: "gateway_response",
+                    executionId: this.config.id,
+                    requestId,
+                    method,
+                    ok: true,
+                    latencyMs: Date.now() - startTime,
+                    sequence: this.devToolsSequence++,
+                    timestamp: Date.now(),
+                });
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(result));
+        }
+        catch (error) {
+            log.error({ method, error }, "handleInvoke: failed");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Emit DevTools response event for error
+            if (devToolsEmitter.hasSubscribers()) {
+                devToolsEmitter.emitEvent({
+                    type: "gateway_response",
+                    executionId: this.config.id,
+                    requestId,
+                    method,
+                    ok: false,
+                    error: { code: "INVOKE_ERROR", message: errorMessage },
+                    latencyMs: Date.now() - startTime,
+                    sequence: this.devToolsSequence++,
+                    timestamp: Date.now(),
+                });
+            }
+            const statusCode = isGuardError(error) ? 403 : 400;
+            res.writeHead(statusCode, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: errorMessage }));
+        }
+    }
+    async handleSubscribe(req, res) {
+        if (req.method !== "POST") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Method not allowed" }));
+            return;
+        }
+        const token = extractToken(req);
+        const authResult = await validateAuth(token, this.config.auth);
+        if (!authResult.valid) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Authentication failed" }));
+            return;
+        }
+        const body = await this.parseBody(req);
+        if (!body) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid request body" }));
+            return;
+        }
+        // Support both formats:
+        // - { sessionId, clientId } - simple format
+        // - { connectionId, add: [...], remove: [...] } - client format
+        const clientId = (body.clientId ?? body.connectionId);
+        if (!clientId) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "clientId or connectionId is required" }));
+            return;
+        }
+        // Handle additions
+        const addSessionIds = [];
+        if (body.sessionId) {
+            addSessionIds.push(body.sessionId);
+        }
+        if (Array.isArray(body.add)) {
+            addSessionIds.push(...body.add);
+        }
+        // Handle removals
+        const removeSessionIds = [];
+        if (Array.isArray(body.remove)) {
+            removeSessionIds.push(...body.remove);
+        }
+        if (addSessionIds.length === 0 && removeSessionIds.length === 0) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "sessionId, add[], or remove[] is required" }));
+            return;
+        }
+        // Process subscriptions
+        for (const sessionId of addSessionIds) {
+            await this.sessions.subscribe(sessionId, clientId);
+        }
+        for (const sessionId of removeSessionIds) {
+            this.sessions.unsubscribe(sessionId, clientId);
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true }));
+    }
+    async handleAbort(req, res) {
+        if (req.method !== "POST") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Method not allowed" }));
+            return;
+        }
+        const token = extractToken(req);
+        const authResult = await validateAuth(token, this.config.auth);
+        if (!authResult.valid) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Authentication failed" }));
+            return;
+        }
+        const body = await this.parseBody(req);
+        if (!body) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid request body" }));
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true }));
+    }
+    async handleCloseEndpoint(req, res) {
+        if (req.method !== "POST") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Method not allowed" }));
+            return;
+        }
+        const token = extractToken(req);
+        const authResult = await validateAuth(token, this.config.auth);
+        if (!authResult.valid) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Authentication failed" }));
+            return;
+        }
+        const body = await this.parseBody(req);
+        if (!body?.sessionId) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "sessionId is required" }));
+            return;
+        }
+        await this.sessions.close(body.sessionId);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true }));
+    }
+    /**
+     * Channel endpoint - handles channel pub/sub operations.
+     */
+    async handleChannel(req, res) {
+        if (req.method !== "POST") {
+            res.writeHead(405, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Method not allowed" }));
+            return;
+        }
+        const token = extractToken(req);
+        const authResult = await validateAuth(token, this.config.auth);
+        if (!authResult.valid) {
+            res.writeHead(401, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Authentication failed" }));
+            return;
+        }
+        const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+        const prefix = this.config.httpPathPrefix ?? "";
+        const path = url.pathname.replace(prefix, "") || "/";
+        const body = await this.parseBody(req);
+        if (!body) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Invalid request body" }));
+            return;
+        }
+        const sessionId = body.sessionId;
+        const channelName = body.channel;
+        const clientId = body.clientId;
+        if (!sessionId || !channelName) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "sessionId and channel are required" }));
+            return;
+        }
+        if (path === "/channel/subscribe" || path === "/channel") {
+            await this.subscribeToChannel(sessionId, channelName, clientId);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true }));
+        }
+        else if (path === "/channel/publish") {
+            const payload = body.payload;
+            await this.publishToChannel(sessionId, channelName, payload);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true }));
+        }
+        else {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Unknown channel operation" }));
+        }
+    }
+    /**
+     * Subscribe a client to a session's channel.
+     * Sets up forwarding from core session channel to SSE clients.
+     */
+    async subscribeToChannel(sessionId, channelName, clientId) {
+        const subscriptionKey = `${sessionId}:${channelName}`;
+        // Add client to subscription list (if provided)
+        if (clientId) {
+            let clientIds = this.channelSubscriptions.get(subscriptionKey);
+            if (!clientIds) {
+                clientIds = new Set();
+                this.channelSubscriptions.set(subscriptionKey, clientIds);
+            }
+            clientIds.add(clientId);
+        }
+        // If we already have a core channel subscription for this session:channel, we're done
+        if (this.coreChannelUnsubscribes.has(subscriptionKey)) {
+            return;
+        }
+        // Get or create the managed session and core session
+        const managedSession = await this.sessions.getOrCreate(sessionId);
+        if (!managedSession.coreSession) {
+            // Use sessionName (without app prefix) for App - Gateway handles routing
+            managedSession.coreSession = await managedSession.appInfo.app.session(managedSession.sessionName);
+        }
+        // Subscribe to the core session's channel and forward events to SSE clients
+        const coreChannel = managedSession.coreSession.channel(channelName);
+        const unsubscribe = coreChannel.subscribe((event) => {
+            this.forwardChannelEvent(subscriptionKey, event);
+        });
+        this.coreChannelUnsubscribes.set(subscriptionKey, unsubscribe);
+        log.debug({ sessionId, channelName }, "Channel forwarding established");
+    }
+    /**
+     * Forward a channel event to all subscribed SSE clients.
+     */
+    forwardChannelEvent(subscriptionKey, event) {
+        const clientIds = this.channelSubscriptions.get(subscriptionKey);
+        if (!clientIds || clientIds.size === 0) {
+            return;
+        }
+        // subscriptionKey format is "sessionId:channelName" where sessionId can contain ":"
+        // e.g., "assistant:default:todo-list" → sessionId="assistant:default", channel="todo-list"
+        // Extract sessionId by removing the last segment (channelName)
+        const lastColonIndex = subscriptionKey.lastIndexOf(":");
+        const sessionId = subscriptionKey.substring(0, lastColonIndex);
+        const sseData = JSON.stringify({
+            type: "channel",
+            sessionId,
+            channel: event.channel,
+            event: {
+                type: event.type,
+                payload: event.payload,
+                metadata: event.metadata,
+            },
+        });
+        for (const clientId of clientIds) {
+            const res = this.sseClients.get(clientId);
+            if (res && !res.writableEnded) {
+                res.write(`data: ${sseData}\n\n`);
+            }
+        }
+    }
+    /**
+     * Publish an event to a session's channel.
+     */
+    async publishToChannel(sessionId, channelName, payload) {
+        const managedSession = await this.sessions.getOrCreate(sessionId);
+        if (!managedSession.coreSession) {
+            // Use sessionName (without app prefix) for App - Gateway handles routing
+            managedSession.coreSession = await managedSession.appInfo.app.session(managedSession.sessionName);
+        }
+        const coreChannel = managedSession.coreSession.channel(channelName);
+        coreChannel.publish({
+            type: "message",
+            channel: channelName,
+            payload,
+        });
+    }
+    parseBody(req) {
+        // If body already parsed by Express middleware, use it
+        if (req.body && typeof req.body === "object") {
+            return Promise.resolve(req.body);
+        }
+        // Otherwise, read from stream
+        return new Promise((resolve) => {
+            let body = "";
+            req.on("data", (chunk) => {
+                body += chunk.toString();
+            });
+            req.on("end", () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+            req.on("error", () => {
+                resolve(null);
+            });
+        });
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Transport Request Handling (standalone mode)
+    // ══════════════════════════════════════════════════════════════════════════
+    async handleTransportRequest(transport, clientId, request) {
+        const client = transport.getClient(clientId);
+        if (!client)
+            return;
+        const startTime = Date.now();
+        const requestId = request.id;
+        const sessionKey = request.params?.sessionId;
+        // Emit DevTools request event
+        if (devToolsEmitter.hasSubscribers()) {
+            devToolsEmitter.emitEvent({
+                type: "gateway_request",
+                executionId: this.config.id,
+                requestId,
+                method: request.method,
+                sessionKey,
+                params: request.params,
+                clientId,
+                sequence: this.devToolsSequence++,
+                timestamp: startTime,
+            });
+        }
+        try {
+            const result = await this.executeMethod(transport, clientId, request.method, request.params);
+            client.send({
+                type: "res",
+                id: request.id,
+                ok: true,
+                payload: result,
+            });
+            // Emit DevTools response event
+            if (devToolsEmitter.hasSubscribers()) {
+                devToolsEmitter.emitEvent({
+                    type: "gateway_response",
+                    executionId: this.config.id,
+                    requestId,
+                    ok: true,
+                    latencyMs: Date.now() - startTime,
+                    sequence: this.devToolsSequence++,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        catch (error) {
+            const errorCode = "METHOD_ERROR";
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            client.send({
+                type: "res",
+                id: request.id,
+                ok: false,
+                error: {
+                    code: errorCode,
+                    message: errorMessage,
+                },
+            });
+            // Emit DevTools response event with error
+            if (devToolsEmitter.hasSubscribers()) {
+                devToolsEmitter.emitEvent({
+                    type: "gateway_response",
+                    executionId: this.config.id,
+                    requestId,
+                    ok: false,
+                    latencyMs: Date.now() - startTime,
+                    error: {
+                        code: errorCode,
+                        message: errorMessage,
+                    },
+                    sequence: this.devToolsSequence++,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+    }
+    async executeMethod(transport, clientId, method, params) {
+        // Built-in methods first
+        switch (method) {
+            case "send":
+                return this.handleSendMethod(transport, clientId, params);
+            case "abort":
+                return this.handleAbortMethod(params);
+            case "status":
+                return this.handleStatusMethod(params);
+            case "history":
+                return this.handleHistoryMethod(params);
+            case "reset":
+                return this.handleResetMethod(params);
+            case "close":
+                return this.handleCloseMethod(params);
+            case "apps":
+                return this.handleAppsMethod();
+            case "sessions":
+                return this.handleSessionsMethod();
+            case "subscribe":
+                return this.handleSubscribeMethod(transport, clientId, params);
+            case "unsubscribe":
+                return this.handleUnsubscribeMethod(transport, clientId, params);
+        }
+        // Check custom methods
+        const procedure = this.getMethodProcedure(method);
+        if (procedure) {
+            return this.executeCustomMethod(transport, clientId, method, params);
+        }
+        throw new Error(`Unknown method: ${method}`);
+    }
+    /**
+     * Execute a custom method within Agentick ALS context.
+     */
+    async executeCustomMethod(transport, clientId, method, params) {
+        const client = transport.getClient(clientId);
+        const sessionId = params.sessionId;
+        // Build metadata: gateway fields + client auth metadata + per-request metadata
+        const metadata = {
+            sessionId,
+            clientId,
+            gatewayId: this.config.id,
+            method,
+            ...client?.state.metadata,
+            ...params.metadata,
+        };
+        // Create kernel context
+        const ctx = Context.create({
+            user: client?.state.user,
+            metadata,
+        });
+        // Get the procedure
+        const procedure = this.getMethodProcedure(method);
+        if (!procedure) {
+            throw new Error(`Unknown method: ${method}`);
+        }
+        // Execute within context
+        // Procedure handles: context forking, middleware (guards), schema validation, metrics
+        const result = await Context.run(ctx, async () => {
+            const handle = await procedure(params);
+            return handle.result;
+        });
+        // Handle streaming results
+        if (result && typeof result === "object" && Symbol.asyncIterator in result) {
+            const generator = result;
+            const chunks = [];
+            for await (const chunk of generator) {
+                // Emit chunk to subscribers
+                if (sessionId) {
+                    this.sendEventToSubscribers(sessionId, "method:chunk", {
+                        method,
+                        chunk,
+                    });
+                }
+                chunks.push(chunk);
+            }
+            // Emit end event
+            if (sessionId) {
+                this.sendEventToSubscribers(sessionId, "method:end", { method });
+            }
+            return { streaming: true, chunks };
+        }
+        return result;
+    }
+    async handleSendMethod(transport, clientId, params) {
+        const { sessionId, message } = params;
+        // Get or create managed session (SessionManager emits DevTools event if new)
+        const managedSession = await this.sessions.getOrCreate(sessionId, clientId);
+        // Auto-subscribe sender to session events
+        // Subscribe with the ORIGINAL sessionId so events can be matched by clients
+        const client = transport.getClient(clientId);
+        if (client) {
+            client.state.subscriptions.add(sessionId);
+            await this.sessions.subscribe(sessionId, clientId);
+        }
+        // Mark session as active (internal, uses normalized ID)
+        this.sessions.setActive(managedSession.state.id, true);
+        // Get or create core session from app
+        if (!managedSession.coreSession) {
+            // Use sessionName (without app prefix) for App - Gateway handles routing
+            managedSession.coreSession = await managedSession.appInfo.app.session(managedSession.sessionName);
+        }
+        // Stream execution to subscribers
+        const messageId = `msg-${Date.now().toString(36)}`;
+        // Execute in background and stream events
+        // Use ORIGINAL sessionId for events so clients can match them
+        this.executeAndStream(sessionId, managedSession.coreSession, message).catch((error) => {
+            this.sendEventToSubscribers(sessionId, "error", {
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+        // Increment message count (SessionManager emits DevTools event)
+        this.sessions.incrementMessageCount(managedSession.state.id, clientId);
+        this.emit("session:message", {
+            sessionId: managedSession.state.id,
+            role: "user",
+            content: message,
+        });
+        return { messageId };
+    }
+    /**
+     * Execute a message and stream events to subscribers.
+     *
+     * @param sessionId - The session key as provided by client (may be unnormalized)
+     * @param coreSession - The core session instance
+     * @param messageText - The message text to send
+     *
+     * IMPORTANT: Uses the original sessionId for events to ensure client matching.
+     */
+    async executeAndStream(sessionId, coreSession, messageText) {
+        try {
+            // Construct a proper Message object from the string
+            const message = {
+                role: "user",
+                content: [{ type: "text", text: messageText }],
+            };
+            const execution = await coreSession.send({ messages: [message] });
+            for await (const event of execution) {
+                // Use the original sessionId for events (ensures client matching)
+                this.sendEventToSubscribers(sessionId, event.type, event);
+            }
+            // Send execution_end event
+            this.sendEventToSubscribers(sessionId, "execution_end", {});
+        }
+        finally {
+            this.sessions.setActive(sessionId, false);
+        }
+    }
+    sendEventToSubscribers(sessionId, eventType, data) {
+        const subscribers = this.sessions.getSubscribers(sessionId);
+        // Send to all clients across all transports (standalone mode)
+        for (const transport of this.transports) {
+            for (const clientId of subscribers) {
+                const client = transport.getClient(clientId);
+                if (client) {
+                    client.send({
+                        type: "event",
+                        event: eventType,
+                        sessionId,
+                        data,
+                    });
+                }
+            }
+        }
+        // Also send to SSE clients (embedded mode)
+        for (const clientId of subscribers) {
+            const res = this.sseClients.get(clientId);
+            if (res && !res.writableEnded) {
+                const sseData = JSON.stringify({
+                    type: eventType,
+                    sessionId,
+                    ...(data && typeof data === "object" ? data : {}),
+                });
+                res.write(`data: ${sseData}\n\n`);
+            }
+        }
+    }
+    /**
+     * Direct send handler for HTTP transport.
+     * Returns an async generator that yields events for streaming.
+     * Accepts full Message object to support multimodal content (images, audio, video, docs).
+     *
+     * IMPORTANT: Uses the original sessionId (as provided by client) for events,
+     * not the normalized internal ID. This ensures clients can match events to their sessions.
+     */
+    async *directSend(sessionId, message) {
+        // Get or create managed session
+        const managedSession = await this.sessions.getOrCreate(sessionId);
+        log.debug({
+            sessionId,
+            sessionName: managedSession.sessionName,
+            stateId: managedSession.state.id,
+            hasCoreSession: !!managedSession.coreSession,
+        }, "directSend: got managed session");
+        // Mark session as active
+        this.sessions.setActive(managedSession.state.id, true);
+        // Get or create core session from app
+        if (!managedSession.coreSession) {
+            // Use sessionName (without app prefix) for App - Gateway handles routing
+            log.debug({ sessionName: managedSession.sessionName }, "directSend: creating core session");
+            managedSession.coreSession = await managedSession.appInfo.app.session(managedSession.sessionName);
+            log.debug({ coreSessionId: managedSession.coreSession.id }, "directSend: created core session");
+        }
+        // Check session status before sending
+        const coreSession = managedSession.coreSession;
+        log.debug({
+            coreSessionId: coreSession.id,
+            status: coreSession._status,
+        }, "directSend: core session status before send");
+        try {
+            const execution = await managedSession.coreSession.send({ messages: [message] });
+            // Increment message count
+            this.sessions.incrementMessageCount(managedSession.state.id);
+            // Extract text content for logging (first text block if any)
+            const textContent = message.content
+                .filter((b) => b.type === "text")
+                .map((b) => b.text)
+                .join(" ");
+            this.emit("session:message", {
+                sessionId: managedSession.state.id,
+                role: "user",
+                content: textContent || "[multimodal content]",
+            });
+            for await (const event of execution) {
+                // Use the ORIGINAL sessionId for events (not normalized managedSession.state.id)
+                // This ensures clients can match events to sessions by the key they used
+                this.sendEventToSubscribers(sessionId, event.type, event);
+                // Yield event for HTTP streaming
+                yield { type: event.type, data: event };
+            }
+        }
+        finally {
+            this.sessions.setActive(managedSession.state.id, false);
+        }
+    }
+    /**
+     * Invoke a custom method directly (for HTTP transport).
+     * Called with pre-authenticated user context.
+     */
+    async invokeMethod(method, params, user) {
+        const procedure = this.getMethodProcedure(method);
+        if (!procedure) {
+            throw new Error(`Unknown method: ${method}`);
+        }
+        const sessionId = params.sessionId;
+        // Get or create session to access channels (if sessionId provided)
+        let channels = undefined;
+        if (sessionId) {
+            const managedSession = await this.sessions.getOrCreate(sessionId);
+            if (!managedSession.coreSession) {
+                // Use sessionName (without app prefix) for App - Gateway handles routing
+                managedSession.coreSession = await managedSession.appInfo.app.session(managedSession.sessionName);
+            }
+            channels = createChannelServiceFromSession(managedSession.coreSession, this.config.id);
+        }
+        // Build metadata
+        const metadata = {
+            sessionId,
+            gatewayId: this.config.id,
+            method,
+            ...params.metadata,
+        };
+        // Create kernel context with channels for pub/sub
+        const ctx = Context.create({
+            user,
+            metadata,
+            channels,
+        });
+        // Execute within context
+        // Procedures return ExecutionHandle by default - access .result to get the handler's return value
+        const result = await Context.run(ctx, async () => {
+            const handle = await procedure(params);
+            return handle.result;
+        });
+        // Handle streaming results (collect all chunks)
+        if (result && typeof result === "object" && Symbol.asyncIterator in result) {
+            const iterable = result;
+            const chunks = [];
+            for await (const chunk of iterable) {
+                chunks.push(chunk);
+            }
+            return { streaming: true, chunks };
+        }
+        return result;
+    }
+    async handleAbortMethod(params) {
+        const session = this.sessions.get(params.sessionId);
+        if (!session) {
+            throw new Error(`Session not found: ${params.sessionId}`);
+        }
+    }
+    handleStatusMethod(params) {
+        const result = {
+            gateway: this.status,
+        };
+        if (params.sessionId) {
+            const session = this.sessions.get(params.sessionId);
+            if (session) {
+                result.session = {
+                    id: session.state.id,
+                    appId: session.state.appId,
+                    messageCount: session.state.messageCount,
+                    createdAt: session.state.createdAt.toISOString(),
+                    lastActivityAt: session.state.lastActivityAt.toISOString(),
+                    isActive: session.state.isActive,
+                };
+            }
+        }
+        return result;
+    }
+    async handleHistoryMethod(params) {
+        return { messages: [], hasMore: false };
+    }
+    async handleResetMethod(params) {
+        // SessionManager.reset() emits DevTools event
+        await this.sessions.reset(params.sessionId);
+        this.emit("session:closed", { sessionId: params.sessionId });
+    }
+    async handleCloseMethod(params) {
+        // SessionManager.close() emits DevTools event
+        await this.sessions.close(params.sessionId);
+        this.emit("session:closed", { sessionId: params.sessionId });
+    }
+    handleAppsMethod() {
+        return {
+            apps: this.registry.all().map((appInfo) => ({
+                id: appInfo.id,
+                name: appInfo.name ?? appInfo.id,
+                description: appInfo.description,
+                isDefault: appInfo.isDefault,
+            })),
+        };
+    }
+    handleSessionsMethod() {
+        return {
+            sessions: this.sessions.all().map((s) => ({
+                id: s.state.id,
+                appId: s.state.appId,
+                createdAt: s.state.createdAt.toISOString(),
+                lastActivityAt: s.state.lastActivityAt.toISOString(),
+                messageCount: s.state.messageCount,
+            })),
+        };
+    }
+    async handleSubscribeMethod(transport, clientId, params) {
+        const client = transport.getClient(clientId);
+        if (client) {
+            client.state.subscriptions.add(params.sessionId);
+            await this.sessions.subscribe(params.sessionId, clientId);
+        }
+    }
+    handleUnsubscribeMethod(transport, clientId, params) {
+        const client = transport.getClient(clientId);
+        if (client) {
+            client.state.subscriptions.delete(params.sessionId);
+            this.sessions.unsubscribe(params.sessionId, clientId);
+        }
+    }
+    createGatewayContext() {
+        return {
+            sendToSession: async (sessionId, message) => {
+                // Internal send (from channels)
+                const managedSession = await this.sessions.getOrCreate(sessionId);
+                if (!managedSession.coreSession) {
+                    // Use sessionName (without app prefix) for App - Gateway handles routing
+                    managedSession.coreSession = await managedSession.appInfo.app.session(managedSession.sessionName);
+                }
+                await this.executeAndStream(managedSession.state.id, managedSession.coreSession, message);
+            },
+            getApps: () => this.registry.ids(),
+            getSession: (sessionId) => {
+                const managedSession = this.sessions.get(sessionId);
+                if (!managedSession) {
+                    throw new Error(`Session not found: ${sessionId}`);
+                }
+                return {
+                    id: managedSession.state.id,
+                    appId: managedSession.state.appId,
+                    send: async function* (message) {
+                        yield { type: "message_end", data: {} };
+                    },
+                };
+            },
+        };
+    }
+}
+/**
+ * Create a gateway instance
+ */
+export function createGateway(config) {
+    return new Gateway(config);
+}
+//# sourceMappingURL=gateway.js.map