@shipfox/client-agent 0.2.0

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@shipfox/client-agent",
+  "license": "MIT",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/client/agent"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#*": {
+      "types": "./src/*",
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    },
+    "#test/*": "./test/*"
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./feature": {
+      "development": {
+        "types": "./src/feature.ts",
+        "default": "./src/feature.ts"
+      },
+      "default": {
+        "types": "./dist/feature.d.ts",
+        "default": "./dist/feature.js"
+      }
+    },
+    "./routes/*": {
+      "development": {
+        "types": "./src/routes/*.tsx",
+        "default": "./src/routes/*.tsx"
+      },
+      "default": {
+        "types": "./dist/routes/*.d.ts",
+        "default": "./dist/routes/*.js"
+      }
+    }
+  },
+  "dependencies": {
+    "@swc/helpers": "^0.5.17",
+    "@tanstack/react-form": "^1.32.0",
+    "@tanstack/react-query": "^5.101.0",
+    "@shipfox/api-agent-dto": "3.0.0",
+    "@shipfox/client-api": "0.2.0",
+    "@shipfox/client-shell": "0.2.0",
+    "@shipfox/client-ui": "0.2.0",
+    "@shipfox/react-ui": "0.3.1"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.101.0",
+    "@tanstack/react-router": "^1.170.16",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@argos-ci/cli": "^5.0.0",
+    "@argos-ci/storybook": "^6.0.0",
+    "@storybook/addon-vitest": "^10.3.6",
+    "@storybook/react": "^10.0.0",
+    "@storybook/react-vite": "^10.0.0",
+    "@tailwindcss/vite": "^4.1.13",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.1.11",
+    "@types/react-dom": "^19.1.7",
+    "@tanstack/react-query": "^5.101.0",
+    "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/browser-playwright": "^4.1.5",
+    "happy-dom": "^20.8.3",
+    "jsdom": "^29.0.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "storybook": "^10.0.0",
+    "storybook-addon-pseudo-states": "^10.0.0",
+    "tailwindcss": "^4.1.13",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.5",
+    "yaml": "^2.8.3",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/client-test-setup": "0.0.2",
+    "@shipfox/ts-config": "1.3.8",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/workflow-document": "2.1.0"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "storybook": "storybook dev -p 6010",
+    "storybook:build": "storybook build -o storybook-static",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/components/add-custom-provider-card.tsx

@@ -0,0 +1,32 @@
+import {Icon} from '@shipfox/react-ui/icon';
+import {Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+
+const SURFACE_CLASS =
+  'overflow-hidden rounded-8 border border-border-neutral-base bg-background-neutral-base';
+
+export function AddCustomProviderCard({onConfigure}: {onConfigure: () => void}) {
+  return (
+    <li>
+      <button
+        type="button"
+        className={cn(
+          'group block h-full 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="Configure custom provider"
+        onClick={onConfigure}
+      >
+        <div className="flex min-w-0 items-center justify-between gap-12">
+          <Text size="md" bold className="min-w-0 truncate">
+            Custom
+          </Text>
+          <div className="flex shrink-0 items-center gap-4 text-foreground-neutral-muted transition-colors group-hover:text-foreground-highlight-interactive">
+            <Text size="sm">Configure</Text>
+            <Icon name="chevronRight" className="size-16" />
+          </div>
+        </div>
+      </button>
+    </li>
+  );
+}

package/src/components/agent-workflow-example.test.ts

@@ -0,0 +1,74 @@
+import {workflowDocumentSchema} from '@shipfox/workflow-document';
+import {parse} from 'yaml';
+import {buildAgentWorkflowExample} from './agent-workflow-example.js';
+
+describe('buildAgentWorkflowExample', () => {
+  it.each([
+    {
+      harness: 'pi',
+      providerId: 'anthropic',
+      model: 'claude-opus-4-8',
+      expectedHarness: '        harness: pi',
+      expectedProvider: '        provider: anthropic',
+      expectedModel: '        model: claude-opus-4-8',
+    },
+    {
+      harness: 'claude',
+      providerId: 'anthropic',
+      model: 'anthropic/claude-opus-4.8',
+      expectedHarness: '        harness: claude',
+      expectedProvider: '        provider: anthropic',
+      expectedModel: '        model: anthropic/claude-opus-4.8',
+    },
+    {
+      harness: 'pi',
+      providerId: 'anthropic',
+      model: '@cf/moonshotai/kimi-k2.7-code',
+      expectedHarness: '        harness: pi',
+      expectedProvider: '        provider: anthropic',
+      expectedModel: "        model: '@cf/moonshotai/kimi-k2.7-code'",
+    },
+    {
+      harness: 'pi',
+      providerId: 'provider#beta',
+      model: "model: beta's",
+      expectedHarness: '        harness: pi',
+      expectedProvider: "        provider: 'provider#beta'",
+      expectedModel: "        model: 'model: beta''s'",
+    },
+    {
+      harness: 'pi',
+      providerId: 'true',
+      model: '123',
+      expectedHarness: '        harness: pi',
+      expectedProvider: "        provider: 'true'",
+      expectedModel: "        model: '123'",
+    },
+  ])('builds valid workflow YAML for provider $providerId and model $model', ({
+    harness,
+    providerId,
+    model,
+    expectedHarness,
+    expectedProvider,
+    expectedModel,
+  }) => {
+    const example = buildAgentWorkflowExample({harness, providerId, model});
+
+    const lines = example.code.split('\n');
+    const parsed = parse(example.code);
+    const parsedStep = parsed as {
+      jobs: {agent: {steps: Array<{harness?: unknown; provider?: unknown; model?: unknown}>}};
+    };
+    const result = workflowDocumentSchema.safeParse(parsed);
+
+    expect(result.success).toBe(true);
+    expect(parsedStep.jobs.agent.steps[0]?.harness).toBe(harness);
+    expect(parsedStep.jobs.agent.steps[0]?.provider).toBe(providerId);
+    expect(parsedStep.jobs.agent.steps[0]?.model).toBe(model);
+    expect(lines).toContain(expectedHarness);
+    expect(lines).toContain(expectedProvider);
+    expect(lines).toContain(expectedModel);
+    expect(example.highlightedLineRange).toEqual({startLine: 11, endLine: 13});
+    expect(lines.slice(10, 13)).toEqual([expectedHarness, expectedProvider, expectedModel]);
+  });
+});

package/src/components/agent-workflow-example.ts

@@ -0,0 +1,55 @@
+import type {CodeBlockHighlightedLineRange} from '@shipfox/react-ui/code-block';
+
+const YAML_SAFE_PLAIN_SCALAR_RE = /^[A-Za-z][A-Za-z0-9._/-]*$/;
+const YAML_AMBIGUOUS_PLAIN_SCALAR_RE = /^(?:false|n|no|null|off|on|true|y|yes)$/i;
+
+export interface AgentWorkflowExample {
+  code: string;
+  highlightedLineRange: CodeBlockHighlightedLineRange;
+}
+
+export function buildAgentWorkflowExample({
+  harness,
+  providerId,
+  model,
+}: {
+  harness: string;
+  providerId: string;
+  model: string;
+}): AgentWorkflowExample {
+  const lines = [
+    'name: Agent',
+    'triggers:',
+    '  on_demand:',
+    '    source: manual',
+    '    event: fire',
+    'jobs:',
+    '  agent:',
+    '    runner: ubuntu-latest',
+    '    steps:',
+    '      - name: implement',
+    `        harness: ${formatYamlPlainOrSingleQuotedScalar(harness)}`,
+    `        provider: ${formatYamlPlainOrSingleQuotedScalar(providerId)}`,
+    `        model: ${formatYamlPlainOrSingleQuotedScalar(model)}`,
+    '        prompt: Describe the change you want the agent to make.',
+  ];
+  const harnessLineIndex = lines.findIndex((line) => line.trimStart().startsWith('harness:'));
+  const modelLineIndex = lines.findIndex((line) => line.trimStart().startsWith('model:'));
+
+  return {
+    code: lines.join('\n'),
+    highlightedLineRange: {
+      startLine: harnessLineIndex + 1,
+      endLine: modelLineIndex + 1,
+    },
+  };
+}
+
+function formatYamlPlainOrSingleQuotedScalar(value: string): string {
+  if (!requiresYamlSingleQuotes(value)) return value;
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function requiresYamlSingleQuotes(value: string): boolean {
+  return !YAML_SAFE_PLAIN_SCALAR_RE.test(value) || YAML_AMBIGUOUS_PLAIN_SCALAR_RE.test(value);
+}

package/src/components/available-provider-card.tsx

@@ -0,0 +1,39 @@
+import type {ModelProviderCatalogEntryDto} from '@shipfox/api-agent-dto';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+
+const SURFACE_CLASS =
+  'overflow-hidden rounded-8 border border-border-neutral-base bg-background-neutral-base';
+
+export function AvailableProviderCard({
+  entry,
+  onConfigure,
+}: {
+  entry: ModelProviderCatalogEntryDto;
+  onConfigure: () => 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={`Configure ${entry.label}`}
+        onClick={onConfigure}
+      >
+        <div className="flex min-w-0 items-center justify-between gap-12">
+          <Text size="md" bold className="min-w-0 truncate">
+            {entry.label}
+          </Text>
+          <div className="flex shrink-0 items-center gap-4 text-foreground-neutral-muted transition-colors group-hover:text-foreground-highlight-interactive">
+            <Text size="sm">Configure</Text>
+            <Icon name="chevronRight" className="size-16" />
+          </div>
+        </div>
+      </button>
+    </li>
+  );
+}

package/src/components/available-providers-grid.test.tsx

@@ -0,0 +1,55 @@
+import {render, screen, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {testModelProviderEntries} from '#test/fixtures/model-providers.js';
+import {AvailableProvidersGrid} from './available-providers-grid.js';
+
+describe('AvailableProvidersGrid', () => {
+  test('shows the search field when more than eight providers are available', () => {
+    render(<AvailableProvidersGrid entries={testModelProviderEntries(9)} onSelect={vi.fn()} />);
+
+    expect(screen.getByRole('searchbox', {name: 'Search providers'})).toBeVisible();
+  });
+
+  test('hides the search field when eight or fewer providers are available without a query', () => {
+    render(<AvailableProvidersGrid entries={testModelProviderEntries(8)} onSelect={vi.fn()} />);
+
+    expect(screen.queryByRole('searchbox', {name: 'Search providers'})).not.toBeInTheDocument();
+    expect(screen.getByRole('list', {name: 'Available providers'})).toBeVisible();
+    expect(screen.getByRole('status')).toHaveTextContent('');
+  });
+
+  test('keeps the search field mounted when a query is active and the entries shrink below the threshold', async () => {
+    const user = userEvent.setup();
+    const {rerender} = render(
+      <AvailableProvidersGrid entries={testModelProviderEntries(9)} onSelect={vi.fn()} />,
+    );
+    await user.type(screen.getByRole('searchbox', {name: 'Search providers'}), 'provider 1');
+
+    rerender(<AvailableProvidersGrid entries={testModelProviderEntries(8)} onSelect={vi.fn()} />);
+
+    expect(screen.getByRole('searchbox', {name: 'Search providers'})).toHaveValue('provider 1');
+  });
+
+  test('clear search resets the query and returns focus to the input', async () => {
+    const user = userEvent.setup();
+    render(<AvailableProvidersGrid entries={testModelProviderEntries(9)} onSelect={vi.fn()} />);
+    const search = screen.getByRole('searchbox', {name: 'Search providers'});
+
+    await user.type(search, 'missing');
+    await user.click(screen.getByRole('button', {name: 'Clear search'}));
+
+    expect(search).toHaveValue('');
+    await waitFor(() => expect(search).toHaveFocus());
+    expect(screen.getByRole('button', {name: 'Configure Provider 0'})).toBeVisible();
+  });
+
+  test('announces the filtered result count while a query is active', async () => {
+    const user = userEvent.setup();
+    render(<AvailableProvidersGrid entries={testModelProviderEntries(9)} onSelect={vi.fn()} />);
+
+    await user.type(screen.getByRole('searchbox', {name: 'Search providers'}), 'provider 1');
+
+    expect(screen.getByRole('status')).toHaveTextContent('1 provider matches "provider 1"');
+    expect(screen.getByRole('list', {name: 'Available providers matching search'})).toBeVisible();
+  });
+});

package/src/components/available-providers-grid.tsx

@@ -0,0 +1,106 @@
+import type {ModelProviderCatalogEntryDto} from '@shipfox/api-agent-dto';
+import {Button} from '@shipfox/react-ui/button';
+import {EmptyState} from '@shipfox/react-ui/empty-state';
+import {Icon} from '@shipfox/react-ui/icon';
+import {Input} from '@shipfox/react-ui/input';
+import type {ReactNode} from 'react';
+import {useMemo, useRef, useState} from 'react';
+import {AvailableProviderCard} from './available-provider-card.js';
+import {providerMatchesSearch} from './provider-search.js';
+
+export const PROVIDER_GRID_CLASS = 'grid grid-cols-2 gap-12 max-[760px]:grid-cols-1';
+
+const SEARCH_VISIBILITY_THRESHOLD = 8;
+const MAX_ECHOED_QUERY_LENGTH = 40;
+
+export function AvailableProvidersGrid<TEntry extends ModelProviderCatalogEntryDto>({
+  entries,
+  onSelect,
+  trailingCard,
+  trailingCardMatchesSearch = () => true,
+}: {
+  entries: TEntry[];
+  onSelect: (entry: TEntry) => void;
+  trailingCard?: ReactNode | undefined;
+  trailingCardMatchesSearch?: ((query: string) => boolean) | undefined;
+}) {
+  const [search, setSearch] = useState('');
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const trimmedSearch = search.trim();
+  const filteredEntries = useMemo(
+    () => entries.filter((entry) => providerMatchesSearch(entry, search)),
+    [entries, search],
+  );
+  const trailingCardVisible = trailingCard !== undefined && trailingCardMatchesSearch(search);
+  const visibleCount = filteredEntries.length + (trailingCardVisible ? 1 : 0);
+  const showSearch = entries.length > SEARCH_VISIBILITY_THRESHOLD || trimmedSearch !== '';
+  const providerListLabel =
+    trimmedSearch !== '' ? 'Available providers matching search' : 'Available providers';
+  const resultCountText =
+    trimmedSearch === '' ? '' : providerResultCountText(filteredEntries.length, trimmedSearch);
+
+  function clearSearch() {
+    setSearch('');
+    inputRef.current?.focus();
+  }
+
+  return (
+    <div className="flex flex-col gap-12">
+      {showSearch ? (
+        <Input
+          ref={inputRef}
+          type="search"
+          aria-label="Search providers"
+          placeholder="Search providers..."
+          value={search}
+          iconLeft={<Icon name="searchLine" className="size-16 text-foreground-neutral-muted" />}
+          onChange={(event) => setSearch(event.target.value)}
+        />
+      ) : null}
+
+      {visibleCount > 0 ? (
+        <ul className={PROVIDER_GRID_CLASS} aria-label={providerListLabel}>
+          {filteredEntries.map((entry) => (
+            <AvailableProviderCard
+              key={entry.id}
+              entry={entry}
+              onConfigure={() => onSelect(entry)}
+            />
+          ))}
+          {trailingCardVisible ? trailingCard : null}
+        </ul>
+      ) : (
+        <NoProviderSearchResults search={trimmedSearch} onClear={clearSearch} />
+      )}
+
+      <p role="status" aria-live="polite" className="sr-only">
+        {resultCountText}
+      </p>
+    </div>
+  );
+}
+
+function NoProviderSearchResults({search, onClear}: {search: string; onClear: () => void}) {
+  return (
+    <EmptyState
+      icon="searchLine"
+      title={`No providers match "${truncateQuery(search)}"`}
+      description="Try a different search, or clear it to see all providers."
+      action={
+        <Button size="sm" variant="secondary" onClick={onClear}>
+          Clear search
+        </Button>
+      }
+    />
+  );
+}
+
+function truncateQuery(query: string): string {
+  if (query.length <= MAX_ECHOED_QUERY_LENGTH) return query;
+  return `${query.slice(0, MAX_ECHOED_QUERY_LENGTH - 3)}...`;
+}
+
+function providerResultCountText(count: number, query: string): string {
+  if (count === 1) return `1 provider matches "${query}"`;
+  return `${count} providers match "${query}"`;
+}

package/src/components/change-default-model-form.tsx

@@ -0,0 +1,104 @@
+import type {ModelProviderConfigDto} from '@shipfox/api-agent-dto';
+import {Button} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {fieldError} from '@shipfox/react-ui/form-field';
+import {ModalBody, ModalFooter} from '@shipfox/react-ui/modal';
+import {Text} from '@shipfox/react-ui/typography';
+import {useForm} from '@tanstack/react-form';
+import {useState} from 'react';
+import {useUpdateModelProviderDefaultModelMutation} from '#hooks/api/model-providers.js';
+import {
+  DefaultModelField,
+  defaultModelFormValue,
+  selectedModelForModelPayload,
+} from './default-model-field.js';
+import {modelProviderConfigErrorToFormError} from './form-errors.js';
+import type {SupportedModelProviderCatalogEntry} from './supported-model-provider-catalog-entry.js';
+
+const CHANGE_DEFAULT_MODEL_FORM_ID = 'model-provider-change-default-model-form';
+
+export function ChangeDefaultModelForm({
+  workspaceId,
+  entry,
+  config,
+  onSaved,
+}: {
+  workspaceId: string;
+  entry: SupportedModelProviderCatalogEntry;
+  config: ModelProviderConfigDto;
+  onSaved: () => void;
+}) {
+  const updateDefaultModel = useUpdateModelProviderDefaultModelMutation();
+  const [formError, setFormError] = useState<string | undefined>();
+  const form = useForm({
+    defaultValues: {default_model: defaultModelFormValue(config.default_model)},
+    onSubmit: async ({value}) => {
+      setFormError(undefined);
+      try {
+        await updateDefaultModel.mutateAsync({
+          workspaceId,
+          providerId: entry.id,
+          body: {default_model: selectedModelForModelPayload(value.default_model)},
+        });
+        onSaved();
+      } catch (error) {
+        const mapped = modelProviderConfigErrorToFormError(error);
+        setFormError(mapped.message);
+      }
+    },
+  });
+
+  return (
+    <>
+      <ModalBody className="gap-16">
+        <form
+          id={CHANGE_DEFAULT_MODEL_FORM_ID}
+          className="flex w-full flex-col gap-14"
+          noValidate
+          onSubmit={(event) => {
+            event.preventDefault();
+            event.stopPropagation();
+            void form.handleSubmit();
+          }}
+        >
+          <form.Field
+            name="default_model"
+            validators={{
+              onBlur: ({value}) => (value.trim() ? undefined : 'Default model is required.'),
+              onSubmit: ({value}) => (value.trim() ? undefined : 'Default model is required.'),
+            }}
+          >
+            {(field) => (
+              <DefaultModelField
+                entry={entry}
+                value={field.state.value}
+                error={fieldError(field)}
+                onChange={(event) => field.handleChange(event.target.value)}
+                onBlur={field.handleBlur}
+              />
+            )}
+          </form.Field>
+        </form>
+        {formError ? (
+          <Callout role="alert" type="error">
+            <div className="flex flex-col gap-8">
+              <Text size="sm" bold>
+                Could not save default model
+              </Text>
+              <Text size="sm">{formError}</Text>
+            </div>
+          </Callout>
+        ) : null}
+      </ModalBody>
+      <ModalFooter>
+        <Button
+          type="submit"
+          form={CHANGE_DEFAULT_MODEL_FORM_ID}
+          isLoading={updateDefaultModel.isPending}
+        >
+          Save model
+        </Button>
+      </ModalFooter>
+    </>
+  );
+}

package/src/components/custom-model-provider-api-options.test.ts

@@ -0,0 +1,18 @@
+import {
+  MODEL_PROVIDER_API_OPTIONS,
+  modelProviderApiLabel,
+} from './custom-model-provider-api-options.js';
+
+describe('modelProviderApiLabel', () => {
+  test('returns configured protocol labels', () => {
+    const result = modelProviderApiLabel('anthropic-messages');
+
+    expect(result).toBe('Anthropic Messages');
+  });
+
+  test('covers every protocol option with a label', () => {
+    const labels = MODEL_PROVIDER_API_OPTIONS.map((option) => modelProviderApiLabel(option.value));
+
+    expect(labels).toEqual(MODEL_PROVIDER_API_OPTIONS.map((option) => option.label));
+  });
+});

package/src/components/custom-model-provider-api-options.ts

@@ -0,0 +1,12 @@
+import type {ModelProviderApi} from '@shipfox/api-agent-dto';
+
+export const MODEL_PROVIDER_API_OPTIONS: Array<{value: ModelProviderApi; label: string}> = [
+  {value: 'openai-completions', label: 'OpenAI Chat Completions'},
+  {value: 'openai-responses', label: 'OpenAI Responses'},
+  {value: 'anthropic-messages', label: 'Anthropic Messages'},
+  {value: 'google-generative-ai', label: 'Google Generative AI'},
+];
+
+export function modelProviderApiLabel(api: ModelProviderApi): string {
+  return MODEL_PROVIDER_API_OPTIONS.find((option) => option.value === api)?.label ?? api;
+}