feat: reduces optionality for model setup

Author: OisinKyne

CLAUDE.md

@@ -262,16 +262,15 @@ Caveats:
 
 **Auto-configuration**: `obol stack up` → `autoConfigureLLM()` detects host Ollama models, patches LiteLLM config. `obolup.sh` → `check_agent_model_api_key()` reads `~/.openclaw/openclaw.json`, resolves API key from `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN` (Anthropic) or `OPENAI_API_KEY` (OpenAI), exports for downstream.
 
-**BYOK cloud providers** (easiest getting-started path) — provider knowledge is a single registry in `internal/model/model.go` (`knownProviders` / `ProviderInfo` with `Mode`/`BaseURL`/`Default`/`SignupURL`/`Free`); adding a provider is one row, no per-provider switch. Built-in: `anthropic`, `openai`, `ollama` (native/local) + OpenAI-compatible aggregators `venice`, `openrouter`, `nvidia`, `gmi`, `novita`, `huggingface` (`Mode=openai-compatible` → `model_list` entry `openai/<id>` + explicit `api_base` + key from the provider's env var; no wildcard). When `--model` is omitted, setup uses the registry `Default` or lists the live `GET <base>/v1/models` (TTY picker / non-TTY error naming real ids). `--free` seeds only the curated free-tier model snapshot (OpenRouter).
+**BYOK cloud providers** (easiest getting-started path) — provider knowledge is a single registry in `internal/model/model.go` (`knownProviders` / `ProviderInfo` with `Mode`/`BaseURL`/`Default`/`KeyURL`/`JoinURL`/`Free`); adding a provider is one row, no per-provider switch. `KeyURL` is the API-key dashboard (assumes account); optional `JoinURL` is a new-user landing page (may carry a referral tag) used in preference to `KeyURL` for browser-open and "new to X? Sign up" hints. Built-in: `anthropic`, `openai`, `ollama` (native/local) + OpenAI-compatible aggregators `venice`, `openrouter`, `nvidia`, `gmi`, `novita`, `huggingface` (`Mode=openai-compatible` → `model_list` entry `openai/<id>` + explicit `api_base` + key from the provider's env var; no wildcard). When `--model` is omitted, setup uses the registry `Default` or lists the live `GET <base>/v1/models` (TTY picker / non-TTY error naming real ids). `--free` seeds the curated free-tier model snapshot (currently OpenRouter only) intersected against the live `/v1/models` response to drop rotated-out ids; auto-applied for `openrouter` when no `--model` is passed.
 
-Two front doors share one engine (`setupCloudProvider` in `cmd/obol/model.go`):
-- `obol buy inference <provider>` — friendly onboarding: opens the provider's `SignupURL` in the browser (`openBrowser`, hermes-style), takes the key (`--api-key` → env var → prompt), wires LiteLLM + syncs agents. `obol buy inference` with a URL/no-arg is still the **x402 crypto-paid seller** path — dispatch keys on whether the positional arg matches a registry provider id.
-- `obol model setup <provider> --api-key <key>` — the scriptable, no-browser equivalent. Unlisted endpoints still use `obol model setup custom`.
+Single front door: `obol model setup` (engine: `setupCloudProvider` in `cmd/obol/model.go`). Interactive picker defaults to OpenRouter — `obol model setup` with no flags walks a TTY user through provider pick → browser open at `JoinURL`/`KeyURL` → key prompt → free-roster seeding. Scriptable variant: `obol model setup --provider <id> --api-key <key>`. Unlisted endpoints: `obol model setup custom --endpoint … --model …`. `obol buy inference <provider>` is reserved for future credit top-ups against remote providers; today it errors with a redirect to `obol model setup`. `obol buy inference [<seller-url>]` (URL or no arg) is the **x402 crypto-paid seller** path — unchanged.
 
 ```bash
-obol buy inference venice                 # opens venice key page, prompts, wires up
-obol buy inference openrouter --free      # seeds curated free models
-obol model setup venice --api-key $VENICE_API_KEY   # scriptable / CI
+obol model setup                                       # interactive; default = openrouter + free roster
+obol model setup --provider venice                     # opens https://venice.ai/chat?ref=ZynMuD (TTY) + prompts for key
+obol model setup --provider venice --api-key $VENICE_API_KEY   # scriptable / CI
+obol model setup --provider openrouter --model openrouter/auto # paid OpenRouter (skips free-roster seeding)
 ```
 
 **External OpenAI-compatible LLM** (vLLM / sglang / mlx-lm / remote GPU) — canonical user flow, no ConfigMap surgery:

cmd/obol/buy.go

@@ -66,45 +66,27 @@ func buyCommand(cfg *config.Config) *cli.Command {
 func buyInferenceCommand(cfg *config.Config) *cli.Command {
 	return &cli.Command{
 		Name:      "inference",
-		Usage:     "Buy inference for your agents — a hosted BYOK provider (Venice, OpenRouter, …) or an x402-gated seller",
-		ArgsUsage: "[<provider>|<seller-url>]",
-		Description: `Two ways to give your agents inference:
+		Usage:     "Buy inference for your agents from an x402-gated seller",
+		ArgsUsage: "[<seller-url>]",
+		Description: `Buy x402-gated inference from a seller.
 
-  1. Hosted provider (BYOK) — hand the command a provider id and it opens
-     that provider's API-key page in your browser, takes the key, and wires
-     your agents' LiteLLM gateway to it:
+Hand the command a seller URL (a storefront base like
+"https://inference.v1337.org" or a specific offer ".../services/aeon") and
+the CLI walks /api/services.json, picks the inference offer, and pre-signs
+payment authorizations via the agent's remote signer. With no argument the
+public ` + x402verifier.DefaultBuySellerURL + ` storefront is used.
 
-         obol buy inference venice
-         obol buy inference openrouter --free
+In a TTY the flow prompts for auto-refill, request count, and confirmation.
+Pass --yes / -y for non-interactive runs (--count required).
 
-     Built-in providers: venice, openrouter, nvidia, gmi, novita,
-     huggingface (plus anthropic, openai). The key is read from the
-     provider's env var when already set, so this stays non-interactive in CI.
-
-  2. x402-gated seller — hand it a seller URL (a storefront base like
-     "https://inference.v1337.org" or a specific offer ".../services/aeon")
-     and the CLI walks /api/services.json, picks the inference offer, and
-     pre-signs payment authorizations via the agent's remote signer. With no
-     argument, the public ` + x402verifier.DefaultBuySellerURL + ` storefront is used.
-
-In a TTY the seller flow prompts for auto-refill, request count, and
-confirmation. Pass --yes / -y for non-interactive runs (--count required).
+For hosted BYOK providers (Venice, OpenRouter, …) use ` + "`obol model setup`" + `
+instead — that path takes the API key and wires LiteLLM directly, no x402.
 
 Examples:
-    obol buy inference venice
-    obol buy inference openrouter --free
+    obol buy inference
     obol buy inference https://inference.v1337.org/services/aeon
     obol buy inference https://seller.example/services/foo --yes --count 100`,
 		Flags: []cli.Flag{
-			&cli.StringFlag{
-				Name:    "api-key",
-				Usage:   "API key for a hosted provider (BYOK). Also read from the provider's env var when set.",
-				Sources: cli.EnvVars("LLM_API_KEY"),
-			},
-			&cli.BoolFlag{
-				Name:  "free",
-				Usage: "For a hosted provider that has them, seed only the curated free-tier models (OpenRouter)",
-			},
 			&cli.StringFlag{
 				Name:  "seller",
 				Usage: "Seller URL (alternative to positional). When neither is set the default storefront is used.",
@@ -177,66 +159,24 @@ Examples:
 	}
 }
 
-// runBuyInferenceProvider is the BYOK front door: open the provider's
-// API-key page (hermes-style openurl), take the key (--api-key → env →
-// prompt), then wire the LiteLLM gateway via the shared model-setup
-// engine. No wallet, no x402 — this is hosted inference with the user's
-// own key, the easiest way to get an agent talking to a model.
-func runBuyInferenceProvider(cfg *config.Config, cmd *cli.Command, prof model.ProviderInfo) error {
-	u := getUI(cmd)
-	u.Infof("Connecting %s for your agents (bring-your-own-key)", prof.Name)
-
-	apiKey := strings.TrimSpace(cmd.String("api-key"))
-	if apiKey == "" {
-		if key, envVar := model.ResolveAPIKey(prof.ID); key != "" {
-			apiKey = key
-			u.Infof("Using %s API key from %s", prof.Name, envVar)
-		}
-	}
-
-	// openurl: send the operator to the provider's onboarding page before
-	// we prompt for the key (skipped when a key is already in hand or
-	// non-TTY). Prefer JoinURL (the new-user landing page, possibly
-	// referral-tagged) when set; fall back to SignupURL (keys dashboard).
-	onboardURL := prof.JoinURL
-	if onboardURL == "" {
-		onboardURL = prof.SignupURL
-	}
-	if apiKey == "" && onboardURL != "" && u.IsTTY() && !u.IsJSON() {
-		u.Infof("Opening %s to sign up / create an API key …", onboardURL)
-		if err := openBrowser(onboardURL); err != nil {
-			u.Dim(fmt.Sprintf("(couldn't open a browser — visit %s)", onboardURL))
-		}
-	}
-
-	var models []string
-	if m := strings.TrimSpace(cmd.String("model")); m != "" {
-		models = []string{m}
-	}
-
-	// Shared engine: prompts for the key if still empty, seeds --free,
-	// resolves a model (registry default or live /v1/models), patches
-	// LiteLLM, and promotes + syncs the agents to use it.
-	return setupCloudProvider(cfg, u, prof, apiKey, models, cmd.Bool("free"))
-}
-
 // runBuyInference is the orchestrator for the new flow. Kept separate from
 // the cli.Command literal so the steps stay scannable: resolve agent →
 // resolve seller URL → pick catalog entry → resolve token+count+budget →
 // confirm → exec buy.py → optional model prefer + agent sync.
 func runBuyInference(ctx context.Context, cfg *config.Config, cmd *cli.Command) error {
 	u := getUI(cmd)
 
-	// Front door: if the argument names a hosted provider in the registry
-	// (venice, openrouter, …) rather than a seller URL, run BYOK onboarding
-	// — open the provider's key page and wire the LiteLLM gateway. Ollama is
-	// local and free, so it's not a "buy" target.
+	// If the argument names a hosted provider in the registry (venice,
+	// openrouter, …) rather than a seller URL, the user wants BYOK setup,
+	// not an x402 purchase. Redirect to `obol model setup`. The command
+	// name stays reserved for future credit top-up flows against the same
+	// remote providers.
 	arg := strings.TrimSpace(cmd.String("seller"))
 	if arg == "" {
 		arg = strings.TrimSpace(cmd.Args().First())
 	}
 	if prof, ok := model.ProviderByID(arg); ok && prof.ID != model.ProviderOllama {
-		return runBuyInferenceProvider(cfg, cmd, prof)
+		return fmt.Errorf("BYOK provider setup moved — run: obol model setup --provider %s", prof.ID)
 	}
 
 	u.Info("Purchasing remote inference for running Obol Agents")

cmd/obol/buy_test.go

@@ -9,7 +9,6 @@ import (
 	"github.com/ObolNetwork/obol-stack/internal/agentruntime"
 	"github.com/ObolNetwork/obol-stack/internal/buy"
 	"github.com/ObolNetwork/obol-stack/internal/config"
-	"github.com/ObolNetwork/obol-stack/internal/model"
 	"github.com/ObolNetwork/obol-stack/internal/schemas"
 )
 
@@ -603,35 +602,35 @@ func TestLooksLikeURL(t *testing.T) {
 	}
 }
 
-// TestBuyInference_BYOKFrontDoor pins the BYOK onboarding surface on
-// `obol buy inference`: the command exposes --api-key/--free/--model, and
-// every registry provider that isn't local Ollama is recognized as a
-// hosted-provider argument (the dispatch the Action keys on).
-func TestBuyInference_BYOKFrontDoor(t *testing.T) {
+// TestBuyInference_NoBYOKArm pins that `obol buy inference` is x402-only:
+// the BYOK provider arm (which previously dispatched to setupCloudProvider
+// when a provider id was passed) has been removed in favour of
+// `obol model setup`. The `--api-key` and `--free` flags went with it.
+// The command name stays reserved for future remote-credit top-ups.
+func TestBuyInference_NoBYOKArm(t *testing.T) {
 	cmd := buyInferenceCommand(&config.Config{})
 
-	want := map[string]bool{"api-key": false, "free": false, "model": false, "seller": false}
+	// BYOK-only flags must be gone; the x402 surface keeps --seller.
+	gone := map[string]bool{"api-key": false, "free": false}
+	stillHere := map[string]bool{"seller": false}
 	for _, f := range cmd.Flags {
 		for _, n := range f.Names() {
-			if _, ok := want[n]; ok {
-				want[n] = true
+			if _, ok := gone[n]; ok {
+				gone[n] = true
+			}
+			if _, ok := stillHere[n]; ok {
+				stillHere[n] = true
 			}
 		}
 	}
-	for n, found := range want {
-		if !found {
-			t.Errorf("buy inference missing --%s flag", n)
+	for n, found := range gone {
+		if found {
+			t.Errorf("buy inference must not expose --%s (BYOK arm removed; use `obol model setup`)", n)
 		}
 	}
-
-	// Hosted providers route to BYOK onboarding; ollama does not (local).
-	for _, id := range []string{"venice", "openrouter", "nvidia", "gmi", "novita", "huggingface"} {
-		p, ok := model.ProviderByID(id)
-		if !ok || p.ID == model.ProviderOllama {
-			t.Errorf("provider %q should be a BYOK buy-inference target", id)
+	for n, found := range stillHere {
+		if !found {
+			t.Errorf("buy inference missing --%s flag", n)
 		}
 	}
-	if p, ok := model.ProviderByID("ollama"); !ok || p.ID != model.ProviderOllama {
-		t.Errorf("ollama must remain a local (non-buy) provider")
-	}
 }

cmd/obol/model.go

@@ -97,17 +97,17 @@ func modelSetupCommand(cfg *config.Config) *cli.Command {
 				providers, _ := model.GetAvailableProviders(cfg)
 
 				options := make([]string, len(providers))
-				// Default to Venice — the friendliest BYOK on-ramp (cheap,
-				// no credit card to start, referral link in the JoinURL).
-				// Falls back to index 0 if Venice is ever removed from the
-				// registry.
+				// Default to OpenRouter — free roster auto-seeds when no
+				// --model is passed, so a new user gets a working remote
+				// model with zero credit-card friction. Falls back to
+				// index 0 if OpenRouter is ever removed from the registry.
 				defaultIdx := 0
 				for i, p := range providers {
 					label := fmt.Sprintf("%s (%s)", p.Name, p.ID)
 					if det, ok := creds[p.ID]; ok {
 						label += " — detected: " + det.source
 					}
-					if p.ID == "venice" {
+					if p.ID == "openrouter" {
 						defaultIdx = i
 					}
 
@@ -202,11 +202,25 @@ func setupOllama(cfg *config.Config, u *ui.UI, models []string) error {
 
 func setupCloudProvider(cfg *config.Config, u *ui.UI, prof model.ProviderInfo, apiKey string, models []string, free bool) error {
 	if apiKey == "" {
+		// Prefer JoinURL (new-user landing, possibly referral-tagged) for
+		// the browser open; fall back to KeyURL (keys dashboard). Always
+		// print both as Dim hints so the URLs are visible whether the
+		// browser opened or not.
+		onboardURL := prof.JoinURL
+		if onboardURL == "" {
+			onboardURL = prof.KeyURL
+		}
+		if onboardURL != "" && u.IsTTY() && !u.IsJSON() {
+			u.Infof("Opening %s to sign up / create an API key …", onboardURL)
+			if err := openBrowser(onboardURL); err != nil {
+				u.Dim(fmt.Sprintf("(couldn't open a browser — visit %s)", onboardURL))
+			}
+		}
 		if prof.JoinURL != "" {
 			u.Dim(fmt.Sprintf("New to %s? Sign up: %s", prof.Name, prof.JoinURL))
 		}
-		if prof.SignupURL != "" {
-			u.Dim(fmt.Sprintf("Get a %s API key: %s", prof.Name, prof.SignupURL))
+		if prof.KeyURL != "" {
+			u.Dim(fmt.Sprintf("Get a %s API key: %s", prof.Name, prof.KeyURL))
 		}
 
 		var err error
@@ -220,14 +234,24 @@ func setupCloudProvider(cfg *config.Config, u *ui.UI, prof model.ProviderInfo, a
 		}
 	}
 
+	// OpenRouter zero-friction default: when no explicit --model and no
+	// explicit --free, auto-seed the curated free roster. The Dim hint
+	// surfaces openrouter/auto as the paid upgrade for users with balance.
+	if !free && len(models) == 0 && prof.ID == "openrouter" && len(prof.Free) > 0 {
+		free = true
+		u.Dim("Seeding OpenRouter's curated free models. With account balance, use: obol model setup --provider openrouter --model openrouter/auto")
+	}
+
 	// --free: seed the provider's curated free-tier models (unless the
-	// operator already named explicit --model values).
+	// operator already named explicit --model values). The static roster
+	// is intersected against the live /v1/models response so removed or
+	// renamed ids drop out without breaking the install.
 	if free {
 		if len(prof.Free) == 0 {
 			return fmt.Errorf("--free is not available for %s (no curated free models); pass --model instead", prof.Name)
 		}
 		if len(models) == 0 {
-			models = append([]string(nil), prof.Free...)
+			models = filterFreeAgainstLive(u, prof, apiKey)
 			u.Infof("Seeding %d curated free %s model(s)", len(models), prof.Name)
 		}
 	}
@@ -260,6 +284,41 @@ func setupCloudProvider(cfg *config.Config, u *ui.UI, prof model.ProviderInfo, a
 	return promoteAndSync(cfg, u, models)
 }
 
+// filterFreeAgainstLive intersects the registry's curated Free model list
+// with the provider's live /v1/models response so removed or renamed ids
+// drop out before they hit LiteLLM. On any fetch failure (network down,
+// auth error, unparseable body) it falls back to the full static list —
+// a slightly stale roster is better than a zero-model install.
+func filterFreeAgainstLive(u *ui.UI, prof model.ProviderInfo, apiKey string) []string {
+	static := append([]string(nil), prof.Free...)
+	live, err := model.FetchOpenAICompatibleModels(prof.BaseURL, apiKey)
+	if err != nil || len(live) == 0 {
+		return static
+	}
+	liveSet := make(map[string]bool, len(live))
+	for _, id := range live {
+		liveSet[id] = true
+	}
+	filtered := make([]string, 0, len(static))
+	dropped := make([]string, 0)
+	for _, id := range static {
+		if liveSet[id] {
+			filtered = append(filtered, id)
+		} else {
+			dropped = append(dropped, id)
+		}
+	}
+	if len(filtered) == 0 {
+		// All curated ids missing from live list — likely a major rotation;
+		// fall back rather than seed nothing.
+		return static
+	}
+	if len(dropped) > 0 {
+		u.Dim(fmt.Sprintf("(%d curated free model(s) no longer listed by %s: %s)", len(dropped), prof.Name, strings.Join(dropped, ", ")))
+	}
+	return filtered
+}
+
 // resolveSetupModel picks a model when the operator passed none. A registry
 // Default wins (overridable in a TTY). With no static default — BYOK
 // aggregators whose catalog rotates — it lists the live /v1/models endpoint:
@@ -290,7 +349,7 @@ func resolveSetupModel(u *ui.UI, prof model.ProviderInfo, apiKey string) (string
 		if u.IsTTY() && !u.IsJSON() {
 			return u.Input(fmt.Sprintf("Model id for %s", prof.Name), "")
 		}
-		return "", fmt.Errorf("could not resolve a model for %s: pass --model <id> (keys/models at %s)", prof.Name, prof.SignupURL)
+		return "", fmt.Errorf("could not resolve a model for %s: pass --model <id> (keys/models at %s)", prof.Name, prof.KeyURL)
 	}
 
 	if u.IsTTY() && !u.IsJSON() {