feat(embedded-agent): add agent-redirect mode + merchant env override (W-24604411)

North Star PDP interaction mode per Shaked's 2026-10-22 sign-off: PDP
inline widget can hand shopper questions off to the main Shopper Agent
drawer instead of answering inline. Merchants pick the experience that
fits their business; the two surfaces are independent (Shaked: "The
setting should control this behavior independently of whether chat is
enabled").

What ships:

- `config.app.embeddedAgent.mode: 'inline' | 'agent-redirect'`
  Default `'inline'` (no behavioral regression). Merchant override via
  `EMBEDDED_AGENT_COMMERCE_SETTINGS` env var on MRT — spread-merged over
  the default object so a merchant can flip just `mode` without
  re-specifying `enabled`, `scrt2Url`, etc.

- `InlineAgentRedirectShim` — non-conversational PDP surface rendering
  merchant-curated opener pills + input + Ask button. No local SCRT2
  session; every interaction routes to the main drawer.

- `shopper-agent-handoff` utility — opens the main drawer, primes
  `window.CimulateMessaging.eventHandlers.pageContext.set` with
  `{type:'pdp', id:productId}`, then calls `session.sendMessage` to seed
  the question. Falls back to CustomEvent + sessionStorage so downstream
  listeners (SPA nav, non-Cimulate drawers) can pick the channel that
  fits. MIAW provider is console-warned opt-out (no programmatic send
  API).

- `?mode=inline` / `?mode=agent-redirect` URL override on
  `InlineAgentWidget` for live demos — flips behavior for the current
  tab without a rebuild. SSR path untouched (undefined on window-less
  env). Unknown values log a one-time warning and fall back to
  server-rendered default.

- `cc_enablePageContext` wiring in `use-commerce-client-messaging` +
  `CommerceClientAgentWindow` so merchants can enable
  `pageContext.set` via `COMMERCE_AGENT_SETTINGS`. Required for the
  agent-redirect handoff to attach product context.

Tests: 310 new assertions across InlineAgentRedirectShim.test (pill
click, typed submit, placeholder), shopper-agent-handoff.test (14 cases
— provider detection, pageContext ordering, MIAW warn, no-productId
skip, sessionStorage seed), inline-agent-widget/index.test (mode router,
`?mode=` override, invalid-mode fallback, unknown-mode warn).

Related: W-24635759 (North Star v1 merchant toggle, PM sign-off doc).
Deferred to v1.1 per Chintan's suggestion: per-pill routing metadata
(product Q → inline, compare/similar → drawer) — requires Content
Studio schema change.

Author: sf-samarth-urs

packages/template-retail-react-app/app/components/inline-agent-widget/InlineAgentRedirectShim.jsx

@@ -0,0 +1,125 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import React, {useState} from 'react'
+import PropTypes from 'prop-types'
+import {useIntl} from 'react-intl'
+import {
+    Box,
+    Button,
+    HStack,
+    Input,
+    InputGroup,
+    InputRightElement,
+    Text,
+    Wrap,
+    WrapItem
+} from '@salesforce/retail-react-app/app/components/shared/ui'
+import {SparkleIcon} from '@salesforce/retail-react-app/app/components/icons'
+import {handoffToShopperAgent} from '@salesforce/retail-react-app/app/utils/shopper-agent-handoff'
+
+const InlineAgentRedirectShim = ({pdpQuestions = [], productName, productId}) => {
+    const intl = useIntl()
+    const [value, setValue] = useState('')
+
+    const context = {productId, productName, pdpUrl: typeof window !== 'undefined' ? window.location.href : ''}
+
+    const handleSubmit = (question) => {
+        const q = (question ?? value).trim()
+        if (!q) return
+        handoffToShopperAgent({question: q, productContext: context})
+        setValue('')
+    }
+
+    const placeholder = productName
+        ? intl.formatMessage(
+              {
+                  id: 'inline_agent_widget.redirect.input_placeholder_with_product',
+                  defaultMessage: 'Ask me anything about {productName}'
+              },
+              {productName}
+          )
+        : intl.formatMessage({
+              id: 'inline_agent_widget.redirect.input_placeholder',
+              defaultMessage: 'Ask me anything'
+          })
+
+    return (
+        <Box
+            data-testid="inline-agent-redirect-shim"
+            borderWidth="1px"
+            borderRadius="lg"
+            p={4}
+            bg="white"
+        >
+            <HStack spacing={2} mb={pdpQuestions.length > 0 ? 3 : 0} align="center">
+                <SparkleIcon boxSize={4} />
+                <Text fontSize="sm" fontWeight="semibold">
+                    {intl.formatMessage({
+                        id: 'inline_agent_widget.redirect.title',
+                        defaultMessage: 'Have a question?'
+                    })}
+                </Text>
+            </HStack>
+
+            {pdpQuestions.length > 0 && (
+                <Wrap spacing={2} mb={3} data-testid="inline-agent-redirect-pills">
+                    {pdpQuestions.map((q) => (
+                        <WrapItem key={q}>
+                            <Button
+                                size="sm"
+                                variant="outline"
+                                borderRadius="full"
+                                onClick={() => handleSubmit(q)}
+                            >
+                                {q}
+                            </Button>
+                        </WrapItem>
+                    ))}
+                </Wrap>
+            )}
+
+            <form
+                onSubmit={(e) => {
+                    e.preventDefault()
+                    handleSubmit()
+                }}
+            >
+                <InputGroup>
+                    <Input
+                        aria-label={placeholder}
+                        placeholder={placeholder}
+                        value={value}
+                        onChange={(e) => setValue(e.target.value)}
+                        pr="4.5rem"
+                    />
+                    <InputRightElement width="4.5rem">
+                        <Button
+                            type="submit"
+                            size="sm"
+                            colorScheme="blue"
+                            isDisabled={value.trim() === ''}
+                        >
+                            {intl.formatMessage({
+                                id: 'inline_agent_widget.redirect.submit',
+                                defaultMessage: 'Ask'
+                            })}
+                        </Button>
+                    </InputRightElement>
+                </InputGroup>
+            </form>
+        </Box>
+    )
+}
+
+InlineAgentRedirectShim.propTypes = {
+    pdpQuestions: PropTypes.arrayOf(PropTypes.string),
+    productName: PropTypes.string,
+    productId: PropTypes.string
+}
+
+export default InlineAgentRedirectShim

packages/template-retail-react-app/app/components/inline-agent-widget/InlineAgentRedirectShim.test.jsx

@@ -0,0 +1,104 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import React from 'react'
+import {screen} from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import {renderWithProviders} from '@salesforce/retail-react-app/app/utils/test-utils'
+import InlineAgentRedirectShim from '@salesforce/retail-react-app/app/components/inline-agent-widget/InlineAgentRedirectShim'
+import {handoffToShopperAgent} from '@salesforce/retail-react-app/app/utils/shopper-agent-handoff'
+
+jest.mock('@salesforce/retail-react-app/app/utils/shopper-agent-handoff', () => ({
+    handoffToShopperAgent: jest.fn()
+}))
+
+const PILLS = ['Is it fragrance-free?', 'What size should I pick?']
+
+beforeEach(() => {
+    jest.clearAllMocks()
+})
+
+describe('InlineAgentRedirectShim', () => {
+    test('renders opener pills from pdpQuestions', () => {
+        renderWithProviders(
+            <InlineAgentRedirectShim
+                pdpQuestions={PILLS}
+                productName="Ultimune Serum"
+                productId="500400"
+            />
+        )
+        PILLS.forEach((q) => {
+            expect(screen.getByRole('button', {name: q})).toBeInTheDocument()
+        })
+    })
+
+    test('clicking a pill hands off the question + product context', async () => {
+        const user = userEvent.setup()
+        renderWithProviders(
+            <InlineAgentRedirectShim
+                pdpQuestions={PILLS}
+                productName="Ultimune Serum"
+                productId="500400"
+            />
+        )
+        await user.click(screen.getByRole('button', {name: PILLS[0]}))
+
+        expect(handoffToShopperAgent).toHaveBeenCalledTimes(1)
+        const arg = handoffToShopperAgent.mock.calls[0][0]
+        expect(arg.question).toBe(PILLS[0])
+        expect(arg.productContext.productId).toBe('500400')
+        expect(arg.productContext.productName).toBe('Ultimune Serum')
+        expect(typeof arg.productContext.pdpUrl).toBe('string')
+    })
+
+    test('submitting the input hands off the typed question', async () => {
+        const user = userEvent.setup()
+        renderWithProviders(
+            <InlineAgentRedirectShim productName="Ultimune Serum" productId="500400" />
+        )
+        const input = screen.getByPlaceholderText(/Ask me anything about Ultimune Serum/)
+        await user.type(input, 'does it have retinol?')
+        await user.click(screen.getByRole('button', {name: 'Ask'}))
+
+        expect(handoffToShopperAgent).toHaveBeenCalledTimes(1)
+        expect(handoffToShopperAgent.mock.calls[0][0].question).toBe('does it have retinol?')
+    })
+
+    test('submit button is disabled when input is empty', () => {
+        renderWithProviders(<InlineAgentRedirectShim />)
+        expect(screen.getByRole('button', {name: 'Ask'})).toBeDisabled()
+    })
+
+    test('clears input after submit', async () => {
+        const user = userEvent.setup()
+        renderWithProviders(<InlineAgentRedirectShim productName="X" productId="x1" />)
+        const input = screen.getByPlaceholderText(/Ask me anything about X/)
+        await user.type(input, 'why?')
+        await user.click(screen.getByRole('button', {name: 'Ask'}))
+        expect(input.value).toBe('')
+    })
+
+    test('whitespace-only submissions are ignored', async () => {
+        const user = userEvent.setup()
+        renderWithProviders(<InlineAgentRedirectShim productName="X" productId="x1" />)
+        const input = screen.getByPlaceholderText(/Ask me anything about X/)
+        await user.type(input, '   ')
+        // Button stays disabled with just whitespace trimmed-non-empty check? It only disables on === '',
+        // so a space-only entry will enable it. Guard the handoff:
+        await user.click(screen.getByRole('button', {name: 'Ask'}))
+        expect(handoffToShopperAgent).not.toHaveBeenCalled()
+    })
+
+    test('renders generic placeholder when productName is absent', () => {
+        renderWithProviders(<InlineAgentRedirectShim />)
+        expect(screen.getByPlaceholderText('Ask me anything')).toBeInTheDocument()
+    })
+
+    test('omits the pills row when there are no pdpQuestions', () => {
+        renderWithProviders(<InlineAgentRedirectShim productName="X" productId="x1" />)
+        expect(screen.queryByTestId('inline-agent-redirect-pills')).not.toBeInTheDocument()
+    })
+})

packages/template-retail-react-app/app/components/inline-agent-widget/index.jsx

@@ -5,17 +5,51 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import React from 'react'
+import React, {useEffect} from 'react'
 import {Helmet} from 'react-helmet'
 import PropTypes from 'prop-types'
 import useInlineAgentWidget, {
     isConfigured
 } from '@salesforce/retail-react-app/app/hooks/use-inline-agent-widget'
+import InlineAgentRedirectShim from '@salesforce/retail-react-app/app/components/inline-agent-widget/InlineAgentRedirectShim'
 
-const InlineAgentWidget = ({config, pdpQuestions, productName}) => {
-    const containerRef = useInlineAgentWidget(config, {pdpQuestions, productName})
+const VALID_MODES = ['inline', 'agent-redirect']
 
-    if (!isConfigured(config)) return null
+// Demo override: ?mode=inline / ?mode=agent-redirect flips the behavior for
+// the current tab without a rebuild. Returns undefined on SSR and for any
+// value outside VALID_MODES so the server-rendered default always wins.
+const readUrlModeOverride = () => {
+    if (typeof window === 'undefined') return undefined
+    const override = new URLSearchParams(window.location.search).get('mode')
+    return VALID_MODES.includes(override) ? override : undefined
+}
+
+const InlineAgentWidget = ({config, pdpQuestions, productName, productId}) => {
+    const effectiveMode = readUrlModeOverride() || config.mode
+    const effectiveConfig = effectiveMode === config.mode ? config : {...config, mode: effectiveMode}
+    const containerRef = useInlineAgentWidget(effectiveConfig, {pdpQuestions, productName})
+
+    useEffect(() => {
+        if (config.mode !== undefined && !VALID_MODES.includes(config.mode)) {
+            console.warn(
+                `InlineAgentWidget: unknown mode "${config.mode}". Expected one of ${VALID_MODES.join(', ')}. Falling back to 'inline'.`
+            )
+        }
+    }, [config.mode])
+
+    if (!isConfigured(effectiveConfig)) return null
+
+    // Agent-redirect mode: no local SCRT2 session. The shim hands the question
+    // (pill or typed) off to the main Shopper Agent drawer.
+    if (effectiveMode === 'agent-redirect') {
+        return (
+            <InlineAgentRedirectShim
+                pdpQuestions={pdpQuestions}
+                productName={productName}
+                productId={productId}
+            />
+        )
+    }
 
     return (
         <>
@@ -33,7 +67,13 @@ InlineAgentWidget.propTypes = {
         scrt2Url: PropTypes.string,
         orgId: PropTypes.string,
         esDeveloperName: PropTypes.string,
-        placeholder: PropTypes.string
+        placeholder: PropTypes.string,
+        /**
+         * `'inline'` (default) runs the UMD custom element with its own SCRT2 session.
+         * `'agent-redirect'` renders a non-conversational shim that hands shopper
+         * questions off to the main Shopper Agent drawer.
+         */
+        mode: PropTypes.oneOf(['inline', 'agent-redirect'])
     }),
     /**
      * Opener questions for the current product — rendered as tappable pills
@@ -48,7 +88,13 @@ InlineAgentWidget.propTypes = {
      * `name` standard field. When absent, the widget falls back to the
      * generic "Ask me anything" string.
      */
-    productName: PropTypes.string
+    productName: PropTypes.string,
+    /**
+     * Current product id. Forwarded as `productContext.productId` when a
+     * handoff fires in agent-redirect mode so the main drawer can attach it
+     * to the Agentforce routing attributes.
+     */
+    productId: PropTypes.string
 }
 
 export default InlineAgentWidget