fix(agent-builder): deduplicate grouped attachment refs in RoundAttachmentReferences

When bulk-adding alerts the chat route chunked them into multiple
AttachmentInput batches, causing one "Attachment added:" line per batch
instead of one per logical group.

- Add group_id and description to Attachment/VersionedAttachment/AttachmentInput
  types and propagate through server validation, state manager, and chat route
- Stamp group_id and description on group items at the flattenAttachments
  boundary (the sole serialisation point), not at call sites
- Deduplicate by group_id in RoundAttachmentReferences; actor-filter runs
  before the seenGroupIds slot is consumed so a non-matching actor ref
  cannot silently block a matching one from rendering
- Fix description falsy-check in AttachmentStateManager (use !== undefined)
- Add tests for RoundAttachmentReferences dedup logic (incl. actor-filter
  regression), flattenAttachments group stamping, and buildOptimisticAttachments
  group_id/description passthrough

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jonwalstedt

x-pack/platform/packages/shared/agent-builder/agent-builder-common/attachments/attachments.ts

@@ -20,6 +20,8 @@ export interface Attachment<
   type: Type;
   /** data bound to the attachment */
   data: DataType;
+  /** Human-readable description of the attachment */
+  description?: string;
   /** should the attachment be hidden from the user - e.g. for screen context */
   hidden?: boolean;
   /**
@@ -28,6 +30,13 @@ export interface Attachment<
    * Undefined for by-value attachments.
    */
   origin?: string;
+  /**
+   * Stable identifier for the logical group this attachment belongs to.
+   * Attachments sharing the same group_id were submitted together as a single
+   * logical entity (e.g. multiple alert batches from one bulk-add action).
+   * Undefined for standalone attachments.
+   */
+  group_id?: string;
 }
 
 /**

x-pack/platform/packages/shared/agent-builder/agent-builder-common/attachments/versioned_attachment.ts

@@ -50,6 +50,13 @@ export interface VersionedAttachment<
   readonly?: boolean;
   /** The client-provided ID if this attachment was created with one (e.g., via flyout configuration) */
   client_id?: string;
+  /**
+   * Stable identifier for the logical group this attachment belongs to.
+   * Attachments sharing the same group_id were submitted together as a single
+   * logical entity (e.g. multiple alert batches from one bulk-add action).
+   * Undefined for standalone attachments.
+   */
+  group_id?: string;
   /**
    * Origin/reference info for attachments created from external sources.
    * For saved-object-backed types this is the saved object ID.
@@ -153,6 +160,16 @@ export interface AttachmentInput<
   hidden?: boolean;
   /** Whether the attachment should be read-only */
   readonly?: boolean;
+  /**
+   * Stable identifier for the logical group this attachment belongs to.
+   * Attachments sharing the same group_id were submitted together as a single
+   * logical entity (e.g. multiple alert batches from one bulk-add action).
+   * Undefined for standalone attachments.
+   *
+   * When this input is part of an AttachmentGroup, flattenAttachments always
+   * stamps this field with the group's id, overriding any value set here.
+   */
+  group_id?: string;
 }
 
 // Zod schemas for validation
