@essentialai/cogent-server 2.0.0

package/dist/app.d.ts

@@ -0,0 +1,38 @@
+import { Hono } from "hono";
+import type { Server } from "node:http";
+import type { Http2Server, Http2SecureServer } from "node:http2";
+import type { SessionStore } from "./services/session-store.js";
+import type { AuthService } from "./services/auth-service.js";
+import type { ConnectionManager } from "./services/connection-manager.js";
+import type { MessageQueueService } from "./services/message-queue.js";
+import type { StatsService } from "./services/stats-service.js";
+import type { ServerEnv } from "./types.js";
+/** Dependencies required to create the Hono app. */
+export interface AppDeps {
+    sessionStore: SessionStore;
+    authService: AuthService;
+    startTime: number;
+    maxMessages: number;
+    connectionManager: ConnectionManager;
+    messageQueue: MessageQueueService;
+    statsService: StatsService;
+    adminPassword: string | null;
+    heartbeatIntervalMs: number;
+    heartbeatMaxMissed: number;
+}
+/** Return type of createApp -- app + injectWebSocket for index.ts wiring. */
+export interface AppResult {
+    app: Hono<ServerEnv>;
+    injectWebSocket: (server: Server | Http2Server | Http2SecureServer) => void;
+}
+/**
+ * Create and configure the Hono app with all middleware and routes.
+ *
+ * Uses an app factory pattern so the app can be tested via app.request()
+ * without starting a real HTTP server.
+ *
+ * Returns both the Hono app and the injectWebSocket function that must
+ * be called with the HTTP server after serve() -- see RESEARCH.md Pitfall 2.
+ */
+export declare function createApp(deps: AppDeps): AppResult;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAa5C,oDAAoD;AACpD,MAAM,WAAW,OAAO;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,YAAY,EAAE,mBAAmB,CAAC;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACrB,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,iBAAiB,KAAK,IAAI,CAAC;CAC7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CA6DlD"}

package/dist/app.js

