# connector-protocol

> WebSocket protocol schemas + shared DTOs for the Synx connector daemon (synx-connector). Zod schemas and inferred types for the daemon↔API control channel — zero private workspace dependencies.

Latest version **0.5.0** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install connector-protocol
pnpm add connector-protocol
yarn add connector-protocol
bun add connector-protocol
```

## Health

**Score 70/100 (B)** — status: active.

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

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2026-11-19 |
| First published | 2026-06-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 468.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | shawnsonb |
| Keywords | synx, connector, websocket, protocol, zod, schema, mcp, agent |

## Links

- npm: https://www.npmjs.com/package/connector-protocol
- Repository: https://github.com/ShawnsonB/Synx
- Homepage: https://github.com/ShawnsonB/Synx#readme
- Issues: https://github.com/ShawnsonB/Synx/issues
- npm.io page: https://npm.io/package/connector-protocol

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 0.5.0 (latest) — 2026-11-19
- 0.4.0 — 2026-06-15
- 0.3.0 — 2026-06-14
- 0.2.0 — 2026-06-11
- 0.0.1 — 2026-06-10

## README

# connector-protocol

WebSocket protocol schemas and shared DTOs for the **Synx connector daemon**
(`synx-connector`) — the local agent that bridges a developer's machine to the
Synx API so Claude-agent sessions can run against local folders.

This package is the single source of truth for the daemon ↔ API control-channel
message shapes. It is published so the public `synx-connector` CLI can depend on
it; it has **zero dependencies on private `@synx/*` workspace packages** and its
only runtime dependency is [`zod`](https://zod.dev).

> Where the private Synx API / web apps need these DTOs, `@synx/types`
> re-exports from this package. The dependency direction is always
> public ← private — never the reverse.

## Install

```sh
npm install connector-protocol zod
```

`zod` (`^4`) is a **peer dependency**, not a bundled one — install it alongside.
This package constructs and returns `z.ZodError` values across its API boundary
(`parseConnectorMessage` returns `{ success: false, error: ZodError }`), so it
must share the **same** zod instance as its consumer; a peer dependency
guarantees a single deduplicated copy and keeps `instanceof ZodError` checks
working. (`synx-connector` already depends on zod directly, satisfying the peer.)

## Usage

### Parse an inbound WS frame

`parseConnectorMessage` accepts a raw JSON string or an already-decoded value
and returns a discriminated result — it never throws for control flow.

```ts
import { parseConnectorMessage, serializeConnectorMessage } from "connector-protocol";

const result = parseConnectorMessage(rawFrame); // rawFrame: string | unknown
if (!result.success) {
  // result.error is a ZodError
  return;
}
switch (result.message.type) {
  case "session.start":
    // result.message is fully typed as SessionStartMessage here
    break;
}

// A bare heartbeat — minimum a daemon must send on each cadence tick.
const frame = serializeConnectorMessage({ type: "heartbeat", ts: Date.now() });

// A heartbeat carrying the optional liveness signal: the ids of sessions with
// an SDK turn currently in flight. The server bumps each listed session's
// `updated_at` so the UI can tell "agent busy, just quiet" from "daemon gone".
// `busySessionIds` is OPTIONAL and additive — omit it and you get the same
// behavior as before it existed.
const liveness = serializeConnectorMessage({
  type: "heartbeat",
  ts: Date.now(),
  busySessionIds: ["1f0c…", "2a7b…"],
});
```

> **Additive-field convention (for external daemon authors).** New OPTIONAL
> fields like `busySessionIds` are added without bumping the message `type`.
> This is safe in both directions: an older daemon that never sends the field
> behaves exactly as before, and an **older server strips unknown additive
> fields** during parsing (the message schemas are `z.object`, which drops
> unrecognized keys by default) — so a newer daemon still talks to an older
> server. Send new optional fields freely; never rely on the server echoing or
> persisting a field your server version predates.

### Heartbeat cadence (single source of truth)

The cadence and its derived timeout / liveness windows live in one place so the
daemon's send interval, the server's reap timeout, and the web liveness UI can
never drift apart:

```ts
import {
  CONNECTOR_HEARTBEAT, // { INTERVAL_MS, TIMEOUT_MULTIPLIER }
  HEARTBEAT_INTERVAL_MS, // send a heartbeat this often (ms)
  HEARTBEAT_TIMEOUT_MS, // no heartbeat for this long ⇒ peer presumed gone
} from "connector-protocol";
```

`HEARTBEAT_TIMEOUT_MS` is derived as `INTERVAL_MS × TIMEOUT_MULTIPLIER` (3× the
cadence), tolerating one missed beat plus clock skew before a peer is judged
gone. A custom daemon should send a `heartbeat` every `HEARTBEAT_INTERVAL_MS`.

### Session events (forward/backward compatible)

The `session.event` envelope keeps its `eventType` as an open `string` and its
`payload` as `unknown`, so a daemon built against an older version of this
package never hard-fails on an event type a newer server introduces. Decode the
payload with `parseSessionEvent`, which returns a `known` / `unknown` result:

```ts
import { parseSessionEvent } from "connector-protocol";

const parsed = parseSessionEvent(msg.eventType, msg.payload);
if (parsed.kind === "known") {
  // parsed.type narrows parsed.payload to the matching typed shape
} else {
  // unknown (or malformed-known) event — store/forward parsed.payload verbatim
}
```

This is the design choice for compatibility: **the envelope is permissive, the
typed validation is a second, opt-in step.** The SDK is known to emit
undocumented message types (e.g. `rate_limit_event`); they flow through as
`unknown` events rather than breaking the channel.

### Tool-result truncation (byte-accurate)

```ts
import { truncateToolResult, MAX_TOOL_RESULT_BYTES } from "connector-protocol";

const { content, truncated, originalBytes } = truncateToolResult(bigOutput);
```

Truncation is measured in **UTF-8 bytes**, not characters, and never splits a
multi-byte sequence.

### Flow control (backpressure)

One transport-agnostic backpressure module (`flow-control`), pure TypeScript
(no Node or DOM APIs; time and timers are injectable). It has two parts.

**Rate pacing: `TokenBucket` + `Pacer`.** A FIFO send queue releases an item
only when every attached bucket has the tokens for it. An idle link adds no
latency, because `enqueue` sends synchronously while tokens last. Order is
strictly preserved. The daemon sends every `session.event` and
`session.permission_request` through a pacer, both live sends and the
reconnect replay flush. Each pacer uses two buckets: one for its own session,
and one per-device bucket that all sessions share. The bucket settings are
`CONNECTOR_INGEST_PACING`. `maxAdmittedInWindow(config, windowMs)`
(burst + refill × window) stays below the gateway's ingest caps:

| Tier    | Bucket         | Max per 10 s | Gateway cap |
| ------- | -------------- | ------------ | ----------- |
| session | 16 burst, 9/s  | 106          | 120 (drop)  |
| device  | 60 burst, 45/s | 510          | 600 (4408)  |

The gap between each limit and its cap absorbs network jitter. A gateway test
checks that the daemon's limits stay below the caps.

```ts
import { CONNECTOR_INGEST_PACING, Pacer, TokenBucket } from "connector-protocol";

const device = new TokenBucket(CONNECTOR_INGEST_PACING.DEVICE); // shared
const outbox = new Pacer<Frame>({
  buckets: [new TokenBucket(CONNECTOR_INGEST_PACING.SESSION), device],
  send: (frame) => socket.trySend(frame), // false ⇒ transport down ⇒ queue discarded
});
outbox.enqueue(frame);
```

**Priority and ordering.** You can pass a `priority` predicate. Items it
matches skip ahead of every non-priority item in the queue but are still
charged tokens. The daemon uses this for `session.permission_request`, so a
blocked agent never waits behind a backlog of events. An item that costs zero
tokens (the daemon uses this for `session.end`) is sent as soon as it reaches
the front of the queue, so it always goes out after the items queued before it.
If `send` throws, the pacer treats it the same as a closed transport.

**Latency bound.** A permission request reaches the gateway within **250 ms**
of the agent asking. That holds behind a saturated event backlog and a
concurrent bulk stream. The load test at
`apps/connector/src/daemon/flow-load.test.ts` enforces it
(`PERMISSION_LATENCY_BOUND_MS`).

**Credit windows: `CreditSender` + `CreditReceiver`.** The receiver controls
the flow, one window per stream. This is built for protocol v2 `op.*` streams,
keyed by `opId` (design `docs/connector/protocol-v2.md`, sections 4.4 and D5).
The unit of credit depends on the stream (`CreditUnit`): `"bytes"` counts raw
decoded bytes for byte streams such as `fs.read`, and `"items"` counts items for
item streams such as `fs.list` and `fs.watch`. `CREDIT_WINDOW_DEFAULTS` mirrors
the protocol constants: 256 KiB for byte streams and 64 items for item streams.

- The window is **fixed per stream** and equals the initial credit. The sender
  can never hold more credit than the window. A grant that would push it above
  the window returns `credit-overflow` and applies nothing. Treat that as a
  protocol error.
- `open(id, initialCredit?)` rejects a byte window smaller than one chunk
  (64 KiB), and the error says why.
- The sender's methods are `open`, `canSend` (a check that changes nothing; it
  returns false while an earlier `spend` is still waiting), `consume` (throws
  `CreditUnavailableError` if there isn't enough credit), `grant`, and `close`.
  `spend` is the waiting version of `consume`, first in first out per stream.
  Closing a stream rejects any pending `spend` calls with `StreamClosedError`.
- The receiver's `open(id, window?)` takes an optional per-stream window.
  `onData(id, n)` returns `credit-exceeded` when the sender sends more than it
  was granted, which is a protocol violation. `release(id, n)` returns the
  credit to grant back. Grants are batched at `grantThreshold`, which defaults
  to half the window. `flush` grants whatever is left.

A stream that runs out of credit pauses only that stream. Sibling streams and
the control lane keep flowing. The primitive defines no wire frames: protocol v2
maps a grant onto `op.credit`.

### Close codes

```ts
import { CONNECTOR_CLOSE_CODES } from "connector-protocol";
// 4401 AUTH · 4403 REVOKED · 4408 PROTOCOL_VIOLATION
```

## Stability

Pre-1.0 (`0.x`): the protocol may change between minor versions until the
connector v1 surface settles.

## License

MIT

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