@@ -198,6 +215,7 @@ export const versionedAttachmentSchema = z.object({
   client_id: z.string().optional(),
   origin: z.string().optional(),
   origin_snapshot_at: z.string().optional(),
+  group_id: z.string().optional(),
 });
 
 export const attachmentInputSchema = z.object({
@@ -208,6 +226,7 @@ export const attachmentInputSchema = z.object({
   description: z.string().optional(),
   hidden: z.boolean().optional(),
   readonly: z.boolean().optional(),
+  group_id: z.string().optional(),
 });
 
 /**

x-pack/platform/packages/shared/agent-builder/agent-builder-server/attachments/attachment_state_manager.ts

@@ -349,13 +349,14 @@ class AttachmentStateManagerImpl implements AttachmentStateManager {
       versions: [version],
       current_version: 1,
       active: true,
-      ...(input.description && { description: input.description }),
+      ...(input.description !== undefined && { description: input.description }),
       ...(input.hidden !== undefined && { hidden: input.hidden }),
       readonly: input.readonly ?? this.getDefaultReadonly(input.type),
       ...(input.origin !== undefined && { origin: input.origin }),
       // When created with origin (by-reference), record snapshot time for isStale comparison.
       // By-value attachments leave this undefined.
       ...(input.origin !== undefined && { origin_snapshot_at: now }),
+      ...(input.group_id !== undefined && { group_id: input.group_id }),
     };
 
     this.attachments.set(id, attachment);

x-pack/platform/plugins/shared/agent_builder/public/application/components/conversations/conversation_rounds/round_attachment_references.test.tsx

@@ -0,0 +1,168 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import type {
+  VersionedAttachment,
+  Attachment,
+  AttachmentVersionRef,
+} from '@kbn/agent-builder-common/attachments';
+import {
+  ATTACHMENT_REF_ACTOR,
+  ATTACHMENT_REF_OPERATION,
+} from '@kbn/agent-builder-common/attachments';
+import { RoundAttachmentReferences } from './round_attachment_references';
+
+const makeVersioned = (
+  id: string,
+  description?: string,
+  group_id?: string
+): VersionedAttachment => ({
+  id,
+  type: 'text',
+  versions: [{ version: 1, data: {}, created_at: '2024-01-01T00:00:00Z', content_hash: 'x' }],
+  current_version: 1,
+  active: true,
+  ...(description !== undefined ? { description } : {}),
+  ...(group_id !== undefined ? { group_id } : {}),
+});
+
+const makeRef = (
+  id: string,
+  actor: (typeof ATTACHMENT_REF_ACTOR)[keyof typeof ATTACHMENT_REF_ACTOR] = ATTACHMENT_REF_ACTOR.user,
+  operation?: (typeof ATTACHMENT_REF_OPERATION)[keyof typeof ATTACHMENT_REF_OPERATION]
+): AttachmentVersionRef => ({
+  attachment_id: id,
+  version: 1,
+  actor,
+  operation,
+});
+
+const makeFallback = (id: string, description?: string, group_id?: string): Attachment => ({
+  id,
+  type: 'text',
+  data: {},
+  ...(description !== undefined ? { description } : {}),
+  ...(group_id !== undefined ? { group_id } : {}),
+});
+
+describe('RoundAttachmentReferences', () => {
+  it('renders nothing when there are no refs or attachments', () => {
+    const { container } = render(<RoundAttachmentReferences />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders nothing when refs are empty', () => {
+    const { container } = render(
+      <RoundAttachmentReferences
+        attachmentRefs={[]}
+        conversationAttachments={[makeVersioned('a', 'Label A')]}
+      />
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders one line per resolved attachment', () => {
+    render(
+      <RoundAttachmentReferences
+        attachmentRefs={[makeRef('a'), makeRef('b')]}
+        conversationAttachments={[makeVersioned('a', 'First'), makeVersioned('b', 'Second')]}
+      />
+    );
+
+    expect(screen.getByText(/First/)).toBeInTheDocument();
+    expect(screen.getByText(/Second/)).toBeInTheDocument();
+  });
+
+  it('deduplicates by group_id — renders only one line for a group', () => {
+    render(
+      <RoundAttachmentReferences
+        attachmentRefs={[makeRef('a1'), makeRef('a2')]}
+        conversationAttachments={[
+          makeVersioned('a1', '27 Alerts', 'group-1'),
+          makeVersioned('a2', '27 Alerts', 'group-1'),
+        ]}
+      />
+    );
+
+    const lines = screen.getAllByText(/27 Alerts/);
+    expect(lines).toHaveLength(1);
+  });
+
+  it('actor filter applied before group dedup — matching actor ref renders even when preceded by non-matching actor ref for the same group', () => {
+    // Regression for: system ref consumed group slot before actor filter, so user ref was never rendered.
+    render(
+      <RoundAttachmentReferences
+        attachmentRefs={[
+          makeRef('a1', ATTACHMENT_REF_ACTOR.system), // non-matching — must NOT consume slot
+          makeRef('a2', ATTACHMENT_REF_ACTOR.user), // matching — must render
+        ]}
+        conversationAttachments={[
+          makeVersioned('a1', '27 Alerts', 'group-1'),
+          makeVersioned('a2', '27 Alerts', 'group-1'),
+        ]}
+        actorFilter={[ATTACHMENT_REF_ACTOR.user]}
+      />
+    );
+
+    expect(screen.getByText(/27 Alerts/)).toBeInTheDocument();
+  });
+
+  it('renders nothing when all refs are filtered out by actorFilter', () => {
+    const { container } = render(
+      <RoundAttachmentReferences
+        attachmentRefs={[makeRef('a', ATTACHMENT_REF_ACTOR.system)]}
+        conversationAttachments={[makeVersioned('a', 'Label')]}
+        actorFilter={[ATTACHMENT_REF_ACTOR.user]}
+      />
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('skips hidden attachments', () => {
+    const hidden: VersionedAttachment = { ...makeVersioned('h', 'Hidden Label'), hidden: true };
+    const { container } = render(
+      <RoundAttachmentReferences
+        attachmentRefs={[makeRef('h')]}
+        conversationAttachments={[hidden]}
+      />
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('skips refs with operation=read', () => {
+    const { container } = render(
+      <RoundAttachmentReferences
+        attachmentRefs={[makeRef('a', ATTACHMENT_REF_ACTOR.user, ATTACHMENT_REF_OPERATION.read)]}
+        conversationAttachments={[makeVersioned('a', 'Label')]}
+      />
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('uses fallbackAttachments when no attachmentRefs are provided', () => {
+    render(
+      <RoundAttachmentReferences fallbackAttachments={[makeFallback('f1', 'Fallback Label')]} />
+    );
+    expect(screen.getByText(/Fallback Label/)).toBeInTheDocument();
+  });
+
+  it('deduplicates fallback attachments by group_id', () => {
+    render(
+      <RoundAttachmentReferences
+        fallbackAttachments={[
+          makeFallback('f1', '27 Alerts', 'group-1'),
+          makeFallback('f2', '27 Alerts', 'group-1'),
+        ]}
+      />
+    );
+
+    const lines = screen.getAllByText(/27 Alerts/);
+    expect(lines).toHaveLength(1);
+  });
+});

x-pack/platform/plugins/shared/agent_builder/public/application/components/conversations/conversation_rounds/round_attachment_references.tsx

@@ -88,6 +88,8 @@ const buildFallbackVersionedAttachments = (attachments: Attachment[]): Versioned
     current_version: 1,
     active: true,
     hidden: attachment.hidden,
+    ...(attachment.group_id !== undefined ? { group_id: attachment.group_id } : {}),
+    ...(attachment.description !== undefined ? { description: attachment.description } : {}),
   }));
 };
 
@@ -134,6 +136,7 @@ export const RoundAttachmentReferences: React.FC<RoundAttachmentReferencesProps>
     }
 
     const resolved: ResolvedReference[] = [];
+    const seenGroupIds = new Set<string>();
     for (const ref of refs) {
       const attachment = attachmentMap.get(ref.attachment_id);
       if (!attachment) {
@@ -150,6 +153,13 @@ export const RoundAttachmentReferences: React.FC<RoundAttachmentReferencesProps>
         continue;
       }
 
+      if (attachment.group_id) {
+        if (seenGroupIds.has(attachment.group_id)) {
+          continue;
+        }
+        seenGroupIds.add(attachment.group_id);
+      }
+
       resolved.push({
         attachment,
         version: ref.version,

x-pack/platform/plugins/shared/agent_builder/public/application/context/conversation/flatten_attachments.test.ts

@@ -36,7 +36,11 @@ describe('flattenAttachments', () => {
     const item1 = input('security.alerts', 'i1');
     const item2 = input('security.alerts', 'i2');
     const g = group('g1', [item1, item2]);
-    expect(flattenAttachments([g])).toEqual([item1, item2]);
+    const result = flattenAttachments([g]);
+    expect(result).toEqual([
+      { ...item1, group_id: 'g1', description: '2 Alerts' },
+      { ...item2, group_id: 'g1', description: '2 Alerts' },
+    ]);
   });
 
   it('flattens a mixed list — groups expand in place, individuals pass through', () => {
@@ -45,7 +49,11 @@ describe('flattenAttachments', () => {
     const item2 = input('security.alerts', 'a2');
     const g = group('g1', [item1, item2]);
     const result = flattenAttachments([solo, g]);
-    expect(result).toEqual([solo, item1, item2]);
+    expect(result).toEqual([
+      solo,
+      { ...item1, group_id: 'g1', description: '2 Alerts' },
+      { ...item2, group_id: 'g1', description: '2 Alerts' },
+    ]);
   });
 
   it('preserves order across multiple groups and individuals', () => {
@@ -59,7 +67,13 @@ describe('flattenAttachments', () => {
       b,
       group('g2', g2Items),
     ];
-    expect(flattenAttachments(attachments)).toEqual([a, ...g1Items, b, ...g2Items]);
+    expect(flattenAttachments(attachments)).toEqual([
+      a,
+      { ...g1Items[0], group_id: 'g1', description: '2 Alerts' },
+      { ...g1Items[1], group_id: 'g1', description: '2 Alerts' },
+      b,
+      { ...g2Items[0], group_id: 'g2', description: '1 Alerts' },
+    ]);
   });
 
   it('handles a group with no items', () => {
@@ -73,4 +87,26 @@ describe('flattenAttachments', () => {
     flattenAttachments(items);
     expect(JSON.stringify(items)).toBe(snapshot);
   });
+
+  it('does not stamp group_id or description on individual attachments', () => {
+    const a = input('text', 'a');
+    const result = flattenAttachments([a]);
+
+    expect(result[0]).not.toHaveProperty('group_id');
+    expect(result[0]).not.toHaveProperty('description');
+  });
+
+  it('preserves an item description when it already has one, does not overwrite with group label', () => {
+    const item: AttachmentInput = {
+      type: 'security.alerts',
+      id: 'i1',
+      data: {},
+      description: 'custom',
+    };
+    const g = group('g1', [item]);
+    const result = flattenAttachments([g]);
+
+    expect(result[0].description).toBe('custom');
+    expect(result[0].group_id).toBe('g1');
+  });
 });

x-pack/platform/plugins/shared/agent_builder/public/application/context/conversation/flatten_attachments.ts

@@ -15,6 +15,19 @@ import { isAttachmentGroup } from '@kbn/agent-builder-common/attachments';
  * Flattens ConversationAttachment[] to AttachmentInput[] for serialization.
  * AttachmentGroups are expanded to their constituent items; individual attachments pass through unchanged.
  * This is the only place groups are dissolved — the server always receives AttachmentInput[].
+ *
+ * Group items are stamped with group_id and description at this boundary:
+ *   - group_id is always set to the group's id, overriding any pre-existing value on the item.
+ *     An item pre-setting group_id would be a caller error — group identity belongs to the group.
+ *   - description falls back to the group's label if the item does not supply its own.
  */
 export const flattenAttachments = (attachments: ConversationAttachment[]): AttachmentInput[] =>
-  attachments.flatMap((a) => (isAttachmentGroup(a) ? a.items : [a]));
+  attachments.flatMap((a) =>
+    isAttachmentGroup(a)
+      ? a.items.map((item) => ({
+          ...item,
+          group_id: a.id,
+          description: item.description ?? a.label,
+        }))
+      : [a]
+  );