@shipfox/client-agent 0.2.0

package/src/components/form-errors.test.ts

@@ -0,0 +1,159 @@
+import {ApiError} from '@shipfox/client-api';
+import {modelProviderConfigErrorField, modelProviderConfigErrorToFormError} from './form-errors.js';
+
+describe('modelProviderConfigErrorToFormError', () => {
+  test.each([
+    [
+      new ApiError({
+        code: 'provider-validation-failed',
+        message: 'Validation failed',
+        status: 422,
+        details: {provider_id: 'anthropic', message: 'Provider rejected the key.'},
+      }),
+      'Provider rejected the key.',
+    ],
+    [
+      new ApiError({
+        code: 'provider-validation-failed',
+        message: 'Validation failed',
+        status: 422,
+        details: {
+          code: 'provider-validation-failed',
+          message: 'Validation failed',
+          details: {provider_id: 'anthropic', message: 'Provider rejected the key.'},
+        },
+      }),
+      'Provider rejected the key.',
+    ],
+    [
+      new ApiError({
+        code: 'provider-validation-failed',
+        message: 'Validation failed',
+        status: 422,
+      }),
+      'Validation failed',
+    ],
+    [
+      new ApiError({
+        code: 'invalid-credential-fields',
+        message: 'Invalid credentials',
+        status: 422,
+        details: {
+          provider_id: 'azure-openai-responses',
+          expected_keys: ['endpoint', 'api_key'],
+        },
+      }),
+      'Credentials must include exactly these fields: endpoint, api_key.',
+    ],
+    [
+      new ApiError({
+        code: 'invalid-credential-fields',
+        message: 'Invalid credentials',
+        status: 422,
+      }),
+      'Credentials do not match the fields required by this provider.',
+    ],
+    [
+      new ApiError({
+        code: 'provider-unsupported',
+        message: 'Unsupported',
+        status: 422,
+        details: {provider_id: 'amazon-bedrock'},
+      }),
+      'This provider is not supported for workspace-managed credentials.',
+    ],
+    [
+      new ApiError({
+        code: 'invalid-agent-model',
+        message: 'Invalid agent model',
+        status: 422,
+        details: {provider_id: 'anthropic', model: 'missing-model'},
+      }),
+      'Choose a model from the models list.',
+    ],
+    [
+      new ApiError({
+        code: 'provider-not-configured',
+        message: 'Not configured',
+        status: 422,
+        details: {provider_id: 'openai'},
+      }),
+      'Configure this provider before setting it as the default.',
+    ],
+    [
+      new ApiError({code: 'not-found', message: 'Provider config not found', status: 404}),
+      'This custom provider no longer exists. Refresh and try again.',
+    ],
+    [
+      new ApiError({code: 'slug-collision', message: 'Slug collision', status: 409}),
+      'A provider with this id already exists in this workspace.',
+    ],
+    [
+      new ApiError({
+        code: 'egress-denied',
+        message: 'Egress denied',
+        status: 400,
+        details: {target: 'http://localhost:11434', reason: 'private-network'},
+      }),
+      'Requests to http://localhost:11434 are blocked (private-network). On Shipfox Cloud the endpoint must be reachable from the internet. Use a public HTTPS URL for hosted providers.',
+    ],
+    [
+      new ApiError({code: 'invalid-header-keep', message: 'Invalid keep', status: 422}),
+      'A kept secret header no longer exists - re-enter its value.',
+    ],
+    [
+      new ApiError({
+        code: 'stored-secret-base-url-changed',
+        message: 'Stored secrets require rotation',
+        status: 422,
+      }),
+      'Re-enter stored secret values before testing against a different base URL.',
+    ],
+    [
+      new ApiError({
+        code: 'workspace-secret-cap-exceeded',
+        message: 'Secret cap',
+        status: 409,
+        details: {cap: 64},
+      }),
+      'This workspace has reached its secrets limit of 64.',
+    ],
+    [
+      new ApiError({code: 'value-too-large', message: 'Too large', status: 400}),
+      'A key or header value is too large to store.',
+    ],
+    [new ApiError({code: 'unknown-code', message: 'Server copy', status: 422}), 'Server copy'],
+  ])('maps ApiError %s to a form-level alert', (error, expectedMessage) => {
+    const result = modelProviderConfigErrorToFormError(error);
+
+    expect(result).toEqual({kind: 'form', message: expectedMessage});
+  });
+
+  test('routes Error to a form-level alert with the error message', () => {
+    const result = modelProviderConfigErrorToFormError(new Error('boom'));
+
+    expect(result).toEqual({kind: 'form', message: 'boom'});
+  });
+
+  test('falls back to generic copy for non-Error throwables', () => {
+    const result = modelProviderConfigErrorToFormError('weird');
+
+    expect(result).toEqual({kind: 'form', message: 'Something went wrong. Try again.'});
+  });
+
+  test('routes base URL secret reuse errors to the base URL field', () => {
+    const result = modelProviderConfigErrorField(
+      new ApiError({
+        code: 'stored-secret-base-url-changed',
+        message: 'Stored secrets require rotation',
+        status: 422,
+      }),
+    );
+
+    expect(result).toEqual({
+      kind: 'field',
+      field: 'base_url',
+      message: 'Re-enter stored secret values before testing against a different base URL.',
+    });
+  });
+});

