@clawpump/claw-agent 0.1.1 → 0.1.3

package/agent/README.md

@@ -15,13 +15,13 @@
   <a href="https://github.com/NousResearch/hermes-agent">Upstream: Hermes</a>
 </p>
 
-ClawPump's full feature set — **104 MCP tools** spanning agents, trading, Phoenix perps, DCA, Jupiter lending, token launch, marketplace, predictions, and market intelligence — is wired in natively. One command:
+ClawPump's full feature set — **131 MCP tools** spanning agents, trading, Phoenix perps, DCA, Jupiter lending, token launch, marketplace, predictions, gift cards (Laso), agent mail, wallet transfers, pay.sh x402 paid APIs, and market intelligence — is wired in natively. One command:
 
 ```bash
 hermes clawpump setup     # pick remote OAuth (browser) or stdio (cpk_ key)
 ```
 
-That pairs the agent with the ClawPump MCP — remote `https://mcp.clawpump.tech/mcp`, or the local `npx @clawpump/agents` stdio path — and the ClawPump green theme is on by default. See the [ClawPump skill](skills/clawpump/SKILL.md) and the catalog entries under [`optional-mcps/`](optional-mcps/) (`clawpump`, `clawpump-stdio`).
+That pairs the agent with the ClawPump MCP — remote `https://mcp.clawpump.tech/mcp`, or the local `npx @clawpump/agents` stdio path — and the ClawPump green theme is on by default. See the [ClawPump skill](skills/clawpump/SKILL.md) and the catalog entries under [`optional-mcps/`](optional-mcps/) (`clawpump`, `clawpump-stdio`). [pay.sh](https://pay.sh) x402 paid APIs are paid straight from the agent wallet via the `pay_sh_*` tools — no separate wallet.
 
 > **Built on Hermes.** ClawPump is a downstream distribution of the **Hermes Agent** by **Nous Research**, used under the MIT License. The upstream agent — its runtime, docs, and features — is unchanged below; ClawPump adds the native ClawPump MCP integration plus init/theme branding on top. Full credit for the underlying agent goes to Nous Research. See [`LICENSE`](LICENSE).
 

package/agent/docs/UPSTREAM_SYNC.md

@@ -0,0 +1,58 @@
+# Keeping ClawPump in sync with upstream Hermes
+
+ClawPump (`Clawpump/claw-agent`) is a **fork of [`NousResearch/hermes-agent`](https://github.com/NousResearch/hermes-agent)** that shares full git history with upstream. Upstream ships very frequently (CalVer, ~daily), so we pull its changes in continuously rather than letting the fork drift.
+
+## How divergence is kept small
+
+All ClawPump-specific behavior lives in a single downstream-owned module, **`hermes_cli/distribution.py`** (skin, default skin, default MCP server, `CLAWPUMP_*` env vars, the `clawpump` subcommand, the npm self-update, the update-check repo URL). The upstream-owned files (`skin_engine.py`, `config.py`, `main.py`, `banner.py`) carry only a small, self-degrading hook each and otherwise match vanilla Hermes byte-for-byte.
+
+**Rule of thumb:** never edit an upstream-owned file to add ClawPump behavior. Add it to `distribution.py` and wire a one-line hook. The smaller the divergence in upstream files, the cleaner every sync.
+
+## Automated sync (`.github/workflows/upstream-sync.yml`)
+
+Runs daily (and via **Actions → Upstream Sync → Run workflow**). Each run:
+
+1. Fetches `upstream/main` and checks how far `main` is behind.
+2. If behind **and** no `upstream-sync` PR is already open, creates a `sync/upstream-<timestamp>` branch and **merges** `upstream/main` into it (a real merge commit, to preserve history).
+3. Opens a PR into `main`, labelled `upstream-sync` (and `has-conflicts` if the merge had conflicts — the markers are committed so you can resolve them in the branch).
+
+It is self-throttling: only one open sync PR at a time, and it no-ops when already up to date.
+
+### Reviewing / merging a sync PR
+
+- **Clean merge:** review the diff + CI, then **merge with a merge commit** (not squash — squashing discards the upstream parent and breaks future merge-bases).
+- **Conflicts:** they're almost always in docs (`README.md`, `.env.example`). Resolve in the branch:
+  ```bash
+  git fetch origin && git switch sync/upstream-<timestamp>
+  # resolve conflicts; for docs you usually keep ours
+  git add -A && git commit && git push
+  ```
+  If a conflict lands in an upstream-owned `.py` file, that's a signal a downstream edit leaked in — prefer moving that edit into `distribution.py` so it won't conflict again.
+
+### One-time setup for full CI on sync PRs
+
+PRs opened with the default `GITHUB_TOKEN` do **not** trigger other workflows, so the repo's CI (tests / lint / branding) won't auto-run on a sync PR. To get CI as the merge gate, add a repo secret **`UPSTREAM_SYNC_PAT`** (a fine-scoped PAT with `repo` + `workflow`); the workflow uses it automatically. Without it, re-run CI on the sync PR manually.
+
+### Caveats
+
+- **`contributor-check`** requires every new commit-author email to be in `AUTHOR_MAP` (`scripts/release.py`). A sync that brings in commits from a *new* upstream contributor will fail this check until you add their mapping — the check prints the exact lines to paste.
+- **`history-check`** requires a common ancestor with `main`; a real merge from our shared-history upstream always satisfies it.
+
+## Manual sync (by hand)
+
+```bash
+# one-time
+git remote add upstream https://github.com/NousResearch/hermes-agent.git
+
+git fetch --no-tags upstream main
+git switch -c sync/upstream-manual main
+git merge upstream/main
+# resolve any conflicts (usually README.md / .env.example), then:
+git commit
+git push -u origin sync/upstream-manual
+# open a PR into main
+```
+
+## Versioning
+
+Tag ClawPump releases off the upstream CalVer base plus a suffix, e.g. `v2026.6.5-clawpump.1`, so it's always clear which upstream snapshot a release is built on.

package/agent/hermes_cli/auth.py

@@ -531,6 +531,33 @@ def _resolve_kimi_base_url(api_key: str, default_url: str, env_override: str) ->
     return default_url
 
 
+# =============================================================================
+# UsePod Endpoint Derivation
+# =============================================================================
+
+# UsePod (usepod.ai) is a drop-in OpenAI-compatible proxy that authenticates by
+# the token embedded in the request PATH — ``/proxy/<token>/v1/...`` — and
+# ignores the Authorization header. The inference base URL is therefore derived
+# from the API key (the token) rather than stored as a static endpoint, so the
+# user only ever needs to paste their token.
+USEPOD_API_BASE = "https://api.usepod.ai"
+
+
+def _resolve_usepod_base_url(api_key: str, env_override: str = "") -> str:
+    """Return the UsePod proxy base URL for *api_key* (the token).
+
+    An explicit ``USEPOD_BASE_URL`` (``env_override``) always wins — e.g. for a
+    self-hosted UsePod gateway. With no token yet, return the proxy root so
+    callers degrade gracefully instead of producing a malformed URL.
+    """
+    if env_override:
+        return env_override.rstrip("/")
+    token = (api_key or "").strip()
+    if not token:
+        return f"{USEPOD_API_BASE}/proxy"
+    return f"{USEPOD_API_BASE}/proxy/{token}/v1"
+
+
 
 _PLACEHOLDER_SECRET_VALUES = {
     "*",
@@ -5657,6 +5684,8 @@ def get_api_key_provider_status(provider_id: str) -> Dict[str, Any]:
 
     if provider_id in {"kimi-coding", "kimi-coding-cn"}:
         base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)
+    elif provider_id == "usepod":
+        base_url = _resolve_usepod_base_url(api_key, env_url)
     elif env_url:
         base_url = env_url
     else:
@@ -5848,6 +5877,8 @@ def resolve_api_key_provider_credentials(provider_id: str) -> Dict[str, Any]:
         base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, env_url)
     elif provider_id == "zai":
         base_url = _resolve_zai_base_url(api_key, pconfig.inference_base_url, env_url)
+    elif provider_id == "usepod":
+        base_url = _resolve_usepod_base_url(api_key, env_url)
     elif env_url:
         base_url = env_url.rstrip("/")
     else:

package/agent/hermes_cli/banner.py

@@ -129,7 +129,10 @@ _UPDATE_CHECK_CACHE_SECONDS = 6 * 3600
 # (e.g. nix-built hermes — no local git history to count against).
 UPDATE_AVAILABLE_NO_COUNT = -1
 
-_UPSTREAM_REPO_URL = "https://github.com/Clawpump/claw-agent.git"
+try:
+    from hermes_cli.distribution import UPDATE_REPO_URL as _UPSTREAM_REPO_URL
+except Exception:
+    _UPSTREAM_REPO_URL = "https://github.com/NousResearch/hermes-agent.git"
 
 
 def _check_via_rev(local_rev: str) -> Optional[int]:

package/agent/hermes_cli/clawpump_cli.py

@@ -1,6 +1,6 @@
 """``hermes clawpump`` — one-command install/auth for the ClawPump MCP.
 
-ClawPump ships its full feature set (104 tools) as an MCP server, bundled in
+ClawPump ships its full feature set (131 tools) as an MCP server, bundled in
 the Hermes catalog as two entries:
 
   - ``clawpump``        remote OAuth over Streamable HTTP (browser, paste cpk_*)
@@ -59,9 +59,10 @@ def _cmd_setup(args) -> int:
     print()
     print(color("  ClawPump setup", Colors.GREEN + Colors.BOLD))
     print(color("  ──────────────", Colors.GREEN))
-    print("  ClawPump's 104 tools (agents, trading, perps, DCA, lending,")
-    print("  token launch, marketplace, predictions, intelligence) come in")
-    print("  through an MCP server. Two ways to connect:")
+    print("  ClawPump's 131 tools (agents, trading, perps, DCA, lending,")
+    print("  token launch, marketplace, predictions, gift cards, agent")
+    print("  mail, intelligence) come in through an MCP server. Two ways")
+    print("  to connect:")
     print()
     print(f"    1) {color('Remote', Colors.GREEN)}  — browser login, paste your cpk_* key (recommended)")
     print(f"    2) {color('Stdio', Colors.GREEN)}   — local npx, store the cpk_* key in ~/.hermes/.env")
@@ -220,7 +221,7 @@ def add_parser(subparsers) -> None:
         help="ClawPump (Solana token launch, trading, perps, DeFi) via MCP",
         description=(
             "Install and authenticate the ClawPump MCP server, then manage which "
-            "of its 104 tools are enabled. Subcommands: setup (default: status), "
+            "of its 131 tools are enabled. Subcommands: setup (default: status), "
             "login, status, tools."
         ),
     )

package/agent/hermes_cli/config.py

@@ -741,23 +741,7 @@ DEFAULT_CONFIG = {
     "fallback_providers": [],
     "credential_pool_strategies": {},
     "toolsets": ["hermes-cli"],
-    # ClawPump is enabled by default in this distribution: the remote MCP
-    # server (the full ClawPump tool surface) comes pre-wired. On first connect
-    # Hermes opens a browser to log in to ClawPump — that one step is per-user
-    # auth and cannot be skipped — after which the mcp_clawpump_* tools load
-    # automatically. The bundled `clawpump` skill requires explicit user
-    # confirmation before any financial/irreversible tool runs. Prune the tool
-    # set any time with `hermes mcp configure clawpump`.
-    "mcp_servers": {
-        "clawpump": {
-            # TODO: switch to https://mcp.clawpump.tech/mcp once the DNS CNAME
-            # is configured; the custom domain is currently NXDOMAIN, so point
-            # at the live Railway domain so a fresh install connects.
-            "url": "https://clawpump-mcp-production.up.railway.app/mcp",
-            "auth": "oauth",
-            "enabled": True,
-        },
-    },
+    "mcp_servers": {},
     "agent": {
         "max_turns": 90,
         # Inactivity timeout for gateway agent execution (seconds).
@@ -1337,7 +1321,7 @@ DEFAULT_CONFIG = {
         # failure isn't silent from the UI's perspective.  Set false to suppress.
         "turn_completion_explainer": True,
         "show_cost": False,       # Show $ cost in the status bar (off by default)
-        "skin": "clawpump",       # ClawPump brand (green claw). Switch with /skin or display.skin.
+        "skin": "default",       # distribution default (clawpump) applied via distribution.apply_config_overlay
         # UI language for static user-facing messages (approval prompts, a
         # handful of gateway slash-command replies).  Does NOT affect agent
         # responses, log lines, tool outputs, or slash-command descriptions.
@@ -3395,38 +3379,21 @@ OPTIONAL_ENV_VARS = {
         "password": False,
         "category": "setting",
     },
-
-    # ── ClawPump (Solana token launch, trading, perps, DeFi) ──
-    # Used by the stdio ClawPump MCP path (`npx @clawpump/agents`, catalog
-    # entry `clawpump-stdio`). The remote OAuth path (`clawpump`) stores
-    # per-user tokens under ~/.hermes/mcp-tokens/ instead and needs no key
-    # here. The ClawPump tools themselves come from the MCP server, not the
-    # native registry, so there's no `tools` list.
-    "CLAWPUMP_API_KEY": {
-        "description": "ClawPump API key (cpk_*) for the ClawPump MCP stdio transport",
-        "prompt": "ClawPump API key (cpk_…)",
-        "url": "https://agents.clawpump.tech/dashboard/api",
-        "password": True,
-        "category": "tools",
-    },
-    "CLAWPUMP_API_URL": {
-        "description": "ClawPump backend URL override (advanced — leave empty for the default)",
-        "prompt": "ClawPump backend URL (leave empty for default)",
-        "url": None,
-        "password": False,
-        "category": "tools",
-        "advanced": True,
-    },
-    "CLAWPUMP_DEFAULT_AGENT": {
-        "description": "Default ClawPump agent id (optional — skips agent-selection prompts)",
-        "prompt": "Default ClawPump agent id (optional)",
-        "url": None,
-        "password": False,
-        "category": "tools",
-        "advanced": True,
-    },
 }
 
+# ── ClawPump distribution overlay (downstream) ───────────────────────────
+# Apply ClawPump's defaults (pre-wired MCP server + default skin) and env-var
+# registry from the downstream-owned overlay, keeping this upstream-owned file
+# mergeable. No-ops on vanilla Hermes (module/keys absent).
+try:
+    from hermes_cli import distribution as _distribution
+
+    _distribution.apply_config_overlay(DEFAULT_CONFIG)
+    _distribution.apply_env_var_overlay(OPTIONAL_ENV_VARS)
+except Exception:
+    pass
+
+
 # Tool Gateway env vars are always visible — they're useful for
 # self-hosted / custom gateway setups regardless of subscription state.
 

package/agent/hermes_cli/distribution.py

@@ -0,0 +1,230 @@
+"""ClawPump distribution overlay (downstream-owned).
+
+This module is the single home for everything that makes this distribution
+"ClawPump" rather than vanilla Hermes. Keeping it here -- instead of editing
+upstream-owned files (skin_engine.py, config.py, ...) -- keeps those files
+byte-for-byte mergeable with NousResearch/hermes-agent, so syncing upstream
+stays (near) conflict-free.
+
+Every upstream consumer imports this lazily and degrades to vanilla Hermes
+when the module (or a given key) is absent. Keep imports light: config.py
+imports this at startup.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+# Default skin for this distribution (vanilla Hermes uses "default").
+DEFAULT_SKIN = "clawpump"
+
+# Git remote the in-app update check compares against (vanilla Hermes uses
+# NousResearch/hermes-agent).
+UPDATE_REPO_URL = "https://github.com/Clawpump/claw-agent.git"
+
+# Extra top-level CLI subcommands this distribution adds (kept in sync with
+# main.py's _BUILTIN_SUBCOMMANDS validation set via a hook there).
+EXTRA_SUBCOMMANDS = ("clawpump",)
+
+# ── Skins shipped by this distribution ───────────────────────────────────
+# Moved verbatim out of hermes_cli/skin_engine.py:_BUILTIN_SKINS and merged
+# back into that dict by a small hook there, so every skin consumer
+# (list_skins / load_skin / get_active_skin) sees it unchanged.
+BUILTIN_SKINS: Dict[str, Dict[str, Any]] = {
+    "clawpump": {
+        "name": "clawpump",
+        "description": "ClawPump — Solana green, claw mark (built on Hermes)",
+        "colors": {
+            "banner_border": "#16A34A",
+            "banner_title": "#4ADE80",
+            "banner_accent": "#22C55E",
+            "banner_dim": "#15803D",
+            "banner_text": "#DCFCE7",
+            "ui_accent": "#22C55E",
+            "ui_label": "#4ADE80",
+            "ui_ok": "#22C55E",
+            "ui_error": "#ef5350",
+            "ui_warn": "#ffa726",
+            "prompt": "#DCFCE7",
+            "input_rule": "#16A34A",
+            "response_border": "#4ADE80",
+            "status_bar_bg": "#0B1F14",
+            "status_bar_text": "#DCFCE7",
+            "status_bar_strong": "#4ADE80",
+            "status_bar_dim": "#3F6B50",
+            "status_bar_good": "#22C55E",
+            "status_bar_warn": "#FACC15",
+            "status_bar_bad": "#F59E0B",
+            "status_bar_critical": "#EF5350",
+            "session_label": "#4ADE80",
+            "session_border": "#3F6B50",
+            "selection_bg": "#14532D",
+            "completion_menu_bg": "#06140C",
+            "completion_menu_current_bg": "#14532D",
+            "completion_menu_meta_bg": "#0B1F14",
+            "completion_menu_meta_current_bg": "#14532D",
+        },
+        "spinner": {
+            "waiting_faces": ["(◴)", "(◷)", "(◶)", "(◵)", "(<>)"],
+            "thinking_faces": ["(✦)", "(◇)", "(◈)", "(⌁)", "(<>)"],
+            "thinking_verbs": [
+                "pumping", "launching", "scanning the mints", "routing the swap",
+                "reading the chart", "minting", "snapping the claw", "checking liquidity",
+            ],
+            "wings": [
+                ["⟪◇", "◇⟫"],
+                ["⟪✦", "✦⟫"],
+                ["⟪>", "<⟫"],
+                ["⟪◈", "◈⟫"],
+            ],
+        },
+        "branding": {
+            "agent_name": "ClawPump",
+            "org": "ClawPump",
+            "credit": "built on Hermes ☤ by Nous Research",
+            "welcome": "Welcome to ClawPump 🦀 — Solana agents, trading & token launch. Type your message or /help for commands.",
+            "goodbye": "Claws out! 🦀",
+            "response_label": " ✦ ClawPump ",
+            "prompt_symbol": "❯",
+            "help_header": "(✦) Available Commands",
+        },
+        "tool_prefix": "┊",
+        "banner_logo": """[bold #86EFAC] ██████╗██╗      █████╗ ██╗    ██╗██████╗ ██╗   ██╗███╗   ███╗██████╗ [/]
+[bold #4ADE80]██╔════╝██║     ██╔══██╗██║    ██║██╔══██╗██║   ██║████╗ ████║██╔══██╗[/]
+[#22C55E]██║     ██║     ███████║██║ █╗ ██║██████╔╝██║   ██║██╔████╔██║██████╔╝[/]
+[#16A34A]██║     ██║     ██╔══██║██║███╗██║██╔═══╝ ██║   ██║██║╚██╔╝██║██╔═══╝ [/]
+[#15803D]╚██████╗███████╗██║  ██║╚███╔███╔╝██║     ╚██████╔╝██║ ╚═╝ ██║██║     [/]
+[#166534] ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝ ╚═╝      ╚═════╝ ╚═╝     ╚═╝╚═╝     [/]""",
+        "banner_hero": """[#86EFAC]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠠⣀⣂⣤⣤⣤⣤⣤⣤⠄[/]
+[#7EE5A4]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣢⣵⣾⣿⣿⣿⣿⣿⣿⣿⡿⠃⠀[/]
+[#77DA9B]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣴⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠀⠀⠀[/]
+[#6FD093]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⣾⠟⠁⢀⣼⣿⣿⣿⣿⣿⣿⣿⡿⠀⠀⠀⠀⠀[/]
+[#68C58A]⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣜⡿⠁⢀⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⠗⠀⠀⠀⠀⠀[/]
+[#60BB82]⠀⠀⠀⠀⠀⠀⠀⠀⢀⣮⣿⣇⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠁⠀⠀⠀⠀⠀⠀[/]
+[#58B179]⠀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠃⣸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀[/]
+[#51A671]⠀⠀⠀⠀⠀⠀⢀⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠃⠀⠀⠀⠀⠀⠀⠀[/]
+[#499C68]⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
+[#429160]⠀⠀⠀⠀⠀⣀⣈⡙⠻⢿⣿⣿⣿⣿⣿⣿⡿⠋⣡⣤⣤⠀⠀⠀⠀⠀⠐⢀⣠⣴[/]
+[#3A8757]⠀⠀⠀⢀⣞⣿⠟⠉⣷⣦⣌⠙⢿⣿⣿⣿⣠⣾⣿⣿⣿⣷⣷⣶⣶⣶⣿⣿⣿⠃[/]
+[#327D4F]⠀⠀⣀⣉⡛⠳⢴⣾⣿⣿⣿⣷⣄⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠁⠀[/]
+[#2B7246]⢠⣞⣿⡟⣩⣿⣶⣌⠻⢿⣿⣿⣿⣆⠘⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠋⠀⠀⠀[/]
+[#23683E]⠀⠉⠙⠻⢿⣿⣿⣿⣷⣄⠻⣿⣿⣿⡀⠹⢿⣿⣿⣿⣿⠿⠟⠋⠁⠀⠀⠀⠀⠀[/]
+[#1C5D35]⠀⠀⠀⠀⠀⠈⠻⣿⣿⣿⣆⠹⣿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
+[#14532D]⠀⠀⠀⠀⠀⠀⠀⠘⢿⣿⠟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]""",
+    },
+}
+
+
+# ── Default-config overlay ───────────────────────────────────────────────
+# ClawPump ships its remote MCP server pre-wired and the clawpump skin as the
+# default brand. Applied onto DEFAULT_CONFIG by a hook in config.py.
+_CLAWPUMP_MCP_SERVER = {
+    # TODO: switch to https://mcp.clawpump.tech/mcp once the DNS CNAME is
+    # configured; the custom domain is currently NXDOMAIN, so point at the
+    # live Railway domain so a fresh install connects.
+    "url": "https://clawpump-mcp-production.up.railway.app/mcp",
+    "auth": "oauth",
+    "enabled": True,
+}
+
+
+def apply_config_overlay(default_config: Dict[str, Any]) -> None:
+    """Apply ClawPump defaults onto a freshly-built DEFAULT_CONFIG.
+
+    Pre-wires the remote ClawPump MCP server (the full tool surface; first
+    connect opens a browser for per-user OAuth, after which the mcp_clawpump_*
+    tools load automatically -- prune with ``hermes mcp configure clawpump``)
+    and makes the clawpump skin the default brand. Idempotent.
+    """
+    servers = default_config.setdefault("mcp_servers", {})
+    if isinstance(servers, dict):
+        servers.setdefault("clawpump", dict(_CLAWPUMP_MCP_SERVER))
+    display = default_config.get("display")
+    if isinstance(display, dict):
+        display["skin"] = DEFAULT_SKIN
+
+
+# ── OPTIONAL_ENV_VARS overlay ────────────────────────────────────────────
+# ClawPump (Solana token launch, trading, perps, DeFi). Used by the stdio
+# ClawPump MCP path (``npx @clawpump/agents``, catalog entry
+# ``clawpump-stdio``). The remote OAuth path (``clawpump``) stores per-user
+# tokens under ~/.hermes/mcp-tokens/ instead and needs no key here.
+_CLAWPUMP_ENV_VARS: Dict[str, Dict[str, Any]] = {
+    "CLAWPUMP_API_KEY": {
+        "description": "ClawPump API key (cpk_*) for the ClawPump MCP stdio transport",
+        "prompt": "ClawPump API key (cpk_…)",
+        "url": "https://agents.clawpump.tech/dashboard/api",
+        "password": True,
+        "category": "tools",
+    },
+    "CLAWPUMP_API_URL": {
+        "description": "ClawPump backend URL override (advanced — leave empty for the default)",
+        "prompt": "ClawPump backend URL (leave empty for default)",
+        "url": None,
+        "password": False,
+        "category": "tools",
+        "advanced": True,
+    },
+    "CLAWPUMP_DEFAULT_AGENT": {
+        "description": "Default ClawPump agent id (optional — skips agent-selection prompts)",
+        "prompt": "Default ClawPump agent id (optional)",
+        "url": None,
+        "password": False,
+        "category": "tools",
+        "advanced": True,
+    },
+}
+
+
+def apply_env_var_overlay(optional_env_vars: Dict[str, Any]) -> None:
+    """Register ClawPump's env vars into config.OPTIONAL_ENV_VARS. Idempotent."""
+    for name, spec in _CLAWPUMP_ENV_VARS.items():
+        optional_env_vars.setdefault(name, dict(spec))
+
+
+# ── CLI integration ──────────────────────────────────────────────────────
+
+
+def register_subparsers(subparsers) -> None:
+    """Register distribution-specific CLI subcommands.
+
+    Wires the ``clawpump`` command (ClawPump MCP install / auth / tool
+    selection) onto the top-level argparse subparsers.
+    """
+    from hermes_cli.clawpump_cli import add_parser as _add_clawpump_parser
+
+    _add_clawpump_parser(subparsers)
+
+
+def try_self_update(project_root: Any) -> bool:
+    """Handle distribution-specific self-update; return True if handled.
+
+    ClawPump agents installed via ``npx @clawpump/claw-agent`` have no git
+    checkout (the bundle ships inside the npm package), so the normal git-pull
+    update can't apply -- re-run the npm installer instead. Returns False when
+    this isn't an npm-bundle install, so the caller falls through to the
+    standard (git / pip / docker) update paths.
+    """
+    from pathlib import Path
+
+    if not (Path(project_root) / ".claw-bundle").exists():
+        return False
+
+    import shutil
+    import subprocess
+    import sys
+
+    print("→ Updating ClawPump agent via npm (npx @clawpump/claw-agent@latest)…")
+    npx = shutil.which("npx")
+    if not npx:
+        print("✗ npx (Node.js) not found. Install Node.js, then run:")
+        print("    npx @clawpump/claw-agent@latest")
+        sys.exit(1)
+    try:
+        subprocess.run([npx, "-y", "@clawpump/claw-agent@latest"], check=True)
+    except subprocess.CalledProcessError as exc:
+        print(f"✗ Update failed (exit {exc.returncode}). Try manually:")
+        print("    npx @clawpump/claw-agent@latest")
+        sys.exit(1)
+    print("✓ ClawPump agent updated. Restart your session with `claw`.")
+    return True

package/agent/hermes_cli/main.py

@@ -5806,19 +5806,31 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
             pass
     effective_base = current_base or pconfig.inference_base_url
 
-    try:
-        override = input(f"Base URL [{effective_base}]: ").strip()
-    except (KeyboardInterrupt, EOFError):
-        print()
-        override = ""
-    if override and base_url_env:
-        if not override.startswith(("http://", "https://")):
-            print(
-                "  Invalid URL — must start with http:// or https://. Keeping current value."
-            )
-        else:
-            save_env_value(base_url_env, override)
-            effective_base = override
+    if provider_id == "usepod":
+        # UsePod authenticates by the token embedded in the URL path, so there
+        # is no base URL for the user to type — it is derived from the pasted
+        # key. Skip the prompt; honour USEPOD_BASE_URL only for self-hosting.
+        from hermes_cli.auth import _resolve_usepod_base_url
+
+        key_for_probe = existing_key or (get_env_value(key_env) if key_env else "")
+        env_override = ""
+        if base_url_env:
+            env_override = get_env_value(base_url_env) or os.getenv(base_url_env, "")
+        effective_base = _resolve_usepod_base_url(key_for_probe, env_override)
+    else:
+        try:
+            override = input(f"Base URL [{effective_base}]: ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print()
+            override = ""
+        if override and base_url_env:
+            if not override.startswith(("http://", "https://")):
+                print(
+                    "  Invalid URL — must start with http:// or https://. Keeping current value."
+                )
+            else:
+                save_env_value(base_url_env, override)
+                effective_base = override
 
     # Model selection — resolution order:
     #   1. models.dev registry (cached, filtered for agentic/tool-capable models)
@@ -5857,6 +5869,22 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
         )
         if model_list:
             print(f"  Found {len(model_list)} model(s) from Ollama Cloud")
+    elif provider_id == "usepod":
+        from hermes_cli.models import fetch_api_models
+        from providers import get_provider_profile
+
+        api_key_for_probe = existing_key or (get_env_value(key_env) if key_env else "")
+        live_models = fetch_api_models(api_key_for_probe, effective_base)
+        if live_models:
+            model_list = live_models
+            print(f"  Found {len(model_list)} model(s) from {pconfig.name} API")
+        else:
+            _pp = get_provider_profile("usepod")
+            model_list = list(getattr(_pp, "fallback_models", ()) or [])
+            if model_list:
+                print(
+                    f'  Showing {len(model_list)} curated models — use "Enter custom model name" for others.'
+                )
     elif provider_id == "novita":
         from hermes_cli.models import fetch_api_models
 
@@ -5964,7 +5992,13 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
             model = {"default": model} if model else {}
             cfg["model"] = model
         model["provider"] = provider_id
-        model["base_url"] = effective_base
+        if provider_id == "usepod":
+            # The effective base URL embeds the token; persisting it would bake
+            # the secret into config.yaml and go stale on key rotation. Runtime
+            # always re-derives it from the current USEPOD_API_KEY.
+            model.pop("base_url", None)
+        else:
+            model["base_url"] = effective_base
         if provider_id in {"opencode-zen", "opencode-go"}:
             model["api_mode"] = opencode_model_api_mode(provider_id, selected)
         else:
@@ -9179,28 +9213,6 @@ def _discard_lockfile_churn(git_cmd, repo_root):
         pass
 
 
-def _cmd_update_claw_npm():
-    """Update a ClawPump agent that was installed via ``npx @clawpump/claw-agent``.
-
-    These installs have no git checkout (the bundle ships inside the npm
-    package), so the normal git-pull update can't apply. Re-run the npm
-    installer instead — it re-bundles the latest and reinstalls in place.
-    """
-    print("→ Updating ClawPump agent via npm (npx @clawpump/claw-agent@latest)…")
-    npx = shutil.which("npx")
-    if not npx:
-        print("✗ npx (Node.js) not found. Install Node.js, then run:")
-        print("    npx @clawpump/claw-agent@latest")
-        sys.exit(1)
-    try:
-        subprocess.run([npx, "-y", "@clawpump/claw-agent@latest"], check=True)
-    except subprocess.CalledProcessError as exc:
-        print(f"✗ Update failed (exit {exc.returncode}). Try manually:")
-        print("    npx @clawpump/claw-agent@latest")
-        sys.exit(1)
-    print("✓ ClawPump agent updated. Restart your session with `claw`.")
-
-
 def cmd_update(args):
     """Update Hermes Agent to the latest version.
 
@@ -9219,10 +9231,13 @@ def cmd_update(args):
         managed_error("update Hermes Agent")
         return
 
-    # ClawPump agents installed via `npx @clawpump/claw-agent` have no git
-    # checkout to pull — update by re-running the npm installer instead.
-    if (PROJECT_ROOT / ".claw-bundle").exists():
-        _cmd_update_claw_npm()
+    # Distribution-specific self-update (e.g. ClawPump's npm bundle, which has
+    # no git checkout to pull). No-op on vanilla Hermes.
+    try:
+        from hermes_cli import distribution as _distribution
+    except Exception:
+        _distribution = None
+    if _distribution is not None and _distribution.try_self_update(PROJECT_ROOT):
         return
 
     # Docker users can't ``git pull`` — the image excludes ``.git`` from
@@ -11485,7 +11500,7 @@ def cmd_logs(args):
 # to parse.
 _BUILTIN_SUBCOMMANDS = frozenset(
     {
-        "acp", "auth", "backup", "bundles", "checkpoints", "claw", "clawpump", "completion",
+        "acp", "auth", "backup", "bundles", "checkpoints", "claw", "completion",
         "computer-use",
         "config", "cron", "curator", "dashboard", "debug", "doctor",
         "dump", "fallback", "gateway", "hooks", "import", "insights",
@@ -11502,6 +11517,14 @@ _BUILTIN_SUBCOMMANDS = frozenset(
     }
 )
 
+# Distribution-specific subcommands (e.g. ClawPump). No-op on vanilla Hermes.
+try:
+    from hermes_cli import distribution as _distribution
+
+    _BUILTIN_SUBCOMMANDS = _BUILTIN_SUBCOMMANDS | frozenset(_distribution.EXTRA_SUBCOMMANDS)
+except Exception:
+    pass
+
 
 # Top-level flags that take a value. Needed by ``_first_positional_argv``
 # so that in ``hermes -m gpt5 chat``, ``gpt5`` is correctly skipped as a
@@ -12782,10 +12805,14 @@ def main():
     _add_portal_parser(subparsers)
 
     # =========================================================================
-    # clawpump command — ClawPump MCP install / auth / tool selection
+    # Distribution-specific subcommands (e.g. ClawPump). No-op on vanilla Hermes.
     # =========================================================================
-    from hermes_cli.clawpump_cli import add_parser as _add_clawpump_parser
-    _add_clawpump_parser(subparsers)
+    try:
+        from hermes_cli import distribution as _distribution
+    except Exception:
+        _distribution = None
+    if _distribution is not None:
+        _distribution.register_subparsers(subparsers)
 
     # =========================================================================
     # kanban command — multi-profile collaboration board