@promptbook/cli 0.112.0-126 → 0.112.0-128

package/apps/agents-server/src/app/api/chat/citation-label/route.ts

@@ -0,0 +1,133 @@
+import { serializeError } from '@promptbook-local/utils';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import {
+    resolveCitationLabelTargetUrl,
+    resolveCitationSourceLabel,
+    type CitationSourceLabelPayload,
+} from '../../../../utils/chat/resolveCitationSourceLabel';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
+
+/**
+ * Maximum accepted citation field length in the label resolver endpoint.
+ *
+ * @private API route constant
+ */
+const MAX_CITATION_LABEL_FIELD_LENGTH = 2_000;
+
+/**
+ * Raw request body accepted by citation label resolver endpoint.
+ *
+ * @private API route type
+ */
+type CitationLabelRequestBody = {
+    /**
+     * Raw citation source.
+     */
+    readonly source?: unknown;
+
+    /**
+     * Optional source URL.
+     */
+    readonly url?: unknown;
+
+    /**
+     * Optional source title.
+     */
+    readonly title?: unknown;
+};
+
+/**
+ * Resolves nicer labels for chat source citations.
+ *
+ * Requires authentication because the endpoint fetches user-provided URLs.
+ *
+ * @route POST /api/chat/citation-label
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        const body = (await request.json()) as CitationLabelRequestBody;
+        const citation = parseCitationLabelRequestBody(body);
+        const targetUrl = resolveCitationLabelTargetUrl(citation);
+
+        if (targetUrl) {
+            try {
+                assertSafeUrl(targetUrl);
+            } catch (error) {
+                assertsError(error);
+                return NextResponse.json({ error: error.message, label: null }, { status: 400 });
+            }
+        }
+
+        const label = await resolveCitationSourceLabel(citation);
+
+        return NextResponse.json({ label });
+    } catch (error) {
+        assertsError(error);
+        const status = error.name === 'SyntaxError' || error.message.startsWith('Invalid ') ? 400 : 500;
+
+        return NextResponse.json(
+            {
+                error: status === 400 ? error.message : serializeError(error),
+                label: null,
+            },
+            { status },
+        );
+    }
+}
+
+/**
+ * Parses and validates one label resolver request body.
+ *
+ * @param body - Raw request body.
+ * @returns Validated citation payload.
+ *
+ * @private API route helper
+ */
+function parseCitationLabelRequestBody(body: CitationLabelRequestBody): CitationSourceLabelPayload {
+    const source = parseOptionalString(body.source, 'source');
+    if (!source) {
+        throw new Error('Invalid source: expected a non-empty string.');
+    }
+
+    return {
+        source,
+        url: parseOptionalString(body.url, 'url'),
+        title: parseOptionalString(body.title, 'title'),
+    };
+}
+
+/**
+ * Parses an optional request body string field.
+ *
+ * @param value - Raw field value.
+ * @param fieldName - Field name used in validation messages.
+ * @returns Trimmed string or undefined.
+ *
+ * @private API route helper
+ */
+function parseOptionalString(value: unknown, fieldName: string): string | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+
+    if (typeof value !== 'string') {
+        throw new Error(`Invalid ${fieldName}: expected a string.`);
+    }
+
+    const trimmedValue = value.trim();
+    if (trimmedValue.length > MAX_CITATION_LABEL_FIELD_LENGTH) {
+        throw new Error(`Invalid ${fieldName}: value is too long.`);
+    }
+
+    return trimmedValue || undefined;
+}
+
+// Note: [🟢] Code for Agents Server citation label API route should never be published into packages that could be imported into browser environment

package/apps/agents-server/src/app/globals.css

@@ -2,6 +2,66 @@
 @import 'tailwindcss/components';
 @import 'tailwindcss/utilities';
 @import '@xterm/xterm/css/xterm.css';
