@atlaskit/rovo-agent-components 4.5.1 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @atlaskit/rovo-agent-components
 
+## 4.6.0
+
+### Minor Changes
+
+- [`2f13c6822ad55`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/2f13c6822ad55) -
+  [TREX-1413] Add presentational `AgentResponseHat` (above assistant messages) and `AgentInputHat`
+  (above the chat prompt input) components for per-turn agent attribution. Both render under the
+  `rovo_chat_agent_identity_ui` feature gate; data wiring (selected agent, dismiss callback) is
+  intentionally not yet connected and will land with TREX-1410/TREX-1411.
+
+  Also:
+  - Adds shared `deriveAgentIdentity` helper in `@atlaskit/rovo-agent-components` (subpath:
+    `ui/agent-identity/derive-agent-identity`) that centralises specialist-vs-default detection,
+    visible/accessible name derivation, and Forge prop gating via `rovo_agent_support_a2a_avatar`.
+    Both hats consume this helper to avoid drift.
+  - Extends `Message.author` in `@atlassian/conversation-assistant-service-api` with
+    `external_config_reference`, `identity_account_id`, `creator_type`, and `icon` so
+    `AgentResponseHat` receives the right inputs once TREX-1411 wires live data. Also marks the
+    existing `named_id` field as `@deprecated` in favour of `external_config_reference` for OOTB
+    avatar lookup.
+  - Adds storybook examples (`73-agent-response`, `74-chat-prompt-input`) for visual validation.
+
 ## 4.5.1
 
 ### Patch Changes

package/dist/cjs/ui/agent-identity/derive-agent-identity.js

@@ -0,0 +1,69 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.deriveAgentIdentity = deriveAgentIdentity;
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
+var _isAgentCreatorType = require("../../common/utils/is-agent-creator-type");
+var _isForgeAgent = require("../../common/utils/is-forge-agent");
+/**
+ * Shared identity-derivation helper used by AgentInputHat (above the prompt
+ * input) and AgentResponseHat (above an assistant message). Both components
+ * need to translate raw agent identity props into the inputs that AgentAvatar
+ * expects, plus an accessible/visible name pair, with the same fallback
+ * semantics. Centralising the logic here avoids drift between the two hats —
+ * historically every change to one needed a paired change to the other.
+ */
+
+/** Raw identity input — typically a subset of `Agent` or `message.author`. */
+
+/** Derived props ready to forward to AgentAvatar + the visible name slot. */
+
+/**
+ * Derive `AgentAvatar` inputs and visible/accessible labels from raw identity.
+ *
+ * Behaviour:
+ *  - Specialist path (`agentId` is a non-empty string): visible text is the
+ *    supplied `agentName`, omitted entirely if absent (no "Rovo" text next to
+ *    a specialist avatar). Accessible label falls back to the agent id so the
+ *    avatar is never announced as "Rovo".
+ *  - Default Rovo path (no `agentId`): visible and accessible labels are the
+ *    localized default name (typically "Rovo").
+ *  - Forge identity props are gated internally via `rovo_agent_support_a2a_avatar`
+ *    so callers don't have to.
+ */
+function deriveAgentIdentity(_ref) {
+  var agentId = _ref.agentId,
+    agentName = _ref.agentName,
+    agentNamedId = _ref.agentNamedId,
+    agentIdentityAccountId = _ref.agentIdentityAccountId,
+    imageUrl = _ref.imageUrl,
+    creatorType = _ref.creatorType,
+    isForgeAgentOverride = _ref.isForgeAgent,
+    forgeAgentIconUrl = _ref.forgeAgentIconUrl,
+    defaultName = _ref.defaultName;
+  var trimmedAgentId = typeof agentId === 'string' ? agentId.trim() : undefined;
+  var specialistAgentId = trimmedAgentId && trimmedAgentId.length > 0 ? trimmedAgentId : undefined;
+  var trimmedAgentName = agentName === null || agentName === void 0 ? void 0 : agentName.trim();
+  var visibleName = specialistAgentId ? trimmedAgentName || undefined : defaultName;
+  var accessibleName = specialistAgentId ? trimmedAgentName || specialistAgentId : defaultName;
+  var a2aGateOn = (0, _platformFeatureFlags.fg)('rovo_agent_support_a2a_avatar');
+
+  // Prefer the explicit override; otherwise validate creatorType via the
+  // type guard so the call site doesn't need an unsafe cast.
+  var isForgeAgent = isForgeAgentOverride !== undefined ? isForgeAgentOverride : creatorType && (0, _isAgentCreatorType.isAgentCreatorType)(creatorType) ? (0, _isForgeAgent.isForgeAgentByCreatorType)(creatorType) : undefined;
+  return {
+    specialistAgentId: specialistAgentId,
+    visibleName: visibleName,
+    accessibleName: accessibleName,
+    avatarProps: {
+      agentId: specialistAgentId,
+      agentNamedId: agentNamedId,
+      agentIdentityAccountId: agentIdentityAccountId,
+      imageUrl: imageUrl,
+      isForgeAgent: a2aGateOn ? isForgeAgent : undefined,
+      forgeAgentIconUrl: a2aGateOn ? forgeAgentIconUrl : undefined
+    }
+  };
+}

