@kangentic/protocol 0.6.0 → 0.8.0

package/dist/capabilities/board-tools.d.ts

@@ -13,7 +13,7 @@
  * this protocol surface honest: a tool renamed or removed desktop-side
  * fails that test instead of silently breaking phones.
  */
-export declare const BOARD_TOOL_READ_NAMES: readonly ["search_tasks", "find_task", "get_current_task", "get_task_stats", "get_usage_stats", "board_summary", "list_sessions", "get_session_history", "get_column_detail", "get_handoff_context", "get_transcript", "get_session_files", "get_session_events"];
+export declare const BOARD_TOOL_READ_NAMES: readonly ["search_tasks", "find_task", "get_current_task", "get_task_stats", "get_usage_stats", "board_summary", "list_sessions", "get_session_history", "get_column_detail", "get_handoff_context", "get_transcript", "get_session_files", "get_session_events", "get_activity_intervals"];
 export declare const BOARD_TOOL_WRITE_NAMES: readonly ["create_task", "update_task", "delete_task", "link_pr", "remove_attachment", "update_column", "create_backlog_task", "promote_backlog", "update_backlog_item", "delete_backlog_item"];
 export type BoardToolReadName = (typeof BOARD_TOOL_READ_NAMES)[number];
 export type BoardToolWriteName = (typeof BOARD_TOOL_WRITE_NAMES)[number];

package/dist/crypto/push-envelope.d.ts

@@ -1,4 +1,4 @@
-export declare const PUSH_CATEGORIES: readonly ["permission-needed", "agent-question", "turn-complete", "session-failed"];
+export declare const PUSH_CATEGORIES: readonly ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
 export type PushCategory = (typeof PUSH_CATEGORIES)[number];
 export declare function isPushCategory(value: unknown): value is PushCategory;
 /** Reject an opened envelope whose sentAt is older than this (stale replay). */

package/dist/events/event.d.ts

