@shipfox/client-agent 0.2.0

package/src/pages/model-provider-onboarding-page.tsx

@@ -0,0 +1,290 @@
+import {
+  DEFAULT_HARNESS,
+  type Harness,
+  type HarnessDescriptor,
+  harnessSupportsProvider,
+  listHarnessDescriptors,
+  type ModelProviderCatalogEntryDto,
+} from '@shipfox/api-agent-dto';
+import {QueryLoadError} from '@shipfox/client-ui';
+import {Button} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Modal, ModalContent, ModalHeader, ModalTitle} from '@shipfox/react-ui/modal';
+import {Skeleton} from '@shipfox/react-ui/skeleton';
+import {toast} from '@shipfox/react-ui/toast';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+import {useEffect, useMemo, useState} from 'react';
+import {AvailableProvidersGrid, PROVIDER_GRID_CLASS} from '#components/available-providers-grid.js';
+import {modelProviderConfigErrorToFormError} from '#components/form-errors.js';
+import {ModelProviderTestAndSaveForm} from '#components/test-and-save-form.js';
+import {
+  useModelProviderCatalogQuery,
+  useSetDefaultHarnessMutation,
+} from '#hooks/api/model-providers.js';
+import {dismissModelProviderOnboarding} from '#state/model-provider-onboarding.js';
+
+const SURFACE_CLASS =
+  'overflow-hidden rounded-8 border border-border-neutral-base bg-background-neutral-base';
+
+export function ModelProviderOnboardingPage({
+  workspaceId,
+  onSkip,
+  onConfigured,
+}: {
+  workspaceId: string;
+  onSkip: () => void;
+  onConfigured: () => void;
+}) {
+  const catalogQuery = useModelProviderCatalogQuery();
+  const setDefaultHarness = useSetDefaultHarnessMutation();
+  const [selectedHarness, setSelectedHarness] = useState<Harness | null>(null);
+  const [selectedEntry, setSelectedEntry] = useState<ModelProviderCatalogEntryDto | null>(null);
+  const [defaultHarnessError, setDefaultHarnessError] = useState<string | undefined>();
+  const [isSettingDefaultHarness, setIsSettingDefaultHarness] = useState(false);
+  const supportedProviders =
+    catalogQuery.data?.providers.filter((provider) => provider.support_status === 'supported') ??
+    [];
+  const filteredProviders = useMemo(() => {
+    if (selectedHarness === null) return [];
+    return supportedProviders.filter((provider) =>
+      harnessSupportsProvider(selectedHarness, provider.id),
+    );
+  }, [selectedHarness, supportedProviders]);
+
+  useEffect(() => {
+    document
+      .getElementById(
+        selectedHarness === null ? 'model-provider-harness-step' : 'model-provider-provider-step',
+      )
+      ?.focus();
+  }, [selectedHarness]);
+
+  function handleSkip() {
+    try {
+      dismissModelProviderOnboarding(workspaceId);
+    } catch {
+      // Skip is best-effort persistence; access to the product must not depend on storage.
+    }
+    onSkip();
+  }
+
+  async function handleProviderSaved() {
+    if (selectedEntry === null || selectedHarness === null) return;
+
+    setDefaultHarnessError(undefined);
+    if (selectedHarness === DEFAULT_HARNESS) {
+      toast.success(`${selectedEntry.label} saved`);
+      onConfigured();
+      return;
+    }
+
+    setIsSettingDefaultHarness(true);
+    try {
+      await setDefaultHarness.mutateAsync({
+        workspaceId,
+        body: {harness_id: selectedHarness},
+      });
+      toast.success(`${selectedEntry.label} saved`);
+      onConfigured();
+    } catch (error) {
+      const mapped = modelProviderConfigErrorToFormError(error);
+      setDefaultHarnessError(mapped.message || 'Could not save default harness. Try again.');
+    } finally {
+      setIsSettingDefaultHarness(false);
+    }
+  }
+
+  const selectedHarnessDescriptor =
+    selectedHarness === null
+      ? null
+      : listHarnessDescriptors().find((harness) => harness.id === selectedHarness);
+  const headingId =
+    selectedHarness === null ? 'model-provider-harness-step' : 'model-provider-provider-step';
+
+  return (
+    <div className="mx-auto flex w-full max-w-[640px] flex-col gap-20">
+      <header className="flex flex-col gap-12">
+        <div className="flex items-start justify-between gap-16 max-[520px]:flex-col max-[520px]:gap-8">
+          <Header id={headingId} variant="h1" tabIndex={-1} className="outline-none">
+            {selectedHarnessDescriptor
+              ? `Configure ${selectedHarnessDescriptor.label}`
+              : 'Choose agent harness'}
+          </Header>
+          <Button type="button" variant="secondary" onClick={handleSkip} className="shrink-0">
+            Skip for now
+          </Button>
+        </div>
+        <Text size="md" className="text-foreground-neutral-muted">
+          {selectedHarnessDescriptor
+            ? `${selectedHarnessDescriptor.label} needs a compatible model provider. Add your own API key, or go back to choose a different harness.`
+            : 'A harness runs agent steps. Choose the engine you want first, then connect a compatible model provider.'}
+        </Text>
+      </header>
+
+      <section aria-labelledby={headingId} className="flex flex-col gap-16">
+        {selectedHarness === null ? (
+          <HarnessPicker onSelect={setSelectedHarness} />
+        ) : (
+          <>
+            <div>
+              <Button type="button" variant="transparent" onClick={() => setSelectedHarness(null)}>
+                Back
+              </Button>
+            </div>
+            <ModelProviderPicker
+              key={selectedHarness}
+              catalogQuery={catalogQuery}
+              supportedProviders={filteredProviders}
+              onSelect={(entry) => {
+                setDefaultHarnessError(undefined);
+                setSelectedEntry(entry);
+              }}
+            />
+          </>
+        )}
+      </section>
+
+      <Modal
+        open={selectedEntry !== null}
+        onOpenChange={(open) => {
+          if (!open && !isSettingDefaultHarness) {
+            setSelectedEntry(null);
+            setDefaultHarnessError(undefined);
+          }
+        }}
+      >
+        <ModalContent aria-describedby={undefined}>
+          <ModalTitle className="sr-only">
+            {selectedEntry ? `Configure ${selectedEntry.label}` : ''}
+          </ModalTitle>
+          <ModalHeader>
+            <Text
+              size="lg"
+              aria-hidden="true"
+              className="overflow-ellipsis overflow-hidden whitespace-nowrap"
+            >
+              {selectedEntry ? `Configure ${selectedEntry.label}` : ''}
+            </Text>
+          </ModalHeader>
+          {isSettingDefaultHarness ? (
+            <div role="status" className="px-20 pb-8">
+              <Text size="sm" className="text-foreground-neutral-muted">
+                Saving harness default...
+              </Text>
+            </div>
+          ) : null}
+          {defaultHarnessError ? (
+            <div className="px-20 pb-8">
+              <Callout role="alert" type="error">
+                <div className="flex flex-col gap-8">
+                  <Text size="sm" bold>
+                    Could not save default harness
+                  </Text>
+                  <Text size="sm">{defaultHarnessError}</Text>
+                </div>
+              </Callout>
+            </div>
+          ) : null}
+          {selectedEntry ? (
+            <ModelProviderTestAndSaveForm
+              workspaceId={workspaceId}
+              entry={selectedEntry}
+              setAsDefaultOnSave
+              onSaved={() => {
+                void handleProviderSaved();
+              }}
+            />
+          ) : null}
+        </ModalContent>
+      </Modal>
+    </div>
+  );
+}
+
+function HarnessPicker({onSelect}: {onSelect: (harness: Harness) => void}) {
+  return (
+    <ul className={PROVIDER_GRID_CLASS} aria-label="Agent harnesses">
+      {listHarnessDescriptors().map((harness) => (
+        <HarnessCard key={harness.id} harness={harness} onChoose={() => onSelect(harness.id)} />
+      ))}
+    </ul>
+  );
+}
+
+function HarnessCard({harness, onChoose}: {harness: HarnessDescriptor; onChoose: () => void}) {
+  return (
+    <li>
+      <button
+        type="button"
+        className={cn(
+          'group block w-full cursor-pointer p-16 text-left outline-none transition-colors hover:bg-background-components-hover focus-visible:shadow-button-neutral-focus',
+          SURFACE_CLASS,
+        )}
+        aria-label={`Choose ${harness.label}`}
+        onClick={onChoose}
+      >
+        <div className="flex min-w-0 items-center justify-between gap-12">
+          <div className="flex min-w-0 flex-col gap-4">
+            <Text size="md" bold className="min-w-0 truncate">
+              {harness.label}
+            </Text>
+            <Text size="sm" className="text-foreground-neutral-muted">
+              {harness.description}
+            </Text>
+          </div>
+          <div className="flex shrink-0 items-center gap-4 text-foreground-neutral-muted transition-colors group-hover:text-foreground-highlight-interactive">
+            <Text size="sm">Choose</Text>
+            <Icon name="chevronRight" className="size-16" />
+          </div>
+        </div>
+      </button>
+    </li>
+  );
+}
+
+function ModelProviderPicker({
+  catalogQuery,
+  supportedProviders,
+  onSelect,
+}: {
+  catalogQuery: ReturnType<typeof useModelProviderCatalogQuery>;
+  supportedProviders: ModelProviderCatalogEntryDto[];
+  onSelect: (entry: ModelProviderCatalogEntryDto) => void;
+}) {
+  if (catalogQuery.isPending) {
+    return (
+      <div role="status" aria-busy="true" aria-label="Loading model providers">
+        <ModelProviderGridSkeleton />
+      </div>
+    );
+  }
+
+  if (catalogQuery.isError && catalogQuery.data === undefined) {
+    return <QueryLoadError query={catalogQuery} subject="model provider catalog" />;
+  }
+
+  if (catalogQuery.data !== undefined && supportedProviders.length === 0) {
+    return (
+      <EmptyState
+        icon="componentLine"
+        title="No providers available to configure"
+        description="Skip for now and add one later from workspace settings."
+      />
+    );
+  }
+
+  return <AvailableProvidersGrid entries={supportedProviders} onSelect={onSelect} />;
+}
+
+function ModelProviderGridSkeleton() {
+  return (
+    <div className={PROVIDER_GRID_CLASS}>
+      {[0, 1, 2, 3].map((card) => (
+        <Skeleton key={card} className="h-136 w-full" />
+      ))}
+    </div>
+  );
+}

