@kangentic/protocol 0.1.1 → 0.3.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/json-value.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The single `isJsonValue` runtime check, shared by framing.ts (validating a
+ * whole decoded BridgeMessage) and payloads.ts (validating one verb's
+ * request payload before a handler trusts it). Split out so neither module
+ * has to re-derive the other's copy.
+ */
+import type { JsonValue } from './messages';
+export declare function isJsonValue(value: unknown): value is JsonValue;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/wire/payloads.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Concrete per-verb request/response payload shapes. `CapabilityRequestMessage.payload`
+ * and `CapabilityResponseMessage.payload` stay `JsonValue` on the envelope
+ * (messages.ts) - these interfaces narrow that generic value at the handler
+ * boundary, and the `parse*RequestPayload` guards below are the runtime
+ * checks a handler runs against an untrusted phone-originated request before
+ * trusting any field.
+ *
+ * Fields that mirror an app-internal shape the protocol package cannot
+ * import (git diff results, board rows, an MCP tool's result) stay
+ * `JsonValue`, same rationale as messages.ts/events/event.ts: this package
+ * is a dependency-light leaf shared by desktop and phone, so it does not
+ * know the desktop app's internal types. Only the fixed envelope fields
+ * (ids, actions, booleans) are concretely typed and runtime-validated here.
+ */
+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, type TranscriptEntryWire } from '../events/payloads';
+export interface ReadStreamRequestPayload {
+    sessionId: string;
+    /**
+     * '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;
+}
+/** Initial snapshot returned on subscribe; live updates arrive as TerminalEvent/ActivityEvent/TranscriptEvent. */
+export interface ReadStreamResponsePayload {
+    scrollback: string;
+    activity: {
+        state: ActivityStateWire | null;
+        reason: ActivityReasonWire | null;
+    };
+    usage: SessionUsageWire | null;
+    /** The live outstanding permission-prompt id (see answer-permission-prompt), or null when none is pending. */
+    awaitedPromptId: string | null;
+}
+/** 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. */
+    action?: 'subscribe' | 'unsubscribe';
+}
+export interface ReadBoardProjectSummary {
+    id: string;
+    name: string;
+}
+/** Returned when the request omits projectId - the phone's project-bootstrap listing. */
+export interface ReadBoardProjectListResponsePayload {
+    projects: ReadBoardProjectSummary[];
+}
+/** Returned when the request carries a projectId - a snapshot of that project's board. */
+export interface ReadBoardSnapshotResponsePayload {
+    projectId: string;
+    columns: BoardColumnWire[];
+    tasks: BoardTaskWire[];
+    backlog: BacklogItemWire[];
+}
+export type ReadBoardResponsePayload = ReadBoardProjectListResponsePayload | ReadBoardSnapshotResponsePayload;
+/** Phone-side narrowing of a read-board response (project list or board snapshot). Throws on a malformed required field. */
+export declare function parseReadBoardResponsePayload(payload: JsonValue): ReadBoardResponsePayload;
+/** Mirrors DiffService's GitDiffScope in the desktop app; kept as a literal union here rather than an import, since the protocol package does not depend on the app. */
+export type ReadDiffScope = 'working' | 'staged' | 'branch';
+export interface ReadDiffRequestPayload {
+    taskId: string;
+    projectId: string;
+    filePath?: string;
+    scope?: ReadDiffScope;
+    /** Defaults to 'subscribe' when omitted. Only the file-list watch (no filePath) has a live feed to tear down; a single-file content fetch is always one-shot. */
+    action?: 'subscribe' | 'unsubscribe';
+}
+/** The desktop's GitDiffFilesResult mirror (no filePath) or GitFileContentResult mirror (filePath set). */
+export type ReadDiffResponsePayload = DiffFileListWire | DiffFileContentWire;
+/** Phone-side narrowing of a read-diff response, discriminated by the presence of "files". Throws on a malformed required field. */
+export declare function parseReadDiffResponsePayload(payload: JsonValue): ReadDiffResponsePayload;
+export interface SendUserMessageRequestPayload {
+    sessionId: string;
+    text: string;
+}
+export interface SendUserMessageResponsePayload {
+    delivered: boolean;
+}
+export interface MoveTaskRequestPayload {
+    taskId: string;
+    targetSwimlaneId: string;
+    targetPosition: number;
+    projectId: string;
+}
+export interface MoveTaskResponsePayload {
+    ok: boolean;
+}
+export interface AnswerPermissionPromptRequestPayload {
+    sessionId: string;
+    /** The prompt id the phone believes is outstanding - the handler rejects a stale/replayed answer whose id no longer matches the live awaited prompt. */
+    promptId: string;
+    keystrokes: string;
+}
+export interface AnswerPermissionPromptResponsePayload {
+    answered: boolean;
+}
+export interface InteractiveTerminalRequestPayload {
+    sessionId: string;
+    data: string;
+}
+export interface InteractiveTerminalResponsePayload {
+    written: boolean;
+}
+export interface BoardToolRequestPayload {
+    tool: string;
+    params: JsonValue;
+}
+export interface BoardToolResponsePayload {
+    result: JsonValue;
+}
+export interface CapabilityRequestPayloadMap {
+    'read-stream': ReadStreamRequestPayload;
+    'read-board': ReadBoardRequestPayload;
+    'read-diff': ReadDiffRequestPayload;
+    'send-user-message': SendUserMessageRequestPayload;
+    'move-task': MoveTaskRequestPayload;
+    'answer-permission-prompt': AnswerPermissionPromptRequestPayload;
+    'interactive-terminal': InteractiveTerminalRequestPayload;
+    'board-tool-read': BoardToolRequestPayload;
+    'board-tool-write': BoardToolRequestPayload;
+}
+export interface CapabilityResponsePayloadMap {
+    'read-stream': ReadStreamResponsePayload | TranscriptWindowResponsePayload;
+    'read-board': ReadBoardResponsePayload;
+    'read-diff': ReadDiffResponsePayload;
+    'send-user-message': SendUserMessageResponsePayload;
+    'move-task': MoveTaskResponsePayload;
+    'answer-permission-prompt': AnswerPermissionPromptResponsePayload;
+    'interactive-terminal': InteractiveTerminalResponsePayload;
+    'board-tool-read': BoardToolResponsePayload;
+    'board-tool-write': BoardToolResponsePayload;
+}
+/**
+ * Validates and narrows a decoded capability-request's generic JsonValue
+ * payload into its verb-specific shape. This is the runtime trust boundary:
+ * every field the phone supplies is checked before a handler reads it.
+ */
+export declare function parseCapabilityRequestPayload<Verb extends CapabilityVerb>(verb: Verb, payload: JsonValue): CapabilityRequestPayloadMap[Verb];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kangentic/protocol",
-  "version": "0.1.1",
+  "version": "0.3.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",