vibe-remote-protocol 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jun-young1993
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# vibe-remote-protocol
+
+VibeRemote binary WebSocket protocol v3 — opcode constants, encoder/decoder helpers, and TypeScript types for `APP_JSON` messages.
+
+The single source of truth that lets `vibe-remote-relay`, the mobile client (Flutter / Dart), and the desktop agent (Electron / TypeScript) communicate over the same wire format.
+
+[한국어 README](./README_KR.md)
+
+---
+
+## Install
+
+```bash
+npm install vibe-remote-protocol
+```
+
+## Quick start
+
+```ts
+import {
+  OPCODE,
+  encodeAppJson,
+  encodeFrameSnapshotPush,
+  readOpcode,
+  isAppJsonMessage,
+  type AppJsonMessage,
+} from 'vibe-remote-protocol';
+
+// 1) Send a hello message
+const hello = encodeAppJson({ type: 'hello', protocolVersion: 3 });
+ws.send(hello);
+
+// 2) Inspect the opcode of an incoming frame
+const op = readOpcode(buffer);
+if (op === OPCODE.APP_JSON) {
+  const json: AppJsonMessage = JSON.parse(buffer.toString('utf-8', 1));
+  if (isAppJsonMessage(json, 'machine_list')) {
+    console.log(json.machines);
+  }
+}
+```
+
+## Opcodes
+
+| Opcode | Name | Direction | Payload |
+|---|---|---|---|
+| `0x00` | `PTY_DATA` | desktop → mobile | raw PTY UTF-8 ANSI stream |
+| `0x01` | `APP_JSON` | bidirectional | UTF-8 JSON (`AppJsonMessage`) |
+| `0x02` | `RESIZE` | mobile → desktop | `[cols u32 BE][rows u32 BE]`, fire-and-forget |
+| `0x03` | `FRAME_SNAPSHOT` | relay → mobile | `[id len u32][id][ansi len u32][ansi]` |
+| `0x04` | `GRID_SNAPSHOT` | desktop → mobile | A3 server-truth full snapshot |
+| `0x05` | `GRID_DIFF` | desktop → mobile | A3 incremental cell ops |
+| `0xFF` | `PROTOCOL_ERROR` | bidirectional | `[reason u8]` |
+
+`0x06`–`0xFE` are reserved.
+
+## Message types
+
+The `AppJsonMessage` discriminated union includes:
+
+- `hello`, `hello_ack` — version negotiation
+- `cap.req`, `cap.ack` — A3 capability negotiation
+- `snapshot.req` — request a fresh full grid snapshot
+- `machine_list`, `session_attach`, `connection_status`
+- `terminal_data`, `claude_state`, `pty_status`, `git_result`
+- `session_replay`, `grid_resize_capped`, `protocol_mismatch`
+- `ping`, `pong`, `error`, `input`
+
+See `dist/messages.d.ts` (or [`src/messages.ts`](./src/messages.ts)) for full field definitions.
+
+## Fixtures
+
+`fixtures/binary-protocol-v3.fixtures.json` is the cross-validation fixture set used by all three repos (mobile / relay / desktop). Each entry contains the wire hex plus the expected parse result for one opcode. The mobile (Dart) and desktop implementations round-trip the same file.
+
+## Versioning policy
+
+- **Major** — opcode added/removed or wire format change
+- **Minor** — new `AppJsonMessage` type (backward compatible)
+- **Patch** — docs / typing fixes only
+
+Three-repo simultaneous-PR policy — see `binary-protocol-v3.md` §10.
+
+For maintainers cutting a new npm release, see [PUBLISHING.md](./PUBLISHING.md).
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/README_KR.md

