@shipfox/api-agent-dto 2.0.0

package/src/schemas/harness.ts

@@ -0,0 +1,210 @@
+import {type AgentThinking, agentThinkingByHarness, type Harness} from '@shipfox/workflow-document';
+import {type ModelProviderRef, SUPPORTED_MODEL_PROVIDER_IDS} from './model-provider-id.js';
+
+export const PI_HARNESS_TOOL_PACKAGE_NAMES = ['pi-web-access'] as const;
+export const HARNESS_TOOL_PACKAGE_NAMES = [...PI_HARNESS_TOOL_PACKAGE_NAMES] as const;
+
+export type HarnessToolPackageName = (typeof HARNESS_TOOL_PACKAGE_NAMES)[number];
+
+export interface HarnessToolDescriptor {
+  readonly name: string;
+  readonly label: string;
+  readonly source: 'built_in' | 'package';
+  readonly packageName?: HarnessToolPackageName;
+  readonly enabledByDefault: boolean;
+}
+
+export interface HarnessToolDeploymentConfig {
+  readonly pi?: {
+    readonly enabledToolPackages?: readonly HarnessToolPackageName[];
+    readonly webSearchEnabled?: boolean;
+  };
+  readonly claude?: {
+    readonly enabledToolPackages?: readonly HarnessToolPackageName[];
+  };
+}
+
+export interface HarnessDescriptor {
+  readonly id: Harness;
+  readonly label: string;
+  readonly description: string;
+  readonly supportedProviderIds: readonly string[];
+  readonly thinkingLevels: readonly AgentThinking[];
+  readonly defaultThinking: AgentThinking;
+  readonly defaultProviderId: ModelProviderRef;
+  readonly tools: readonly HarnessToolDescriptor[];
+}
+
+export const DEFAULT_PI_ENABLED_TOOL_PACKAGES = 'pi-web-access';
+export const DEFAULT_PI_WEB_SEARCH_ENABLED = true;
+
+export const PI_HARNESS: HarnessDescriptor = {
+  id: 'pi',
+  label: 'pi',
+  description: 'Works with 30+ model providers',
+  supportedProviderIds: SUPPORTED_MODEL_PROVIDER_IDS,
+  thinkingLevels: agentThinkingByHarness.pi.options,
+  defaultThinking: 'xhigh',
+  defaultProviderId: 'anthropic',
+  tools: [
+    builtInTool('read', 'Read'),
+    builtInTool('bash', 'Bash'),
+    builtInTool('edit', 'Edit'),
+    builtInTool('write', 'Write'),
+    builtInTool('grep', 'Grep'),
+    builtInTool('find', 'Find'),
+    builtInTool('ls', 'List'),
+    packageTool('web_search', 'Web search', 'pi-web-access'),
+    packageTool('fetch_content', 'Fetch content', 'pi-web-access'),
+    packageTool('get_search_content', 'Get search content', 'pi-web-access'),
+  ],
+};
+
+export const CLAUDE_HARNESS: HarnessDescriptor = {
+  id: 'claude',
+  label: 'Claude',
+  description: 'Runs on your Anthropic API key',
+  supportedProviderIds: ['anthropic'],
+  thinkingLevels: agentThinkingByHarness.claude.options,
+  defaultThinking: 'xhigh',
+  defaultProviderId: 'anthropic',
+  tools: [
+    builtInTool('Read', 'Read'),
+    builtInTool('Bash', 'Bash'),
+    builtInTool('Edit', 'Edit'),
+    builtInTool('Write', 'Write'),
+    builtInTool('Glob', 'Glob'),
+    builtInTool('Grep', 'Grep'),
+    builtInTool('WebFetch', 'Web fetch'),
+    builtInTool('WebSearch', 'Web search'),
+  ],
+};
+
+const HARNESS_DESCRIPTORS = {
+  pi: PI_HARNESS,
+  claude: CLAUDE_HARNESS,
+} as const satisfies Record<Harness, HarnessDescriptor>;
+
+export function getHarnessDescriptor(id: Harness): HarnessDescriptor {
+  return HARNESS_DESCRIPTORS[id];
+}
+
+export function listHarnessDescriptors(): HarnessDescriptor[] {
+  return Object.values(HARNESS_DESCRIPTORS);
+}
+
+export function harnessSupportsProvider(id: Harness, providerId: string): boolean {
+  return getHarnessDescriptor(id).supportedProviderIds.includes(providerId);
+}
+
+export function listHarnessTools(id: Harness): HarnessToolDescriptor[] {
+  return [...getHarnessDescriptor(id).tools];
+}
+
+export function getHarnessToolDescriptor(
+  id: Harness,
+  toolName: string,
+): HarnessToolDescriptor | undefined {
+  return getHarnessDescriptor(id).tools.find((tool) => tool.name === toolName);
+}
+
+export function listEnabledHarnessTools(
+  id: Harness,
+  deploymentConfig: HarnessToolDeploymentConfig = {},
+): HarnessToolDescriptor[] {
+  return getHarnessDescriptor(id).tools.filter((tool) =>
+    isHarnessToolEnabled(id, tool, deploymentConfig),
+  );
+}
+
+export function harnessSupportsTool(
+  id: Harness,
+  toolName: string,
+  deploymentConfig: HarnessToolDeploymentConfig = {},
+): boolean {
+  const tool = getHarnessToolDescriptor(id, toolName);
+  if (tool === undefined) return false;
+
+  return isHarnessToolEnabled(id, tool, deploymentConfig);
+}
+
+export function buildHarnessToolDeploymentConfig(params: {
+  readonly piEnabledToolPackages?: string | undefined;
+  readonly piWebSearchEnabled?: boolean | undefined;
+}): HarnessToolDeploymentConfig {
+  return {
+    pi: {
+      enabledToolPackages: parsePiEnabledToolPackages(
+        params.piEnabledToolPackages ?? DEFAULT_PI_ENABLED_TOOL_PACKAGES,
+      ),
+      webSearchEnabled: params.piWebSearchEnabled ?? DEFAULT_PI_WEB_SEARCH_ENABLED,
+    },
+    claude: {
+      enabledToolPackages: [],
+    },
+  };
+}
+
+export const DEFAULT_HARNESS_TOOL_DEPLOYMENT_CONFIG = buildHarnessToolDeploymentConfig({});
+
+export function parsePiEnabledToolPackages(value: string): HarnessToolPackageName[] {
+  const packageNames = value
+    .split(',')
+    .map((packageName) => packageName.trim())
+    .filter((packageName) => packageName.length > 0);
+
+  const validPackageNames = new Set<string>(PI_HARNESS_TOOL_PACKAGE_NAMES);
+  const invalidPackageNames = packageNames.filter(
+    (packageName) => !validPackageNames.has(packageName),
+  );
+  if (invalidPackageNames.length > 0) {
+    throw new Error(
+      `AGENT_PI_ENABLED_TOOL_PACKAGES contains unsupported package(s): ${invalidPackageNames.join(
+        ', ',
+      )}. Accepted values: ${PI_HARNESS_TOOL_PACKAGE_NAMES.join(', ')}.`,
+    );
+  }
+
+  return [...new Set(packageNames)] as HarnessToolPackageName[];
+}
+
+function isHarnessToolEnabled(
+  id: Harness,
+  tool: HarnessToolDescriptor,
+  deploymentConfig: HarnessToolDeploymentConfig,
+): boolean {
+  if (!tool.enabledByDefault) return false;
+  if (tool.source === 'built_in') return true;
+
+  const packageName = tool.packageName;
+  if (packageName === undefined) return false;
+
+  const harnessConfig = deploymentConfig[id];
+  if (!harnessConfig?.enabledToolPackages?.includes(packageName)) return false;
+
+  return !isDisabledPiSearchTool(id, tool, deploymentConfig);
+}
+
+function isDisabledPiSearchTool(
+  id: Harness,
+  tool: HarnessToolDescriptor,
+  deploymentConfig: HarnessToolDeploymentConfig,
+): boolean {
+  return (
+    id === 'pi' &&
+    deploymentConfig.pi?.webSearchEnabled === false &&
+    (tool.name === 'web_search' || tool.name === 'get_search_content')
+  );
+}
+
+function builtInTool(name: string, label: string): HarnessToolDescriptor {
+  return {name, label, source: 'built_in', enabledByDefault: true};
+}
+
+function packageTool(
+  name: string,
+  label: string,
+  packageName: HarnessToolPackageName,
+): HarnessToolDescriptor {
+  return {name, label, source: 'package', packageName, enabledByDefault: true};
+}

