@essentialai/cogent-server 2.0.0

package/dist/ui/pages/SessionList.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+import { css } from "hono/css";
+import { Layout } from "../components/Layout.js";
+import { NavBar } from "../components/NavBar.js";
+import { Footer } from "../components/Footer.js";
+import { colors, fonts } from "../styles/theme.js";
+const container = css `
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 0 1.5rem 2rem;
+`;
+const pageTitle = css `
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: ${colors.text};
+  margin: 0 0 2rem 0;
+`;
+const tableWrapper = css `
+  overflow-x: auto;
+`;
+const tableStyle = css `
+  width: 100%;
+  border-collapse: collapse;
+  font-family: ${fonts.mono};
+  font-size: 0.8rem;
+
+  th {
+    text-align: left;
+    padding: 0.6rem 0.75rem;
+    color: ${colors.textMuted};
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    font-size: 0.7rem;
+    border-bottom: 1px solid ${colors.border};
+  }
+
+  td {
+    padding: 0.6rem 0.75rem;
+    border-bottom: 1px solid ${colors.border};
+    color: ${colors.text};
+    vertical-align: middle;
+  }
+
+  tr:hover td {
+    background: ${colors.bgCard};
+  }
+`;
+const sessionLink = css `
+  color: ${colors.cyan};
+  text-decoration: none;
+  &:hover {
+    text-decoration: underline;
+  }
+`;
+const connectedCount = css `
+  color: ${colors.green};
+  font-weight: 700;
+`;
+const deleteBtn = css `
+  background: transparent;
+  border: 1px solid ${colors.red};
+  color: ${colors.red};
+  padding: 0.25rem 0.6rem;
+  border-radius: 3px;
+  cursor: pointer;
+  font-family: ${fonts.mono};
+  font-size: 0.75rem;
+
+  &:hover {
+    background: ${colors.red};
+    color: ${colors.bg};
+  }
+`;
+const emptyState = css `
+  text-align: center;
+  padding: 3rem 1rem;
+  color: ${colors.textMuted};
+  font-size: 0.9rem;
+`;
+/**
+ * Session list page with table of all sessions.
+ * Each row links to the session detail page and has a delete button.
+ */
+export const SessionList = ({ sessions }) => (_jsxs(Layout, { title: "Sessions", children: [_jsx(NavBar, { active: "sessions" }), _jsxs("div", { class: container, children: [_jsx("h1", { class: pageTitle, children: "Sessions" }), sessions.length === 0 ? (_jsx("div", { class: emptyState, children: "No sessions found." })) : (_jsx("div", { class: tableWrapper, children: _jsxs("table", { class: tableStyle, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Session ID" }), _jsx("th", { children: "Label" }), _jsx("th", { children: "Created" }), _jsx("th", { children: "IP" }), _jsx("th", { children: "Peers" }), _jsx("th", { children: "Messages" }), _jsx("th", { children: "Actions" })] }) }), _jsx("tbody", { children: sessions.map((s) => (_jsxs("tr", { children: [_jsx("td", { children: _jsx("a", { href: "/admin/sessions/" + s.sessionId, class: sessionLink, children: s.sessionId.length > 20
+                                                    ? s.sessionId.slice(0, 20) + "..."
+                                                    : s.sessionId }) }), _jsx("td", { children: s.label ?? "-" }), _jsx("td", { children: new Date(s.createdAt).toLocaleString() }), _jsx("td", { children: s.creatorIp ?? "-" }), _jsxs("td", { children: [s.peerCount, " registered /", " ", _jsx("span", { class: connectedCount, children: s.connectedPeerIds.length }), " ", "connected"] }), _jsx("td", { children: s.messageCount }), _jsx("td", { children: _jsx("form", { method: "post", action: "/admin/sessions/" + s.sessionId + "/delete", style: "display:inline", children: _jsx("button", { type: "submit", class: deleteBtn, onclick: "return confirm('Delete this session and all its data?')", children: "Delete" }) }) })] }))) })] }) })), _jsx(Footer, {})] })] }));
+//# sourceMappingURL=SessionList.js.map

package/dist/ui/pages/SessionList.js.map

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