package/src/components/form-errors.ts

@@ -0,0 +1,102 @@
+import {ApiError} from '@shipfox/client-api';
+
+export type ModelProviderConfigFormErrorMapping =
+  | {kind: 'form'; message: string}
+  | {kind: 'field'; field: 'slug' | 'base_url' | 'default_model'; message: string};
+
+type ModelProviderErrorDetails = {
+  message?: unknown;
+  provider_id?: unknown;
+  expected_keys?: unknown;
+  reason?: unknown;
+  target?: unknown;
+  cap?: unknown;
+  details?: unknown;
+};
+
+export function modelProviderConfigErrorToFormError(
+  error: unknown,
+): ModelProviderConfigFormErrorMapping {
+  if (error instanceof ApiError) {
+    return {kind: 'form', message: apiErrorMessage(error)};
+  }
+  if (error instanceof Error) {
+    return {kind: 'form', message: error.message};
+  }
+  return {kind: 'form', message: 'Something went wrong. Try again.'};
+}
+
+function apiErrorMessage(error: ApiError): string {
+  const details = modelProviderErrorDetails(error.details);
+
+  if (error.code === 'provider-validation-failed') {
+    return typeof details.message === 'string' ? details.message : error.message;
+  }
+  if (error.code === 'invalid-credential-fields') {
+    const expectedKeys = Array.isArray(details.expected_keys)
+      ? details.expected_keys.filter((key): key is string => typeof key === 'string')
+      : [];
+    if (expectedKeys.length > 0) {
+      return `Credentials must include exactly these fields: ${expectedKeys.join(', ')}.`;
+    }
+    return 'Credentials do not match the fields required by this provider.';
+  }
+  if (error.code === 'invalid-agent-model') {
+    return 'Choose a model from the models list.';
+  }
+  if (error.code === 'slug-collision') {
+    return 'A provider with this id already exists in this workspace.';
+  }
+  if (error.code === 'egress-denied') {
+    const target = typeof details.target === 'string' ? details.target : undefined;
+    const reason = typeof details.reason === 'string' ? details.reason : undefined;
+    const prefix = target && reason ? `Requests to ${target} are blocked (${reason}). ` : '';
+    return `${prefix}On Shipfox Cloud the endpoint must be reachable from the internet. Use a public HTTPS URL for hosted providers.`;
+  }
+  if (error.code === 'invalid-header-keep') {
+    return 'A kept secret header no longer exists - re-enter its value.';
+  }
+  if (error.code === 'stored-secret-base-url-changed') {
+    return 'Re-enter stored secret values before testing against a different base URL.';
+  }
+  if (error.code === 'not-found') {
+    return 'This custom provider no longer exists. Refresh and try again.';
+  }
+  if (error.code === 'workspace-secret-cap-exceeded') {
+    return typeof details.cap === 'number'
+      ? `This workspace has reached its secrets limit of ${details.cap}.`
+      : 'This workspace has reached its secrets limit.';
+  }
+  if (error.code === 'value-too-large') {
+    return 'A key or header value is too large to store.';
+  }
+  if (error.code === 'provider-unsupported') {
+    return 'This provider is not supported for workspace-managed credentials.';
+  }
+  if (error.code === 'provider-not-configured') {
+    return 'Configure this provider before setting it as the default.';
+  }
+  return error.message;
+}
+
+export function modelProviderConfigErrorField(error: unknown): ModelProviderConfigFormErrorMapping {
+  const mapping = modelProviderConfigErrorToFormError(error);
+  if (!(error instanceof ApiError)) return mapping;
+  if (error.code === 'slug-collision') return {...mapping, kind: 'field', field: 'slug'};
+  if (error.code === 'egress-denied') return {...mapping, kind: 'field', field: 'base_url'};
+  if (error.code === 'invalid-agent-model')
+    return {...mapping, kind: 'field', field: 'default_model'};
+  if (error.code === 'stored-secret-base-url-changed')
+    return {...mapping, kind: 'field', field: 'base_url'};
+  return mapping;
+}
+
+function modelProviderErrorDetails(rawDetails: unknown): ModelProviderErrorDetails {
+  if (typeof rawDetails !== 'object' || rawDetails === null) return {};
+
+  const payload = rawDetails as ModelProviderErrorDetails;
+  if (typeof payload.details === 'object' && payload.details !== null) {
+    return payload.details as ModelProviderErrorDetails;
+  }
+  return payload;
+}

