@kangentic/protocol 0.2.0 → 0.5.0

package/dist/version.d.ts

@@ -8,5 +8,5 @@
  * differing prologue produces a differing transcript hash `h` from the
  * first MixHash call, which cascades into every derived key.
  */
-export declare const PROTOCOL_VERSION = "1";
+export declare const PROTOCOL_VERSION = "2";
 export declare function encodeProtocolVersion(version?: string): Uint8Array;

package/dist/wire/framing.d.ts

@@ -1,4 +1,8 @@
 import type { BridgeMessage } from './messages';
 export declare const MAX_FRAME_LENGTH: number;
+/** Upper bound on the JSON a compressed frame may declare/inflate to. */
+export declare const MAX_DECODED_LENGTH: number;
+/** JSON below this size ships raw - deflate overhead is not worth it. */
+export declare const COMPRESSION_THRESHOLD: number;
 export declare function encodeMessage(message: BridgeMessage): Uint8Array;
 export declare function decodeMessage(bytes: Uint8Array): BridgeMessage;

package/dist/wire/payloads.d.ts

@@ -15,11 +15,29 @@
  */
 import type { CapabilityVerb } from '../capabilities/verbs';
 import type { JsonValue } from './messages';
-import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type DiffFileContentWire, type DiffFileListWire, type SessionUsageWire } from '../events/payloads';
+import { type ActivityReasonWire, type ActivityStateWire, type BacklogItemWire, type BoardColumnWire, type BoardTaskWire, type DiffFileContentWire, type DiffFileListWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEntryWire } from '../events/payloads';
 export interface ReadStreamRequestPayload {
     sessionId: string;
-    action: 'subscribe' | 'unsubscribe';
+    /**
+     * 'transcript-window' is a one-shot windowed-history read: the newest
+     * `limit` transcript entries strictly before `beforeIndex` (or the tail
+     * when `beforeIndex` is omitted). The desktop may return fewer entries
+     * than `limit` to keep the response frame small - page again from the
+     * returned `startIndex`. Live updates after 'subscribe' arrive as
+     * incremental TranscriptEvent deltas, never full transcripts.
+     */
+    action: 'subscribe' | 'unsubscribe' | 'transcript-window';
+    /** transcript-window only: fetch entries strictly before this absolute index. Omit for the newest window. */
+    beforeIndex?: number;
+    /** transcript-window only: maximum entries wanted (the desktop may cap this and may return fewer). */
+    limit?: number;
 }
