@arcturn/protocol

Internal to the arcturn CLI. Published so arcturn resolves; its API may change in any release without a major version bump. Embedders should depend on @arcturn/core and @arcturn/ai, whose surfaces are the ones the SDK documents.

NDJSON wire-protocol framing and validation for Arcturn server mode. This is the typed contract shared by @arcturn/server (the host) and any remote client — a web UI, a mobile app, or another process driving an arcturn serve instance.

What's in it

src/index.ts exports:

• PROTOCOL_VERSION — re-exported from @arcturn/types.
• createProtocolClient, ProtocolClient, ProtocolClientOptions — a client over any WebSocketLike transport, plus its error types (ProtocolClientError, ProtocolClosedError, ProtocolRequestError, ProtocolTimeoutError, ProtocolVersionMismatchError) and ClientErrorCode.
• FrameDecoder, encodeFrame, isProtocolError, DEFAULT_MAX_LINE_LENGTH — NDJSON framing for stream transports (one JSON value per line, LF-delimited).
• errorResponse, okResponse, eventMessage, sessionsMessage, ErrorCode — server response builders.
• nextRequestId, RequestIdGenerator — request id generation.
• validateClientRequest, validateServerMessage, validatePermissionDecision, validatePermissionRule, validateSessionHeader — runtime validation for every frame crossing the wire.

Install

Arcturn is not yet published to npm. Until it is, use it from a clone of the monorepo as a pnpm workspace package:

git clone https://github.com/sitharaj88/arcturn.git && cd arcturn
pnpm install && pnpm -r build

Then depend on it from another workspace package: "@arcturn/protocol": "workspace:*".

Usage

Decoding NDJSON frames as they arrive on a stream transport:

import { FrameDecoder, isProtocolError } from "@arcturn/protocol";

const decoder = new FrameDecoder();
for (const frame of decoder.feed(chunk)) {
  if (isProtocolError(frame)) {
    console.error(frame.code, frame.message);
    continue;
  }
  // frame is a parsed JSON value — validate it against the expected message shape
}

Encoding an outgoing frame: encodeFrame({ id: "1", method: "listSessions", params: {} }). @arcturn/server's ArcturnServer speaks a one-frame-per-WebSocket-text-message variant of this contract; see its docs for the full server-side wiring.

Docs

• Server mode — wire protocol, authentication, threat model.
• Embedding with the SDK — how this fits with the rest of the runtime.

License

Apache-2.0 — see LICENSE.

👤 Author

Sitharaj Seenivasan

• 🌐 Website: sitharaj.in
• 💼 LinkedIn: sitharaj08
• 💻 GitHub: sitharaj88

☕ Support

If this project helps you, consider buying me a coffee — it keeps the work going.

📄 License

Licensed under the Apache License 2.0. © 2026 Sitharaj Seenivasan.