@@ -0,0 +1,87 @@
+# vibe-remote-protocol
+
+VibeRemote binary WebSocket protocol v3 — opcode 상수, encoder/decoder helper, 그리고 `APP_JSON` 메시지의 TypeScript 타입.
+
+`vibe-remote-relay`, 모바일 클라이언트(Flutter / Dart), 데스크탑 에이전트(Electron / TypeScript) 가 동일한 wire format 으로 통신하기 위한 단일 source of truth.
+
+[English README](./README.md)
+
+---
+
+## 설치
+
+```bash
+npm install vibe-remote-protocol
+```
+
+## Quick start
+
+```ts
+import {
+  OPCODE,
+  encodeAppJson,
+  encodeFrameSnapshotPush,
+  readOpcode,
+  isAppJsonMessage,
+  type AppJsonMessage,
+} from 'vibe-remote-protocol';
+
+// 1) hello 메시지 송신
+const hello = encodeAppJson({ type: 'hello', protocolVersion: 3 });
+ws.send(hello);
+
+// 2) 수신 frame 의 opcode 확인
+const op = readOpcode(buffer);
+if (op === OPCODE.APP_JSON) {
+  const json: AppJsonMessage = JSON.parse(buffer.toString('utf-8', 1));
+  if (isAppJsonMessage(json, 'machine_list')) {
+    console.log(json.machines);
+  }
+}
+```
+
+## Opcode
+
+| Opcode | Name | 방향 | Payload |
+|---|---|---|---|
+| `0x00` | `PTY_DATA` | desktop → mobile | raw PTY UTF-8 ANSI stream |
+| `0x01` | `APP_JSON` | 양방향 | UTF-8 JSON (`AppJsonMessage`) |
+| `0x02` | `RESIZE` | mobile → desktop | `[cols u32 BE][rows u32 BE]`, fire-and-forget |
+| `0x03` | `FRAME_SNAPSHOT` | relay → mobile | `[id len u32][id][ansi len u32][ansi]` |
+| `0x04` | `GRID_SNAPSHOT` | desktop → mobile | A3 server-truth full snapshot |
+| `0x05` | `GRID_DIFF` | desktop → mobile | A3 incremental cell ops |
+| `0xFF` | `PROTOCOL_ERROR` | 양방향 | `[reason u8]` |
+
+`0x06` ~ `0xFE` reserved.
+
+## 메시지 타입
+
+`AppJsonMessage` discriminated union 에는 다음이 포함됩니다:
+
+- `hello`, `hello_ack` — version negotiation
+- `cap.req`, `cap.ack` — A3 capability negotiation
+- `snapshot.req` — full grid snapshot 재요청
+- `machine_list`, `session_attach`, `connection_status`
+- `terminal_data`, `claude_state`, `pty_status`, `git_result`
+- `session_replay`, `grid_resize_capped`, `protocol_mismatch`
+- `ping`, `pong`, `error`, `input`
+
+자세한 필드는 `dist/messages.d.ts` 또는 [`src/messages.ts`](./src/messages.ts) 참고.
+
+## Fixture
+
+`fixtures/binary-protocol-v3.fixtures.json` — 3 repo (mobile / relay / desktop) cross-validation 용. 각 opcode 별 wire hex + expected parse 결과. mobile (Dart) 과 desktop 의 구현도 동일 fixture 로 round-trip 검증.
+
+## 버전 정책
+
+- **Major** — opcode 추가/제거 또는 wire format 변경
+- **Minor** — `AppJsonMessage` 타입 추가 (호환)
+- **Patch** — 문서/타입 보정
+
+3 repo 동시 PR 정책 — `binary-protocol-v3.md` §10 참고.
+
+새 npm 릴리즈를 cut 하는 maintainer 는 [PUBLISHING_KR.md](./PUBLISHING_KR.md) 참고.
+
+## License
+
+MIT — [`LICENSE`](./LICENSE) 파일 참조.

package/dist/binary-protocol.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Binary protocol v3 — opcode 상수 + helpers.
+ *
+ * 단일 source of truth: spec 문서 `binary-protocol-v3.md` (모바일 리포에 보관).
+ * opcode 상수 / encoding 규칙이 spec 문서와 *반드시* 일치해야 한다 — fixture-driven
+ * contract test (`fixtures/binary-protocol-v3.fixtures.json`) 가 wire 호환을 영구 검증.
+ *
+ * 본 파일은:
+ *  - opcode 식별 helpers (host PTY_DATA / mobile session_attach 분기)
+ *  - FRAME_SNAPSHOT push encoding (Approach B 의 last-frame replay)
+ *  - PROTOCOL_ERROR 송신 helpers
+ *  - APP_JSON encoder
+ */
+export declare const OPCODE: {
+    readonly PTY_DATA: 0;
+    readonly APP_JSON: 1;
+    readonly RESIZE: 2;
+    readonly FRAME_SNAPSHOT: 3;
+    readonly GRID_SNAPSHOT: 4;
+    readonly GRID_DIFF: 5;
+    readonly PROTOCOL_ERROR: 255;
+};
+export declare const PROTOCOL_ERROR_REASON: {
+    readonly UNKNOWN_OPCODE: 1;
+    readonly MALFORMED_PAYLOAD: 2;
+    readonly VERSION_MISMATCH: 3;
+    readonly UNAUTHORIZED: 4;
+};
+/**
+ * 본 프로토콜 패키지가 구현하는 binary protocol version.
+ * 양 client (mobile / desktop) 의 `kRelayProtocolVersion` / `PROTOCOL_VERSION`
+ * 과 *동시* 변경 필수.
+ */
+export declare const PROTOCOL_VERSION_V3 = 3;
+/**
+ * frame 의 opcode 만 빠르게 식별. binary frame 검증 + 라우팅 분기에 사용.
+ * empty buffer 면 -1 리턴 (호출자가 close 결정).
+ */
+export declare function readOpcode(buffer: Buffer): number;
+/**
+ * APP_JSON frame 의 payload 가 `"session_attach"` 를 포함하는지 빠르게 검사.
+ *
+ * substring fast path — JSON parse 회피로 high-frequency 메시지 (예: terminal_input)
+ * 의 처리 비용을 상수로. true 일 때만 호출자가 [parseAppJsonSessionAttach] 로 정확히
+ * 검증.
+ *
+ * False positive 가능 (예: terminal_input 의 data field 가 "session_attach" string
+ * 포함) — 호출자가 JSON parse 후 type 필드로 최종 결정.
+ */
+export declare function isAppJsonSessionAttachLike(buffer: Buffer): boolean;
+/**
+ * APP_JSON session_attach payload 를 JSON parse. malformed / 잘못된 type 이면 null.
+ */
+export declare function parseAppJsonSessionAttach(buffer: Buffer): {
+    machineId: string;
+} | null;
+/**
+ * FRAME_SNAPSHOT (0x03) frame encode.
+ *
+ * Wire format:
+ * `[0x03] [machineId len: BE u32] [machineId UTF-8] [ansi len: BE u32] [ansi UTF-8]`
+ */
+export declare function encodeFrameSnapshotPush(machineId: string, ansi: string): Buffer;
+/**
+ * PROTOCOL_ERROR (0xFF) frame encode.
+ */
+export declare function encodeProtocolError(reason: number): Buffer;
+/**
+ * APP_JSON (0x01) frame encode — server-initiated message 송신용.
+ */
+export declare function encodeAppJson(data: object): Buffer;
+/**
+ * RESIZE (0x02) frame encode — mobile → host. fire-and-forget, ack 없음.
+ *
+ * Wire format: `[0x02] [cols: BE u32] [rows: BE u32]`
+ */
+export declare function encodeResize(cols: number, rows: number): Buffer;
+//# sourceMappingURL=binary-protocol.d.ts.map