package/dist/es2019/ui/agent-identity/derive-agent-identity.js

@@ -0,0 +1,65 @@
+/**
+ * Shared identity-derivation helper used by AgentInputHat (above the prompt
+ * input) and AgentResponseHat (above an assistant message). Both components
+ * need to translate raw agent identity props into the inputs that AgentAvatar
+ * expects, plus an accessible/visible name pair, with the same fallback
+ * semantics. Centralising the logic here avoids drift between the two hats —
+ * historically every change to one needed a paired change to the other.
+ */
+
+import { fg } from '@atlaskit/platform-feature-flags';
+import { isAgentCreatorType } from '../../common/utils/is-agent-creator-type';
+import { isForgeAgentByCreatorType } from '../../common/utils/is-forge-agent';
+
+/** Raw identity input — typically a subset of `Agent` or `message.author`. */
+
+/** Derived props ready to forward to AgentAvatar + the visible name slot. */
+
+/**
+ * Derive `AgentAvatar` inputs and visible/accessible labels from raw identity.
+ *
+ * Behaviour:
+ *  - Specialist path (`agentId` is a non-empty string): visible text is the
+ *    supplied `agentName`, omitted entirely if absent (no "Rovo" text next to
+ *    a specialist avatar). Accessible label falls back to the agent id so the
+ *    avatar is never announced as "Rovo".
+ *  - Default Rovo path (no `agentId`): visible and accessible labels are the
+ *    localized default name (typically "Rovo").
+ *  - Forge identity props are gated internally via `rovo_agent_support_a2a_avatar`
+ *    so callers don't have to.
+ */
+export function deriveAgentIdentity({
+  agentId,
+  agentName,
+  agentNamedId,
+  agentIdentityAccountId,
+  imageUrl,
+  creatorType,
+  isForgeAgent: isForgeAgentOverride,
+  forgeAgentIconUrl,
+  defaultName
+}) {
+  const trimmedAgentId = typeof agentId === 'string' ? agentId.trim() : undefined;
+  const specialistAgentId = trimmedAgentId && trimmedAgentId.length > 0 ? trimmedAgentId : undefined;
+  const trimmedAgentName = agentName === null || agentName === void 0 ? void 0 : agentName.trim();
+  const visibleName = specialistAgentId ? trimmedAgentName || undefined : defaultName;
+  const accessibleName = specialistAgentId ? trimmedAgentName || specialistAgentId : defaultName;
+  const a2aGateOn = fg('rovo_agent_support_a2a_avatar');
+
+  // Prefer the explicit override; otherwise validate creatorType via the
+  // type guard so the call site doesn't need an unsafe cast.
+  const isForgeAgent = isForgeAgentOverride !== undefined ? isForgeAgentOverride : creatorType && isAgentCreatorType(creatorType) ? isForgeAgentByCreatorType(creatorType) : undefined;
+  return {
+    specialistAgentId,
+    visibleName,
+    accessibleName,
+    avatarProps: {
+      agentId: specialistAgentId,
+      agentNamedId,
+      agentIdentityAccountId,
+      imageUrl,
+      isForgeAgent: a2aGateOn ? isForgeAgent : undefined,
+      forgeAgentIconUrl: a2aGateOn ? forgeAgentIconUrl : undefined
+    }
+  };
+}

