@essentialai/cogent-bridge 1.0.0

package/dist/backend/http-backend.js

@@ -0,0 +1,185 @@
+import { SERVER_VERSION } from "../constants.js";
+/**
+ * API path patterns matching @essentialai/cogent PATHS constants.
+ * Defined locally because cogent is not a dependency of the main package.
+ */
+const PATHS = {
+    peers: "/api/sessions/:sessionId/peers",
+    peer: "/api/sessions/:sessionId/peers/:peerId",
+    messages: "/api/sessions/:sessionId/messages",
+    health: "/api/health",
+};
+/**
+ * Cloud-mode storage backend.
+ *
+ * Implements StorageBackend by translating all state operations into REST
+ * API calls to the cloud relay server. Used when COGENT_ENDPOINT is
+ * set to an HTTP/HTTPS URL.
+ *
+ * Cloud-specific behavior differences from FileBackend:
+ * - updateLastSeen is a no-op (server tracks activity automatically)
+ * - validateSession always returns true (server validates on every request)
+ * - execClaude returns a synthetic result (no CLI subprocess in cloud mode)
+ * - checkHealth queries the server health endpoint instead of local checks
+ */
+export class HttpBackend {
+    http;
+    sessionId;
+    constructor(http, sessionId) {
+        this.http = http;
+        this.sessionId = sessionId;
+    }
+    /**
+     * Register a peer in the cloud session.
+     * POST /api/sessions/:sessionId/peers
+     *
+     * The sessionId parameter from StorageBackend is the local CC sessionId;
+     * in cloud mode we ignore it and use this.sessionId (the cloud session).
+     */
+    async registerPeer(peerId, _sessionId, cwd, label) {
+        const path = PATHS.peers.replace(":sessionId", this.sessionId);
+        return this.http.post(path, { peerId, cwd, label });
+    }
+    /**
+     * Deregister a peer from the cloud session.
+     * DELETE /api/sessions/:sessionId/peers/:peerId
+     *
+     * Returns true on success, false if the peer was not found.
+     */
+    async deregisterPeer(peerId) {
+        const path = PATHS.peer
+            .replace(":sessionId", this.sessionId)
+            .replace(":peerId", peerId);
+        try {
+            await this.http.delete(path, {});
+            return true;
+        }
+        catch {
+            // Server returns 404 if peer not found, which HttpClient throws as BridgeError
+            return false;
+        }
+    }
+    /**
+     * Get a single peer by ID.
+     * No dedicated single-peer REST endpoint exists, so we list all peers
+     * and filter client-side.
+     */
+    async getPeer(peerId) {
+        const peers = await this.listPeers();
+        return peers.find((p) => p.peerId === peerId);
+    }
+    /**
+     * List all peers in the cloud session.
+     * GET /api/sessions/:sessionId/peers
+     */
+    async listPeers() {
+        const path = PATHS.peers.replace(":sessionId", this.sessionId);
+        const result = await this.http.get(path);
+        return result.peers;
+    }
+    /**
+     * Update last-seen timestamp for a peer.
+     * In cloud mode, the server updates lastSeenAt automatically on
+     * authenticated requests, so this is a no-op.
+     */
+    async updateLastSeen(_peerId) {
+        /* Server tracks activity automatically */
+    }
+    /**
+     * Record a message in the cloud session.
+     * POST /api/sessions/:sessionId/messages
+     *
+     * Sends the message to the server which stores it and returns
+     * { id, success, timestamp }. We merge the server response with
+     * the input record to construct a full MessageRecord.
+     */
+    async recordMessage(record) {
+        const path = PATHS.messages.replace(":sessionId", this.sessionId);
+        const resp = await this.http.post(path, {
+            fromPeerId: record.fromPeerId,
+            toPeerId: record.toPeerId,
+            message: record.message,
+        });
+        return {
+            ...record,
+            id: resp.id,
+            timestamp: resp.timestamp,
+        };
+    }
+    /**
+     * Get message history from the cloud session.
+     * GET /api/sessions/:sessionId/messages
+     *
+     * Supports optional peerId filter and limit (default 100).
+     */
+    async getHistory(peerId, limit) {
+        const path = PATHS.messages.replace(":sessionId", this.sessionId);
+        const query = {};
+        if (peerId) {
+            query.peerId = peerId;
+        }
+        query.limit = String(limit ?? 100);
+        const result = await this.http.get(path, query);
+        return result.messages;
+    }
+    /**
+     * Validate a session.
+     * In cloud mode, the server validates session authenticity on every
+     * authenticated request, so this always returns true.
+     */
+    async validateSession(_sessionId, _cwd) {
+        return true;
+    }
+    /**
+     * Execute a Claude CLI command.
+     * In cloud mode, there is no CLI subprocess. Message delivery is
+     * handled by recordMessage() via REST. The send-message tool handler
+     * calls execClaude() after validating peers, then calls recordMessage()
+     * separately. In cloud mode, execClaude simply returns a synthetic
+     * result indicating the message was delivered via the cloud relay.
+     */
+    async execClaude(_sessionId, _message, _cwd, _timeoutMs) {
+        return {
+            stdout: "Message delivered via cloud relay.",
+            stderr: "",
+            exitCode: 0,
+        };
+    }
+    /**
+     * Check health of the cloud relay server.
+     * GET /api/health
+     *
+     * Maps the server's HealthResponse into the local HealthCheckResult
+     * format with cloud-mode-specific diagnostics.
+     */
+    async checkHealth() {
+        const resp = await this.http.get(PATHS.health);
+        return {
+            healthy: resp.status === "ok",
+            serverVersion: SERVER_VERSION,
+            statePath: "cloud:" + this.sessionId,
+            claudePath: "N/A (cloud mode)",
+            checks: {
+                stateFile: {
+                    ok: true,
+                    message: "Cloud mode -- state managed by server",
+                },
+                lockMechanism: {
+                    ok: true,
+                    message: "Cloud mode -- no local locks needed",
+                },
+                claudeCli: {
+                    ok: true,
+                    message: "Cloud mode -- no CLI needed",
+                },
+            },
+            timestamp: new Date().toISOString(),
+            mode: "cloud",
+            serverStatus: resp.status,
+            activeSessions: resp.activeSessions,
+            connectedPeers: resp.connectedPeers,
+            serverUptime: resp.uptime,
+        };
+    }
+}
+//# sourceMappingURL=http-backend.js.map

