@ai-matrx/desktop-protocol 0.1.0

package/dist/frame.js

@@ -0,0 +1,109 @@
+// src/error.ts
+var DesktopProtocolError = class extends Error {
+  code;
+  retryable;
+  data;
+  constructor(code, message, options = {}) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "DesktopProtocolError";
+    this.code = code;
+    this.retryable = options.retryable ?? false;
+    this.data = options.data;
+  }
+  /** The wire body (ProtocolErrorBody) — what a core or relay sends for this error. */
+  toBody() {
+    return this.data === void 0 ? { code: this.code, message: this.message, retryable: this.retryable } : { code: this.code, message: this.message, retryable: this.retryable, data: this.data };
+  }
+};
+
+// src/frame.ts
+var FRAME_HEADER_BYTES = 16;
+var FRAME_VERSION = 1;
+var FRAME_STRUCT_FORMAT = ">BBBBIII";
+var FrameFlag = { FIN: 1, REPLAY: 2 };
+var FrameChannel = {
+  /** core→client: pty output, fs.read_stream bytes */
+  DATA: 0,
+  /** core→client: stderr of a non-pty process (reserved for exec.spawn in v1.1) */
+  STDERR: 1,
+  /** client→core: keystrokes / stdin to sid */
+  STDIN: 2,
+  /** core→client: serialized terminal screen (attach when since_seq is outside the ring) */
+  SNAPSHOT: 3,
+  /** relay↔device hop only: a JSON envelope carried inside a binary frame so the relay can route
+   *  by cid without parsing JSON. Never seen by clients. */
+  ENVELOPE: 255
+};
+var U32_MAX = 4294967295;
+var CHANNELS = new Set(Object.values(FrameChannel));
+function frameError(message) {
+  return new DesktopProtocolError("PROTOCOL_ERROR", message);
+}
+function checkU32(name, value) {
+  if (!Number.isInteger(value) || value < 0 || value > U32_MAX) throw frameError(`frame ${name} is not a u32: ${value}`);
+}
+function assertFrameHeader(h) {
+  if (h.version !== FRAME_VERSION) throw frameError(`unsupported frame version ${String(h.version)}`);
+  if (!Number.isInteger(h.flags) || h.flags < 0 || h.flags > 3) throw frameError(`reserved frame flag bits set: ${h.flags}`);
+  if (!CHANNELS.has(h.channel)) throw frameError(`unknown frame channel ${String(h.channel)}`);
+  checkU32("cid", h.cid);
+  checkU32("sid", h.sid);
+  checkU32("seq", h.seq);
+}
+function encodeFrame(h, payload) {
+  assertFrameHeader(h);
+  const out = new Uint8Array(FRAME_HEADER_BYTES + payload.byteLength);
+  const v = new DataView(out.buffer);
+  v.setUint8(0, h.version);
+  v.setUint8(1, h.flags);
+  v.setUint8(2, h.channel);
+  v.setUint8(3, 0);
+  v.setUint32(4, h.cid);
+  v.setUint32(8, h.sid);
+  v.setUint32(12, h.seq);
+  out.set(payload, FRAME_HEADER_BYTES);
+  return out;
+}
+function decodeFrame(buf) {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  if (bytes.byteLength < FRAME_HEADER_BYTES) throw frameError(`short frame: ${bytes.byteLength} bytes`);
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (v.getUint8(3) !== 0) throw frameError("reserved frame byte 3 is not 0");
+  const header = {
+    version: v.getUint8(0),
+    flags: v.getUint8(1),
+    channel: v.getUint8(2),
+    cid: v.getUint32(4),
+    sid: v.getUint32(8),
+    seq: v.getUint32(12)
+  };
+  assertFrameHeader(header);
+  return { header, payload: bytes.subarray(FRAME_HEADER_BYTES) };
+}
+function readCid(frame) {
+  if (frame.byteLength < FRAME_HEADER_BYTES) throw frameError(`short frame: ${frame.byteLength} bytes`);
+  return new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(4);
+}
+function stampCid(frame, cid) {
+  if (frame.byteLength < FRAME_HEADER_BYTES) throw frameError(`short frame: ${frame.byteLength} bytes`);
+  checkU32("cid", cid);
+  new DataView(frame.buffer, frame.byteOffset, frame.byteLength).setUint32(4, cid);
+  return frame;
+}
+function hasFlag(header, flag) {
+  return (header.flags & flag) !== 0;
+}
+export {
+  FRAME_HEADER_BYTES,
+  FRAME_STRUCT_FORMAT,
+  FRAME_VERSION,
+  FrameChannel,
+  FrameFlag,
+  assertFrameHeader,
+  decodeFrame,
+  encodeFrame,
+  hasFlag,
+  readCid,
+  stampCid
+};
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/error.ts","../src/frame.ts"],"sourcesContent":["/**\n * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a\n * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on\n * purpose: `./frame` (the relay hot path) throws it without pulling the schema graph.\n */\nimport type { ErrorCodeName, ErrorData } from \"./types\";\n\nexport class DesktopProtocolError extends Error {\n  readonly code: ErrorCodeName;\n  readonly retryable: boolean;\n  readonly data: ErrorData | undefined;\n\n  constructor(code: ErrorCodeName, message: string, options: { retryable?: boolean; data?: ErrorData; cause?: unknown } = {}) {\n    super(message, options.cause === undefined ? undefined : { cause: options.cause });\n    this.name = \"DesktopProtocolError\";\n    this.code = code;\n    this.retryable = options.retryable ?? false;\n    this.data = options.data;\n  }\n\n  /** The wire body (ProtocolErrorBody) — what a core or relay sends for this error. */\n  toBody(): { code: ErrorCodeName; message: string; retryable: boolean; data?: ErrorData } {\n    return this.data === undefined\n      ? { code: this.code, message: this.message, retryable: this.retryable }\n      : { code: this.code, message: this.message, retryable: this.retryable, data: this.data };\n  }\n}\n\nexport function isDesktopProtocolError(value: unknown): value is DesktopProtocolError {\n  return value instanceof DesktopProtocolError || (value instanceof Error && value.name === \"DesktopProtocolError\" && \"code\" in value);\n}\n","/**\n * `@ai-matrx/desktop-protocol/frame` — the 16-byte binary frame codec. ZOD-FREE by design: the\n * relay Worker's hot path imports only this entry and must stay tiny.\n *\n *   off size field     notes\n *   0   u8   version   = 1\n *   1   u8   flags     bit0 FIN (last frame of this stream), bit1 REPLAY (from ring buffer),\n *                      bits2-7 reserved = 0\n *   2   u8   channel   see FrameChannel\n *   3   u8   reserved  = 0\n *   4   u32  cid       relay connection id. 0 on every client↔relay hop; the relay stamps it on\n *                      the relay→device hop and strips it on the way back (rewrites 4 bytes in\n *                      place — the relay never parses payloads).\n *   8   u32  sid       stream id, announced by the core in stream{meta:{kind:\"open\",sid}}\n *   12  u32  seq       per-stream frame sequence, starts at 1, strictly +1\n *\n * Big-endian. Payload length = message length − 16 (one frame = one WS binary message).\n * Python struct format: \">BBBBIII\". The zod twin (FrameHeader in the root entry, and so the JSON\n * Schema and Pydantic model) is checked against this file by src/frame.test.ts.\n */\nimport { DesktopProtocolError } from \"./error\";\n\nexport const FRAME_HEADER_BYTES = 16 as const;\nexport const FRAME_VERSION = 1 as const;\nexport const FRAME_STRUCT_FORMAT = \">BBBBIII\" as const;\nexport const FrameFlag = { FIN: 0b01, REPLAY: 0b10 } as const;\nexport const FrameChannel = {\n  /** core→client: pty output, fs.read_stream bytes */\n  DATA: 0,\n  /** core→client: stderr of a non-pty process (reserved for exec.spawn in v1.1) */\n  STDERR: 1,\n  /** client→core: keystrokes / stdin to sid */\n  STDIN: 2,\n  /** core→client: serialized terminal screen (attach when since_seq is outside the ring) */\n  SNAPSHOT: 3,\n  /** relay↔device hop only: a JSON envelope carried inside a binary frame so the relay can route\n   *  by cid without parsing JSON. Never seen by clients. */\n  ENVELOPE: 255,\n} as const;\n\nexport type FrameChannelValue = (typeof FrameChannel)[keyof typeof FrameChannel];\n\nexport interface FrameHeader {\n  version: typeof FRAME_VERSION;\n  /** 0..3 — FrameFlag bits. */\n  flags: number;\n  channel: FrameChannelValue;\n  cid: number;\n  sid: number;\n  seq: number;\n}\n\nexport interface DecodedFrame {\n  header: FrameHeader;\n  /** A VIEW into the input buffer (no copy). Copy it if you keep it past the input's lifetime. */\n  payload: Uint8Array;\n}\n\nconst U32_MAX = 4_294_967_295;\nconst CHANNELS: ReadonlySet<number> = new Set(Object.values(FrameChannel));\n\nfunction frameError(message: string): DesktopProtocolError {\n  return new DesktopProtocolError(\"PROTOCOL_ERROR\", message);\n}\n\nfunction checkU32(name: string, value: number): void {\n  if (!Number.isInteger(value) || value < 0 || value > U32_MAX) throw frameError(`frame ${name} is not a u32: ${value}`);\n}\n\n/** Validate a header without zod. Throws DesktopProtocolError(PROTOCOL_ERROR). */\nexport function assertFrameHeader(h: FrameHeader): void {\n  if (h.version !== FRAME_VERSION) throw frameError(`unsupported frame version ${String(h.version)}`);\n  if (!Number.isInteger(h.flags) || h.flags < 0 || h.flags > 3) throw frameError(`reserved frame flag bits set: ${h.flags}`);\n  if (!CHANNELS.has(h.channel)) throw frameError(`unknown frame channel ${String(h.channel)}`);\n  checkU32(\"cid\", h.cid);\n  checkU32(\"sid\", h.sid);\n  checkU32(\"seq\", h.seq);\n}\n\nexport function encodeFrame(h: FrameHeader, payload: Uint8Array): Uint8Array {\n  assertFrameHeader(h);\n  const out = new Uint8Array(FRAME_HEADER_BYTES + payload.byteLength);\n  const v = new DataView(out.buffer);\n  v.setUint8(0, h.version);\n  v.setUint8(1, h.flags);\n  v.setUint8(2, h.channel);\n  v.setUint8(3, 0);\n  v.setUint32(4, h.cid);\n  v.setUint32(8, h.sid);\n  v.setUint32(12, h.seq);\n  out.set(payload, FRAME_HEADER_BYTES);\n  return out;\n}\n\nexport function decodeFrame(buf: ArrayBuffer | Uint8Array): DecodedFrame {\n  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);\n  if (bytes.byteLength < FRAME_HEADER_BYTES) throw frameError(`short frame: ${bytes.byteLength} bytes`);\n  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n  if (v.getUint8(3) !== 0) throw frameError(\"reserved frame byte 3 is not 0\");\n  const header = {\n    version: v.getUint8(0),\n    flags: v.getUint8(1),\n    channel: v.getUint8(2),\n    cid: v.getUint32(4),\n    sid: v.getUint32(8),\n    seq: v.getUint32(12),\n  } as FrameHeader;\n  assertFrameHeader(header);\n  return { header, payload: bytes.subarray(FRAME_HEADER_BYTES) };\n}\n\n/** Read only the 4-byte cid (relay routing) without decoding the rest. */\nexport function readCid(frame: Uint8Array): number {\n  if (frame.byteLength < FRAME_HEADER_BYTES) throw frameError(`short frame: ${frame.byteLength} bytes`);\n  return new DataView(frame.buffer, frame.byteOffset, frame.byteLength).getUint32(4);\n}\n\n/** Relay hot path: rewrite only the cid IN PLACE, never touch the payload. Returns the same array. */\nexport function stampCid(frame: Uint8Array, cid: number): Uint8Array {\n  if (frame.byteLength < FRAME_HEADER_BYTES) throw frameError(`short frame: ${frame.byteLength} bytes`);\n  checkU32(\"cid\", cid);\n  new DataView(frame.buffer, frame.byteOffset, frame.byteLength).setUint32(4, cid);\n  return frame;\n}\n\nexport function hasFlag(header: FrameHeader, flag: (typeof FrameFlag)[keyof typeof FrameFlag]): boolean {\n  return (header.flags & flag) !== 0;\n}\n"],"mappings":"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","names":[]}