package/src/routes/model-provider.tsx

@@ -0,0 +1,20 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {useNavigate, useParams} from '@tanstack/react-router';
+import {ModelProviderOnboardingPage} from '#pages/model-provider-onboarding-page.js';
+
+export default defineRoute({
+  component: () => {
+    const {wid} = useParams({strict: false}) as {wid: string};
+    const navigate = useNavigate();
+    const goToProjectCreation = () => {
+      void navigate({to: '/workspaces/$wid/projects/new', params: {wid}, replace: true});
+    };
+    return (
+      <ModelProviderOnboardingPage
+        workspaceId={wid}
+        onSkip={goToProjectCreation}
+        onConfigured={goToProjectCreation}
+      />
+    );
+  },
+});

package/src/state/model-provider-onboarding.test.ts

@@ -0,0 +1,55 @@
+import {
+  dismissModelProviderOnboarding,
+  isModelProviderOnboardingDismissed,
+} from './model-provider-onboarding.js';
+
+function createStorage(initial: Record<string, string> = {}) {
+  const store = new Map(Object.entries(initial));
+  return {
+    getItem: vi.fn((key: string) => store.get(key) ?? null),
+    setItem: vi.fn((key: string, value: string) => {
+      store.set(key, value);
+    }),
+  };
+}
+
+describe('model provider onboarding dismissed state', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  test('round-trips dismissed workspaces through localStorage', () => {
+    const localStorage = createStorage();
+    vi.stubGlobal('window', {localStorage});
+
+    dismissModelProviderOnboarding('workspace-1');
+
+    expect(isModelProviderOnboardingDismissed('workspace-1')).toBe(true);
+    expect(isModelProviderOnboardingDismissed('workspace-2')).toBe(false);
+  });
+
+  test('keeps dismissed state isolated per workspace', () => {
+    const localStorage = createStorage({
+      'shipfox.modelProviderOnboardingDismissed': JSON.stringify({'workspace-1': true}),
+    });
+    vi.stubGlobal('window', {localStorage});
+
+    expect(isModelProviderOnboardingDismissed('workspace-1')).toBe(true);
+    expect(isModelProviderOnboardingDismissed('workspace-2')).toBe(false);
+  });
+
+  test('is safe without window', () => {
+    expect(isModelProviderOnboardingDismissed('workspace-1')).toBe(false);
+
+    expect(() => dismissModelProviderOnboarding('workspace-1')).not.toThrow();
+  });
+
+  test('treats corrupt JSON as empty state', () => {
+    const localStorage = createStorage({
+      'shipfox.modelProviderOnboardingDismissed': '{',
+    });
+    vi.stubGlobal('window', {localStorage});
+
+    expect(isModelProviderOnboardingDismissed('workspace-1')).toBe(false);
+  });
+});