package/dist/esm/ui/agent-identity/derive-agent-identity.js

@@ -0,0 +1,64 @@
+/**
+ * Shared identity-derivation helper used by AgentInputHat (above the prompt
+ * input) and AgentResponseHat (above an assistant message). Both components
+ * need to translate raw agent identity props into the inputs that AgentAvatar
+ * expects, plus an accessible/visible name pair, with the same fallback
+ * semantics. Centralising the logic here avoids drift between the two hats —
+ * historically every change to one needed a paired change to the other.
+ */
+
+import { fg } from '@atlaskit/platform-feature-flags';
+import { isAgentCreatorType } from '../../common/utils/is-agent-creator-type';
+import { isForgeAgentByCreatorType } from '../../common/utils/is-forge-agent';
+
+/** Raw identity input — typically a subset of `Agent` or `message.author`. */
+
+/** Derived props ready to forward to AgentAvatar + the visible name slot. */
+
+/**
+ * Derive `AgentAvatar` inputs and visible/accessible labels from raw identity.
+ *
+ * Behaviour:
+ *  - Specialist path (`agentId` is a non-empty string): visible text is the
+ *    supplied `agentName`, omitted entirely if absent (no "Rovo" text next to
+ *    a specialist avatar). Accessible label falls back to the agent id so the
+ *    avatar is never announced as "Rovo".
+ *  - Default Rovo path (no `agentId`): visible and accessible labels are the
+ *    localized default name (typically "Rovo").
+ *  - Forge identity props are gated internally via `rovo_agent_support_a2a_avatar`
+ *    so callers don't have to.
+ */
+export function deriveAgentIdentity(_ref) {
+  var agentId = _ref.agentId,
+    agentName = _ref.agentName,
+    agentNamedId = _ref.agentNamedId,
+    agentIdentityAccountId = _ref.agentIdentityAccountId,
+    imageUrl = _ref.imageUrl,
+    creatorType = _ref.creatorType,
+    isForgeAgentOverride = _ref.isForgeAgent,
+    forgeAgentIconUrl = _ref.forgeAgentIconUrl,
+    defaultName = _ref.defaultName;
+  var trimmedAgentId = typeof agentId === 'string' ? agentId.trim() : undefined;
+  var specialistAgentId = trimmedAgentId && trimmedAgentId.length > 0 ? trimmedAgentId : undefined;
+  var trimmedAgentName = agentName === null || agentName === void 0 ? void 0 : agentName.trim();
+  var visibleName = specialistAgentId ? trimmedAgentName || undefined : defaultName;
+  var accessibleName = specialistAgentId ? trimmedAgentName || specialistAgentId : defaultName;
+  var a2aGateOn = fg('rovo_agent_support_a2a_avatar');
+
+  // Prefer the explicit override; otherwise validate creatorType via the
+  // type guard so the call site doesn't need an unsafe cast.
+  var isForgeAgent = isForgeAgentOverride !== undefined ? isForgeAgentOverride : creatorType && isAgentCreatorType(creatorType) ? isForgeAgentByCreatorType(creatorType) : undefined;
+  return {
+    specialistAgentId: specialistAgentId,
+    visibleName: visibleName,
+    accessibleName: accessibleName,
+    avatarProps: {
+      agentId: specialistAgentId,
+      agentNamedId: agentNamedId,
+      agentIdentityAccountId: agentIdentityAccountId,
+      imageUrl: imageUrl,
+      isForgeAgent: a2aGateOn ? isForgeAgent : undefined,
+      forgeAgentIconUrl: a2aGateOn ? forgeAgentIconUrl : undefined
+    }
+  };
+}