package/dist/binary-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-protocol.d.ts","sourceRoot":"","sources":["../src/binary-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,MAAM;;;;;;;;CAQT,CAAC;AAEX,eAAO,MAAM,qBAAqB;;;;;CAKxB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAKlE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,GACb;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoB9B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,MAAM,CAeR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/D"}

package/dist/binary-protocol.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Binary protocol v3 — opcode 상수 + helpers.
+ *
+ * 단일 source of truth: spec 문서 `binary-protocol-v3.md` (모바일 리포에 보관).
+ * opcode 상수 / encoding 규칙이 spec 문서와 *반드시* 일치해야 한다 — fixture-driven
+ * contract test (`fixtures/binary-protocol-v3.fixtures.json`) 가 wire 호환을 영구 검증.
+ *
+ * 본 파일은:
+ *  - opcode 식별 helpers (host PTY_DATA / mobile session_attach 분기)
+ *  - FRAME_SNAPSHOT push encoding (Approach B 의 last-frame replay)
+ *  - PROTOCOL_ERROR 송신 helpers
+ *  - APP_JSON encoder
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION_V3 = exports.PROTOCOL_ERROR_REASON = exports.OPCODE = void 0;
+exports.readOpcode = readOpcode;
+exports.isAppJsonSessionAttachLike = isAppJsonSessionAttachLike;
+exports.parseAppJsonSessionAttach = parseAppJsonSessionAttach;
+exports.encodeFrameSnapshotPush = encodeFrameSnapshotPush;
+exports.encodeProtocolError = encodeProtocolError;
+exports.encodeAppJson = encodeAppJson;
+exports.encodeResize = encodeResize;
+exports.OPCODE = {
+    PTY_DATA: 0x00,
+    APP_JSON: 0x01,
+    RESIZE: 0x02,
+    FRAME_SNAPSHOT: 0x03,
+    GRID_SNAPSHOT: 0x04,
+    GRID_DIFF: 0x05,
+    PROTOCOL_ERROR: 0xff,
+};
+exports.PROTOCOL_ERROR_REASON = {
+    UNKNOWN_OPCODE: 0x01,
+    MALFORMED_PAYLOAD: 0x02,
+    VERSION_MISMATCH: 0x03,
+    UNAUTHORIZED: 0x04,
+};
+/**
+ * 본 프로토콜 패키지가 구현하는 binary protocol version.
+ * 양 client (mobile / desktop) 의 `kRelayProtocolVersion` / `PROTOCOL_VERSION`
+ * 과 *동시* 변경 필수.
+ */
+exports.PROTOCOL_VERSION_V3 = 3;
+/**
+ * frame 의 opcode 만 빠르게 식별. binary frame 검증 + 라우팅 분기에 사용.
+ * empty buffer 면 -1 리턴 (호출자가 close 결정).
+ */
+function readOpcode(buffer) {
+    if (buffer.length === 0)
+        return -1;
+    return buffer.readUInt8(0);
+}
+/**
+ * APP_JSON frame 의 payload 가 `"session_attach"` 를 포함하는지 빠르게 검사.
+ *
+ * substring fast path — JSON parse 회피로 high-frequency 메시지 (예: terminal_input)
+ * 의 처리 비용을 상수로. true 일 때만 호출자가 [parseAppJsonSessionAttach] 로 정확히
+ * 검증.
+ *
+ * False positive 가능 (예: terminal_input 의 data field 가 "session_attach" string
+ * 포함) — 호출자가 JSON parse 후 type 필드로 최종 결정.
+ */
+function isAppJsonSessionAttachLike(buffer) {
+    if (buffer.length < 2)
+        return false;
+    if (buffer.readUInt8(0) !== exports.OPCODE.APP_JSON)
+        return false;
+    const text = buffer.toString('utf-8', 1);
+    return text.includes('"session_attach"');
+}
+/**
+ * APP_JSON session_attach payload 를 JSON parse. malformed / 잘못된 type 이면 null.
+ */
+function parseAppJsonSessionAttach(buffer) {
+    if (buffer.readUInt8(0) !== exports.OPCODE.APP_JSON)
+        return null;
+    const text = buffer.toString('utf-8', 1);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        parsed.type !== 'session_attach') {
+        return null;
+    }
+    const rawMachineId = parsed.machineId;
+    return {
+        machineId: typeof rawMachineId === 'string' ? rawMachineId : '',
+    };
+}
+/**
+ * FRAME_SNAPSHOT (0x03) frame encode.
+ *
+ * Wire format:
+ * `[0x03] [machineId len: BE u32] [machineId UTF-8] [ansi len: BE u32] [ansi UTF-8]`
+ */
+function encodeFrameSnapshotPush(machineId, ansi) {
+    const idBytes = Buffer.from(machineId, 'utf-8');
+    const ansiBytes = Buffer.from(ansi, 'utf-8');
+    const frame = Buffer.alloc(1 + 4 + idBytes.length + 4 + ansiBytes.length);
+    let offset = 0;
+    frame.writeUInt8(exports.OPCODE.FRAME_SNAPSHOT, offset);
+    offset += 1;
+    frame.writeUInt32BE(idBytes.length, offset);
+    offset += 4;
+    idBytes.copy(frame, offset);
+    offset += idBytes.length;
+    frame.writeUInt32BE(ansiBytes.length, offset);
+    offset += 4;
+    ansiBytes.copy(frame, offset);
+    return frame;
+}
+/**
+ * PROTOCOL_ERROR (0xFF) frame encode.
+ */
+function encodeProtocolError(reason) {
+    const frame = Buffer.alloc(2);
+    frame.writeUInt8(exports.OPCODE.PROTOCOL_ERROR, 0);
+    frame.writeUInt8(reason & 0xff, 1);
+    return frame;
+}
+/**
+ * APP_JSON (0x01) frame encode — server-initiated message 송신용.
+ */
+function encodeAppJson(data) {
+    const body = Buffer.from(JSON.stringify(data), 'utf-8');
+    const frame = Buffer.alloc(1 + body.length);
+    frame.writeUInt8(exports.OPCODE.APP_JSON, 0);
+    body.copy(frame, 1);
+    return frame;
+}
+/**
+ * RESIZE (0x02) frame encode — mobile → host. fire-and-forget, ack 없음.
+ *
+ * Wire format: `[0x02] [cols: BE u32] [rows: BE u32]`
+ */
+function encodeResize(cols, rows) {
+    const frame = Buffer.alloc(9);
+    frame.writeUInt8(exports.OPCODE.RESIZE, 0);
+    frame.writeUInt32BE(cols, 1);
+    frame.writeUInt32BE(rows, 5);
+    return frame;
+}
+//# sourceMappingURL=binary-protocol.js.map

