@kangentic/protocol 0.18.0 → 0.19.0

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   PUSH_CATEGORIES: () => PUSH_CATEGORIES,
   PUSH_ENVELOPE_MAX_AGE_MS: () => PUSH_ENVELOPE_MAX_AGE_MS,
   PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS: () => PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
+  RESPONSE_TOO_LARGE_ERROR_CODE: () => RESPONSE_TOO_LARGE_ERROR_CODE,
   SecretstreamState: () => SecretstreamState,
   SessionFrameKind: () => SessionFrameKind,
   UNSUPPORTED_VERB_ERROR_CODE: () => UNSUPPORTED_VERB_ERROR_CODE,
@@ -58,6 +59,7 @@ __export(index_exports, {
   deriveSessionSlotId: () => deriveSessionSlotId,
   deriveShortAuthenticationString: () => deriveShortAuthenticationString,
   encodeMessage: () => encodeMessage,
+  encodeMessageFailure: () => encodeMessageFailure,
   encodePairingQrPayload: () => encodePairingQrPayload,
   encodeProtocolVersion: () => encodeProtocolVersion,
   encodeRosterEntryForSigning: () => encodeRosterEntryForSigning,
@@ -5010,6 +5012,7 @@ var FRAME_FORMAT_DEFLATE = 1;
 var JSON_OPEN_BRACE = 123;
 var DEFLATE_HEADER_LENGTH = 5;
 var UNSUPPORTED_VERB_ERROR_CODE = "unsupported-verb";
+var RESPONSE_TOO_LARGE_ERROR_CODE = "response-too-large";
 var UNSUPPORTED_VERB_ERROR_NAME = "UnsupportedVerbError";
 var UnsupportedVerbError = class extends Error {
   requestId;
@@ -5046,6 +5049,15 @@ function encodeMessage(message) {
   }
   return frame;
 }
+function encodeMessageFailure(message) {
+  try {
+    if (new TextEncoder().encode(JSON.stringify(message)).length <= MAX_FRAME_LENGTH) return null;
+    encodeMessage(message);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
 function decodeMessage(bytes) {
   if (bytes.length > MAX_FRAME_LENGTH) {
     throw new Error(`Bridge message frame exceeds ${MAX_FRAME_LENGTH} bytes`);
@@ -6246,6 +6258,7 @@ function isBridgeEvent(value) {
   PUSH_CATEGORIES,
   PUSH_ENVELOPE_MAX_AGE_MS,
   PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
+  RESPONSE_TOO_LARGE_ERROR_CODE,
   SecretstreamState,
   SessionFrameKind,
   UNSUPPORTED_VERB_ERROR_CODE,
@@ -6265,6 +6278,7 @@ function isBridgeEvent(value) {
   deriveSessionSlotId,
   deriveShortAuthenticationString,
   encodeMessage,
+  encodeMessageFailure,
   encodePairingQrPayload,
   encodeProtocolVersion,
   encodeRosterEntryForSigning,

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { SecretstreamState, deriveSecretstreamPair, FrameTag, type SecretstreamD
 export { deriveShortAuthenticationString, type ShortAuthenticationString } from './crypto/sas';
 export { deriveSessionSlotId, derivePairingSlotId } from './crypto/slot';
 export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessage, CapabilityResponseMessage, CapabilityErrorCode, EventMessage } from './wire/messages';
-export { encodeMessage, decodeMessage, UnsupportedVerbError, isUnsupportedVerbError, UNSUPPORTED_VERB_ERROR_CODE, MAX_FRAME_LENGTH, MAX_DECODED_LENGTH, COMPRESSION_THRESHOLD, } from './wire/framing';
+export { encodeMessage, encodeMessageFailure, decodeMessage, UnsupportedVerbError, isUnsupportedVerbError, UNSUPPORTED_VERB_ERROR_CODE, RESPONSE_TOO_LARGE_ERROR_CODE, MAX_FRAME_LENGTH, MAX_DECODED_LENGTH, COMPRESSION_THRESHOLD, } from './wire/framing';
 export { isJsonValue, isRecord } from './wire/json-value';
 export { SessionFrameKind, wrapSessionFrame, unwrapSessionFrame } from './wire/session-frame';
 export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, parseStartSessionResponsePayload, parsePauseSessionResponsePayload, isReadStreamSessionStatusWire, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardView, type ReadBoardProjectSummary, type ReadBoardProjectGroup, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, type ReadBoardArchivedResponsePayload, type ReadBoardResponsePayload, type ReadDiffScope, type ReadDiffRequestPayload, type ReadDiffResponsePayload, type SendUserMessageRequestPayload, type SendUserMessageResponsePayload, type MoveTaskRequestPayload, type MoveTaskResponsePayload, type AnswerPermissionPromptRequestPayload, type AnswerPermissionPromptResponsePayload, type InteractiveTerminalRequestPayload, type InteractiveTerminalResponsePayload, type BoardToolRequestPayload, type BoardToolResponsePayload, type RegisterPushRequestPayload, type RegisterPushResponsePayload, type StartSessionRequestPayload, type StartSessionResponsePayload, type StartSessionOutcome, type PauseSessionRequestPayload, type PauseSessionResponsePayload, } from './wire/payloads';

package/dist/index.mjs

@@ -4883,6 +4883,7 @@ var FRAME_FORMAT_DEFLATE = 1;
 var JSON_OPEN_BRACE = 123;
 var DEFLATE_HEADER_LENGTH = 5;
 var UNSUPPORTED_VERB_ERROR_CODE = "unsupported-verb";
+var RESPONSE_TOO_LARGE_ERROR_CODE = "response-too-large";
 var UNSUPPORTED_VERB_ERROR_NAME = "UnsupportedVerbError";
 var UnsupportedVerbError = class extends Error {
   requestId;
@@ -4919,6 +4920,15 @@ function encodeMessage(message) {
   }
   return frame;
 }
+function encodeMessageFailure(message) {
+  try {
+    if (new TextEncoder().encode(JSON.stringify(message)).length <= MAX_FRAME_LENGTH) return null;
+    encodeMessage(message);
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
 function decodeMessage(bytes) {
   if (bytes.length > MAX_FRAME_LENGTH) {
     throw new Error(`Bridge message frame exceeds ${MAX_FRAME_LENGTH} bytes`);
@@ -6118,6 +6128,7 @@ export {
   PUSH_CATEGORIES,
   PUSH_ENVELOPE_MAX_AGE_MS,
   PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
+  RESPONSE_TOO_LARGE_ERROR_CODE,
   SecretstreamState,
   SessionFrameKind,
   UNSUPPORTED_VERB_ERROR_CODE,
@@ -6137,6 +6148,7 @@ export {
   deriveSessionSlotId,
   deriveShortAuthenticationString,
   encodeMessage,
+  encodeMessageFailure,
   encodePairingQrPayload,
   encodeProtocolVersion,
   encodeRosterEntryForSigning,

package/dist/wire/framing.d.ts

@@ -6,6 +6,8 @@ export declare const MAX_DECODED_LENGTH: number;
 export declare const COMPRESSION_THRESHOLD: number;
 /** The `code` a desktop puts on its refusal of a verb its build does not know. */
 export declare const UNSUPPORTED_VERB_ERROR_CODE: CapabilityErrorCode;
+/** The `code` a desktop puts on its refusal of a response that would not fit the frame caps above. */
+export declare const RESPONSE_TOO_LARGE_ERROR_CODE: CapabilityErrorCode;
 /**
  * Thrown by `decodeMessage` for a capability-request whose envelope is
  * well-formed (a string `requestId`, a string `verb`, a JSON `payload`) but
@@ -34,4 +36,17 @@ export declare class UnsupportedVerbError extends Error {
  */
 export declare function isUnsupportedVerbError(error: unknown): error is UnsupportedVerbError;
 export declare function encodeMessage(message: BridgeMessage): Uint8Array;
+/**
+ * Why `encodeMessage` would throw for `message`, or null when it would not,
+ * without keeping the frame. A sender with side effects asks this BEFORE
+ * committing them, so it can send something smaller instead of committing to
+ * a message it cannot send (the desktop re-takes a shorter terminal seed).
+ *
+ * Exact, not an estimate. Raw UTF-8 JSON at or under MAX_FRAME_LENGTH always
+ * fits, because `encodeMessage` only switches to deflate when deflate is
+ * smaller, so that common case costs one stringify. A larger message runs the
+ * real encode, deflate included, and a sender that then sends it pays that
+ * encode a second time. Measured terminal seeds are far under the threshold.
+ */
+export declare function encodeMessageFailure(message: BridgeMessage): string | null;
 export declare function decodeMessage(bytes: Uint8Array): BridgeMessage;

package/dist/wire/messages.d.ts

@@ -32,13 +32,21 @@ export interface CapabilityRequestMessage {
 }
 /**
  * A stable key a client can branch on, beside the human-readable `error`.
- * Today the one member is the refusal a desktop sends for a verb its build
- * does not know (see `UnsupportedVerbError` in framing.ts), so a newer phone
- * can tell "desktop is old" from "desktop is unreachable" and show the right
- * copy. A union rather than a bare string so a second code is a deliberate
- * addition here, not a typo at a call site.
+ * A union rather than a bare string so a new code is a deliberate addition
+ * here, not a typo at a call site.
+ *
+ * - `unsupported-verb`: the desktop's build does not know the verb (see
+ *   `UnsupportedVerbError` in framing.ts), so a newer phone can tell "desktop
+ *   is old" from "desktop is unreachable" and show the right copy.
+ * - `response-too-large`: the answer would not fit the frame caps
+ *   (MAX_DECODED_LENGTH before compression, MAX_FRAME_LENGTH after), so the
+ *   desktop refused instead of sending it. The request was valid and its
+ *   target still exists, so a client must not read it as the target being
+ *   gone (a session ending, a project removed). It is a backstop. A desktop
+ *   shrinks a `read-stream` terminal seed to fit rather than refuse it, so a
+ *   phone's terminal subscribe is never answered with this code.
  */
-export type CapabilityErrorCode = 'unsupported-verb';
+export type CapabilityErrorCode = 'unsupported-verb' | 'response-too-large';
 export interface CapabilityResponseMessage {
     type: 'capability-response';
     requestId: string;

package/package.json

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