@shipfox/api-agent 2.0.0

package/src/config.ts

@@ -0,0 +1,75 @@
+import {
+  agentThinkingSchema,
+  buildHarnessToolDeploymentConfig,
+  getModelProviderEntry,
+  SUPPORTED_MODEL_PROVIDER_IDS,
+  type SupportedModelProviderId,
+} from '@shipfox/api-agent-dto';
+import {bool, createConfig, num, str} from '@shipfox/config';
+
+const AGENT_THINKING_CHOICES = agentThinkingSchema.options;
+
+export const config = createConfig({
+  AGENT_DEFAULT_PROVIDER: str({
+    desc: 'Instance-wide default model provider ID used when a workflow and workspace do not choose one. Optional. Use one of the supported model provider IDs from the model provider catalog.',
+    choices: SUPPORTED_MODEL_PROVIDER_IDS,
+    default: undefined,
+  }),
+  AGENT_DEFAULT_PROVIDER_MODEL: str({
+    desc: 'Instance-wide default model ID used when the resolved provider matches AGENT_DEFAULT_PROVIDER and no workflow or workspace model is set. Optional. Use a model ID supported by that provider.',
+    default: undefined,
+  }),
+  AGENT_DEFAULT_PROVIDER_THINKING: str({
+    desc: 'Instance-wide default thinking effort used when the resolved provider matches AGENT_DEFAULT_PROVIDER and no workflow or workspace thinking effort is set. Optional. Accepted values are off, minimal, low, medium, high, and xhigh.',
+    choices: AGENT_THINKING_CHOICES,
+    default: undefined,
+  }),
+  AGENT_DEFAULT_PROVIDER_API_KEY: str({
+    desc: 'API key for the instance default provider. Optional. Must belong to AGENT_DEFAULT_PROVIDER. If you change the default provider, change this key too. Instance defaults support API-key-only providers.',
+    default: undefined,
+  }),
+  AGENT_PROVIDER_VALIDATION_TIMEOUT_MS: num({
+    desc: 'Maximum time in milliseconds to wait for the live provider test request when saving credentials.',
+    default: 10000,
+  }),
+  AGENT_CUSTOM_PROVIDER_ALLOW_PRIVATE_NETWORKS: bool({
+    desc: 'Allows custom model providers to use private, loopback, link-local, metadata, and .internal network targets. Keep this true for local development and self-hosted private networks. Set it to false on cloud instances.',
+    default: true,
+  }),
+  AGENT_CUSTOM_PROVIDER_HOST_DENYLIST: str({
+    desc: 'Comma-separated hosts and IP ranges that custom model providers may not call. Accepts exact hosts, suffix patterns such as .internal.example or *.internal.example, IP literals, and CIDR blocks such as 10.0.0.0/8.',
+    default: '',
+  }),
+  AGENT_PI_ENABLED_TOOL_PACKAGES: str({
+    desc: 'Comma-separated optional Pi tool packages enabled for this deployment. Defaults to pi-web-access so Pi web access is available. Set it to an empty value to enable only Pi built-in tools. Accepted values: pi-web-access.',
+    default: 'pi-web-access',
+  }),
+  AGENT_PI_WEB_SEARCH_ENABLED: bool({
+    desc: 'Enables Pi web search tools when pi-web-access is enabled. Set it to false to disable web_search and get_search_content while keeping fetch_content available.',
+    default: true,
+  }),
+});
+
+assertInstanceDefaultModelProviderApiKeyConfig();
+
+export const harnessToolDeploymentConfig = buildHarnessToolDeploymentConfig({
+  piEnabledToolPackages: config.AGENT_PI_ENABLED_TOOL_PACKAGES,
+  piWebSearchEnabled: config.AGENT_PI_WEB_SEARCH_ENABLED,
+});
+
+function assertInstanceDefaultModelProviderApiKeyConfig(): void {
+  if (!config.AGENT_DEFAULT_PROVIDER_API_KEY) return;
+  if (!config.AGENT_DEFAULT_PROVIDER) {
+    throw new Error('AGENT_DEFAULT_PROVIDER_API_KEY requires AGENT_DEFAULT_PROVIDER to be set.');
+  }
+
+  const credentialFields =
+    getModelProviderEntry(config.AGENT_DEFAULT_PROVIDER as SupportedModelProviderId)
+      ?.credential_fields ?? [];
+  const field = credentialFields[0];
+  if (credentialFields.length === 1 && field?.key === 'api_key' && field.secret) return;
+
+  throw new Error(
+    'AGENT_DEFAULT_PROVIDER_API_KEY requires AGENT_DEFAULT_PROVIDER to use exactly one secret api_key credential field.',
+  );
+}

package/src/core/catalog-registry.test.ts

