@essentialai/cogent-bridge 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 cc-bridge-mcp-server contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# @essentialai/cogent-bridge
+
+Cogent Bridge from Essential AI Solutions (essentialai.uk) — MCP server for inter-Claude-Code session communication.
+
+## Quick Start
+
+### Install via Plugin Marketplace (Recommended)
+
+```bash
+claude plugin marketplace add eaisdevelopment/cogent-marketplace
+claude plugin install cogent-bridge@cogent-marketplace
+```
+
+Restart Claude Code. Use `/cogent-bridge:register` to join the bridge — session discovery, registration, and message protocol are all handled automatically.
+
+### Alternative: Manual Setup
+
+Add `.mcp.json` to **both** project repositories:
+
+```json
+{
+  "mcpServers": {
+    "cogent-bridge": {
+      "command": "npx",
+      "args": ["-y", "@essentialai/cogent-bridge"],
+      "env": {}
+    }
+  }
+}
+```
+
+Or use the CLI:
+
+```bash
+claude mcp add --transport stdio cogent-bridge -- npx -y @essentialai/cogent-bridge
+```
+
+Restart Claude Code in both repos. The bridge tools are now available.
+
+> See [docs/installation.md](docs/installation.md) for all installation options, configuration, and troubleshooting.
+
+## What It Does
+
+Two Claude Code instances -- one working on a backend repo, another on a frontend repo -- need to negotiate testing scenarios and debug collaboratively in real-time without mixing their accumulated project context.
+
+```
+Cogent_Backend                                Cogent_Frontend
+    |                                         |
+    +-- .mcp.json --> @essentialai/cogent-bridge    |
+    |                    |                    |
+    |                    +-- ~/.cogent/cogent-state.json
+    |                    |                    |
+    |                    |   <-- .mcp.json ---+
+    |                                         |
+    +-- claude --resume <sessionId> -p "msg" -+
+```
+
+Each CC instance spawns its own MCP server process via stdio transport. Shared state is persisted to `~/.cogent/cogent-state.json` with file locking so both processes see the same peer registry and message history.
+
+Messages are relayed by calling `claude --resume <sessionId> -p "message"` as a subprocess. Before sending, the bridge validates that the target session file exists on disk — if the session has ended, it fails immediately instead of waiting for timeout. On timeout, it retries once with a shorter 30-second timeout. File locking uses `fs.writeFile` with `flag: "wx"` (O_CREAT | O_EXCL), stale lock detection via `process.kill(pid, 0)`, and atomic writes via temp-file-then-rename.
+
+## Tools Reference
+
+The server exposes six tools, all prefixed with `cogent_`:
+
+### cogent_register_peer
+
+Register a Claude Code session as a named peer on the bridge.
+
+| Parameter   | Type   | Required | Description                                                  |
+|-------------|--------|----------|--------------------------------------------------------------|
+| `peerId`    | string | yes      | Unique identifier, e.g. `"backend"` or `"frontend"`          |
+| `sessionId` | string | yes      | Claude Code session ID (used with `--resume`)                |
+| `cwd`       | string | yes      | Absolute path to the project working directory               |
+| `label`     | string | yes      | Human-readable label, e.g. `"Cogent_Backend"` or `"Cogent_Frontend"` |
+
+### cogent_deregister_peer
+
+Remove a previously registered peer from the bridge.
+
+| Parameter | Type   | Required | Description                           |
+|-----------|--------|----------|---------------------------------------|
+| `peerId`  | string | yes      | Peer ID to deregister, e.g. `"backend"` |
+
+### cogent_send_message
+
+Send a message from one registered peer to another. The message is relayed by resuming the target's Claude Code session via CLI subprocess. Returns the target's response.
+
+| Parameter    | Type   | Required | Description                                |
+|--------------|--------|----------|--------------------------------------------|
+| `fromPeerId` | string | yes      | Peer ID of the sender, e.g. `"backend"`    |
+| `toPeerId`   | string | yes      | Peer ID of the recipient, e.g. `"frontend"` |
+| `message`    | string | yes      | The message content to send                |
+
+### cogent_list_peers
+
+List all currently registered peers. Returns peer IDs, session IDs, working directories, labels, and a `potentiallyStale` flag for peers idle beyond the configured timeout. No parameters.
+
+### cogent_get_history
+
+Retrieve the message history for the bridge. Returns messages in chronological order, most recent last.
+
+| Parameter | Type   | Required | Description                                    |
+|-----------|--------|----------|------------------------------------------------|
+| `peerId`  | string | no       | Filter history to messages involving this peer  |
+| `limit`   | number | no       | Maximum number of messages to return (default 50) |
+
+### cogent_health_check
+
+Diagnose the bridge's operational status. No parameters required.
+
+**Checks performed:**
+
+- **State file** -- Can the state directory be read and written?
+- **Lock mechanism** -- Can file locks be acquired and released?
+- **Claude CLI** -- Is the `claude` binary available and responsive?
+
+**Response fields:**
+
+| Field           | Type    | Description                             |
+|-----------------|---------|-----------------------------------------|
+| `healthy`       | boolean | All checks passed                       |
+| `serverVersion` | string  | Current server version                  |
+| `statePath`     | string  | Path to state file                      |
+| `claudePath`    | string  | Path to Claude CLI                      |
+| `checks`        | object  | Per-check pass/fail with detail messages |
+| `timestamp`     | string  | ISO timestamp of the check              |
+
+## Configuration
+
+All settings are configured via environment variables with sensible defaults:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COGENT_STATE_PATH` | `~/.cogent` | Directory for state file and logs |
+| `COGENT_TIMEOUT_MS` | `120000` (2 min) | CLI subprocess timeout in milliseconds |
+| `COGENT_CHAR_LIMIT` | `0` (unlimited) | Max characters in relayed message (0 = no limit) |
+| `COGENT_LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
+| `COGENT_CLAUDE_PATH` | `claude` | Path to the Claude Code CLI executable |
+| `COGENT_STALE_TIMEOUT_MS` | `1800000` (30 min) | Idle time before peer is flagged stale (0 = disabled) |
+
+To override defaults, set environment variables in your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cogent-bridge": {
+      "command": "npx",
+      "args": ["-y", "@essentialai/cogent-bridge"],
+      "env": {
+        "COGENT_STATE_PATH": "/custom/path",
+        "COGENT_LOG_LEVEL": "debug"
+      }
+    }
+  }
+}
+```
+
+## Usage Workflow
+
+1. Start two Claude Code sessions, one per repo.
+
+2. In each session, find your session ID:
+
+   ```bash
+   ls -t ~/.claude/projects/$(pwd | sed 's/[^a-zA-Z0-9-]/-/g')/*.jsonl 2>/dev/null | head -1 | xargs -I{} basename {} .jsonl
+   ```
+
+3. Each session registers itself on the bridge:
+
+   ```
+   # In Cogent_Backend:
+   Use cogent_register_peer:
+     peerId: "backend", sessionId: "<backend-session-id>",
+     cwd: "/path/to/backend", label: "Cogent_Backend"
+
+   # In Cogent_Frontend:
+   Use cogent_register_peer:
+     peerId: "frontend", sessionId: "<frontend-session-id>",
+     cwd: "/path/to/frontend", label: "Cogent_Frontend"
+   ```
+
+4. Send a message from either session:
+
+   ```
+   Use cogent_send_message:
+     fromPeerId: "backend", toPeerId: "frontend",
+     message: "What endpoint does the login form POST to?"
+   ```
+
+5. The bridge validates the target session exists, resumes it with the message, and returns the response. On timeout, it automatically retries once.
+
+6. Check message history at any time:
+
+   ```
+   Use cogent_get_history to see all exchanges, or filter by peerId.
+   ```
+
+7. When done, deregister peers:
+
+   ```
+   Use cogent_deregister_peer:
+     peerId: "backend"
+   ```
+
+## Troubleshooting
+
+### NVM/PATH: "npx not found" or server fails to start
+
+MCP servers are spawned as subprocesses and may not inherit your NVM configuration.
+
+**Option 1: Use absolute path to npx**
+
+Find your npx path with `which npx` (e.g., `/Users/you/.nvm/versions/node/v22.11.0/bin/npx`), then update `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cogent-bridge": {
+      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/npx",
+      "args": ["-y", "@essentialai/cogent-bridge"]
+    }
+  }
+}
+```
+
+**Option 2: Use `claude mcp add` (handles PATH automatically)**
+
+```bash
+claude mcp add --transport stdio cogent-bridge -- npx -y @essentialai/cogent-bridge
+```
+
+**Option 3: Ensure NVM loads in non-interactive shells**
+
+Add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+```
+
+### State file location
+
+The bridge stores state at `~/.cogent/cogent-state.json` by default.
+
+- Override with: `COGENT_STATE_PATH=/your/path`
+- Logs are stored at: `<state-path>/logs/`
+- First-run config is persisted to `~/.cogent-config.json`
+
+### Common errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `CLI_NOT_FOUND` | `claude` not on PATH | Install Claude Code or set `COGENT_CLAUDE_PATH` |
+| `CLI_TIMEOUT` | Response took > 2 min (retried once at 30s) | Increase `COGENT_TIMEOUT_MS`, or check target session is active |
+| `LOCK_TIMEOUT` | Lock held by dead process | Delete `<state-path>/cogent-state.json.lock` |
+| `STATE_CORRUPT` | Invalid JSON in state | Auto-recovers; backup saved as `.corrupt.<timestamp>` |
+| `PEER_NOT_FOUND` | Target peer not registered | Register both peers before sending messages |
+| `CLI_EXEC_FAILED` (session not found) | Target session file missing | Ask peer to re-register with current session ID |
+
+## Development
+
+Build from source:
+
+```bash
+git clone https://github.com/eaisdevelopment/cogent.git
+cd cogent-bridge
+npm install
+npm run build
+npm test
+```
+
+### Project Structure
+
+```
+src/
+├── index.ts                 # Server entry point, registers tools, starts stdio transport
+├── config.ts                # Environment variable loading and validation (zod)
+├── constants.ts             # Server name and version from package.json
+├── errors.ts                # BridgeError class and error code enum
+├── logger.ts                # Timestamped file + stderr logger
+├── startup.ts               # First-run prompt, config loading, CLI validation
+├── types.ts                 # Core interfaces (PeerInfo, MessageRecord, etc.)
+├── services/
+│   ├── cc-cli.ts            # CLI subprocess wrapper (spawn with claude --resume)
+│   ├── health-check.ts      # State file, lock, and CLI diagnostic checks
+│   └── peer-registry.ts     # File-based shared state with locking
+└── tools/
+    ├── register-peer.ts     # cogent_register_peer
+    ├── deregister-peer.ts   # cogent_deregister_peer
+    ├── send-message.ts      # cogent_send_message
+    ├── list-peers.ts        # cogent_list_peers
+    ├── get-history.ts       # cogent_get_history
+    └── health-check.ts      # cogent_health_check
+```
+
+### npm Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `npm run build` | `tsc` | Compile TypeScript to `dist/` |
+| `npm run dev` | `tsx watch src/index.ts` | Development mode with auto-reload |
+| `npm start` | `node dist/index.js` | Run compiled server |
+| `npm run clean` | `rm -rf dist` | Remove build artifacts |
+| `npm test` | `vitest run` | Run test suite |
+| `npm run test:watch` | `vitest` | Run tests in watch mode |
+| `npm run test:coverage` | `vitest run --coverage` | Run tests with coverage report |
+
+## License
+
+ISC

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

@@ -0,0 +1,28 @@
+import { StorageBackend } from "./storage-backend.js";
+/** Set the singleton backend (called during server startup). */
+export declare function initBackend(backend: StorageBackend): void;
+/**
+ * Get the active storage backend.
+ *
+ * If no backend has been set via initBackend(), lazy-initializes a FileBackend.
+ * This makes existing tests pass without modification -- they never call
+ * initBackend(), so getBackend() auto-creates a FileBackend that delegates
+ * to the same service functions the tests already mock via vi.mock().
+ */
+export declare function getBackend(): StorageBackend;
+/** Reset the singleton to null (for test isolation). */
+export declare function resetBackend(): void;
+/** Check whether a value looks like a cloud endpoint (http:// or https://). */
+export declare function isCloudEndpoint(value: string): boolean;
+/**
+ * Factory: create a backend from an optional endpoint string.
+ *
+ * - If endpoint is an HTTP/HTTPS URL, creates an HttpBackend for cloud mode.
+ *   Requires sessionId and token (from env vars or tool-based session setup).
+ * - Otherwise returns a FileBackend for local file-based state.
+ *
+ * Note: Does NOT import config.ts to avoid circular dependency risk
+ * (decision from 02B-01). Caller passes params explicitly.
+ */
+export declare function createBackend(endpoint?: string, sessionId?: string, token?: string): StorageBackend;
+//# sourceMappingURL=backend-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend-provider.d.ts","sourceRoot":"","sources":["../../src/backend/backend-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAetD,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,cAAc,CAK3C;AAED,wDAAwD;AACxD,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,cAAc,CAahB"}

