[8369] Have the Expert open the onboarding conversation

The Expert speaks first on the onboarding page, so the frontend needs a way
to start a turn the user has not typed. openConversation sends a turn with an
empty query, the same shape resumeToolApprovals already uses, and the agent
tells onboarding apart from ordinary support by the onboarding flag now
carried on the context object.

Two things it deliberately does not do. No user message is added, since the
user has not said anything. And the session clock is left unstarted, so the
25 minute warning and 28 minute expiry begin when the user first replies
rather than while they are still reading the opening question.

The onboarding flag goes on both branches of the context getter: they build
their objects separately, so a field added to one goes missing depending on
load timing. It tracks the conversation rather than the deployment, staying
true after the Expert moves the user into the editor and going false once
onboarding is finished or skipped.

Drops the hardcoded placeholder transcript that stood in while this was
missing. A transcript holding only canned messages still counts as empty and
gets cleared, so arriving from the drawer does not leave its greeting in the
way, while a real conversation is left alone and picked up where it stopped.

Author: cstns

frontend/src/components/expert/composables/onboardingFixture.js

@@ -24,7 +24,6 @@ import { mapState } from 'pinia'
 
 import teamApi from '@/api/team.ts'
 import ExpertPanel from '@/components/expert/Expert.vue'
-import { ONBOARDING_FIXTURE_MESSAGES } from '@/components/expert/composables/onboardingFixture.js'
 import Alerts from '@/services/alerts.js'
 import { useAccountSettingsStore } from '@/stores/account-settings.js'
 import { useAccountStore } from '@/stores/account.js'
