@essentialai/cogent

Shared types, Zod schemas, and error codes for the Cogent bridge ecosystem.

This package provides the contract layer used by both @essentialai/cogent-bridge (MCP client) and @essentialai/cogent-server (cloud relay server).

Install

npm install @essentialai/cogent

Peer dependency: zod (^3.25.0 || ^4.0.0)

What's Included

Type Definitions

• Session types -- SessionInfo, CreateSessionRequest/Response, JoinSessionRequest/Response
• Peer types -- PeerInfo, RegisterPeerRequest/Response, ListPeersResponse
• Message types -- SendMessageRequest/Response, MessageRecord, GetHistoryResponse
• WebSocket frame types -- WsFrame, PeerConnectedFrame, MessagePushFrame, HeartbeatFrame
• API contracts -- RouteContract mapping all 9 REST endpoints

Zod Schemas

Every type has a corresponding Zod schema for runtime validation:

import { CreateSessionRequestSchema, JoinSessionResponseSchema } from "@essentialai/cogent";

// Validate incoming request
const parsed = CreateSessionRequestSchema.parse(requestBody);

// Validate API response
const response = JoinSessionResponseSchema.parse(apiResponse);

Error Codes

31 unified error codes across file, HTTP, WebSocket, and auth domains:

import { ErrorCode, BridgeError } from "@essentialai/cogent";

throw new BridgeError(
  ErrorCode.SESSION_NOT_FOUND,
  "Session abc-123 not found",
  "Check the session ID or create a new session"
);

Route Contracts

Type-safe API endpoint definitions:

import { API_ROUTES } from "@essentialai/cogent";

// API_ROUTES.createSession -> { method, path, request schema, response schema }
// API_ROUTES.joinSession -> ...
// API_ROUTES.registerPeer -> ...

Helpers

• generateSessionId() / generatePeerId() / generateMessageId() -- UUID v4 generators
• generateSessionLabel() -- human-readable adjective-noun-hex labels
• isValidSessionId() / isValidSessionLabel() -- format validators

File Transport Types (subpath)

import { BridgeState, PeerInfo } from "@essentialai/cogent/file";

Types for the local file-based transport (used in local-only mode).

Links

• cogent.tools -- Cloud relay server
• GitHub

License

Apache-2.0