@atlaskit/collab-provider 21.1.3 → 21.2.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @atlaskit/collab-provider
 
+## 21.2.0
+
+### Minor Changes
+
+- [`782360c1111dc`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/782360c1111dc) -
+  Agent-edit shimmer review follow-ups (behind the default-OFF `platform_editor_agent_be_streaming`
+  experiment):
+  - Add a second shimmer phase: after the skeleton loader clears, the changed range shows a purple
+    "just edited" highlight (same colours as the editor AI "improve writing" in-editor highlight)
+    that eases in and out over its lifetime. The Rovo telepointer stays through both phases.
+  - The two phases are sized by independent experiment params: `shimmerDurationMs` (skeleton,
+    renamed from `durationMs`) and `highlightDurationMs` (highlight). `0` on either skips just that
+    phase, `0` on both shows nothing.
+  - Gate the agent-edit shimmer styles behind the experiment in both the emotion and compiled
+    `EditorContentContainer` style entries, using the no-exposure check on the hot render path.
+  - Add an `agentEditReceived` collab-provider analytics event, fired once per received transaction
+    that contains agent-authored steps, with non-PII attributes (agent ids, count, kinds,
+    agent/total step counts).
+  - Add an `agentEditShimmerNotShown` COLLAB operational analytics event for agent edits that apply
+    without the shimmer (`rebasedConcurrentEdit`, `nothingToShow`, `captureThrew`,
+    `tornDownMidAnimation`); neutral action + `reason`, non-PII attributes.
+  - Hoist the top-level block/position helpers in `agent-shimmer-ranges` to reusable module scope,
+    drop the redundant upper-bound clamp in `agent-shimmer-decorations`, and remove the empty
+    `@example` JSDoc tags added in the original PR.
+
+  `@atlaskit/editor-common` gains a new subpath export,
+  `@atlaskit/editor-common/analytics/types/agent-edit-shimmer-events`, exposing the
+  `agentEditShimmerNotShown` operational event types. Usage:
+
+  ```ts
+  import { ACTION, ACTION_SUBJECT, EVENT_TYPE } from '@atlaskit/editor-common/analytics';
+  import type { AgentEditShimmerNotShownReason } from '@atlaskit/editor-common/analytics/types/agent-edit-shimmer-events';
+
+  const reason: AgentEditShimmerNotShownReason = 'captureThrew';
+  editorAnalyticsApi?.fireAnalyticsEvent({
+  	action: ACTION.AGENT_EDIT_SHIMMER_NOT_SHOWN,
+  	actionSubject: ACTION_SUBJECT.COLLAB,
+  	eventType: EVENT_TYPE.OPERATIONAL,
+  	attributes: { reason },
+  });
+  ```
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 21.1.3
 
 ### Patch Changes

package/dist/cjs/document/document-service.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.DocumentService = void 0;
 var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
 var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