package/dist/backend/http-backend.js.map

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

package/dist/backend/index.d.ts

@@ -0,0 +1,5 @@
+export type { StorageBackend } from "./storage-backend.js";
+export { FileBackend } from "./file-backend.js";
+export { HttpBackend } from "./http-backend.js";
+export { initBackend, getBackend, resetBackend, createBackend, isCloudEndpoint } from "./backend-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/backend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/backend/index.js

@@ -0,0 +1,4 @@
+export { FileBackend } from "./file-backend.js";
+export { HttpBackend } from "./http-backend.js";
+export { initBackend, getBackend, resetBackend, createBackend, isCloudEndpoint } from "./backend-provider.js";
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/backend/storage-backend.d.ts

@@ -0,0 +1,22 @@
+import { PeerInfo, MessageRecord, CliExecResult } from "../types.js";
+import { HealthCheckResult } from "../services/health-check.js";
+/**
+ * Abstract storage backend interface.
+ *
+ * Mirrors the exact signatures of the free functions in peer-registry.ts,
+ * cc-cli.ts, and health-check.ts. Implementations can delegate to local
+ * file-based state (FileBackend) or to a remote HTTP server (future).
+ */
+export interface StorageBackend {
+    registerPeer(peerId: string, sessionId: string, cwd: string, label: string): Promise<PeerInfo>;
+    deregisterPeer(peerId: string): Promise<boolean>;
+    getPeer(peerId: string): Promise<PeerInfo | undefined>;
+    listPeers(): Promise<PeerInfo[]>;
+    updateLastSeen(peerId: string): Promise<void>;
+    recordMessage(record: Omit<MessageRecord, "id" | "timestamp">): Promise<MessageRecord>;
+    getHistory(peerId?: string, limit?: number): Promise<MessageRecord[]>;
+    validateSession(sessionId: string, cwd: string): Promise<boolean>;
+    execClaude(sessionId: string, message: string, cwd: string, timeoutMs?: number): Promise<CliExecResult>;
+    checkHealth(): Promise<HealthCheckResult>;
+}
+//# sourceMappingURL=storage-backend.d.ts.map