@@ -50,6 +49,7 @@ export default {
         return {
             provisioning: false,
             teleportReady: false,
+            conversationRequested: false,
             // How many turns the user had contributed when the page opened.
             // Anything beyond it is them engaging, which lets the seeded
             // transcript exist without counting as engagement.
@@ -89,7 +89,7 @@ export default {
         team: {
             immediate: true,
             handler () {
-                this.seedFixtureTranscript()
+                this.openConversation()
             }
         },
         userTurns: {
@@ -128,12 +128,8 @@ export default {
         })
     },
     methods: {
-        // TEMPORARY until flowfuse#8369: the Expert can't open a conversation
-        // on its own yet, so seed a placeholder transcript to work against.
-        // A transcript holding only canned messages (`generated`, e.g. the
-        // drawer's welcome text) counts as empty and gets replaced.
-        seedFixtureTranscript () {
-            if (!this.team || this.notAvailable) {
+        openConversation () {
+            if (!this.team || this.notAvailable || this.conversationRequested) {
                 return
             }
             const expertStore = useProductExpertStore()
@@ -143,7 +139,8 @@ export default {
             if (expertStore.messages.length > 0) {
                 useProductExpertSupportAgentStore().reset()
             }
-            expertStore.hydrateMessages(ONBOARDING_FIXTURE_MESSAGES)
+            this.conversationRequested = true
+            expertStore.openConversation()
         },
         async skipOnboarding () {
             if (this.provisioning) {

frontend/src/pages/team/Onboarding.vue

@@ -10,6 +10,7 @@ import { useDataFarmApplicationsStore } from './data-farm-applications'
 import { useDataFarmTeamsStore } from './data-farm-teams'
 import { useProductAssistantStore } from './product-assistant.js'
 import { useProductExpertStore } from './product-expert.js'
+import { useUxStore } from './ux.js'
 
 import { useMqttExpertTopicHelper } from '@/composables/services/MqttExpertTopicHelper'
 
@@ -101,7 +102,8 @@ export const useContextStore = defineStore('context', {
                     selectedNodes: null,
                     scope: this.isImmersive ? 'immersive' : 'ff-app',
                     questionCadence: useProductExpertStore().questionCadence,
-                    planMode: useProductExpertStore().planMode
+                    planMode: useProductExpertStore().planMode,
+                    onboarding: useUxStore().isOnboarding
                 }
             }
 
@@ -145,6 +147,7 @@ export const useContextStore = defineStore('context', {
                 supportsPlatformUIAutomation: useAccountSettingsStore().featuresCheck?.isExpertPlatformAutomationFeatureEnabled ?? false,
                 questionCadence: useProductExpertStore().questionCadence,
                 planMode: useProductExpertStore().planMode,
+                onboarding: useUxStore().isOnboarding,
                 // Capability flags: signal that this version can render the question,
                 // plan, and approval cards. Older instances omit them and the agent drops
                 // the matching tool / runs in backward-compatible mode.

frontend/src/stores/context.js

@@ -211,6 +211,35 @@ export const useProductExpertStore = defineStore('product-expert', {
         setComposerCommand (command) {
             this.composerCommand = command
         },
+        async openConversation () {
+            const agentStore = this._agentStore
+
+            if (agentStore.sessionId && this.isWaitingForResponse) {
+                return undefined
+            }
+            if (!agentStore.sessionId) {
+                agentStore.sessionId = uuidv4()
+            }
+
+            agentStore.abortController = markRaw(new AbortController())
+            try {
+                const result = await this.sendQuery({ query: '' })
+                if (result) {
+                    await this.handleMessageResponse(result)
+                }
+                return result
+            } catch (error) {
+                if (error.name === 'AbortError' || error.name === 'CanceledError') {
+                    return undefined
+                }
+                if (!this.shouldUseMqtt) {
+                    console.error('Expert API error:', error)
+                }
+                this.addPredefinedAiMessage('Sorry, I could not get started. Please refresh to try again.', { isError: true })
+            } finally {
+                agentStore.abortController = null
+            }
+        },
         async handleQuery ({ query }) {
             const agentStore = this._agentStore
 

frontend/src/stores/product-expert.js

@@ -7,7 +7,7 @@ const mocks = vi.hoisted(() => {
         contextStore: { team: null },
         settingsStore: { featuresCheck: {} },
         accountStore: { setTeam: vi.fn().mockResolvedValue() },
-        expertStore: { messages: [], hydrateMessages: vi.fn() },
+        expertStore: { messages: [], openConversation: vi.fn() },
         supportAgentStore: { reset: vi.fn() },
         uxStore: { isOnboardingIntake: true, endOnboarding: vi.fn() }
     }
@@ -146,40 +146,51 @@ describe('Onboarding page', () => {
         expect(wrapper.vm.$options.provide.call(wrapper.vm)['expert-surface']).toBe('onboarding')
     })
 
-    describe('fixture transcript', () => {
+    describe('opening the conversation', () => {
         beforeEach(() => {
-            mocks.expertStore.hydrateMessages.mockClear()
+            mocks.expertStore.openConversation.mockClear()
             mocks.supportAgentStore.reset.mockClear()
             mocks.expertStore.messages = []
         })
 
-        test('seeds the placeholder conversation when the transcript is empty', async () => {
+        test('asks the Expert to open the conversation when the transcript is empty', async () => {
             await mountPage()
-            expect(mocks.expertStore.hydrateMessages).toHaveBeenCalledTimes(1)
-            const seeded = mocks.expertStore.hydrateMessages.mock.calls[0][0]
-            expect(Array.isArray(seeded)).toBe(true)
-            expect(seeded.length).toBeGreaterThan(0)
+            expect(mocks.expertStore.openConversation).toHaveBeenCalledTimes(1)
             expect(mocks.supportAgentStore.reset).not.toHaveBeenCalled()
         })
 
-        test('replaces a transcript that only holds canned messages', async () => {
+        // Arriving from the drawer leaves its canned welcome behind; it is not a
+        // conversation, so it gets cleared rather than opened on top of
+        test('clears a transcript that only holds canned messages first', async () => {
             mocks.expertStore.messages = [{ _type: 'ai', generated: true }]
             await mountPage()
             expect(mocks.supportAgentStore.reset).toHaveBeenCalledTimes(1)
-            expect(mocks.expertStore.hydrateMessages).toHaveBeenCalledTimes(1)
+            expect(mocks.expertStore.openConversation).toHaveBeenCalledTimes(1)
         })
 
-        test('does not reseed a real conversation', async () => {
+        // This is what makes the page resumable: a conversation already in
+        // progress is picked up rather than restarted
+        test('leaves a real conversation alone', async () => {
             mocks.expertStore.messages = [{ _type: 'human', content: 'hello' }]
             await mountPage()
-            expect(mocks.expertStore.hydrateMessages).not.toHaveBeenCalled()
+            expect(mocks.expertStore.openConversation).not.toHaveBeenCalled()
             expect(mocks.supportAgentStore.reset).not.toHaveBeenCalled()
         })
 
-        test('does not seed when the page is redirecting away', async () => {
+        test('does not open when the page is redirecting away', async () => {
             mocks.settingsStore.featuresCheck = { isAiOnboardingFeatureEnabled: false }
             await mountPage()
-            expect(mocks.expertStore.hydrateMessages).not.toHaveBeenCalled()
+            expect(mocks.expertStore.openConversation).not.toHaveBeenCalled()
+        })
+
+        // The team watcher can fire more than once before the opening turn comes
+        // back, and an empty transcript would let it through every time
+        test('only opens once even if the team resolves again', async () => {
+            const wrapper = await mountPage()
+            mocks.contextStore.team = { id: 't1', slug: 'ateam', instanceCount: 0 }
+            await wrapper.vm.$nextTick()
+            wrapper.vm.openConversation()
+            expect(mocks.expertStore.openConversation).toHaveBeenCalledTimes(1)
         })
     })
 

test/unit/frontend/pages/team/Onboarding.spec.js

@@ -431,6 +431,28 @@ describe('context store', () => {
                 expect(expert.scope).toBe('ff-app')
             })
 
+            // Both branches build the object separately, so a field added to one
+            // and not the other goes missing depending on load timing
+            it('carries the onboarding flag on both the early-return and main paths', async () => {
+                const { useUxStore } = await import('@/stores/ux.js')
+                const store = useContextStore()
+                const uxStore = useUxStore()
+
+                expect(store.route).toBe(null)
+                expect(store.expert.onboarding).toBe(false)
+
+                uxStore.setNewlyCreatedUser()
+                expect(store.expert.onboarding).toBe(true)
+
+                store.setTeamMembership({ role: 30 })
+                store.updateRoute({ name: 'team', fullPath: '/team/a', params: {} })
+                expect(store.route).not.toBe(null)
+                expect(store.expert.onboarding).toBe(true)
+
+                uxStore.endOnboarding()
+                expect(store.expert.onboarding).toBe(false)
+            })
+
             it('includes teamId and teamSlug from context team', () => {
                 const store = useContextStore()
                 store.setTeam({ id: 'team-42', slug: 'my-team' })

test/unit/frontend/stores/context.spec.js

@@ -305,6 +305,81 @@ describe('product-expert store', () => {
         })
     })
 
+    describe('openConversation', () => {
+        it('sends a turn with no query', async () => {
+            const store = useProductExpertStore()
+            const sendQuery = vi.spyOn(store, 'sendQuery').mockResolvedValue(undefined)
+
+            await store.openConversation()
+
+            expect(sendQuery).toHaveBeenCalledWith({ query: '' })
+        })
+
+        // The user has not said anything, so nothing of theirs belongs in the
+        // transcript
+        it('adds no user message', async () => {
+            const store = useProductExpertStore()
+            vi.spyOn(store, 'sendQuery').mockResolvedValue(undefined)
+
+            await store.openConversation()
+
+            expect(store.messages).toHaveLength(0)
+        })
+
+        // The expiry window should start when the user replies, not while they
+        // are still reading the opening question
+        it('does not start the session clock', async () => {
+            const store = useProductExpertStore()
+            const supportAgent = useProductExpertSupportAgentStore()
+            vi.spyOn(store, 'sendQuery').mockResolvedValue(undefined)
+
+            await store.openConversation()
+
+            expect(supportAgent.sessionStartTime).toBe(null)
+        })
+
+        it('gives the session an id', async () => {
+            const store = useProductExpertStore()
+            const supportAgent = useProductExpertSupportAgentStore()
+            vi.spyOn(store, 'sendQuery').mockResolvedValue(undefined)
+
+            await store.openConversation()
+
+            expect(supportAgent.sessionId).toBeTruthy()
+        })
+
+        it('clears the abort controller when the turn settles', async () => {
+            const store = useProductExpertStore()
+            const supportAgent = useProductExpertSupportAgentStore()
+            vi.spyOn(store, 'sendQuery').mockResolvedValue(undefined)
+
+            await store.openConversation()
+
+            expect(supportAgent.abortController).toBe(null)
+        })
+
+        it('surfaces a failure to the user rather than leaving a blank page', async () => {
+            const store = useProductExpertStore()
+            vi.spyOn(store, 'sendQuery').mockRejectedValue(new Error('broker down'))
+
+            await store.openConversation()
+
+            expect(store.messages).toHaveLength(1)
+            expect(store.messages[0].error).toBe(true)
+        })
+
+        it('says nothing when the turn was aborted', async () => {
+            const store = useProductExpertStore()
+            const aborted = new Error('aborted')
+            aborted.name = 'AbortError'
+            vi.spyOn(store, 'sendQuery').mockRejectedValue(aborted)
+
+            await store.openConversation()
+
+            expect(store.messages).toHaveLength(0)
+        })
+    })
+
     describe('reset', () => {
         it('calls reset on the active agent store and resets own state', () => {
             const store = useProductExpertStore()