# @essentialai/cogent

> Shared types, schemas, and contracts for Cogent Bridge

Latest version **3.9.0** (published 2026-09-03) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @essentialai/cogent
pnpm add @essentialai/cogent
yarn add @essentialai/cogent
bun add @essentialai/cogent
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.9.0 |
| Published | 2026-09-03 |
| First published | 2026-02-15 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 3 |
| Unpacked size | 159.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Pavlo Sidelov |
| Maintainers | essentialaisolutions |

## Links

- npm: https://www.npmjs.com/package/@essentialai/cogent
- Repository: https://github.com/eaisdevelopment/cogent
- Homepage: https://github.com/eaisdevelopment/cogent#readme
- Issues: https://github.com/eaisdevelopment/cogent/issues
- npm.io page: https://npm.io/package/@essentialai/cogent

## Dependencies (3)

- [bcryptjs](https://npm.io/package/bcryptjs.md) ^3.0.3
- [@a2a-js/sdk](https://npm.io/package/@a2a-js/sdk.md) ^1.0.1
- [slackify-markdown](https://npm.io/package/slackify-markdown.md) ^5.0.0

## Recent versions

- 3.9.0 (latest) — 2026-09-03
- 3.8.0 — 2026-08-12
- 3.7.0 — 2026-08-08
- 3.6.1 — 2026-08-06
- 3.6.0 — 2026-08-05
- 3.5.0 — 2026-06-23
- 3.4.0 — 2026-06-08
- 3.2.0 — 2026-06-01
- 3.1.0 — 2026-05-26
- 3.0.0 — 2026-03-19
- 2.0.0 — 2026-02-25
- 1.0.0 — 2026-02-15

## README

# @essentialai/cogent

[![npm version](https://img.shields.io/npm/v/@essentialai/cogent)](https://www.npmjs.com/package/@essentialai/cogent)
[![license](https://img.shields.io/npm/l/@essentialai/cogent)](https://www.npmjs.com/package/@essentialai/cogent)
[![downloads](https://img.shields.io/npm/dm/@essentialai/cogent)](https://www.npmjs.com/package/@essentialai/cogent)

Shared types, Zod schemas, and error codes for the [Cogent bridge](https://cogent.tools) ecosystem.

This package provides the contract layer used by both [`@essentialai/cogent-bridge`](https://www.npmjs.com/package/@essentialai/cogent-bridge) (MCP client) and [`@essentialai/cogent-server`](https://www.npmjs.com/package/@essentialai/cogent-server) (cloud relay server).

## Install

```bash
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:

```typescript
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:

```typescript
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:

```typescript
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)

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

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

## Links

- [cogent.tools](https://cogent.tools) -- Cloud relay server
- [GitHub](https://github.com/eaisdevelopment/cogent)

## License

Apache-2.0

---
_Source: https://npm.io/package/@essentialai/cogent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._