@vellumai/assistant 0.10.9 → 0.10.10-dev.202607162206.d08e98e

package/src/cli/commands/inference-providers.ts

@@ -1,14 +1,17 @@
 /**
  * `assistant inference providers` CLI namespace.
  *
- * Provider-scoped admin commands. Currently exposes one subcommand:
+ * Provider-scoped admin commands:
  *
- *   `assistant inference providers connections <verb>`
- *     list    — list all connections (optionally filtered by provider)
- *     get     — show a single connection
- *     create  — create a new connection
- *     update  — update a connection's auth
- *     delete  — delete a connection (rejects if profiles reference it)
+ *   `assistant inference providers <verb>`
+ *     list    — list configured providers (optionally filtered by provider)
+ *     get     — show a single provider entry
+ *     create  — add a provider (auth derived from the provider type)
+ *     update  — update a provider entry
+ *     delete  — remove a provider (rejects if profiles reference it)
+ *
+ *   `assistant inference providers connections <verb>` is a deprecated alias
+ *   of the same verbs, kept for one release.
  *
  * All subcommands delegate to the daemon via IPC using the
  * `inference_provider_connections_*` routes.
@@ -60,12 +63,97 @@ function formatAuth(auth: AuthInfo): string {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Auth derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the auth object a provider implies via the daemon's shared
+ * `deriveAuthForProvider` (one source of truth for the keyless / vellum /
+ * openai-compatible rules), mapping its credential-required null to a
+ * CLI-flavored error message string.
+ */
+async function deriveAuthInput(
+  provider: string,
+  credential?: string,
+): Promise<Record<string, unknown> | string> {
+  // Deferred: pure module, imported lazily per cli/no-daemon-internals.
+  const { deriveAuthForProvider } =
+    await import("../../providers/inference/auth.js");
+  const derived = deriveAuthForProvider(provider, credential);
+  if (!derived) {
+    return `Provider "${provider}" authenticates by API key — pass --credential <vault-key> (or an explicit --auth override)`;
+  }
+  return derived as unknown as Record<string, unknown>;
+}
+
+/**
+ * Build and validate an explicit `--auth` override from CLI flags. Returns
+ * the auth object on success, or an error message string on validation
+ * failure.
+ */
+function buildAuthInput(
+  authType: string,
+  credential?: string,
+): Record<string, unknown> | string {
+  if (authType === "api_key") {
+    if (!credential) {
+      return "--credential is required when --auth api_key";
+    }
+    return { type: "api_key", credential };
+  }
+  if (authType === "platform") {
+    if (credential) {
+      return "--credential is not accepted with --auth platform";
+    }
+    return { type: "platform" };
+  }
+  if (authType === "none") {
+    if (credential) {
+      return "--credential is not accepted with --auth none";
+    }
+    return { type: "none" };
+  }
+  if (authType === "oauth_subscription") {
+    if (!credential) {
+      return "--credential is required when --auth oauth_subscription";
+    }
+    return { type: "oauth_subscription", credential };
+  }
+  return `Unknown auth type "${authType}". Use: api_key, platform, none, oauth_subscription`;
+}
+
+/** Commander collector for a repeatable option (e.g. `--model` multiple times). */
+function collectRepeatable(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+/**
+ * Build the openai-compatible custom-provider fields (`base_url`, `models`)
+ * from CLI flags, forwarded to the connection route under its exact field
+ * names. The daemon stays authoritative on whether they are required/allowed;
+ * the CLI only shape-forwards what the user passed.
+ */
+function buildCustomProviderFields(opts: {
+  baseUrl?: string;
+  model?: string[];
+}): Record<string, unknown> {
+  const fields: Record<string, unknown> = {};
+  if (opts.baseUrl !== undefined) {
+    fields.base_url = opts.baseUrl;
+  }
+  if (opts.model !== undefined && opts.model.length > 0) {
+    fields.models = opts.model.map((id) => ({ id }));
+  }
+  return fields;
+}
+
 // ---------------------------------------------------------------------------
 // Subcommand: list
 // ---------------------------------------------------------------------------
 
-function attachListSubcommand(connections: Command): void {
-  subcommand(connections, "list").action(
+function attachListSubcommand(parent: Command): void {
+  subcommand(parent, "list").action(
     async (opts: { provider?: string; json?: boolean }) => {
       const ipcResult = await cliIpcCall<{ connections: ProviderConnection[] }>(
         "inference_provider_connections_list",
@@ -89,14 +177,12 @@ function attachListSubcommand(connections: Command): void {
       }
 
       if (rows.length === 0) {
-        process.stdout.write("No connections found.\n");
+        process.stdout.write("No providers found.\n");
         return;
       }
 
       for (const conn of rows) {
-        process.stdout.write(
-          `${conn.name}  provider=${conn.provider}  auth=${formatAuth(conn.auth)}\n`,
-        );
+        process.stdout.write(`${conn.name}  provider=${conn.provider}\n`);
       }
     },
   );
@@ -106,8 +192,8 @@ function attachListSubcommand(connections: Command): void {
 // Subcommand: get
 // ---------------------------------------------------------------------------
 
-function attachGetSubcommand(connections: Command): void {
-  subcommand(connections, "get").action(
+function attachGetSubcommand(parent: Command): void {
+  subcommand(parent, "get").action(
     async (name: string, opts: { json?: boolean }) => {
       const ipcResult = await cliIpcCall<ProviderConnection>(
         "inference_provider_connections_get",
@@ -143,82 +229,18 @@ function attachGetSubcommand(connections: Command): void {
   );
 }
 
-// ---------------------------------------------------------------------------
-// Auth input builder
-// ---------------------------------------------------------------------------
-
-/**
- * Build and validate auth input from CLI flags. Returns the auth object on
- * success, or an error message string on validation failure.
- */
-function buildAuthInput(
-  authType: string,
-  credential?: string,
-): Record<string, unknown> | string {
-  if (authType === "api_key") {
-    if (!credential) {
-      return "--credential is required when --auth api_key";
-    }
-    return { type: "api_key", credential };
-  }
-  if (authType === "platform") {
-    if (credential) {
-      return "--credential is not accepted with --auth platform";
-    }
-    return { type: "platform" };
-  }
-  if (authType === "none") {
-    if (credential) {
-      return "--credential is not accepted with --auth none";
-    }
-    return { type: "none" };
-  }
-  if (authType === "oauth_subscription") {
-    if (!credential) {
-      return "--credential is required when --auth oauth_subscription";
-    }
-    return { type: "oauth_subscription", credential };
-  }
-  return `Unknown auth type "${authType}". Use: api_key, platform, none, oauth_subscription`;
-}
-
-/** Commander collector for a repeatable option (e.g. `--model` multiple times). */
-function collectRepeatable(value: string, previous: string[]): string[] {
-  return [...previous, value];
-}
-
-/**
- * Build the openai-compatible custom-provider fields (`base_url`, `models`)
- * from CLI flags, forwarded to the connection route under its exact field
- * names. The daemon stays authoritative on whether they are required/allowed;
- * the CLI only shape-forwards what the user passed.
- */
-function buildCustomProviderFields(opts: {
-  baseUrl?: string;
-  model?: string[];
-}): Record<string, unknown> {
-  const fields: Record<string, unknown> = {};
-  if (opts.baseUrl !== undefined) {
-    fields.base_url = opts.baseUrl;
-  }
-  if (opts.model !== undefined && opts.model.length > 0) {
-    fields.models = opts.model.map((id) => ({ id }));
-  }
-  return fields;
-}
-
 // ---------------------------------------------------------------------------
 // Subcommand: create
 // ---------------------------------------------------------------------------
 
-function attachCreateSubcommand(connections: Command): void {
+function attachCreateSubcommand(parent: Command): void {
   // `--model` uses an array-accumulating collector, which the declarative
   // help contract cannot express — it is registered imperatively here (with
   // the trailing `--json` after it, preserving option order).
-  subcommand(connections, "create")
+  subcommand(parent, "create")
     .option(
       "--model <id>",
-      "Model id offered by this connection (repeatable; required for openai-compatible)",
+      "Model id offered by this provider (repeatable; required for openai-compatible)",
       collectRepeatable,
       [] as string[],
     )
@@ -228,14 +250,16 @@ function attachCreateSubcommand(connections: Command): void {
         name: string,
         opts: {
           provider: string;
-          auth: string;
+          auth?: string;
           credential?: string;
           baseUrl?: string;
           model?: string[];
           json?: boolean;
         },
       ) => {
-        const authInput = buildAuthInput(opts.auth, opts.credential);
+        const authInput = opts.auth
+          ? buildAuthInput(opts.auth, opts.credential)
+          : await deriveAuthInput(opts.provider, opts.credential);
         if (typeof authInput === "string") {
           writeCliError(authInput, opts.json);
           return;
@@ -274,8 +298,8 @@ function attachCreateSubcommand(connections: Command): void {
           );
         } else {
           process.stdout.write(
-            `Created connection "${conn.name}" (provider=${conn.provider}, auth=${formatAuth(conn.auth)})\n` +
-              `Verify it works: point a profile's provider_connection at "${conn.name}", then run: assistant inference send --profile <profile> "Reply with OK"\n`,
+            `Added provider "${conn.name}" (provider=${conn.provider})\n` +
+              `Verify it works: point a profile at "${conn.name}", then run: assistant inference send --profile <profile> "Reply with OK"\n`,
           );
         }
       },
@@ -286,12 +310,12 @@ function attachCreateSubcommand(connections: Command): void {
 // Subcommand: update
 // ---------------------------------------------------------------------------
 
-function attachUpdateSubcommand(connections: Command): void {
+function attachUpdateSubcommand(parent: Command): void {
   // `--model` collector registered imperatively — see the note on `create`.
-  subcommand(connections, "update")
+  subcommand(parent, "update")
     .option(
       "--model <id>",
-      "Model id offered by this connection (repeatable; openai-compatible)",
+      "Model id offered by this provider (repeatable; openai-compatible)",
       collectRepeatable,
       [] as string[],
     )
@@ -300,14 +324,44 @@ function attachUpdateSubcommand(connections: Command): void {
       async (
         name: string,
         opts: {
-          auth: string;
+          auth?: string;
           credential?: string;
           baseUrl?: string;
           model?: string[];
           json?: boolean;
         },
       ) => {
-        const authInput = buildAuthInput(opts.auth, opts.credential);
+        // Resolve the auth to send: explicit --auth wins; a bare --credential
+        // rotates the key via derived api_key auth; with neither, re-send the
+        // stored auth verbatim so base-url/model-only updates work.
+        let authInput: Record<string, unknown> | string;
+        if (opts.auth) {
+          authInput = buildAuthInput(opts.auth, opts.credential);
+        } else {
+          const existing = await cliIpcCall<ProviderConnection>(
+            "inference_provider_connections_get",
+            { pathParams: { name } },
+          );
+          if (!existing.ok) {
+            writeCliError(existing.error ?? "Unknown error", opts.json);
+            return;
+          }
+          const storedAuth = existing.result!.auth;
+          if (opts.credential) {
+            // A bare --credential must never silently flip subscription auth
+            // to api_key — subscription tokens rotate via login-chatgpt.
+            if (storedAuth.type === "oauth_subscription") {
+              writeCliError(
+                `Provider "${name}" uses subscription auth, which --credential cannot rotate. Re-run: assistant inference providers login-chatgpt (or pass an explicit --auth to switch auth types)`,
+                opts.json,
+              );
+              return;
+            }
+            authInput = { type: "api_key", credential: opts.credential };
+          } else {
+            authInput = storedAuth as unknown as Record<string, unknown>;
+          }
+        }
         if (typeof authInput === "string") {
           writeCliError(authInput, opts.json);
           return;
@@ -334,8 +388,8 @@ function attachUpdateSubcommand(connections: Command): void {
           );
         } else {
           process.stdout.write(
-            `Updated connection "${name}" auth to ${formatAuth(conn.auth)}\n` +
-              `Verify it works: assistant inference send --profile <profile-using-this-connection> "Reply with OK"\n`,
+            `Updated provider "${name}" (auth=${formatAuth(conn.auth)})\n` +
+              `Verify it works: assistant inference send --profile <profile-using-this-provider> "Reply with OK"\n`,
           );
         }
       },
@@ -346,8 +400,8 @@ function attachUpdateSubcommand(connections: Command): void {
 // Subcommand: delete
 // ---------------------------------------------------------------------------
 
-function attachDeleteSubcommand(connections: Command): void {
-  subcommand(connections, "delete").action(
+function attachDeleteSubcommand(parent: Command): void {
+  subcommand(parent, "delete").action(
     async (name: string, opts: { json?: boolean }) => {
       const ipcResult = await cliIpcCall<{ ok: true }>(
         "inference_provider_connections_delete",
@@ -364,7 +418,7 @@ function attachDeleteSubcommand(connections: Command): void {
       if (opts.json) {
         process.stdout.write(JSON.stringify({ ok: true }) + "\n");
       } else {
-        process.stdout.write(`Deleted connection "${name}"\n`);
+        process.stdout.write(`Removed provider "${name}"\n`);
       }
     },
   );
@@ -442,14 +496,14 @@ function attachLoginChatgptSubcommand(providers: Command): void {
           );
         }
 
-        // Step 3: Create (or update) provider connection via IPC
+        // Step 3: Create (or update) the provider entry via IPC
         const connectionName = "chatgpt-subscription";
         const authInput = {
           type: "oauth_subscription",
           credential: "credential/chatgpt/access_token",
         };
 
-        // Try to update first; if the connection doesn't exist, create it.
+        // Try to update first; if the entry doesn't exist, create it.
         const updateResult = await cliIpcCall<ProviderConnection>(
           "inference_provider_connections_update",
           {
@@ -459,7 +513,7 @@ function attachLoginChatgptSubcommand(providers: Command): void {
         );
 
         if (!updateResult.ok) {
-          // Connection doesn't exist yet — create it
+          // Entry doesn't exist yet — create it
           const createResult = await cliIpcCall<ProviderConnection>(
             "inference_provider_connections_create",
             {
@@ -473,7 +527,7 @@ function attachLoginChatgptSubcommand(providers: Command): void {
 
           if (!createResult.ok) {
             writeCliError(
-              createResult.error ?? "Failed to create provider connection",
+              createResult.error ?? "Failed to add the ChatGPT provider",
               opts.json,
             );
             return;
@@ -491,7 +545,7 @@ function attachLoginChatgptSubcommand(providers: Command): void {
         } else {
           process.stdout.write(
             `ChatGPT subscription auth configured successfully.\n` +
-              `Connection "${connectionName}" is ready (provider=openai, auth=oauth_subscription).\n`,
+              `Provider "${connectionName}" is ready.\n`,
           );
         }
       } catch (err) {
@@ -506,15 +560,22 @@ function attachLoginChatgptSubcommand(providers: Command): void {
 // Registration
 // ---------------------------------------------------------------------------
 
+/** Attach the five CRUD verbs to a parent (`providers` or its alias). */
+function attachCrudVerbs(parent: Command): void {
+  attachListSubcommand(parent);
+  attachGetSubcommand(parent);
+  attachCreateSubcommand(parent);
+  attachUpdateSubcommand(parent);
+  attachDeleteSubcommand(parent);
+}
+
 export function attachProvidersSubcommand(inference: Command): void {
   const providers = subcommand(inference, "providers");
-  const connections = subcommand(providers, "connections");
+  attachCrudVerbs(providers);
 
-  attachListSubcommand(connections);
-  attachGetSubcommand(connections);
-  attachCreateSubcommand(connections);
-  attachUpdateSubcommand(connections);
-  attachDeleteSubcommand(connections);
+  // Deprecated alias, kept for one release.
+  const connections = subcommand(providers, "connections");
+  attachCrudVerbs(connections);
 
   attachLoginChatgptSubcommand(providers);
   attachDefaultProviderSubcommand(providers);

package/src/cli/commands/inference.help.ts

@@ -90,7 +90,7 @@ export const inferenceHelp: CliCommandHelp = {
   description: "LLM inference operations",
   helpText: `
 The inference command group sends requests to your configured LLM provider.
-The provider is resolved from your assistant config (llm.default.provider).
+The provider is resolved from your assistant config (llm.defaultProvider).
 
 Examples:
   $ assistant inference send "What is the capital of France?"
@@ -195,39 +195,116 @@ Examples:
     },
     {
       name: "providers",
-      description: "Inference provider admin commands",
-      subcommands: [
-        {
-          name: "connections",
-          description:
-            "Manage provider connections (auth configs for inference)",
-          helpText: `
-Provider connections map a name to a (provider, auth) pair.
-Profiles reference connections via the 'provider_connection' field.
+      description: "Manage the model providers this assistant can use",
+      helpText: `
+A provider entry names a model provider plus how to reach it. Auth is
+derived from the provider: keyless providers (ollama) need none, the
+Vellum entry routes through the platform's managed proxy, and everything
+else uses an API key referenced by --credential.
 
-Canonical connections (seeded on every boot):
-  anthropic-managed  → provider=anthropic, auth=platform
-  openai-managed     → provider=openai,    auth=platform
-  gemini-managed     → provider=gemini,    auth=platform
+Canonical entry (seeded on every boot):
+  vellum → the platform-managed provider; cannot be deleted
 
 Examples:
-  $ assistant inference providers connections list
-  $ assistant inference providers connections get anthropic-managed
-  $ assistant inference providers connections create anthropic-personal \\
-      --provider anthropic --auth api_key --credential credential/anthropic/api_key
-  $ assistant inference providers connections create local-llm \\
-      --provider openai-compatible --auth none \\
+  $ assistant inference providers list
+  $ assistant inference providers get vellum
+  $ assistant inference providers create anthropic-personal \\
+      --provider anthropic --credential credential/anthropic/api_key
+  $ assistant inference providers create local-llm \\
+      --provider openai-compatible \\
       --base-url http://localhost:1234/v1 --model my-model
-  $ assistant inference providers connections update anthropic-personal --auth platform
-  $ assistant inference providers connections delete anthropic-personal
+  $ assistant inference providers update anthropic-personal \\
+      --credential credential/anthropic/api_key
+  $ assistant inference providers delete anthropic-personal
 
-After creating or updating a connection, validate it with a live call through
+After creating or updating a provider, validate it with a live call through
 a profile that uses it:
   $ assistant inference send --profile <profile> "Reply with OK"`,
+      subcommands: [
+        {
+          name: "list",
+          description: "List configured providers",
+          options: [
+            { flags: "--provider <p>", description: "Filter by provider" },
+            { flags: "--json", description: "Output as JSON" },
+          ],
+        },
+        {
+          name: "get",
+          args: "<name>",
+          description: "Show a single provider entry",
+          options: [{ flags: "--json", description: "Output as JSON" }],
+        },
+        {
+          // NOTE: the repeatable `--model` collector option and the
+          // trailing `--json` are registered imperatively in
+          // `inference-providers.ts` (array-accumulating parser functions
+          // are not expressible as plain help data).
+          name: "create",
+          args: "<name>",
+          description: "Add a provider",
+          options: [
+            {
+              flags: "--provider <p>",
+              description: "Provider (anthropic|openai|gemini|ollama|...)",
+              required: true,
+            },
+            {
+              flags: "--credential <vault-key>",
+              description:
+                "Vault credential name (required for API-key providers)",
+            },
+            {
+              flags: "--auth <type>",
+              description:
+                "Override the derived auth: api_key|platform|none|oauth_subscription",
+            },
+            {
+              flags: "--base-url <url>",
+              description:
+                "Endpoint base URL (required for --provider openai-compatible)",
+            },
+          ],
+        },
+        {
+          // NOTE: `--model` + `--json` registered imperatively — see `create`.
+          name: "update",
+          args: "<name>",
+          description: "Update a provider entry",
+          options: [
+            {
+              flags: "--credential <vault-key>",
+              description:
+                "Rotate the API-key credential (derives api_key auth)",
+            },
+            {
+              flags: "--auth <type>",
+              description:
+                "Override the auth explicitly: api_key|platform|none|oauth_subscription",
+            },
+            {
+              flags: "--base-url <url>",
+              description: "Endpoint base URL (openai-compatible providers)",
+            },
+          ],
+        },
+        {
+          name: "delete",
+          args: "<name>",
+          description: "Remove a provider",
+          options: [{ flags: "--json", description: "Output as JSON" }],
+        },
+        {
+          name: "connections",
+          description:
+            "(Deprecated) use `assistant inference providers <verb>` instead",
+          helpText: `
+Deprecated alias kept for one release: every verb here is the same as the
+matching \`assistant inference providers <verb>\` command.`,
           subcommands: [
             {
               name: "list",
-              description: "List all provider connections",
+              description: "(Deprecated) use `providers list`",
               options: [
                 { flags: "--provider <p>", description: "Filter by provider" },
                 { flags: "--json", description: "Output as JSON" },
@@ -236,17 +313,13 @@ a profile that uses it:
             {
               name: "get",
               args: "<name>",
-              description: "Show a single provider connection",
+              description: "(Deprecated) use `providers get`",
               options: [{ flags: "--json", description: "Output as JSON" }],
             },
             {
-              // NOTE: the repeatable `--model` collector option and the
-              // trailing `--json` are registered imperatively in
-              // `inference-providers.ts` (array-accumulating parser functions
-              // are not expressible as plain help data).
               name: "create",
               args: "<name>",
-              description: "Create a new provider connection",
+              description: "(Deprecated) use `providers create`",
               options: [
                 {
                   flags: "--provider <p>",
@@ -254,14 +327,14 @@ a profile that uses it:
                   required: true,
                 },
                 {
-                  flags: "--auth <type>",
-                  description: "Auth type: api_key|platform|none",
-                  required: true,
+                  flags: "--credential <vault-key>",
+                  description:
+                    "Vault credential name (required for API-key providers)",
                 },
                 {
-                  flags: "--credential <vault-key>",
+                  flags: "--auth <type>",
                   description:
-                    "Vault credential name (required for --auth api_key)",
+                    "Override the derived auth: api_key|platform|none|oauth_subscription",
                 },
                 {
                   flags: "--base-url <url>",
@@ -271,32 +344,31 @@ a profile that uses it:
               ],
             },
             {
-              // NOTE: `--model` + `--json` registered imperatively — see `create`.
               name: "update",
               args: "<name>",
-              description: "Update a connection's auth",
+              description: "(Deprecated) use `providers update`",
               options: [
                 {
-                  flags: "--auth <type>",
-                  description: "Auth type: api_key|platform|none",
-                  required: true,
+                  flags: "--credential <vault-key>",
+                  description:
+                    "Rotate the API-key credential (derives api_key auth)",
                 },
                 {
-                  flags: "--credential <vault-key>",
+                  flags: "--auth <type>",
                   description:
-                    "Vault credential name (required for --auth api_key)",
+                    "Override the auth explicitly: api_key|platform|none|oauth_subscription",
                 },
                 {
                   flags: "--base-url <url>",
                   description:
-                    "Endpoint base URL (openai-compatible connections)",
+                    "Endpoint base URL (openai-compatible providers)",
                 },
               ],
             },
             {
               name: "delete",
               args: "<name>",
-              description: "Delete a provider connection",
+              description: "(Deprecated) use `providers delete`",
               options: [{ flags: "--json", description: "Output as JSON" }],
             },
           ],
@@ -313,7 +385,7 @@ a profile that uses it:
           options: [
             {
               flags: "--connection <name>",
-              description: "Pin a specific connection when setting",
+              description: "Pin a specific provider entry when setting",
             },
             {
               flags: "--json",
@@ -473,7 +545,7 @@ export const llmHelp: CliCommandHelp = {
   helpText: `
 The llm command group is a shorthand for 'assistant inference send'. It sends
 requests to your configured LLM provider, resolved from your assistant config
-(llm.default.provider). For profile session management, use 'assistant inference session'.
+(llm.defaultProvider). For profile session management, use 'assistant inference session'.
 
 Examples:
   $ assistant llm send "What is the capital of France?"