@q9labsai/chalk-client 5.2.6 → 5.3.1

package/dist/{chunk-5YPQNMJE.js → chunk-FD7ZSDTM.js}

@@ -1,3 +1,7 @@
+import {
+  sessionBaggage
+} from "./chunk-N4IPKRS6.js";
+
 // src/sync/canonical.ts
 var encoder = new TextEncoder();
 function canonicalJson(value) {
@@ -405,11 +409,20 @@ var SyncProtocolMetadata = {
         pattern: "^[a-z][a-z0-9_*\\-/]{0,255}=[\\x21-\\x2b\\x2d-\\x3c\\x3e-\\x7e]{1,256}(,[a-z][a-z0-9_*\\-/]{0,255}=[\\x21-\\x2b\\x2d-\\x3c\\x3e-\\x7e]{1,256})*$"
       }
     },
+    helloOnlyFields: {
+      baggage: {
+        kind: "string",
+        minBytes: 47,
+        maxBytes: 47,
+        format: "w3c-baggage-session-id",
+        pattern: "^session\\.id=[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+      }
+    },
     acceptedOn: {
       hello: "client-to-server",
       serverFrames: "server-to-client"
     },
-    upgradeHeaders: ["x-chalk-journey-id", "traceparent", "tracestate"],
+    upgradeHeaders: ["x-chalk-journey-id", "traceparent", "tracestate", "baggage"],
     rule: "propagate_from_first_observed_layer_to_every_downstream_frame"
   },
   externalIntents: [
@@ -712,7 +725,9 @@ function strictCommand(value) {
 function strictCollaborationsHelloExtension(value) {
   return exactObject(value, ["name", "chat_cursor"]) && ["collaboration_v1", "collaboration_v2"].includes(String(value.name)) && exactObject(value.chat_cursor, ["after_sequence", "retained_floor_sequence"]);
 }
-function strictHello(value) {
+function strictHello(hello) {
+  const { baggage, ...value } = hello;
+  if (baggage !== void 0 && !(typeof baggage === "string" && boundedCorrelationString(baggage, 47, 47) && /^session\.id=[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(baggage))) return false;
   const base = exactObjectWithCorrelation(value, ["type", "protocol", "token", "streams"]);
   const extended = exactObjectWithCorrelation(value, ["type", "protocol", "token", "streams", "extensions"]) && Array.isArray(value.extensions) && value.extensions.length === 1 && strictCollaborationsHelloExtension(value.extensions[0]);
   if (!base && !extended || !exactObject(value.streams, ["control", "media", "presence", "requests"])) return false;
@@ -861,7 +876,8 @@ function strictEvent(value) {
 }
 function strictProjectionItem(value, stream) {
   if (stream === "media") return exactObject(value, ["participant_id", "source", "enabled", "publication_id"]);
-  if (stream === "presence") return exactObject(value, ["participant_id", "state", "speaking", "active_speaker"]);
+  if (stream === "presence")
+    return isObject(value) && exactObject(value, [...["participant_id", "state", "speaking", "active_speaker"], ...Object.hasOwn(value, "identity_id") ? ["identity_id"] : [], ...Object.hasOwn(value, "device_type") ? ["device_type"] : [], ...Object.hasOwn(value, "admission_revision") ? ["admission_revision"] : []]);
   return false;
 }
 function strictProjection(value) {
@@ -873,7 +889,13 @@ function strictWelcome(value) {
   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);
   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"] : []];
+  const fields = [
+    ...base,
+    ...extensionValid ? ["extensions"] : [],
+    ...Object.hasOwn(value, "entry_confirmation") ? ["entry_confirmation"] : [],
+    ...Object.hasOwn(value, "entry_generation") ? ["entry_generation"] : [],
+    ...Object.hasOwn(value, "participant_identity_id") ? ["participant_identity_id"] : []
+  ];
   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"]);
@@ -950,9 +972,10 @@ var TraceparentSchema = boundedUtf8String(55, 55).check(
 var TracestateSchema = boundedUtf8String(512, 1).check(
   Schema.makeFilter((value) => new RegExp("^[a-z][a-z0-9_*\\-/]{0,255}=[\\x21-\\x2b\\x2d-\\x3c\\x3e-\\x7e]{1,256}(,[a-z][a-z0-9_*\\-/]{0,255}=[\\x21-\\x2b\\x2d-\\x3c\\x3e-\\x7e]{1,256})*$", "u").test(value) ? void 0 : { path: [], issue: "must be a valid bounded W3C tracestate" })
 );
+var BaggageSchema = boundedUtf8String(47, 47).check(Schema.makeFilter((value) => /^session\.id=[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value) ? void 0 : { path: [], issue: "must be the single W3C baggage member session.id=<lowercase UUID>" }));
 var SyncCorrelationFieldsSchema = Schema.Struct({ journey_id: Schema.optional(JourneyIdSchema), traceparent: Schema.optional(TraceparentSchema), tracestate: Schema.optional(TracestateSchema) });
-var HelloCorrelationFields = { journey_id: Schema.optional(JourneyIdSchema), traceparent: Schema.optional(TraceparentSchema), tracestate: Schema.optional(TracestateSchema) };
-var ServerCorrelationFields = { ...HelloCorrelationFields };
+var ServerCorrelationFields = { journey_id: Schema.optional(JourneyIdSchema), traceparent: Schema.optional(TraceparentSchema), tracestate: Schema.optional(TracestateSchema) };
+var HelloCorrelationFields = { ...ServerCorrelationFields, baggage: Schema.optional(BaggageSchema) };
 var StateDigestSchema = Schema.String.check(Schema.makeFilter((value) => /^[0-9a-f]{64}$/u.test(value) ? void 0 : { path: [], issue: "must be a lowercase hexadecimal SHA-256 digest" }));
 var UnsignedDecimalSchema = Schema.String.check(Schema.makeFilter((value) => /^(?:0|[1-9][0-9]*)$/u.test(value) ? void 0 : { path: [], issue: "must be an unsigned decimal integer" }));
 var CommandIdSchema = boundedUtf8String(64).check(Schema.makeFilter((value) => textEncoder.encode(value).byteLength >= 16 ? void 0 : { path: [], issue: "must meet the command ID minimum byte length" }));
@@ -1479,6 +1502,7 @@ var WelcomeBase = {
   protocol: Schema.Literal(1),
   participant_id: UuidSchema,
   participant_generation: PositiveIntegerSchema,
+  participant_identity_id: Schema.optionalKey(UuidSchema),
   recovery_id: UuidSchema,
   head: ControlCursorSchema,
   entry_confirmation: Schema.optionalKey(Schema.Literal(true)),
@@ -1527,9 +1551,15 @@ var CommandIdConflictAckFrameSchema = Schema.Struct({ type: Schema.Literal("ack"
 var MediaProjectionItemSchema = Schema.Struct({ participant_id: UuidSchema, source: Schema.Union([Schema.Literal("microphone"), Schema.Literal("camera"), Schema.Literal("screen")]), enabled: Schema.Boolean, publication_id: Schema.NullOr(boundedUtf8String(256, 1)) }).check(
   Schema.makeFilter((item) => !item.enabled || item.publication_id !== null ? void 0 : { path: [], issue: "enabled requires a publication_id" })
 );
-var PresenceProjectionItemSchema = Schema.Struct({ participant_id: UuidSchema, state: Schema.Union([Schema.Literal("connected"), Schema.Literal("disconnected")]), speaking: Schema.Boolean, active_speaker: Schema.Boolean }).check(
-  Schema.makeFilter((item) => item.state !== "disconnected" || !item.speaking && !item.active_speaker ? void 0 : { path: [], issue: "disconnected presence cannot be speaking or active speaker" })
-);
+var PresenceProjectionItemSchema = Schema.Struct({
+  participant_id: UuidSchema,
+  state: Schema.Union([Schema.Literal("connected"), Schema.Literal("disconnected")]),
+  speaking: Schema.Boolean,
+  active_speaker: Schema.Boolean,
+  identity_id: Schema.optional(UuidSchema),
+  device_type: Schema.optional(Schema.Literals(["phone", "tablet", "computer"])),
+  admission_revision: Schema.optional(PositiveIntegerSchema)
+}).check(Schema.makeFilter((item) => item.state !== "disconnected" || !item.speaking && !item.active_speaker ? void 0 : { path: [], issue: "disconnected presence cannot be speaking or active speaker" }));
 var MediaProjectionSnapshotFrameSchema = Schema.Struct({
   type: Schema.Literal("projection_snapshot"),
   stream: Schema.Literal("media"),
@@ -2514,6 +2544,11 @@ var V1CommandScheduler = class {
   async acknowledge(frame) {
     const deferred = this.#commands.get(frame.command_id);
     if (!deferred) return;
+    if (isSatisfiedByInactiveParticipant(frame, deferred.frame)) {
+      const head = this.#options.controlHead();
+      await this.#finishCommand(frame.command_id, { type: "ack", command_id: frame.command_id, delivery: "duplicate", outcome: "satisfied", revision: head.revision, state_digest: head.state_digest });
+      return;
+    }
     if (frame.outcome === "rejected" || frame.outcome === "command_id_conflict") {
       await this.#finishCommand(frame.command_id, frame);
       return;
@@ -2552,15 +2587,12 @@ var V1CommandScheduler = class {
     }
   }
   async settleTerminalRecovery(frame) {
-    const satisfiedOperations = /* @__PURE__ */ new Set();
-    if (frame.reason === "episode_ended") {
-      satisfiedOperations.add("end_episode");
-      satisfiedOperations.add("participant_leave");
-    } else if (frame.reason === "participant_inactive") {
-      satisfiedOperations.add("participant_leave");
-    }
+    const satisfies = (operation) => {
+      if (frame.reason === "episode_ended") return operation === "end_episode" || operation === "participant_leave";
+      return frame.reason === "participant_inactive" && inactiveParticipantSatisfies(operation);
+    };
     for (const [commandId, deferred] of this.#commands) {
-      if (deferred.frame.type !== "operation" || !satisfiedOperations.has(deferred.frame.name)) continue;
+      if (deferred.frame.type !== "operation" || !satisfies(deferred.frame.name)) continue;
       await this.#finishCommand(commandId, {
         type: "ack",
         command_id: commandId,
@@ -2730,6 +2762,12 @@ function targetFrame(commandId, command) {
       return { type: "command", command_id: commandId, name: command.name, payload: command.payload };
   }
 }
+function inactiveParticipantSatisfies(operation) {
+  return operation === "participant_leave";
+}
+function isSatisfiedByInactiveParticipant(result, command) {
+  return result.outcome === "rejected" && result.reason === "participant_inactive" && command.type === "operation" && inactiveParticipantSatisfies(command.name);
+}
 function isTerminalLifecycleOperation(frame) {
   return frame.type === "operation" && (frame.name === "participant_leave" || frame.name === "end_episode");
 }
@@ -2988,6 +3026,7 @@ var MAX_REPLAY_EVENTS = SyncProtocolLimits.completeReplayMaxEvents;
 var MAX_REPLAY_BYTES = SyncProtocolLimits.completeReplayEncodedBytes;
 var MAX_PROJECTION_EVENT_EVIDENCE = 256;
 var CLIENT_RESTART_CLOSE_CODE = 4e3;
+var legacyHelloServers = /* @__PURE__ */ new Set();
 var DEFAULT_RECONNECT_DELAY_MS = 250;
 var MAX_RECONNECT_DELAY_MS = 5e3;
 var FAST_RECONNECT_ATTEMPTS = 8;
@@ -3016,6 +3055,7 @@ var V1SyncClient = class {
   #presence = null;
   #participantId = null;
   #participantGeneration = null;
+  #participantIdentityId;
   #entryGeneration = null;
   #recovery = null;
   #snapshotRecoveryRequested = false;
@@ -3037,6 +3077,8 @@ var V1SyncClient = class {
     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())), attempt: this.#connectAttemptCount };
   }
   #reconnectAttempt = 0;
+  /** The socket whose hello carried baggage and has not been answered by a welcome yet. */
+  #baggageHelloSocket = null;
   #episodeEndTimer;
   #heartbeatTimer;
   #missedHeartbeats = 0;
@@ -3067,7 +3109,11 @@ var V1SyncClient = class {
       isStarted: () => this.#started,
       sendIfLive: (frame) => this.#sendIfLive(frame),
       stateChanged: () => this.#emit(),
-      ackHeadIsProven: (ack) => this.#ackHeadIsProven(ack)
+      ackHeadIsProven: (ack) => this.#ackHeadIsProven(ack),
+      controlHead: () => {
+        const control = this.#requireControl();
+        return { revision: control.revision, state_digest: control.stateDigest };
+      }
     });
     this.#liveTargets = new V1LiveTargetCoordinator({
       mediaPlane: options.mediaPlane,
@@ -3136,6 +3182,7 @@ var V1SyncClient = class {
     this.#socket?.close(1e3, "client stopped");
     this.#socket = null;
     this.#phase = { phase: "stopped" };
+    this.#options.mediaPlane?.remotePublicationsChanged?.([], "unavailable");
     this.#rejectEphemeral("client_stopped");
     this.#collaborationState.disconnect("client_stopped");
     this.#localPublications = [];
@@ -3164,6 +3211,7 @@ var V1SyncClient = class {
       },
       participantId: this.#participantId,
       participantGeneration: this.#participantGeneration,
+      participantIdentityId: this.#participantIdentityId,
       control: this.#control,
       optimisticControl,
       media: copyProjection(this.#media),
@@ -3183,6 +3231,7 @@ var V1SyncClient = class {
     return () => this.#mediaPauseListeners.delete(listener);
   }
   #notifyMediaPause(event) {
+    if (event.name === "episode_ended") this.#options.mediaPlane?.remotePublicationsChanged?.([]);
     const source = event.name === "participant_microphone_stopped" ? "microphone" : event.name === "participant_camera_stopped" ? "camera" : event.name === "participant_screen_share_stopped" ? "screen" : null;
     if (source && "participant_id" in event.payload && event.payload.participant_id === this.#participantId) {
       for (const listener of this.#mediaPauseListeners) listener({ source, revision: event.revision });
@@ -3355,11 +3404,12 @@ var V1SyncClient = class {
       this.#clock().setTimeout(() => {
         if (connectionGeneration !== this.#connectionGeneration) return;
         this.#inbound = this.#inbound.then(() => {
+          const legacyHello = event.code === 1009 && this.#legacyHelloRejected(socket);
           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);
+          this.#disconnected(socket, legacyHello);
         });
       }, 0);
     };
@@ -3376,10 +3426,12 @@ var V1SyncClient = class {
       const token = await this.#options.token();
       if (socket !== this.#socket) return;
       this.#phase = { phase: "recovering" };
+      const baggage = legacyHelloServers.has(this.#options.url) ? void 0 : sessionBaggage();
       const hello = {
         type: "hello",
         protocol: 1,
         ...this.#options.traceparent ? { traceparent: this.#options.traceparent } : {},
+        ...baggage ? { baggage } : {},
         token,
         streams: {
           control: { cursor: this.#control && { revision: this.#control.revision, state_schema_version: this.#control.stateSchemaVersion, state_digest: this.#control.stateDigest } },
@@ -3389,6 +3441,7 @@ var V1SyncClient = class {
         }
       };
       const collaborationExtension = this.#collaborationState.helloExtension;
+      this.#baggageHelloSocket = baggage ? socket : null;
       if (!collaborationExtension) {
         this.#send(hello);
       } else {
@@ -3408,7 +3461,7 @@ var V1SyncClient = class {
     } catch (error) {
       if (this.#snapshotRecoveryRequested) this.#failDigestRecovery();
       else if (error instanceof V1StateDigestMismatchError) this.#recoverDigestMismatch();
-      else this.#recover("invalid_frame");
+      else this.#recover("invalid_frame", error instanceof V1ReplicaError && error.message === "invalid_frame" && this.#legacyHelloRejected(socket));
     }
   }
   async #handleFrame(frame) {
@@ -3444,6 +3497,7 @@ var V1SyncClient = class {
           const control = this.#requireControl();
           this.#send({ type: "delivery_ack", stream: "control", revision: control.revision, state_digest: control.stateDigest });
         }
+        if (this.#control?.status === "ended" || frame.name === "participant_left" && frame.payload.participant_id === this.#participantId) this.#participantIdentityId = void 0;
         if (frame.name === "participant_left" && frame.payload.participant_id === this.#participantId) {
           this.#phase = { phase: "terminal", terminalReason: frame.payload.reason === "removed" ? "participant_removed" : "participant_inactive" };
           this.#socket?.close(1e3, "participant inactive");
@@ -3529,11 +3583,13 @@ var V1SyncClient = class {
   }
   async #welcome(frame) {
     if (this.#phase.phase !== "recovering" || this.#recovery) throw new V1ReplicaError("unexpected welcome");
+    this.#baggageHelloSocket = null;
     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.#participantIdentityId = frame.mode === "terminal" ? void 0 : frame.participant_identity_id;
     this.#updateLocalMediaStates();
     if (frame.mode === "terminal") {
       await this.#commandScheduler.settleTerminalRecovery(frame);
@@ -3547,6 +3603,7 @@ var V1SyncClient = class {
       const control = await restoreV1Snapshot(frame.snapshot);
       if (!sameHead(control, frame.head)) throw new V1ReplicaError("snapshot head mismatch");
       this.#control = control;
+      if (control.status === "ended") this.#options.mediaPlane?.remotePublicationsChanged?.([]);
       this.#snapshotRevision = control.revision;
       this.#snapshotRecoveryRequested = false;
       this.#controlHeads.clear();
@@ -3592,7 +3649,7 @@ var V1SyncClient = class {
           previous.find((candidate) => mediaKey(candidate) === mediaKey(item)),
           item
         );
-      if (!this.#mediaEnded()) this.#options.mediaPlane?.remotePublicationsChanged?.();
+      if (!this.#mediaEnded()) this.#options.mediaPlane?.remotePublicationsChanged?.(this.#media?.items ?? []);
     } else {
       this.#presence = { projectionId: frame.projection_id, sequence: 0, items: frame.items.map(presenceItem) };
       this.#presenceEventEvidence.clear();
@@ -3611,7 +3668,7 @@ var V1SyncClient = class {
       rememberBoundedEvidence(this.#mediaEventEvidence, frame.sequence, frameSignature(frame), MAX_PROJECTION_EVENT_EVIDENCE);
       this.#notifyRemotePublicationResumed(previous, item);
       if (!this.#mediaEnded() && item.participantId !== this.#participantId && (previous?.enabled !== item.enabled || previous?.publicationId !== item.publicationId)) {
-        this.#options.mediaPlane?.remotePublicationsChanged?.();
+        this.#options.mediaPlane?.remotePublicationsChanged?.(this.#media?.items ?? []);
       }
     } else {
       if (this.#acceptProjectionDuplicate(this.#presence, this.#presenceEventEvidence, frame)) return;
@@ -3683,7 +3740,7 @@ var V1SyncClient = class {
     if (evidence.get(frame.sequence) !== frameSignature(frame)) throw new V1ReplicaError("conflicting or unprovable duplicate projection event");
     return true;
   }
-  #disconnected(socket) {
+  #disconnected(socket, retryNow = false) {
     if (socket !== this.#socket) return;
     this.#socket = null;
     this.#clearDial();
@@ -3694,6 +3751,7 @@ var V1SyncClient = class {
     this.#commandScheduler.disconnect();
     this.#media = null;
     this.#presence = null;
+    this.#options.mediaPlane?.remotePublicationsChanged?.([], this.#mediaEnded() ? "available" : "unavailable");
     this.#rejectRequests("disconnected_before_delivery");
     this.#collaborationState.disconnect("disconnected_before_delivery");
     if (!this.#started || this.#phase.phase === "terminal") return;
@@ -3701,6 +3759,13 @@ var V1SyncClient = class {
     this.#emit();
     if (!this.#transportAvailable) return;
     this.#clearReconnect();
+    if (retryNow) {
+      this.#reconnectTimer = this.#clock().setTimeout(() => {
+        this.#reconnectTimer = void 0;
+        this.#connect();
+      }, 0);
+      return;
+    }
     const configuredDelay = this.#options.reconnectDelayMs;
     const exponentialAttempt = configuredDelay === void 0 ? Math.max(0, this.#reconnectAttempt - FAST_RECONNECT_ATTEMPTS + 1) : this.#reconnectAttempt;
     const baseDelay = configuredDelay === 0 ? 0 : Math.min(MAX_RECONNECT_DELAY_MS, (configuredDelay ?? DEFAULT_RECONNECT_DELAY_MS) * 2 ** Math.min(exponentialAttempt, 5));
@@ -3711,11 +3776,21 @@ var V1SyncClient = class {
       this.#connect();
     }, delay);
   }
-  #recover(reason) {
+  #recover(reason, retryNow = false) {
     const socket = this.#socket;
     if (!socket) return;
     socket.close(CLIENT_RESTART_CLOSE_CODE, reason);
-    this.#disconnected(socket);
+    this.#disconnected(socket, retryNow);
+  }
+  /**
+   * A Sync that predates the session ID rejects any hello with an unknown `baggage` field before welcome. The first
+   * rejection marks that server as legacy, so the retry and every later reconnect send the hello without it.
+   */
+  #legacyHelloRejected(socket) {
+    if (this.#baggageHelloSocket !== socket) return false;
+    this.#baggageHelloSocket = null;
+    legacyHelloServers.add(this.#options.url);
+    return true;
   }
   #recoverDigestMismatch() {
     const now = this.#clock().now();
@@ -3900,7 +3975,7 @@ function mediaItem(item) {
   return { participantId: item.participant_id, source: item.source, enabled: item.enabled, publicationId: item.publication_id };
 }
 function presenceItem(item) {
-  return { participantId: item.participant_id, state: item.state, speaking: item.speaking, activeSpeaker: item.active_speaker };
+  return { participantId: item.participant_id, admissionRevision: item.admission_revision, identityId: item.identity_id, deviceType: item.device_type, state: item.state, speaking: item.speaking, activeSpeaker: item.active_speaker };
 }
 function mediaKey(item) {
   return `${item.participantId}:${item.source}`;
@@ -3928,6 +4003,8 @@ function validMediaPublication(publication) {
 }
 function entryUrl(value, generation, confirmation) {
   const url = new URL(value);
+  url.searchParams.set("participant_devices", "1");
+  url.searchParams.set("participant_device_admissions", "2");
   url.searchParams.set("entry_generation", generation === null ? "new" : String(generation));
   if (confirmation) url.searchParams.set("entry_confirmation", "1");
   return url.toString();