package/src/state/model-provider-onboarding.ts

@@ -0,0 +1,34 @@
+const MODEL_PROVIDER_ONBOARDING_STORAGE_KEY = 'shipfox.modelProviderOnboardingDismissed';
+
+type DismissedMap = Record<string, true>;
+
+export function isModelProviderOnboardingDismissed(workspaceId: string): boolean {
+  return Boolean(readDismissedMap()[workspaceId]);
+}
+
+export function dismissModelProviderOnboarding(workspaceId: string): void {
+  if (typeof window === 'undefined') return;
+
+  const dismissed = readDismissedMap();
+  dismissed[workspaceId] = true;
+  window.localStorage.setItem(MODEL_PROVIDER_ONBOARDING_STORAGE_KEY, JSON.stringify(dismissed));
+}
+
+function readDismissedMap(): DismissedMap {
+  if (typeof window === 'undefined') return {};
+
+  try {
+    const raw = window.localStorage.getItem(MODEL_PROVIDER_ONBOARDING_STORAGE_KEY);
+    if (!raw) return {};
+    const parsed: unknown = JSON.parse(raw);
+    if (!isDismissedMap(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+function isDismissedMap(value: unknown): value is DismissedMap {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((entry) => entry === true);
+}

package/test/fixtures/model-providers.ts

@@ -0,0 +1,111 @@
+import type {
+  CustomModelProviderConfigDto,
+  ListModelProviderConfigsResponseDto,
+  ModelProviderCatalogEntryDto,
+  ModelProviderCatalogResponseDto,
+  ModelProviderConfigDto,
+} from '@shipfox/api-agent-dto';
+
+export const AGENT_TEST_WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+
+const TEST_PROVIDER_IDS = [
+  'anthropic',
+  'openai',
+  'deepseek',
+  'nvidia',
+  'google',
+  'mistral',
+  'groq',
+  'cerebras',
+  'xai',
+] as const;
+
+export function modelProviderEntry(
+  overrides: Partial<ModelProviderCatalogEntryDto> = {},
+): ModelProviderCatalogEntryDto {
+  return {
+    id: 'anthropic',
+    label: 'Anthropic',
+    support_status: 'supported',
+    default_model: null,
+    credential_fields: [{key: 'api_key', label: 'API key', secret: true}],
+    unsupported_reason: null,
+    models: [{id: 'claude-opus-4-8', label: 'Claude Opus 4.8'}],
+    ...overrides,
+  };
+}
+
+export function unsupportedModelProviderEntry(
+  overrides: Partial<ModelProviderCatalogEntryDto> = {},
+): ModelProviderCatalogEntryDto {
+  return {
+    id: 'amazon-bedrock',
+    label: 'Amazon Bedrock',
+    support_status: 'unsupported',
+    default_model: null,
+    credential_fields: [],
+    unsupported_reason: 'AWS cloud credentials are not supported yet.',
+    models: [],
+    ...overrides,
+  };
+}
+
+export function testModelProviderEntries(count: number): ModelProviderCatalogEntryDto[] {
+  return TEST_PROVIDER_IDS.slice(0, count).map((id, index) =>
+    modelProviderEntry({
+      id,
+      label: `Provider ${index}`,
+      default_model: `model-${index}`,
+      models: [{id: `model-${index}`, label: `Model ${index}`}],
+    }),
+  );
+}
+
+export function modelProviderConfig(
+  overrides: Partial<Omit<ModelProviderConfigDto, 'kind'>> = {},
+): ModelProviderConfigDto {
+  return {
+    kind: 'builtin',
+    provider_id: 'anthropic',
+    default_model: null,
+    created_at: '2026-05-08T00:00:00.000Z',
+    updated_at: '2026-05-08T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+export function customModelProviderConfig(
+  overrides: Partial<Omit<CustomModelProviderConfigDto, 'kind'>> = {},
+): CustomModelProviderConfigDto {
+  return {
+    kind: 'custom',
+    provider_id: 'openai-compatible',
+    display_name: 'OpenAI Compatible',
+    base_url: 'https://models.example.test/v1',
+    api: 'openai-responses',
+    headers: [],
+    secret_header_names: [],
+    default_model: 'custom-model',
+    models: [{id: 'custom-model', label: 'Custom Model'}],
+    created_at: '2026-05-08T00:00:00.000Z',
+    updated_at: '2026-05-08T00:00:00.000Z',
+    ...overrides,
+  };
+}
+
+export function modelProviderCatalogResponse(
+  modelProviders: ModelProviderCatalogEntryDto[] = [modelProviderEntry()],
+): ModelProviderCatalogResponseDto {
+  return {providers: modelProviders};
+}
+
+export function modelProviderConfigsResponse(
+  overrides: Partial<ListModelProviderConfigsResponseDto> = {},
+): ListModelProviderConfigsResponseDto {
+  return {
+    configs: [modelProviderConfig()],
+    default_harness_id: null,
+    default_provider_id: 'anthropic',
+    ...overrides,
+  };
+}

package/test/setup.ts

@@ -0,0 +1,3 @@
+import {installClientDomTestEnv} from '@shipfox/client-test-setup';
+
+installClientDomTestEnv();

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/react",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}