@kangentic/protocol 0.3.0 → 0.5.0

package/dist/capabilities/verbs.d.ts

@@ -9,7 +9,7 @@
  * wire a handler, and a device's roster entry still has to include it in
  * its CapabilitySet.
  */
-export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt", "interactive-terminal", "board-tool-read", "board-tool-write"];
+export declare const CAPABILITY_VERBS: readonly ["read-stream", "read-board", "read-diff", "send-user-message", "move-task", "answer-permission-prompt", "interactive-terminal", "board-tool-read", "board-tool-write", "register-push"];
 export type CapabilityVerb = (typeof CAPABILITY_VERBS)[number];
 export declare function isCapabilityVerb(value: string): value is CapabilityVerb;
 /** Deny-by-default: a verb absent from the set is not authorized. */

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

@@ -0,0 +1,38 @@
+export declare const PUSH_CATEGORIES: readonly ["permission-needed", "agent-question", "turn-complete", "session-failed"];
+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). */
+export declare const PUSH_ENVELOPE_MAX_AGE_MS: number;
+/** Tolerated forward clock skew; anything claiming to be further in the future is rejected. */
+export declare const PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS: number;
+/**
+ * The real notification content, visible only on the sealing desktop and
+ * the opening device. Everything the OS-visible push payload carries
+ * instead is a static placeholder.
+ */
+export interface PushEnvelopePlaintext {
+    category: PushCategory;
+    projectId: string;
+    taskId: string;
+    sessionId: string;
+    taskTitle: string;
+    detail: string;
+    /** Wall-clock ms at seal time; openPushEnvelope enforces the freshness window from it. */
+    sentAt: number;
+}
+/** Narrows a decrypted envelope's JSON to PushEnvelopePlaintext. Throws on any malformed field. */
+export declare function parsePushEnvelopePlaintext(value: unknown): PushEnvelopePlaintext;
+/**
+ * Seals a notification into an opaque base64url blob:
+ * base64url(nonce[24] || XChaCha20-Poly1305(pushKey, nonce, aad=recipientStaticPublicKey, JSON(plaintext))).
+ */
+export declare function sealPushEnvelope(pushKey: Uint8Array, recipientStaticPublicKey: Uint8Array, plaintext: PushEnvelopePlaintext): string;
+/**
+ * Opens a sealed push blob. Throws on: a malformed blob, a tampered
+ * ciphertext, the wrong key, the wrong recipient key (AAD mismatch),
+ * non-JSON or malformed plaintext, an unknown category, or a sentAt
+ * outside the freshness window (older than 24h, or more than 5min in the
+ * future). The caller (the device-side notification handler) catches and
+ * shows the generic placeholder.
+ */
+export declare function openPushEnvelope(pushKey: Uint8Array, recipientStaticPublicKey: Uint8Array, blob: string): PushEnvelopePlaintext;

package/dist/events/event.d.ts

@@ -2,7 +2,7 @@
  * The event contract the phone consumes, pushed as EventMessage.event over
  * an established BridgeSession once Phase 2's capability handlers (desktop
  * bridge module) subscribe SessionManager/transcript-service/DiffService to
- * a session's live state. Five kinds:
+ * a session's live state. Six kinds:
  *
  * - transcript: a revision-gated delta from resolveTaskTranscript, for the
  *   phone's transcript-styled conversation view.
@@ -13,6 +13,9 @@
  * - terminal: raw PTY output from the unfiltered data-tap, for the phone's
  *   raw-terminal-mirror view (a distinct consumer from the parsed
  *   transcript).
+ * - terminal-resize: the PTY grid changed (desktop pane refit, phone fit
+ *   request, or restore-on-release); the phone re-sizes its renderer to
+ *   match before the TUI's repaint bytes arrive on the terminal stream.
  * - board: a board-mutation notification, filterable by project and
  *   (optionally) task.
  * - diff: a payload-less "something under this task's worktree changed,
@@ -24,7 +27,7 @@
  * event before its router dispatches on `kind`.
  */
 import type { JsonValue } from '../wire/messages';