package/dist/backend/backend-provider.js

@@ -0,0 +1,60 @@
+import { FileBackend } from "./file-backend.js";
+import { HttpBackend } from "./http-backend.js";
+import { HttpClient } from "../cloud/http-client.js";
+/**
+ * Singleton accessor for the active storage backend.
+ *
+ * Follows the same pattern as config.ts: explicit init for production,
+ * lazy fallback for tests. getBackend() auto-creates a FileBackend when
+ * no backend has been set, ensuring existing tests work without modification.
+ */
+let _backend = null;
+/** Set the singleton backend (called during server startup). */
+export function initBackend(backend) {
+    _backend = backend;
+}
+/**
+ * Get the active storage backend.
+ *
+ * If no backend has been set via initBackend(), lazy-initializes a FileBackend.
+ * This makes existing tests pass without modification -- they never call
+ * initBackend(), so getBackend() auto-creates a FileBackend that delegates
+ * to the same service functions the tests already mock via vi.mock().
+ */
+export function getBackend() {
+    if (!_backend) {
+        _backend = new FileBackend();
+    }
+    return _backend;
+}
+/** Reset the singleton to null (for test isolation). */
+export function resetBackend() {
+    _backend = null;
+}
+/** Check whether a value looks like a cloud endpoint (http:// or https://). */
+export function isCloudEndpoint(value) {
+    return /^https?:\/\//i.test(value);
+}
+/**
+ * Factory: create a backend from an optional endpoint string.
+ *
+ * - If endpoint is an HTTP/HTTPS URL, creates an HttpBackend for cloud mode.
+ *   Requires sessionId and token (from env vars or tool-based session setup).
+ * - Otherwise returns a FileBackend for local file-based state.
+ *
+ * Note: Does NOT import config.ts to avoid circular dependency risk
+ * (decision from 02B-01). Caller passes params explicitly.
+ */
+export function createBackend(endpoint, sessionId, token) {
+    if (endpoint && isCloudEndpoint(endpoint)) {
+        if (!sessionId || !token) {
+            throw new Error("Cloud mode requires COGENT_SESSION_ID and COGENT_SECRET " +
+                "(or use create-session/join-session tools). " +
+                `Got endpoint: ${endpoint}`);
+        }
+        const httpClient = new HttpClient(endpoint, token);
+        return new HttpBackend(httpClient, sessionId);
+    }
+    return new FileBackend();
+}
+//# sourceMappingURL=backend-provider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend-provider.js","sourceRoot":"","sources":["../../src/backend/backend-provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD;;;;;;GAMG;AAEH,IAAI,QAAQ,GAA0B,IAAI,CAAC;AAE3C,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,OAAuB;IACjD,QAAQ,GAAG,OAAO,CAAC;AACrB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU;IACxB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,QAAQ,GAAG,IAAI,WAAW,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY;IAC1B,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAiB,EACjB,SAAkB,EAClB,KAAc;IAEd,IAAI,QAAQ,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CACb,0DAA0D;gBAC1D,8CAA8C;gBAC9C,iBAAiB,QAAQ,EAAE,CAC5B,CAAC;QACJ,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACnD,OAAO,IAAI,WAAW,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC;AAC3B,CAAC"}

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