package/src/schemas/index.ts

@@ -0,0 +1,136 @@
+export {
+  type AgentModelOptionDto,
+  type AgentThinking,
+  agentModelOptionSchema,
+  agentThinkingByHarness,
+  agentThinkingSchema,
+  claudeAgentThinkingSchema,
+  DEFAULT_AGENT_THINKING,
+  DEFAULT_HARNESS,
+  DEFAULT_MODEL_PROVIDER,
+  getModelProviderEntry,
+  type Harness,
+  harnessSchema,
+  listSupportedModelProviders,
+  MODEL_PROVIDER_CATALOG_SEED,
+  type ModelProviderCatalogEntryDto,
+  type ModelProviderCatalogResponseDto,
+  type ModelProviderCatalogSeedDto,
+  type ModelProviderCredentialFieldDto,
+  type ModelProviderSupportStatus,
+  modelProviderCatalogEntrySchema,
+  modelProviderCatalogResponseSchema,
+  modelProviderCatalogSeedSchema,
+  modelProviderCredentialFieldSchema,
+  modelProviderSupportStatusSchema,
+  piAgentThinkingSchema,
+  thinkingLevelsForHarness,
+} from './catalog.js';
+export {
+  type CreateCustomModelProviderBodyDto,
+  type CustomAgentModelDto,
+  type CustomModelProviderConfigDto,
+  type CustomModelProviderHeaderDto,
+  type CustomModelProviderHeaderRequestDto,
+  type CustomModelProviderRuntimeConfigDto,
+  createCustomModelProviderBodySchema,
+  customAgentModelSchema,
+  customModelProviderConfigDtoSchema,
+  customModelProviderHeaderDtoSchema,
+  customModelProviderHeaderRequestSchema,
+  customModelProviderRuntimeConfigSchema,
+  DEFAULT_CUSTOM_MODEL_CONTEXT_WINDOW,
+  DEFAULT_CUSTOM_MODEL_INPUT_IMAGE,
+  DEFAULT_CUSTOM_MODEL_MAX_OUTPUT_TOKENS,
+  DEFAULT_CUSTOM_MODEL_REASONING,
+  type DiscoverCustomModelProviderModelsBodyDto,
+  type DiscoverCustomModelProviderModelsBySlugBodyDto,
+  type DiscoverCustomModelProviderModelsResponseDto,
+  discoverCustomModelProviderModelsBodySchema,
+  discoverCustomModelProviderModelsBySlugBodySchema,
+  discoverCustomModelProviderModelsResponseSchema,
+  MAX_MODEL_COUNT,
+  type ModelProviderApi,
+  modelProviderApiSchema,
+  type UpdateCustomModelProviderBodyDto,
+  type UpdateCustomModelProviderHeaderRequestDto,
+  updateCustomModelProviderBodySchema,
+  updateCustomModelProviderHeaderRequestSchema,
+} from './custom-model-provider.js';
+export {
+  buildHarnessToolDeploymentConfig,
+  CLAUDE_HARNESS,
+  DEFAULT_HARNESS_TOOL_DEPLOYMENT_CONFIG,
+  DEFAULT_PI_ENABLED_TOOL_PACKAGES,
+  DEFAULT_PI_WEB_SEARCH_ENABLED,
+  getHarnessDescriptor,
+  getHarnessToolDescriptor,
+  HARNESS_TOOL_PACKAGE_NAMES,
+  type HarnessDescriptor,
+  type HarnessToolDeploymentConfig,
+  type HarnessToolDescriptor,
+  type HarnessToolPackageName,
+  harnessSupportsProvider,
+  harnessSupportsTool,
+  listEnabledHarnessTools,
+  listHarnessDescriptors,
+  listHarnessTools,
+  PI_HARNESS,
+  PI_HARNESS_TOOL_PACKAGE_NAMES,
+  parsePiEnabledToolPackages,
+} from './harness.js';
+export {
+  AGENT_INTEGRATION_MCP_AUTH,
+  AGENT_INTEGRATION_MCP_ENDPOINT,
+  AGENT_INTEGRATION_MCP_SERVER_NAME,
+  AGENT_INTEGRATION_MCP_TRANSPORT,
+  type AgentIntegrationMcpServerConfigDto,
+  agentIntegrationMcpServerSchema,
+  type MaterializedAgentIntegrationConfigDto,
+  type MaterializedAgentIntegrationToolConfigDto,
+  type MaterializedAgentStepConfigDto,
+  materializedAgentIntegrationSchema,
+  materializedAgentIntegrationToolSchema,
+  materializedAgentStepConfigSchema,
+} from './materialized-agent-step-config.js';
+export {
+  getModelProviderCredentialKeys,
+  type ListModelProviderConfigsResponseDto,
+  listModelProviderConfigsResponseSchema,
+  type ModelProviderConfigDto,
+  type ModelProviderConfigResponseDto,
+  modelProviderConfigDtoSchema,
+  modelProviderConfigResponseSchema,
+  modelProviderCredentialKeysMatch,
+  type SetDefaultModelProviderBodyDto,
+  type SetDefaultModelProviderResponseDto,
+  setDefaultModelProviderBodySchema,
+  setDefaultModelProviderResponseSchema,
+  type UpdateModelProviderConfigBodyDto,
+  type UpdateModelProviderDefaultModelBodyDto,
+  updateModelProviderConfigBodySchema,
+  updateModelProviderDefaultModelBodySchema,
+} from './model-provider-config.js';
+export {
+  isReservedModelProviderId,
+  MODEL_PROVIDER_IDS,
+  MODEL_PROVIDER_SLUG_PATTERN,
+  type ModelProviderId,
+  type ModelProviderRef,
+  modelProviderRefSchema,
+  providerIdSchema,
+  SUPPORTED_MODEL_PROVIDER_IDS,
+  type SupportedModelProviderId,
+  supportedModelProviderIdSchema,
+  UNSUPPORTED_MODEL_PROVIDER_IDS,
+} from './model-provider-id.js';
+export {
+  type AgentRuntimeCredentialsResponseDto,
+  agentRuntimeCredentialsResponseSchema,
+} from './runtime-config.js';
+export {
+  type SetDefaultHarnessBodyDto,
+  type SetDefaultHarnessResponseDto,
+  setDefaultHarnessBodySchema,
+  setDefaultHarnessResponseSchema,
+} from './workspace-defaults.js';

