[Dashboards in Chat] Sidebar dashboard app integration - enable automatic dashboard attachments in new conversations (elastic#263987)

## Summary

This PR removes `onAttachmentMount` and replaces it with
conversation-level APIs that are a better fit for dashboard/chat
integration.

`onAttachmentMount` worked for persisted attachments that were already
rendered in a conversation, but it turned out to be too narrow for the
dashboard app use case. In particular, dashboard app sync also needs to
work for draft attachments. If a user opens a new dashboard with a new
conversation, the dashboard can be attached as a draft attachment before
it exists as a persisted conversation attachment. In that flow, manual
dashboard changes still need to update the attachment, but
`onAttachmentMount` never fires because there is nothing persisted yet
(attachment has not been mounted).

The old model also pushed dashboard integration toward per-attachment
subscriptions, while the actual behavior we need is conversation-level.
Dashboard sync needs awareness of the full set of conversation
attachments so it can decide which dashboard attachment should own sync,
rather than wiring each attachment independently. It also needs to
preserve some state across conversation switches, such as the current
draft attachment id so we don't create a new attachment every time we
switch to another conversation (because we cannot remove the old one).

To support that, this PR introduces `subscribeToConversationChanges`,
which exposes the active conversation id and attachments whenever the
bound conversation changes, and `chatOpen$`, which lets dashboard
integration activate only when chat is actually open. Together, these
APIs let dashboard integration subscribe once for the active
dashboard/chat session instead of once per mounted attachment.

## What Changed

- removed `onAttachmentMount` from the attachment UI contract
- added `subscribeToConversationChanges` to the `agent_builder` public
start contract
- added `chatOpen$` to the `agent_builder` public start contract
- added internal conversation change notifications for both
embedded/sidebar chat (we don't use full-page chat here, but I think we
will soon) and routed/full-page chat
- updated dashboard integration to activate only when both the dashboard
app and chat are running
- refactored dashboard integration to use conversation-level attachment
state instead of per-attachment mount lifecycle
- added draft attachment id management so draft dashboard attachments
keep a stable id until they are persisted
- extracted shared dashboard state defaults into helpers
- updated and expanded tests around plugin APIs, conversation change
notifications, and dashboard integration flows

## Dashboard Integration Improvements

This change makes dashboard/chat synchronization work for both draft and
persisted dashboard attachments.


It also allows dashboard integration to:
- add and update dashboard attachments for new conversations (!New
attachments can only be created for new conversations!)
- keep manual dashboard edits synced even before the attachment is
persisted
- preserve the current draft attachment id across conversation switches
(so we don't create a new attachment, since we have no ability to remove
the old one)

## Why This Is Better

A conversation-level subscription is a better abstraction for dashboard
integration than an attachment-mount lifecycle hook.

It gives integration code visibility into all attachments for the active
conversation, lets it maintain state across conversation changes, and
covers the important case where dashboard sync must begin before any
persisted attachment exists. It also keeps integration inactive unless
both chat and dashboard are actually present, which reduces unnecessary
subscriptions and avoids running sync logic outside the intended flow.

## Test Plan

- [ ] Open a new dashboard with a new conversation and verify manual
dashboard edits keep updating the draft dashboard attachment
- [ ] Switch between conversations and verify the current draft
attachment id is preserved until the draft is persisted
- [ ] Open a dashboard with an existing conversation and verify manual
dashboard edits keep updating the draft dashboard attachment. When
submitting, new attachment correctly is added to the conversation
- [ ] Complete a round that creates the draft attachment and verify
subsequent new drafts use a new id
- [ ] Save and save as from the dashboard app and verify attachment
origin is updated correctly
- [ ] Verify dashboard integration only becomes active when both the
dashboard app and chat are running

demo:


https://github.com/user-attachments/assets/3c8563db-ca3e-46a8-8f7d-6ff14b5a7c53

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: macroscopeapp[bot] <170038800+macroscopeapp[bot]@users.noreply.github.com>

Author: 3 people

packages/kbn-optimizer/limits.yml

@@ -31,7 +31,7 @@ pageLoadAssetSize:
   crossClusterReplication: 12662
   customIntegrations: 11715
   dashboard: 20000
-  dashboardAgent: 5135
+  dashboardAgent: 8000
   dashboardMarkdown: 6151
   data: 496646
   dataQuality: 11469

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

@@ -154,14 +154,6 @@ export interface AttachmentUIDefinition<TAttachment extends UnknownAttachment =
    * Buttons will appear alongside or below the rendered content.
    */
   getActionButtons?: (params: GetActionButtonsParams<TAttachment>) => ActionButton[];
-  /**
-   * Optional lifecycle hook called when an attachment is first rendered in the conversation.
-   * Called once per attachment (not per version). Use for setting up subscriptions or
-   * other side effects that should persist across version renders.
-   *
-   * @returns Optional cleanup function called when the attachment is removed from the conversation.
-   */
-  onAttachmentMount?: (params: AttachmentLifecycleParams<TAttachment>) => void | (() => void);
 }
 
 /**

x-pack/platform/packages/shared/agent-builder/agent-builder-browser/events/contract.ts

@@ -6,8 +6,32 @@
  */
 
 import type { Observable } from 'rxjs';