@@ -0,0 +1,60 @@
+import { Hono } from "hono";
+import { createNodeWebSocket } from "@hono/node-ws";
+import { requestLogger } from "./middleware/request-logger.js";
+import { errorHandler } from "./middleware/error-handler.js";
+import { notFoundHandler } from "./middleware/not-found.js";
+import { createSessionRoutes } from "./routes/sessions.js";
+import { createHealthRoutes } from "./routes/health.js";
+import { createPeerRoutes } from "./routes/peers.js";
+import { createMessageRoutes } from "./routes/messages.js";
+import { createPollRoutes } from "./routes/poll.js";
+import { createUiRoutes } from "./routes/ui.js";
+import { createWsAuthMiddleware } from "./middleware/ws-auth.js";
+import { createWsHandler } from "./ws/handler.js";
+/**
+ * Create and configure the Hono app with all middleware and routes.
+ *
+ * Uses an app factory pattern so the app can be tested via app.request()
+ * without starting a real HTTP server.
+ *
+ * Returns both the Hono app and the injectWebSocket function that must
+ * be called with the HTTP server after serve() -- see RESEARCH.md Pitfall 2.
+ */
+export function createApp(deps) {
+    const { sessionStore, authService, startTime, maxMessages, connectionManager, messageQueue, statsService, adminPassword, heartbeatIntervalMs, heartbeatMaxMissed, } = deps;
+    const app = new Hono();
+    const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
+    // --- Error handling ---
+    app.onError(errorHandler);
+    app.notFound(notFoundHandler);
+    // --- WebSocket route (registered BEFORE request logger to avoid header conflicts) ---
+    // Auth middleware reads token from query param; runs before WS upgrade handshake.
+    app.get("/ws/:sessionId", createWsAuthMiddleware(sessionStore, authService), upgradeWebSocket((c) => {
+        const sessionId = c.get("sessionId");
+        const peerId = c.req.query("peerId");
+        return createWsHandler(sessionId, peerId, {
+            connectionManager,
+            messageQueue,
+            sessionStore,
+            heartbeatIntervalMs,
+            heartbeatMaxMissed,
+        });
+    }));
+    // --- Global middleware (applied after WS route to avoid header conflicts per RESEARCH.md Pitfall 1) ---
+    app.use("*", requestLogger());
+    // --- UI routes (after requestLogger, before API routes) ---
+    const uiRoutes = createUiRoutes({ statsService, adminPassword, sessionStore, connectionManager });
+    app.route("/", uiRoutes);
+    // --- Unauthenticated routes ---
+    app.route("/api/sessions", createSessionRoutes(sessionStore, authService));
+    app.route("/api/health", createHealthRoutes(sessionStore, startTime, connectionManager));
+    // --- Authenticated routes ---
+    // Peer routes: /:sessionId/peers (POST, GET), /:sessionId/peers/:peerId (DELETE)
+    app.route("/api/sessions", createPeerRoutes(sessionStore, authService, connectionManager));
+    // Message routes: /:sessionId/messages (POST, GET)
+    app.route("/api/sessions", createMessageRoutes(sessionStore, authService, maxMessages, connectionManager, messageQueue));
+    // Poll routes: /:sessionId/poll (GET)
+    app.route("/api/sessions", createPollRoutes(sessionStore, authService));
+    return { app, injectWebSocket };
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/**
+ * Zod schema for server configuration.
+ * All values loadable from COGENT_SERVER_* environment variables.
+ */
+declare const ServerConfigSchema: z.ZodObject<{
+    PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    HOST: z.ZodDefault<z.ZodString>;
+    STATE_DIR: z.ZodDefault<z.ZodString>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
+        error: "error";
+        info: "info";
+        warn: "warn";
+    }>>;
+    BCRYPT_ROUNDS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    STALE_PEER_TIMEOUT_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    MAX_MESSAGES_PER_SESSION: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    CORS_ORIGIN: z.ZodDefault<z.ZodString>;
+    WS_HEARTBEAT_INTERVAL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    WS_HEARTBEAT_MAX_MISSED: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    WS_GRACE_PERIOD_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    QUEUE_TTL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    QUEUE_CLEANUP_INTERVAL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    SESSION_INACTIVITY_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    SESSION_CLEANUP_INTERVAL_MS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    ADMIN_PASSWORD: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Inferred server configuration type. */
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+/**
+ * Shape of camelCase keys accepted in config.json.
+ * Each key maps to a COGENT_SERVER_* env var equivalent.
+ */
+export interface ConfigFileOptions {
+    port?: number;
+    host?: string;
+    stateDir?: string;
+    logLevel?: string;
+    bcryptRounds?: number;
+    stalePeerTimeoutMs?: number;
+    maxMessagesPerSession?: number;
+    corsOrigin?: string;
+    wsHeartbeatIntervalMs?: number;
+    wsHeartbeatMaxMissed?: number;
+    wsGracePeriodMs?: number;
+    queueTtlMs?: number;
+    queueCleanupIntervalMs?: number;
+    sessionInactivityMs?: number;
+    sessionCleanupIntervalMs?: number;
+    adminPassword?: string;
+}
+/**
+ * Load a config.json file and return its values mapped to COGENT_SERVER_* env var names.
+ *
+ * - If the file does not exist, returns an empty object (no error).
+ * - If the file contains invalid JSON, throws with a clear error message.
+ * - Only non-undefined values are included in the result.
+ */
+export declare function loadConfigFile(configPath: string): Record<string, string>;
+/**
+ * Load server configuration from COGENT_SERVER_* environment variables,
+ * with optional config.json support.
+ *
+ * Precedence (highest to lowest):
+ *   1. Environment variables (COGENT_SERVER_*)
+ *   2. config.json values (if file exists)
+ *   3. Zod schema defaults
+ *
+ * Strips the prefix, validates with Zod, freezes the result.
+ * Can only be called once -- subsequent calls throw.
+ *
+ * @param env - Environment variable source (defaults to process.env)
+ * @param configPath - Path to config.json file (default: "config.json" relative to cwd)
+ */
+export declare function loadServerConfig(env?: Record<string, string | undefined>, configPath?: string): Readonly<ServerConfig>;
+/**
+ * Get the previously loaded server configuration.
+ * Throws if loadServerConfig() has not been called.
+ */
+export declare function getServerConfig(): Readonly<ServerConfig>;
+/**
+ * Reset the loaded config (for testing only).
+ * @internal
+ */
+export declare function _resetConfig(): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;GAGG;AACH,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;iBA2BtB,CAAC;AAEH,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BzE;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,UAAU,GAAE,MAAgD,GAC3D,QAAQ,CAAC,YAAY,CAAC,CA2BxB;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,QAAQ,CAAC,YAAY,CAAC,CAOxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC"}

package/dist/config.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+/**
+ * Zod schema for server configuration.
+ * All values loadable from COGENT_SERVER_* environment variables.
+ */
+const ServerConfigSchema = z.object({
+    PORT: z.coerce.number().default(3000),
+    HOST: z.string().default("0.0.0.0"),
+    STATE_DIR: z.string().default(path.join(os.homedir(), ".cogent-server", "sessions")),
+    LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
+    BCRYPT_ROUNDS: z.coerce.number().int().min(4).max(31).default(12),
+    STALE_PEER_TIMEOUT_MS: z.coerce.number().default(1_800_000),
+    MAX_MESSAGES_PER_SESSION: z.coerce.number().int().min(1).default(1500),
+    CORS_ORIGIN: z.string().default("*"),
+    /** Ping interval for WebSocket heartbeat (default: 30s). */
+    WS_HEARTBEAT_INTERVAL_MS: z.coerce.number().default(30_000),
+    /** Number of missed pongs before terminating a WebSocket connection (default: 3, giving 90s window). */
+    WS_HEARTBEAT_MAX_MISSED: z.coerce.number().int().min(1).default(3),
+    /** Grace period after last WS connection closes before marking peer offline (default: 30s). */
+    WS_GRACE_PERIOD_MS: z.coerce.number().default(30_000),
+    /** Queue message TTL in ms (default: 7 days). */
+    QUEUE_TTL_MS: z.coerce.number().default(604_800_000),
+    /** Queue cleanup interval in ms (default: 6 hours). */
+    QUEUE_CLEANUP_INTERVAL_MS: z.coerce.number().default(21_600_000),
+    /** Inactivity threshold before a session is eligible for automatic deletion (default: 7 days). */
+    SESSION_INACTIVITY_MS: z.coerce.number().default(604_800_000),
+    /** How often to scan for and delete inactive sessions (default: 1 hour). */
+    SESSION_CLEANUP_INTERVAL_MS: z.coerce.number().default(3_600_000),
+    /** Admin dashboard password. When undefined, admin dashboard is disabled entirely. */
+    ADMIN_PASSWORD: z.string().optional(),
+});
+const ENV_PREFIX = "COGENT_SERVER_";
+/** Maps camelCase config.json keys to COGENT_SERVER_* env var names. */
+const CONFIG_KEY_MAP = {
+    port: "COGENT_SERVER_PORT",
+    host: "COGENT_SERVER_HOST",
+    stateDir: "COGENT_SERVER_STATE_DIR",
+    logLevel: "COGENT_SERVER_LOG_LEVEL",
+    bcryptRounds: "COGENT_SERVER_BCRYPT_ROUNDS",
+    stalePeerTimeoutMs: "COGENT_SERVER_STALE_PEER_TIMEOUT_MS",
+    maxMessagesPerSession: "COGENT_SERVER_MAX_MESSAGES_PER_SESSION",
+    corsOrigin: "COGENT_SERVER_CORS_ORIGIN",
+    wsHeartbeatIntervalMs: "COGENT_SERVER_WS_HEARTBEAT_INTERVAL_MS",
+    wsHeartbeatMaxMissed: "COGENT_SERVER_WS_HEARTBEAT_MAX_MISSED",
+    wsGracePeriodMs: "COGENT_SERVER_WS_GRACE_PERIOD_MS",
+    queueTtlMs: "COGENT_SERVER_QUEUE_TTL_MS",
+    queueCleanupIntervalMs: "COGENT_SERVER_QUEUE_CLEANUP_INTERVAL_MS",
+    sessionInactivityMs: "COGENT_SERVER_SESSION_INACTIVITY_MS",
+    sessionCleanupIntervalMs: "COGENT_SERVER_SESSION_CLEANUP_INTERVAL_MS",
+    adminPassword: "COGENT_SERVER_ADMIN_PASSWORD",
+};
+/**
+ * Load a config.json file and return its values mapped to COGENT_SERVER_* env var names.
+ *
+ * - If the file does not exist, returns an empty object (no error).
+ * - If the file contains invalid JSON, throws with a clear error message.
+ * - Only non-undefined values are included in the result.
+ */
+export function loadConfigFile(configPath) {
+    let content;
+    try {
+        content = fs.readFileSync(configPath, "utf-8");
+    }
+    catch (err) {
+        // File not found is OK -- config.json is optional
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return {};
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`Invalid JSON in config file: ${configPath}`);
+    }
+    const configObj = parsed;
+    const result = {};
+    for (const [key, envKey] of Object.entries(CONFIG_KEY_MAP)) {
+        const value = configObj[key];
+        if (value !== undefined) {
+            result[envKey] = String(value);
+        }
+    }
+    return result;
+}
+let _config = null;
+/**
+ * Load server configuration from COGENT_SERVER_* environment variables,
+ * with optional config.json support.
+ *
+ * Precedence (highest to lowest):
+ *   1. Environment variables (COGENT_SERVER_*)
+ *   2. config.json values (if file exists)
+ *   3. Zod schema defaults
+ *
+ * Strips the prefix, validates with Zod, freezes the result.
+ * Can only be called once -- subsequent calls throw.
+ *
+ * @param env - Environment variable source (defaults to process.env)
+ * @param configPath - Path to config.json file (default: "config.json" relative to cwd)
+ */
+export function loadServerConfig(env = process.env, configPath = path.join(process.cwd(), "config.json")) {
+    if (_config !== null) {
+        throw new Error("Server config already loaded. Use getServerConfig().");
+    }
+    // Load config.json values (returns empty object if file missing)
+    const fileValues = loadConfigFile(configPath);
+    // Strip COGENT_SERVER_ prefix from matching env vars
+    const raw = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (key.startsWith(ENV_PREFIX) && value !== undefined) {
+            raw[key.slice(ENV_PREFIX.length)] = value;
+        }
+    }
+    // Merge config.json values UNDER env vars: only set if env var is not already present
+    for (const [envKey, fileValue] of Object.entries(fileValues)) {
+        const stripped = envKey.slice(ENV_PREFIX.length);
+        if (!(stripped in raw)) {
+            raw[stripped] = fileValue;
+        }
+    }
+    const parsed = ServerConfigSchema.parse(raw);
+    _config = Object.freeze(parsed);
+    return _config;
+}
+/**
+ * Get the previously loaded server configuration.
+ * Throws if loadServerConfig() has not been called.
+ */
+export function getServerConfig() {
+    if (_config === null) {
+        throw new Error("Server config not loaded. Call loadServerConfig() first.");
+    }
+    return _config;
+}
+/**
+ * Reset the loaded config (for testing only).
+ * @internal
+ */
+export function _resetConfig() {
+    _config = null;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,102 @@
+import { serve } from "@hono/node-server";
+import { loadServerConfig, getServerConfig } from "./config.js";
+import { AuthService } from "./services/auth-service.js";
+import { SessionStore } from "./services/session-store.js";
+import { PeerCleanup } from "./services/peer-cleanup.js";
+import { ConnectionManager } from "./services/connection-manager.js";
+import { MessageQueueService } from "./services/message-queue.js";
+import { StatsService } from "./services/stats-service.js";
+import { createPeerDisconnectedFrame } from "./ws/frames.js";
+import { SessionCleanup } from "./services/session-cleanup.js";
+import { createApp } from "./app.js";
+/**
+ * Cogent Server entry point.
+ *
+ * 1. Load and validate server configuration from env vars
+ * 2. Initialize services (auth, session store, connection manager, message queue)
+ * 3. Create and wire the Hono app with WebSocket support
+ * 4. Start the HTTP server and inject WebSocket handler
+ * 5. Start background services (peer cleanup, queue cleanup)
+ * 6. Register graceful shutdown handlers
+ */
+async function main() {
+    // Load config from COGENT_SERVER_* environment variables
+    loadServerConfig();
+    const config = getServerConfig();
+    // Initialize services
+    const authService = new AuthService(config.BCRYPT_ROUNDS);
+    const sessionStore = new SessionStore(config.STATE_DIR, config.MAX_MESSAGES_PER_SESSION);
+    await sessionStore.init();
+    // Create WebSocket-aware services
+    const connectionManager = new ConnectionManager(config.WS_GRACE_PERIOD_MS);
+    const messageQueue = new MessageQueueService(sessionStore, config.QUEUE_TTL_MS);
+    // Set up peer offline callback: broadcast peer_disconnected when grace period expires
+    connectionManager.setOnPeerOffline((sessionId, peerId) => {
+        const frame = createPeerDisconnectedFrame(peerId);
+        connectionManager.broadcastToSession(sessionId, JSON.stringify(frame));
+    });
+    // Record server start time for uptime calculation
+    const startTime = Date.now();
+    // Admin dashboard password (null = admin disabled)
+    const adminPassword = config.ADMIN_PASSWORD ?? null;
+    // Stats aggregation service for landing page and SSE stream
+    const statsService = new StatsService(sessionStore, connectionManager, startTime);
+    // Create the Hono app with all middleware, routes, and WebSocket support
+    const { app, injectWebSocket } = createApp({
+        sessionStore,
+        authService,
+        startTime,
+        maxMessages: config.MAX_MESSAGES_PER_SESSION,
+        connectionManager,
+        messageQueue,
+        statsService,
+        adminPassword,
+        heartbeatIntervalMs: config.WS_HEARTBEAT_INTERVAL_MS,
+        heartbeatMaxMissed: config.WS_HEARTBEAT_MAX_MISSED,
+    });
+    // Start stale peer cleanup background service
+    const peerCleanup = new PeerCleanup(sessionStore, config.STALE_PEER_TIMEOUT_MS);
+    peerCleanup.start();
+    // Start message queue cleanup background service
+    messageQueue.startCleanup(config.QUEUE_CLEANUP_INTERVAL_MS);
+    // Start inactive session cleanup background service (default: scan every hour, delete after 7 days)
+    const sessionCleanup = new SessionCleanup(sessionStore, connectionManager, config.SESSION_INACTIVITY_MS);
+    sessionCleanup.start(config.SESSION_CLEANUP_INTERVAL_MS);
+    // Start the HTTP server
+    const server = serve({
+        fetch: app.fetch,
+        port: config.PORT,
+        hostname: config.HOST,
+    });
+    // CRITICAL: inject WebSocket handler into the HTTP server (see RESEARCH.md Pitfall 2)
+    // Without this call, WebSocket upgrade requests would return 404.
+    injectWebSocket(server);
+    console.error(`Cogent Server listening on ${config.HOST}:${config.PORT} (WebSocket enabled)`);
+    // Start stats refresh after server is listening
+    statsService.start();
+    // Graceful shutdown on SIGTERM and SIGINT
+    const shutdown = () => {
+        console.error("Shutting down Cogent Server...");
+        // Stop background services
+        statsService.stop();
+        peerCleanup.stop();
+        sessionCleanup.stop();
+        messageQueue.stopCleanup();
+        // Close all WebSocket connections with 1012 (Service Restart) before HTTP server shutdown
+        connectionManager.closeAll(1012, "Service restart");
+        server.close((err) => {
+            if (err) {
+                console.error("Error during shutdown:", err);
+                process.exit(1);
+            }
+            process.exit(0);
+        });
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+}
+main().catch((err) => {
+    console.error("Fatal error starting Cogent Server:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/middleware/auth.d.ts

@@ -0,0 +1,15 @@
+import type { SessionStore } from "../services/session-store.js";
+import type { AuthService } from "../services/auth-service.js";
+import type { ServerEnv } from "../types.js";
+/**
+ * Create bearer token auth middleware.
+ *
+ * Extracts the Authorization header, hashes the token with SHA-256,
+ * looks up the session via the token index, performs a timing-safe
+ * comparison for defense-in-depth, and sets sessionId + session on
+ * the Hono context for downstream handlers.
+ *
+ * Uses dependency injection so the middleware is fully testable.
+ */
+export declare function createAuthMiddleware(sessionStore: SessionStore, authService: AuthService): import("hono").MiddlewareHandler<ServerEnv, string, {}, Response>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,qEA4DzB"}

package/dist/middleware/auth.js

@@ -0,0 +1,47 @@
+import { createMiddleware } from "hono/factory";
+import { BridgeError, ErrorCode } from "@essentialai/cogent";
+/**
+ * Create bearer token auth middleware.
+ *
+ * Extracts the Authorization header, hashes the token with SHA-256,
+ * looks up the session via the token index, performs a timing-safe
+ * comparison for defense-in-depth, and sets sessionId + session on
+ * the Hono context for downstream handlers.
+ *
+ * Uses dependency injection so the middleware is fully testable.
+ */
+export function createAuthMiddleware(sessionStore, authService) {
+    return createMiddleware(async (c, next) => {
+        // 1. Extract Authorization header
+        const authHeader = c.req.header("Authorization");
+        if (!authHeader) {
+            throw new BridgeError(ErrorCode.AUTH_MISSING_TOKEN, "Authorization header required", "Include 'Authorization: Bearer <token>' header");
+        }
+        // 2. Parse Bearer <token> format
+        const match = authHeader.match(/^Bearer\s+(.+)$/i);
+        if (!match) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Invalid Authorization header format", "Use 'Bearer <token>' format");
+        }
+        const token = match[1];
+        // 3. Hash the token with SHA-256 for index lookup
+        const tokenHash = authService.hashToken(token);
+        // 4. Look up session by token hash
+        const result = await sessionStore.getSessionByTokenHash(tokenHash);
+        if (!result) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Invalid or expired token");
+        }
+        // 5. Defense-in-depth: timing-safe comparison of the token hash
+        //    Even though we looked up by hash, this guards against hash collisions.
+        const storedTokenHash = result.state.tokens.find((t) => t.tokenHash === tokenHash)?.tokenHash;
+        if (!storedTokenHash ||
+            !authService.timingSafeCompare(tokenHash, storedTokenHash)) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Invalid or expired token");
+        }
+        // 6. Set session context for downstream handlers
+        c.set("sessionId", result.sessionId);
+        c.set("session", result.state);
+        // 7. Continue to next middleware/handler
+        await next();
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/middleware/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAK7D;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,YAA0B,EAC1B,WAAwB;IAExB,OAAO,gBAAgB,CAAY,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACnD,kCAAkC;QAClC,MAAM,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QACjD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,+BAA+B,EAC/B,gDAAgD,CACjD,CAAC;QACJ,CAAC;QAED,iCAAiC;QACjC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,qCAAqC,EACrC,6BAA6B,CAC9B,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAEvB,kDAAkD;QAClD,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAE/C,mCAAmC;QACnC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,0BAA0B,CAC3B,CAAC;QACJ,CAAC;QAED,gEAAgE;QAChE,4EAA4E;QAC5E,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAC9C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CACjC,EAAE,SAAS,CAAC;QAEb,IACE,CAAC,eAAe;YAChB,CAAC,WAAW,CAAC,iBAAiB,CAAC,SAAS,EAAE,eAAe,CAAC,EAC1D,CAAC;YACD,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,0BAA0B,CAC3B,CAAC;QACJ,CAAC;QAED,iDAAiD;QACjD,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACrC,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAE/B,yCAAyC;QACzC,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,14 @@
+import type { ErrorHandler } from "hono";
+import type { ServerEnv } from "../types.js";
+/**
+ * Global error handler for the Hono app.
+ *
+ * - HTTPException instances (from middleware like basicAuth) are passed
+ *   through as-is using getResponse() to preserve correct status codes.
+ * - BridgeError instances are serialized to structured JSON using toJSON()
+ *   with the correct HTTP status code from the ErrorHttpStatus mapping.
+ * - All other errors are wrapped in a generic INTERNAL_SERVER_ERROR
+ *   BridgeError, with the original error logged to stderr for debugging.
+ */
+export declare const errorHandler: ErrorHandler<ServerEnv>;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/middleware/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAGzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,EAAE,YAAY,CAAC,SAAS,CAkBhD,CAAC"}

package/dist/middleware/error-handler.js

@@ -0,0 +1,26 @@
+import { BridgeError, ErrorCode } from "@essentialai/cogent";
+import { HTTPException } from "hono/http-exception";
+/**
+ * Global error handler for the Hono app.
+ *
+ * - HTTPException instances (from middleware like basicAuth) are passed
+ *   through as-is using getResponse() to preserve correct status codes.
+ * - BridgeError instances are serialized to structured JSON using toJSON()
+ *   with the correct HTTP status code from the ErrorHttpStatus mapping.
+ * - All other errors are wrapped in a generic INTERNAL_SERVER_ERROR
+ *   BridgeError, with the original error logged to stderr for debugging.
+ */
+export const errorHandler = (err, c) => {
+    // Pass through Hono HTTPException responses (e.g. 401 from basicAuth)
+    if (err instanceof HTTPException) {
+        return err.getResponse();
+    }
+    if (err instanceof BridgeError) {
+        return c.json(err.toJSON(), err.httpStatus);
+    }
+    // Unexpected error -- wrap and log
+    const bridgeErr = new BridgeError(ErrorCode.INTERNAL_SERVER_ERROR, "An unexpected error occurred", "Please try again or contact support");
+    console.error("Unhandled error:", err);
+    return c.json(bridgeErr.toJSON(), 500);
+};
+//# sourceMappingURL=error-handler.js.map

package/dist/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAA4B,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;IAC9D,sEAAsE;IACtE,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;QACjC,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;IAC3B,CAAC;IAED,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,UAAkC,CAAC,CAAC;IACtE,CAAC;IAED,mCAAmC;IACnC,MAAM,SAAS,GAAG,IAAI,WAAW,CAC/B,SAAS,CAAC,qBAAqB,EAC/B,8BAA8B,EAC9B,qCAAqC,CACtC,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACvC,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC,CAAC"}

package/dist/middleware/not-found.d.ts

@@ -0,0 +1,8 @@
+import type { NotFoundHandler } from "hono";
+import type { ServerEnv } from "../types.js";
+/**
+ * 404 handler for unknown routes.
+ * Returns a structured BridgeError JSON response (not default HTML).
+ */
+export declare const notFoundHandler: NotFoundHandler<ServerEnv>;
+//# sourceMappingURL=not-found.d.ts.map

package/dist/middleware/not-found.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../../src/middleware/not-found.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,SAAS,CAWtD,CAAC"}

package/dist/middleware/not-found.js

@@ -0,0 +1,12 @@
+import { BridgeError, ErrorCode } from "@essentialai/cogent";
+/**
+ * 404 handler for unknown routes.
+ * Returns a structured BridgeError JSON response (not default HTML).
+ */
+export const notFoundHandler = (c) => {
+    const method = c.req.method;
+    const path = c.req.path;
+    const err = new BridgeError(ErrorCode.ENDPOINT_NOT_FOUND, `Route not found: ${method} ${path}`, "Check the URL and HTTP method");
+    return c.json(err.toJSON(), 404);
+};
+//# sourceMappingURL=not-found.js.map

package/dist/middleware/not-found.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.js","sourceRoot":"","sources":["../../src/middleware/not-found.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAI7D;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAA+B,CAAC,CAAC,EAAE,EAAE;IAC/D,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAExB,MAAM,GAAG,GAAG,IAAI,WAAW,CACzB,SAAS,CAAC,kBAAkB,EAC5B,oBAAoB,MAAM,IAAI,IAAI,EAAE,EACpC,+BAA+B,CAChC,CAAC;IAEF,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;AACnC,CAAC,CAAC"}