package/src/schemas/materialized-agent-step-config.test.ts

@@ -0,0 +1,198 @@
+import {
+  AGENT_INTEGRATION_MCP_AUTH,
+  AGENT_INTEGRATION_MCP_ENDPOINT,
+  AGENT_INTEGRATION_MCP_SERVER_NAME,
+  AGENT_INTEGRATION_MCP_TRANSPORT,
+  materializedAgentStepConfigSchema,
+} from './materialized-agent-step-config.js';
+
+const materializedIntegration = {
+  connectionId: 'connection-1',
+  connectionSlug: 'github-main',
+  provider: 'github',
+  requiredScope: [{permission: 'issues', access: 'write'}],
+  tools: [
+    {
+      id: 'issue_read',
+      sensitivity: 'read',
+      sensitive: false,
+      requiredScope: [{permission: 'issues', access: 'read'}],
+      inputSchema: {type: 'object'},
+      methods: [
+        {
+          id: 'get',
+          token: 'issue_read.get',
+          description: 'Get issue.',
+          sensitivity: 'read',
+          sensitive: false,
+          requiredScope: [{permission: 'issues', access: 'read'}],
+        },
+      ],
+    },
+    {
+      id: 'issue_write',
+      sensitivity: 'write',
+      sensitive: false,
+      requiredScope: [{permission: 'issues', access: 'write'}],
+      inputSchema: {type: 'object'},
+      outputSchema: {type: 'object'},
+      methods: [
+        {
+          id: 'create',
+          token: 'issue_write.create',
+          description: 'Create issue.',
+          sensitivity: 'write',
+          sensitive: false,
+          requiredScope: [{permission: 'issues', access: 'write'}],
+        },
+      ],
+    },
+  ],
+} as const;
+
+const integrationMcpServer = {
+  name: AGENT_INTEGRATION_MCP_SERVER_NAME,
+  transport: AGENT_INTEGRATION_MCP_TRANSPORT,
+  endpoint: AGENT_INTEGRATION_MCP_ENDPOINT,
+  auth: AGENT_INTEGRATION_MCP_AUTH,
+  integrations: [materializedIntegration],
+} as const;
+
+describe('materializedAgentStepConfigSchema', () => {
+  it('accepts a materialized agent step config', () => {
+    const parsed = materializedAgentStepConfigSchema.parse({
+      harness: 'pi',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'high',
+      tools: ['read', 'web_search'],
+      integrations: [materializedIntegration],
+      mcpServers: [integrationMcpServer],
+      prompt: 'Fix the failing tests.',
+    });
+
+    expect(parsed).toEqual({
+      harness: 'pi',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'high',
+      tools: ['read', 'web_search'],
+      integrations: [materializedIntegration],
+      mcpServers: [integrationMcpServer],
+      prompt: 'Fix the failing tests.',
+    });
+  });
+
+  it('accepts a custom provider ref', () => {
+    const parsed = materializedAgentStepConfigSchema.parse({
+      harness: 'pi',
+      provider: 'local-vllm',
+      model: 'llama-3.1',
+      thinking: 'high',
+      prompt: 'Fix the failing tests.',
+    });
+
+    expect(parsed.provider).toBe('local-vllm');
+  });
+
+  it('defaults a missing harness for stored materialized configs', () => {
+    const parsed = materializedAgentStepConfigSchema.parse({
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'high',
+      prompt: 'Fix the failing tests.',
+    });
+
+    expect(parsed.harness).toBe('pi');
+  });
+
+  it('rejects missing fields and strips extra fields', () => {
+    const missingField = () =>
+      materializedAgentStepConfigSchema.parse({
+        harness: 'pi',
+        provider: 'anthropic',
+        model: 'claude-opus-4-8',
+        prompt: 'Fix the failing tests.',
+      });
+    const extraField = materializedAgentStepConfigSchema.parse({
+      harness: 'pi',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'high',
+      prompt: 'Fix the failing tests.',
+      gate: {success: 'ok'},
+    });
+
+    expect(missingField).toThrow();
+    expect(extraField).toEqual({
+      harness: 'pi',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'high',
+      prompt: 'Fix the failing tests.',
+    });
+  });
+
+  it('rejects malformed tools', () => {
+    const emptyTools = () =>
+      materializedAgentStepConfigSchema.parse({
+        harness: 'pi',
+        provider: 'anthropic',
+        model: 'claude-opus-4-8',
+        thinking: 'high',
+        tools: [],
+        prompt: 'Fix the failing tests.',
+      });
+
+    expect(emptyTools).toThrow();
+  });
+
+  it('rejects malformed integrations', () => {
+    const emptyTools = () =>
+      materializedAgentStepConfigSchema.parse({
+        harness: 'pi',
+        provider: 'anthropic',
+        model: 'claude-opus-4-8',
+        thinking: 'high',
+        integrations: [
+          {
+            connectionId: 'connection-1',
+            connectionSlug: 'github-main',
+            provider: 'github',
+            requiredScope: [],
+            tools: [],
+          },
+        ],
+        prompt: 'Fix the failing tests.',
+      });
+
+    expect(emptyTools).toThrow();
+  });
+
+  it.each([
+    ['empty integrations', {...integrationMcpServer, integrations: []}],
+    ['wrong auth', {...integrationMcpServer, auth: 'provider_token'}],
+    ['wrong transport', {...integrationMcpServer, transport: 'stdio'}],
+    ['missing endpoint', omit(integrationMcpServer, 'endpoint')],
+    ['missing name', omit(integrationMcpServer, 'name')],
+  ])('rejects malformed integration MCP server config for %s', (_caseName, mcpServer) => {
+    const parse = () =>
+      materializedAgentStepConfigSchema.parse({
+        harness: 'pi',
+        provider: 'anthropic',
+        model: 'claude-opus-4-8',
+        thinking: 'high',
+        integrations: [materializedIntegration],
+        mcpServers: [mcpServer],
+        prompt: 'Fix the failing tests.',
+      });
+
+    expect(parse).toThrow();
+  });
+});
+
+function omit<T extends object, K extends keyof T>(object: T, key: K): Omit<T, K> {
+  const copy = {...object};
+  delete copy[key];
+  return copy;
+}

