Have the Expert open the onboarding conversation (#8467)

Author: cstns

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

@@ -11,7 +11,9 @@
                     data-action="skip-onboarding"
                     :disabled="provisioning"
                     @click="skipOnboarding"
-                >Set it up myself</ff-button>
+                >
+                   Set it up myself
+                </ff-button>
             </Teleport>
             <div class="onboarding-column">
                 <ExpertPanel />
@@ -25,7 +27,6 @@ import { mapState } from 'pinia'
 
 import teamApi from '@/api/team.ts'
 import ExpertPanel from '@/components/expert/Expert.vue'
-import { ONBOARDING_FIXTURE_MESSAGES } from '@/composables/Components/expert/onboardingFixture.js'
 import Alerts from '@/services/alerts.js'
 import { useAccountSettingsStore } from '@/stores/account-settings.js'
 import { useAccountStore } from '@/stores/account.js'
@@ -48,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.
@@ -82,11 +84,11 @@ export default {
         team: {
             immediate: true,
             handler () {
-                this.seedFixtureTranscript()
-                // The baseline is taken here, after the seed, rather than in
-                // the userTurns watcher: on a direct page load that watcher
-                // fires before the team resolves and would count the seeded
-                // turns as engagement
+                this.openConversation()
+                // The baseline is taken here, once the team has resolved,
+                // rather than in the userTurns watcher: on a direct page load
+                // that watcher fires before the team resolves, and any turns
+                // the transcript picks up afterwards would count as engagement
                 if (this.team && this.initialUserTurns === null) {
                     this.initialUserTurns = this.userTurns
                 }
@@ -121,12 +123,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()
@@ -136,7 +134,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

@@ -219,6 +219,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() }
     }
@@ -147,40 +147,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)
         })
     })
 
@@ -222,19 +233,14 @@ describe('Onboarding page', () => {
         })
 
         // A direct load or refresh resolves the team after the page mounts, so
-        // the seed lands after the turn baseline would have been captured. The
-        // seeded turns must not read as engagement
-        test('does not count turns seeded after a late team resolve as engagement', async () => {
+        // a resumed transcript can land after the turn baseline would have
+        // been captured. Turns already there must not read as engagement
+        test('does not count turns present before the team resolves as engagement', async () => {
             mocks.contextStore.team = null
             mocks.expertStore.messages = []
-            mocks.expertStore.hydrateMessages.mockImplementationOnce(() => {
-                mocks.expertStore.messages = [
-                    { _type: 'ai', generated: true },
-                    { _type: 'human', content: 'seeded' }
-                ]
-            })
             const wrapper = await mountPage()
 
+            mocks.expertStore.messages = [{ _type: 'human', content: 'hello again' }]
             mocks.contextStore.team = { id: 't1', slug: 'ateam', instanceCount: 0 }
             await flushPromises()
             expect(wrapper.find('[data-action="skip-onboarding"]').classes()).not.toContain('has-engaged')

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()