package/src/components/harness-availability.test.ts

@@ -0,0 +1,45 @@
+import {getHarnessDescriptor} from '@shipfox/api-agent-dto';
+import {customModelProviderConfig, modelProviderConfig} from '#test/fixtures/model-providers.js';
+import {compatibleHarnessIds, isHarnessAvailable} from './harness-availability.js';
+
+describe('harness availability', () => {
+  test('marks pi available with any builtin provider config', () => {
+    const result = isHarnessAvailable(getHarnessDescriptor('pi'), [
+      modelProviderConfig({provider_id: 'openai'}),
+    ]);
+
+    expect(result).toBe(true);
+  });
+
+  test('marks pi available with only a custom provider config', () => {
+    const result = isHarnessAvailable(getHarnessDescriptor('pi'), [customModelProviderConfig()]);
+
+    expect(result).toBe(true);
+  });
+
+  test('marks claude available only when Anthropic is configured', () => {
+    const openai = isHarnessAvailable(getHarnessDescriptor('claude'), [
+      modelProviderConfig({provider_id: 'openai'}),
+    ]);
+    const anthropic = isHarnessAvailable(getHarnessDescriptor('claude'), [
+      modelProviderConfig({provider_id: 'anthropic'}),
+    ]);
+
+    expect(openai).toBe(false);
+    expect(anthropic).toBe(true);
+  });
+
+  test('marks both harnesses unavailable when no providers are configured', () => {
+    expect(isHarnessAvailable(getHarnessDescriptor('pi'), [])).toBe(false);
+    expect(isHarnessAvailable(getHarnessDescriptor('claude'), [])).toBe(false);
+  });
+
+  test('returns compatible harnesses for builtin and custom providers', () => {
+    expect(compatibleHarnessIds({isCustom: false, providerId: 'anthropic'})).toEqual([
+      'pi',
+      'claude',
+    ]);
+    expect(compatibleHarnessIds({isCustom: false, providerId: 'openai'})).toEqual(['pi']);
+    expect(compatibleHarnessIds({isCustom: true, providerId: 'custom-provider'})).toEqual(['pi']);
+  });
+});