@@ -69,6 +69,24 @@ export type ActivityEventPayload = {
  | {
     type: 'session-ended';
     intentional: boolean;
+}
+/**
+ * The agent's most recent assistant message, already collapsed to a short
+ * plain-text preview, pushed whenever it changes.
+ *
+ * A phone's session list renders exactly one line per session. Deriving it
+ * client-side cost a transcript-window request per session (measured 2.3 to
+ * 34.6 KB each, to keep a string under 200 characters) plus 0.7 to 3.8
+ * seconds of desktop work per request. The desktop already resolves the
+ * transcript to compute its delta pushes, so it can carry the line for
+ * free on a feed the phone is receiving anyway.
+ *
+ * Absent from pre-0.8.0 desktops; a phone that sees none should fall back
+ * to whatever it can derive locally rather than showing nothing.
+ */
+ | {
+    type: 'message-preview';
+    text: string;
 };
 export interface ActivityEvent {
     kind: 'activity';

package/dist/events/payloads.d.ts

@@ -115,11 +115,19 @@ export interface TerminalDimensionsWire {
 }
 /** Mirrors the desktop's ActivityState. 'permission' means the agent paused for user approval (incl. AskUserQuestion / ExitPlanMode pauses). */
 export type ActivityStateWire = 'thinking' | 'idle' | 'permission';
-/** Mirrors the desktop's ActivityReason discriminated union. */
+/**
+ * Mirrors the desktop's ActivityReason discriminated union. `since` (epoch ms
+ * the session first needed the user) is optional, additive-field style like
+ * `toolCallCount`/`effort` above: an older phone parsing a payload with the
+ * field missing still validates, and a desktop that has not yet learned a
+ * `since` for a phantom-state edge case can omit it.
+ */
 export type ActivityReasonWire = {
     kind: 'idle';
+    since?: number;
 } | {
     kind: 'permission';
+    since?: number;
 } | {
     kind: 'tool';
     pendingCount: number;

package/dist/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   KK_PATTERN: () => KK_PATTERN,
   MAX_DECODED_LENGTH: () => MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH: () => MAX_FRAME_LENGTH,
+  MAX_RELAY_ADDRESS_LENGTH: () => MAX_RELAY_ADDRESS_LENGTH,
   PAIRING_URI_SCHEME: () => PAIRING_URI_SCHEME,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
   PUSH_CATEGORIES: () => PUSH_CATEGORIES,
@@ -70,6 +71,7 @@ __export(index_exports, {
   isPushCategory: () => isPushCategory,
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
+  isSecureRelayAddress: () => isSecureRelayAddress,
   openPushEnvelope: () => openPushEnvelope,
   parseActivityEventPayload: () => parseActivityEventPayload,
   parseBacklogItemWire: () => parseBacklogItemWire,
@@ -5186,6 +5188,56 @@ function base64UrlDecode(encoded) {
   return bytes;
 }
 
+// src/crypto/push-envelope.ts
+var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
+function isPushCategory(value) {
+  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
+}
+var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+function requireEnvelopeString(record, field) {
+  const value = record[field];
+  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
+  return value;
+}
+function parsePushEnvelopePlaintext(value) {
+  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
+  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
+  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
+    throw new Error('push envelope plaintext has an invalid "sentAt"');
+  }
+  return {
+    category: value.category,
+    projectId: requireEnvelopeString(value, "projectId"),
+    taskId: requireEnvelopeString(value, "taskId"),
+    sessionId: requireEnvelopeString(value, "sessionId"),
+    taskTitle: requireEnvelopeString(value, "taskTitle"),
+    detail: requireEnvelopeString(value, "detail"),
+    sentAt: value.sentAt
+  };
+}
+function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
+  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
+  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
+  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
+  return base64UrlEncode(concatBytes4(nonce, ciphertext));
+}
+function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
+  const bytes = base64UrlDecode(blob);
+  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
+    throw new Error("push envelope blob is too short");
+  }
+  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
+  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
+  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
+  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
+  const plaintext = parsePushEnvelopePlaintext(decoded);
+  const now = Date.now();
+  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
+  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
+  return plaintext;
+}
+
 // src/events/payloads.ts
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
@@ -5267,6 +5319,7 @@ function isActivityReasonWire(value) {
   switch (value.kind) {
     case "idle":
     case "permission":
+      return value.since === void 0 || typeof value.since === "number";
     case "turn-active":
       return true;
     case "tool":
@@ -5495,6 +5548,10 @@ function parseReadStreamRequestPayload(payload) {
     }
     request.limit = payload.limit;
   }
+  if (payload.terminal !== void 0) {
+    if (typeof payload.terminal !== "boolean") throw new Error('read-stream payload has an invalid "terminal"');
+    request.terminal = payload.terminal;
+  }
   return request;
 }
 var ACCENT_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
@@ -5651,6 +5708,12 @@ function parseRegisterPushRequestPayload(payload) {
     }
     request.platform = payload.platform;
   }