package/dist/ui/styles/theme.d.ts

@@ -0,0 +1,35 @@
+import { css, keyframes } from "hono/css";
+/**
+ * Terminal-aesthetic color palette.
+ * Dark background with Matrix green accent, muted text, and subtle borders.
+ */
+export declare const colors: {
+    readonly bg: "#0d1117";
+    readonly bgCard: "#161b22";
+    readonly bgTerminal: "#0a0a0a";
+    readonly text: "#c9d1d9";
+    readonly textMuted: "#8b949e";
+    readonly green: "#00ff41";
+    readonly cyan: "#58a6ff";
+    readonly amber: "#e3b341";
+    readonly red: "#f85149";
+    readonly border: "#30363d";
+    readonly borderGlow: "#00ff4133";
+};
+/**
+ * Monospace font stack for the terminal aesthetic.
+ */
+export declare const fonts: {
+    readonly mono: "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', monospace";
+};
+/**
+ * Cursor blink keyframe animation -- opacity toggle at 50%.
+ * Typed as ReturnType<typeof keyframes> to avoid exposing internal CssClassName.
+ */
+export declare const cursorBlink: ReturnType<typeof keyframes>;
+/**
+ * Global styles using Hono's css helper with :-hono-global selector.
+ * Sets box-sizing, font, background, text color, link color, and selection.
+ */
+export declare const globalStyles: ReturnType<typeof css>;
+//# sourceMappingURL=theme.d.ts.map

package/dist/ui/styles/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../../src/ui/styles/theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;CAYT,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,KAAK;;CAER,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,UAAU,CAAC,OAAO,SAAS,CAGpD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,CAAC,OAAO,GAAG,CA2B/C,CAAC"}

package/dist/ui/styles/theme.js

@@ -0,0 +1,65 @@
+import { css, keyframes } from "hono/css";
+/**
+ * Terminal-aesthetic color palette.
+ * Dark background with Matrix green accent, muted text, and subtle borders.
+ */
+export const colors = {
+    bg: "#0d1117",
+    bgCard: "#161b22",
+    bgTerminal: "#0a0a0a",
+    text: "#c9d1d9",
+    textMuted: "#8b949e",
+    green: "#00ff41",
+    cyan: "#58a6ff",
+    amber: "#e3b341",
+    red: "#f85149",
+    border: "#30363d",
+    borderGlow: "#00ff4133",
+};
+/**
+ * Monospace font stack for the terminal aesthetic.
+ */
+export const fonts = {
+    mono: "'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', monospace",
+};
+/**
+ * Cursor blink keyframe animation -- opacity toggle at 50%.
+ * Typed as ReturnType<typeof keyframes> to avoid exposing internal CssClassName.
+ */
+export const cursorBlink = keyframes `
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
+`;
+/**
+ * Global styles using Hono's css helper with :-hono-global selector.
+ * Sets box-sizing, font, background, text color, link color, and selection.
+ */
+export const globalStyles = css `
+  :-hono-global {
+    * {
+      box-sizing: border-box;
+    }
+    html {
+      font-family: ${fonts.mono};
+      font-size: 14px;
+      background: ${colors.bg};
+      color: ${colors.text};
+    }
+    body {
+      margin: 0;
+      padding: 0;
+    }
+    a {
+      color: ${colors.cyan};
+      text-decoration: none;
+    }
+    a:hover {
+      text-decoration: underline;
+    }
+    ::selection {
+      background: ${colors.green};
+      color: ${colors.bgTerminal};
+    }
+  }
+`;
+//# sourceMappingURL=theme.js.map

package/dist/ui/styles/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../../../src/ui/styles/theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;GAGG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,EAAE,EAAE,SAAS;IACb,MAAM,EAAE,SAAS;IACjB,UAAU,EAAE,SAAS;IACrB,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,SAAS;IACpB,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,GAAG,EAAE,SAAS;IACd,MAAM,EAAE,SAAS;IACjB,UAAU,EAAE,WAAW;CACf,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,IAAI,EAAE,sEAAsE;CACpE,CAAC;AAEX;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAiC,SAAS,CAAA;;;CAGjE,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAA2B,GAAG,CAAA;;;;;;qBAMlC,KAAK,CAAC,IAAI;;oBAEX,MAAM,CAAC,EAAE;eACd,MAAM,CAAC,IAAI;;;;;;;eAOX,MAAM,CAAC,IAAI;;;;;;;oBAON,MAAM,CAAC,KAAK;eACjB,MAAM,CAAC,UAAU;;;CAG/B,CAAC"}

