@kangentic/protocol 0.7.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/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,
@@ -5317,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":
@@ -5545,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}$/;
@@ -5741,11 +5748,22 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
+// 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);
@@ -5876,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",
@@ -5926,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"');
   }
@@ -5992,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,
@@ -6030,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

@@ -5206,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":
@@ -5434,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}$/;
@@ -5630,11 +5635,22 @@ function parseCapabilityRequestPayload(verb, payload) {
   }
 }
 
+// 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);
@@ -5765,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",
@@ -5815,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"');
   }
@@ -5880,6 +5901,7 @@ export {
   KK_PATTERN,
   MAX_DECODED_LENGTH,
   MAX_FRAME_LENGTH,
+  MAX_RELAY_ADDRESS_LENGTH,
   PAIRING_URI_SCHEME,
   PROTOCOL_VERSION,
   PUSH_CATEGORIES,
@@ -5918,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

@@ -32,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-

package/package.json

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