-import { type ActivityReasonWire, type ActivityStateWire, type SessionEventWire, type SessionUsageWire, type TranscriptEventPayload } from './payloads';
+import { type ActivityReasonWire, type ActivityStateWire, type SessionEventWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEventPayload } from './payloads';
 export interface TranscriptEvent {
     kind: 'transcript';
     sessionId: string;
@@ -46,6 +49,17 @@ export type ActivityEventPayload = {
     type: 'permission';
     promptId: string;
     pending: boolean;
+}
+/**
+ * The streamed session's PTY exited. Pushed once by the desktop's
+ * read-stream subscription right before it tears itself down, so the
+ * phone learns "this session is over" from the feed itself instead of
+ * inferring it from silence. `intentional` distinguishes a deliberate
+ * stop (desktop Stop button, suspend, shutdown) from a crash.
+ */
+ | {
+    type: 'session-ended';
+    intentional: boolean;
 };
 export interface ActivityEvent {
     kind: 'activity';
@@ -61,6 +75,13 @@ export interface TerminalEvent {
         data: string;
     };
 }
+export interface TerminalResizeEvent {
+    kind: 'terminal-resize';
+    sessionId: string;
+    taskId: string;
+    /** The PTY's new grid; every terminal byte sent after this event is laid out for it. */
+    payload: TerminalDimensionsWire;
+}
 export interface BoardEventPayload {
     change: 'task-created' | 'task-updated' | 'task-deleted' | 'swimlane-updated' | 'backlog-changed';
     ids: string[];
@@ -76,7 +97,7 @@ export interface DiffEvent {
     taskId: string;
     payload: null;
 }
-export type BridgeEvent = TranscriptEvent | ActivityEvent | TerminalEvent | BoardEvent | DiffEvent;
+export type BridgeEvent = TranscriptEvent | ActivityEvent | TerminalEvent | TerminalResizeEvent | BoardEvent | DiffEvent;
 /**
  * Narrows an activity event's payload to its typed union. Throws on a
  * malformed required field so the caller can drop the event cleanly.

package/dist/events/payloads.d.ts

@@ -102,6 +102,17 @@ export type TranscriptEventPayload = {
     revision: number;
     totalEntries: number;
 };
+/**
+ * PTY grid dimensions, shared by the read-stream snapshot (`ptyDimensions`),
+ * the `terminal-resize` event, and the interactive-terminal `resize` action.
+ * The bytes on the terminal stream are laid out for exactly this grid; a
+ * renderer that uses any other geometry misplaces every cursor-addressed
+ * frame the fullscreen TUI draws.
+ */
+export interface TerminalDimensionsWire {
+    cols: number;
+    rows: number;
+}
 /** 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. */
@@ -236,6 +247,12 @@ export interface DiffFileContentWire {
 export declare function parseTranscriptEntriesWire(payload: JsonValue): TranscriptEntryWire[];
 /** Narrows a transcript event's delta/reset payload. Throws on a malformed required field so the caller can drop the push. */
 export declare function parseTranscriptEventPayload(payload: JsonValue): TranscriptEventPayload;
+/**
+ * Narrows a PTY dimensions payload. Bounds are sanity caps, not policy:
+ * the desktop's own resize clamp (cols >= 2, rows >= 1) is the floor, and
+ * 1000 on each axis rejects garbage without constraining any real device.
+ */
+export declare function parseTerminalDimensionsWire(payload: JsonValue): TerminalDimensionsWire;
 /** True for a well-formed ActivityStateWire value. */
 export declare function isActivityStateWire(value: unknown): value is ActivityStateWire;
 /** True for a well-formed ActivityReasonWire value. */

package/dist/index.cjs

@@ -34,6 +34,9 @@ __export(index_exports, {
   MAX_FRAME_LENGTH: () => MAX_FRAME_LENGTH,
   PAIRING_URI_SCHEME: () => PAIRING_URI_SCHEME,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  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,
   SecretstreamState: () => SecretstreamState,
   SessionFrameKind: () => SessionFrameKind,
   X25519_KEY_LENGTH: () => X25519_KEY_LENGTH,
@@ -64,8 +67,10 @@ __export(index_exports, {
   isBridgeEvent: () => isBridgeEvent,
   isCapabilityVerb: () => isCapabilityVerb,
   isJsonValue: () => isJsonValue,
+  isPushCategory: () => isPushCategory,
   isRecord: () => isRecord,
   isRosterEntryExpired: () => isRosterEntryExpired,
+  openPushEnvelope: () => openPushEnvelope,
   parseActivityEventPayload: () => parseActivityEventPayload,
   parseBacklogItemWire: () => parseBacklogItemWire,
   parseBoardColumnWire: () => parseBoardColumnWire,
@@ -73,16 +78,20 @@ __export(index_exports, {
   parseCapabilityRequestPayload: () => parseCapabilityRequestPayload,
   parseDiffFileContentWire: () => parseDiffFileContentWire,
   parseDiffFileListWire: () => parseDiffFileListWire,
+  parsePushEnvelopePlaintext: () => parsePushEnvelopePlaintext,
   parseReadBoardResponsePayload: () => parseReadBoardResponsePayload,
   parseReadDiffResponsePayload: () => parseReadDiffResponsePayload,
   parseReadStreamResponsePayload: () => parseReadStreamResponsePayload,
+  parseRegisterPushRequestPayload: () => parseRegisterPushRequestPayload,
   parseSessionEventWire: () => parseSessionEventWire,
   parseSessionUsageWire: () => parseSessionUsageWire,
+  parseTerminalDimensionsWire: () => parseTerminalDimensionsWire,
   parseTranscriptEntriesWire: () => parseTranscriptEntriesWire,
   parseTranscriptEventPayload: () => parseTranscriptEventPayload,
   parseTranscriptWindowResponsePayload: () => parseTranscriptWindowResponsePayload,
   randomBytes: () => randomBytes4,
   rosterDeviceCapabilitySet: () => rosterDeviceCapabilitySet,
+  sealPushEnvelope: () => sealPushEnvelope,
   signRosterEntry: () => signRosterEntry,
   unwrapSessionFrame: () => unwrapSessionFrame,
   verifyRosterEntry: () => verifyRosterEntry,
@@ -4975,7 +4984,8 @@ var CAPABILITY_VERBS = [
   "answer-permission-prompt",
   "interactive-terminal",
   "board-tool-read",
-  "board-tool-write"
+  "board-tool-write",
+  "register-push"
 ];
 function isCapabilityVerb(value) {
   return CAPABILITY_VERBS.includes(value);
@@ -5061,7 +5071,8 @@ function validateEvent(event) {
   switch (event.kind) {
     case "transcript":
     case "activity":
-    case "terminal": {
+    case "terminal":
+    case "terminal-resize": {
       if (typeof event.sessionId !== "string") throw new Error(`"${event.kind}" event is missing "sessionId"`);
       if (typeof event.taskId !== "string") throw new Error(`"${event.kind}" event is missing "taskId"`);
       return event;
@@ -5134,6 +5145,47 @@ function unwrapSessionFrame(frame) {
   return { kind, payload: frame.subarray(1) };
 }
 
+// src/wire/base64url.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+var DECODE_MAP = {};
+for (let i = 0; i < ALPHABET.length; i++) DECODE_MAP[ALPHABET[i]] = i;
+function base64UrlEncode(bytes) {
+  let result = "";
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const chunk = bytes[i] << 16 | bytes[i + 1] << 8 | bytes[i + 2];
+    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63] + ALPHABET[chunk & 63];
+  }
+  const remaining = bytes.length - i;
+  if (remaining === 1) {
+    const chunk = bytes[i] << 16;
+    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63];
+  } else if (remaining === 2) {
+    const chunk = bytes[i] << 16 | bytes[i + 1] << 8;
+    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63];
+  }
+  return result;
+}
+function base64UrlDecode(encoded) {
+  const byteLength = Math.floor(encoded.length * 6 / 8);
+  const bytes = new Uint8Array(byteLength);
+  let bitBuffer = 0;
+  let bitCount = 0;
+  let outputIndex = 0;
+  for (const char of encoded) {
+    const value = DECODE_MAP[char];
+    if (value === void 0) throw new Error(`Invalid base64url character: "${char}"`);
+    bitBuffer = bitBuffer << 6 | value;
+    bitCount += 6;
+    if (bitCount >= 8) {
+      bitCount -= 8;
+      bytes[outputIndex] = bitBuffer >> bitCount & 255;
+      outputIndex += 1;
+    }
+  }
+  return bytes;
+}
+
 // src/events/payloads.ts
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
@@ -5199,6 +5251,14 @@ function parseTranscriptEventPayload(payload) {
   });
   return { mode: "delta", revision, totalEntries, upserts };
 }
+function parseTerminalDimensionsWire(payload) {
+  if (!isRecord(payload)) throw new Error("terminal dimensions must be an object");
+  const cols = requireNumber(payload, "cols", "terminal dimensions");
+  const rows = requireNumber(payload, "rows", "terminal dimensions");
+  if (!Number.isInteger(cols) || cols < 2 || cols > 1e3) throw new Error('terminal dimensions have an invalid "cols"');
+  if (!Number.isInteger(rows) || rows < 1 || rows > 1e3) throw new Error('terminal dimensions have an invalid "rows"');
+  return { cols, rows };
+}
 function isActivityStateWire(value) {
   return value === "thinking" || value === "idle" || value === "permission";
 }
@@ -5359,6 +5419,7 @@ function parseDiffFileContentWire(payload) {
 }
 
 // src/wire/payloads.ts
+var READ_STREAM_SESSION_STATUSES = ["running", "queued", "suspended", "exited"];
 function parseReadStreamResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-stream response must be an object");
   if (typeof payload.scrollback !== "string") throw new Error('read-stream response is missing "scrollback"');
@@ -5370,12 +5431,22 @@ function parseReadStreamResponsePayload(payload) {
   if (payload.awaitedPromptId !== null && typeof payload.awaitedPromptId !== "string") {
     throw new Error('read-stream response has an invalid "awaitedPromptId"');
   }
-  return {
+  const response = {
     scrollback: payload.scrollback,
     activity: { state: state ?? null, reason: reason ?? null },
     usage: payload.usage === null || payload.usage === void 0 ? null : parseSessionUsageWire(payload.usage),
     awaitedPromptId: payload.awaitedPromptId ?? null
   };
+  if (payload.ptyDimensions !== void 0) {
+    response.ptyDimensions = parseTerminalDimensionsWire(payload.ptyDimensions);
+  }
+  if (payload.sessionStatus !== void 0) {
+    if (typeof payload.sessionStatus !== "string" || !READ_STREAM_SESSION_STATUSES.includes(payload.sessionStatus)) {
+      throw new Error('read-stream response has an invalid "sessionStatus"');
+    }
+    response.sessionStatus = payload.sessionStatus;
+  }
+  return response;
 }
 function parseTranscriptWindowResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("transcript-window response must be an object");
@@ -5417,6 +5488,13 @@ function parseReadStreamRequestPayload(payload) {
   }
   return request;
 }
+var ACCENT_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+function parseAccentColor(value, context) {
+  if (typeof value !== "string" || !ACCENT_COLOR_PATTERN.test(value)) {
+    throw new Error(`${context} has an invalid accent color (expected "#rrggbb")`);
+  }
+  return value;
+}
 function parseReadBoardResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board response must be an object");
   if (Array.isArray(payload.projects)) {
@@ -5424,7 +5502,11 @@ function parseReadBoardResponsePayload(payload) {
       if (!isRecord(project) || typeof project.id !== "string" || typeof project.name !== "string") {
         throw new Error(`read-board project ${index} is malformed`);
       }
-      return { id: project.id, name: project.name };
+      return {
+        id: project.id,
+        name: project.name,
+        ...project.color !== void 0 ? { color: parseAccentColor(project.color, `read-board project ${index}`) } : {}
+      };
     });
     return { projects };
   }
@@ -5436,7 +5518,8 @@ function parseReadBoardResponsePayload(payload) {
     projectId: payload.projectId,
     columns: payload.columns.map((column) => parseBoardColumnWire(column)),
     tasks: payload.tasks.map((task) => parseBoardTaskWire(task)),
-    backlog: payload.backlog.map((item) => parseBacklogItemWire(item))
+    backlog: payload.backlog.map((item) => parseBacklogItemWire(item)),
+    ...payload.projectColor !== void 0 ? { projectColor: parseAccentColor(payload.projectColor, "read-board snapshot") } : {}
   };
 }
 function parseReadBoardRequestPayload(payload) {
@@ -5503,8 +5586,21 @@ function parseAnswerPermissionPromptRequestPayload(payload) {
 function parseInteractiveTerminalRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("interactive-terminal payload must be an object");
   if (typeof payload.sessionId !== "string") throw new Error('interactive-terminal payload missing "sessionId"');
-  if (typeof payload.data !== "string") throw new Error('interactive-terminal payload missing "data"');
-  return { sessionId: payload.sessionId, data: payload.data };
+  if (payload.action === void 0 || payload.action === "write") {
+    if (typeof payload.data !== "string") throw new Error('interactive-terminal payload missing "data"');
+    return { sessionId: payload.sessionId, action: "write", data: payload.data };
+  }
+  if (payload.action === "resize") {
+    return {
+      sessionId: payload.sessionId,
+      action: "resize",
+      dimensions: parseTerminalDimensionsWire(payload.dimensions)
+    };
+  }
+  if (payload.action === "release-size") {
+    return { sessionId: payload.sessionId, action: "release-size" };
+  }
+  throw new Error('interactive-terminal payload has an invalid "action"');
 }
 function parseBoardToolRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("board-tool payload must be an object");
@@ -5512,6 +5608,42 @@ function parseBoardToolRequestPayload(payload) {
   if (payload.params === void 0 || !isJsonValue(payload.params)) throw new Error('board-tool payload missing a JSON "params"');
   return { tool: payload.tool, params: payload.params };
 }
+var PUSH_KEY_LENGTH = 32;
+function parseRegisterPushRequestPayload(payload) {
+  if (!isRecord(payload)) throw new Error("register-push payload must be an object");
+  if (payload.action !== "register" && payload.action !== "unregister") {
+    throw new Error('register-push payload has an invalid "action"');
+  }
+  const request = { action: payload.action };
+  if (payload.expoPushToken !== void 0) {
+    if (typeof payload.expoPushToken !== "string") throw new Error('register-push payload has a non-string "expoPushToken"');
+    request.expoPushToken = payload.expoPushToken;
+  }
+  if (payload.pushKeyBase64 !== void 0) {
+    if (typeof payload.pushKeyBase64 !== "string") throw new Error('register-push payload has a non-string "pushKeyBase64"');
+    let decodedKey;
+    try {
+      decodedKey = base64UrlDecode(payload.pushKeyBase64);
+    } catch {
+      throw new Error('register-push payload has a malformed "pushKeyBase64"');
+    }
+    if (decodedKey.length !== PUSH_KEY_LENGTH) {
+      throw new Error(`register-push payload "pushKeyBase64" must decode to ${PUSH_KEY_LENGTH} bytes`);
+    }
+    request.pushKeyBase64 = payload.pushKeyBase64;
+  }
+  if (payload.platform !== void 0) {
+    if (payload.platform !== "android" && payload.platform !== "ios") {
+      throw new Error('register-push payload has an invalid "platform"');
+    }
+    request.platform = payload.platform;
+  }
+  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"');
+  }
+  return request;
+}
 function parseCapabilityRequestPayload(verb, payload) {
   switch (verb) {
     case "read-stream":
@@ -5531,6 +5663,8 @@ function parseCapabilityRequestPayload(verb, payload) {
     case "board-tool-read":
     case "board-tool-write":
       return parseBoardToolRequestPayload(payload);
+    case "register-push":
+      return parseRegisterPushRequestPayload(payload);
     default: {
       const exhaustiveCheck = verb;
       throw new Error(`Unknown capability verb: ${String(exhaustiveCheck)}`);
@@ -5538,45 +5672,54 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
-// src/wire/base64url.ts
-var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-var DECODE_MAP = {};
-for (let i = 0; i < ALPHABET.length; i++) DECODE_MAP[ALPHABET[i]] = i;
-function base64UrlEncode(bytes) {
-  let result = "";
-  let i = 0;
-  for (; i + 2 < bytes.length; i += 3) {
-    const chunk = bytes[i] << 16 | bytes[i + 1] << 8 | bytes[i + 2];
-    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63] + ALPHABET[chunk & 63];
-  }
-  const remaining = bytes.length - i;
-  if (remaining === 1) {
-    const chunk = bytes[i] << 16;
-    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63];
-  } else if (remaining === 2) {
-    const chunk = bytes[i] << 16 | bytes[i + 1] << 8;
-    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63];
-  }
-  return result;
+// 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 base64UrlDecode(encoded) {
-  const byteLength = Math.floor(encoded.length * 6 / 8);
-  const bytes = new Uint8Array(byteLength);
-  let bitBuffer = 0;
-  let bitCount = 0;
-  let outputIndex = 0;
-  for (const char of encoded) {
-    const value = DECODE_MAP[char];
-    if (value === void 0) throw new Error(`Invalid base64url character: "${char}"`);
-    bitBuffer = bitBuffer << 6 | value;
-    bitCount += 6;
-    if (bitCount >= 8) {
-      bitCount -= 8;
-      bytes[outputIndex] = bitBuffer >> bitCount & 255;
-      outputIndex += 1;
-    }
+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 bytes;
+  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/qr.ts
@@ -5754,6 +5897,10 @@ function parseActivityEventPayload(payload) {
       if (typeof payload.pending !== "boolean") throw new Error('permission payload is missing "pending"');
       return { type: "permission", promptId: payload.promptId, pending: payload.pending };
     }
+    case "session-ended": {
+      if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
+      return { type: "session-ended", intentional: payload.intentional };
+    }
     default:
       throw new Error('activity payload has an unknown "type"');
   }
@@ -5783,6 +5930,15 @@ function isBridgeEvent(value) {
       if (typeof value.sessionId !== "string" || typeof value.taskId !== "string") return false;
       return isRecord(value.payload) && typeof value.payload.data === "string";
     }
+    case "terminal-resize": {
+      if (typeof value.sessionId !== "string" || typeof value.taskId !== "string") return false;
+      try {
+        parseTerminalDimensionsWire(value.payload);
+        return true;
+      } catch {
+        return false;
+      }
+    }
     case "board": {
       if (typeof value.projectId !== "string") return false;
       if (value.taskId !== void 0 && typeof value.taskId !== "string") return false;
@@ -5813,6 +5969,9 @@ function isBridgeEvent(value) {
   MAX_FRAME_LENGTH,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
+  PUSH_CATEGORIES,
+  PUSH_ENVELOPE_MAX_AGE_MS,
+  PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
   SecretstreamState,
   SessionFrameKind,
   X25519_KEY_LENGTH,
@@ -5843,8 +6002,10 @@ function isBridgeEvent(value) {
   isBridgeEvent,
   isCapabilityVerb,
   isJsonValue,
+  isPushCategory,
   isRecord,
   isRosterEntryExpired,
+  openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,
   parseBoardColumnWire,
@@ -5852,16 +6013,20 @@ function isBridgeEvent(value) {
   parseCapabilityRequestPayload,
   parseDiffFileContentWire,
   parseDiffFileListWire,
+  parsePushEnvelopePlaintext,
   parseReadBoardResponsePayload,
   parseReadDiffResponsePayload,
   parseReadStreamResponsePayload,
+  parseRegisterPushRequestPayload,
   parseSessionEventWire,
   parseSessionUsageWire,
+  parseTerminalDimensionsWire,
   parseTranscriptEntriesWire,
   parseTranscriptEventPayload,
   parseTranscriptWindowResponsePayload,
   randomBytes,
   rosterDeviceCapabilitySet,
+  sealPushEnvelope,
   signRosterEntry,
   unwrapSessionFrame,
   verifyRosterEntry,

package/dist/index.d.ts

@@ -12,11 +12,12 @@ export type { JsonValue, BridgeMessage, HeartbeatMessage, CapabilityRequestMessa
 export { encodeMessage, decodeMessage, 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, type CapabilityRequestPayloadMap, type CapabilityResponsePayloadMap, type ReadStreamRequestPayload, type ReadStreamResponsePayload, 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, } from './wire/payloads';
+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 { 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';
-export { isBridgeEvent, parseActivityEventPayload, type BridgeEvent, type TranscriptEvent, type ActivityEvent, type ActivityEventPayload, type TerminalEvent, type BoardEvent, type BoardEventPayload, type DiffEvent, } from './events/event';
-export { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionEventWire, parseBoardColumnWire, parseBoardTaskWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionEventWire, type BoardColumnWire, type BoardTaskWire, type BacklogItemWire, type DiffFileStatusWire, type DiffFileWire, type DiffFileListWire, type DiffFileContentWire, } from './events/payloads';
+export { isBridgeEvent, parseActivityEventPayload, type BridgeEvent, type TranscriptEvent, type ActivityEvent, type ActivityEventPayload, type TerminalEvent, type TerminalResizeEvent, type BoardEvent, type BoardEventPayload, type DiffEvent, } from './events/event';
+export { parseTranscriptEntriesWire, parseTranscriptEventPayload, type TranscriptEventPayload, type TranscriptUpsertWire, isActivityStateWire, isActivityReasonWire, parseSessionUsageWire, parseSessionEventWire, parseTerminalDimensionsWire, parseBoardColumnWire, parseBoardTaskWire, parseBacklogItemWire, parseDiffFileListWire, parseDiffFileContentWire, type TranscriptBlockWire, type TranscriptEntryWire, type TranscriptTurnUsageWire, type TranscriptSystemSubtypeWire, type ActivityStateWire, type ActivityReasonWire, type SessionUsageWire, type SessionEventWire, type TerminalDimensionsWire, type BoardColumnWire, type BoardTaskWire, type BacklogItemWire, type DiffFileStatusWire, type DiffFileWire, type DiffFileListWire, type DiffFileContentWire, } from './events/payloads';
 export type { Transport, TransportState, Unsubscribe } from './transport/transport';

package/dist/index.mjs

@@ -4873,7 +4873,8 @@ var CAPABILITY_VERBS = [
   "answer-permission-prompt",
   "interactive-terminal",
   "board-tool-read",
-  "board-tool-write"
+  "board-tool-write",
+  "register-push"
 ];
 function isCapabilityVerb(value) {
   return CAPABILITY_VERBS.includes(value);
@@ -4959,7 +4960,8 @@ function validateEvent(event) {
   switch (event.kind) {
     case "transcript":
     case "activity":
-    case "terminal": {
+    case "terminal":
+    case "terminal-resize": {
       if (typeof event.sessionId !== "string") throw new Error(`"${event.kind}" event is missing "sessionId"`);
       if (typeof event.taskId !== "string") throw new Error(`"${event.kind}" event is missing "taskId"`);
       return event;
@@ -5032,6 +5034,47 @@ function unwrapSessionFrame(frame) {
   return { kind, payload: frame.subarray(1) };
 }
 
+// src/wire/base64url.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+var DECODE_MAP = {};
+for (let i = 0; i < ALPHABET.length; i++) DECODE_MAP[ALPHABET[i]] = i;
+function base64UrlEncode(bytes) {
+  let result = "";
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const chunk = bytes[i] << 16 | bytes[i + 1] << 8 | bytes[i + 2];
+    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63] + ALPHABET[chunk & 63];
+  }
+  const remaining = bytes.length - i;
+  if (remaining === 1) {
+    const chunk = bytes[i] << 16;
+    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63];
+  } else if (remaining === 2) {
+    const chunk = bytes[i] << 16 | bytes[i + 1] << 8;
+    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63];
+  }
+  return result;
+}
+function base64UrlDecode(encoded) {
+  const byteLength = Math.floor(encoded.length * 6 / 8);
+  const bytes = new Uint8Array(byteLength);
+  let bitBuffer = 0;
+  let bitCount = 0;
+  let outputIndex = 0;
+  for (const char of encoded) {
+    const value = DECODE_MAP[char];
+    if (value === void 0) throw new Error(`Invalid base64url character: "${char}"`);
+    bitBuffer = bitBuffer << 6 | value;
+    bitCount += 6;
+    if (bitCount >= 8) {
+      bitCount -= 8;
+      bytes[outputIndex] = bitBuffer >> bitCount & 255;
+      outputIndex += 1;
+    }
+  }
+  return bytes;
+}
+
 // src/events/payloads.ts
 var DIFF_FILE_STATUSES = ["A", "M", "D", "R", "C", "U"];
 var TRANSCRIPT_SYSTEM_SUBTYPES = ["compaction", "command", "command_output", "session_boundary"];
@@ -5097,6 +5140,14 @@ function parseTranscriptEventPayload(payload) {
   });
   return { mode: "delta", revision, totalEntries, upserts };
 }
+function parseTerminalDimensionsWire(payload) {
+  if (!isRecord(payload)) throw new Error("terminal dimensions must be an object");
+  const cols = requireNumber(payload, "cols", "terminal dimensions");
+  const rows = requireNumber(payload, "rows", "terminal dimensions");
+  if (!Number.isInteger(cols) || cols < 2 || cols > 1e3) throw new Error('terminal dimensions have an invalid "cols"');
+  if (!Number.isInteger(rows) || rows < 1 || rows > 1e3) throw new Error('terminal dimensions have an invalid "rows"');
+  return { cols, rows };
+}
 function isActivityStateWire(value) {
   return value === "thinking" || value === "idle" || value === "permission";
 }
@@ -5257,6 +5308,7 @@ function parseDiffFileContentWire(payload) {
 }
 
 // src/wire/payloads.ts
+var READ_STREAM_SESSION_STATUSES = ["running", "queued", "suspended", "exited"];
 function parseReadStreamResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-stream response must be an object");
   if (typeof payload.scrollback !== "string") throw new Error('read-stream response is missing "scrollback"');
@@ -5268,12 +5320,22 @@ function parseReadStreamResponsePayload(payload) {
   if (payload.awaitedPromptId !== null && typeof payload.awaitedPromptId !== "string") {
     throw new Error('read-stream response has an invalid "awaitedPromptId"');
   }
-  return {
+  const response = {
     scrollback: payload.scrollback,
     activity: { state: state ?? null, reason: reason ?? null },
     usage: payload.usage === null || payload.usage === void 0 ? null : parseSessionUsageWire(payload.usage),
     awaitedPromptId: payload.awaitedPromptId ?? null
   };
+  if (payload.ptyDimensions !== void 0) {
+    response.ptyDimensions = parseTerminalDimensionsWire(payload.ptyDimensions);
+  }
+  if (payload.sessionStatus !== void 0) {
+    if (typeof payload.sessionStatus !== "string" || !READ_STREAM_SESSION_STATUSES.includes(payload.sessionStatus)) {
+      throw new Error('read-stream response has an invalid "sessionStatus"');
+    }
+    response.sessionStatus = payload.sessionStatus;
+  }
+  return response;
 }
 function parseTranscriptWindowResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("transcript-window response must be an object");
@@ -5315,6 +5377,13 @@ function parseReadStreamRequestPayload(payload) {
   }
   return request;
 }
+var ACCENT_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+function parseAccentColor(value, context) {
+  if (typeof value !== "string" || !ACCENT_COLOR_PATTERN.test(value)) {
+    throw new Error(`${context} has an invalid accent color (expected "#rrggbb")`);
+  }
+  return value;
+}
 function parseReadBoardResponsePayload(payload) {
   if (!isRecord(payload)) throw new Error("read-board response must be an object");
   if (Array.isArray(payload.projects)) {
@@ -5322,7 +5391,11 @@ function parseReadBoardResponsePayload(payload) {
       if (!isRecord(project) || typeof project.id !== "string" || typeof project.name !== "string") {
         throw new Error(`read-board project ${index} is malformed`);
       }
-      return { id: project.id, name: project.name };
+      return {
+        id: project.id,
+        name: project.name,
+        ...project.color !== void 0 ? { color: parseAccentColor(project.color, `read-board project ${index}`) } : {}
+      };
     });
     return { projects };
   }
@@ -5334,7 +5407,8 @@ function parseReadBoardResponsePayload(payload) {
     projectId: payload.projectId,
     columns: payload.columns.map((column) => parseBoardColumnWire(column)),
     tasks: payload.tasks.map((task) => parseBoardTaskWire(task)),
-    backlog: payload.backlog.map((item) => parseBacklogItemWire(item))
+    backlog: payload.backlog.map((item) => parseBacklogItemWire(item)),
+    ...payload.projectColor !== void 0 ? { projectColor: parseAccentColor(payload.projectColor, "read-board snapshot") } : {}
   };
 }
 function parseReadBoardRequestPayload(payload) {
@@ -5401,8 +5475,21 @@ function parseAnswerPermissionPromptRequestPayload(payload) {
 function parseInteractiveTerminalRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("interactive-terminal payload must be an object");
   if (typeof payload.sessionId !== "string") throw new Error('interactive-terminal payload missing "sessionId"');
-  if (typeof payload.data !== "string") throw new Error('interactive-terminal payload missing "data"');
-  return { sessionId: payload.sessionId, data: payload.data };
+  if (payload.action === void 0 || payload.action === "write") {
+    if (typeof payload.data !== "string") throw new Error('interactive-terminal payload missing "data"');
+    return { sessionId: payload.sessionId, action: "write", data: payload.data };
+  }
+  if (payload.action === "resize") {
+    return {
+      sessionId: payload.sessionId,
+      action: "resize",
+      dimensions: parseTerminalDimensionsWire(payload.dimensions)
+    };
+  }
+  if (payload.action === "release-size") {
+    return { sessionId: payload.sessionId, action: "release-size" };
+  }
+  throw new Error('interactive-terminal payload has an invalid "action"');
 }
 function parseBoardToolRequestPayload(payload) {
   if (!isRecord(payload)) throw new Error("board-tool payload must be an object");
@@ -5410,6 +5497,42 @@ function parseBoardToolRequestPayload(payload) {
   if (payload.params === void 0 || !isJsonValue(payload.params)) throw new Error('board-tool payload missing a JSON "params"');
   return { tool: payload.tool, params: payload.params };
 }
+var PUSH_KEY_LENGTH = 32;
+function parseRegisterPushRequestPayload(payload) {
+  if (!isRecord(payload)) throw new Error("register-push payload must be an object");
+  if (payload.action !== "register" && payload.action !== "unregister") {
+    throw new Error('register-push payload has an invalid "action"');
+  }
+  const request = { action: payload.action };
+  if (payload.expoPushToken !== void 0) {
+    if (typeof payload.expoPushToken !== "string") throw new Error('register-push payload has a non-string "expoPushToken"');
+    request.expoPushToken = payload.expoPushToken;
+  }
+  if (payload.pushKeyBase64 !== void 0) {
+    if (typeof payload.pushKeyBase64 !== "string") throw new Error('register-push payload has a non-string "pushKeyBase64"');
+    let decodedKey;
+    try {
+      decodedKey = base64UrlDecode(payload.pushKeyBase64);
+    } catch {
+      throw new Error('register-push payload has a malformed "pushKeyBase64"');
+    }
+    if (decodedKey.length !== PUSH_KEY_LENGTH) {
+      throw new Error(`register-push payload "pushKeyBase64" must decode to ${PUSH_KEY_LENGTH} bytes`);
+    }
+    request.pushKeyBase64 = payload.pushKeyBase64;
+  }
+  if (payload.platform !== void 0) {
+    if (payload.platform !== "android" && payload.platform !== "ios") {
+      throw new Error('register-push payload has an invalid "platform"');
+    }
+    request.platform = payload.platform;
+  }
+  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"');
+  }
+  return request;
+}
 function parseCapabilityRequestPayload(verb, payload) {
   switch (verb) {
     case "read-stream":
@@ -5429,6 +5552,8 @@ function parseCapabilityRequestPayload(verb, payload) {
     case "board-tool-read":
     case "board-tool-write":
       return parseBoardToolRequestPayload(payload);
+    case "register-push":
+      return parseRegisterPushRequestPayload(payload);
     default: {
       const exhaustiveCheck = verb;
       throw new Error(`Unknown capability verb: ${String(exhaustiveCheck)}`);
@@ -5436,45 +5561,54 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
-// src/wire/base64url.ts
-var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-var DECODE_MAP = {};
-for (let i = 0; i < ALPHABET.length; i++) DECODE_MAP[ALPHABET[i]] = i;
-function base64UrlEncode(bytes) {
-  let result = "";
-  let i = 0;
-  for (; i + 2 < bytes.length; i += 3) {
-    const chunk = bytes[i] << 16 | bytes[i + 1] << 8 | bytes[i + 2];
-    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63] + ALPHABET[chunk & 63];
-  }
-  const remaining = bytes.length - i;
-  if (remaining === 1) {
-    const chunk = bytes[i] << 16;
-    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63];
-  } else if (remaining === 2) {
-    const chunk = bytes[i] << 16 | bytes[i + 1] << 8;
-    result += ALPHABET[chunk >> 18 & 63] + ALPHABET[chunk >> 12 & 63] + ALPHABET[chunk >> 6 & 63];
-  }
-  return result;
+// 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 base64UrlDecode(encoded) {
-  const byteLength = Math.floor(encoded.length * 6 / 8);
-  const bytes = new Uint8Array(byteLength);
-  let bitBuffer = 0;
-  let bitCount = 0;
-  let outputIndex = 0;
-  for (const char of encoded) {
-    const value = DECODE_MAP[char];
-    if (value === void 0) throw new Error(`Invalid base64url character: "${char}"`);
-    bitBuffer = bitBuffer << 6 | value;
-    bitCount += 6;
-    if (bitCount >= 8) {
-      bitCount -= 8;
-      bytes[outputIndex] = bitBuffer >> bitCount & 255;
-      outputIndex += 1;
-    }
+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 bytes;
+  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/qr.ts
@@ -5652,6 +5786,10 @@ function parseActivityEventPayload(payload) {
       if (typeof payload.pending !== "boolean") throw new Error('permission payload is missing "pending"');
       return { type: "permission", promptId: payload.promptId, pending: payload.pending };
     }
+    case "session-ended": {
+      if (typeof payload.intentional !== "boolean") throw new Error('session-ended payload is missing "intentional"');
+      return { type: "session-ended", intentional: payload.intentional };
+    }
     default:
       throw new Error('activity payload has an unknown "type"');
   }
@@ -5681,6 +5819,15 @@ function isBridgeEvent(value) {
       if (typeof value.sessionId !== "string" || typeof value.taskId !== "string") return false;
       return isRecord(value.payload) && typeof value.payload.data === "string";
     }
+    case "terminal-resize": {
+      if (typeof value.sessionId !== "string" || typeof value.taskId !== "string") return false;
+      try {
+        parseTerminalDimensionsWire(value.payload);
+        return true;
+      } catch {
+        return false;
+      }
+    }
     case "board": {
       if (typeof value.projectId !== "string") return false;
       if (value.taskId !== void 0 && typeof value.taskId !== "string") return false;
@@ -5710,6 +5857,9 @@ export {
   MAX_FRAME_LENGTH,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
+  PUSH_CATEGORIES,
+  PUSH_ENVELOPE_MAX_AGE_MS,
+  PUSH_ENVELOPE_MAX_FUTURE_SKEW_MS,
   SecretstreamState,
   SessionFrameKind,
   X25519_KEY_LENGTH,
@@ -5740,8 +5890,10 @@ export {
   isBridgeEvent,
   isCapabilityVerb,
   isJsonValue,
+  isPushCategory,
   isRecord,
   isRosterEntryExpired,
+  openPushEnvelope,
   parseActivityEventPayload,
   parseBacklogItemWire,
   parseBoardColumnWire,
@@ -5749,16 +5901,20 @@ export {
   parseCapabilityRequestPayload,
   parseDiffFileContentWire,
   parseDiffFileListWire,
+  parsePushEnvelopePlaintext,
   parseReadBoardResponsePayload,
   parseReadDiffResponsePayload,
   parseReadStreamResponsePayload,
+  parseRegisterPushRequestPayload,
   parseSessionEventWire,
   parseSessionUsageWire,
+  parseTerminalDimensionsWire,
   parseTranscriptEntriesWire,
   parseTranscriptEventPayload,
   parseTranscriptWindowResponsePayload,
   randomBytes4 as randomBytes,
   rosterDeviceCapabilitySet,
+  sealPushEnvelope,
   signRosterEntry,
   unwrapSessionFrame,
   verifyRosterEntry,

package/dist/wire/payloads.d.ts

@@ -15,7 +15,7 @@
  */
 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';
+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;
     /**
@@ -32,6 +32,12 @@ export interface ReadStreamRequestPayload {
     /** 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;
@@ -42,6 +48,17 @@ 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;
@@ -66,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 {
@@ -77,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. */
@@ -120,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;
@@ -134,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;
@@ -144,6 +213,7 @@ export interface CapabilityRequestPayloadMap {
     'interactive-terminal': InteractiveTerminalRequestPayload;
     'board-tool-read': BoardToolRequestPayload;
     'board-tool-write': BoardToolRequestPayload;
+    'register-push': RegisterPushRequestPayload;
 }
 export interface CapabilityResponsePayloadMap {
     'read-stream': ReadStreamResponsePayload | TranscriptWindowResponsePayload;
@@ -155,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.3.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",