+  if (payload.categories !== void 0) {
+    if (!Array.isArray(payload.categories) || !payload.categories.every((entry) => typeof entry === "string")) {
+      throw new Error('register-push payload has a malformed "categories"');
+    }
+    request.categories = payload.categories.filter(isPushCategory);
+  }
   if (request.action === "register") {
     if (request.expoPushToken === void 0) throw new Error('register-push register payload missing "expoPushToken"');
     if (request.pushKeyBase64 === void 0) throw new Error('register-push register payload missing "pushKeyBase64"');
@@ -5685,61 +5748,22 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
-// src/crypto/push-envelope.ts
-var PUSH_CATEGORIES = ["permission-needed", "agent-question", "turn-complete", "session-failed"];
-function isPushCategory(value) {
-  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
-}
-var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
-var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
-function requireEnvelopeString(record, field) {
-  const value = record[field];
-  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
-  return value;
-}
-function parsePushEnvelopePlaintext(value) {
-  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
-  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
-  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
-    throw new Error('push envelope plaintext has an invalid "sentAt"');
-  }
-  return {
-    category: value.category,
-    projectId: requireEnvelopeString(value, "projectId"),
-    taskId: requireEnvelopeString(value, "taskId"),
-    sessionId: requireEnvelopeString(value, "sessionId"),
-    taskTitle: requireEnvelopeString(value, "taskTitle"),
-    detail: requireEnvelopeString(value, "detail"),
-    sentAt: value.sentAt
-  };
-}
-function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
-  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
-  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
-  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
-  return base64UrlEncode(concatBytes4(nonce, ciphertext));
-}
-function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
-  const bytes = base64UrlDecode(blob);
-  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
-    throw new Error("push envelope blob is too short");
-  }
-  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
-  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
-  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
-  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
-  const plaintext = parsePushEnvelopePlaintext(decoded);
-  const now = Date.now();
-  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
-  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
-  return plaintext;
+// src/pairing/relay-address.ts
+var MAX_RELAY_ADDRESS_LENGTH = 512;
+var LOOPBACK_WS_PREFIXES = ["ws://localhost", "ws://127.0.0.1", "ws://[::1]"];
+function isSecureRelayAddress(relayAddress) {
+  if (relayAddress.startsWith("wss://")) return true;
+  return LOOPBACK_WS_PREFIXES.some((prefix) => {
+    if (!relayAddress.startsWith(prefix)) return false;
+    const boundaryChar = relayAddress.charAt(prefix.length);
+    return boundaryChar === "" || boundaryChar === ":" || boundaryChar === "/" || boundaryChar === "?" || boundaryChar === "#";
+  });
 }
 
 // src/pairing/qr.ts
 var PAIRING_URI_SCHEME = "kangentic-pair";
 var PAYLOAD_VERSION = 1;
 var PAIRING_TOKEN_LENGTH = 32;
