@mutagent/cli 0.1.226 → 0.1.228

package/dist/bin/cli.js

@@ -2253,6 +2253,442 @@ import { Provider as ProviderCatalogId } from "@mutagent/sdk/models";
 init_sdk_client();
 import chalk8 from "chalk";
 init_errors();
+
+// src/lib/api-format.ts
+init_errors();
+
+// ../mutagent/src/modules/tenancy/providers/catalog.ts
+var apiKeyField = (description) => ({
+  name: "apiKey",
+  label: "API key",
+  required: true,
+  treatment: "secret",
+  validation: { rule: "non-empty-string", minLength: 8 },
+  description
+});
+var baseUrlOverrideField = {
+  name: "baseUrl",
+  label: "Base URL override",
+  required: false,
+  treatment: "plain",
+  validation: { rule: "https-url" },
+  description: "Route requests through a proxy or a regional endpoint instead of the default one."
+};
+var modelAllowListField = {
+  name: "modelAllowList",
+  label: "Model allow-list",
+  required: false,
+  treatment: "plain",
+  validation: { rule: "string-list" },
+  description: "Narrow the models this configuration offers. Entries outside the provider policy are ignored."
+};
+var directApiKeyFields = (keyDescription) => [
+  apiKeyField(keyDescription),
+  baseUrlOverrideField,
+  modelAllowListField
+];
+var azureFields = [
+  {
+    name: "resourceEndpoint",
+    label: "Resource endpoint",
+    required: true,
+    treatment: "plain",
+    validation: { rule: "https-url" },
+    description: "The Azure resource endpoint, e.g. https://my-resource.openai.azure.com."
+  },
+  apiKeyField("The key issued for the Azure resource."),
+  {
+    name: "deploymentName",
+    label: "Deployment name",
+    required: true,
+    treatment: "plain",
+    validation: { rule: "non-empty-string", minLength: 1 },
+    description: "Azure addresses a model by the name given to its deployment, not by model id."
+  },
+  {
+    name: "apiVersion",
+    label: "API version",
+    required: false,
+    treatment: "plain",
+    validation: {
+      rule: "pattern",
+      pattern: "^\\d{4}-\\d{2}-\\d{2}(-preview)?$",
+      hint: "An ISO date, optionally suffixed -preview.",
+      examples: ["2024-08-01-preview", "2023-06-01", "2025-01-01"],
+      counterExamples: ["2024-8-1", "24-08-01", "2024-08-01-beta", "latest"]
+    },
+    description: "Pin the Azure API version. Defaults to the current stable version when omitted."
+  }
+];
+var vertexFields = [
+  {
+    name: "projectId",
+    label: "Project ID",
+    required: true,
+    treatment: "plain",
+    validation: {
+      rule: "pattern",
+      pattern: "^[a-z][a-z0-9-]{4,28}[a-z0-9]$",
+      hint: "A Google Cloud project ID: 6 to 30 lowercase characters, starting with a letter.",
+      examples: ["my-project-123", "abcdef", "my-gcp-project"],
+      counterExamples: ["ab", "My-Project", "1project", "my_project"]
+    },
+    description: "The Google Cloud project that holds the Vertex AI entitlement."
+  },
+  {
+    name: "region",
+    label: "Region",
+    required: true,
+    treatment: "plain",
+    validation: {
+      rule: "pattern",
+      pattern: "^(global|(?:us|europe|asia|australia|northamerica|southamerica|africa|me)-[a-z]+\\d+)$",
+      hint: "A Vertex location: a continent prefix, a direction and an index — or `global`.",
+      examples: [
+        "us-central1",
+        "europe-west4",
+        "europe-west12",
+        "asia-northeast1",
+        "northamerica-northeast1",
+        "southamerica-east1",
+        "australia-southeast1",
+        "africa-south1",
+        "me-central2",
+        "global"
+      ],
+      counterExamples: ["zz-qqqqqq9", "us-central", "US-CENTRAL1", "us_central1", "1-west1"]
+    },
+    description: "The Vertex location the models are served from."
+  },
+  {
+    name: "serviceAccountKey",
+    label: "Service-account credential",
+    required: true,
+    treatment: "secret",
+    validation: { rule: "json-object" },
+    description: "The service-account key JSON granting Vertex AI access to the project."
+  },
+  modelAllowListField
+];
+var PROVIDER_CATALOG = [
+  {
+    id: "openai",
+    label: "OpenAI",
+    kind: "direct",
+    credentialFields: directApiKeyFields("An OpenAI API key, issued from the OpenAI platform."),
+    modelPolicy: {
+      mode: "floor",
+      floor: "5.5",
+      knownMembers: ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5"],
+      summary: "GPT models at or above 5.5. FR-CORE-008 states the floor and then enumerates the members current at writing; the floor is the rule, the enumeration is the snapshot."
+    },
+    description: "GPT models served directly by OpenAI."
+  },
+  {
+    id: "anthropic",
+    label: "Anthropic",
+    kind: "direct",
+    credentialFields: directApiKeyFields("An Anthropic API key, issued from the Anthropic console."),
+    modelPolicy: {
+      mode: "explicit",
+      models: [
+        "claude-opus-5",
+        "claude-sonnet-5",
+        "claude-fable-5",
+        "claude-opus-4-8",
+        "claude-haiku-4-5"
+      ],
+      summary: "The Claude 5 family, plus Opus 4.8 and Haiku 4.5."
+    },
+    description: "Claude models served directly by Anthropic."
+  },
+  {
+    id: "google",
+    label: "Google Gemini",
+    kind: "direct",
+    credentialFields: directApiKeyFields("A Google AI Studio API key."),
+    modelPolicy: {
+      mode: "floor",
+      floor: "3.1",
+      summary: "Gemini 3.1 Pro and above. The floor is 3.1; nothing older is offered."
+    },
+    description: "Gemini models served directly by Google AI Studio."
+  },
+  {
+    id: "moonshot",
+    label: "Moonshot AI",
+    kind: "direct",
+    credentialFields: directApiKeyFields("A Moonshot AI platform API key."),
+    modelPolicy: {
+      mode: "explicit",
+      models: ["kimi-k3"],
+      summary: "Kimi K3, the 1M-context model. The 256K models are all K2-generation and are not offered."
+    },
+    description: "Kimi models served directly by Moonshot AI."
+  },
+  {
+    id: "glm",
+    label: "z.ai (GLM)",
+    kind: "direct",
+    credentialFields: directApiKeyFields("A z.ai API key."),
+    modelPolicy: {
+      mode: "explicit",
+      models: ["glm-5.2"],
+      summary: "GLM-5.2."
+    },
+    description: "GLM models served directly by z.ai."
+  },
+  {
+    id: "deepseek",
+    label: "DeepSeek",
+    kind: "direct",
+    credentialFields: directApiKeyFields("A DeepSeek platform API key."),
+    modelPolicy: {
+      mode: "explicit",
+      models: ["deepseek-v4-flash", "deepseek-v4-pro"],
+      summary: "The DeepSeek V4 pair — Flash and Pro."
+    },
+    description: "DeepSeek models served directly by DeepSeek."
+  },
+  {
+    id: "xai",
+    label: "xAI",
+    kind: "direct",
+    credentialFields: directApiKeyFields("An xAI API key."),
+    modelPolicy: {
+      mode: "floor",
+      floor: "4.5",
+      summary: "Grok 4.5 and above. The floor is 4.5; nothing older is offered."
+    },
+    description: "Grok models served directly by xAI."
+  },
+  {
+    id: "azure",
+    label: "Azure",
+    kind: "gateway",
+    hostedFamilies: ["openai", "anthropic"],
+    credentialFields: azureFields,
+    modelPolicy: {
+      mode: "derived",
+      from: ["openai", "anthropic"],
+      addressing: {
+        openai: {
+          scheme: "deployment-name",
+          pattern: "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
+          examples: ["my-gpt-5-6-deployment", "prod_gpt", "gpt56sol"],
+          counterExamples: ["gpt-5.6-sol", "claude-opus-5@20260115", "has space", ""]
+        },
+        anthropic: {
+          scheme: "deployment-name",
+          pattern: "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
+          examples: ["my-claude-deployment", "prod_claude"],
+          counterExamples: ["claude-opus-5@20260115", "gpt-5.6-sol", "has space", ""]
+        }
+      },
+      summary: "The OpenAI and Anthropic rosters, each model addressed by the name of its Azure deployment."
+    },
+    description: "Azure AI Foundry, hosting OpenAI and Anthropic models. One configuration per hosted family."
+  },
+  {
+    id: "vertex",
+    label: "Google Vertex",
+    kind: "gateway",
+    hostedFamilies: ["gemini", "anthropic"],
+    credentialFields: vertexFields,
+    modelPolicy: {
+      mode: "derived",
+      from: ["gemini", "anthropic"],
+      addressing: {
+        gemini: {
+          scheme: "plain",
+          pattern: "^(?!.*@)[a-zA-Z0-9][a-zA-Z0-9.\\-]*$",
+          examples: ["gemini-3.1-pro", "gemini-3.1-flash", "gemini-3.1-pro-preview"],
+          counterExamples: [
+            "gemini-3.1-pro@20260115",
+            "us.anthropic.claude-opus-5-v1:0",
+            "has space",
+            ""
+          ]
+        },
+        anthropic: {
+          scheme: "dated",
+          pattern: "^[a-zA-Z0-9][a-zA-Z0-9.\\-]*@\\d{8}$",
+          examples: ["claude-opus-5@20260115", "claude-sonnet-5@20251022"],
+          counterExamples: [
+            "claude-opus-5",
+            "claude-opus-5@",
+            "claude-opus-5@2026",
+            "gemini-3.1-pro"
+          ]
+        }
+      },
+      summary: "The Gemini and Anthropic rosters. Anthropic models are @-dated on Vertex; Gemini models are not."
+    },
+    description: "Google Vertex AI, hosting Gemini and Anthropic models. One configuration per hosted family."
+  },
+  {
+    id: "bedrock",
+    label: "AWS Bedrock",
+    kind: "gateway",
+    hostedFamilies: ["anthropic"],
+    credentialFields: [
+      {
+        name: "region",
+        label: "Region",
+        required: true,
+        treatment: "plain",
+        validation: {
+          rule: "pattern",
+          pattern: "^[a-z]{2}(-gov)?-[a-z]+-\\d+$",
+          hint: "An AWS region: a two-letter geography, a direction and an index.",
+          examples: [
+            "us-east-1",
+            "eu-central-1",
+            "ap-southeast-1",
+            "sa-east-1",
+            "me-south-1",
+            "af-south-1",
+            "il-central-1",
+            "mx-central-1",
+            "us-gov-west-1"
+          ],
+          counterExamples: ["us-east", "US-EAST-1", "useast1", "europe-west4"]
+        },
+        description: "The AWS region the Bedrock models are invoked in."
+      },
+      {
+        name: "apiKey",
+        label: "Bearer API key",
+        required: true,
+        treatment: "secret",
+        validation: {
+          rule: "pattern",
+          pattern: "^(?!AKIA)[^\\s:]+$",
+          hint: "A single opaque bearer token. Long-lived AWS access key and secret pairs are not accepted.",
+          examples: ["bedrock-api-key-abc123", "ABSKQmVkcm9ja0FQSUtleQ=="],
+          counterExamples: [
+            "AKIAIOSFODNN7EXAMPLE",
+            "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG",
+            "someid:somesecret",
+            "has space"
+          ]
+        },
+        description: "A Bedrock bearer API key. This is the only credential type Bedrock accepts here."
+      },
+      {
+        name: "inferenceProfile",
+        label: "Inference profile",
+        required: false,
+        treatment: "plain",
+        validation: { rule: "non-empty-string", minLength: 1 },
+        description: "Pin a cross-region inference profile. Defaults to the profile for the configured region."
+      }
+    ],
+    modelPolicy: {
+      mode: "derived",
+      from: ["anthropic"],
+      addressing: {
+        anthropic: {
+          scheme: "inference-profile",
+          pattern: "^(us|eu|apac)\\.[a-z0-9-]+\\.[a-zA-Z0-9.\\-]+(:\\d+)?$",
+          examples: [
+            "us.anthropic.claude-opus-5-v1:0",
+            "eu.anthropic.claude-sonnet-5-v1:0",
+            "apac.anthropic.claude-haiku-4-5-v1:0"
+          ],
+          counterExamples: [
+            "anthropic.claude-opus-5-v1:0",
+            "claude-opus-5",
+            "claude-opus-5@20260115"
+          ]
+        }
+      },
+      summary: "The Anthropic roster, addressed as region-prefixed inference-profile IDs."
+    },
+    description: "AWS Bedrock, hosting Anthropic models. Bearer API key only."
+  },
+  {
+    id: "custom",
+    label: "Custom (OpenAI or Anthropic compatible)",
+    kind: "direct",
+    credentialFields: [
+      {
+        name: "baseUrl",
+        label: "Base URL",
+        required: true,
+        treatment: "plain",
+        validation: { rule: "https-url" },
+        description: "The endpoint serving the API. Pick its wire format below."
+      },
+      apiKeyField("The key the endpoint expects, sent as a bearer token."),
+      {
+        name: "wireFormat",
+        label: "Wire format",
+        required: false,
+        treatment: "plain",
+        validation: { rule: "one-of", values: ["openai", "anthropic"] },
+        description: "Whether the endpoint speaks the OpenAI or the Anthropic request shape. Defaults to OpenAI when left unset — an endpoint that expects Anthropic's shape needs this set to 'anthropic'."
+      },
+      modelAllowListField
+    ],
+    modelPolicy: {
+      mode: "open",
+      summary: "Whatever the configured endpoint publishes."
+    },
+    description: "Any endpoint speaking an OpenAI-compatible or Anthropic-compatible API — self-hosted or third-party."
+  }
+];
+var CATALOG_BY_ID = new Map(PROVIDER_CATALOG.map((entry) => [entry.id, entry]));
+function getProviderCatalogEntry(id) {
+  return CATALOG_BY_ID.get(id);
+}
+function getCredentialField(entry, name) {
+  return entry.credentialFields.find((field) => field.name === name);
+}
+// src/lib/api-format.ts
+var API_FORMAT_WIRE_NAME = "wireFormat";
+function apiFormatValuesFor(providerType) {
+  const entry = getProviderCatalogEntry(providerType);
+  if (!entry)
+    return;
+  const field = getCredentialField(entry, API_FORMAT_WIRE_NAME);
+  if (!field)
+    return;
+  return field.validation.rule === "one-of" ? field.validation.values : undefined;
+}
+function providerAcceptsApiFormat(providerType) {
+  const entry = getProviderCatalogEntry(providerType);
+  return entry !== undefined && entryAcceptsApiFormat(entry);
+}
+function entryAcceptsApiFormat(entry) {
+  return getCredentialField(entry, API_FORMAT_WIRE_NAME) !== undefined;
+}
+function providersAcceptingApiFormat(catalog = PROVIDER_CATALOG) {
+  return catalog.filter(entryAcceptsApiFormat).map((entry) => entry.id);
+}
+function apiFormatHelpText() {
+  const accepting = providersAcceptingApiFormat();
+  if (accepting.length === 0) {
+    return "API format spoken by the endpoint (no catalog entry currently declares one)";
+  }
+  const values = [...new Set(accepting.flatMap((id) => apiFormatValuesFor(id) ?? []))];
+  const scope = `${accepting.join(", ")} only`;
+  return values.length > 0 ? `API format the endpoint speaks — ${scope}: ${values.join(", ")}` : `API format the endpoint speaks — ${scope}`;
+}
+function validateApiFormat(providerType, value) {
+  if (!providerAcceptsApiFormat(providerType)) {
+    const accepting = providersAcceptingApiFormat();
+    throw new MutagentError("API_FORMAT_NOT_APPLICABLE", accepting.length > 0 ? `--api-format applies only to ${accepting.join(", ")}. '${providerType}' speaks its own API.` : `--api-format applies to no provider in the catalog. '${providerType}' speaks its own API.`, accepting.length > 0 ? `Remove --api-format, or use --provider ${accepting.join(" | ")}` : "Remove --api-format");
+  }
+  const values = apiFormatValuesFor(providerType);
+  if (!values)
+    return;
+  if (!values.includes(value)) {
+    throw new MutagentError("INVALID_API_FORMAT", `'${value}' is not an API format that '${providerType}' speaks.`, `${providerType} accepts: ${values.join(", ")}`);
+  }
+}
+
+// src/commands/providers/add.ts
 var GATEWAY_HOSTED_FAMILIES = {
   azure: ["openai", "anthropic"],
   vertex: ["gemini", "anthropic"],
@@ -2277,10 +2713,12 @@ function collectCredentialFields(options) {
     fields.projectId = options.projectId;
   if (options.region)
     fields.region = options.region;
+  if (options.apiFormat)
+    fields[API_FORMAT_WIRE_NAME] = options.apiFormat;
   return fields;
 }
 function registerAddCommand(parent) {
-  parent.command("add").description("Add a new provider configuration").requiredOption("-p, --provider <type>", "Provider type (openai, anthropic, azure, ...)").requiredOption("-n, --name <name>", "Display name for this provider").option("-k, --api-key <key>", "API key for the provider (every entry except Google Vertex)").option("--service-account-key <json>", "Google Vertex service-account credential JSON").option("--hosted-family <family>", `Hosted model family for gateway providers: ${HOSTED_FAMILIES.join(", ")}`).option("--base-url <url>", "Custom base URL for the provider API").option("--resource-endpoint <url>", "Azure resource endpoint").option("--deployment-name <name>", "Azure deployment name").option("--api-version <version>", "Azure API version (e.g. 2024-08-01-preview)").option("--project-id <id>", "Google Vertex project ID").option("--region <region>", "Region (Vertex location, or AWS Bedrock region)").option("--set-default", "Set as the default provider of its kind").addHelpText("after", `
+  parent.command("add").description("Add a new provider configuration").requiredOption("-p, --provider <type>", "Provider type (openai, anthropic, azure, ...)").requiredOption("-n, --name <name>", "Display name for this provider").option("-k, --api-key <key>", "API key for the provider (every entry except Google Vertex)").option("--service-account-key <json>", "Google Vertex service-account credential JSON").option("--hosted-family <family>", `Hosted model family for gateway providers: ${HOSTED_FAMILIES.join(", ")}`).option("--base-url <url>", "Custom base URL for the provider API").option("--api-format <format>", apiFormatHelpText()).option("--resource-endpoint <url>", "Azure resource endpoint").option("--deployment-name <name>", "Azure deployment name").option("--api-version <version>", "Azure API version (e.g. 2024-08-01-preview)").option("--project-id <id>", "Google Vertex project ID").option("--region <region>", "Region (Vertex location, or AWS Bedrock region)").option("--set-default", "Set as the default provider of its kind").addHelpText("after", `
 Examples:
   ${chalk8.dim("$")} mutagent providers add --provider openai --name "My OpenAI" --api-key $OPENAI_API_KEY
   ${chalk8.dim("$")} mutagent providers add --provider azure --name "Azure GPT" --api-key $KEY \\
@@ -2288,10 +2726,16 @@ Examples:
   ${chalk8.dim("$")} mutagent providers add --provider bedrock --name "Bedrock Claude" --api-key $KEY \\
       --hosted-family anthropic --region us-east-1
   ${chalk8.dim("$")} mutagent providers add --provider custom --name "Ollama" --api-key none --base-url https://ollama.internal --json
+  ${chalk8.dim("$")} mutagent providers add --provider custom --name "Claude-compatible" --api-key $KEY \\
+      --base-url https://llm.internal --api-format anthropic
 
 Gateway providers (${[...GATEWAY_PROVIDERS].join(", ")}) serve another vendor's models and
 require --hosted-family. Direct providers must not set it.
 
+${apiFormatHelpText()}. An endpoint speaking the Anthropic request shape needs
+--api-format anthropic; left unset, the server's default applies. Passing it to a
+provider that speaks its own API is an error, not a silent no-op.
+
 Providers are configured for your workspace. Set the target with:
   ${chalk8.dim("$")} mutagent config set workspace <workspace-id>
 
@@ -2326,6 +2770,9 @@ AI Agent Directive:
       } else if (isGateway && allowedFamilies.length > 1) {
         throw new MutagentError("MISSING_HOSTED_FAMILY", `'${providerType}' is a gateway and needs to know which model family it serves.`, `Add --hosted-family <${allowedFamilies.join("|")}>`);
       }
+      if (options.apiFormat) {
+        validateApiFormat(providerType, options.apiFormat);
+      }
       const client = await getSDKClient();
       const workspaceId = client.requireUnambiguousWorkspace();
       const credentialFields = collectCredentialFields(options);
@@ -2357,6 +2804,9 @@ AI Agent Directive:
         if (options.hostedFamily) {
           console.log(`  Serves:    ${options.hostedFamily}`);
         }
+        if (options.apiFormat) {
+          console.log(`  API format: ${options.apiFormat}`);
+        }
         console.log(`  Workspace: ${workspaceId}`);
         console.log(`  URL:       ${providerLink(created.id)}`);
         if (options.setDefault) {
@@ -5134,5 +5584,5 @@ program.addCommand(createInstallCommand());
 program.addCommand(createFeedbackCommand());
 program.parse();
 
-//# debugId=850D997C527DFF0A64756E2164756E21
+//# debugId=67EF27735DAD427E64756E2164756E21
 //# sourceMappingURL=cli.js.map