@@ -948,17 +949,15 @@ var DocumentService = exports.DocumentService = /*#__PURE__*/function () {
     }
 
     /**
-     * Detect agent-authored steps in a received batch and register
-     * each distinct agent as a local participant so it appears in the presence facepile.
+     * Detect agent-authored steps in a received batch and register each distinct agent as a local
+     * participant so it appears in the presence facepile.
      *
-     * Gated behind a default-OFF feature gate: `collab-provider` is shared platform infra (used by
-     * Jira JWM/JPD etc.), so this is a strict no-op everywhere unless the gate is explicitly enabled.
-     *
-     * Isolated in its own try/catch so a presence failure can never affect step persistence.
+     * Gated behind a default-OFF gate because `collab-provider` is shared platform infra (Jira
+     * JWM/JPD etc.), and isolated in its own try/catch so a presence failure can never affect step
+     * persistence.
      *
      * Known limitation (PoC): steps replayed via catch-up/reconnect can briefly re-surface an agent
      * whose activity is stale — a freshness guard is a follow-up.
-     * @example
      */
   }, {
     key: "maybeAddAgentPresenceFromSteps",
@@ -968,28 +967,57 @@ var DocumentService = exports.DocumentService = /*#__PURE__*/function () {
         return;
       }
       try {
+        var _this$analyticsHelper34;
         var providerIds = new Set();
+        var agentIds = new Set();
+        var agentTypes = new Set();
+        var agentStepCount = 0;
         var _iterator = _createForOfIteratorHelper(steps),
           _step;
         try {
           for (_iterator.s(); !(_step = _iterator.n()).done;) {
             var step = _step.value;
             var providerId = (0, _utils.getAgentProviderId)(step);
-            if (providerId) {
-              providerIds.add(providerId);
+            if (!providerId) {
+              continue;
+            }
+            providerIds.add(providerId);
+            agentStepCount++;
+            var _ref10 = step,
+              agentId = _ref10.agentId,
+              agentType = _ref10.agentType;
+            if (agentType) {
+              agentTypes.add(agentType);
+            }
+            if (agentId) {
+              agentIds.add((0, _utils.normalizeAgentId)(agentId));
             }
           }
+          // No agent-authored steps in this batch — nothing to register or report.
         } catch (err) {
           _iterator.e(err);
         } finally {
           _iterator.f();
         }
+        if (providerIds.size === 0) {
+          return;
+        }
+        // Anchor signal that the agent-presence logic kicked off for a received transaction. Fires
+        // once per transaction (agent edits arrive as batches, not per keystroke). Attributes are
+        // non-PII: agent kinds, actor ids, and counts — never document content.
+        (_this$analyticsHelper34 = this.analyticsHelper) === null || _this$analyticsHelper34 === void 0 || _this$analyticsHelper34.sendActionEvent(_const.EVENT_ACTION.AGENT_EDIT_RECEIVED, _const.EVENT_STATUS.SUCCESS, {
+          agentIds: (0, _toConsumableArray2.default)(agentIds),
+          agentCount: providerIds.size,
+          agentTypes: (0, _toConsumableArray2.default)(agentTypes),
+          agentStepCount: agentStepCount,
+          totalStepCount: steps.length
+        });
         providerIds.forEach(function (providerId) {
           return _this3.participantsService.upsertAIProviderParticipantLocally(providerId);
         });
       } catch (error) {
-        var _this$analyticsHelper34;
-        (_this$analyticsHelper34 = this.analyticsHelper) === null || _this$analyticsHelper34 === void 0 || _this$analyticsHelper34.sendErrorEvent(error, 'Error while adding agent presence from steps');
+        var _this$analyticsHelper35;
+        (_this$analyticsHelper35 = this.analyticsHelper) === null || _this$analyticsHelper35 === void 0 || _this$analyticsHelper35.sendErrorEvent(error, 'Error while adding agent presence from steps');
       }
     }
   }, {
@@ -1013,10 +1041,10 @@ var DocumentService = exports.DocumentService = /*#__PURE__*/function () {
      * @param root0.clientId
      * @example
      */
-    function setup(_ref10) {
-      var getState = _ref10.getState,
-        onSyncUpError = _ref10.onSyncUpError,
-        clientId = _ref10.clientId;
+    function setup(_ref11) {
+      var getState = _ref11.getState,
+        onSyncUpError = _ref11.onSyncUpError,
+        clientId = _ref11.clientId;
       this.getState = getState;
       this.onSyncUpError = onSyncUpError || noop;
       this.clientId = clientId;
@@ -1039,8 +1067,8 @@ var DocumentService = exports.DocumentService = /*#__PURE__*/function () {
       var _this$getState0;
       var state = (_this$getState0 = this.getState) === null || _this$getState0 === void 0 ? void 0 : _this$getState0.call(this);
       if (!state) {
-        var _this$analyticsHelper35;
-        (_this$analyticsHelper35 = this.analyticsHelper) === null || _this$analyticsHelper35 === void 0 || _this$analyticsHelper35.sendErrorEvent(new Error('Editor state is undefined'), 'sendStepsFromCurrentState called without state');
+        var _this$analyticsHelper36;
+        (_this$analyticsHelper36 = this.analyticsHelper) === null || _this$analyticsHelper36 === void 0 || _this$analyticsHelper36.sendErrorEvent(new Error('Editor state is undefined'), 'sendStepsFromCurrentState called without state');
         return;
       }
       this.send(null, null, state, sendAnalyticsEvent, reason);
@@ -1091,8 +1119,8 @@ var DocumentService = exports.DocumentService = /*#__PURE__*/function () {
       // to ensure that analytics events with the number of unconfirmed steps is only
       // sent once on connection (as opposed to on every step)
       if (sendAnalyticsEvent) {
-        var _this$analyticsHelper36;
-        (_this$analyticsHelper36 = this.analyticsHelper) === null || _this$analyticsHelper36 === void 0 || _this$analyticsHelper36.sendActionEvent(_const.EVENT_ACTION.HAS_UNCONFIRMED_STEPS, _const.EVENT_STATUS.INFO, {
+        var _this$analyticsHelper37;
+        (_this$analyticsHelper37 = this.analyticsHelper) === null || _this$analyticsHelper37 === void 0 || _this$analyticsHelper37.sendActionEvent(_const.EVENT_ACTION.HAS_UNCONFIRMED_STEPS, _const.EVENT_STATUS.INFO, {
           numUnconfirmedSteps: (unconfirmedSteps === null || unconfirmedSteps === void 0 ? void 0 : unconfirmedSteps.length) || 0
         });
       }
@@ -1101,12 +1129,12 @@ var DocumentService = exports.DocumentService = /*#__PURE__*/function () {
       }
       var rebased = tr === null || tr === void 0 ? void 0 : tr.getMeta('rebasedData');
       if (rebased) {
-        var _this$analyticsHelper37;
+        var _this$analyticsHelper38;
         var obfuscatedUnconfirmedSteps = this.obfuscateStepsAndState(rebased.unconfirmedSteps).obfuscatedSteps;
         var obfuscatedRemoteSteps = this.obfuscateStepsAndState(rebased.remoteSteps);
         var obfuscatedRebasedSteps = this.obfuscateStepsAndState(unconfirmedSteps).obfuscatedSteps;
         // send analtyics on unconfirmed steps
-        (_this$analyticsHelper37 = this.analyticsHelper) === null || _this$analyticsHelper37 === void 0 || _this$analyticsHelper37.sendActionEvent(_const.EVENT_ACTION.STEPS_REBASED, _const.EVENT_STATUS.INFO, {
+        (_this$analyticsHelper38 = this.analyticsHelper) === null || _this$analyticsHelper38 === void 0 || _this$analyticsHelper38.sendActionEvent(_const.EVENT_ACTION.STEPS_REBASED, _const.EVENT_STATUS.INFO, {
           obfuscatedUnconfirmedSteps: obfuscatedUnconfirmedSteps,
           obfuscatedRemoteSteps: obfuscatedRemoteSteps,
           obfuscatedRebasedSteps: obfuscatedRebasedSteps,

package/dist/cjs/helpers/const.js

@@ -50,7 +50,11 @@ var EVENT_ACTION = exports.EVENT_ACTION = /*#__PURE__*/function (EVENT_ACTION) {
   EVENT_ACTION["STEPS_REBASED"] = "stepsRebased";
   // https://data-portal.internal.atlassian.com/analytics/registry/76616
   EVENT_ACTION["POLLING_FALLBACK"] = "pollingFallback";
-  EVENT_ACTION["PROCESS_STEPS"] = "processSteps"; // https://data-portal.internal.atlassian.com/analytics/registry/85229
+  EVENT_ACTION["PROCESS_STEPS"] = "processSteps";
+  // https://data-portal.internal.atlassian.com/analytics/registry/85229
+  // Fired once per received transaction that contains agent-authored steps. Needs a data-portal
+  // analytics registry entry before the experiment is enabled broadly.
+  EVENT_ACTION["AGENT_EDIT_RECEIVED"] = "agentEditReceived";
   return EVENT_ACTION;
 }({});
 var EVENT_STATUS = exports.EVENT_STATUS = /*#__PURE__*/function (EVENT_STATUS) {

package/dist/cjs/participants/participants-service.js

@@ -133,7 +133,6 @@ var ParticipantsService = exports.ParticipantsService = /*#__PURE__*/function ()
      * presence consumer on each streamed step.
      *
      * @param providerId `agent:<aaid|type>` id of the agent
-     * @example
      */
     (0, _defineProperty2.default)(this, "upsertAIProviderParticipantLocally", function (providerId) {
       var payload = _this.buildAIProviderPresencePayload(providerId);
@@ -164,7 +163,6 @@ var ParticipantsService = exports.ParticipantsService = /*#__PURE__*/function ()
     /**
      * (Re)starts the sliding 30s inactivity timer for an agent participant. Called on every agent
      * step so the window slides forward from the agent's most recent activity.
-     * @example
      */
     (0, _defineProperty2.default)(this, "resetAgentPresenceTimer", function (sessionId) {
       var existingTimer = _this.agentPresenceTimers.get(sessionId);
@@ -178,7 +176,6 @@ var ParticipantsService = exports.ParticipantsService = /*#__PURE__*/function ()
     /**
      * Removes an inactive agent participant once its sliding window elapses and emits the `presence`
      * leave so the facepile drops it.
-     * @example
      */
     (0, _defineProperty2.default)(this, "removeAgentParticipant", function (sessionId) {
       _this.agentPresenceTimers.delete(sessionId);
@@ -194,7 +191,6 @@ var ParticipantsService = exports.ParticipantsService = /*#__PURE__*/function ()
     /**
      * Clears all pending agent presence sliding timers (on disconnect/destroy) so they don't fire
      * against cleared state.
-     * @example
      */
     (0, _defineProperty2.default)(this, "clearAgentPresenceTimers", function () {
       _this.agentPresenceTimers.forEach(function (timer) {

package/dist/cjs/version-wrapper.js

@@ -5,7 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.version = exports.nextMajorVersion = exports.name = void 0;
 var name = exports.name = "@atlaskit/collab-provider";
-var version = exports.version = "21.1.2";
+var version = exports.version = "21.1.3";
 var nextMajorVersion = exports.nextMajorVersion = function nextMajorVersion() {
   return [Number(version.split('.')[0]) + 1, 0, 0].join('.');
 };

package/dist/es2019/document/document-service.js

@@ -9,7 +9,7 @@ import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 import { ACK_MAX_TRY, EVENT_ACTION, EVENT_STATUS, CatchupEventReason } from '../helpers/const';
 import { MEASURE_NAME, startMeasure, stopMeasure } from '../analytics/performance';
 import { INTERNAL_ERROR_CODE } from '../errors/internal-errors';
-import { createLogger, getAgentProviderId, getDocAdfWithObfuscationFromJSON, getObfuscatedSteps, getStepUGCFreeDetails, sleep } from '../helpers/utils';
+import { createLogger, getAgentProviderId, getDocAdfWithObfuscationFromJSON, getObfuscatedSteps, getStepUGCFreeDetails, normalizeAgentId, sleep } from '../helpers/utils';
 import { MAX_STEP_REJECTED_ERROR, MAX_STEP_REJECTED_ERROR_AGGRESSIVE } from '../provider';
 import { CommitStepService } from '../provider/commit-step';
 import { CantSyncUpError, UpdateDocumentError } from '../errors/custom-errors';
@@ -827,34 +827,62 @@ export class DocumentService {
   }
 
   /**
-   * Detect agent-authored steps in a received batch and register
-   * each distinct agent as a local participant so it appears in the presence facepile.
+   * Detect agent-authored steps in a received batch and register each distinct agent as a local
+   * participant so it appears in the presence facepile.
    *
-   * Gated behind a default-OFF feature gate: `collab-provider` is shared platform infra (used by
-   * Jira JWM/JPD etc.), so this is a strict no-op everywhere unless the gate is explicitly enabled.
-   *
-   * Isolated in its own try/catch so a presence failure can never affect step persistence.
+   * Gated behind a default-OFF gate because `collab-provider` is shared platform infra (Jira
+   * JWM/JPD etc.), and isolated in its own try/catch so a presence failure can never affect step
+   * persistence.
    *
    * Known limitation (PoC): steps replayed via catch-up/reconnect can briefly re-surface an agent
    * whose activity is stale — a freshness guard is a follow-up.
-   * @example
    */
   maybeAddAgentPresenceFromSteps(steps) {
     if (!expValEquals('platform_editor_agent_be_streaming', 'isEnabled', true)) {
       return;
     }
     try {
+      var _this$analyticsHelper34;
       const providerIds = new Set();
+      const agentIds = new Set();
+      const agentTypes = new Set();
+      let agentStepCount = 0;
       for (const step of steps) {
         const providerId = getAgentProviderId(step);
-        if (providerId) {
-          providerIds.add(providerId);
+        if (!providerId) {
+          continue;
+        }
+        providerIds.add(providerId);
+        agentStepCount++;
+        const {
+          agentId,
+          agentType
+        } = step;
+        if (agentType) {
+          agentTypes.add(agentType);
         }
+        if (agentId) {
+          agentIds.add(normalizeAgentId(agentId));
+        }
+      }
+      // No agent-authored steps in this batch — nothing to register or report.
+      if (providerIds.size === 0) {
+        return;
       }
+      // Anchor signal that the agent-presence logic kicked off for a received transaction. Fires
+      // once per transaction (agent edits arrive as batches, not per keystroke). Attributes are
+      // non-PII: agent kinds, actor ids, and counts — never document content.
+      (_this$analyticsHelper34 = this.analyticsHelper) === null || _this$analyticsHelper34 === void 0 ? void 0 : _this$analyticsHelper34.sendActionEvent(EVENT_ACTION.AGENT_EDIT_RECEIVED, EVENT_STATUS.SUCCESS, {
+        agentIds: [...agentIds],
+        agentCount: providerIds.size,
+        agentTypes: [...agentTypes],
+        agentStepCount,
+        totalStepCount: steps.length
+      });
       providerIds.forEach(providerId => this.participantsService.upsertAIProviderParticipantLocally(providerId));
     } catch (error) {
-      var _this$analyticsHelper34;
-      (_this$analyticsHelper34 = this.analyticsHelper) === null || _this$analyticsHelper34 === void 0 ? void 0 : _this$analyticsHelper34.sendErrorEvent(error, 'Error while adding agent presence from steps');
+      var _this$analyticsHelper35;
+      (_this$analyticsHelper35 = this.analyticsHelper) === null || _this$analyticsHelper35 === void 0 ? void 0 : _this$analyticsHelper35.sendErrorEvent(error, 'Error while adding agent presence from steps');
     }
   }
   /**
@@ -897,8 +925,8 @@ export class DocumentService {
     var _this$getState0;
     const state = (_this$getState0 = this.getState) === null || _this$getState0 === void 0 ? void 0 : _this$getState0.call(this);
     if (!state) {
-      var _this$analyticsHelper35;
-      (_this$analyticsHelper35 = this.analyticsHelper) === null || _this$analyticsHelper35 === void 0 ? void 0 : _this$analyticsHelper35.sendErrorEvent(new Error('Editor state is undefined'), 'sendStepsFromCurrentState called without state');
+      var _this$analyticsHelper36;
+      (_this$analyticsHelper36 = this.analyticsHelper) === null || _this$analyticsHelper36 === void 0 ? void 0 : _this$analyticsHelper36.sendErrorEvent(new Error('Editor state is undefined'), 'sendStepsFromCurrentState called without state');
       return;
     }
     this.send(null, null, state, sendAnalyticsEvent, reason);
@@ -944,8 +972,8 @@ export class DocumentService {
     // to ensure that analytics events with the number of unconfirmed steps is only
     // sent once on connection (as opposed to on every step)
     if (sendAnalyticsEvent) {
-      var _this$analyticsHelper36;
-      (_this$analyticsHelper36 = this.analyticsHelper) === null || _this$analyticsHelper36 === void 0 ? void 0 : _this$analyticsHelper36.sendActionEvent(EVENT_ACTION.HAS_UNCONFIRMED_STEPS, EVENT_STATUS.INFO, {
+      var _this$analyticsHelper37;
+      (_this$analyticsHelper37 = this.analyticsHelper) === null || _this$analyticsHelper37 === void 0 ? void 0 : _this$analyticsHelper37.sendActionEvent(EVENT_ACTION.HAS_UNCONFIRMED_STEPS, EVENT_STATUS.INFO, {
         numUnconfirmedSteps: (unconfirmedSteps === null || unconfirmedSteps === void 0 ? void 0 : unconfirmedSteps.length) || 0
       });
     }
@@ -954,12 +982,12 @@ export class DocumentService {
     }
     const rebased = tr === null || tr === void 0 ? void 0 : tr.getMeta('rebasedData');
     if (rebased) {
-      var _this$analyticsHelper37;
+      var _this$analyticsHelper38;
       const obfuscatedUnconfirmedSteps = this.obfuscateStepsAndState(rebased.unconfirmedSteps).obfuscatedSteps;
       const obfuscatedRemoteSteps = this.obfuscateStepsAndState(rebased.remoteSteps);
       const obfuscatedRebasedSteps = this.obfuscateStepsAndState(unconfirmedSteps).obfuscatedSteps;
       // send analtyics on unconfirmed steps
-      (_this$analyticsHelper37 = this.analyticsHelper) === null || _this$analyticsHelper37 === void 0 ? void 0 : _this$analyticsHelper37.sendActionEvent(EVENT_ACTION.STEPS_REBASED, EVENT_STATUS.INFO, {
+      (_this$analyticsHelper38 = this.analyticsHelper) === null || _this$analyticsHelper38 === void 0 ? void 0 : _this$analyticsHelper38.sendActionEvent(EVENT_ACTION.STEPS_REBASED, EVENT_STATUS.INFO, {
         obfuscatedUnconfirmedSteps,
         obfuscatedRemoteSteps,
         obfuscatedRebasedSteps,

package/dist/es2019/helpers/const.js

@@ -44,7 +44,11 @@ export let EVENT_ACTION = /*#__PURE__*/function (EVENT_ACTION) {
   EVENT_ACTION["STEPS_REBASED"] = "stepsRebased";
   // https://data-portal.internal.atlassian.com/analytics/registry/76616
   EVENT_ACTION["POLLING_FALLBACK"] = "pollingFallback";
-  EVENT_ACTION["PROCESS_STEPS"] = "processSteps"; // https://data-portal.internal.atlassian.com/analytics/registry/85229
+  EVENT_ACTION["PROCESS_STEPS"] = "processSteps";
+  // https://data-portal.internal.atlassian.com/analytics/registry/85229
+  // Fired once per received transaction that contains agent-authored steps. Needs a data-portal
+  // analytics registry entry before the experiment is enabled broadly.
+  EVENT_ACTION["AGENT_EDIT_RECEIVED"] = "agentEditReceived";
   return EVENT_ACTION;
 }({});
 export let EVENT_STATUS = /*#__PURE__*/function (EVENT_STATUS) {

package/dist/es2019/participants/participants-service.js

@@ -118,7 +118,6 @@ export class ParticipantsService {
      * presence consumer on each streamed step.
      *
      * @param providerId `agent:<aaid|type>` id of the agent
-     * @example
      */
     _defineProperty(this, "upsertAIProviderParticipantLocally", providerId => {
       const payload = this.buildAIProviderPresencePayload(providerId);
@@ -152,7 +151,6 @@ export class ParticipantsService {
     /**
      * (Re)starts the sliding 30s inactivity timer for an agent participant. Called on every agent
      * step so the window slides forward from the agent's most recent activity.
-     * @example
      */
     _defineProperty(this, "resetAgentPresenceTimer", sessionId => {
       const existingTimer = this.agentPresenceTimers.get(sessionId);
@@ -164,7 +162,6 @@ export class ParticipantsService {
     /**
      * Removes an inactive agent participant once its sliding window elapses and emits the `presence`
      * leave so the facepile drops it.
-     * @example
      */
     _defineProperty(this, "removeAgentParticipant", sessionId => {
       this.agentPresenceTimers.delete(sessionId);
@@ -180,7 +177,6 @@ export class ParticipantsService {
     /**
      * Clears all pending agent presence sliding timers (on disconnect/destroy) so they don't fire
      * against cleared state.
-     * @example
      */
     _defineProperty(this, "clearAgentPresenceTimers", () => {
       this.agentPresenceTimers.forEach(timer => clearTimeout(timer));

package/dist/es2019/version-wrapper.js

@@ -1,5 +1,5 @@
 export const name = "@atlaskit/collab-provider";
-export const version = "21.1.2";
+export const version = "21.1.3";
 export const nextMajorVersion = () => {
   return [Number(version.split('.')[0]) + 1, 0, 0].join('.');
 };

package/dist/esm/document/document-service.js

@@ -1,3 +1,4 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
 import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
 import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
 import _createClass from "@babel/runtime/helpers/createClass";
@@ -18,7 +19,7 @@ import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 import { ACK_MAX_TRY, EVENT_ACTION, EVENT_STATUS, CatchupEventReason } from '../helpers/const';
 import { MEASURE_NAME, startMeasure, stopMeasure } from '../analytics/performance';
 import { INTERNAL_ERROR_CODE } from '../errors/internal-errors';
-import { createLogger, getAgentProviderId, getDocAdfWithObfuscationFromJSON, getObfuscatedSteps, getStepUGCFreeDetails, sleep } from '../helpers/utils';
+import { createLogger, getAgentProviderId, getDocAdfWithObfuscationFromJSON, getObfuscatedSteps, getStepUGCFreeDetails, normalizeAgentId, sleep } from '../helpers/utils';
 import { MAX_STEP_REJECTED_ERROR, MAX_STEP_REJECTED_ERROR_AGGRESSIVE } from '../provider';
 import { CommitStepService } from '../provider/commit-step';
 import { CantSyncUpError, UpdateDocumentError } from '../errors/custom-errors';
@@ -942,17 +943,15 @@ export var DocumentService = /*#__PURE__*/function () {
     }
 
     /**
-     * Detect agent-authored steps in a received batch and register
-     * each distinct agent as a local participant so it appears in the presence facepile.
+     * Detect agent-authored steps in a received batch and register each distinct agent as a local
+     * participant so it appears in the presence facepile.
      *
-     * Gated behind a default-OFF feature gate: `collab-provider` is shared platform infra (used by
-     * Jira JWM/JPD etc.), so this is a strict no-op everywhere unless the gate is explicitly enabled.
-     *
-     * Isolated in its own try/catch so a presence failure can never affect step persistence.
+     * Gated behind a default-OFF gate because `collab-provider` is shared platform infra (Jira
+     * JWM/JPD etc.), and isolated in its own try/catch so a presence failure can never affect step
+     * persistence.
      *
      * Known limitation (PoC): steps replayed via catch-up/reconnect can briefly re-surface an agent
      * whose activity is stale — a freshness guard is a follow-up.
-     * @example
      */
   }, {
     key: "maybeAddAgentPresenceFromSteps",
@@ -962,28 +961,57 @@ export var DocumentService = /*#__PURE__*/function () {
         return;
       }
       try {
+        var _this$analyticsHelper34;
         var providerIds = new Set();
+        var agentIds = new Set();
+        var agentTypes = new Set();
+        var agentStepCount = 0;
         var _iterator = _createForOfIteratorHelper(steps),
           _step;
         try {
           for (_iterator.s(); !(_step = _iterator.n()).done;) {
             var step = _step.value;
             var providerId = getAgentProviderId(step);
-            if (providerId) {
-              providerIds.add(providerId);
+            if (!providerId) {
+              continue;
+            }
+            providerIds.add(providerId);
+            agentStepCount++;
+            var _ref10 = step,
+              agentId = _ref10.agentId,
+              agentType = _ref10.agentType;
+            if (agentType) {
+              agentTypes.add(agentType);
+            }
+            if (agentId) {
+              agentIds.add(normalizeAgentId(agentId));
             }
           }
+          // No agent-authored steps in this batch — nothing to register or report.
         } catch (err) {
           _iterator.e(err);
         } finally {
           _iterator.f();
         }
+        if (providerIds.size === 0) {
+          return;
+        }
+        // Anchor signal that the agent-presence logic kicked off for a received transaction. Fires
+        // once per transaction (agent edits arrive as batches, not per keystroke). Attributes are
+        // non-PII: agent kinds, actor ids, and counts — never document content.
+        (_this$analyticsHelper34 = this.analyticsHelper) === null || _this$analyticsHelper34 === void 0 || _this$analyticsHelper34.sendActionEvent(EVENT_ACTION.AGENT_EDIT_RECEIVED, EVENT_STATUS.SUCCESS, {
+          agentIds: _toConsumableArray(agentIds),
+          agentCount: providerIds.size,
+          agentTypes: _toConsumableArray(agentTypes),
+          agentStepCount: agentStepCount,
+          totalStepCount: steps.length
+        });
         providerIds.forEach(function (providerId) {
           return _this3.participantsService.upsertAIProviderParticipantLocally(providerId);
         });
       } catch (error) {
-        var _this$analyticsHelper34;
-        (_this$analyticsHelper34 = this.analyticsHelper) === null || _this$analyticsHelper34 === void 0 || _this$analyticsHelper34.sendErrorEvent(error, 'Error while adding agent presence from steps');
+        var _this$analyticsHelper35;
+        (_this$analyticsHelper35 = this.analyticsHelper) === null || _this$analyticsHelper35 === void 0 || _this$analyticsHelper35.sendErrorEvent(error, 'Error while adding agent presence from steps');
       }
     }
   }, {
@@ -1007,10 +1035,10 @@ export var DocumentService = /*#__PURE__*/function () {
      * @param root0.clientId
      * @example
      */
-    function setup(_ref10) {
-      var getState = _ref10.getState,
-        onSyncUpError = _ref10.onSyncUpError,
-        clientId = _ref10.clientId;
+    function setup(_ref11) {
+      var getState = _ref11.getState,
+        onSyncUpError = _ref11.onSyncUpError,
+        clientId = _ref11.clientId;
       this.getState = getState;
       this.onSyncUpError = onSyncUpError || noop;
       this.clientId = clientId;
@@ -1033,8 +1061,8 @@ export var DocumentService = /*#__PURE__*/function () {
       var _this$getState0;
       var state = (_this$getState0 = this.getState) === null || _this$getState0 === void 0 ? void 0 : _this$getState0.call(this);
       if (!state) {
-        var _this$analyticsHelper35;
-        (_this$analyticsHelper35 = this.analyticsHelper) === null || _this$analyticsHelper35 === void 0 || _this$analyticsHelper35.sendErrorEvent(new Error('Editor state is undefined'), 'sendStepsFromCurrentState called without state');
+        var _this$analyticsHelper36;
+        (_this$analyticsHelper36 = this.analyticsHelper) === null || _this$analyticsHelper36 === void 0 || _this$analyticsHelper36.sendErrorEvent(new Error('Editor state is undefined'), 'sendStepsFromCurrentState called without state');
         return;
       }
       this.send(null, null, state, sendAnalyticsEvent, reason);
@@ -1085,8 +1113,8 @@ export var DocumentService = /*#__PURE__*/function () {
       // to ensure that analytics events with the number of unconfirmed steps is only
       // sent once on connection (as opposed to on every step)
       if (sendAnalyticsEvent) {
-        var _this$analyticsHelper36;
-        (_this$analyticsHelper36 = this.analyticsHelper) === null || _this$analyticsHelper36 === void 0 || _this$analyticsHelper36.sendActionEvent(EVENT_ACTION.HAS_UNCONFIRMED_STEPS, EVENT_STATUS.INFO, {
+        var _this$analyticsHelper37;
+        (_this$analyticsHelper37 = this.analyticsHelper) === null || _this$analyticsHelper37 === void 0 || _this$analyticsHelper37.sendActionEvent(EVENT_ACTION.HAS_UNCONFIRMED_STEPS, EVENT_STATUS.INFO, {
           numUnconfirmedSteps: (unconfirmedSteps === null || unconfirmedSteps === void 0 ? void 0 : unconfirmedSteps.length) || 0
         });
       }
@@ -1095,12 +1123,12 @@ export var DocumentService = /*#__PURE__*/function () {
       }
       var rebased = tr === null || tr === void 0 ? void 0 : tr.getMeta('rebasedData');
       if (rebased) {
-        var _this$analyticsHelper37;
+        var _this$analyticsHelper38;
         var obfuscatedUnconfirmedSteps = this.obfuscateStepsAndState(rebased.unconfirmedSteps).obfuscatedSteps;
         var obfuscatedRemoteSteps = this.obfuscateStepsAndState(rebased.remoteSteps);
         var obfuscatedRebasedSteps = this.obfuscateStepsAndState(unconfirmedSteps).obfuscatedSteps;
         // send analtyics on unconfirmed steps
-        (_this$analyticsHelper37 = this.analyticsHelper) === null || _this$analyticsHelper37 === void 0 || _this$analyticsHelper37.sendActionEvent(EVENT_ACTION.STEPS_REBASED, EVENT_STATUS.INFO, {
+        (_this$analyticsHelper38 = this.analyticsHelper) === null || _this$analyticsHelper38 === void 0 || _this$analyticsHelper38.sendActionEvent(EVENT_ACTION.STEPS_REBASED, EVENT_STATUS.INFO, {
           obfuscatedUnconfirmedSteps: obfuscatedUnconfirmedSteps,
           obfuscatedRemoteSteps: obfuscatedRemoteSteps,
           obfuscatedRebasedSteps: obfuscatedRebasedSteps,

package/dist/esm/helpers/const.js

@@ -44,7 +44,11 @@ export var EVENT_ACTION = /*#__PURE__*/function (EVENT_ACTION) {
   EVENT_ACTION["STEPS_REBASED"] = "stepsRebased";
   // https://data-portal.internal.atlassian.com/analytics/registry/76616
   EVENT_ACTION["POLLING_FALLBACK"] = "pollingFallback";
-  EVENT_ACTION["PROCESS_STEPS"] = "processSteps"; // https://data-portal.internal.atlassian.com/analytics/registry/85229
+  EVENT_ACTION["PROCESS_STEPS"] = "processSteps";
+  // https://data-portal.internal.atlassian.com/analytics/registry/85229
+  // Fired once per received transaction that contains agent-authored steps. Needs a data-portal
+  // analytics registry entry before the experiment is enabled broadly.
+  EVENT_ACTION["AGENT_EDIT_RECEIVED"] = "agentEditReceived";
   return EVENT_ACTION;
 }({});
 export var EVENT_STATUS = /*#__PURE__*/function (EVENT_STATUS) {

package/dist/esm/participants/participants-service.js

@@ -126,7 +126,6 @@ export var ParticipantsService = /*#__PURE__*/function () {
      * presence consumer on each streamed step.
      *
      * @param providerId `agent:<aaid|type>` id of the agent
-     * @example
      */
     _defineProperty(this, "upsertAIProviderParticipantLocally", function (providerId) {
       var payload = _this.buildAIProviderPresencePayload(providerId);
@@ -157,7 +156,6 @@ export var ParticipantsService = /*#__PURE__*/function () {
     /**
      * (Re)starts the sliding 30s inactivity timer for an agent participant. Called on every agent
      * step so the window slides forward from the agent's most recent activity.
-     * @example
      */
     _defineProperty(this, "resetAgentPresenceTimer", function (sessionId) {
       var existingTimer = _this.agentPresenceTimers.get(sessionId);
@@ -171,7 +169,6 @@ export var ParticipantsService = /*#__PURE__*/function () {
     /**
      * Removes an inactive agent participant once its sliding window elapses and emits the `presence`
      * leave so the facepile drops it.
-     * @example
      */
     _defineProperty(this, "removeAgentParticipant", function (sessionId) {
       _this.agentPresenceTimers.delete(sessionId);
@@ -187,7 +184,6 @@ export var ParticipantsService = /*#__PURE__*/function () {
     /**
      * Clears all pending agent presence sliding timers (on disconnect/destroy) so they don't fire
      * against cleared state.
-     * @example
      */
     _defineProperty(this, "clearAgentPresenceTimers", function () {
       _this.agentPresenceTimers.forEach(function (timer) {

package/dist/esm/version-wrapper.js

@@ -1,5 +1,5 @@
 export var name = "@atlaskit/collab-provider";
-export var version = "21.1.2";
+export var version = "21.1.3";
 export var nextMajorVersion = function nextMajorVersion() {
   return [Number(version.split('.')[0]) + 1, 0, 0].join('.');
 };

package/dist/types/document/document-service.d.ts

@@ -95,17 +95,15 @@ export declare class DocumentService implements DocumentServiceInterface {
     private isStepsFromNewClientIdForSameUserId;
     private processSteps;
     /**
-     * Detect agent-authored steps in a received batch and register
-     * each distinct agent as a local participant so it appears in the presence facepile.
+     * Detect agent-authored steps in a received batch and register each distinct agent as a local
+     * participant so it appears in the presence facepile.
      *
-     * Gated behind a default-OFF feature gate: `collab-provider` is shared platform infra (used by
-     * Jira JWM/JPD etc.), so this is a strict no-op everywhere unless the gate is explicitly enabled.
-     *
-     * Isolated in its own try/catch so a presence failure can never affect step persistence.
+     * Gated behind a default-OFF gate because `collab-provider` is shared platform infra (Jira
+     * JWM/JPD etc.), and isolated in its own try/catch so a presence failure can never affect step
+     * persistence.
      *
      * Known limitation (PoC): steps replayed via catch-up/reconnect can briefly re-surface an agent
      * whose activity is stale — a freshness guard is a follow-up.
-     * @example
      */
     private maybeAddAgentPresenceFromSteps;
     getUnconfirmedStepsOrigins: () => readonly Transaction[] | undefined;

package/dist/types/helpers/const.d.ts

@@ -23,7 +23,8 @@ export declare enum EVENT_ACTION {
     OUT_OF_SYNC = "outOfSync",// https://data-portal.internal.atlassian.com/analytics/registry/74993
     STEPS_REBASED = "stepsRebased",// https://data-portal.internal.atlassian.com/analytics/registry/76616
     POLLING_FALLBACK = "pollingFallback",
-    PROCESS_STEPS = "processSteps"
+    PROCESS_STEPS = "processSteps",// https://data-portal.internal.atlassian.com/analytics/registry/85229
+    AGENT_EDIT_RECEIVED = "agentEditReceived"
 }
 export declare enum EVENT_STATUS {
     SUCCESS = "SUCCESS",
@@ -311,7 +312,18 @@ type ProcessStepsAnalyticsEvent = {
     } & BaseActionAnalyticsEventAttributes;
     eventAction: EVENT_ACTION.PROCESS_STEPS;
 };
-export type ActionAnalyticsEvent = AddStepsSuccessAnalyticsEvent | AddStepsFailureAnalyticsEvent | ReInitDocFailAnalyticsEvent | ReInitDocSuccessAnalyticsEvent | ConnectionSuccessAnalyticsEvent | ConnectionFailureAnalyticsEvent | CatchUpSuccessAnalyticsEvent | CatchUpFailureAnalyticsEvent | DocumentInitSuccessAnalyticsEvent | UpdateParticipantsSuccessAnalyticsEvent | CommitUnconfirmedStepsSuccessAnalyticsEvent | CommitUnconfirmedStepsFailureAnalyticsEvent | PublishPageSuccessAnalyticsEvent | PublishPageFailureAnalyticsEvent | GetCurrentStateSuccessAnalyticsEvent | GetCurrentStateFailureAnalyticsEvent | InvalidateTokenAnalyticsEvent | SendStepsRetryAnalyticsEvent | CatchupAfterMaxSendStepsRetryAnalyticsEvent | CatchUpDroppedStepsEvent | WebsocketMessageVolumeMetricEvent | ProviderInitializedAnalyticsEvent | ProviderSetupAnalyticsEvent | ProviderHasUnconfirmedStepsAnalyticsEvent | UpdateDocumentAnalyticsEvent | ReconnectionAnalyticsEvent | OutOfSyncAnalyticsEvent | StepsRebasedAnalyticsEvent | PollingFallbackAnalyticsEvent | ProcessStepsAnalyticsEvent;
+type AgentEditReceivedAnalyticsEvent = {
+    attributes: {
+        agentCount: number;
+        agentIds: string[];
+        agentStepCount: number;
+        agentTypes: string[];
+        eventStatus: EVENT_STATUS.SUCCESS;
+        totalStepCount: number;
+    } & BaseActionAnalyticsEventAttributes;
+    eventAction: EVENT_ACTION.AGENT_EDIT_RECEIVED;
+};
+export type ActionAnalyticsEvent = AddStepsSuccessAnalyticsEvent | AddStepsFailureAnalyticsEvent | ReInitDocFailAnalyticsEvent | ReInitDocSuccessAnalyticsEvent | ConnectionSuccessAnalyticsEvent | ConnectionFailureAnalyticsEvent | CatchUpSuccessAnalyticsEvent | CatchUpFailureAnalyticsEvent | DocumentInitSuccessAnalyticsEvent | UpdateParticipantsSuccessAnalyticsEvent | CommitUnconfirmedStepsSuccessAnalyticsEvent | CommitUnconfirmedStepsFailureAnalyticsEvent | PublishPageSuccessAnalyticsEvent | PublishPageFailureAnalyticsEvent | GetCurrentStateSuccessAnalyticsEvent | GetCurrentStateFailureAnalyticsEvent | InvalidateTokenAnalyticsEvent | SendStepsRetryAnalyticsEvent | CatchupAfterMaxSendStepsRetryAnalyticsEvent | CatchUpDroppedStepsEvent | WebsocketMessageVolumeMetricEvent | ProviderInitializedAnalyticsEvent | ProviderSetupAnalyticsEvent | ProviderHasUnconfirmedStepsAnalyticsEvent | UpdateDocumentAnalyticsEvent | ReconnectionAnalyticsEvent | OutOfSyncAnalyticsEvent | StepsRebasedAnalyticsEvent | PollingFallbackAnalyticsEvent | ProcessStepsAnalyticsEvent | AgentEditReceivedAnalyticsEvent;
 export declare const ACK_MAX_TRY = 60;
 export declare const CONFLUENCE = "confluence";
 /** Enumerable for attaching a reason to catchup (v2) call(s) */

package/dist/types/participants/participants-service.d.ts

@@ -82,25 +82,21 @@ export declare class ParticipantsService {
      * presence consumer on each streamed step.
      *
      * @param providerId `agent:<aaid|type>` id of the agent
-     * @example
      */
     upsertAIProviderParticipantLocally: (providerId: string) => void;
     /**
      * (Re)starts the sliding 30s inactivity timer for an agent participant. Called on every agent
      * step so the window slides forward from the agent's most recent activity.
-     * @example
      */
     private resetAgentPresenceTimer;
     /**
      * Removes an inactive agent participant once its sliding window elapses and emits the `presence`
      * leave so the facepile drops it.
-     * @example
      */
     private removeAgentParticipant;
     /**
      * Clears all pending agent presence sliding timers (on disconnect/destroy) so they don't fire
      * against cleared state.
-     * @example
      */
     private clearAgentPresenceTimers;
     private hasPresenceActivityChanged;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/collab-provider",
-	"version": "21.1.3",
+	"version": "21.2.0",
 	"description": "A provider for collaborative editing.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -71,6 +71,6 @@
 		}
 	},
 	"peerDependencies": {
-		"@atlaskit/editor-common": "^116.41.0"
+		"@atlaskit/editor-common": "^116.42.0"
 	}
 }