@shipfox/client-agent 4.0.0 → 6.0.1

package/src/core/model-provider-management-reducer.test.ts

@@ -0,0 +1,59 @@
+import {type ManagementModal, managementModalReducer} from './model-provider-management-reducer.js';
+import type {BuiltinProviderConfig, CustomProviderConfig, SupportedProvider} from './models.js';
+
+const provider: SupportedProvider = {
+  kind: 'supported',
+  id: 'anthropic',
+  label: 'Anthropic',
+  defaultModel: 'claude-sonnet-4-5',
+  credentialFields: [],
+  models: [],
+};
+
+const builtinConfig: BuiltinProviderConfig = {
+  kind: 'builtin',
+  providerId: 'anthropic',
+  defaultModel: null,
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-01T00:00:00.000Z',
+};
+
+const customConfig: CustomProviderConfig = {
+  kind: 'custom',
+  providerId: 'local',
+  displayName: 'Local',
+  api: 'openai-completions',
+  baseUrl: 'https://example.test/v1',
+  headers: [],
+  secretHeaderNames: [],
+  models: [],
+  defaultModel: null,
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-01T00:00:00.000Z',
+};
+
+describe('managementModalReducer', () => {
+  test('always replaces the current modal with one valid mode', () => {
+    const initial: ManagementModal = {kind: 'configure-builtin', provider};
+
+    const state = managementModalReducer(initial, {type: 'edit-custom', config: customConfig});
+
+    expect(state).toEqual({kind: 'edit-custom', config: customConfig});
+  });
+
+  test.each([
+    {type: 'close'} as const,
+    {type: 'configure-builtin', provider} as const,
+    {type: 'edit-builtin', provider, config: builtinConfig} as const,
+    {type: 'change-default-model', provider, config: builtinConfig} as const,
+    {type: 'create-custom'} as const,
+    {type: 'edit-custom', config: customConfig} as const,
+    {type: 'show-usage', providerId: 'anthropic', initialModel: null} as const,
+  ])('accepts $type from every existing mode', (action) => {
+    const existing: ManagementModal = {kind: 'show-usage', providerId: 'local', initialModel: null};
+
+    const state = managementModalReducer(existing, action);
+
+    expect(state.kind).not.toBeUndefined();
+  });
+});

package/src/core/model-provider-management-reducer.ts

@@ -0,0 +1,72 @@
+import type {BuiltinProviderConfig, CustomProviderConfig, SupportedProvider} from './models.js';
+
+export type ManagementModal =
+  | {readonly kind: 'closed'}
+  | {readonly kind: 'configure-builtin'; readonly provider: SupportedProvider}
+  | {
+      readonly kind: 'edit-builtin';
+      readonly provider: SupportedProvider;
+      readonly config: BuiltinProviderConfig;
+    }
+  | {
+      readonly kind: 'change-default-model';
+      readonly provider: SupportedProvider;
+      readonly config: BuiltinProviderConfig;
+    }
+  | {readonly kind: 'create-custom'}
+  | {readonly kind: 'edit-custom'; readonly config: CustomProviderConfig}
+  | {
+      readonly kind: 'show-usage';
+      readonly providerId: string;
+      readonly initialModel: string | null;
+      readonly restoreFocusToConfiguredProviders?: boolean | undefined;
+    };
+
+export type ManagementModalAction =
+  | {readonly type: 'close'}
+  | {readonly type: 'configure-builtin'; readonly provider: SupportedProvider}
+  | {
+      readonly type: 'edit-builtin';
+      readonly provider: SupportedProvider;
+      readonly config: BuiltinProviderConfig;
+    }
+  | {
+      readonly type: 'change-default-model';
+      readonly provider: SupportedProvider;
+      readonly config: BuiltinProviderConfig;
+    }
+  | {readonly type: 'create-custom'}
+  | {readonly type: 'edit-custom'; readonly config: CustomProviderConfig}
+  | {
+      readonly type: 'show-usage';
+      readonly providerId: string;
+      readonly initialModel: string | null;
+      readonly restoreFocusToConfiguredProviders?: boolean | undefined;
+    };
+
+export function managementModalReducer(
+  _state: ManagementModal,
+  action: ManagementModalAction,
+): ManagementModal {
+  switch (action.type) {
+    case 'close':
+      return {kind: 'closed'};
+    case 'configure-builtin':
+      return {kind: 'configure-builtin', provider: action.provider};
+    case 'edit-builtin':
+      return {kind: 'edit-builtin', provider: action.provider, config: action.config};
+    case 'change-default-model':
+      return {kind: 'change-default-model', provider: action.provider, config: action.config};
+    case 'create-custom':
+      return {kind: 'create-custom'};
+    case 'edit-custom':
+      return {kind: 'edit-custom', config: action.config};
+    case 'show-usage':
+      return {
+        kind: 'show-usage',
+        providerId: action.providerId,
+        initialModel: action.initialModel,
+        restoreFocusToConfiguredProviders: action.restoreFocusToConfiguredProviders ?? false,
+      };
+  }
+}