package/src/components/harness-availability.ts

@@ -0,0 +1,35 @@
+import {
+  DEFAULT_HARNESS,
+  type Harness,
+  type HarnessDescriptor,
+  listHarnessDescriptors,
+  type ModelProviderConfigResponseDto,
+} from '@shipfox/api-agent-dto';
+
+export function configSupportsHarness(
+  config: ModelProviderConfigResponseDto,
+  descriptor: HarnessDescriptor,
+): boolean {
+  if (config.kind === 'custom') return descriptor.id === DEFAULT_HARNESS;
+  return descriptor.supportedProviderIds.includes(config.provider_id);
+}
+
+export function isHarnessAvailable(
+  descriptor: HarnessDescriptor,
+  configs: ModelProviderConfigResponseDto[],
+): boolean {
+  return configs.some((config) => configSupportsHarness(config, descriptor));
+}
+
+export function compatibleHarnessIds({
+  isCustom,
+  providerId,
+}: {
+  isCustom: boolean;
+  providerId: string;
+}): Harness[] {
+  if (isCustom) return [DEFAULT_HARNESS];
+  return listHarnessDescriptors()
+    .filter((descriptor) => descriptor.supportedProviderIds.includes(providerId))
+    .map((descriptor) => descriptor.id);
+}

package/src/components/harnesses-section.stories.tsx

@@ -0,0 +1,129 @@
+import type {ModelProviderConfigDto} from '@shipfox/api-agent-dto';
+import {configureApiClient} from '@shipfox/client-api';
+import {Toaster} from '@shipfox/react-ui/toast';
+import type {Meta, StoryObj} from '@storybook/react';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {useMemo} from 'react';
+import {WorkspaceHarnessesSection} from './harnesses-section.js';
+
+const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+
+type Scenario =
+  | 'default-pi'
+  | 'default-claude'
+  | 'claude-unavailable'
+  | 'default-claude-unavailable'
+  | 'loading'
+  | 'error';
+
+interface HarnessesStoryProps {
+  scenario: Scenario;
+}
+
+function HarnessesStory({scenario}: HarnessesStoryProps) {
+  configureApiClient({
+    baseUrl: 'https://api.example.test',
+    fetchImpl: fetchForScenario(scenario),
+  });
+
+  const queryClient = useMemo(
+    () => new QueryClient({defaultOptions: {queries: {retry: false}}}),
+    [],
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <div className="mx-auto w-full max-w-[760px] bg-background-neutral-background p-24">
+        <WorkspaceHarnessesSection workspaceId={WORKSPACE_ID} />
+      </div>
+      <Toaster />
+    </QueryClientProvider>
+  );
+}
+
+const meta = {
+  title: 'Agent/HarnessSettings',
+  component: HarnessesStory,
+  parameters: {layout: 'fullscreen'},
+  args: {scenario: 'default-pi'},
+} satisfies Meta<typeof HarnessesStory>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {};
+
+export const DefaultClaude: Story = {
+  args: {scenario: 'default-claude'},
+};
+
+export const ClaudeUnavailable: Story = {
+  args: {scenario: 'claude-unavailable'},
+};
+
+export const DefaultClaudeUnavailable: Story = {
+  args: {scenario: 'default-claude-unavailable'},
+};
+
+export const Loading: Story = {
+  args: {scenario: 'loading'},
+};
+
+export const ErrorState: Story = {
+  args: {scenario: 'error'},
+};
+
+function fetchForScenario(scenario: Scenario): typeof fetch {
+  return () => {
+    if (scenario === 'loading') return new Promise<Response>(() => undefined);
+    if (scenario === 'error') return Promise.resolve(errorResponse());
+    return Promise.resolve(jsonResponse(configsForScenario(scenario)));
+  };
+}
+
+function configsForScenario(scenario: Scenario) {
+  if (scenario === 'claude-unavailable') {
+    return {
+      configs: [providerConfig({provider_id: 'openai'})],
+      default_provider_id: 'openai',
+      default_harness_id: null,
+    };
+  }
+  if (scenario === 'default-claude-unavailable') {
+    return {
+      configs: [providerConfig({provider_id: 'openai'})],
+      default_provider_id: 'openai',
+      default_harness_id: 'claude',
+    };
+  }
+  return {
+    configs: [providerConfig({provider_id: 'anthropic'})],
+    default_provider_id: 'anthropic',
+    default_harness_id: scenario === 'default-claude' ? 'claude' : null,
+  };
+}
+
+function providerConfig(
+  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,
+  };
+}
+
+function jsonResponse(body: unknown, init: ResponseInit = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {'content-type': 'application/json'},
+    ...init,
+  });
+}
+
+function errorResponse() {
+  return jsonResponse({code: 'server-error'}, {status: 500, statusText: 'Server error'});
+}