+/**
+ * Mirrors the desktop's SessionStatus. 'suspended' is a registered-but-
+ * parked session (resumable placeholder); 'exited' can appear when a
+ * snapshot races the session's teardown.
+ */
+export type ReadStreamSessionStatusWire = 'running' | 'queued' | 'suspended' | 'exited';
 /** Initial snapshot returned on subscribe; live updates arrive as TerminalEvent/ActivityEvent/TranscriptEvent. */
 export interface ReadStreamResponsePayload {
     scrollback: string;
@@ -30,9 +48,33 @@ export interface ReadStreamResponsePayload {
     usage: SessionUsageWire | null;
     /** The live outstanding permission-prompt id (see answer-permission-prompt), or null when none is pending. */
     awaitedPromptId: string | null;
+    /**
+     * The PTY grid the scrollback bytes are laid out for. Absent from
+     * pre-0.4.0 desktops; the phone then falls back to inferring a width
+     * from the scrollback content.
+     */
+    ptyDimensions?: TerminalDimensionsWire;
+    /**
+     * The session's lifecycle status at snapshot time. Absent from
+     * pre-0.5.0 desktops; the phone then assumes 'running'.
+     */
+    sessionStatus?: ReadStreamSessionStatusWire;
 }
 /** Phone-side narrowing of a read-stream subscribe response. Throws on a malformed required field. */
 export declare function parseReadStreamResponsePayload(payload: JsonValue): ReadStreamResponsePayload;
+/**
+ * A contiguous slice of the transcript, returned by the read-stream
+ * 'transcript-window' action. `startIndex` is the absolute index of
+ * `entries[0]`; `startIndex > 0` means more history exists above.
+ */
+export interface TranscriptWindowResponsePayload {
+    revision: number;
+    totalEntries: number;
+    startIndex: number;
+    entries: TranscriptEntryWire[];
+}
+/** Phone-side narrowing of a transcript-window response. Throws on a malformed required field. */
+export declare function parseTranscriptWindowResponsePayload(payload: JsonValue): TranscriptWindowResponsePayload;
 export interface ReadBoardRequestPayload {
     projectId?: string;
     /** Defaults to 'subscribe' when omitted. 'unsubscribe' only has an effect when projectId is set - the no-projectId project list is a one-shot read with no live feed to tear down. */
@@ -41,6 +83,13 @@ export interface ReadBoardRequestPayload {
 export interface ReadBoardProjectSummary {
     id: string;
     name: string;
+    /**
+     * Accent color for this project ("#rrggbb"). Today the desktop derives
+     * it deterministically from the project id; a user-set project color
+     * can later override it through this same field. Absent from pre-0.5.0
+     * desktops.
+     */
+    color?: string;
 }
 /** Returned when the request omits projectId - the phone's project-bootstrap listing. */
 export interface ReadBoardProjectListResponsePayload {
@@ -52,6 +101,8 @@ export interface ReadBoardSnapshotResponsePayload {
     columns: BoardColumnWire[];
     tasks: BoardTaskWire[];
     backlog: BacklogItemWire[];
+    /** The project's accent color ("#rrggbb"); same semantics as ReadBoardProjectSummary.color. Absent from pre-0.5.0 desktops. */
+    projectColor?: string;
 }
 export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload;
 /** Phone-side narrowing of a read-board response (project list or board snapshot). Throws on a malformed required field. */
@@ -95,13 +146,38 @@ export interface AnswerPermissionPromptRequestPayload {
 export interface AnswerPermissionPromptResponsePayload {
     answered: boolean;
 }
-export interface InteractiveTerminalRequestPayload {
+/**
+ * Three actions ride the one interactive-terminal grant: a device trusted
+ * to type raw bytes into the PTY is equally trusted to resize it, so
+ * resize adds no new capability surface.
+ *
+ * - write (the default when `action` is omitted, which is what every
+ *   pre-0.4.0 phone sends): raw bytes into the PTY.
+ * - resize: set the PTY grid so the TUI redraws phone-shaped. The desktop
+ *   remembers its own last dimensions and restores them when the phone
+ *   releases (explicitly, or implicitly on disconnect/revoke).
+ * - release-size: give the grid back to the desktop now.
+ */
+export type InteractiveTerminalRequestPayload = {
     sessionId: string;
+    action?: 'write';
     data: string;
-}
-export interface InteractiveTerminalResponsePayload {
+} | {
+    sessionId: string;
+    action: 'resize';
+    dimensions: TerminalDimensionsWire;
+} | {
+    sessionId: string;
+    action: 'release-size';
+};
+export type InteractiveTerminalResponsePayload = {
     written: boolean;
-}
+} | {
+    resized: boolean;
+    colsChanged: boolean;
+} | {
+    released: boolean;
+};
 export interface BoardToolRequestPayload {
     tool: string;
     params: JsonValue;
@@ -109,6 +185,24 @@ export interface BoardToolRequestPayload {
 export interface BoardToolResponsePayload {
     result: JsonValue;
 }
+/**
+ * Registers (or unregisters) this device for E2E-encrypted push
+ * notifications. 'register' carries the device's Expo push token plus a
+ * device-generated 32-byte push key (base64url) the desktop seals every
+ * notification envelope with (see crypto/push-envelope.ts); 'unregister'
+ * carries neither. The desktop keys the registration by the requesting
+ * device's roster identity, never by anything in this payload.
+ */
+export interface RegisterPushRequestPayload {
+    action: 'register' | 'unregister';
+    expoPushToken?: string;
+    pushKeyBase64?: string;
+    platform?: 'android' | 'ios';
+}
+export interface RegisterPushResponsePayload {
+    registered: boolean;
+}
+export declare function parseRegisterPushRequestPayload(payload: JsonValue): RegisterPushRequestPayload;
 export interface CapabilityRequestPayloadMap {
     'read-stream': ReadStreamRequestPayload;
     'read-board': ReadBoardRequestPayload;
@@ -119,9 +213,10 @@ export interface CapabilityRequestPayloadMap {
     'interactive-terminal': InteractiveTerminalRequestPayload;
     'board-tool-read': BoardToolRequestPayload;
     'board-tool-write': BoardToolRequestPayload;
+    'register-push': RegisterPushRequestPayload;
 }
 export interface CapabilityResponsePayloadMap {
-    'read-stream': ReadStreamResponsePayload;
+    'read-stream': ReadStreamResponsePayload | TranscriptWindowResponsePayload;
     'read-board': ReadBoardResponsePayload;
     'read-diff': ReadDiffResponsePayload;
     'send-user-message': SendUserMessageResponsePayload;
@@ -130,6 +225,7 @@ export interface CapabilityResponsePayloadMap {
     'interactive-terminal': InteractiveTerminalResponsePayload;
     'board-tool-read': BoardToolResponsePayload;
     'board-tool-write': BoardToolResponsePayload;
+    'register-push': RegisterPushResponsePayload;
 }
 /**
  * Validates and narrows a decoded capability-request's generic JsonValue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Kangentic mobile bridge wire protocol: framing, Noise-based pairing and session handshakes, signed device roster, and capability verbs shared between desktop and mobile.",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -42,7 +42,8 @@
   "dependencies": {
     "@noble/ciphers": "^2.2.0",
     "@noble/curves": "^2.2.0",
-    "@noble/hashes": "^2.2.0"
+    "@noble/hashes": "^2.2.0",
+    "fflate": "^0.8.3"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",