package/src/schemas/materialized-agent-step-config.ts

@@ -0,0 +1,69 @@
+import {agentThinkingSchema, DEFAULT_HARNESS, harnessSchema} from '@shipfox/workflow-document';
+import {z} from 'zod';
+import {modelProviderRefSchema} from './model-provider-id.js';
+
+const agentToolSensitivitySchema = z.enum(['read', 'write']);
+const agentToolJsonSchema = z.record(z.string(), z.unknown());
+const agentToolRequiredScopeSchema = z.array(z.unknown());
+
+export const materializedAgentIntegrationToolMethodSchema = z.strictObject({
+  id: z.string().min(1),
+  token: z.string().min(1),
+  description: z.string().min(1).optional(),
+  sensitivity: agentToolSensitivitySchema,
+  sensitive: z.boolean(),
+  requiredScope: agentToolRequiredScopeSchema,
+});
+
+export const materializedAgentIntegrationToolSchema = z.strictObject({
+  id: z.string().min(1),
+  sensitivity: agentToolSensitivitySchema,
+  sensitive: z.boolean(),
+  requiredScope: agentToolRequiredScopeSchema,
+  inputSchema: agentToolJsonSchema,
+  outputSchema: agentToolJsonSchema.optional(),
+  methods: z.array(materializedAgentIntegrationToolMethodSchema).min(1).optional(),
+});
+
+export const materializedAgentIntegrationSchema = z.strictObject({
+  connectionId: z.string().min(1),
+  connectionSlug: z.string().min(1),
+  provider: z.string().min(1),
+  requiredScope: agentToolRequiredScopeSchema,
+  tools: z.array(materializedAgentIntegrationToolSchema).min(1),
+});
+
+export const AGENT_INTEGRATION_MCP_SERVER_NAME = 'shipfox_integration_tools';
+export const AGENT_INTEGRATION_MCP_ENDPOINT = '/runs/jobs/current/integration-tools/mcp';
+export const AGENT_INTEGRATION_MCP_TRANSPORT = 'http';
+export const AGENT_INTEGRATION_MCP_AUTH = 'lease_token';
+
+export const agentIntegrationMcpServerSchema = z.strictObject({
+  name: z.literal(AGENT_INTEGRATION_MCP_SERVER_NAME),
+  transport: z.literal(AGENT_INTEGRATION_MCP_TRANSPORT),
+  endpoint: z.literal(AGENT_INTEGRATION_MCP_ENDPOINT),
+  auth: z.literal(AGENT_INTEGRATION_MCP_AUTH),
+  integrations: z.array(materializedAgentIntegrationSchema).min(1),
+});
+
+export const materializedAgentStepConfigSchema = z
+  .object({
+    harness: harnessSchema.default(DEFAULT_HARNESS),
+    provider: modelProviderRefSchema,
+    model: z.string().min(1),
+    thinking: agentThinkingSchema,
+    tools: z.array(z.string().min(1)).min(1).optional(),
+    integrations: z.array(materializedAgentIntegrationSchema).min(1).optional(),
+    mcpServers: z.array(agentIntegrationMcpServerSchema).length(1).optional(),
+    prompt: z.string(),
+  })
+  .strip();
+
+export type MaterializedAgentStepConfigDto = z.infer<typeof materializedAgentStepConfigSchema>;
+export type MaterializedAgentIntegrationConfigDto = z.infer<
+  typeof materializedAgentIntegrationSchema
+>;
+export type MaterializedAgentIntegrationToolConfigDto = z.infer<
+  typeof materializedAgentIntegrationToolSchema
+>;
+export type AgentIntegrationMcpServerConfigDto = z.infer<typeof agentIntegrationMcpServerSchema>;