package/dist/types/ui/agent-identity/derive-agent-identity.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared identity-derivation helper used by AgentInputHat (above the prompt
+ * input) and AgentResponseHat (above an assistant message). Both components
+ * need to translate raw agent identity props into the inputs that AgentAvatar
+ * expects, plus an accessible/visible name pair, with the same fallback
+ * semantics. Centralising the logic here avoids drift between the two hats —
+ * historically every change to one needed a paired change to the other.
+ */
+/** Raw identity input — typically a subset of `Agent` or `message.author`. */
+export type AgentIdentityInput = {
+    /** Specialist agent id. Falsy/empty/whitespace = default Rovo turn. */
+    agentId?: string;
+    agentName?: string;
+    agentNamedId?: string;
+    agentIdentityAccountId?: string;
+    imageUrl?: string;
+    /**
+     * Raw backend `creator_type` (e.g. "FORGE", "REMOTE_A2A"). Validated via
+     * `isAgentCreatorType` internally so callers don't need an unsafe cast.
+     * Ignored when `isForgeAgent` is provided explicitly.
+     */
+    creatorType?: string;
+    /** Pre-resolved Forge/REMOTE_A2A flag. Takes precedence over `creatorType`. */
+    isForgeAgent?: boolean;
+    forgeAgentIconUrl?: string;
+    /** Localized fallback used when the default Rovo path renders text. */
+    defaultName: string;
+};
+/** Derived props ready to forward to AgentAvatar + the visible name slot. */
+export type DerivedAgentIdentity = {
+    /** Non-empty agentId when on the specialist path; undefined otherwise. */
+    specialistAgentId: string | undefined;
+    /** Visible label to render in the hat's text slot, or undefined to omit. */
+    visibleName: string | undefined;
+    /** Always-non-empty accessible label for the avatar. */
+    accessibleName: string;
+    /** Props to spread onto AgentAvatar — only meaningful on the specialist path. */
+    avatarProps: {
+        agentId: string | undefined;
+        agentNamedId: string | undefined;
+        agentIdentityAccountId: string | undefined;
+        imageUrl: string | undefined;
+        isForgeAgent: boolean | undefined;
+        forgeAgentIconUrl: string | undefined;
+    };
+};
+/**
+ * Derive `AgentAvatar` inputs and visible/accessible labels from raw identity.
+ *
+ * Behaviour:
+ *  - Specialist path (`agentId` is a non-empty string): visible text is the
+ *    supplied `agentName`, omitted entirely if absent (no "Rovo" text next to
+ *    a specialist avatar). Accessible label falls back to the agent id so the
+ *    avatar is never announced as "Rovo".
+ *  - Default Rovo path (no `agentId`): visible and accessible labels are the
+ *    localized default name (typically "Rovo").
+ *  - Forge identity props are gated internally via `rovo_agent_support_a2a_avatar`
+ *    so callers don't have to.
+ */
+export declare function deriveAgentIdentity({ agentId, agentName, agentNamedId, agentIdentityAccountId, imageUrl, creatorType, isForgeAgent: isForgeAgentOverride, forgeAgentIconUrl, defaultName, }: AgentIdentityInput): DerivedAgentIdentity;