@@ -0,0 +1,22 @@
+import { PeerInfo, MessageRecord, CliExecResult } from "../types.js";
+import { HealthCheckResult } from "../services/health-check.js";
+import { StorageBackend } from "./storage-backend.js";
+/**
+ * File-based storage backend.
+ *
+ * Pure pass-through delegation to existing free functions in peer-registry.ts,
+ * cc-cli.ts, and health-check.ts. No added logic, logging, or transformation.
+ */
+export declare class FileBackend implements 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=file-backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-backend.d.ts","sourceRoot":"","sources":["../../src/backend/file-backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAKtD;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,cAAc;IAGhD,YAAY,CACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC;IAIpB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIhD,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAItD,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAIhC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7C,aAAa,CACX,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC;IAIzB,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAMrE,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIjE,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC;IAMzB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAG1C"}

package/dist/backend/file-backend.js

@@ -0,0 +1,46 @@
+import * as registry from "../services/peer-registry.js";
+import * as cli from "../services/cc-cli.js";
+import * as health from "../services/health-check.js";
+/**
+ * File-based storage backend.
+ *
+ * Pure pass-through delegation to existing free functions in peer-registry.ts,
+ * cc-cli.ts, and health-check.ts. No added logic, logging, or transformation.
+ */
+export class FileBackend {
+    // --- Peer management ---
+    registerPeer(peerId, sessionId, cwd, label) {
+        return registry.registerPeer(peerId, sessionId, cwd, label);
+    }
+    deregisterPeer(peerId) {
+        return registry.deregisterPeer(peerId);
+    }
+    getPeer(peerId) {
+        return registry.getPeer(peerId);
+    }
+    listPeers() {
+        return registry.listPeers();
+    }
+    updateLastSeen(peerId) {
+        return registry.updateLastSeen(peerId);
+    }
+    // --- Message state ---
+    recordMessage(record) {
+        return registry.recordMessage(record);
+    }
+    getHistory(peerId, limit) {
+        return registry.getHistory(peerId, limit);
+    }
+    // --- Message relay ---
+    validateSession(sessionId, cwd) {
+        return cli.validateSession(sessionId, cwd);
+    }
+    execClaude(sessionId, message, cwd, timeoutMs) {
+        return cli.execClaude(sessionId, message, cwd, timeoutMs);
+    }
+    // --- Health ---
+    checkHealth() {
+        return health.checkHealth();
+    }
+}
+//# sourceMappingURL=file-backend.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-backend.js","sourceRoot":"","sources":["../../src/backend/file-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,QAAQ,MAAM,8BAA8B,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,uBAAuB,CAAC;AAC7C,OAAO,KAAK,MAAM,MAAM,6BAA6B,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IACtB,0BAA0B;IAE1B,YAAY,CACV,MAAc,EACd,SAAiB,EACjB,GAAW,EACX,KAAa;QAEb,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;IAED,cAAc,CAAC,MAAc;QAC3B,OAAO,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,MAAc;QACpB,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,SAAS;QACP,OAAO,QAAQ,CAAC,SAAS,EAAE,CAAC;IAC9B,CAAC;IAED,cAAc,CAAC,MAAc;QAC3B,OAAO,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED,wBAAwB;IAExB,aAAa,CACX,MAA+C;QAE/C,OAAO,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,UAAU,CAAC,MAAe,EAAE,KAAc;QACxC,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,wBAAwB;IAExB,eAAe,CAAC,SAAiB,EAAE,GAAW;QAC5C,OAAO,GAAG,CAAC,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,UAAU,CACR,SAAiB,EACjB,OAAe,EACf,GAAW,EACX,SAAkB;QAElB,OAAO,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;IAC5D,CAAC;IAED,iBAAiB;IAEjB,WAAW;QACT,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC;IAC9B,CAAC;CACF"}

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

