@shipfox/api-agent-dto 2.0.0

package/src/schemas/model-provider-config.test.ts

@@ -0,0 +1,152 @@
+import {
+  getModelProviderCredentialKeys,
+  listModelProviderConfigsResponseSchema,
+  modelProviderConfigDtoSchema,
+  modelProviderCredentialKeysMatch,
+  setDefaultModelProviderBodySchema,
+  setDefaultModelProviderResponseSchema,
+  updateModelProviderConfigBodySchema,
+  updateModelProviderDefaultModelBodySchema,
+} from './model-provider-config.js';
+
+describe('model provider config schemas', () => {
+  it('parses an update body with non-empty credentials', () => {
+    const parsed = updateModelProviderConfigBodySchema.parse({
+      default_model: 'claude-opus-4-8',
+      credentials: {api_key: 'rotated-secret'},
+    });
+
+    expect(parsed.default_model).toBe('claude-opus-4-8');
+    expect(parsed.credentials.api_key).toBe('rotated-secret');
+  });
+
+  it('parses an update body with Latest selected', () => {
+    const parsed = updateModelProviderConfigBodySchema.parse({
+      default_model: null,
+      credentials: {api_key: 'rotated-secret'},
+    });
+
+    expect(parsed.default_model).toBeNull();
+    expect(parsed.credentials.api_key).toBe('rotated-secret');
+  });
+
+  it('rejects an update body with empty credentials', () => {
+    const parse = () => updateModelProviderConfigBodySchema.parse({credentials: {}});
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an update body with empty credential keys', () => {
+    const parse = () =>
+      updateModelProviderConfigBodySchema.parse({
+        credentials: {'': 'rotated-secret'},
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects an update body with empty credential values', () => {
+    const parse = () =>
+      updateModelProviderConfigBodySchema.parse({
+        credentials: {api_key: ''},
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('exposes provider-aware credential key validation for update routes', () => {
+    const parsed = updateModelProviderConfigBodySchema.parse({
+      credentials: {token: 'rotated-secret'},
+    });
+
+    const keysMatch = modelProviderCredentialKeysMatch('openai', parsed.credentials);
+
+    expect(keysMatch).toBe(false);
+  });
+
+  it('parses a model-only update body with Latest selected', () => {
+    const parsed = updateModelProviderDefaultModelBodySchema.parse({default_model: null});
+
+    expect(parsed.default_model).toBeNull();
+  });
+
+  it('parses a model-only update body with an explicit model', () => {
+    const parsed = updateModelProviderDefaultModelBodySchema.parse({
+      default_model: 'claude-haiku-4-5',
+    });
+
+    expect(parsed.default_model).toBe('claude-haiku-4-5');
+  });
+
+  it('returns credential keys for route-layer validation', () => {
+    const keys = getModelProviderCredentialKeys('cloudflare-ai-gateway');
+
+    expect(keys).toEqual(['account_id', 'api_key', 'gateway_id']);
+  });
+
+  it('parses a set-default body for a supported provider', () => {
+    const parsed = setDefaultModelProviderBodySchema.parse({provider_id: 'anthropic'});
+
+    expect(parsed.provider_id).toBe('anthropic');
+  });
+
+  it('parses a set-default body for an unsupported but valid provider ref', () => {
+    const parsed = setDefaultModelProviderBodySchema.parse({provider_id: 'openai-codex'});
+
+    expect(parsed.provider_id).toBe('openai-codex');
+  });
+
+  it('parses a set-default response with a nullable provider', () => {
+    const parsed = setDefaultModelProviderResponseSchema.parse({default_provider_id: null});
+
+    expect(parsed.default_provider_id).toBeNull();
+  });
+
+  it('parses config rows and list responses with a nullable default model provider', () => {
+    const row = {
+      kind: 'builtin',
+      provider_id: 'openai',
+      default_model: null,
+      created_at: '2026-06-27T10:30:00.000Z',
+      updated_at: '2026-06-27T10:45:00.000Z',
+    };
+
+    const parsedRow = modelProviderConfigDtoSchema.parse(row);
+    const parsedList = listModelProviderConfigsResponseSchema.parse({
+      configs: [row],
+      default_harness_id: null,
+      default_provider_id: null,
+    });
+
+    expect(parsedList.default_harness_id).toBeNull();
+    expect(parsedRow.provider_id).toBe('openai');
+    expect(parsedRow.default_model).toBeNull();
+    expect(parsedList.default_provider_id).toBeNull();
+  });
+
+  it('parses custom config rows in list responses', () => {
+    const parsedList = listModelProviderConfigsResponseSchema.parse({
+      configs: [
+        {
+          kind: 'custom',
+          provider_id: 'local-vllm',
+          display_name: 'Local vLLM',
+          api: 'openai-responses',
+          base_url: 'https://llm.example.test/v1',
+          headers: [],
+          secret_header_names: ['authorization'],
+          models: [{id: 'llama-3.1', label: 'Llama 3.1'}],
+          default_model: null,
+          created_at: '2026-06-27T10:30:00.000Z',
+          updated_at: '2026-06-27T10:45:00.000Z',
+        },
+      ],
+      default_harness_id: 'claude',
+      default_provider_id: 'local-vllm',
+    });
+
+    expect(parsedList.configs[0]?.kind).toBe('custom');
+    expect(parsedList.default_harness_id).toBe('claude');
+    expect(parsedList.default_provider_id).toBe('local-vllm');
+  });
+});

package/src/schemas/model-provider-config.ts

@@ -0,0 +1,88 @@
+import {z} from 'zod';
+import {getModelProviderEntry, harnessSchema} from './catalog.js';
+import {customModelProviderConfigDtoSchema} from './custom-model-provider.js';
+import {modelProviderRefSchema, type SupportedModelProviderId} from './model-provider-id.js';
+
+const credentialKeySchema = z.string().min(1);
+const credentialRecordSchema = z.record(credentialKeySchema, z.string().min(1));
+
+export const modelProviderConfigDtoSchema = z.object({
+  kind: z.literal('builtin'),
+  provider_id: modelProviderRefSchema,
+  default_model: z.string().min(1).nullable(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+export type ModelProviderConfigDto = z.infer<typeof modelProviderConfigDtoSchema>;
+
+export const modelProviderConfigResponseSchema = z.discriminatedUnion('kind', [
+  modelProviderConfigDtoSchema,
+  customModelProviderConfigDtoSchema,
+]);
+
+export type ModelProviderConfigResponseDto = z.infer<typeof modelProviderConfigResponseSchema>;
+
+export const listModelProviderConfigsResponseSchema = z.object({
+  configs: z.array(modelProviderConfigResponseSchema),
+  default_provider_id: modelProviderRefSchema.nullable(),
+  default_harness_id: harnessSchema.nullable(),
+});
+
+export type ListModelProviderConfigsResponseDto = z.infer<
+  typeof listModelProviderConfigsResponseSchema
+>;
+
+export const updateModelProviderConfigBodySchema = z.object({
+  default_model: z.string().min(1).nullable().optional(),
+  credentials: credentialRecordSchema.refine((credentials) => Object.keys(credentials).length > 0, {
+    message: 'Credentials must include at least one key.',
+  }),
+  set_as_default: z.boolean().optional(),
+});
+
+export type UpdateModelProviderConfigBodyDto = z.infer<typeof updateModelProviderConfigBodySchema>;
+
+export const updateModelProviderDefaultModelBodySchema = z.object({
+  default_model: z.string().min(1).nullable(),
+});
+
+export type UpdateModelProviderDefaultModelBodyDto = z.infer<
+  typeof updateModelProviderDefaultModelBodySchema
+>;
+
+export const setDefaultModelProviderBodySchema = z.object({
+  provider_id: modelProviderRefSchema,
+});
+
+export type SetDefaultModelProviderBodyDto = z.infer<typeof setDefaultModelProviderBodySchema>;
+
+export const setDefaultModelProviderResponseSchema = z.object({
+  default_provider_id: modelProviderRefSchema.nullable(),
+});
+
+export type SetDefaultModelProviderResponseDto = z.infer<
+  typeof setDefaultModelProviderResponseSchema
+>;
+
+export function getModelProviderCredentialKeys(
+  providerId: SupportedModelProviderId,
+): string[] | undefined {
+  const entry = getModelProviderEntry(providerId);
+  if (entry === undefined || entry.support_status !== 'supported') return undefined;
+  return entry.credential_fields.map((field) => field.key).sort();
+}
+
+export function modelProviderCredentialKeysMatch(
+  providerId: SupportedModelProviderId,
+  credentials: Record<string, string>,
+): boolean {
+  const expectedKeys = getModelProviderCredentialKeys(providerId);
+  if (expectedKeys === undefined) return false;
+  return sameKeys(Object.keys(credentials).sort(), expectedKeys);
+}
+
+function sameKeys(actualKeys: string[], expectedKeys: string[]): boolean {
+  if (actualKeys.length !== expectedKeys.length) return false;
+  return actualKeys.every((key, index) => key === expectedKeys[index]);
+}

package/src/schemas/model-provider-id.ts

@@ -0,0 +1,60 @@
+import {z} from 'zod';
+
+export const SUPPORTED_MODEL_PROVIDER_IDS = [
+  'anthropic',
+  'ant-ling',
+  'azure-openai-responses',
+  'openai',
+  'deepseek',
+  'nvidia',
+  'google',
+  'mistral',
+  'groq',
+  'cerebras',
+  'cloudflare-ai-gateway',
+  'cloudflare-workers-ai',
+  'xai',
+  'openrouter',
+  'vercel-ai-gateway',
+  'zai',
+  'zai-coding-cn',
+  'opencode',
+  'opencode-go',
+  'huggingface',
+  'fireworks',
+  'together',
+  'kimi-coding',
+  'minimax',
+  'minimax-cn',
+  'moonshotai',
+  'moonshotai-cn',
+  'xiaomi',
+  'xiaomi-token-plan-cn',
+  'xiaomi-token-plan-ams',
+  'xiaomi-token-plan-sgp',
+] as const;
+
+export const UNSUPPORTED_MODEL_PROVIDER_IDS = [
+  'amazon-bedrock',
+  'google-vertex',
+  'openai-codex',
+  'github-copilot',
+] as const;
+
+export const MODEL_PROVIDER_IDS = [
+  ...SUPPORTED_MODEL_PROVIDER_IDS,
+  ...UNSUPPORTED_MODEL_PROVIDER_IDS,
+] as const;
+
+export const supportedModelProviderIdSchema = z.enum(SUPPORTED_MODEL_PROVIDER_IDS);
+export const providerIdSchema = z.enum(MODEL_PROVIDER_IDS);
+export const MODEL_PROVIDER_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{1,38}[a-z0-9]$/;
+export const modelProviderRefSchema = z.string().regex(MODEL_PROVIDER_SLUG_PATTERN);
+
+export type SupportedModelProviderId = z.infer<typeof supportedModelProviderIdSchema>;
+export type ModelProviderId = z.infer<typeof providerIdSchema>;
+export type ModelProviderRef = z.infer<typeof modelProviderRefSchema>;
+
+export function isReservedModelProviderId(value: string): boolean {
+  return (MODEL_PROVIDER_IDS as readonly string[]).includes(value);
+}

package/src/schemas/runtime-config.test.ts

@@ -0,0 +1,132 @@
+import {agentRuntimeCredentialsResponseSchema} from './runtime-config.js';
+
+describe('agentRuntimeCredentialsResponseSchema', () => {
+  it('parses runtime credentials for a supported provider', () => {
+    const parsed = agentRuntimeCredentialsResponseSchema.parse({
+      harness: 'pi',
+      provider_id: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'high',
+      credentials: {api_key: 'secret'},
+    });
+
+    expect(parsed.provider_id).toBe('anthropic');
+  });
+
+  it('parses runtime credentials with a custom model provider descriptor', () => {
+    const parsed = agentRuntimeCredentialsResponseSchema.parse({
+      harness: 'pi',
+      provider_id: 'local-vllm',
+      model: 'llama-3.1',
+      thinking: 'high',
+      credentials: {api_key: 'secret', authorization: 'Bearer secret'},
+      custom_provider: {
+        api: 'openai-responses',
+        base_url: 'https://llm.example.test/v1',
+        headers: [{name: 'x-region', value: 'local'}],
+        secret_header_names: ['authorization'],
+        models: [{id: 'llama-3.1', label: 'Llama 3.1'}],
+        requires_api_key: true,
+      },
+    });
+
+    expect(parsed.provider_id).toBe('local-vllm');
+    expect(parsed.custom_provider?.api).toBe('openai-responses');
+  });
+
+  it('rejects a custom model provider descriptor without key intent', () => {
+    const parse = () =>
+      agentRuntimeCredentialsResponseSchema.parse({
+        harness: 'pi',
+        provider_id: 'local-vllm',
+        model: 'llama-3.1',
+        thinking: 'high',
+        credentials: {api_key: 'secret'},
+        custom_provider: {
+          api: 'openai-responses',
+          base_url: 'https://llm.example.test/v1',
+          headers: [],
+          secret_header_names: [],
+          models: [{id: 'llama-3.1', label: 'Llama 3.1'}],
+        },
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects custom model provider runtime credentials without a custom model provider descriptor', () => {
+    const parse = () =>
+      agentRuntimeCredentialsResponseSchema.parse({
+        harness: 'pi',
+        provider_id: 'local-vllm',
+        model: 'llama-3.1',
+        thinking: 'high',
+        credentials: {api_key: 'secret'},
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a response without a model', () => {
+    const parse = () =>
+      agentRuntimeCredentialsResponseSchema.parse({
+        harness: 'pi',
+        provider_id: 'anthropic',
+        thinking: 'high',
+        credentials: {api_key: 'secret'},
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects a response without thinking', () => {
+    const parse = () =>
+      agentRuntimeCredentialsResponseSchema.parse({
+        harness: 'pi',
+        provider_id: 'anthropic',
+        model: 'claude-opus-4-8',
+        credentials: {api_key: 'secret'},
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects runtime credentials for an invalid provider ref', () => {
+    const parse = () =>
+      agentRuntimeCredentialsResponseSchema.parse({
+        harness: 'pi',
+        provider_id: 'bad_provider',
+        model: 'gpt-5.5-pro',
+        thinking: 'high',
+        credentials: {api_key: 'secret'},
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects runtime credentials with an empty key', () => {
+    const parse = () =>
+      agentRuntimeCredentialsResponseSchema.parse({
+        harness: 'pi',
+        provider_id: 'anthropic',
+        model: 'claude-opus-4-8',
+        thinking: 'high',
+        credentials: {'': 'secret'},
+      });
+
+    expect(parse).toThrow();
+  });
+
+  it('rejects runtime credentials with an empty value', () => {
+    const parse = () =>
+      agentRuntimeCredentialsResponseSchema.parse({
+        harness: 'pi',
+        provider_id: 'anthropic',
+        model: 'claude-opus-4-8',
+        thinking: 'high',
+        credentials: {api_key: ''},
+      });
+
+    expect(parse).toThrow();
+  });
+});

package/src/schemas/runtime-config.ts

@@ -0,0 +1,38 @@
+import {agentThinkingSchema, harnessSchema} from '@shipfox/workflow-document';
+import {z} from 'zod';
+import {customModelProviderRuntimeConfigSchema} from './custom-model-provider.js';
+import {isReservedModelProviderId, modelProviderRefSchema} from './model-provider-id.js';
+
+const credentialKeySchema = z.string().min(1);
+const credentialValueSchema = z.string().min(1);
+
+/**
+ * Lease-scoped runtime credentials. The credential values are secrets and must
+ * never be written to logs, traces, client state, or generic catalog surfaces.
+ */
+export const agentRuntimeCredentialsResponseSchema = z
+  .object({
+    harness: harnessSchema,
+    provider_id: modelProviderRefSchema,
+    model: z.string().min(1),
+    thinking: agentThinkingSchema,
+    credentials: z.record(credentialKeySchema, credentialValueSchema),
+    custom_provider: customModelProviderRuntimeConfigSchema.optional(),
+  })
+  .superRefine((response, ctx) => {
+    if (isReservedModelProviderId(response.provider_id) || response.custom_provider !== undefined) {
+      return;
+    }
+
+    ctx.addIssue({
+      code: 'custom',
+      path: ['custom_provider'],
+      message: 'Custom model provider runtime config is required for custom model provider refs.',
+    });
+  });
+
+export type AgentRuntimeCredentialsResponseDto = z.infer<
+  typeof agentRuntimeCredentialsResponseSchema
+>;
+export type {CustomModelProviderRuntimeConfigDto} from './custom-model-provider.js';
+export {customModelProviderRuntimeConfigSchema};

package/src/schemas/workspace-defaults.ts

@@ -0,0 +1,14 @@
+import {z} from 'zod';
+import {harnessSchema} from './catalog.js';
+
+export const setDefaultHarnessBodySchema = z.object({
+  harness_id: harnessSchema,
+});
+
+export type SetDefaultHarnessBodyDto = z.infer<typeof setDefaultHarnessBodySchema>;
+
+export const setDefaultHarnessResponseSchema = z.object({
+  default_harness_id: harnessSchema,
+});
+
+export type SetDefaultHarnessResponseDto = z.infer<typeof setDefaultHarnessResponseSchema>;

package/tsconfig.build.json

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