@kangentic/protocol 0.2.0 → 0.3.0

package/dist/events/event.d.ts

@@ -24,12 +24,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 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';

package/dist/events/payloads.d.ts

@@ -68,6 +68,40 @@ 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;
+};
 /** 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 +232,10 @@ 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;
 /** True for a well-formed ActivityStateWire value. */
 export declare function isActivityStateWire(value: unknown): value is ActivityStateWire;
 /** True for a well-formed ActivityReasonWire value. */