package/dist/binary-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-protocol.js","sourceRoot":"","sources":["../src/binary-protocol.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @vibe-remote/protocol — VibeRemote binary WebSocket protocol v3.
+ *
+ * Public API:
+ *   - opcode 상수: OPCODE, PROTOCOL_ERROR_REASON, PROTOCOL_VERSION_V3
+ *   - encoders: encodeAppJson, encodeFrameSnapshotPush, encodeProtocolError, encodeResize
+ *   - inspectors: readOpcode, isAppJsonSessionAttachLike, parseAppJsonSessionAttach
+ *   - APP_JSON 메시지 타입: AppJsonMessage 및 모든 Msg* 인터페이스
+ */
+export { OPCODE, PROTOCOL_ERROR_REASON, PROTOCOL_VERSION_V3, readOpcode, isAppJsonSessionAttachLike, parseAppJsonSessionAttach, encodeFrameSnapshotPush, encodeProtocolError, encodeAppJson, encodeResize, } from './binary-protocol';
+export type { AppJsonMessage, Machine, PtyStatus, ClaudeState, ClientCapability, SnapshotReqReason, PtyAuthorityMode, MsgHello, MsgHelloAck, MsgCapReq, MsgCapAck, MsgSnapshotReq, MsgMachineList, MsgSessionAttach, MsgConnectionStatus, MsgTerminalData, MsgClaudeState, MsgPtyStatus, MsgGitResult, MsgSessionReplay, MsgGridResizeCapped, MsgProtocolMismatch, MsgPing, MsgPong, MsgError, MsgInput, } from './messages';
+export { isAppJsonMessage } from './messages';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,MAAM,EACN,qBAAqB,EACrB,mBAAmB,EACnB,UAAU,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,EACb,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,cAAc,EACd,OAAO,EACP,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,SAAS,EACT,SAAS,EACT,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,OAAO,EACP,OAAO,EACP,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * @vibe-remote/protocol — VibeRemote binary WebSocket protocol v3.
+ *
+ * Public API:
+ *   - opcode 상수: OPCODE, PROTOCOL_ERROR_REASON, PROTOCOL_VERSION_V3
+ *   - encoders: encodeAppJson, encodeFrameSnapshotPush, encodeProtocolError, encodeResize
+ *   - inspectors: readOpcode, isAppJsonSessionAttachLike, parseAppJsonSessionAttach
+ *   - APP_JSON 메시지 타입: AppJsonMessage 및 모든 Msg* 인터페이스
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAppJsonMessage = exports.encodeResize = exports.encodeAppJson = exports.encodeProtocolError = exports.encodeFrameSnapshotPush = exports.parseAppJsonSessionAttach = exports.isAppJsonSessionAttachLike = exports.readOpcode = exports.PROTOCOL_VERSION_V3 = exports.PROTOCOL_ERROR_REASON = exports.OPCODE = void 0;
+var binary_protocol_1 = require("./binary-protocol");
+Object.defineProperty(exports, "OPCODE", { enumerable: true, get: function () { return binary_protocol_1.OPCODE; } });
+Object.defineProperty(exports, "PROTOCOL_ERROR_REASON", { enumerable: true, get: function () { return binary_protocol_1.PROTOCOL_ERROR_REASON; } });
+Object.defineProperty(exports, "PROTOCOL_VERSION_V3", { enumerable: true, get: function () { return binary_protocol_1.PROTOCOL_VERSION_V3; } });
+Object.defineProperty(exports, "readOpcode", { enumerable: true, get: function () { return binary_protocol_1.readOpcode; } });
+Object.defineProperty(exports, "isAppJsonSessionAttachLike", { enumerable: true, get: function () { return binary_protocol_1.isAppJsonSessionAttachLike; } });
+Object.defineProperty(exports, "parseAppJsonSessionAttach", { enumerable: true, get: function () { return binary_protocol_1.parseAppJsonSessionAttach; } });
+Object.defineProperty(exports, "encodeFrameSnapshotPush", { enumerable: true, get: function () { return binary_protocol_1.encodeFrameSnapshotPush; } });
+Object.defineProperty(exports, "encodeProtocolError", { enumerable: true, get: function () { return binary_protocol_1.encodeProtocolError; } });
+Object.defineProperty(exports, "encodeAppJson", { enumerable: true, get: function () { return binary_protocol_1.encodeAppJson; } });
+Object.defineProperty(exports, "encodeResize", { enumerable: true, get: function () { return binary_protocol_1.encodeResize; } });
+var messages_1 = require("./messages");
+Object.defineProperty(exports, "isAppJsonMessage", { enumerable: true, get: function () { return messages_1.isAppJsonMessage; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,qDAW2B;AAVzB,yGAAA,MAAM,OAAA;AACN,wHAAA,qBAAqB,OAAA;AACrB,sHAAA,mBAAmB,OAAA;AACnB,6GAAA,UAAU,OAAA;AACV,6HAAA,0BAA0B,OAAA;AAC1B,4HAAA,yBAAyB,OAAA;AACzB,0HAAA,uBAAuB,OAAA;AACvB,sHAAA,mBAAmB,OAAA;AACnB,gHAAA,aAAa,OAAA;AACb,+GAAA,YAAY,OAAA;AAgCd,uCAA8C;AAArC,4GAAA,gBAAgB,OAAA"}

package/dist/messages.d.ts

@@ -0,0 +1,158 @@
+/**
+ * APP_JSON (opcode 0x01) 의 payload 타입 정의.
+ *
+ * 본 파일은 wire spec 의 `type` discriminator 기반 sum type 을 TypeScript 로 표현한다.
+ * 비-TS 클라이언트(Dart/Rust/Python)는 spec 문서와 fixture 만 보고 동일 메시지를 구현하면 된다.
+ *
+ * 변경 시 spec 문서 `binary-protocol-v3.md` 와 3 repo (mobile / relay / desktop) 의 구현을
+ * 동시에 갱신해야 한다. fixture (`fixtures/binary-protocol-v3.fixtures.json`) 의 round-trip
+ * 테스트가 호환을 영구 검증.
+ */
+/** PTY 운영 상태 — `pty_status` 메시지의 `status` 필드. */
+export type PtyStatus = 'idle' | 'running' | 'dead' | 'oom';
+/** Claude Code 실행 상태 — host 의 PTY 패턴 매칭 결과. */
+export type ClaudeState = 'idle' | 'working' | 'awaiting-approval';
+/** A3 capability negotiation 의 client 후보. */
+export type ClientCapability = 'grid.diff' | 'pty.data';
+/** Snapshot 요청 사유 — `snapshot.req` 메시지의 `reason` 필드. */
+export type SnapshotReqReason = 'recover' | 'reattach' | 'manual';
+/** PTY 사이즈 권위 모드 — host 가 mobile 의 RESIZE 를 어떻게 다룰지 결정. */
+export type PtyAuthorityMode = 'desktop-priority' | 'mobile-priority';
+/** Machine (SSH host) — host 가 관리하는 원격 노드 메타데이터. */
+export interface Machine {
+    id: string;
+    name: string;
+    /** 'connected' | 'disconnected' | 'connecting' | ... — host 가 자유 형식. */
+    status: string;
+    host?: string;
+    username?: string;
+    port?: number;
+    errorMessage?: string;
+    ptyAuthority?: PtyAuthorityMode;
+}
+/** 첫 frame — client 가 server (relay/host) 에 protocol version 통보. */
+export interface MsgHello {
+    type: 'hello';
+    protocolVersion: number;
+    clientId?: string;
+}
+/** hello 응답 — server 의 version 회신. */
+export interface MsgHelloAck {
+    type: 'hello_ack';
+    serverVersion: number;
+}
+/** Capability 협상 요청 — client → host. */
+export interface MsgCapReq {
+    type: 'cap.req';
+    client_caps: ClientCapability[];
+    client_ver: number;
+}
+/** Capability 협상 응답 — host → client. */
+export interface MsgCapAck {
+    type: 'cap.ack';
+    selected: ClientCapability | string;
+    server_ver: number;
+    max_cols: number;
+    max_rows: number;
+}
+/** Snapshot 재요청 — client (grid.diff path) → host. */
+export interface MsgSnapshotReq {
+    type: 'snapshot.req';
+    reason: SnapshotReqReason;
+    last_seq: number;
+}
+/** host 의 machine 목록 push. */
+export interface MsgMachineList {
+    type: 'machine_list';
+    machines: Machine[];
+}
+/** mobile 이 특정 machine 의 세션을 attach 요청 / host 가 ack. */
+export interface MsgSessionAttach {
+    type: 'session_attach';
+    machineId: string;
+}
+/** machine 의 연결 상태 변화 push. */
+export interface MsgConnectionStatus {
+    type: 'connection_status';
+    machineId: string;
+    status: string;
+}
+/** legacy(v2) 호환 path — PTY raw text 를 JSON 으로 wrap. v3 에서는 PTY_DATA opcode 권장. */
+export interface MsgTerminalData {
+    type: 'terminal_data';
+    machineId: string;
+    data: string;
+}
+/** Claude 실행 상태 변화. */
+export interface MsgClaudeState {
+    type: 'claude_state';
+    machineId: string;
+    state: ClaudeState;
+}
+/** PTY 운영 상태 변화. */
+export interface MsgPtyStatus {
+    type: 'pty_status';
+    machineId: string;
+    status: PtyStatus;
+    pid?: number;
+}
+/** Git 명령 결과 push. */
+export interface MsgGitResult {
+    type: 'git_result';
+    machineId: string;
+    action: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+}
+/**
+ * Session replay — host 가 ring buffer 의 청크를 모바일에 송신.
+ * `totalChunks` 회 만큼 `chunkIndex` 가 증가하며 도착.
+ */
+export interface MsgSessionReplay {
+    type: 'session_replay';
+    machineId: string;
+    chunkIndex: number;
+    totalChunks: number;
+    data: string;
+}
+/** server-side RESIZE cap (500×200) 적용 통보. */
+export interface MsgGridResizeCapped {
+    type: 'grid_resize_capped';
+    actual_cols: number;
+    actual_rows: number;
+}
+/** Protocol version mismatch — server 가 client 에게 통보 (binary 0xFF 와 별도 호환 경로). */
+export interface MsgProtocolMismatch {
+    type: 'protocol_mismatch';
+    clientVersion: number;
+    serverVersion: number;
+    minimumRequired: number;
+}
+/** Heartbeat — server initiated. */
+export interface MsgPing {
+    type: 'ping';
+}
+/** Heartbeat 응답 — client → server. */
+export interface MsgPong {
+    type: 'pong';
+    timestamp: number;
+}
+/** generic application error. */
+export interface MsgError {
+    type: 'error';
+    message: string;
+}
+/** mobile → host: keyboard / paste / Y-N 등 raw 텍스트 입력. */
+export interface MsgInput {
+    type: 'input';
+    machineId?: string;
+    data: string;
+}
+/** discriminated union — APP_JSON payload 의 모든 정식 타입. */
+export type AppJsonMessage = MsgHello | MsgHelloAck | MsgCapReq | MsgCapAck | MsgSnapshotReq | MsgMachineList | MsgSessionAttach | MsgConnectionStatus | MsgTerminalData | MsgClaudeState | MsgPtyStatus | MsgGitResult | MsgSessionReplay | MsgGridResizeCapped | MsgProtocolMismatch | MsgPing | MsgPong | MsgError | MsgInput;
+/** type discriminator 로 좁히는 helper. */
+export declare function isAppJsonMessage<T extends AppJsonMessage['type']>(msg: unknown, type: T): msg is Extract<AppJsonMessage, {
+    type: T;
+}>;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"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"}

package/dist/messages.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * APP_JSON (opcode 0x01) 의 payload 타입 정의.
+ *
+ * 본 파일은 wire spec 의 `type` discriminator 기반 sum type 을 TypeScript 로 표현한다.
+ * 비-TS 클라이언트(Dart/Rust/Python)는 spec 문서와 fixture 만 보고 동일 메시지를 구현하면 된다.
+ *
+ * 변경 시 spec 문서 `binary-protocol-v3.md` 와 3 repo (mobile / relay / desktop) 의 구현을
+ * 동시에 갱신해야 한다. fixture (`fixtures/binary-protocol-v3.fixtures.json`) 의 round-trip
+ * 테스트가 호환을 영구 검증.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAppJsonMessage = isAppJsonMessage;
+/** type discriminator 로 좁히는 helper. */
+function isAppJsonMessage(msg, type) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        msg.type === type);
+}
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAiMH,4CASC;AAVD,uCAAuC;AACvC,SAAgB,gBAAgB,CAC9B,GAAY,EACZ,IAAO;IAEP,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACX,GAA0B,CAAC,IAAI,KAAK,IAAI,CAC1C,CAAC;AACJ,CAAC"}

