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.
Where the private Synx API / web apps need these DTOs,
@synx/typesre-exports from this package. The dependency direction is always public ← private — never the reverse.
Install
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.
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
busySessionIdsare added without bumping the messagetype. 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 arez.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:
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:
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)
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.
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-overflowand 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 earlierspendis still waiting),consume(throwsCreditUnavailableErrorif there isn't enough credit),grant, andclose.spendis the waiting version ofconsume, first in first out per stream. Closing a stream rejects any pendingspendcalls withStreamClosedError. - The receiver's
open(id, window?)takes an optional per-stream window.onData(id, n)returnscredit-exceededwhen 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 atgrantThreshold, which defaults to half the window.flushgrants 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
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