package/src/components/harnesses-section.test.tsx

@@ -0,0 +1,188 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {Toaster} from '@shipfox/react-ui/toast';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {render, screen, waitFor, within} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type {ReactElement} from 'react';
+import {
+  AGENT_TEST_WORKSPACE_ID,
+  modelProviderConfig,
+  modelProviderConfigsResponse,
+} from '#test/fixtures/model-providers.js';
+import {WorkspaceHarnessesSection} from './harnesses-section.js';
+
+function jsonResponse(body: unknown, init: ResponseInit = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {'content-type': 'application/json'},
+    ...init,
+  });
+}
+
+function renderHarnesses(element: ReactElement) {
+  const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+  const result = render(
+    <QueryClientProvider client={queryClient}>
+      {element}
+      <Toaster />
+    </QueryClientProvider>,
+  );
+
+  return {...result, queryClient};
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return {promise, resolve};
+}
+
+async function openHarnessActions(user: ReturnType<typeof userEvent.setup>, label: string) {
+  await user.click(screen.getByRole('button', {name: `Open ${label} harness actions`}));
+}
+
+describe('WorkspaceHarnessesSection', () => {
+  test('omits actions on the default row and enables them on an available non-default row', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      baseUrl: 'https://api.example.test',
+      fetchImpl: vi.fn().mockResolvedValue(jsonResponse(modelProviderConfigsResponse())),
+    });
+
+    renderHarnesses(<WorkspaceHarnessesSection workspaceId={AGENT_TEST_WORKSPACE_ID} />);
+
+    expect(await screen.findByText('Harnesses')).toBeVisible();
+    expect(await screen.findByText('Default harness')).toHaveClass('sr-only');
+
+    expect(screen.queryByRole('button', {name: 'Open pi harness actions'})).not.toBeInTheDocument();
+
+    await openHarnessActions(user, 'Claude');
+    expect(screen.getByRole('menuitem', {name: 'Set as default'})).toBeVisible();
+    expect(screen.getByRole('menuitem', {name: 'Set as default'})).not.toHaveAttribute(
+      'data-disabled',
+    );
+  });
+
+  test('disables set as default and shows a warning for an unavailable harness', async () => {
+    const user = userEvent.setup();
+    configureApiClient({
+      baseUrl: 'https://api.example.test',
+      fetchImpl: vi.fn().mockResolvedValue(
+        jsonResponse(
+          modelProviderConfigsResponse({
+            configs: [modelProviderConfig({provider_id: 'openai'})],
+          }),
+        ),
+      ),
+    });
+
+    renderHarnesses(<WorkspaceHarnessesSection workspaceId={AGENT_TEST_WORKSPACE_ID} />);
+
+    const claudeRow = (await screen.findByText('Claude')).closest('li');
+    if (claudeRow === null) throw new Error('Expected Claude row');
+    expect(
+      within(claudeRow).getByText('Configure a compatible model provider to use this harness.'),
+    ).toHaveClass('sr-only');
+
+    await openHarnessActions(user, 'Claude');
+
+    expect(screen.getByRole('menuitem', {name: 'Set as default'})).toHaveAttribute('data-disabled');
+  });
+
+  test('sets the default harness and shows a success toast', async () => {
+    const user = userEvent.setup();
+    let requestBody: unknown;
+    const updateResponse = deferred<Response>();
+    const fetchImpl = vi.fn(async (input: RequestInfo | URL) => {
+      const request = input as Request;
+      if (request.method === 'PUT') {
+        requestBody = await request.clone().json();
+        return await updateResponse.promise;
+      }
+      return jsonResponse(modelProviderConfigsResponse());
+    });
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderHarnesses(<WorkspaceHarnessesSection workspaceId={AGENT_TEST_WORKSPACE_ID} />);
+
+    await screen.findByText('Claude');
+    await openHarnessActions(user, 'Claude');
+    await user.click(screen.getByRole('menuitem', {name: 'Set as default'}));
+
+    await waitFor(() => expect(requestBody).toEqual({harness_id: 'claude'}));
+    expect(screen.getByRole('button', {name: 'Open Claude harness actions'})).toBeDisabled();
+    updateResponse.resolve(jsonResponse({default_harness_id: 'claude'}));
+    expect(
+      await screen.findByText('Claude is now the default harness', {
+        selector: '[data-sonner-toast][data-mounted="true"][data-visible="true"] [data-title]',
+      }),
+    ).toBeVisible();
+  });
+
+  test('shows an inline error when setting the default harness fails', async () => {
+    const user = userEvent.setup();
+    const fetchImpl = vi.fn((input: RequestInfo | URL) => {
+      const request = input as Request;
+      if (request.method === 'PUT') {
+        return Promise.resolve(jsonResponse({code: 'server-error'}, {status: 500}));
+      }
+      return Promise.resolve(jsonResponse(modelProviderConfigsResponse()));
+    });
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderHarnesses(<WorkspaceHarnessesSection workspaceId={AGENT_TEST_WORKSPACE_ID} />);
+
+    await screen.findByText('Claude');
+    await openHarnessActions(user, 'Claude');
+    await user.click(screen.getByRole('menuitem', {name: 'Set as default'}));
+
+    await waitFor(() =>
+      expect(fetchImpl.mock.calls.some(([input]) => (input as Request).method === 'PUT')).toBe(
+        true,
+      ),
+    );
+    expect(await screen.findByText('Could not save default harness. Try again.')).toBeVisible();
+  });
+
+  test('ignores stale default harness failures after changing workspaces', async () => {
+    const user = userEvent.setup();
+    const updateResponse = deferred<Response>();
+    const fetchImpl = vi.fn((input: RequestInfo | URL) => {
+      const request = input as Request;
+      if (request.method === 'PUT') {
+        return updateResponse.promise;
+      }
+      return Promise.resolve(jsonResponse(modelProviderConfigsResponse()));
+    });
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+    const nextWorkspaceId = '22222222-2222-4222-8222-222222222222';
+
+    const result = renderHarnesses(
+      <WorkspaceHarnessesSection workspaceId={AGENT_TEST_WORKSPACE_ID} />,
+    );
+
+    await screen.findByText('Claude');
+    await openHarnessActions(user, 'Claude');
+    await user.click(screen.getByRole('menuitem', {name: 'Set as default'}));
+    await waitFor(() =>
+      expect(screen.getByRole('button', {name: 'Open Claude harness actions'})).toBeDisabled(),
+    );
+
+    result.rerender(
+      <QueryClientProvider client={result.queryClient}>
+        <WorkspaceHarnessesSection workspaceId={nextWorkspaceId} />
+        <Toaster />
+      </QueryClientProvider>,
+    );
+    updateResponse.resolve(jsonResponse({code: 'server-error'}, {status: 500}));
+
+    await waitFor(() =>
+      expect(screen.getByRole('button', {name: 'Open Claude harness actions'})).not.toBeDisabled(),
+    );
+    expect(
+      screen.queryByText('Could not save default harness. Try again.'),
+    ).not.toBeInTheDocument();
+  });
+});