@kangentic/protocol 0.2.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,12 +27,13 @@
  * event before its router dispatches on `kind`.
  */
 import type { JsonValue } from '../wire/messages';
-import { type ActivityReasonWire, type ActivityStateWire, type SessionEventWire, type SessionUsageWire, type TranscriptEntryWire } from './payloads';
+import { type ActivityReasonWire, type ActivityStateWire, type SessionEventWire, type SessionUsageWire, type TerminalDimensionsWire, type TranscriptEventPayload } from './payloads';
 export interface TranscriptEvent {
     kind: 'transcript';
     sessionId: string;
     taskId: string;
-    payload: TranscriptEntryWire[];
+    /** Incremental (protocol v2): indexed upserts or a reset signal, never the whole transcript. See TranscriptEventPayload. */
+    payload: TranscriptEventPayload;
 }
 export type ActivityEventPayload = {
     type: 'activity';
@@ -45,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';
@@ -60,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[];
@@ -75,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

@@ -68,6 +68,51 @@ export type TranscriptEntryWire = {
     subtype: TranscriptSystemSubtypeWire;
     text: string;
 };
+/** One transcript entry at its absolute position in the full transcript at the delta's revision. */
+export interface TranscriptUpsertWire {
+    index: number;
+    entry: TranscriptEntryWire;
+}
+/**
+ * Protocol v2 transcript payload: incremental, never the whole transcript.
+ *
+ * - 'delta' carries only the entries that changed or appeared since the
+ *   last delta the desktop sent on this subscription, as absolute-indexed
+ *   upserts in ascending order. A large delta is split across several
+ *   events (same revision) so every frame stays well under the transport
+ *   caps and the first chunk renders without waiting for the rest. The
+ *   phone applies upserts inside or adjacent to its loaded window and
+ *   re-requests a window when it detects a gap.
+ * - 'reset' tells the phone its local state is unreconstructable from
+ *   deltas (entries removed or reordered, or a degraded transcript source
+ *   whose uuids are unstable) - drop local entries and re-request a
+ *   window via the read-stream 'transcript-window' action.
+ *
+ * `revision` is the desktop's monotonically increasing whole-transcript
+ * version; `totalEntries` is the full transcript length at that revision,
+ * which is how the phone knows history extends above its window.
+ */
+export type TranscriptEventPayload = {
+    mode: 'delta';
+    revision: number;
+    totalEntries: number;
+    upserts: TranscriptUpsertWire[];
+} | {
+    mode: 'reset';
+    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. */
@@ -198,8 +243,16 @@ export interface DiffFileContentWire {
     modified: string;
     language: string;
 }
-/** Narrows a transcript event's payload to the entry array the phone renders. Throws on a malformed entry so the caller can drop the push. */
+/** Narrows a transcript entry array (windowed-history pages). Throws on a malformed entry so the caller can drop the payload. */
 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. */