+import type { Conversation } from '@kbn/agent-builder-common';
 import type { BrowserChatEvent } from './events';
 
+export interface ActiveConversation {
+  /**
+   * Active conversation id, if one already exists.
+   * Undefined means we're currently in a new conversation.
+   */
+  id?: string;
+  /**
+   * The currently bound conversation, when it has been successfully fetched.
+   * Undefined while the conversation is new, still loading, or failed to load.
+   */
+  conversation?: Conversation;
+}
+
+export interface ChatUiEventsContract {
+  /**
+   * Emits the currently active conversation binding for both the embeddable sidebar and
+   * the full-page routed chat. Emits `null` when no chat surface is currently bound.
+   *
+   * Backed by a `BehaviorSubject`: new subscribers receive the current value immediately.
+   */
+  activeConversation$: Observable<ActiveConversation | null>;
+}
+
 /**
  * Public-facing contract for AgentBuilder's events service.
  */
@@ -16,4 +40,8 @@ export interface EventsServiceStartContract {
    * (hot) observable of all chat events.
    */
   chat$: Observable<BrowserChatEvent>;
+  /**
+   * Chat UI-shell state observables.
+   */
+  ui: ChatUiEventsContract;
 }

x-pack/platform/packages/shared/agent-builder/agent-builder-browser/events/index.ts

@@ -6,4 +6,8 @@
  */
 
 export type { BrowserChatEvent } from './events';
-export type { EventsServiceStartContract } from './contract';
+export type {
+  EventsServiceStartContract,
+  ChatUiEventsContract,
+  ActiveConversation,
+} from './contract';

x-pack/platform/packages/shared/agent-builder/agent-builder-browser/index.ts

@@ -16,7 +16,12 @@ export type {
 } from './tools';
 export type { AgentsServiceStartContract } from './agents';
 export type { AttachmentUIDefinition, AttachmentServiceStartContract } from './attachments';
-export type { EventsServiceStartContract, BrowserChatEvent } from './events';
+export type {
+  EventsServiceStartContract,
+  ChatUiEventsContract,
+  BrowserChatEvent,
+  ActiveConversation,
+} from './events';
 export { WorkflowComboBox } from './workflow_combo_box';
 export type { WorkflowComboBoxProps, WorkflowComboBoxOption } from './workflow_combo_box';
 export { AgentBuilderAnnouncementModal } from './announcement_modal/agent_builder_announcement_modal';

x-pack/platform/plugins/shared/agent_builder/CONTRIBUTOR_GUIDE.md