-var MAX_RELAY_ADDRESS_LENGTH = 512;
 var MAX_PAYLOAD_LENGTH = 4096;
 function writeUint32(value) {
   const bytes = new Uint8Array(4);
@@ -5870,7 +5894,8 @@ var BOARD_TOOL_READ_NAMES = [
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
-  "get_session_events"
+  "get_session_events",
+  "get_activity_intervals"
 ];
 var BOARD_TOOL_WRITE_NAMES = [
   "create_task",
@@ -5920,6 +5945,10 @@ function parseActivityEventPayload(payload) {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
       return { type: "session-ended", intentional: payload.intentional };
     }
+    case "message-preview": {
+      if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');
+      return { type: "message-preview", text: payload.text };
+    }
     default:
       throw new Error('activity payload has an unknown "type"');
   }
@@ -5986,6 +6015,7 @@ function isBridgeEvent(value) {
   KK_PATTERN,
   MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH,
+  MAX_RELAY_ADDRESS_LENGTH,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
   PUSH_CATEGORIES,
@@ -6024,6 +6054,7 @@ function isBridgeEvent(value) {
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
+  isSecureRelayAddress,
   openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { SessionFrameKind, wrapSessionFrame, unwrapSessionFrame } from './wire/s
 export { parseCapabilityRequestPayload, parseReadStreamResponsePayload, parseReadBoardResponsePayload, parseReadDiffResponsePayload, parseTranscriptWindowResponsePayload, parseRegisterPushRequestPayload, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, type ReadStreamSessionStatusWire, type TranscriptWindowResponsePayload, type ReadBoardRequestPayload, type ReadBoardProjectSummary, type ReadBoardProjectListResponsePayload, type ReadBoardSnapshotResponsePayload, 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, } from './wire/payloads';
 export { PUSH_CATEGORIES, isPushCategory, parsePushEnvelopePlaintext, sealPushEnvelope, openPushEnvelope, PUSH_ENVELOPE_MAX_AGE_MS, PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS, type PushCategory, type PushEnvelopePlaintext, } from './crypto/push-envelope';
 export { PAIRING_URI_SCHEME, encodePairingQrPayload, decodePairingQrPayload, type PairingQrPayload, } from './pairing/qr';
+export { MAX_RELAY_ADDRESS_LENGTH, isSecureRelayAddress } from './pairing/relay-address';
 export { signRosterEntry, verifyRosterEntry, encodeRosterEntryForSigning, isRosterEntryExpired, findRosterDevice, rosterDeviceCapabilitySet, capabilitySetToRosterCapabilities, type RosterDeviceEntry, type DeviceRoster, } from './roster/roster';
 export { CAPABILITY_VERBS, isCapabilityVerb, capabilitySetFromArray, capabilitySetToArray, type CapabilityVerb, type CapabilitySet, } from './capabilities/verbs';
 export { BOARD_TOOL_READ_NAMES, BOARD_TOOL_WRITE_NAMES, isBoardToolReadName, isBoardToolWriteName, type BoardToolReadName, type BoardToolWriteName, type BoardToolName, } from './capabilities/board-tools';

package/dist/index.mjs

@@ -5075,6 +5075,56 @@ function base64UrlDecode(encoded) {
   return bytes;
 }
 
+// src/crypto/push-envelope.ts
+var PUSH_CATEGORIES = ["input-required", "turn-complete", "session-failed", "plan-complete", "spawn-stalled"];
+function isPushCategory(value) {
+  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
+}
+var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
+function requireEnvelopeString(record, field) {
+  const value = record[field];
+  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
+  return value;
+}
+function parsePushEnvelopePlaintext(value) {
+  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
+  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
+  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
+    throw new Error('push envelope plaintext has an invalid "sentAt"');
+  }
+  return {
+    category: value.category,
+    projectId: requireEnvelopeString(value, "projectId"),
+    taskId: requireEnvelopeString(value, "taskId"),
+    sessionId: requireEnvelopeString(value, "sessionId"),
+    taskTitle: requireEnvelopeString(value, "taskTitle"),
+    detail: requireEnvelopeString(value, "detail"),
+    sentAt: value.sentAt
+  };
+}
+function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
+  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
+  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
+  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
+  return base64UrlEncode(concatBytes4(nonce, ciphertext));
+}
+function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
+  const bytes = base64UrlDecode(blob);
+  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
+    throw new Error("push envelope blob is too short");
+  }
+  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
+  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
+  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
+  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
+  const plaintext = parsePushEnvelopePlaintext(decoded);
+  const now = Date.now();
+  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
+  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
+  return plaintext;
+}
+
 // src/events/payloads.ts
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
@@ -5156,6 +5206,7 @@ function isActivityReasonWire(value) {
   switch (value.kind) {
     case "idle":
     case "permission":
+      return value.since === void 0 || typeof value.since === "number";
     case "turn-active":
       return true;
     case "tool":
@@ -5384,6 +5435,10 @@ function parseReadStreamRequestPayload(payload) {
     }
     request.limit = payload.limit;
   }
+  if (payload.terminal !== void 0) {
+    if (typeof payload.terminal !== "boolean") throw new Error('read-stream payload has an invalid "terminal"');
+    request.terminal = payload.terminal;
+  }
   return request;
 }
 var ACCENT_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
@@ -5540,6 +5595,12 @@ function parseRegisterPushRequestPayload(payload) {
     }
     request.platform = payload.platform;
   }