package/dist/ws/frames.d.ts

@@ -0,0 +1,82 @@
+import type { PeerInfo, MessageRecord } from "@essentialai/cogent";
+/**
+ * WebSocket close codes for different disconnect scenarios.
+ * Uses standard RFC 6455 / IANA-registered codes.
+ */
+export declare const WsCloseCode: {
+    /** Clean client-initiated close. */
+    readonly NORMAL_CLOSURE: 1000;
+    /** Heartbeat timeout -- 3 missed pings (90s). */
+    readonly HEARTBEAT_TIMEOUT: 1001;
+    /** Invalid frame data from client. */
+    readonly UNSUPPORTED_DATA: 1003;
+    /** Unexpected server error. */
+    readonly INTERNAL_ERROR: 1011;
+    /** Server shutting down via SIGTERM. */
+    readonly SERVICE_RESTART: 1012;
+};
+export interface MessageFrame {
+    type: "message";
+    payload: MessageRecord;
+    timestamp: string;
+}
+export interface PeerConnectedFrame {
+    type: "peer_connected";
+    payload: {
+        peerId: string;
+        name: string;
+        project: string;
+    };
+    timestamp: string;
+}
+export interface PeerDisconnectedFrame {
+    type: "peer_disconnected";
+    payload: {
+        peerId: string;
+    };
+    timestamp: string;
+}
+export interface PeersSnapshotFrame {
+    type: "peers_snapshot";
+    payload: {
+        peers: PeerInfo[];
+    };
+    timestamp: string;
+}
+export interface QueuedMessagesFrame {
+    type: "queued_messages";
+    payload: {
+        messages: MessageRecord[];
+    };
+    timestamp: string;
+}
+export interface ErrorFrame {
+    type: "error";
+    payload: {
+        code: string;
+        message: string;
+    };
+    timestamp: string;
+}
+/**
+ * Discriminated union of all server-to-client WebSocket frame types.
+ * The `type` field acts as the discriminator for client-side dispatch.
+ */
+export type WsServerFrame = MessageFrame | PeerConnectedFrame | PeerDisconnectedFrame | PeersSnapshotFrame | QueuedMessagesFrame | ErrorFrame;
+/** Create a frame delivering a single message to a peer. */
+export declare function createMessageFrame(message: MessageRecord): MessageFrame;
+/** Create a frame notifying peers that a new peer has connected via WebSocket. */
+export declare function createPeerConnectedFrame(peer: {
+    peerId: string;
+    name: string;
+    project: string;
+}): PeerConnectedFrame;
+/** Create a frame notifying peers that a peer has disconnected. */
+export declare function createPeerDisconnectedFrame(peerId: string): PeerDisconnectedFrame;
+/** Create a snapshot frame listing all currently connected peers in the session. */
+export declare function createPeersSnapshotFrame(peers: PeerInfo[]): PeersSnapshotFrame;
+/** Create a frame delivering all queued offline messages to a reconnecting peer. */
+export declare function createQueuedMessagesFrame(messages: MessageRecord[]): QueuedMessagesFrame;
+/** Create an error frame sent to a peer before closing the connection. */
+export declare function createErrorFrame(code: string, message: string): ErrorFrame;
+//# sourceMappingURL=frames.d.ts.map

package/dist/ws/frames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.d.ts","sourceRoot":"","sources":["../../src/ws/frames.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,WAAW;IACtB,oCAAoC;;IAEpC,iDAAiD;;IAEjD,sCAAsC;;IAEtC,+BAA+B;;IAE/B,wCAAwC;;CAEhC,CAAC;AAMX,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,aAAa,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE;QAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE;QAAE,QAAQ,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,kBAAkB,GAClB,qBAAqB,GACrB,kBAAkB,GAClB,mBAAmB,GACnB,UAAU,CAAC;AAMf,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAMvE;AAED,kFAAkF;AAClF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,kBAAkB,CAMrB;AAED,mEAAmE;AACnE,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,GACb,qBAAqB,CAMvB;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,QAAQ,EAAE,GAChB,kBAAkB,CAMpB;AAED,oFAAoF;AACpF,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,aAAa,EAAE,GACxB,mBAAmB,CAMrB;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,UAAU,CAMZ"}

