release: v0.10.0-rc12 (consolidate #593/#594/#595/#597 + review hardening) (#600)

* Work on openapi spec for services

* Improve 402 html page

* Update storefronts

* feat(buy-x402): add --set-default so the agent self-adopts paid/<model> as primary

After a persistent inference buy publishes paid/<remote-model> in LiteLLM, the
agent adopts it as its own primary chat model in-pod via native
'hermes config set model.default' (atomic write, per-request re-read, no restart,
no host CLI, no new RBAC). Includes a LiteLLM /v1/models existence guard, an
auto-refill safety warning, and a PyYAML fallback writer.

Validated by a design+adversarial workflow and a live CLI smoke against a running
obol-agent: buy --set-default flips config.yaml model.default to paid/AEON-7/... and
the next agent chat settled via the x402-buyer pool (spent 0->1) with no restart;
rollback verified.

* Have agent stream responses to keep the tunnel alive

* security(x402): SRI-pin the Scalar bundle on the public /api page

The /api OpenAPI reference is served over the public tunnel and pulls the
@scalar/api-reference bundle from jsdelivr. The integrity hash was left empty
in phase 1, so the browser executed whatever the CDN returned, unverified.

Populate scalarBundleSRI with the sha384 of the pinned 1.34.0 bundle so a
tampered CDN response is blocked. Comment updated to stress the hash must be
re-derived in lockstep with every scalarBundleVersion bump.

* fix(buy-x402): run --set-default existence guard before auto-refill warning

The 'paid/<model> not selectable in LiteLLM' guard ran *after* the
no-auto-refill WARNING. A model that LiteLLM would refuse still printed a
scary 'every chat turn fails when the pool empties' warning describing a
primary-model failure mode that cannot occur when the default was never
switched. Reorder so we refuse first and only warn when we are actually
about to adopt the model.

* security(x402): sanitize ServiceOffer-sourced tokens in 402 copy-paste commands

spec.model.name and metadata.name flow from the ServiceOffer CR into
copy-pasteable 'obol buy inference ...' commands rendered on the public 402
page. A hostile or fat-fingered offer could smuggle shell metacharacters into
a command a reader might paste. Add sanitizeDisplayToken at the render
boundary: CR-sourced tokens must match the model-id/k8s-name charset
(^[A-Za-z0-9._:/-]+$) or collapse to the existing safe placeholder. Real ids
like qwen3.5:9b and anthropic/claude-3-5-sonnet-latest pass through unchanged.

* docs(claude): compress and correct CLAUDE.md; fold in #597 streaming/sell-agent facts

Terse rewrite of project CLAUDE.md (42725 -> 41797 bytes) corrected against the live codebase. Preserves all invariants, the 14 pitfalls, and flag warnings; adds #597's stream:true / statusRecorder.Flush guidance and agent-backed-offer (port 8642) facts so the compressed doc loses nothing rc12 ships.

---------

Co-authored-by: Oisín Kyne <oisin@obol.tech>
Co-authored-by: bussyjd <jd@obol.tech>
Co-authored-by: bussyjd <bussyjd@users.noreply.github.com>

Author: 3 people

CLAUDE.md

@@ -195,8 +195,9 @@ Examples:
 				Usage: "Agent name for ERC-8004 registration (defaults to the offer name)",
 			},
 			&cli.StringFlag{
-				Name:  "register-description",
-				Usage: "Agent description for ERC-8004 registration",
+				Name:    "description",
+				Aliases: []string{"register-description"},
+				Usage:   "Human-readable description of the service. Surfaced on the 402 payment page, in the storefront catalog, and (when registration is enabled) on the ERC-8004 registration document.",
 			},
 			&cli.StringFlag{
 				Name:  "register-image",
@@ -296,6 +297,18 @@ Examples:
 			if modelFlag == "" {
 				return fmt.Errorf("--model is required (or run interactively to auto-detect)")
 			}
+			// LiteLLM's `paid/*` wildcard route doesn't match model names
+			// containing `/` — buyers signing against this seller would see
+			// requests fall through to the buyer sidecar with a 404 (see
+			// CLAUDE.md and the obol-agent's recent buy report). Reject
+			// up-front and suggest a `--` separator that survives the route.
+			if strings.Contains(modelFlag, "/") {
+				return fmt.Errorf(
+					"--model %q contains '/', which breaks LiteLLM's `paid/*` wildcard on the buyer side; "+
+						"use `--` (or another non-slash separator) — e.g. `%s` instead of `%s`",
+					modelFlag, strings.ReplaceAll(modelFlag, "/", "--"), modelFlag,
+				)
+			}
 
 			teeType := cmd.String("tee")
 			modelHash := cmd.String("model-hash")
@@ -345,7 +358,7 @@ Examples:
 			persistedRegistration, _, regErr := buildSellRegistrationConfig(name, sellRegistrationInput{
 				NoRegister:    cmd.Bool("no-register"),
 				Name:          cmd.String("register-name"),
-				Description:   cmd.String("register-description"),
+				Description:   cmd.String("description"),
 				Image:         cmd.String("register-image"),
 				Skills:        cmd.StringSlice("register-skills"),
 				Domains:       cmd.StringSlice("register-domains"),
@@ -601,8 +614,9 @@ Examples:
 				Usage: "Agent name for ERC-8004 registration",
 			},
 			&cli.StringFlag{
-				Name:  "register-description",
-				Usage: "Agent description for ERC-8004 registration",
+				Name:    "description",
+				Aliases: []string{"register-description"},
+				Usage:   "Human-readable description of the service. Surfaced on the 402 payment page, in the storefront catalog, and (when registration is enabled) on the ERC-8004 registration document.",
 			},
 			&cli.StringFlag{
 				Name:  "register-image",
@@ -799,7 +813,7 @@ Examples:
 				NoRegister:    cmd.Bool("no-register"),
 				Register:      cmd.Bool("register"),
 				Name:          cmd.String("register-name"),
-				Description:   cmd.String("register-description"),
+				Description:   cmd.String("description"),
 				Image:         cmd.String("register-image"),
 				Skills:        cmd.StringSlice("register-skills"),
 				Domains:       cmd.StringSlice("register-domains"),
@@ -1362,7 +1376,7 @@ var demoTypes = map[string]demoSpec{
 	"quant": {
 		Type:         "quant",
 		Price:        "10",
-		Description:  "Agent-backed chain analyst (Agent CRD + ServiceOffer of type=agent)",
+		Description:  "A simple example agent that can analyse Ethereum and Base for you",
 		NeedsERPC:    true,
 		DefaultChain: "ethereum",
 		DefaultToken: "OBOL",
@@ -3861,7 +3875,7 @@ func buildResumeGatewayArgs(d *inference.Deployment) []string {
 			args = append(args, "--register-name", v)
 		}
 		if v, _ := d.Registration["description"].(string); v != "" {
-			args = append(args, "--register-description", v)
+			args = append(args, "--description", v)
 		}
 		if v, _ := d.Registration["image"].(string); v != "" {
 			args = append(args, "--register-image", v)

cmd/obol/sell.go

@@ -75,8 +75,9 @@ Examples:
 				Usage: "Agent name for ERC-8004 registration (defaults to the offer name)",
 			},
 			&cli.StringFlag{
-				Name:  "register-description",
-				Usage: "Agent description for ERC-8004 registration (defaults to the agent's objective)",
+				Name:    "description",
+				Aliases: []string{"register-description"},
+				Usage:   "Human-readable description of the service. Surfaced on the 402 payment page, in the storefront catalog, and (when registration is enabled) on the ERC-8004 registration document. Defaults to the agent's objective.",
 			},
 		},
 		Action: func(ctx context.Context, cmd *cli.Command) error {
@@ -173,7 +174,7 @@ Examples:
 			if regName == "" {
 				regName = name
 			}
-			regDesc := strings.TrimSpace(cmd.String("register-description"))
+			regDesc := strings.TrimSpace(cmd.String("description"))
 			if regDesc == "" {
 				regDesc = agent.Objective
 			}
@@ -418,6 +419,16 @@ func runAgentBackedDemo(
 		"metadata": map[string]any{
 			"name":      name,
 			"namespace": offerNs,
+			// Agent-backed demos can't live in the legacy "demo"
+			// namespace today (the controller's confused-deputy guard at
+			// agent_resolver.go forces spec.agent.ref.namespace ==
+			// offer.namespace), so the catalog renderer can't infer
+			// "demo" from offer.namespace alone. The obol.org/demo
+			// label is the explicit signal — keep it set here so quant
+			// and friends show up under "Demo services" on the
+			// storefront. Drop this once we relax the cross-namespace
+			// guard (see plans/openapi-402-followups.md).
+			"labels": map[string]any{"obol.org/demo": "true"},
 		},
 		"spec": specMap,
 	}

cmd/obol/sell_agent.go

@@ -1396,7 +1396,7 @@ func TestBuildResumeGatewayArgs(t *testing.T) {
 				"--per-mtok", "23",
 				"--facilitator", "https://x402.gcp.obol.tech",
 				"--register-name", "Qwen3.6-27B AEON Ultimate",
-				"--register-description", "Uncensored Qwen3.6-27B abliteration",
+				"--description", "Uncensored Qwen3.6-27B abliteration",
 				"--register-skills", "llm/inference",
 				"--register-skills", "llm/uncensored",
 				"--register-domains", "inference.v1337.org",
@@ -1419,7 +1419,7 @@ func TestBuildResumeGatewayArgs(t *testing.T) {
 			},
 			wantNoSub: []string{
 				"--register-name",
-				"--register-description",
+				"--description",
 			},
 		},
 		{

cmd/obol/sell_test.go

@@ -10,6 +10,7 @@ Purchase access to remote x402-gated services. There are two flows, picked by us
 
 - **`pay <url>`** — single-shot. Probe the URL, sign **one** payment authorization, attach `X-PAYMENT`, send the request, return the response. Stateless. Use for `type:http` services and any one-off purchase. Max loss = price of one request.
 - **`buy <name>`** — pre-payment budget. Pre-sign **N** authorizations, declare them in a `PurchaseRequest` CR, let the `x402-buyer` sidecar spend them transparently as the agent calls the model through LiteLLM at `paid/<remote-model>`. Use for long-running paid inference. Max loss = N × price; runtime path holds zero signer access.
+- **`buy <name> --model <id> --set-default`** — same as `buy` above, then adopt `paid/<remote-model>` as the agent's **own primary model**, in-pod, by itself: an atomic `hermes config set model.default` that Hermes re-reads per request (effective next chat turn, **no restart**, no host-side `obol model prefer`/`obol model sync`). Refuses if the model isn't selectable in LiteLLM. Pair with `--auto-refill` so the primary model doesn't brick when the pre-signed pool empties.
 
 Both flows auto-detect the token + transfer method from the seller's 402 response. Currently supported: **USDC via EIP-3009** (Base Sepolia, Base Mainnet, Ethereum Mainnet) and **OBOL via Permit2** (Ethereum Mainnet).
 
@@ -71,6 +72,18 @@ This is one tx, ~46k gas, valid forever (unless the user later revokes). EIP-300
   storefront publishes machine-readable metadata at
   `<base>/api/services.json` with full asset, EIP-712 signing domain,
   transfer method, and atomic-unit price for every offered service.
+- **`pay` timeout defaults to ~100 s.** This is the Cloudflare free-tier
+  tunnel cap — longer requests get killed by the edge before our client
+  ever sees a response. Reasoning models, long generations, or large
+  batches need `--timeout <seconds>` set explicitly, and the seller's own
+  upstream/edge limit still applies.
+- **Avoid `/` in remote model identifiers.** LiteLLM's `paid/*` wildcard
+  route only matches a single segment; a remote `vendor/model` would
+  resolve to `paid/vendor/model` and miss the wildcard, so the request
+  falls through to the buyer sidecar and 404s. Sellers should use a non-
+  slash separator (e.g. `vendor--model`); buyers signing against a
+  legacy slashed name need the controller to insert an explicit LiteLLM
+  entry for the alias (`addLiteLLMModelEntry`).
 
 ## When to Use
 
@@ -150,6 +163,7 @@ python3 ${OBOL_SKILLS_DIR:-/data/.openclaw/skills}/buy-x402/scripts/buy.py maint
 | `probe <url> [--model <id>] [--type http\|inference] [--method GET\|POST]` | Send request without payment, parse 402 response for pricing |
 | `pay <url> [--type http\|inference] [--method GET\|POST] [--data <body>]` | Single-shot paid request: sign 1 auth, attach X-PAYMENT, send |
 | `buy <name> --endpoint <url> --model <id> [--budget N] [--count N]` | Pre-sign auths, create/update `PurchaseRequest`, expose `paid/<model>` |
+| `buy <name> --endpoint <url> --model <id> --set-default [--auto-refill]` | As above, then set `paid/<model>` as the agent's own primary model in-pod (no restart, no host CLI) |
 | `process <name> \| --all` | Reconcile `autoRefill` policies against live `x402-buyer` status |
 | `list` | List purchased providers + remaining auth counts |
 | `status <name>` | Check sidecar pod status + remaining auths |