+  if (payload.categories !== void 0) {
+    if (!Array.isArray(payload.categories) || !payload.categories.every((entry) => typeof entry === "string")) {
+      throw new Error('register-push payload has a malformed "categories"');
+    }
+    request.categories = payload.categories.filter(isPushCategory);
+  }
   if (request.action === "register") {
     if (request.expoPushToken === void 0) throw new Error('register-push register payload missing "expoPushToken"');
     if (request.pushKeyBase64 === void 0) throw new Error('register-push register payload missing "pushKeyBase64"');
@@ -5574,61 +5635,22 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
-// src/crypto/push-envelope.ts
-var PUSH_CATEGORIES = ["permission-needed", "agent-question", "turn-complete", "session-failed"];
-function isPushCategory(value) {
-  return typeof value === "string" && PUSH_CATEGORIES.includes(value);
-}
-var PUSH_ENVELOPE_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
-var PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS = 5 * 60 * 1e3;
-function requireEnvelopeString(record, field) {
-  const value = record[field];
-  if (typeof value !== "string") throw new Error(`push envelope plaintext is missing a string "${field}"`);
-  return value;
-}
-function parsePushEnvelopePlaintext(value) {
-  if (!isRecord(value)) throw new Error("push envelope plaintext must be an object");
-  if (!isPushCategory(value.category)) throw new Error('push envelope plaintext has an unknown "category"');
-  if (typeof value.sentAt !== "number" || !Number.isFinite(value.sentAt)) {
-    throw new Error('push envelope plaintext has an invalid "sentAt"');
-  }
-  return {
-    category: value.category,
-    projectId: requireEnvelopeString(value, "projectId"),
-    taskId: requireEnvelopeString(value, "taskId"),
-    sessionId: requireEnvelopeString(value, "sessionId"),
-    taskTitle: requireEnvelopeString(value, "taskTitle"),
-    detail: requireEnvelopeString(value, "detail"),
-    sentAt: value.sentAt
-  };
-}
-function sealPushEnvelope(pushKey, recipientStaticPublicKey, plaintext) {
-  const nonce = randomBytes4(XCHACHA_NONCE_LENGTH);
-  const encodedPlaintext = new TextEncoder().encode(JSON.stringify(plaintext));
-  const ciphertext = xaeadEncrypt(pushKey, nonce, recipientStaticPublicKey, encodedPlaintext);
-  return base64UrlEncode(concatBytes4(nonce, ciphertext));
-}
-function openPushEnvelope(pushKey, recipientStaticPublicKey, blob) {
-  const bytes = base64UrlDecode(blob);
-  if (bytes.length < XCHACHA_NONCE_LENGTH + AEAD_TAG_LENGTH) {
-    throw new Error("push envelope blob is too short");
-  }
-  const nonce = bytes.subarray(0, XCHACHA_NONCE_LENGTH);
-  const ciphertext = bytes.subarray(XCHACHA_NONCE_LENGTH);
-  const decrypted = xaeadDecrypt(pushKey, nonce, recipientStaticPublicKey, ciphertext);
-  const decoded = JSON.parse(new TextDecoder().decode(decrypted));
-  const plaintext = parsePushEnvelopePlaintext(decoded);
-  const now = Date.now();
-  if (plaintext.sentAt < now - PUSH_ENVELOPE_MAX_AGE_MS) throw new Error("push envelope is stale");
-  if (plaintext.sentAt > now + PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS) throw new Error("push envelope sentAt is in the future");
-  return plaintext;
+// src/pairing/relay-address.ts
+var MAX_RELAY_ADDRESS_LENGTH = 512;
+var LOOPBACK_WS_PREFIXES = ["ws://localhost", "ws://127.0.0.1", "ws://[::1]"];
+function isSecureRelayAddress(relayAddress) {
+  if (relayAddress.startsWith("wss://")) return true;
+  return LOOPBACK_WS_PREFIXES.some((prefix) => {
+    if (!relayAddress.startsWith(prefix)) return false;
+    const boundaryChar = relayAddress.charAt(prefix.length);
+    return boundaryChar === "" || boundaryChar === ":" || boundaryChar === "/" || boundaryChar === "?" || boundaryChar === "#";
+  });
 }
 
 // src/pairing/qr.ts
 var PAIRING_URI_SCHEME = "kangentic-pair";
 var PAYLOAD_VERSION = 1;
 var PAIRING_TOKEN_LENGTH = 32;
-var MAX_RELAY_ADDRESS_LENGTH = 512;
 var MAX_PAYLOAD_LENGTH = 4096;
 function writeUint32(value) {
   const bytes = new Uint8Array(4);
@@ -5759,7 +5781,8 @@ var BOARD_TOOL_READ_NAMES = [
   "get_handoff_context",
   "get_transcript",
   "get_session_files",
-  "get_session_events"
+  "get_session_events",
+  "get_activity_intervals"
 ];
 var BOARD_TOOL_WRITE_NAMES = [
   "create_task",
@@ -5809,6 +5832,10 @@ function parseActivityEventPayload(payload) {
       if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
       return { type: "session-ended", intentional: payload.intentional };
     }
+    case "message-preview": {
+      if (typeof payload.text !== "string") throw new Error('message-preview payload is missing "text"');
+      return { type: "message-preview", text: payload.text };
+    }
     default:
       throw new Error('activity payload has an unknown "type"');
   }
@@ -5874,6 +5901,7 @@ export {
   KK_PATTERN,
   MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH,
+  MAX_RELAY_ADDRESS_LENGTH,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
   PUSH_CATEGORIES,
@@ -5912,6 +5940,7 @@ export {
   isPushCategory,
   isRecord,
   isRosterEntryExpired,
+  isSecureRelayAddress,
   openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,

package/dist/pairing/qr.d.ts

@@ -1,3 +1,4 @@
+export { MAX_RELAY_ADDRESS_LENGTH, isSecureRelayAddress } from './relay-address';
 export declare const PAIRING_URI_SCHEME = "kangentic-pair";
 export interface PairingQrPayload {
     desktopStaticPublicKey: Uint8Array;

package/dist/pairing/relay-address.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Relay address rules shared, byte-for-byte, with the mobile app's
+ * src/pairing/qr.ts. This module imports nothing on purpose: it is
+ * deep-imported by the desktop's src/shared/relay.ts, which the RENDERER
+ * bundles, and pulling in the rest of this package (crypto/primitives ->
+ * @noble/*) would drag Noise crypto into that bundle for no reason. Keep it
+ * dependency-free.
+ */
+export declare const MAX_RELAY_ADDRESS_LENGTH = 512;
+/**
+ * True if the phone's pairing QR scanner will accept this relay address.
+ * wss:// is always secure; ws:// is accepted only for loopback, since the
+ * pairing token doubles as the Noise PSK and is dialed verbatim as
+ * `?slot=`. Prefix-based (not hostname-based) with an explicit boundary
+ * check, so `ws://localhost.evil.com` - a hostname that merely starts with
+ * the string "localhost" - is rejected rather than treated as loopback.
+ */
+export declare function isSecureRelayAddress(relayAddress: string): boolean;

package/dist/wire/payloads.d.ts

@@ -15,6 +15,7 @@
  */
 import type { CapabilityVerb } from '../capabilities/verbs';
 import type { JsonValue } from './messages';
+import { type PushCategory } from '../crypto/push-envelope';
 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;
@@ -31,6 +32,20 @@ export interface ReadStreamRequestPayload {
     beforeIndex?: number;
     /** transcript-window only: maximum entries wanted (the desktop may cap this and may return fewer). */
     limit?: number;
+    /**
+     * subscribe only: whether this subscription wants live PTY bytes.
+     *
+     * A phone watching its session list needs activity, permission and
+     * transcript pushes, but NOT the terminal - it discards those bytes on
+     * arrival. Measured on a live board, that discard cost roughly 13MB an hour
+     * of relay traffic and mobile data for a feed showing no terminal at all.
+     *
+     * Omitted means true, so an older phone keeps the previous behaviour and an
+     * older desktop that ignores the field simply keeps sending (wasteful, not
+     * broken). Set false for a list-only subscription and re-subscribe with it
+     * true when a terminal actually opens.
+     */
+    terminal?: boolean;
 }
 /**
  * Mirrors the desktop's SessionStatus. 'suspended' is a registered-but-
@@ -207,12 +222,20 @@ export interface BoardToolResponsePayload {
  * 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.
+ *
+ * `categories`, when present, is the device's push preferences: the desktop
+ * filters outgoing notifications to this set before sending, so preference
+ * enforcement never depends on the receiving device (a future iOS
+ * Notification Service Extension stays preference-free). Absent means every
+ * category (the default, and what an older device that predates this field
+ * implicitly requests); an explicit empty array means none.
  */
 export interface RegisterPushRequestPayload {
     action: 'register' | 'unregister';
     expoPushToken?: string;
     pushKeyBase64?: string;
     platform?: 'android' | 'ios';
+    categories?: PushCategory[];
 }
 export interface RegisterPushResponsePayload {
     registered: boolean;

package/package.json

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