package/dist/ws/frames.js

@@ -0,0 +1,68 @@
+/**
+ * WebSocket close codes for different disconnect scenarios.
+ * Uses standard RFC 6455 / IANA-registered codes.
+ */
+export const WsCloseCode = {
+    /** Clean client-initiated close. */
+    NORMAL_CLOSURE: 1000,
+    /** Heartbeat timeout -- 3 missed pings (90s). */
+    HEARTBEAT_TIMEOUT: 1001,
+    /** Invalid frame data from client. */
+    UNSUPPORTED_DATA: 1003,
+    /** Unexpected server error. */
+    INTERNAL_ERROR: 1011,
+    /** Server shutting down via SIGTERM. */
+    SERVICE_RESTART: 1012,
+};
+// ---------------------------------------------------------------------------
+// Frame creation helpers -- each returns a typed WsServerFrame with timestamp
+// ---------------------------------------------------------------------------
+/** Create a frame delivering a single message to a peer. */
+export function createMessageFrame(message) {
+    return {
+        type: "message",
+        payload: message,
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Create a frame notifying peers that a new peer has connected via WebSocket. */
+export function createPeerConnectedFrame(peer) {
+    return {
+        type: "peer_connected",
+        payload: peer,
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Create a frame notifying peers that a peer has disconnected. */
+export function createPeerDisconnectedFrame(peerId) {
+    return {
+        type: "peer_disconnected",
+        payload: { peerId },
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Create a snapshot frame listing all currently connected peers in the session. */
+export function createPeersSnapshotFrame(peers) {
+    return {
+        type: "peers_snapshot",
+        payload: { peers },
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Create a frame delivering all queued offline messages to a reconnecting peer. */
+export function createQueuedMessagesFrame(messages) {
+    return {
+        type: "queued_messages",
+        payload: { messages },
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Create an error frame sent to a peer before closing the connection. */
+export function createErrorFrame(code, message) {
+    return {
+        type: "error",
+        payload: { code, message },
+        timestamp: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=frames.js.map

package/dist/ws/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../../src/ws/frames.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,oCAAoC;IACpC,cAAc,EAAE,IAAI;IACpB,iDAAiD;IACjD,iBAAiB,EAAE,IAAI;IACvB,sCAAsC;IACtC,gBAAgB,EAAE,IAAI;IACtB,+BAA+B;IAC/B,cAAc,EAAE,IAAI;IACpB,wCAAwC;IACxC,eAAe,EAAE,IAAI;CACb,CAAC;AAsDX,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAE9E,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,wBAAwB,CAAC,IAIxC;IACC,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,2BAA2B,CACzC,MAAc;IAEd,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,EAAE,MAAM,EAAE;QACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,wBAAwB,CACtC,KAAiB;IAEjB,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,EAAE,KAAK,EAAE;QAClB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,yBAAyB,CACvC,QAAyB;IAEzB,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,EAAE,QAAQ,EAAE;QACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,OAAe;IAEf,OAAO;QACL,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;QAC1B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC"}

package/dist/ws/handler.d.ts

@@ -0,0 +1,26 @@
+import type { WSEvents } from "hono/ws";
+import type { ConnectionManager } from "../services/connection-manager.js";
+import type { MessageQueueService } from "../services/message-queue.js";
+import type { SessionStore } from "../services/session-store.js";
+/**
+ * Dependencies for the WebSocket handler.
+ * Injected via createWsHandler to keep the handler testable.
+ */
+export interface WsHandlerDeps {
+    connectionManager: ConnectionManager;
+    messageQueue: MessageQueueService;
+    sessionStore: SessionStore;
+    heartbeatIntervalMs: number;
+    heartbeatMaxMissed: number;
+}
+/**
+ * Create a WSEvents handler for a single WebSocket connection.
+ *
+ * Manages the full connection lifecycle:
+ * - onOpen: heartbeat setup, connection tracking, peers snapshot, offline queue flush, broadcast peer_connected
+ * - onMessage: log and ignore (clients use REST for actions)
+ * - onClose: remove connection from tracker (triggers grace timer internally)
+ * - onError: log and continue
+ */
+export declare function createWsHandler(sessionId: string, peerId: string, deps: WsHandlerDeps): WSEvents;
+//# sourceMappingURL=handler.d.ts.map

package/dist/ws/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/ws/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,OAAO,KAAK,EAAE,iBAAiB,EAAkB,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAQjE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,YAAY,EAAE,mBAAmB,CAAC;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAClB,QAAQ,CA+EV"}

package/dist/ws/handler.js

@@ -0,0 +1,72 @@
+import { setupHeartbeat } from "./heartbeat.js";
+import { createPeersSnapshotFrame, createQueuedMessagesFrame, createPeerConnectedFrame, } from "./frames.js";
+/**
+ * Create a WSEvents handler for a single WebSocket connection.
+ *
+ * Manages the full connection lifecycle:
+ * - onOpen: heartbeat setup, connection tracking, peers snapshot, offline queue flush, broadcast peer_connected
+ * - onMessage: log and ignore (clients use REST for actions)
+ * - onClose: remove connection from tracker (triggers grace timer internally)
+ * - onError: log and continue
+ */
+export function createWsHandler(sessionId, peerId, deps) {
+    return {
+        async onOpen(_evt, ws) {
+            const rawWs = ws.raw;
+            // 1. Set up heartbeat ping/pong
+            const heartbeatInterval = setupHeartbeat(rawWs, deps.heartbeatIntervalMs, deps.heartbeatMaxMissed);
+            // 2. Register connection in the connection manager
+            const conn = {
+                ws,
+                rawWs,
+                peerId,
+                sessionId,
+                connectedAt: Date.now(),
+                heartbeatInterval,
+            };
+            deps.connectionManager.addConnection(conn);
+            // 3. Send peers_snapshot: all currently connected peer IDs with their info
+            const connectedPeerIds = deps.connectionManager.getConnectedPeerIds(sessionId);
+            const session = await deps.sessionStore.getSession(sessionId);
+            if (session) {
+                const peers = connectedPeerIds
+                    .map((pid) => session.peers[pid])
+                    .filter((p) => p !== undefined);
+                const snapshotFrame = createPeersSnapshotFrame(peers);
+                ws.send(JSON.stringify(snapshotFrame));
+            }
+            // 4. Flush offline message queue
+            const messages = await deps.messageQueue.dequeueAll(sessionId, peerId);
+            if (messages.length > 0) {
+                const queueFrame = createQueuedMessagesFrame(messages);
+                ws.send(JSON.stringify(queueFrame));
+            }
+            // 5. Broadcast peer_connected to other peers in the session
+            if (session) {
+                const peerInfo = session.peers[peerId];
+                if (peerInfo) {
+                    const connectedFrame = createPeerConnectedFrame({
+                        peerId: peerInfo.peerId,
+                        name: peerInfo.label,
+                        project: peerInfo.cwd,
+                    });
+                    deps.connectionManager.broadcastToSession(sessionId, JSON.stringify(connectedFrame), peerId);
+                }
+            }
+        },
+        onMessage(_evt, _ws) {
+            // Clients use REST for all state-mutating operations.
+            // No recognized client-to-server frame types needed yet.
+            // Protocol-level ping/pong handles keepalive at the ws layer.
+        },
+        onClose(_evt, ws) {
+            // Remove connection from tracker -- this handles grace timer start internally
+            deps.connectionManager.removeConnection(sessionId, peerId, ws);
+        },
+        onError(evt, _ws) {
+            // Log the error but do not crash the server
+            console.error(`WebSocket error for peer ${peerId} in session ${sessionId}:`, evt);
+        },
+    };
+}
+//# sourceMappingURL=handler.js.map

package/dist/ws/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/ws/handler.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAcrB;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAiB,EACjB,MAAc,EACd,IAAmB;IAEnB,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE;YACnB,MAAM,KAAK,GAAG,EAAE,CAAC,GAAgB,CAAC;YAElC,gCAAgC;YAChC,MAAM,iBAAiB,GAAG,cAAc,CACtC,KAAK,EACL,IAAI,CAAC,mBAAmB,EACxB,IAAI,CAAC,kBAAkB,CACxB,CAAC;YAEF,mDAAmD;YACnD,MAAM,IAAI,GAAmB;gBAC3B,EAAE;gBACF,KAAK;gBACL,MAAM;gBACN,SAAS;gBACT,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;gBACvB,iBAAiB;aAClB,CAAC;YACF,IAAI,CAAC,iBAAiB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;YAE3C,2EAA2E;YAC3E,MAAM,gBAAgB,GACpB,IAAI,CAAC,iBAAiB,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;YACxD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YAC9D,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,KAAK,GAAG,gBAAgB;qBAC3B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;qBAChC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;gBAClC,MAAM,aAAa,GAAG,wBAAwB,CAAC,KAAK,CAAC,CAAC;gBACtD,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;YACzC,CAAC;YAED,iCAAiC;YACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YACvE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,UAAU,GAAG,yBAAyB,CAAC,QAAQ,CAAC,CAAC;gBACvD,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;YACtC,CAAC;YAED,4DAA4D;YAC5D,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACvC,IAAI,QAAQ,EAAE,CAAC;oBACb,MAAM,cAAc,GAAG,wBAAwB,CAAC;wBAC9C,MAAM,EAAE,QAAQ,CAAC,MAAM;wBACvB,IAAI,EAAE,QAAQ,CAAC,KAAK;wBACpB,OAAO,EAAE,QAAQ,CAAC,GAAG;qBACtB,CAAC,CAAC;oBACH,IAAI,CAAC,iBAAiB,CAAC,kBAAkB,CACvC,SAAS,EACT,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,EAC9B,MAAM,CACP,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,SAAS,CAAC,IAAI,EAAE,GAAG;YACjB,sDAAsD;YACtD,yDAAyD;YACzD,8DAA8D;QAChE,CAAC;QAED,OAAO,CAAC,IAAI,EAAE,EAAE;YACd,8EAA8E;YAC9E,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,OAAO,CAAC,GAAG,EAAE,GAAG;YACd,4CAA4C;YAC5C,OAAO,CAAC,KAAK,CACX,4BAA4B,MAAM,eAAe,SAAS,GAAG,EAC7D,GAAG,CACJ,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ws/heartbeat.d.ts

@@ -0,0 +1,18 @@
+import type WebSocket from "ws";
+/**
+ * Set up server-side ping/pong heartbeat for a WebSocket connection.
+ *
+ * Sends native WebSocket ping frames at the configured interval.
+ * If `maxMissed` consecutive pongs are not received, the connection
+ * is forcefully terminated via `ws.terminate()`.
+ *
+ * The client's WebSocket stack auto-replies to ping frames with pong,
+ * so no application-level keepalive is needed.
+ *
+ * @param rawWs The underlying ws.WebSocket object (from ws.raw)
+ * @param intervalMs Milliseconds between ping frames (default: 30s)
+ * @param maxMissed Number of missed pongs before termination (default: 3)
+ * @returns The interval handle (caller should store it for cleanup)
+ */
+export declare function setupHeartbeat(rawWs: WebSocket, intervalMs: number, maxMissed: number): ReturnType<typeof setInterval>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/ws/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/ws/heartbeat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,IAAI,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,UAAU,CAAC,OAAO,WAAW,CAAC,CA2BhC"}

package/dist/ws/heartbeat.js

@@ -0,0 +1,39 @@
+/**
+ * Set up server-side ping/pong heartbeat for a WebSocket connection.
+ *
+ * Sends native WebSocket ping frames at the configured interval.
+ * If `maxMissed` consecutive pongs are not received, the connection
+ * is forcefully terminated via `ws.terminate()`.
+ *
+ * The client's WebSocket stack auto-replies to ping frames with pong,
+ * so no application-level keepalive is needed.
+ *
+ * @param rawWs The underlying ws.WebSocket object (from ws.raw)
+ * @param intervalMs Milliseconds between ping frames (default: 30s)
+ * @param maxMissed Number of missed pongs before termination (default: 3)
+ * @returns The interval handle (caller should store it for cleanup)
+ */
+export function setupHeartbeat(rawWs, intervalMs, maxMissed) {
+    let missedPings = 0;
+    // Reset counter when pong is received
+    rawWs.on("pong", () => {
+        missedPings = 0;
+    });
+    const interval = setInterval(() => {
+        // Check if we've exceeded the missed pong threshold
+        if (missedPings >= maxMissed) {
+            rawWs.terminate();
+            clearInterval(interval);
+            return;
+        }
+        // Increment and send ping
+        missedPings++;
+        rawWs.ping();
+    }, intervalMs);
+    // Fast-path cleanup when connection closes normally
+    rawWs.on("close", () => {
+        clearInterval(interval);
+    });
+    return interval;
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/ws/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../src/ws/heartbeat.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAgB,EAChB,UAAkB,EAClB,SAAiB;IAEjB,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,sCAAsC;IACtC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;QACpB,WAAW,GAAG,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;QAChC,oDAAoD;QACpD,IAAI,WAAW,IAAI,SAAS,EAAE,CAAC;YAC7B,KAAK,CAAC,SAAS,EAAE,CAAC;YAClB,aAAa,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO;QACT,CAAC;QAED,0BAA0B;QAC1B,WAAW,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,EAAE,CAAC;IACf,CAAC,EAAE,UAAU,CAAC,CAAC;IAEf,oDAAoD;IACpD,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACrB,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/docker-compose.yml

@@ -0,0 +1,38 @@
+services:
+  server:
+    build:
+      context: ..
+      dockerfile: server/Dockerfile
+    restart: unless-stopped
+    expose:
+      - "3000"
+    volumes:
+      - cogent_data:/data
+    env_file:
+      - .env
+    environment:
+      - COGENT_SERVER_STATE_DIR=/data/sessions
+      - NODE_ENV=production
+    stop_grace_period: 30s
+
+  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    env_file:
+      - .env
+    depends_on:
+      server:
+        condition: service_healthy
+
+volumes:
+  cogent_data:
+  caddy_data:
+  caddy_config:

package/nginx.conf.example

@@ -0,0 +1,63 @@
+# CC Cloud Bridge Server - Nginx Reverse Proxy Configuration
+#
+# Alternative to Caddy. Requires manual TLS certificate management via certbot.
+# The docker-compose.yml uses Caddy by default for automatic HTTPS.
+#
+# To use this instead of Caddy:
+# 1. Replace "example.com" with your actual domain throughout this file
+# 2. Obtain TLS certificates: certbot certonly --standalone -d example.com
+# 3. Set up certbot auto-renewal: certbot renew --quiet (via cron/systemd timer)
+# 4. Point the server upstream to your CC Bridge Server instance
+#
+# Reference: https://nginx.org/en/docs/http/websocket.html
+
+http {
+    # WebSocket upgrade mapping -- required for WS proxying
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        ''      close;
+    }
+
+    upstream cc_bridge {
+        # Replace with your server address if not running on localhost
+        server 127.0.0.1:3000;
+    }
+
+    # Redirect all HTTP traffic to HTTPS
+    server {
+        listen 80;
+        # Replace example.com with your domain
+        server_name example.com;
+        return 301 https://$host$request_uri;
+    }
+
+    server {
+        listen 443 ssl;
+        # Replace example.com with your domain
+        server_name example.com;
+
+        # TLS certificates (managed by certbot)
+        # Replace example.com with your domain
+        ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
+        ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+
+        location / {
+            proxy_pass http://cc_bridge;
+            proxy_http_version 1.1;
+
+            # WebSocket upgrade headers
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+
+            # Preserve original client information
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+
+            # WebSocket timeout (default 60s is too short for long-lived connections)
+            proxy_read_timeout 86400s;
+            proxy_send_timeout 86400s;
+        }
+    }
+}