package/dist/types-ts4.5/ui/agent-identity/derive-agent-identity.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared identity-derivation helper used by AgentInputHat (above the prompt
+ * input) and AgentResponseHat (above an assistant message). Both components
+ * need to translate raw agent identity props into the inputs that AgentAvatar
+ * expects, plus an accessible/visible name pair, with the same fallback
+ * semantics. Centralising the logic here avoids drift between the two hats —
+ * historically every change to one needed a paired change to the other.
+ */
+/** Raw identity input — typically a subset of `Agent` or `message.author`. */
+export type AgentIdentityInput = {
+    /** Specialist agent id. Falsy/empty/whitespace = default Rovo turn. */
+    agentId?: string;
+    agentName?: string;
+    agentNamedId?: string;
+    agentIdentityAccountId?: string;
+    imageUrl?: string;
+    /**
+     * Raw backend `creator_type` (e.g. "FORGE", "REMOTE_A2A"). Validated via
+     * `isAgentCreatorType` internally so callers don't need an unsafe cast.
+     * Ignored when `isForgeAgent` is provided explicitly.
+     */
+    creatorType?: string;
+    /** Pre-resolved Forge/REMOTE_A2A flag. Takes precedence over `creatorType`. */
+    isForgeAgent?: boolean;
+    forgeAgentIconUrl?: string;
+    /** Localized fallback used when the default Rovo path renders text. */
+    defaultName: string;
+};
+/** Derived props ready to forward to AgentAvatar + the visible name slot. */
+export type DerivedAgentIdentity = {
+    /** Non-empty agentId when on the specialist path; undefined otherwise. */
+    specialistAgentId: string | undefined;
+    /** Visible label to render in the hat's text slot, or undefined to omit. */
+    visibleName: string | undefined;
+    /** Always-non-empty accessible label for the avatar. */
+    accessibleName: string;
+    /** Props to spread onto AgentAvatar — only meaningful on the specialist path. */
+    avatarProps: {
+        agentId: string | undefined;
+        agentNamedId: string | undefined;
+        agentIdentityAccountId: string | undefined;
+        imageUrl: string | undefined;
+        isForgeAgent: boolean | undefined;
+        forgeAgentIconUrl: string | undefined;
+    };
+};
+/**
+ * Derive `AgentAvatar` inputs and visible/accessible labels from raw identity.
+ *
+ * Behaviour:
+ *  - Specialist path (`agentId` is a non-empty string): visible text is the
+ *    supplied `agentName`, omitted entirely if absent (no "Rovo" text next to
+ *    a specialist avatar). Accessible label falls back to the agent id so the
+ *    avatar is never announced as "Rovo".
+ *  - Default Rovo path (no `agentId`): visible and accessible labels are the
+ *    localized default name (typically "Rovo").
+ *  - Forge identity props are gated internally via `rovo_agent_support_a2a_avatar`
+ *    so callers don't have to.
+ */
+export declare function deriveAgentIdentity({ agentId, agentName, agentNamedId, agentIdentityAccountId, imageUrl, creatorType, isForgeAgent: isForgeAgentOverride, forgeAgentIconUrl, defaultName, }: AgentIdentityInput): DerivedAgentIdentity;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/rovo-agent-components",
-	"version": "4.5.1",
+	"version": "4.6.0",
 	"description": "This package host public components related to rovo agents, the components here are needed for other public atlaskit packages",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-monorepo",
 	"atlassian": {

package/ui/agent-identity/derive-agent-identity/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/rovo-agent-components/ui/agent-identity/derive-agent-identity",
+  "main": "../../../dist/cjs/ui/agent-identity/derive-agent-identity.js",
+  "module": "../../../dist/esm/ui/agent-identity/derive-agent-identity.js",
+  "module:es2019": "../../../dist/es2019/ui/agent-identity/derive-agent-identity.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../../../dist/types/ui/agent-identity/derive-agent-identity.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../../../dist/types-ts4.5/ui/agent-identity/derive-agent-identity.d.ts"
+      ]
+    }
+  }
+}