@@ -775,62 +775,135 @@ const myAttachmentType: AttachmentTypeDefinition<'my_type', MyContent> = {
 
 Refer to [`AttachmentStaleCheckResult`](https://github.com/elastic/kibana/blob/main/x-pack/platform/packages/shared/agent-builder/agent-builder-common/attachments/stale_check.ts) for the result types returned by the stale check API.
 
-#### Attachment lifecycle hook: onAttachmentMount
+## Chat integration and pending attachments
 
-The `onAttachmentMount` lifecycle hook allows you to run side effects when an attachment is mounted to a conversation, and clean them up when the attachment is removed.
+Plugins can integrate with the active chat surface (the embeddable sidebar and the full-page routed chat) through the `agentBuilder` start contract.
 
-**When to use `onAttachmentMount`:**
+This is useful when the surrounding application wants to attach page context only under specific conditions, and react when the active chat binds to a new or existing conversation.
 
-- Setting up subscriptions that should live for the duration of the attachment's presence in the conversation
-- Syncing attachment state with external systems
-- Any side effect that needs cleanup when the attachment is removed
+A **pending attachment** is a client-only attachment attached to the active conversation that has not yet been persisted to a round; it lives in the chat UI until the user submits the next message, at which point it is sent with that round and persisted.
 
-**Important:** This hook is called once per attachment (not per version). The framework tracks attachment presence at the conversation level, so you don't need to handle deduplication.
+### `setChatConfig(...)`
 
-**Parameters:**
+> **Scope:** sidebar only.
+
+`setChatConfig(...)` configures the next sidebar open, or updates the active sidebar if it is already open.
+
+It supports the regular embeddable conversation props, including:
+
+- `newConversation` - force the sidebar to start a fresh conversation instead of restoring the persisted one
+- `attachments` - pre-populate the pending attachment list for the active sidebar conversation
+
+Use `clearChatConfig()` to remove that runtime configuration.
+
+#### `newConversation`
+
+Set `newConversation: true` when the sidebar must always bind to a fresh conversation:
 
 ```ts
-interface AttachmentLifecycleParams<TAttachment> {
-  /** The attachment instance */
-  attachment: TAttachment;
-  /** The conversation ID containing this attachment */
-  conversationId: string;
-  /** Whether the attachment is rendered in the sidebar context */
-  isSidebar: boolean;
-}
+agentBuilder.setChatConfig({
+  newConversation: true,
+});
 ```
 
-**Example: Syncing attachment origin when a dashboard is saved**
+#### `attachments`
 
-```tsx
-export const myAttachmentDefinition: AttachmentUIDefinition<MyAttachment> = {
-  getLabel: () => 'My attachment',
-  getIcon: () => 'document',
+Set `attachments` when you want the sidebar to open with one or more pending attachments already present:
 
-  onAttachmentMount: ({ attachment, conversationId }) => {
-    // Set up a subscription when the attachment is added
-    const subscription = someObservable$.subscribe((newValue) => {
-      if (newValue !== attachment.origin) {
-        // Update the attachment's origin using the plugin API
-        agentBuilder.updateAttachmentOrigin(conversationId, attachment.id, newValue);
-      }
-    });
+```ts
+agentBuilder.setChatConfig({
+  attachments: [
+    {
+      id: 'my-context',
+      type: 'my_type',
+      data: { ... },
+    },
+  ],
+});
+```
 
-    // Return cleanup function - called when the attachment is removed from the conversation
-    return () => {
-      subscription.unsubscribe();
-    };
-  },
+### `addAttachment(...)`
 
-  // ... other definition properties
-};
+> **Scope:** sidebar only. If no sidebar is open, the call is silently ignored.
+
+`addAttachment(...)` adds or updates a pending attachment in the active sidebar conversation.
+
+```ts
+agentBuilder.addAttachment({
+  id: 'my-pending-context',
+  type: 'my_type',
+  data: { ... },
+  origin: 'saved-object-id',
+});
+```
+
+Pending attachments added through `agentBuilder.addAttachment(...)` can include an `origin` string, just like other attachment inputs sent to the Agent Builder APIs. Use this when your pending attachment already corresponds to a persistent resource (for example, a saved object-backed dashboard or visualization), and your attachment type expects `origin` to be present.
+
+## Events
+
+The `agentBuilder` start contract exposes observables on the `events.ui` namespace that let plugins react to the chat surface lifecycle (currently the active conversation binding).
+
+### Observing sidebar open state
+
+If you need to know whether the Agent Builder sidebar is currently open, subscribe to the core chrome sidebar primitive and match on the `agentBuilder` app id:
+
+```ts
+useEffect(() => {
+  const sub = chrome.sidebar.getCurrentAppId$().subscribe((appId) => {
+    const isOpen = appId === 'agentBuilder';
+    // react to the {isOpen} value
+  });
+
+  return () => sub.unsubscribe();
+}, [chrome.sidebar]);
 ```
 
-**Cleanup behavior:**
+### `events.ui.activeConversation$`
+
+Use `events.ui.activeConversation$` when you need to react to the conversation currently bound to the active chat surface.
+
+The non-null payload is:
+
+- `id?: string` - the currently bound conversation id, or `undefined` when the chat is currently bound to a new conversation
+- `conversation?: Conversation` - the fully loaded conversation when it has been successfully fetched (undefined for new conversations, while loading, or on fetch errors)
+
+```ts
+class MyPlugin {
+  private conversationSubscription?: Subscription;
+
+  start(core: CoreStart, { agentBuilder }: { agentBuilder: AgentBuilderPluginStart }) {
+    this.conversationSubscription = agentBuilder.events.ui.activeConversation$.subscribe((change) => {
+      if (!change) {
+        // No chat surface currently bound — tear down local state.
+        return;
+      }
+
+      const { id, conversation } = change;
+
+      if (!id) {
+        agentBuilder.addAttachment({
+          id: 'my-pending-context',
+          type: 'my_type',
+          data: { ... },
+        });
+        return;
+      }
+
+      const hasMyAttachment = conversation?.attachments?.some(
+        (attachment) => attachment.id === 'my-pending-context'
+      );
 
-- The cleanup function is called when the attachment is removed from the conversation
-- It's also called when the conversation component unmounts (e.g., navigating away)
-- If `onAttachmentMount` returns `undefined` or `void`, no cleanup is performed
+      if (!hasMyAttachment) {
+        // Handle the switch away from the pending attachment in your plugin state.
+      }
+    });
+  }
+
+  stop() {
+    this.conversationSubscription?.unsubscribe();
+  }
+}
+```
 
 ## Registering skills
 

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

@@ -9,9 +9,6 @@ import { EuiFlexGroup } from '@elastic/eui';
 import { i18n } from '@kbn/i18n';
 import React from 'react';
 import { useConversation, useConversationRounds } from '../../../hooks/use_conversation';
-import { useAgentBuilderServices } from '../../../hooks/use_agent_builder_service';
-import { useAttachmentLifecycle } from '../../../hooks/use_attachment_lifecycle';
-import { useConversationContext } from '../../../context/conversation/conversation_context';
 import { RoundLayout } from './round_layout';
 
 const CONVERSATION_ROUNDS_ID = 'agentBuilderConversationRoundsContainer';
@@ -25,15 +22,6 @@ export const ConversationRounds: React.FC<ConversationRoundsProps> = ({
 }) => {
   const { conversation } = useConversation();
   const conversationRounds = useConversationRounds();
-  const { attachmentsService } = useAgentBuilderServices();
-  const { conversationActions } = useConversationContext();
-
-  useAttachmentLifecycle({
-    attachments: conversation?.attachments,
-    conversationId: conversation?.id,
-    attachmentsService,
-    invalidateConversation: conversationActions.invalidateConversation,
-  });
 
   return (
     <EuiFlexGroup

x-pack/platform/plugins/shared/agent_builder/public/application/context/conversation/conversation_change_notifier.tsx

@@ -0,0 +1,47 @@
+/*
+ * 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 { useEffect } from 'react';
+import { useAgentBuilderServices } from '../../hooks/use_agent_builder_service';
+import { useConversation } from '../../hooks/use_conversation';
+import { useConversationId } from './use_conversation_id';
+
+/**
+ * Publishes the active conversation to the shared `EventsService` whenever the
+ * conversation id or fetch state changes, and resets it to `null` when the
+ * subtree unmounts (e.g. the user navigates away from the full-page chat or
+ * closes the sidebar).
+ */
+export const ConversationChangeNotifier = (): null => {
+  const { eventsService } = useAgentBuilderServices();
+  const conversationId = useConversationId();
+  const { conversation, isError, isFetched } = useConversation();
+
+  useEffect(() => {
+    if (!conversationId) {
+      eventsService.setActiveConversation({ id: undefined });
+      return;
+    }
+
+    if (isError) {
+      eventsService.setActiveConversation({ id: conversationId });
+      return;
+    }
+
+    if (isFetched && conversation) {
+      eventsService.setActiveConversation({ id: conversationId, conversation });
+    }
+  }, [conversationId, conversation, isError, isFetched, eventsService]);
+
+  useEffect(() => {
+    return () => {
+      eventsService.clearActiveConversation();
+    };
+  }, [eventsService]);
+
+  return null;
+};

x-pack/platform/plugins/shared/agent_builder/public/application/context/conversation/embeddable_conversations_provider.tsx

@@ -20,6 +20,7 @@ import { upsertAttachmentsIntoList } from './upsert_attachments_into_list';
 import { AgentBuilderServicesContext } from '../agent_builder_services_context';
 import { SendMessageProvider } from '../send_message/send_message_context';
 import { useConversationActions } from './use_conversation_actions';
+import { ConversationChangeNotifier } from './conversation_change_notifier';
 import { usePersistedConversationId } from '../../hooks/use_persisted_conversation_id';
 import { AppLeaveContext } from '../app_leave_context';
 
@@ -229,6 +230,7 @@ export const EmbeddableConversationsProvider: React.FC<EmbeddableConversationsPr
           <AgentBuilderServicesContext.Provider value={services}>
             <AppLeaveContext.Provider value={noopOnAppLeave}>
               <ConversationContext.Provider value={conversationContextValue}>
+                <ConversationChangeNotifier />
                 <SendMessageProvider>{children}</SendMessageProvider>
               </ConversationContext.Provider>
             </AppLeaveContext.Provider>

x-pack/platform/plugins/shared/agent_builder/public/application/context/conversation/routed_conversations_provider.tsx

@@ -18,6 +18,7 @@ import { useAgentBuilderServices } from '../../hooks/use_agent_builder_service';
 import { useConversationActions } from './use_conversation_actions';
 import { queryKeys } from '../../query_keys';
 import { upsertAttachmentsIntoList } from './upsert_attachments_into_list';
+import { ConversationChangeNotifier } from './conversation_change_notifier';
 
 interface RoutedConversationsProviderProps {
   children: React.ReactNode;
@@ -147,6 +148,9 @@ export const RoutedConversationsProvider: React.FC<RoutedConversationsProviderPr
   );
 
   return (
-    <ConversationContext.Provider value={contextValue}>{children}</ConversationContext.Provider>
+    <ConversationContext.Provider value={contextValue}>
+      <ConversationChangeNotifier />
+      {children}
+    </ConversationContext.Provider>
   );
 };