Guide the user to provider setup when a composer mode has no configured provider (#4739)

Author: georgi

web/src/components/chat/composer/MediaChatComposer.tsx

@@ -44,6 +44,8 @@ import type {
 } from "../../../stores/MediaGenerationStore";
 import MediaControlChip from "./MediaControlChip";
 import MediaModeMenu from "./MediaModeMenu";
+import ModeProviderSetupBanner from "./ModeProviderSetupBanner";
+import { useModeProviderSetup } from "./useModeProviderSetup";
 import PiComposerControls, { piModeAvailable } from "./PiComposerControls";
 import SmartToyOutlinedIcon from "@mui/icons-material/SmartToyOutlined";
 import MediaOptionMenu, { MediaOption } from "./MediaOptionMenu";
@@ -204,6 +206,12 @@ const MediaChatComposer: React.FC<MediaChatComposerProps> = ({
 
   const addRecentModel = useModelPreferencesStore((s) => s.addRecent);
 
+  // When the selected mode's capability has no configured provider, surface a
+  // setup banner and route the send into the provider-onboarding dialog
+  // instead of letting the request fail server-side. Pi routes through its own
+  // agent socket, so it is exempt.
+  const providerSetup = useModeProviderSetup(isPi ? null : mode);
+
   const [modeAnchor, setModeAnchor] = useState<HTMLButtonElement | null>(null);
   const [durationAnchor, setDurationAnchor] = useState<HTMLButtonElement | null>(null);
   const [resolutionAnchor, setResolutionAnchor] = useState<HTMLButtonElement | null>(null);
@@ -501,6 +509,12 @@ const MediaChatComposer: React.FC<MediaChatComposerProps> = ({
     if (!canGenerate) {
       return;
     }
+    // No configured provider can serve this mode — sending would only fail on
+    // the server. Keep the prompt and guide the user through provider setup.
+    if (providerSetup.needsSetup) {
+      providerSetup.openSetup();
+      return;
+    }
     const content: MessageContent[] = [];
     if (prompt.trim().length > 0) {
       content.push({ type: "text", text: prompt });
@@ -520,7 +534,8 @@ const MediaChatComposer: React.FC<MediaChatComposerProps> = ({
     getFileContents,
     sendMessage,
     clearFiles,
-    recordHistory
+    recordHistory,
+    providerSetup
   ]);
 
   const handlePaste = useCallback(
@@ -890,6 +905,13 @@ const MediaChatComposer: React.FC<MediaChatComposerProps> = ({
         />
         {mentionMenu}
 
+        {providerSetup.needsSetup && providerSetup.reason && (
+          <ModeProviderSetupBanner
+            reason={providerSetup.reason}
+            onConnect={providerSetup.openSetup}
+          />
+        )}
+
         {queuedMessage && (
           <FlexRow
             gap={0.5}

web/src/components/chat/composer/ModeProviderSetupBanner.tsx

@@ -0,0 +1,39 @@
+import React, { memo } from "react";
+import KeyRoundedIcon from "@mui/icons-material/KeyRounded";
+import { AlertBanner, EditorButton } from "../../ui_primitives";
+
+interface ModeProviderSetupBannerProps {
+  reason: string;
+  onConnect: () => void;
+}
+
+/**
+ * Inline callout shown in the composer when the selected mode has no
+ * configured provider behind it. Offers the provider-onboarding dialog so the
+ * user can connect a provider and add an API key without leaving the chat.
+ */
+const ModeProviderSetupBanner: React.FC<ModeProviderSetupBannerProps> = ({
+  reason,
+  onConnect
+}) => (
+  <AlertBanner
+    severity="info"
+    compact
+    icon={<KeyRoundedIcon fontSize="small" />}
+    action={
+      <EditorButton
+        variant="outlined"
+        color="primary"
+        size="small"
+        onClick={onConnect}
+      >
+        Connect a provider
+      </EditorButton>
+    }
+    sx={{ mx: 1, mb: 0.5, alignItems: "center" }}
+  >
+    {reason}
+  </AlertBanner>
+);
+
+export default memo(ModeProviderSetupBanner);

web/src/components/chat/composer/__tests__/useModeProviderSetup.test.tsx

@@ -0,0 +1,119 @@
+import { renderHook, act } from "@testing-library/react";
+import { useModeProviderSetup } from "../useModeProviderSetup";
+import { capabilityForMode, setupReasonForMode } from "../modeProviderSetup";
+import { useProvidersByCapability } from "../../../../hooks/useProviders";
+import { openProviderOnboarding } from "../../../../stores/ProviderOnboardingStore";
+
+jest.mock("../../../../hooks/useProviders", () => ({
+  useProvidersByCapability: jest.fn()
+}));
+
+jest.mock("../../../../stores/ProviderOnboardingStore", () => ({
+  openProviderOnboarding: jest.fn()
+}));
+
+const mockUseProvidersByCapability =
+  useProvidersByCapability as jest.MockedFunction<
+    typeof useProvidersByCapability
+  >;
+const mockOpenProviderOnboarding =
+  openProviderOnboarding as jest.MockedFunction<typeof openProviderOnboarding>;
+
+const providersResult = (
+  providers: { provider: string; capabilities: string[] }[],
+  overrides: Partial<ReturnType<typeof useProvidersByCapability>> = {}
+) => ({
+  providers,
+  isLoading: false,
+  isFetching: false,
+  error: null,
+  ...overrides
+});
+
+describe("capabilityForMode", () => {
+  it("maps each selectable mode to the capability that serves it", () => {
+    expect(capabilityForMode("chat")).toBe("generate_message");
+    expect(capabilityForMode("image")).toBe("text_to_image");
+    expect(capabilityForMode("image_edit")).toBe("text_to_image");
+    expect(capabilityForMode("video")).toBe("text_to_video");
+    expect(capabilityForMode("image_to_video")).toBe("text_to_video");
+    expect(capabilityForMode("audio")).toBe("text_to_speech");
+  });
+
+  it("maps not-yet-selectable modes to null", () => {
+    expect(capabilityForMode("retake")).toBeNull();
+    expect(capabilityForMode("extend")).toBeNull();
+    expect(capabilityForMode("motion_control")).toBeNull();
+    expect(capabilityForMode("audio_to_video")).toBeNull();
+  });
+
+  it("has a reason for every mode with a capability", () => {
+    for (const mode of [
+      "chat",
+      "image",
+      "image_edit",
+      "video",
+      "image_to_video",
+      "audio"
+    ] as const) {
+      expect(setupReasonForMode(mode)).toEqual(expect.any(String));
+    }
+  });
+});
+
+describe("useModeProviderSetup", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("flags a mode whose capability has no configured provider", () => {
+    mockUseProvidersByCapability.mockReturnValue(providersResult([]));
+
+    const { result } = renderHook(() => useModeProviderSetup("image"));
+
+    expect(mockUseProvidersByCapability).toHaveBeenCalledWith("text_to_image");
+    expect(result.current.needsSetup).toBe(true);
+    expect(result.current.reason).toBe(setupReasonForMode("image"));
+
+    act(() => result.current.openSetup());
+    expect(mockOpenProviderOnboarding).toHaveBeenCalledWith({
+      capability: "text_to_image",
+      reason: setupReasonForMode("image")
+    });
+  });
+
+  it("stays quiet when a provider serves the mode", () => {
+    mockUseProvidersByCapability.mockReturnValue(
+      providersResult([{ provider: "fal_ai", capabilities: ["text_to_image"] }])
+    );
+
+    const { result } = renderHook(() => useModeProviderSetup("image"));
+
+    expect(result.current.needsSetup).toBe(false);
+    expect(result.current.reason).toBeNull();
+  });
+
+  it("stays quiet while the provider query is loading or errored", () => {
+    mockUseProvidersByCapability.mockReturnValue(
+      providersResult([], { isLoading: true, isFetching: true })
+    );
+    const loading = renderHook(() => useModeProviderSetup("video"));
+    expect(loading.result.current.needsSetup).toBe(false);
+
+    mockUseProvidersByCapability.mockReturnValue(
+      providersResult([], { error: new Error("offline") })
+    );
+    const errored = renderHook(() => useModeProviderSetup("video"));
+    expect(errored.result.current.needsSetup).toBe(false);
+  });
+
+  it("is disabled for a null mode (Pi) and never opens onboarding", () => {
+    mockUseProvidersByCapability.mockReturnValue(providersResult([]));
+
+    const { result } = renderHook(() => useModeProviderSetup(null));
+
+    expect(result.current.needsSetup).toBe(false);
+    act(() => result.current.openSetup());
+    expect(mockOpenProviderOnboarding).not.toHaveBeenCalled();
+  });
+});

web/src/components/chat/composer/modeProviderSetup.ts

@@ -0,0 +1,49 @@
+/**
+ * modeProviderSetup — maps a composer media mode to the provider capability it
+ * needs, plus the message shown when no provider with that capability is
+ * configured. Used by the composer's setup banner and its send gate to route
+ * the user into the provider-onboarding dialog instead of letting a send fail.
+ */
+import type { MediaMode } from "../../../stores/MediaGenerationStore";
+import type { OnboardingCapability } from "../../../stores/ProviderOnboardingStore";
+
+/** Backend capability a mode's generation request is served by. Modes that are
+ *  not selectable yet (retake, extend, …) map to null and are never gated. */
+export const capabilityForMode = (
+  mode: MediaMode
+): OnboardingCapability | null => {
+  switch (mode) {
+    case "chat":
+      return "generate_message";
+    case "image":
+    case "image_edit":
+      return "text_to_image";
+    case "video":
+    case "image_to_video":
+      return "text_to_video";
+    case "audio":
+      return "text_to_speech";
+    default:
+      return null;
+  }
+};
+
+/** One-liner shown in the setup banner and passed to the onboarding dialog. */
+export const setupReasonForMode = (mode: MediaMode): string | null => {
+  switch (mode) {
+    case "chat":
+      return "Chat needs a language model. Connect a provider to start.";
+    case "image":
+      return "Generating images needs an image provider. Connect one to continue.";
+    case "image_edit":
+      return "Editing images needs an image provider. Connect one to continue.";
+    case "video":
+      return "Generating videos needs a video provider. Connect one to continue.";
+    case "image_to_video":
+      return "Animating images needs a video provider. Connect one to continue.";
+    case "audio":
+      return "Generating speech needs a text-to-speech provider. Connect one to continue.";
+    default:
+      return null;
+  }
+};

web/src/components/chat/composer/useModeProviderSetup.ts

@@ -0,0 +1,46 @@
+import { useCallback } from "react";
+import { useProvidersByCapability } from "../../../hooks/useProviders";
+import { openProviderOnboarding } from "../../../stores/ProviderOnboardingStore";
+import type { MediaMode } from "../../../stores/MediaGenerationStore";
+import { capabilityForMode, setupReasonForMode } from "./modeProviderSetup";
+
+export interface ModeProviderSetup {
+  /** True when the mode needs a capability no configured provider serves. */
+  needsSetup: boolean;
+  /** Banner copy for the current mode (null when nothing is needed). */
+  reason: string | null;
+  /** Open the provider-onboarding dialog filtered to the mode's capability. */
+  openSetup: () => void;
+}
+
+/**
+ * Watches whether the selected composer mode has a configured provider behind
+ * it. The providers endpoint only lists providers whose credential is present,
+ * so an empty capability-filtered list means the mode cannot run until the
+ * user connects a provider. Pass null (e.g. Pi mode) to disable the check.
+ * While the provider query is loading or errored the check stays quiet — the
+ * connection banner already surfaces fetch errors.
+ */
+export const useModeProviderSetup = (
+  mode: MediaMode | null
+): ModeProviderSetup => {
+  const capability = mode ? capabilityForMode(mode) : null;
+  const { providers, isLoading, error } = useProvidersByCapability(
+    capability ?? "generate_message"
+  );
+  const needsSetup =
+    capability !== null && !isLoading && !error && providers.length === 0;
+  const reason = needsSetup && mode ? setupReasonForMode(mode) : null;
+
+  const openSetup = useCallback(() => {
+    if (!capability) {
+      return;
+    }
+    openProviderOnboarding({
+      capability,
+      reason: (mode && setupReasonForMode(mode)) ?? undefined
+    });
+  }, [capability, mode]);
+
+  return { needsSetup, reason, openSetup };
+};