package/dist/backend/storage-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-backend.d.ts","sourceRoot":"","sources":["../../src/backend/storage-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAE7B,YAAY,CACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAEvD,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEjC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAG9C,aAAa,CACX,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAGtE,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElE,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAAC;IAG1B,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC3C"}

package/dist/backend/storage-backend.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage-backend.js.map

package/dist/backend/storage-backend.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function runCli(): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAU5C"}

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+export async function runCli() {
+    const command = process.argv[2];
+    if (command === "init") {
+        const { runWizard } = await import("./wizard/index.js");
+        await runWizard();
+    }
+    else {
+        // Default: start MCP server (existing behavior)
+        await import("./index.js");
+    }
+}
+runCli().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`Fatal error: ${msg}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,MAAM,CAAC,KAAK,UAAU,MAAM;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAEhC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;QACxD,MAAM,SAAS,EAAE,CAAC;IACpB,CAAC;SAAM,CAAC;QACN,gDAAgD;QAChD,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC9B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cloud/backoff.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Exponential backoff utility for reconnection delays.
+ * Produces delays from baseMs (default 1s) doubling up to maxMs (default 30s)
+ * with configurable jitter to prevent thundering herd.
+ */
+export declare class ExponentialBackoff {
+    private readonly baseMs;
+    private readonly maxMs;
+    private readonly jitterFactor;
+    private attempt;
+    constructor(baseMs?: number, maxMs?: number, jitterFactor?: number);
+    /** Get the next delay in ms and increment attempt counter. */
+    next(): number;
+    /** Reset after successful connection. */
+    reset(): void;
+    /** Current attempt number (0-based). */
+    get attempts(): number;
+}
+//# sourceMappingURL=backoff.d.ts.map

package/dist/cloud/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/cloud/backoff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,kBAAkB;IAI3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAL/B,OAAO,CAAC,OAAO,CAAK;gBAGD,MAAM,GAAE,MAAa,EACrB,KAAK,GAAE,MAAe,EACtB,YAAY,GAAE,MAAY;IAG7C,8DAA8D;IAC9D,IAAI,IAAI,MAAM;IAOd,yCAAyC;IACzC,KAAK,IAAI,IAAI;IAIb,wCAAwC;IACxC,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF"}

package/dist/cloud/backoff.js

@@ -0,0 +1,32 @@
+/**
+ * Exponential backoff utility for reconnection delays.
+ * Produces delays from baseMs (default 1s) doubling up to maxMs (default 30s)
+ * with configurable jitter to prevent thundering herd.
+ */
+export class ExponentialBackoff {
+    baseMs;
+    maxMs;
+    jitterFactor;
+    attempt = 0;
+    constructor(baseMs = 1000, maxMs = 30_000, jitterFactor = 0.1) {
+        this.baseMs = baseMs;
+        this.maxMs = maxMs;
+        this.jitterFactor = jitterFactor;
+    }
+    /** Get the next delay in ms and increment attempt counter. */
+    next() {
+        const expDelay = Math.min(this.baseMs * 2 ** this.attempt, this.maxMs);
+        const jitter = expDelay * this.jitterFactor * (Math.random() * 2 - 1);
+        this.attempt++;
+        return Math.max(0, expDelay + jitter);
+    }
+    /** Reset after successful connection. */
+    reset() {
+        this.attempt = 0;
+    }
+    /** Current attempt number (0-based). */
+    get attempts() {
+        return this.attempt;
+    }
+}
+//# sourceMappingURL=backoff.js.map

package/dist/cloud/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/cloud/backoff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IAIV;IACA;IACA;IALX,OAAO,GAAG,CAAC,CAAC;IAEpB,YACmB,SAAiB,IAAI,EACrB,QAAgB,MAAM,EACtB,eAAuB,GAAG;QAF1B,WAAM,GAAN,MAAM,CAAe;QACrB,UAAK,GAAL,KAAK,CAAiB;QACtB,iBAAY,GAAZ,YAAY,CAAc;IAC1C,CAAC;IAEJ,8DAA8D;IAC9D,IAAI;QACF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,yCAAyC;IACzC,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACnB,CAAC;IAED,wCAAwC;IACxC,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}

package/dist/cloud/credential-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shape of persisted cloud session credentials.
+ * Stored in ~/.cogent-credentials.json.
+ *
+ * Per anti-pattern guidance: stores the bearer token (not the secret).
+ * The secret is only used during create/join -- the token authenticates
+ * subsequent requests.
+ */
+export interface PersistedCredentials {
+    endpoint: string;
+    sessionId: string;
+    token: string;
+    savedAt: string;
+}
+/**
+ * Load persisted credentials from disk.
+ * Returns null on any error (file not found, JSON parse failure, etc.).
+ */
+export declare function loadCredentials(credentialPath?: string): Promise<PersistedCredentials | null>;
+/**
+ * Save credentials to disk as pretty-printed JSON.
+ */
+export declare function saveCredentials(creds: PersistedCredentials, credentialPath?: string): Promise<void>;
+/**
+ * Delete the credential file from disk.
+ * Silently ignores ENOENT (file already absent).
+ */
+export declare function clearCredentials(credentialPath?: string): Promise<void>;
+//# sourceMappingURL=credential-store.d.ts.map

package/dist/cloud/credential-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.d.ts","sourceRoot":"","sources":["../../src/cloud/credential-store.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;GAGG;AACH,wBAAsB,eAAe,CACnC,cAAc,GAAE,MAAwB,GACvC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAOtC;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,cAAc,GAAE,MAAwB,GACvC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,cAAc,GAAE,MAAwB,GACvC,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/cloud/credential-store.js

@@ -0,0 +1,38 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+const CREDENTIAL_PATH = path.join(os.homedir(), ".cogent-credentials.json");
+/**
+ * Load persisted credentials from disk.
+ * Returns null on any error (file not found, JSON parse failure, etc.).
+ */
+export async function loadCredentials(credentialPath = CREDENTIAL_PATH) {
+    try {
+        const raw = await fs.readFile(credentialPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save credentials to disk as pretty-printed JSON.
+ */
+export async function saveCredentials(creds, credentialPath = CREDENTIAL_PATH) {
+    await fs.writeFile(credentialPath, JSON.stringify(creds, null, 2) + "\n", "utf-8");
+}
+/**
+ * Delete the credential file from disk.
+ * Silently ignores ENOENT (file already absent).
+ */
+export async function clearCredentials(credentialPath = CREDENTIAL_PATH) {
+    try {
+        await fs.unlink(credentialPath);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=credential-store.js.map

package/dist/cloud/credential-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.js","sourceRoot":"","sources":["../../src/cloud/credential-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AAiBzB,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,0BAA0B,CAAC,CAAC;AAE5E;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,iBAAyB,eAAe;IAExC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAA2B,EAC3B,iBAAyB,eAAe;IAExC,MAAM,EAAE,CAAC,SAAS,CAChB,cAAc,EACd,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EACrC,OAAO,CACR,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,iBAAyB,eAAe;IAExC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/cloud/http-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Authenticated HTTP client for cloud relay server communication.
+ * Uses Node built-in fetch() (Node 18+) with Bearer token auth.
+ * Maps HTTP error responses to BridgeError for consistent error handling.
+ */
+export declare class HttpClient {
+    private readonly baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    private headers;
+    /**
+     * Perform an authenticated GET request.
+     * Appends query parameters to the URL if provided.
+     */
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    /**
+     * Perform an authenticated POST request with a JSON body.
+     */
+    post<T>(path: string, body: unknown): Promise<T>;
+    /**
+     * Perform an authenticated DELETE request.
+     * Returns void; ignores 204 No Content responses.
+     */
+    delete(path: string, body?: unknown): Promise<void>;
+    /**
+     * Update the Bearer token (e.g., after join-session returns a new token).
+     */
+    updateToken(newToken: string): void;
+    /**
+     * Parse an error response from the server and throw a BridgeError.
+     * If the server returns a cogent ErrorCode, it is passed through.
+     * For non-JSON error responses, STARTUP_FAILED is used as a fallback code.
+     */
+    private throwMappedError;
+}
+//# sourceMappingURL=http-client.d.ts.map

package/dist/cloud/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../src/cloud/http-client.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,KAAK,CAAS;gBAGH,OAAO,EAAE,MAAM,EAChC,KAAK,EAAE,MAAM;IAKf,OAAO,CAAC,OAAO;IAOf;;;OAGG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IActE;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAatD;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC;;;;OAIG;YACW,gBAAgB;CAyB/B"}

package/dist/cloud/http-client.js

@@ -0,0 +1,94 @@
+import { BridgeError, BridgeErrorCode } from "../errors.js";
+/**
+ * Authenticated HTTP client for cloud relay server communication.
+ * Uses Node built-in fetch() (Node 18+) with Bearer token auth.
+ * Maps HTTP error responses to BridgeError for consistent error handling.
+ */
+export class HttpClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    headers() {
+        return {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.token}`,
+        };
+    }
+    /**
+     * Perform an authenticated GET request.
+     * Appends query parameters to the URL if provided.
+     */
+    async get(path, query) {
+        const url = new URL(path, this.baseUrl);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        const resp = await fetch(url, { headers: this.headers() });
+        if (!resp.ok) {
+            await this.throwMappedError(resp);
+        }
+        return resp.json();
+    }
+    /**
+     * Perform an authenticated POST request with a JSON body.
+     */
+    async post(path, body) {
+        const url = new URL(path, this.baseUrl);
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            await this.throwMappedError(resp);
+        }
+        return resp.json();
+    }
+    /**
+     * Perform an authenticated DELETE request.
+     * Returns void; ignores 204 No Content responses.
+     */
+    async delete(path, body) {
+        const url = new URL(path, this.baseUrl);
+        const resp = await fetch(url, {
+            method: "DELETE",
+            headers: this.headers(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!resp.ok && resp.status !== 204) {
+            await this.throwMappedError(resp);
+        }
+    }
+    /**
+     * Update the Bearer token (e.g., after join-session returns a new token).
+     */
+    updateToken(newToken) {
+        this.token = newToken;
+    }
+    /**
+     * Parse an error response from the server and throw a BridgeError.
+     * If the server returns a cogent ErrorCode, it is passed through.
+     * For non-JSON error responses, STARTUP_FAILED is used as a fallback code.
+     */
+    async throwMappedError(resp) {
+        let errorBody;
+        try {
+            errorBody = (await resp.json());
+        }
+        catch {
+            errorBody = { message: resp.statusText };
+        }
+        // Try to use the server's error code if it maps to a BridgeErrorCode,
+        // otherwise fall back to STARTUP_FAILED as the most generic code.
+        const code = errorBody.code && errorBody.code in BridgeErrorCode
+            ? errorBody.code
+            : BridgeErrorCode.STARTUP_FAILED;
+        throw new BridgeError(code, errorBody.message ?? `HTTP ${resp.status}`, errorBody.suggestion);
+    }
+}
+//# sourceMappingURL=http-client.js.map

package/dist/cloud/http-client.js.map

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

package/dist/cloud/index.d.ts

@@ -0,0 +1,10 @@
+export { HttpClient } from "./http-client.js";
+export { ExponentialBackoff } from "./backoff.js";
+export { loadCredentials, saveCredentials, clearCredentials, } from "./credential-store.js";
+export type { PersistedCredentials } from "./credential-store.js";
+export type { WsServerFrame, MessageFrame, PeerConnectedFrame, PeerDisconnectedFrame, PeersSnapshotFrame, QueuedMessagesFrame, ErrorFrame, } from "./ws-frames.js";
+export { WsCloseCode } from "./ws-frames.js";
+export { MessageInbox } from "./message-inbox.js";
+export { CloudWsClient } from "./ws-client.js";
+export type { WsState } from "./ws-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cloud/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cloud/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EACV,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cloud/index.js

@@ -0,0 +1,7 @@
+export { HttpClient } from "./http-client.js";
+export { ExponentialBackoff } from "./backoff.js";
+export { loadCredentials, saveCredentials, clearCredentials, } from "./credential-store.js";
+export { WsCloseCode } from "./ws-frames.js";
+export { MessageInbox } from "./message-inbox.js";
+export { CloudWsClient } from "./ws-client.js";
+//# sourceMappingURL=index.js.map

package/dist/cloud/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cloud/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EACL,eAAe,EACf,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAW/B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/cloud/message-inbox.d.ts

@@ -0,0 +1,49 @@
+import type { MessageRecord } from "../types.js";
+/**
+ * In-memory message inbox with deduplication and timestamp ordering.
+ *
+ * Aggregates messages from both WebSocket push and poll fallback channels.
+ * Deduplicates by message ID (bounded to last 1000 IDs) and maintains
+ * messages ordered by server timestamp for consistent display.
+ */
+export declare class MessageInbox {
+    private messages;
+    private seenIds;
+    private seenOrder;
+    private listeners;
+    private lastMessageId;
+    /**
+     * Add a single message to the inbox.
+     * Returns true if the message was new (not a duplicate).
+     */
+    addMessage(msg: MessageRecord): boolean;
+    /**
+     * Add multiple messages at once.
+     * Returns the count of new (non-duplicate) messages added.
+     */
+    addMessages(msgs: MessageRecord[]): number;
+    /**
+     * Get all unread messages (copy of the internal array).
+     */
+    getUnread(): MessageRecord[];
+    /**
+     * Mark messages as read by removing them from the unread list.
+     * Does NOT remove from seenIds -- they remain for deduplication.
+     */
+    markRead(messageIds: string[]): void;
+    /**
+     * Get the ID of the last message received (by timestamp order).
+     * Used for poll sync -- pass as lastMessageId query parameter.
+     */
+    getLastMessageId(): string | null;
+    /**
+     * Subscribe to new message notifications.
+     * Returns an unsubscribe function.
+     */
+    onNewMessage(listener: () => void): () => void;
+    /**
+     * Clear all state: messages, seen IDs, last message ID, and listeners.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=message-inbox.d.ts.map

package/dist/cloud/message-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-inbox.d.ts","sourceRoot":"","sources":["../../src/cloud/message-inbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,aAAa,CAAuB;IAE5C;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO;IAuCvC;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,MAAM;IAU1C;;OAEG;IACH,SAAS,IAAI,aAAa,EAAE;IAI5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI;IAKpC;;;OAGG;IACH,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAU9C;;OAEG;IACH,KAAK,IAAI,IAAI;CAOd"}