@@ -0,0 +1,94 @@
+import type { StorageBackend } from "./storage-backend.js";
+import type { PeerInfo, MessageRecord, CliExecResult } from "../types.js";
+import type { HealthCheckResult } from "../services/health-check.js";
+import type { HttpClient } from "../cloud/http-client.js";
+/**
+ * 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 declare class HttpBackend implements StorageBackend {
+    private readonly http;
+    private readonly sessionId;
+    constructor(http: HttpClient, sessionId: string);
+    /**
+     * 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).
+     */
+    registerPeer(peerId: string, _sessionId: string, cwd: string, label: string): Promise<PeerInfo>;
+    /**
+     * Deregister a peer from the cloud session.
+     * DELETE /api/sessions/:sessionId/peers/:peerId
+     *
+     * Returns true on success, false if the peer was not found.
+     */
+    deregisterPeer(peerId: string): Promise<boolean>;
+    /**
+     * Get a single peer by ID.
+     * No dedicated single-peer REST endpoint exists, so we list all peers
+     * and filter client-side.
+     */
+    getPeer(peerId: string): Promise<PeerInfo | undefined>;
+    /**
+     * List all peers in the cloud session.
+     * GET /api/sessions/:sessionId/peers
+     */
+    listPeers(): Promise<PeerInfo[]>;
+    /**
+     * Update last-seen timestamp for a peer.
+     * In cloud mode, the server updates lastSeenAt automatically on
+     * authenticated requests, so this is a no-op.
+     */
+    updateLastSeen(_peerId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    recordMessage(record: Omit<MessageRecord, "id" | "timestamp">): Promise<MessageRecord>;
+    /**
+     * Get message history from the cloud session.
+     * GET /api/sessions/:sessionId/messages
+     *
+     * Supports optional peerId filter and limit (default 100).
+     */
+    getHistory(peerId?: string, limit?: number): Promise<MessageRecord[]>;
+    /**
+     * Validate a session.
+     * In cloud mode, the server validates session authenticity on every
+     * authenticated request, so this always returns true.
+     */
+    validateSession(_sessionId: string, _cwd: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    execClaude(_sessionId: string, _message: string, _cwd: string, _timeoutMs?: number): Promise<CliExecResult>;
+    /**
+     * 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.
+     */
+    checkHealth(): Promise<HealthCheckResult>;
+}
+//# sourceMappingURL=http-backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http-backend.d.ts","sourceRoot":"","sources":["../../src/backend/http-backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAc1D;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,YAAW,cAAc;IAE9C,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM;IAGpC;;;;;;OAMG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC;IAKpB;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAatD;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAK5D;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAMtC;;;;OAIG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD;;;;;;;OAOG;IACG,aAAa,CACjB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,WAAW,CAAC,GAC9C,OAAO,CAAC,aAAa,CAAC;IAmBzB;;;;;OAKG;IACG,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAe3E;;;;OAIG;IACG,eAAe,CACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,CAAC;IAInB;;;;;;;OAOG;IACG,UAAU,CACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC;IAQzB;;;;;;OAMG;IACG,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAoChD"}