+@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&family=Inter:wght@400;500;600;700&display=swap');
+
+/**
+ * Scoped design tokens for the imported manGo onboarding wizard.
+ */
+[data-onboarding-ui] {
+    --ob-font-sans: 'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif;
+    --ob-font-display: 'Outfit', 'Inter', ui-sans-serif, system-ui, sans-serif;
+    --ob-brand-blue: #7aebff;
+    --ob-brand-blue-dark: #30a8bd;
+    --ob-brand-green: #7affeb;
+    --ob-brand-green-dark: #30bda8;
+    --ob-ink: #111827;
+    --ob-mist: #f3f4f6;
+    --ob-accent-50: #ecfdff;
+    --ob-accent-100: #d2f8ff;
+    --ob-accent-200: #a8f1fd;
+    --ob-accent-300: #7aebff;
+    --ob-accent-400: #43d3e6;
+    --ob-accent-500: #30a8bd;
+    --ob-accent-600: #2491a4;
+    --ob-accent-700: #1d7686;
+    --ob-accent-800: #1a5e6b;
+    --ob-accent-900: #164a55;
+    --ob-shadow-xs: 0 1px 2px 0 rgb(17 24 39 / 0.04);
+    --ob-shadow-sm: 0 1px 2px 0 rgb(17 24 39 / 0.05), 0 1px 3px 0 rgb(17 24 39 / 0.05);
+    --ob-shadow-md: 0 2px 4px -1px rgb(17 24 39 / 0.05), 0 4px 12px -2px rgb(17 24 39 / 0.08);
+    --ob-shadow-lg: 0 4px 8px -2px rgb(17 24 39 / 0.06), 0 12px 28px -6px rgb(17 24 39 / 0.12);
+    --ob-shadow-accent: 0 1px 2px 0 rgb(48 168 189 / 0.2), 0 6px 16px -4px rgb(48 168 189 / 0.32);
+    --ob-grad-primary: linear-gradient(135deg, var(--ob-brand-blue) 0%, var(--ob-brand-green) 100%);
+    --ob-grad-ink: linear-gradient(160deg, #1b2435 0%, #111827 55%, #0b0f19 100%);
+    --ob-ring: rgb(48 168 189 / 0.5);
+    font-family: var(--ob-font-sans);
+}
+
+[data-onboarding-ui] .ob-display {
+    font-family: var(--ob-font-display);
+    letter-spacing: 0;
+}
+
+@keyframes ob-rise {
+    from {
+        opacity: 0;
+        transform: translateY(8px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+[data-onboarding-ui] .ob-animate-rise {
+    animation: ob-rise 0.4s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    [data-onboarding-ui] .ob-animate-rise {
+        animation: none;
+    }
+}
 
 /**
  * OpenMoji black and white CSS
@@ -1037,6 +1097,24 @@ html.dark [data-chat-modal='tool-call'][data-chat-theme='dark'] button {
     color: inherit;
 }
 
+html.dark [data-onboarding-ui] .bg-white,
+html.dark [data-onboarding-ui] .bg-white\/80 {
+    background-color: #ffffff !important;
+}
+
+html.dark [data-onboarding-ui] input:not([type='checkbox']):not([type='radio']):not([type='range']),
+html.dark [data-onboarding-ui] textarea,
+html.dark [data-onboarding-ui] select {
+    background-color: #ffffff;
+    color: #18181b;
+    border-color: #d4d4d8;
+}
+
+html.dark [data-onboarding-ui] input:not([type='checkbox']):not([type='radio']):not([type='range'])::placeholder,
+html.dark [data-onboarding-ui] textarea::placeholder {
+    color: #a1a1aa;
+}
+
 /* Print styles */
 @media print {
     @page {

package/apps/agents-server/src/components/Header/ActiveAgentBreadcrumbContext.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+import type { AgentBasicInformation } from '../../../../../src/book-2.0/agent-source/AgentBasicInformation';
+
+/**
+ * Subset of agent information that the Header breadcrumb needs to render an agent's name (and avatar)
+ * even when the active agent is not part of the loaded organization list.
+ *
+ * @private mechanism of Agents Server header
+ */
+export type ActiveAgentBreadcrumbInfo = Pick<
+    AgentBasicInformation,
+    'agentName' | 'agentHash' | 'permanentId' | 'meta'
+>;
+
+/**
+ * Internal shape of the active-agent breadcrumb context.
+ *
+ * @private type of Header
+ */
+type ActiveAgentBreadcrumbContextValue = {
+    readonly activeAgentBreadcrumbInfo: ActiveAgentBreadcrumbInfo | null;
+    readonly setActiveAgentBreadcrumbInfo: (info: ActiveAgentBreadcrumbInfo | null) => void;
+};
+
+/**
+ * Context that lets agent pages share the active agent's display info with the Header.
+ *
+ * @private mechanism of Agents Server header
+ */
+const ActiveAgentBreadcrumbContext = createContext<ActiveAgentBreadcrumbContextValue | null>(null);
+
+/**
+ * Provides storage for the active agent's breadcrumb info to the Header.
+ *
+ * @private function of Header
+ */
+export function ActiveAgentBreadcrumbProvider({ children }: { readonly children: ReactNode }) {
+    const [activeAgentBreadcrumbInfo, setActiveAgentBreadcrumbInfo] = useState<ActiveAgentBreadcrumbInfo | null>(null);
+
+    const value = useMemo<ActiveAgentBreadcrumbContextValue>(
+        () => ({ activeAgentBreadcrumbInfo, setActiveAgentBreadcrumbInfo }),
+        [activeAgentBreadcrumbInfo],
+    );
+
+    return <ActiveAgentBreadcrumbContext.Provider value={value}>{children}</ActiveAgentBreadcrumbContext.Provider>;
+}
+
+/**
+ * Reads the active agent's breadcrumb info, used by the Header to render the agent's name in
+ * the breadcrumb whenever the agent is not present in the loaded organization list.
+ *
+ * @private function of Header
+ */
+export function useActiveAgentBreadcrumbInfo(): ActiveAgentBreadcrumbInfo | null {
+    return useContext(ActiveAgentBreadcrumbContext)?.activeAgentBreadcrumbInfo ?? null;
+}
+
+/**
+ * Registers the active agent's breadcrumb info while the calling component is mounted.
+ * Pages that have loaded the agent profile call this hook so the Header breadcrumb can show
+ * the agent's name instead of falling back to its identifier.
+ *
+ * @private function of Header
+ */
+export function useRegisterActiveAgentBreadcrumbInfo(info: ActiveAgentBreadcrumbInfo | null): void {
+    const context = useContext(ActiveAgentBreadcrumbContext);
+    const setter = context?.setActiveAgentBreadcrumbInfo;
+
+    useEffect(() => {
+        if (!setter) {
+            return;
+        }
+
+        setter(info);
+
+        return () => {
+            setter(null);
+        };
+    }, [info, setter]);
+}

package/apps/agents-server/src/components/Header/useHeaderActiveAgent.ts

@@ -5,6 +5,7 @@ import { buildAgentFolderContext, type AgentFolderContext } from '../../utils/ag
 import type { AgentOrganizationAgent } from '../../utils/agentOrganization/types';
 import { buildAgentProfileHref, buildFreshAgentChatHref } from '../../utils/agentRouting/agentRouteHrefs';
 import type { ServerTranslationKey } from '../../languages/ServerTranslationKeys';
+import { useActiveAgentBreadcrumbInfo, type ActiveAgentBreadcrumbInfo } from './ActiveAgentBreadcrumbContext';
 import type { HeaderAgentMenuFolder } from './AgentMenuStructure';
 import { buildAgentMenuStructure } from './buildAgentMenuStructure';
 import { createAgentViewLabel } from './createAgentViewLabel';
@@ -137,11 +138,17 @@ function createActiveAgentHref(activeAgentNavigationId: string | null): string {
 /**
  * Resolves the breadcrumb label shown for the active agent.
  *
+ * The agent's identifier (its `agentName` or `permanentId`) must never leak into the breadcrumb
+ * because the URL form is opaque to the user. When the agent cannot be resolved from the loaded
+ * organization list (typical for anonymous users browsing a public agent), the Header falls back
+ * to the breadcrumb info registered by the agent page; if that is also missing, a generic label
+ * is shown instead of the raw identifier.
+ *
  * @private function of Header
  */
 function createActiveAgentLabel(
     activeAgent: AgentOrganizationAgent | null,
-    activeAgentIdentifier: string | null,
+    activeAgentBreadcrumbInfo: ActiveAgentBreadcrumbInfo | null,
     agentFolderById: Map<number, HeaderAgentMenuFolder>,
     namingPlural: string,
     translate: HeaderTranslate,
@@ -150,7 +157,11 @@ function createActiveAgentLabel(
         return createAgentHierarchyLabel(activeAgent, agentFolderById);
     }
 
-    return activeAgentIdentifier || translate('header.agentsLabelFallback', { agentsPlural: namingPlural });
+    if (activeAgentBreadcrumbInfo) {
+        return activeAgentBreadcrumbInfo.meta?.fullname || activeAgentBreadcrumbInfo.agentName;
+    }
+
+    return translate('header.agentsLabelFallback', { agentsPlural: namingPlural });
 }
 
 /**
@@ -218,11 +229,12 @@ export function useHeaderActiveAgent({
         () => resolveActiveAgent(activeAgentNavigation, agentByIdentifier),
         [activeAgentNavigation, agentByIdentifier],
     );
+    const activeAgentBreadcrumbInfo = useActiveAgentBreadcrumbInfo();
     const activeAgentNavigationId = resolveActiveAgentNavigationId(activeAgent, activeAgentNavigation.agentIdentifier);
     const activeAgentHref = createActiveAgentHref(activeAgentNavigationId);
     const activeAgentLabel = createActiveAgentLabel(
         activeAgent,
-        activeAgentNavigation.agentIdentifier,
+        activeAgentBreadcrumbInfo,
         agentFolderById,
         namingPlural,
         translate,
@@ -239,10 +251,17 @@ export function useHeaderActiveAgent({
         [activeAgentMenuAgent.folderId, activeAgentMenuAgent.visibility, agentFolderById],
     );
     const { origin, hostname } = readWindowLocationState();
-    const activeAgentAvatarUrl = useMemo(
-        () => (activeAgent ? resolveAgentAvatarImageUrl({ agent: activeAgent }) : null),
-        [activeAgent],
-    );
+    const activeAgentAvatarUrl = useMemo(() => {
+        if (activeAgent) {
+            return resolveAgentAvatarImageUrl({ agent: activeAgent });
+        }
+
+        if (activeAgentBreadcrumbInfo) {
+            return resolveAgentAvatarImageUrl({ agent: activeAgentBreadcrumbInfo });
+        }
+
+        return null;
+    }, [activeAgent, activeAgentBreadcrumbInfo]);
 
     return {
         activeAgent,

package/apps/agents-server/src/components/LayoutWrapper/LayoutWrapper.tsx

@@ -18,6 +18,7 @@ import { ChatEnterBehaviorPreferencesProvider } from '../ChatEnterBehavior/ChatE
 import { HomepageOptimisticNavigation } from '../Homepage/HomepageOptimisticNavigation';
 import { FileUploadAvailabilityProvider } from '../FileUploadAvailability/FileUploadAvailabilityContext';
 import { Footer, type FooterLink } from '../Footer/Footer';
+import { ActiveAgentBreadcrumbProvider } from '../Header/ActiveAgentBreadcrumbContext';
 import { Header } from '../Header/Header';
 import { MobileMenuHoistingProvider } from '../Header/MobileMenuHoistingContext';
 import { MetadataFlagsProvider } from '../MetadataFlags/MetadataFlagsContext';
@@ -165,39 +166,41 @@ export function LayoutWrapper({
                                                                             controlPanelOptionAvailability,
                                                                         }}
                                                                     >
-                                                                        {shouldRenderMinimalShell ? (
-                                                                            <main className={minimalMainClassName}>
-                                                                                {children}
-                                                                            </main>
-                                                                        ) : (
-                                                                            <div className="agents-server-app-shell flex flex-col">
-                                                                                <Header
-                                                                                    isAdmin={isAdmin}
-                                                                                    isGlobalAdmin={isGlobalAdmin}
-                                                                                    currentUser={currentUser}
-                                                                                    serverName={serverName}
-                                                                                    serverLogoUrl={serverLogoUrl}
-                                                                                    agents={agents}
-                                                                                    agentFolders={agentFolders}
-                                                                                    federatedServers={federatedServers}
-                                                                                    isExperimental={isExperimental}
-                                                                                    feedbackMode={feedbackMode}
-                                                                                    shibbolethAuthenticationStatus={
-                                                                                        shibbolethAuthenticationStatus
-                                                                                    }
-                                                                                />
-                                                                                <main className={mainClassName}>
-                                                                                    <HomepageOptimisticNavigation
-                                                                                        pathname={pathname}
-                                                                                    >
-                                                                                        {children}
-                                                                                    </HomepageOptimisticNavigation>
+                                                                        <ActiveAgentBreadcrumbProvider>
+                                                                            {shouldRenderMinimalShell ? (
+                                                                                <main className={minimalMainClassName}>
+                                                                                    {children}
                                                                                 </main>
-                                                                                {isFooterShown && !isFooterHiddenOnPage && (
-                                                                                    <Footer extraLinks={footerLinks} />
-                                                                                )}
-                                                                            </div>
-                                                                        )}
+                                                                            ) : (
+                                                                                <div className="agents-server-app-shell flex flex-col">
+                                                                                    <Header
+                                                                                        isAdmin={isAdmin}
+                                                                                        isGlobalAdmin={isGlobalAdmin}
+                                                                                        currentUser={currentUser}
+                                                                                        serverName={serverName}
+                                                                                        serverLogoUrl={serverLogoUrl}
+                                                                                        agents={agents}
+                                                                                        agentFolders={agentFolders}
+                                                                                        federatedServers={federatedServers}
+                                                                                        isExperimental={isExperimental}
+                                                                                        feedbackMode={feedbackMode}
+                                                                                        shibbolethAuthenticationStatus={
+                                                                                            shibbolethAuthenticationStatus
+                                                                                        }
+                                                                                    />
+                                                                                    <main className={mainClassName}>
+                                                                                        <HomepageOptimisticNavigation
+                                                                                            pathname={pathname}
+                                                                                        >
+                                                                                            {children}
+                                                                                        </HomepageOptimisticNavigation>
+                                                                                    </main>
+                                                                                    {isFooterShown && !isFooterHiddenOnPage && (
+                                                                                        <Footer extraLinks={footerLinks} />
+                                                                                    )}
+                                                                                </div>
+                                                                            )}
+                                                                        </ActiveAgentBreadcrumbProvider>
                                                                     </MetadataFlagsProvider>
                                                                 </MobileMenuHoistingProvider>
                                                             </MenuHoistingProvider>

package/apps/agents-server/src/components/NewAgentDialog/ManGoNewAgentWizard/ManGoNewAgentWizard.tsx

@@ -0,0 +1,151 @@
+'use client';
+
+import type { string_book } from '@promptbook-local/types';
+import { useCallback, useMemo, useState } from 'react';
+import type { NewAgentWizardMode } from '../../../constants/newAgentWizard';
+import type { AgentVisibility } from '../../../utils/agentVisibility';
+import { Dialog } from '../../Portal/Dialog';
+import { ONBOARDING_ENTRY_PATH, ONBOARDING_STEPS } from './config/steps';
+import { ManGoOnboardingNavigationContext } from './ManGoOnboardingNavigation';
+import { OnboardingProvider } from './state/OnboardingProvider';
+import { WizardShell } from './components/WizardShell';
+import { BookStep } from './components/steps/BookStep';
+import { DoneStep, type ManGoCreatedAgentPayload } from './components/steps/DoneStep';
+import { KnowledgeStep } from './components/steps/KnowledgeStep';
+import { TestStep } from './components/steps/TestStep';
+import { ZadaniStep } from './components/steps/ZadaniStep';
+
+/**
+ * Props accepted by the imported manGo new-agent wizard.
+ */
+type ManGoNewAgentWizardProps = {
+    /**
+     * Metadata-driven flow assignment used for analytics.
+     */
+    readonly mode: NewAgentWizardMode;
+
+    /**
+     * Default visibility resolved from server metadata.
+     */
+    readonly defaultVisibility: AgentVisibility;
+
+    /**
+     * Folder scope where the flow was opened.
+     */
+    readonly folderId?: number | null;
+
+    /**
+     * Requests closing the fullscreen wizard.
+     */
+    readonly onClose: () => void;
+
+    /**
+     * Persists the synthesized agent source using the existing create-agent endpoint.
+     */
+    readonly onCreate: (request: ManGoNewAgentWizardCreateRequest) => Promise<ManGoCreatedAgentPayload>;
+
+    /**
+     * Opens the created agent route after the completion screen.
+     */
+    readonly onOpenCreatedAgent: (targetPath: string) => void;
+};
+
+/**
+ * Payload submitted when the manGo wizard creates an agent.
+ */
+export type ManGoNewAgentWizardCreateRequest = {
+    /**
+     * Book source synthesized from the wizard session.
+     */
+    readonly agentSource: string_book;
+
+    /**
+     * Explicit visibility used for the created agent.
+     */
+    readonly visibility: AgentVisibility;
+
+    /**
+     * Number of ready knowledge sources included in the final source.
+     */
+    readonly knowledgeCount: number;
+};
+
+/**
+ * Renders the current local route from the imported manGo wizard.
+ *
+ * @param props - Current route and create-agent callbacks.
+ * @returns Step component for the current route.
+ */
+function renderManGoWizardStep(props: {
+    readonly currentPath: string;
+    readonly defaultVisibility: AgentVisibility;
+    readonly onCreate: ManGoNewAgentWizardProps['onCreate'];
+    readonly onOpenCreatedAgent: ManGoNewAgentWizardProps['onOpenCreatedAgent'];
+}) {
+    const { currentPath, defaultVisibility, onCreate, onOpenCreatedAgent } = props;
+
+    switch (currentPath) {
+        case ONBOARDING_STEPS[0].path:
+            return <BookStep />;
+        case ONBOARDING_STEPS[1].path:
+            return <KnowledgeStep />;
+        case ONBOARDING_STEPS[2].path:
+            return <TestStep />;
+        case ONBOARDING_STEPS[3].path:
+            return (
+                <DoneStep
+                    defaultVisibility={defaultVisibility}
+                    onCreate={onCreate}
+                    onOpenCreatedAgent={onOpenCreatedAgent}
+                />
+            );
+        case ONBOARDING_ENTRY_PATH:
+        default:
+            return <ZadaniStep />;
+    }
+}
+
+/**
+ * Renders the imported manGo fullscreen new-agent wizard.
+ *
+ * @param props - Wizard callbacks and metadata-backed defaults.
+ * @returns Fullscreen create-agent wizard dialog.
+ */
+export function ManGoNewAgentWizard(props: ManGoNewAgentWizardProps) {
+    const { defaultVisibility, onClose, onCreate, onOpenCreatedAgent } = props;
+    const [currentPath, setCurrentPath] = useState(ONBOARDING_ENTRY_PATH);
+    const navigateToPath = useCallback((path: string) => {
+        setCurrentPath(path);
+    }, []);
+    const navigationContextValue = useMemo(
+        () => ({
+            currentPath,
+            navigateToPath,
+            requestClose: onClose,
+        }),
+        [currentPath, navigateToPath, onClose],
+    );
+
+    return (
+        <Dialog
+            onClose={onClose}
+            ariaLabel="manGo wizard"
+            isBackdropDismissible={false}
+            backdropClassName="items-stretch justify-stretch bg-slate-950/80 p-0 backdrop-blur-0"
+            className="!h-[100dvh] !w-screen !max-w-none !overflow-hidden !rounded-none !border-0 !bg-transparent !p-0 !shadow-none"
+        >
+            <ManGoOnboardingNavigationContext.Provider value={navigationContextValue}>
+                <OnboardingProvider>
+                    <WizardShell>
+                        {renderManGoWizardStep({
+                            currentPath,
+                            defaultVisibility,
+                            onCreate,
+                            onOpenCreatedAgent,
+                        })}
+                    </WizardShell>
+                </OnboardingProvider>
+            </ManGoOnboardingNavigationContext.Provider>
+        </Dialog>
+    );
+}

package/apps/agents-server/src/components/NewAgentDialog/ManGoNewAgentWizard/ManGoOnboardingNavigation.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+import { NotAllowed } from '../../../../../../src/errors/NotAllowed';
+
+/**
+ * In-dialog navigation context used by the imported manGo onboarding wizard.
+ *
+ * @private internal context of <ManGoNewAgentWizard/>.
+ */
+type ManGoOnboardingNavigationContextValue = {
+    /**
+     * Current wizard path mirrored from the original route-based onboarding flow.
+     */
+    readonly currentPath: string;
+
+    /**
+     * Moves the fullscreen wizard to another original onboarding path.
+     */
+    readonly navigateToPath: (path: string) => void;
+
+    /**
+     * Requests closing the fullscreen wizard.
+     */
+    readonly requestClose: () => void;
+};
+
+/**
+ * React context carrying the local wizard navigation state.
+ *
+ * @private internal context of <ManGoNewAgentWizard/>.
+ */
+export const ManGoOnboardingNavigationContext = createContext<ManGoOnboardingNavigationContextValue | null>(null);
+
+/**
+ * Reads the current in-dialog manGo onboarding navigation state.
+ *
+ * @returns Navigation helpers scoped to the current wizard.
+ *
+ * @private internal hook of <ManGoNewAgentWizard/>.
+ */
+export function useManGoOnboardingNavigation(): ManGoOnboardingNavigationContextValue {
+    const context = useContext(ManGoOnboardingNavigationContext);
+
+    if (!context) {
+        throw new NotAllowed('useManGoOnboardingNavigation must be used within <ManGoOnboardingNavigationContext>.');
+    }
+
+    return context;
+}