@@ -0,0 +1,48 @@
+import {getModels, getProviders, type KnownProvider} from '@earendil-works/pi-ai';
+import {
+  getModelProviderEntry,
+  MODEL_PROVIDER_CATALOG_SEED,
+  MODEL_PROVIDER_IDS,
+  type ModelProviderId,
+  SUPPORTED_MODEL_PROVIDER_IDS,
+} from '@shipfox/api-agent-dto';
+
+const STORE_COMPATIBLE_CREDENTIAL_KEY_PATTERN = /^[a-z_][a-z0-9_]*$/;
+
+describe('model provider catalog registry', () => {
+  it('keeps catalog provider ids synced with the pinned Pi provider registry', () => {
+    const catalogModelProviderIds = [...MODEL_PROVIDER_IDS].sort();
+    const piModelProviderIds = getProviders().sort();
+
+    expect(catalogModelProviderIds).toEqual(piModelProviderIds);
+  });
+
+  it('keeps supported catalog default models present in the pinned Pi model registry', () => {
+    const supportedEntries = MODEL_PROVIDER_CATALOG_SEED.filter(
+      (entry) => entry.support_status === 'supported',
+    );
+
+    const missingDefaults = supportedEntries.flatMap((entry) => {
+      const piModels = getModels(entry.id as KnownProvider);
+      const defaultExists = piModels.some((model) => model.id === entry.default_model);
+      return defaultExists ? [] : [formatMissingDefault(entry.id, entry.default_model)];
+    });
+
+    expect(missingDefaults).toEqual([]);
+  });
+
+  it('keeps supported credential field keys compatible with the agent secrets namespace', () => {
+    const invalidKeys = SUPPORTED_MODEL_PROVIDER_IDS.flatMap((providerId) => {
+      const entry = getModelProviderEntry(providerId);
+      return (entry?.credential_fields ?? [])
+        .filter((field) => !STORE_COMPATIBLE_CREDENTIAL_KEY_PATTERN.test(field.key))
+        .map((field) => `${providerId}:${field.key}`);
+    });
+
+    expect(invalidKeys).toEqual([]);
+  });
+});
+
+function formatMissingDefault(providerId: ModelProviderId, defaultModel: string | null): string {
+  return `${providerId}:${defaultModel ?? '<null>'}`;
+}

package/src/core/credential-fingerprints.test.ts

@@ -0,0 +1,34 @@
+import {
+  credentialsToStoreValues,
+  storeValuesToRuntimeCredentials,
+} from './credential-fingerprints.js';
+
+describe('credential storage keys', () => {
+  it('maps provider credential keys to uppercase store keys', () => {
+    const values = credentialsToStoreValues('cloudflare-ai-gateway', {
+      api_key: 'cf-secret',
+      account_id: 'account-123',
+      gateway_id: 'gateway-456',
+    });
+
+    expect(values).toEqual({
+      API_KEY: 'cf-secret',
+      ACCOUNT_ID: 'account-123',
+      GATEWAY_ID: 'gateway-456',
+    });
+  });
+
+  it('maps store keys back to provider runtime keys', () => {
+    const credentials = storeValuesToRuntimeCredentials('cloudflare-ai-gateway', {
+      API_KEY: 'cf-secret',
+      ACCOUNT_ID: 'account-123',
+      GATEWAY_ID: 'gateway-456',
+    });
+
+    expect(credentials).toEqual({
+      api_key: 'cf-secret',
+      account_id: 'account-123',
+      gateway_id: 'gateway-456',
+    });
+  });
+});

package/src/core/credential-fingerprints.ts

@@ -0,0 +1,84 @@
+import type {SupportedModelProviderId} from '@shipfox/api-agent-dto';
+import {getModelProviderEntry} from '@shipfox/api-agent-dto';
+import {UnsupportedModelProviderError} from './errors.js';
+
+export function agentSystemNamespace(providerId: string): string {
+  return `system/agent/model-provider/${providerId}`;
+}
+
+export function toStoreKey(fieldKey: string): string {
+  return fieldKey.toUpperCase();
+}
+
+export function customCredentialToStoreKey(fieldKey: string): string {
+  if (fieldKey === 'api_key') return 'API_KEY';
+  if (fieldKey.startsWith('header:'))
+    return `HEADER_${encodeStoreKey(fieldKey.slice('header:'.length))}`;
+  return `CREDENTIAL_${encodeStoreKey(fieldKey)}`;
+}
+
+export function customStoreKeyToRuntimeKey(storeKey: string): string {
+  if (storeKey === 'API_KEY') return 'api_key';
+  if (storeKey.startsWith('HEADER_'))
+    return `header:${decodeStoreKey(storeKey.slice('HEADER_'.length))}`;
+  if (storeKey.startsWith('CREDENTIAL_'))
+    return decodeStoreKey(storeKey.slice('CREDENTIAL_'.length));
+  return storeKey.toLowerCase();
+}
+
+export function customCredentialsToStoreValues(
+  credentials: Record<string, string>,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(credentials).map(([key, value]) => [customCredentialToStoreKey(key), value]),
+  );
+}
+
+export function storeValuesToCustomRuntimeCredentials(
+  values: Record<string, string>,
+): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(values).map(([key, value]) => [customStoreKeyToRuntimeKey(key), value]),
+  );
+}
+
+export function credentialsToStoreValues(
+  providerId: SupportedModelProviderId,
+  credentials: Record<string, string>,
+): Record<string, string> {
+  const entry = getSupportedModelProviderEntry(providerId);
+
+  return Object.fromEntries(
+    entry.credential_fields.map((field) => [toStoreKey(field.key), credentials[field.key] ?? '']),
+  );
+}
+
+export function storeValuesToRuntimeCredentials(
+  providerId: SupportedModelProviderId,
+  values: Record<string, string>,
+): Record<string, string> {
+  const entry = getSupportedModelProviderEntry(providerId);
+
+  return Object.fromEntries(
+    entry.credential_fields.flatMap((field) => {
+      const value = values[toStoreKey(field.key)];
+      return value === undefined ? [] : [[field.key, value]];
+    }),
+  );
+}
+
+function getSupportedModelProviderEntry(providerId: SupportedModelProviderId) {
+  const entry = getModelProviderEntry(providerId);
+  if (entry === undefined || entry.support_status !== 'supported') {
+    throw new UnsupportedModelProviderError(providerId);
+  }
+  return entry;
+}
+
+function encodeStoreKey(value: string): string {
+  return Buffer.from(value, 'utf8').toString('hex').toUpperCase();
+}
+
+function decodeStoreKey(value: string): string {
+  return Buffer.from(value, 'hex').toString('utf8');
+}