@q9labsai/chalk-client 5.1.0 → 5.2.1

package/dist/{chunk-K7PNW3KI.js → chunk-TVNI2XUZ.js}

@@ -120,7 +120,7 @@ var BrowserSyncSocket = class {
     this.#socket = socket;
     this.#socket.addEventListener("open", () => this.onopen?.());
     this.#socket.addEventListener("message", (event) => this.onmessage?.({ data: event.data }));
-    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -154,7 +154,9 @@ function createReactNativeWebSocketFactory(WebSocketConstructor) {
 function createReactNativeSyncLifecycle(environment) {
   return {
     subscribe(listener) {
-      const appState = environment.appState.addEventListener("change", (state) => listener(state === "active" ? "active" : "inactive"));
+      const appState = environment.appState.addEventListener("change", (state) => {
+        if (state !== "inactive") listener(state === "active" ? "active" : "inactive");
+      });
       const network = environment.networkInfo?.addEventListener((state) => listener(isNetworkOnline(state) ? "online" : "offline"));
       listener(environment.appState.currentState === "active" ? "active" : "inactive");
       return () => {
@@ -176,7 +178,7 @@ var ReactNativeSyncSocket = class {
     this.#socket = socket;
     this.#socket.onopen = () => this.onopen?.();
     this.#socket.onmessage = (event) => this.onmessage?.({ data: event.data });
-    this.#socket.onclose = (event) => this.onclose?.({ code: typeof event.code === "number" ? event.code : 1006 });
+    this.#socket.onclose = (event) => this.onclose?.({ code: typeof event.code === "number" ? event.code : 1006, reason: typeof event.reason === "string" ? event.reason : void 0 });
     this.#socket.onerror = () => this.onerror?.();
   }
   send(data) {
@@ -196,7 +198,7 @@ var BrowserFallbackSyncSocket = class {
     this.#socket = socket;
     this.#socket.addEventListener("open", () => this.onopen?.());
     this.#socket.addEventListener("message", (event) => this.onmessage?.({ data: event.data }));
-    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -217,6 +219,40 @@ function unsubscribe(subscription) {
   }
 }
 
+// src/sync/connect-diagnostics.ts
+var SAFE_REASONS = /* @__PURE__ */ new Set([
+  "hello timeout",
+  "invalid token",
+  "policy violation",
+  "dependency unavailable",
+  "server draining",
+  "heartbeat timeout",
+  "normal",
+  "transport error",
+  "authentication failed",
+  "delivery recovery required",
+  "space action delivery recovery required",
+  "text frames only",
+  "unsupported protocol",
+  "invalid frame",
+  "WebSocket dial timeout",
+  "lifecycle transport deadline",
+  "lifecycle unavailable",
+  "invalid_frame",
+  "state_digest_mismatch",
+  "state_digest_recovery_failed",
+  "terminal event acknowledged",
+  "client stopped",
+  "participant inactive",
+  "terminal recovery"
+]);
+function safeSyncCloseReason(reason) {
+  return reason ? SAFE_REASONS.has(reason) ? reason : "redacted" : null;
+}
+function formatSyncConnectDiagnostic(diagnostic) {
+  return `[${diagnostic.stage}; open=${diagnostic.opened ? 1 : 0}; close=${diagnostic.closeCode ?? "none"}; reason=${safeSyncCloseReason(diagnostic.closeReason ?? void 0) ?? "none"}; ${Math.round(diagnostic.durationMs)}ms]`;
+}
+
 // src/sync/v1-health.ts
 var SYNC_HEALTH_BUDGET = {
   probeIntervalMs: 500,
@@ -266,7 +302,14 @@ var SyncProtocolMetadata = {
     field: "protocol",
     value: 1,
     transport: "websocket-json-text",
-    route: "/v1/sync"
+    route: "/v1/sync",
+    entryGeneration: {
+      queryParameter: "entry_generation",
+      newEntry: "new",
+      resume: "previous welcome entry_generation",
+      confirmation: "monotonic compare-and-set",
+      scope: "participant"
+    }
   },
   directions: {
     clientToServer: "client-to-server",
@@ -290,7 +333,7 @@ var SyncProtocolMetadata = {
     },
     {
       id: "live",
-      accepts: ["command", "live_target", "directed_request", "delivery_ack", "request_ack", "reaction_send", "chat_send", "chat_page_request", "chat_read_set", "chat_reaction_set", "ping"],
+      accepts: ["entered", "command", "live_target", "directed_request", "delivery_ack", "request_ack", "reaction_send", "chat_send", "chat_page_request", "chat_read_set", "chat_reaction_set", "ping"],
       heartbeat: {
         intervalMs: 2e4,
         missedDeadlinesBeforeClose: 2
@@ -570,7 +613,7 @@ var SyncProtocolMetadata = {
     {
       code: 1008,
       connection: "closed",
-      reasons: ["invalid token", "policy violation"]
+      reasons: ["invalid token", "policy violation", "entry timeout"]
     },
     {
       code: 1009,
@@ -742,6 +785,8 @@ function strictClientFrame(value) {
       return exactObject(value, ["type", "stream", "revision", "state_digest"]);
     case "recovery_ack":
       return exactObject(value, ["type", "recovery_id", "revision", "state_digest"]);
+    case "entered":
+      return exactObject(value, ["type"]);
     case "ping":
       return exactObject(value, ["type"]);
     default:
@@ -824,7 +869,8 @@ function strictWelcome(value) {
   const base = ["type", "protocol", "participant_id", "participant_generation", "recovery_id", "head", "mode"];
   const extension = Array.isArray(value.extensions) && value.extensions.length === 1 ? value.extensions[0] : void 0;
   const extensionValid = isObject(extension) && ["collaboration_v1", "collaboration_v2"].includes(String(extension.name)) && exactObject(extension, ["name", "capabilities", "participant_capabilities", "chat_head_sequence", "retained_floor_sequence", "read_receipts"]) && Array.isArray(extension.read_receipts);
-  const fields = extensionValid ? [...base, "extensions"] : base;
+  if (Object.hasOwn(value, "entry_confirmation") && value.entry_confirmation !== true) return false;
+  const fields = [...base, ...extensionValid ? ["extensions"] : [], ...Object.hasOwn(value, "entry_confirmation") ? ["entry_confirmation"] : [], ...Object.hasOwn(value, "entry_generation") ? ["entry_generation"] : []];
   if (!strictCursor(value.head)) return false;
   if (value.mode === "snapshot") return exactObjectWithCorrelation(value, [...fields, "snapshot"]) && strictSnapshot(value.snapshot);
   if (value.mode === "terminal") return exactObjectWithCorrelation(value, [...fields, "reason"]);
@@ -883,6 +929,8 @@ function strictServerFrame(value) {
       return exactObjectWithCorrelation(value, ["type", "command_id", "code"]);
     case "error":
       return exactObjectWithCorrelation(value, ["type", "code", "detail"]);
+    case "entered_ack":
+      return exactObjectWithCorrelation(value, ["type"]);
     case "pong":
       return exactObjectWithCorrelation(value, ["type"]);
     default:
@@ -1423,7 +1471,16 @@ var CollaborationWelcomeExtensionSchema = Schema.Struct({
   retained_floor_sequence: Schema.NullOr(UnsignedDecimalSchema),
   read_receipts: Schema.Array(ChatReadReceiptSchema).check(Schema.isMaxLength(500))
 }).check(exactKeys(["name", "capabilities", "participant_capabilities", "chat_head_sequence", "retained_floor_sequence", "read_receipts"]));
-var WelcomeBase = { type: Schema.Literal("welcome"), protocol: Schema.Literal(1), participant_id: UuidSchema, participant_generation: PositiveIntegerSchema, recovery_id: UuidSchema, head: ControlCursorSchema };
+var WelcomeBase = {
+  type: Schema.Literal("welcome"),
+  protocol: Schema.Literal(1),
+  participant_id: UuidSchema,
+  participant_generation: PositiveIntegerSchema,
+  recovery_id: UuidSchema,
+  head: ControlCursorSchema,
+  entry_confirmation: Schema.optionalKey(Schema.Literal(true)),
+  entry_generation: Schema.optionalKey(PositiveIntegerSchema.check(Schema.isLessThanOrEqualTo(9007199254740991)))
+};
 var ExtendedWelcomeBase = { ...WelcomeBase, extensions: Schema.Tuple([CollaborationWelcomeExtensionSchema]) };
 var WelcomeSnapshotFrameSchema = Schema.Struct({ ...WelcomeBase, mode: Schema.Literal("snapshot"), snapshot: SnapshotSchema, ...ServerCorrelationFields }).check(boundedServerFrame(SyncProtocolLimits.snapshotEncodedBytes));
 var WelcomeReplayFrameSchema = Schema.Struct({ ...WelcomeBase, mode: Schema.Literal("replay"), ...ServerCorrelationFields });
@@ -1599,6 +1656,8 @@ var RejectedChatReadResultFrameSchema = Schema.Struct({ type: Schema.Literal("ch
 var ChatReadResultFrameSchema = Schema.Union([AcceptedChatReadResultFrameSchema, RejectedChatReadResultFrameSchema]);
 var RetryableErrorFrameSchema = Schema.Struct({ type: Schema.Literal("retryable_error"), command_id: CommandIdSchema, code: RetryableErrorCodeSchema, ...ServerCorrelationFields });
 var ErrorFrameSchema = Schema.Struct({ type: Schema.Literal("error"), code: ProtocolErrorCodeSchema, detail: boundedUtf8String(1024), ...ServerCorrelationFields });
+var EnteredFrameSchema = Schema.Struct({ type: Schema.Literal("entered") });
+var EnteredAckFrameSchema = Schema.Struct({ type: Schema.Literal("entered_ack"), ...ServerCorrelationFields });
 var PingFrameSchema = Schema.Struct({ type: Schema.Literal("ping") });
 var PongFrameSchema = Schema.Struct({ type: Schema.Literal("pong"), ...ServerCorrelationFields });
 var SyncV1ClientFrameSchema = Schema.Unknown.check(Schema.makeFilter((frame) => strictClientFrame(frame) ? void 0 : { path: [], issue: "must not contain unknown or missing fields" })).pipe(
@@ -1632,6 +1691,7 @@ var SyncV1ClientFrameSchema = Schema.Unknown.check(Schema.makeFilter((frame) =>
       ChatReactionSetFrameSchema,
       DeliveryAckFrameSchema,
       RecoveryAckFrameSchema,
+      EnteredFrameSchema,
       PingFrameSchema
     ])
   )
@@ -1663,6 +1723,7 @@ var SyncV1ServerFrameSchema = Schema.Unknown.check(Schema.makeFilter((frame) =>
       ChatReactionResultFrameSchema,
       RetryableErrorFrameSchema,
       ErrorFrameSchema,
+      EnteredAckFrameSchema,
       PongFrameSchema
     ])
   )
@@ -1897,7 +1958,7 @@ function reduceEvent(state, event) {
     case "episode_started":
       return state;
     case "episode_ended":
-      return { ...state, status: "ended", participants: [], admissionRequests: [], recording: null };
+      return { ...state, status: "ended", endReason: event.payload.reason, participants: [], admissionRequests: [], recording: null };
     case "hand_raised":
     case "hand_lowered":
       return updateParticipant(state, event.payload.participant_id, (participant) => ({ ...participant, handRaised: event.name === "hand_raised" }));
@@ -2939,6 +3000,9 @@ var V1SyncClient = class {
   #snapshotRevision = null;
   #controlEvents = /* @__PURE__ */ new Map();
   #liveTargets;
+  #entryPending = false;
+  // Older Sync rejects new hello fields, so entry confirmation is requested on the URL and granted in welcome.
+  #entryNegotiated = false;
   #requests = /* @__PURE__ */ new Map();
   #mediaEventEvidence = /* @__PURE__ */ new Map();
   #presenceEventEvidence = /* @__PURE__ */ new Map();
@@ -2949,6 +3013,7 @@ var V1SyncClient = class {
   #presence = null;
   #participantId = null;
   #participantGeneration = null;
+  #entryGeneration = null;
   #recovery = null;
   #snapshotRecoveryRequested = false;
   #lastDigestRecoveryAt = null;
@@ -2958,7 +3023,14 @@ var V1SyncClient = class {
   #reconnectTimer;
   #cancelDial;
   #dialTimeoutCount = 0;
+  #connectStartedAt = null;
+  #opened = false;
+  #connectFailure;
+  #connectDiagnostic() {
+    return { stage: this.#opened ? "hello" : "upgrade", opened: this.#opened, closeCode: null, closeReason: null, durationMs: Math.max(0, this.#clock().now() - (this.#connectStartedAt ?? this.#clock().now())) };
+  }
   #reconnectAttempt = 0;
+  #episodeEndTimer;
   #heartbeatTimer;
   #missedHeartbeats = 0;
   #noticeTimer;
@@ -3036,11 +3108,15 @@ var V1SyncClient = class {
   }
   stop() {
     this.#started = false;
+    this.#entryPending = false;
+    this.#entryGeneration = null;
     this.#startupGeneration += 1;
     this.#unsubscribeLifecycle?.();
     this.#unsubscribeLifecycle = void 0;
     this.#clearReconnect();
     this.#clearDial();
+    this.#clock().clearTimeout(this.#episodeEndTimer);
+    this.#episodeEndTimer = void 0;
     this.#clearHeartbeat();
     this.#clearNoticeProbe();
     this.#commandScheduler.stop("client_stopped");
@@ -3055,11 +3131,24 @@ var V1SyncClient = class {
     this.#liveTargets.resetLocalMedia();
     this.#emit();
   }
+  /** Announces completed startup; transport recovery resends until acknowledged. */
+  async confirmEntered() {
+    this.#requireLive();
+    this.#entryPending = true;
+    if (!this.#entryNegotiated) return;
+    this.#send({ type: "entered" });
+  }
   getSnapshot() {
     const pendingCommands = this.#commandScheduler.pendingCommands;
     const optimisticControl = this.#control && this.#participantId ? optimisticV1Control(this.#control, this.#participantId, pendingCommands) : this.#control;
     return {
-      connection: { ...this.#phase, ...this.#phase.phase === "live" ? { noticeUnresponsive: this.#health.health === "recovering", health: this.#health.health } : {}, ...this.#dialTimeoutCount ? { dialTimeoutCount: this.#dialTimeoutCount } : {} },
+      connection: {
+        ...this.#phase,
+        ...this.#connectStartedAt !== null && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering") ? { connectAttempt: this.#connectDiagnostic() } : {},
+        ...this.#connectFailure && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering") ? { connectFailure: this.#connectFailure } : {},
+        ...this.#phase.phase === "live" ? { noticeUnresponsive: this.#health.health === "recovering", health: this.#health.health } : {},
+        ...this.#dialTimeoutCount ? { dialTimeoutCount: this.#dialTimeoutCount } : {}
+      },
       participantId: this.#participantId,
       participantGeneration: this.#participantGeneration,
       control: this.#control,
@@ -3199,8 +3288,19 @@ var V1SyncClient = class {
   #connect() {
     if (!this.#started || !this.#transportAvailable || this.#socket || this.#phase.phase === "terminal") return;
     this.#phase = { phase: "connecting" };
+    this.#connectStartedAt = this.#clock().now();
+    this.#opened = false;
+    this.#connectFailure = void 0;
     this.#emit();
-    const socket = this.#options.webSocket.connect(this.#options.url);
+    this.#entryNegotiated = false;
+    let socket;
+    try {
+      socket = this.#options.webSocket.connect(entryUrl(this.#options.url, this.#entryGeneration, this.#options.entryConfirmation === true));
+    } catch {
+      this.#connectFailure = this.#connectDiagnostic();
+      this.#emit();
+      throw new V1SyncError("Sync WebSocket could not be created", "sync_hello_timeout");
+    }
     const connectionGeneration = ++this.#connectionGeneration;
     this.#socket = socket;
     this.#cancelDial = scheduleSyncDialDeadline(
@@ -3208,6 +3308,7 @@ var V1SyncClient = class {
       () => {
         this.#cancelDial = void 0;
         this.#dialTimeoutCount += 1;
+        this.#connectFailure = this.#connectDiagnostic();
         this.#recover("WebSocket dial timeout");
       },
       this.#options.dialTimeoutMs
@@ -3215,18 +3316,36 @@ var V1SyncClient = class {
     socket.onopen = () => {
       if (socket !== this.#socket) return;
       this.#clearDial();
+      this.#opened = true;
+      this.#connectFailure = void 0;
       void this.#authenticate(socket);
     };
     socket.onmessage = (event) => {
       this.#inbound = this.#inbound.then(() => this.#receive(socket, event.data));
     };
-    socket.onclose = () => {
+    socket.onclose = (event) => {
+      if (socket === this.#socket && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering")) {
+        this.#connectFailure = { ...this.#connectDiagnostic(), closeCode: event.code, closeReason: safeSyncCloseReason(event.reason) };
+        this.#emit();
+      }
       this.#clock().setTimeout(() => {
         if (connectionGeneration !== this.#connectionGeneration) return;
-        this.#inbound = this.#inbound.then(() => this.#disconnected(socket));
+        this.#inbound = this.#inbound.then(() => {
+          if (socket === this.#socket && event.code === 1008 && (event.reason === "" || event.reason === "invalid token" || event.reason === "policy violation" || event.reason === "entry timeout")) {
+            this.#phase = { phase: "terminal", terminalReason: event.reason === "entry timeout" ? "entry_timeout" : "access_rejected" };
+            this.#emit();
+          }
+          this.#disconnected(socket);
+        });
       }, 0);
     };
-    socket.onerror = () => socket.close(CLIENT_RESTART_CLOSE_CODE, "transport error");
+    socket.onerror = () => {
+      if (socket === this.#socket && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering")) {
+        this.#connectFailure = this.#connectDiagnostic();
+        this.#emit();
+      }
+      socket.close(CLIENT_RESTART_CLOSE_CODE, "transport error");
+    };
   }
   async #authenticate(socket) {
     try {
@@ -3309,6 +3428,19 @@ var V1SyncClient = class {
       case "ack":
         this.#requireLive();
         await this.#commandScheduler.acknowledge(frame);
+        if (frame.outcome === "rejected" && frame.reason === "episode_ended") {
+          if (this.#episodeEndTimer === void 0) {
+            this.#episodeEndTimer = this.#clock().setTimeout(() => {
+              this.#episodeEndTimer = void 0;
+              if (this.#control?.status === "ended" || this.#phase.phase === "terminal") return;
+              this.#phase = { phase: "terminal", terminalReason: "episode_ended" };
+              this.#clearReconnect();
+              this.#socket?.close(1e3, "episode ended");
+              this.#emit();
+            }, 5e3);
+          }
+          this.#recover("episode ended");
+        }
         return;
       case "retryable_error":
         this.#requireLive();
@@ -3355,6 +3487,10 @@ var V1SyncClient = class {
         return;
       case "error":
         throw new V1ReplicaError(frame.code);
+      case "entered_ack":
+        this.#requireLive();
+        this.#entryPending = false;
+        return;
       case "pong": {
         this.#requireLive();
         this.#missedHeartbeats = 0;
@@ -3368,6 +3504,8 @@ var V1SyncClient = class {
   async #welcome(frame) {
     if (this.#phase.phase !== "recovering" || this.#recovery) throw new V1ReplicaError("unexpected welcome");
     this.#collaborationState.acceptWelcome(frame);
+    this.#entryNegotiated = frame.entry_confirmation === true;
+    this.#entryGeneration = frame.entry_generation ?? this.#entryGeneration;
     this.#participantId = frame.participant_id;
     this.#participantGeneration = frame.participant_generation;
     this.#updateLocalMediaStates();
@@ -3486,8 +3624,11 @@ var V1SyncClient = class {
     if (!this.#recovery?.controlComplete || !this.#media || !this.#presence) return;
     this.#recovery = null;
     this.#phase = { phase: "live" };
+    this.#connectStartedAt = null;
+    this.#connectFailure = void 0;
     this.#reconnectAttempt = 0;
     this.#missedHeartbeats = 0;
+    if (this.#entryPending && this.#entryNegotiated) this.#send({ type: "entered" });
     this.#commandScheduler.enterLive();
     this.#liveTargets.enterLive();
     this.#startHeartbeat();
@@ -3529,9 +3670,10 @@ var V1SyncClient = class {
     this.#presence = null;
     this.#rejectRequests("disconnected_before_delivery");
     this.#collaborationState.disconnect("disconnected_before_delivery");
-    if (!this.#started || !this.#transportAvailable || this.#phase.phase === "terminal") return;
+    if (!this.#started || this.#phase.phase === "terminal") return;
     this.#phase = { phase: "connecting" };
     this.#emit();
+    if (!this.#transportAvailable) return;
     this.#clearReconnect();
     const configuredDelay = this.#options.reconnectDelayMs;
     const exponentialAttempt = configuredDelay === void 0 ? Math.max(0, this.#reconnectAttempt - FAST_RECONNECT_ATTEMPTS + 1) : this.#reconnectAttempt;
@@ -3576,8 +3718,13 @@ var V1SyncClient = class {
     if (event === "online" || event === "offline") this.#online = event === "online";
     else this.#active = event === "active";
     this.#transportAvailable = this.#online && this.#active;
-    if (!this.#transportAvailable) this.#socket?.close(CLIENT_RESTART_CLOSE_CODE, "lifecycle unavailable");
-    else this.#connect();
+    if (!this.#transportAvailable) {
+      const socket = this.#socket;
+      if (socket) {
+        socket.close(CLIENT_RESTART_CLOSE_CODE, "lifecycle unavailable");
+        this.#disconnected(socket);
+      }
+    } else this.#connect();
   }
   #rejectEphemeral(code) {
     this.#rejectRequests(code);
@@ -3746,6 +3893,12 @@ function copyPublication(publication) {
 function validMediaPublication(publication) {
   return typeof publication.participantId === "string" && publication.participantId.length > 0 && (publication.source === "microphone" || publication.source === "camera" || publication.source === "screen" || publication.source === "screen_audio") && typeof publication.enabled === "boolean" && (publication.publicationId === null || typeof publication.publicationId === "string") && (!publication.enabled || publication.publicationId !== null);
 }
+function entryUrl(value, generation, confirmation) {
+  const url = new URL(value);
+  url.searchParams.set("entry_generation", generation === null ? "new" : String(generation));
+  if (confirmation) url.searchParams.set("entry_confirmation", "1");
+  return url.toString();
+}
 function assertV1Url(value) {
   const url = new URL(value);
   if (url.pathname !== "/v1/sync") throw new V1SyncError("SyncEngine v1 websocket URL must use /v1/sync", "invalid_url");
@@ -3893,6 +4046,7 @@ function createV1SyncClient(options) {
 }
 
 export {
+  formatSyncConnectDiagnostic,
   UuidSchema,
   ReactionValues,
   ReactionSchema,