npm.io
0.5.0 • Published 3h ago

connector-protocol

Licence
MIT
Version
0.5.0
Deps
0
Size
469 kB
Vulns
0
Weekly
0

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/types re-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 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:

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-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
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

Keywords