package/src/core/models.ts

@@ -0,0 +1,143 @@
+export type HarnessId = 'pi' | 'claude';
+export type ProviderApi =
+  | 'openai-completions'
+  | 'openai-responses'
+  | 'anthropic-messages'
+  | 'google-generative-ai';
+
+export interface HarnessDescriptor {
+  readonly id: HarnessId;
+  readonly label: string;
+  readonly description: string;
+  readonly supportedProviderIds: readonly string[];
+}
+
+export interface AgentModel {
+  readonly id: string;
+  readonly label: string;
+  readonly contextWindow?: number | undefined;
+  readonly maxOutputTokens?: number | undefined;
+  readonly inputImage?: boolean | undefined;
+  readonly reasoning?: boolean | undefined;
+}
+
+export interface CredentialField {
+  readonly key: string;
+  readonly label: string;
+  readonly secret: boolean;
+}
+
+export interface SupportedProvider {
+  readonly kind: 'supported';
+  readonly id: string;
+  readonly label: string;
+  readonly defaultModel: string | null;
+  readonly credentialFields: readonly CredentialField[];
+  readonly models: readonly AgentModel[];
+}
+
+export interface UnsupportedProvider {
+  readonly kind: 'unsupported';
+  readonly id: string;
+  readonly label: string;
+  readonly unsupportedReason: string;
+}
+
+export type ProviderCatalogEntry = SupportedProvider | UnsupportedProvider;
+
+export interface BuiltinProviderConfig {
+  readonly kind: 'builtin';
+  readonly providerId: string;
+  readonly defaultModel: string | null;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface ProviderHeader {
+  readonly name: string;
+  readonly value: string;
+}
+
+export interface CustomProviderConfig {
+  readonly kind: 'custom';
+  readonly providerId: string;
+  readonly displayName: string;
+  readonly api: ProviderApi;
+  readonly baseUrl: string;
+  readonly headers: readonly ProviderHeader[];
+  readonly secretHeaderNames: readonly string[];
+  readonly models: readonly AgentModel[];
+  readonly defaultModel: string | null;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export type ProviderConfig = BuiltinProviderConfig | CustomProviderConfig;
+
+export interface ProviderCatalog {
+  readonly providers: readonly ProviderCatalogEntry[];
+}
+
+export interface ProviderConfiguration {
+  readonly configs: readonly ProviderConfig[];
+  readonly defaultHarnessId: HarnessId | null;
+  readonly defaultProviderId: string | null;
+}
+
+export interface DefaultModelProviderSelection {
+  readonly defaultProviderId: string | null;
+}
+
+export interface DefaultHarnessSelection {
+  readonly defaultHarnessId: HarnessId;
+}
+
+export interface ProviderCredentialsCommand {
+  defaultModel?: string | null | undefined;
+  credentials: Record<string, string>;
+  setAsDefault?: boolean | undefined;
+}
+
+export interface CustomProviderHeaderCommand {
+  name: string;
+  value?: string | undefined;
+  secret: boolean;
+  keep?: boolean | undefined;
+}
+
+export interface CustomProviderModelCommand {
+  id: string;
+  label: string;
+  contextWindow?: number | undefined;
+  maxOutputTokens?: number | undefined;
+  inputImage?: boolean | undefined;
+  reasoning?: boolean | undefined;
+}
+
+export interface CreateCustomProviderCommand {
+  slug: string;
+  displayName: string;
+  api: ProviderApi;
+  baseUrl: string;
+  apiKey?: string | undefined;
+  headers?: CustomProviderHeaderCommand[] | undefined;
+  models: CustomProviderModelCommand[];
+  defaultModel?: string | null | undefined;
+}
+
+export interface UpdateCustomProviderCommand {
+  displayName?: string | undefined;
+  api?: ProviderApi | undefined;
+  baseUrl?: string | undefined;
+  apiKey?: string | undefined;
+  headers?: CustomProviderHeaderCommand[] | undefined;
+  models?: CustomProviderModelCommand[] | undefined;
+  defaultModel?: string | null | undefined;
+}
+
+export interface DiscoverProviderModelsCommand {
+  api?: ProviderApi | undefined;
+  baseUrl?: string | undefined;
+  apiKey?: string | undefined;
+  headers?: CustomProviderHeaderCommand[] | undefined;
+}

package/src/core/onboarding-reducer.test.ts

@@ -0,0 +1,44 @@
+import type {SupportedProvider} from './models.js';
+import {initialOnboardingState, onboardingReducer} from './onboarding-reducer.js';
+
+const provider: SupportedProvider = {
+  kind: 'supported',
+  id: 'anthropic',
+  label: 'Anthropic',
+  defaultModel: 'claude',
+  credentialFields: [],
+  models: [],
+};
+
+test('cannot select a provider before selecting a harness', () => {
+  expect(onboardingReducer(initialOnboardingState, {type: 'provider-selected', provider})).toBe(
+    initialOnboardingState,
+  );
+});
+
+test('back steps back one screen at a time, keeping earlier selections', () => {
+  const choosingProvider = onboardingReducer(initialOnboardingState, {
+    type: 'harness-selected',
+    harnessId: 'claude',
+  });
+  const configuring = onboardingReducer(choosingProvider, {type: 'provider-selected', provider});
+  const saving = onboardingReducer(configuring, {type: 'provider-saved'});
+
+  expect(onboardingReducer(saving, {type: 'back'})).toEqual(configuring);
+  expect(onboardingReducer(configuring, {type: 'back'})).toEqual(choosingProvider);
+  expect(onboardingReducer(choosingProvider, {type: 'back'})).toBe(initialOnboardingState);
+  expect(onboardingReducer(initialOnboardingState, {type: 'back'})).toBe(initialOnboardingState);
+});
+
+test('keeps the selected provider while a default-harness request fails', () => {
+  const choosingProvider = onboardingReducer(initialOnboardingState, {
+    type: 'harness-selected',
+    harnessId: 'claude',
+  });
+  const configuring = onboardingReducer(choosingProvider, {type: 'provider-selected', provider});
+  const saving = onboardingReducer(configuring, {type: 'provider-saved'});
+
+  expect(
+    onboardingReducer(saving, {type: 'default-harness-failed', message: 'Try again.'}),
+  ).toEqual({...saving, error: 'Try again.'});
+});

package/src/core/onboarding-reducer.ts

@@ -0,0 +1,64 @@
+import type {HarnessId, SupportedProvider} from './models.js';
+
+export type OnboardingState =
+  | {readonly step: 'choose-harness'}
+  | {readonly step: 'choose-provider'; readonly harnessId: HarnessId}
+  | {
+      readonly step: 'configure-provider';
+      readonly harnessId: HarnessId;
+      readonly provider: SupportedProvider;
+      readonly error?: string | undefined;
+    }
+  | {
+      readonly step: 'saving-default-harness';
+      readonly harnessId: HarnessId;
+      readonly provider: SupportedProvider;
+      readonly error?: string | undefined;
+    };
+
+export type OnboardingAction =
+  | {readonly type: 'harness-selected'; readonly harnessId: HarnessId}
+  | {readonly type: 'back'}
+  | {readonly type: 'provider-selected'; readonly provider: SupportedProvider}
+  | {readonly type: 'provider-saved'}
+  | {readonly type: 'default-harness-failed'; readonly message: string}
+  | {readonly type: 'default-harness-saved'};
+
+export const initialOnboardingState: OnboardingState = {step: 'choose-harness'};
+
+function goBack(state: OnboardingState): OnboardingState {
+  switch (state.step) {
+    case 'choose-harness':
+      return state;
+    case 'choose-provider':
+      return initialOnboardingState;
+    case 'configure-provider':
+      return {step: 'choose-provider', harnessId: state.harnessId};
+    case 'saving-default-harness':
+      return {step: 'configure-provider', harnessId: state.harnessId, provider: state.provider};
+  }
+}
+
+export function onboardingReducer(
+  state: OnboardingState,
+  action: OnboardingAction,
+): OnboardingState {
+  switch (action.type) {
+    case 'harness-selected':
+      return {step: 'choose-provider', harnessId: action.harnessId};
+    case 'back':
+      return goBack(state);
+    case 'provider-selected':
+      return state.step === 'choose-provider'
+        ? {step: 'configure-provider', harnessId: state.harnessId, provider: action.provider}
+        : state;
+    case 'provider-saved':
+      return state.step === 'configure-provider'
+        ? {step: 'saving-default-harness', harnessId: state.harnessId, provider: state.provider}
+        : state;
+    case 'default-harness-failed':
+      return state.step === 'saving-default-harness' ? {...state, error: action.message} : state;
+    case 'default-harness-saved':
+      return initialOnboardingState;
+  }
+}

package/src/core/provider-policy.ts

@@ -0,0 +1,53 @@
+import type {
+  HarnessDescriptor,
+  ProviderCatalogEntry,
+  ProviderConfig,
+  SupportedProvider,
+} from './models.js';
+
+export function isSupportedProvider(entry: ProviderCatalogEntry): entry is SupportedProvider {
+  return entry.kind === 'supported';
+}
+
+export function supportsProvider(harness: HarnessDescriptor, providerId: string): boolean {
+  return harness.supportedProviderIds.includes(providerId);
+}
+
+export function availableProviders(
+  catalog: readonly ProviderCatalogEntry[],
+  configs: readonly ProviderConfig[],
+): SupportedProvider[] {
+  const configuredIds = new Set(configs.map((config) => config.providerId));
+  return catalog.filter(isSupportedProvider).filter((provider) => !configuredIds.has(provider.id));
+}
+
+export function providerMatchesSearch(entry: SupportedProvider, query: string): boolean {
+  const needle = query.trim().toLocaleLowerCase();
+  if (!needle) return true;
+  const terms = [
+    entry.id,
+    entry.label,
+    ...entry.models.flatMap((model) => [model.id, model.label]),
+  ];
+  return terms.some((term) => term.toLocaleLowerCase().includes(needle));
+}
+
+export function customProviderCardMatchesSearch(query: string): boolean {
+  const needle = query.trim().toLocaleLowerCase();
+  if (!needle) return true;
+  return 'custom provider openai anthropic google endpoint https public'.includes(needle);
+}
+
+export function deriveProviderSlug(displayName: string): string {
+  return displayName
+    .trim()
+    .toLocaleLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+const PROVIDER_SLUG_RE = /^[a-z][a-z0-9-]{1,62}$/;
+
+export function isProviderSlugValid(slug: string): boolean {
+  return PROVIDER_SLUG_RE.test(slug);
+}

package/src/feature.ts

@@ -1,4 +1,14 @@
-import {defineClientFeature} from '@shipfox/client-shell';
+import {defineClientFeature, type SettingsSectionEntry} from '@shipfox/client-shell';
+
+export const agentSettingsSections = [
+  {
+    id: 'settings.agents',
+    pathSegment: 'agents',
+    label: 'Agents',
+    icon: 'robot2Line',
+    order: 400,
+  },
+] as const satisfies readonly SettingsSectionEntry[];
 
 export const agentFeature = defineClientFeature({
   id: 'shipfox.agent',
@@ -8,5 +18,11 @@ export const agentFeature = defineClientFeature({
       parent: 'workspaceLayout',
       impl: '@shipfox/client-agent/routes/model-provider',
     },
+    {
+      path: '/workspaces/$wid/settings/agents',
+      parent: 'workspaceSettings',
+      impl: '@shipfox/client-agent/routes/agents-settings',
+    },
   ],
+  settingsSections: agentSettingsSections,
 });

package/src/hooks/api/model-provider-command-mapper.ts

@@ -0,0 +1,122 @@
+import type {
+  CreateCustomModelProviderBodyDto,
+  DiscoverCustomModelProviderModelsBodyDto,
+  DiscoverCustomModelProviderModelsBySlugBodyDto,
+  SetDefaultHarnessBodyDto,
+  SetDefaultModelProviderBodyDto,
+  UpdateCustomModelProviderBodyDto,
+  UpdateModelProviderConfigBodyDto,
+  UpdateModelProviderDefaultModelBodyDto,
+} from '@shipfox/api-agent-dto';
+import type {
+  CreateCustomProviderCommand,
+  CustomProviderHeaderCommand,
+  CustomProviderModelCommand,
+  DiscoverProviderModelsCommand,
+  ProviderCredentialsCommand,
+  UpdateCustomProviderCommand,
+} from '#core/models.js';
+
+export function toProviderCredentialsBody(
+  command: ProviderCredentialsCommand,
+): UpdateModelProviderConfigBodyDto {
+  return {
+    ...(command.defaultModel === undefined ? {} : {default_model: command.defaultModel}),
+    credentials: command.credentials,
+    ...(command.setAsDefault ? {set_as_default: true} : {}),
+  };
+}
+
+export function toDefaultModelBody(
+  defaultModel: string | null,
+): UpdateModelProviderDefaultModelBodyDto {
+  return {default_model: defaultModel};
+}
+
+export function toDefaultProviderBody(providerId: string): SetDefaultModelProviderBodyDto {
+  return {provider_id: providerId};
+}
+
+export function toDefaultHarnessBody(harnessId: 'pi' | 'claude'): SetDefaultHarnessBodyDto {
+  return {harness_id: harnessId};
+}
+
+export function toCreateCustomProviderBody(
+  command: CreateCustomProviderCommand,
+): CreateCustomModelProviderBodyDto {
+  return {
+    slug: command.slug,
+    display_name: command.displayName,
+    api: command.api,
+    base_url: command.baseUrl,
+    ...(command.apiKey ? {api_key: command.apiKey} : {}),
+    ...(command.headers?.length ? {headers: command.headers.map(toCreateHeader)} : {}),
+    models: command.models.map(toModel),
+    ...(command.defaultModel ? {default_model: command.defaultModel} : {}),
+  };
+}
+
+export function toUpdateCustomProviderBody(
+  command: UpdateCustomProviderCommand,
+): UpdateCustomModelProviderBodyDto {
+  return {
+    ...(command.displayName === undefined ? {} : {display_name: command.displayName}),
+    ...(command.api === undefined ? {} : {api: command.api}),
+    ...(command.baseUrl === undefined ? {} : {base_url: command.baseUrl}),
+    ...(command.apiKey === undefined ? {} : {api_key: command.apiKey}),
+    ...(command.headers === undefined ? {} : {headers: command.headers.map(toUpdateHeader)}),
+    ...(command.models === undefined ? {} : {models: command.models.map(toModel)}),
+    ...(command.defaultModel === undefined ? {} : {default_model: command.defaultModel}),
+  };
+}
+
+export function toDiscoverModelsBody(
+  command: DiscoverProviderModelsCommand,
+): DiscoverCustomModelProviderModelsBodyDto {
+  if (command.api === undefined || command.baseUrl === undefined) {
+    throw new Error('Model discovery requires an API and base URL.');
+  }
+  return {
+    api: command.api,
+    base_url: command.baseUrl,
+    ...(command.apiKey ? {api_key: command.apiKey} : {}),
+    ...(command.headers?.length
+      ? {headers: command.headers.flatMap(({name, value}) => (value ? [{name, value}] : []))}
+      : {}),
+  };
+}
+
+export function toDiscoverModelsBySlugBody(
+  command: DiscoverProviderModelsCommand,
+): DiscoverCustomModelProviderModelsBySlugBodyDto {
+  return {
+    ...(command.api === undefined ? {} : {api: command.api}),
+    ...(command.baseUrl === undefined ? {} : {base_url: command.baseUrl}),
+    ...(command.apiKey === undefined ? {} : {api_key: command.apiKey}),
+    ...(command.headers === undefined ? {} : {headers: command.headers.map(toUpdateHeader)}),
+  };
+}
+
+function toCreateHeader(header: CustomProviderHeaderCommand) {
+  return {name: header.name, value: header.value ?? '', secret: header.secret};
+}
+
+function toUpdateHeader(header: CustomProviderHeaderCommand) {
+  return {
+    name: header.name,
+    ...(header.value === undefined ? {} : {value: header.value}),
+    secret: header.secret,
+    ...(header.keep ? {keep: true} : {}),
+  };
+}
+
+function toModel(model: CustomProviderModelCommand) {
+  return {
+    id: model.id,
+    label: model.label,
+    ...(model.contextWindow === undefined ? {} : {context_window: model.contextWindow}),
+    ...(model.maxOutputTokens === undefined ? {} : {max_output_tokens: model.maxOutputTokens}),
+    ...(model.inputImage ? {input_image: true} : {}),
+    ...(model.reasoning ? {reasoning: true} : {}),
+  };
+}

package/src/hooks/api/model-provider-mapper.test.ts

@@ -0,0 +1,27 @@
+import {
+  modelProviderCatalogResponse,
+  modelProviderConfigsResponse,
+  modelProviderEntry,
+} from '#test/fixtures/model-providers.js';
+import {toProviderCatalog, toProviderConfiguration} from './model-provider-mapper.js';
+
+test('maps provider catalog entries before they reach the client domain', () => {
+  const catalog = toProviderCatalog(modelProviderCatalogResponse([modelProviderEntry()]));
+
+  expect(catalog.providers).toEqual([
+    expect.objectContaining({
+      kind: 'supported',
+      defaultModel: 'claude-opus-4-8',
+      credentialFields: [{key: 'api_key', label: 'API key', secret: true}],
+    }),
+  ]);
+});
+
+test('maps configuration response defaults and provider config fields', () => {
+  const configuration = toProviderConfiguration(modelProviderConfigsResponse());
+
+  expect(configuration.defaultProviderId).toBe('anthropic');
+  expect(configuration.configs[0]).toEqual(
+    expect.objectContaining({providerId: 'anthropic', defaultModel: null}),
+  );
+});