package/fixtures/binary-protocol-v3.fixtures.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "binary-protocol-v3 contract test fixtures",
+  "version": 3,
+  "description": "3 repo cross-validation fixture set. mobile (Dart) / relay (TypeScript) / desktop (TypeScript) 의 spec 가 본 fixture 를 parse 한 결과가 일치해야 함. wireHex 의 공백/대소문자는 무시 — parse 시 hex pair 로만 해석.",
+  "fixtures": [
+    {
+      "name": "PTY_DATA — hello newline",
+      "opcode": 0,
+      "wireHex": "00 68 65 6C 6C 6F 0A",
+      "expected": {
+        "type": "pty_data",
+        "textUtf8": "hello\n"
+      }
+    },
+    {
+      "name": "PTY_DATA — empty payload (PTY 가 0 byte forward — edge)",
+      "opcode": 0,
+      "wireHex": "00",
+      "expected": {
+        "type": "pty_data",
+        "textUtf8": ""
+      }
+    },
+    {
+      "name": "PTY_DATA — 한국어 (UTF-8 multi-byte)",
+      "opcode": 0,
+      "wireHex": "00 EC 95 88 EB 85 95",
+      "expected": {
+        "type": "pty_data",
+        "textUtf8": "안녕"
+      }
+    },
+    {
+      "name": "APP_JSON — hello (mobile → relay 첫 frame)",
+      "opcode": 1,
+      "wireHex": "01 7B 22 74 79 70 65 22 3A 22 68 65 6C 6C 6F 22 2C 22 70 72 6F 74 6F 63 6F 6C 56 65 72 73 69 6F 6E 22 3A 33 7D",
+      "expected": {
+        "type": "app_json",
+        "json": { "type": "hello", "protocolVersion": 3 }
+      }
+    },
+    {
+      "name": "APP_JSON — hello_ack (server → mobile 응답)",
+      "opcode": 1,
+      "wireHex": "01 7B 22 74 79 70 65 22 3A 22 68 65 6C 6C 6F 5F 61 63 6B 22 2C 22 73 65 72 76 65 72 56 65 72 73 69 6F 6E 22 3A 33 7D",
+      "expected": {
+        "type": "app_json",
+        "json": { "type": "hello_ack", "serverVersion": 3 }
+      }
+    },
+    {
+      "name": "RESIZE — 80x24 (RFC 4254 default)",
+      "opcode": 2,
+      "wireHex": "02 00 00 00 50 00 00 00 18",
+      "expected": {
+        "type": "resize",
+        "cols": 80,
+        "rows": 24
+      }
+    },
+    {
+      "name": "RESIZE — 200x60 (큰 viewport)",
+      "opcode": 2,
+      "wireHex": "02 00 00 00 C8 00 00 00 3C",
+      "expected": {
+        "type": "resize",
+        "cols": 200,
+        "rows": 60
+      }
+    },
+    {
+      "name": "FRAME_SNAPSHOT — machineId=m1, ANSI=ESC[H",
+      "opcode": 3,
+      "wireHex": "03 00 00 00 02 6D 31 00 00 00 03 1B 5B 48",
+      "expected": {
+        "type": "frame_snapshot",
+        "machineId": "m1",
+        "ansiUtf8": "[H"
+      }
+    },
+    {
+      "name": "FRAME_SNAPSHOT — empty ANSI (alt-screen exit)",
+      "opcode": 3,
+      "wireHex": "03 00 00 00 02 6D 31 00 00 00 00",
+      "expected": {
+        "type": "frame_snapshot",
+        "machineId": "m1",
+        "ansiUtf8": ""
+      }
+    },
+    {
+      "name": "PROTOCOL_ERROR — version_mismatch (0x03)",
+      "opcode": 255,
+      "wireHex": "FF 03",
+      "expected": {
+        "type": "protocol_error",
+        "reason": 3,
+        "reasonName": "version_mismatch"
+      }
+    },
+    {
+      "name": "PROTOCOL_ERROR — unknown_opcode (0x01)",
+      "opcode": 255,
+      "wireHex": "FF 01",
+      "expected": {
+        "type": "protocol_error",
+        "reason": 1,
+        "reasonName": "unknown_opcode"
+      }
+    },
+    {
+      "name": "APP_JSON — cap.req (A3 capability negotiation, client → agent)",
+      "opcode": 1,
+      "wireHex": "01 7b 22 74 79 70 65 22 3a 22 63 61 70 2e 72 65 71 22 2c 22 63 6c 69 65 6e 74 5f 63 61 70 73 22 3a 5b 22 67 72 69 64 2e 64 69 66 66 22 2c 22 70 74 79 2e 64 61 74 61 22 5d 2c 22 63 6c 69 65 6e 74 5f 76 65 72 22 3a 33 7d",
+      "expected": {
+        "type": "app_json",
+        "json": { "type": "cap.req", "client_caps": ["grid.diff", "pty.data"], "client_ver": 3 }
+      }
+    },
+    {
+      "name": "APP_JSON — cap.ack (A3 capability negotiation, agent → client, selected=grid.diff)",
+      "opcode": 1,
+      "wireHex": "01 7b 22 74 79 70 65 22 3a 22 63 61 70 2e 61 63 6b 22 2c 22 73 65 6c 65 63 74 65 64 22 3a 22 67 72 69 64 2e 64 69 66 66 22 2c 22 73 65 72 76 65 72 5f 76 65 72 22 3a 33 2c 22 6d 61 78 5f 63 6f 6c 73 22 3a 35 30 30 2c 22 6d 61 78 5f 72 6f 77 73 22 3a 32 30 30 7d",
+      "expected": {
+        "type": "app_json",
+        "json": { "type": "cap.ack", "selected": "grid.diff", "server_ver": 3, "max_cols": 500, "max_rows": 200 }
+      }
+    },
+    {
+      "name": "APP_JSON — snapshot.req (manual reason, last_seq=42)",
+      "opcode": 1,
+      "wireHex": "01 7b 22 74 79 70 65 22 3a 22 73 6e 61 70 73 68 6f 74 2e 72 65 71 22 2c 22 72 65 61 73 6f 6e 22 3a 22 6d 61 6e 75 61 6c 22 2c 22 6c 61 73 74 5f 73 65 71 22 3a 34 32 7d",
+      "expected": {
+        "type": "app_json",
+        "json": { "type": "snapshot.req", "reason": "manual", "last_seq": 42 }
+      }
+    },
+    {
+      "name": "GRID_SNAPSHOT — minimal 1x2 grid, cells='ab' palette mode, cursor (0,2)",
+      "opcode": 4,
+      "wireHex": "04 00 00 00 01 00 02 00 01 61 07 00 00 62 07 00 00 00 00 00 02",
+      "expected": {
+        "type": "grid_snapshot",
+        "seq": 1,
+        "cols": 2,
+        "rows": 1,
+        "cellsBytes": 8,
+        "cursorR": 0,
+        "cursorC": 2,
+        "decodedCells": [
+          { "ch": "a", "fg": 7, "bg": 0, "attrs": 0 },
+          { "ch": "b", "fg": 7, "bg": 0, "attrs": 0 }
+        ]
+      }
+    },
+    {
+      "name": "GRID_DIFF — 1 op (r=0,c=0,ch=X,fg=1 red,bg=0,attrs=bold)",
+      "opcode": 5,
+      "wireHex": "05 00 00 00 02 00 00 00 01 00 01 00 00 00 00 58 01 00 01",
+      "expected": {
+        "type": "grid_diff",
+        "seq": 2,
+        "baseSeq": 1,
+        "opCount": 1,
+        "ops": [
+          { "r": 0, "c": 0, "ch": "X", "fg": 1, "bg": 0, "attrs": 1 }
+        ]
+      }
+    }
+  ],
+  "malformed": [
+    {
+      "name": "RESIZE — payload 길이 8 미만 (malformed)",
+      "wireHex": "02 00 00 00 50",
+      "expected": {
+        "type": "parse_error",
+        "shouldEmit": "PROTOCOL_ERROR(0x02 malformed_payload)"
+      }
+    },
+    {
+      "name": "FRAME_SNAPSHOT — machineId len 헤더 부족",
+      "wireHex": "03 00 00",
+      "expected": {
+        "type": "parse_error",
+        "shouldEmit": "PROTOCOL_ERROR(0x02 malformed_payload)"
+      }
+    },
+    {
+      "name": "FRAME_SNAPSHOT — declared len 이 buffer 초과",
+      "wireHex": "03 00 00 00 FF 6D 31",
+      "expected": {
+        "type": "parse_error",
+        "shouldEmit": "PROTOCOL_ERROR(0x02 malformed_payload)"
+      }
+    },
+    {
+      "name": "Unknown opcode (0x10 — reserved 영역)",
+      "wireHex": "10 DE AD BE EF",
+      "expected": {
+        "type": "parse_error",
+        "shouldEmit": "PROTOCOL_ERROR(0x01 unknown_opcode)"
+      }
+    },
+    {
+      "name": "Empty frame (0 byte)",
+      "wireHex": "",
+      "expected": {
+        "type": "parse_error",
+        "shouldEmit": "PROTOCOL_ERROR(0x02 malformed_payload)"
+      }
+    },
+    {
+      "name": "GRID_SNAPSHOT — header < 11 bytes (cursor 영역 없음)",
+      "wireHex": "04 00 00 00 01 00 02 00 01",
+      "expected": {
+        "type": "parse_error",
+        "shouldEmit": "PROTOCOL_ERROR(0x02 malformed_payload)"
+      }
+    },
+    {
+      "name": "GRID_DIFF — header < 11 bytes (opCount/ops 영역 없음)",
+      "wireHex": "05 00 00 00 02 00 00",
+      "expected": {
+        "type": "parse_error",
+        "shouldEmit": "PROTOCOL_ERROR(0x02 malformed_payload)"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "vibe-remote-protocol",
+  "version": "1.0.0",
+  "description": "VibeRemote binary WebSocket protocol v3 — opcode constants, encoders/decoders, and TypeScript message types shared by relay, desktop agent, and mobile clients.",
+  "license": "MIT",
+  "author": "jun-young1993",
+  "homepage": "https://github.com/june-glre/vibe-remote-protocol",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/june-glre/vibe-remote-protocol.git"
+  },
+  "keywords": [
+    "vibe-remote",
+    "websocket",
+    "protocol",
+    "binary",
+    "terminal",
+    "pty",
+    "relay"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "fixtures",
+    "README.md",
+    "README_KR.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "jest",
+    "lint": "tsc --noEmit",
+    "clean": "rimraf dist"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.2",
+    "@types/node": "^20.3.1",
+    "jest": "^29.5.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.1.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+
+}