hive-intelligence 1.8.0 → 1.10.0

package/README.md

@@ -19,9 +19,10 @@ hosted MCP server, local `stdio` runtime, CLI, and REST API.
 npx -y -p hive-intelligence@latest hive init --all --skip-verify
 ```
 
-Use the hosted MCP when you want Hive to run auth, rate limits, provider
-infrastructure, and runtime status. Use local `stdio` when you want desktop
-client setup, self-hosting, or provider-key experiments.
+Use the hosted MCP when your client can add a remote MCP URL. Use local `stdio`
+for desktop clients that only launch local processes (it proxies to the hosted
+MCP by default), or opt into `hive serve --local` to self-host with your own
+provider keys.
 
 ## What You Get
 
@@ -41,7 +42,7 @@ client setup, self-hosting, or provider-key experiments.
 - Bundled agent skills that teach assistants the right Hive workflow:
   discovery -> schema lookup -> bounded execution -> evidence receipt.
 - A broad provider catalog remains available behind discovery for agents that
-  need a long-tail endpoint. The current catalog contains 525 tools, but that
+  need a long-tail endpoint. The current catalog contains 523 tools, but that
   coverage is not the primary product contract.
 
 ## Quickstart
@@ -206,15 +207,38 @@ advertised as live until external approval and clean-profile verification. See
 
 ## Run Local stdio MCP
 
-Use local `stdio` when you want a self-hosted MCP process, local desktop config,
-or your own upstream provider keys.
+Use local `stdio` for clients that only launch local processes, such as Claude
+Desktop's `claude_desktop_config.json`. By default the stdio server is a thin
+proxy to the hosted MCP, so it serves the same production tools, data, and
+receipts. It authenticates with the key saved by `hive auth login` (or
+`HIVE_API_KEY` in the launching environment); without one it runs keyless
+(discovery plus the free hero calls).
+
+```json
+{
+  "mcpServers": {
+    "hive": {
+      "command": "npx",
+      "args": ["-y", "-p", "hive-intelligence@latest", "hive"]
+    }
+  }
+}
+```
+
+Running `hive` with no subcommand starts the `stdio` MCP server. Always launch
+it through `hive-intelligence@latest`: `npx hive-mcp` downloads an unrelated npm
+package (or runs a stale global install), and `npx hive-intelligence` without
+`@latest` can keep running an old version.
+
+To self-host with your own upstream provider keys instead, opt in with
+`hive serve --local` or `HIVE_STDIO_MODE=local`:
 
 ```json
 {
   "mcpServers": {
     "hive-local": {
       "command": "npx",
-      "args": ["-y", "-p", "hive-intelligence@latest", "hive"],
+      "args": ["-y", "-p", "hive-intelligence@latest", "hive", "serve", "--local"],
       "env": {
         "COINGECKO_PRO_API_KEY": "optional",
         "ALCHEMY_API_KEY": "optional",
@@ -226,9 +250,6 @@ or your own upstream provider keys.
 }
 ```
 
-Running `hive` with no subcommand starts the `stdio` MCP server. `hive-mcp`
-remains available as a backward-compatible binary alias.
-
 ## Staying Current
 
 The hosted MCP (`https://mcp.hiveintelligence.xyz/mcp`) is managed by Hive.
@@ -247,6 +268,16 @@ npx -y -p hive-intelligence@latest hive upgrade
 `hive doctor` and the MCP server instructions, so your agent can prompt you when
 an update is available. Set `HIVE_NO_UPDATE_CHECK=1` to disable the check.
 
+`hive doctor` also flags a stale global `hive-intelligence` install, client
+configs that launch `npx hive-mcp`, a bare global `hive` binary, a pinned or
+untagged `hive-intelligence`, or the retired `https://hiveintelligence.xyz/mcp`
+URL, and duplicate Hive entries. `hive doctor --fix` rewrites those entries to
+the canonical form after saving a `.hive-backup-<time>` copy of each file:
+
+```bash
+npx -y -p hive-intelligence@latest hive doctor --fix
+```
+
 ## Use The CLI
 
 Search the catalog:
@@ -470,6 +501,7 @@ tool lists:
 | Polymarket      | Prediction markets: market and event search, market-implied odds, order books, odds history, wallet positions | Free (keyless)                                                                                                        |
 | Alternative.me  | Crypto Fear and Greed Index, current plus daily history                            | Free (keyless)                                                                                                        |
 | Blockchain.com  | Daily Bitcoin on-chain charts: hash rate, active addresses, transaction count      | Free (keyless)                                                                                                        |
+| Blockscout      | EVM token holder counts by USD balance tier (`get_token_holder_distribution`)      | Free (keyless); optional `BLOCKSCOUT_API_KEY` for the PRO API                                                         |
 | Open Data Fetch | Allowlisted, size-capped access to long-tail public crypto APIs                    | Free                                                                                                                                            |
 
 Providers without configured keys remain discoverable and return classified

package/agent-skills/packs/hive/SKILL.md

@@ -16,9 +16,9 @@ through one MCP server and one CLI, and every answer carries a receipt:
 provider, fetch time, cache state, runtime status, and digests of the input
 and result. Three things Hive has that most crypto data tools do not:
 
-- **History that venues no longer serve.** Perp funding settlements, open
-  interest, basis, long/short ratios, and liquidations for one coin across up
-  to 33 CEX and DEX venues, archived since 2023-11.
+- **History that venues no longer serve.** Perp funding settlements for one
+  coin across up to 33 CEX and DEX venues since 2023-11, plus basis, open
+  interest and liquidations since 2025 and long/short ratios since 2026-03.
 - **Cross-venue views.** One call compares funding or basis across venues
   instead of one exchange at a time.
 - **Provenance you can cite.** The `_hive` block on every material response
@@ -237,13 +237,15 @@ and probability claims are yours and must be labeled as such.
 
 Discovery tools are free; every other tool costs one credit. Keyed lanes debit
 only after validation and client resolution, so a validation error or a
-missing provider key costs 0 and a call that reaches the provider costs 1 even
-when the provider fails. The keyless lane consumes one allowance call per
-material request, valid or not. `report_feedback` is free on every lane.
+missing provider key costs 0, and a call that fails after the debit is
+refunded, so only a call that succeeds costs 1. The keyless lane takes one
+allowance call per material request and gives it back when the call fails.
+`report_feedback` is free on every lane.
 
 Every material response says what it cost: `credit_cost` (0 or 1),
-`credits_used` (what was actually debited), and `credits_remaining` (an
-integer, `null` when unlimited, absent when the lane has no notion of it).
+`credits_used` (what the call cost, 0 when a failed call was refunded), and
+`credits_remaining` (an integer, `null` when unlimited, absent when the lane
+has no notion of it).
 Do not print the balance on every call; mention it when it is low or when the
 user asks.
 

package/agent-skills/packs/hive-mcp/SKILL.md

@@ -27,10 +27,11 @@ file path and shape vary per client.
   interactive path is live.
 - **Cost** — discovery tools are free; every other tool costs one credit.
   Keyed lanes debit only after validation and client resolution, so a
-  validation error or missing provider key costs 0 and a call that reaches the
-  provider costs 1 even when the provider fails. The keyless lane consumes one
-  allowance call per material request, valid or not. Every material response
-  reports `credit_cost`, `credits_used`, and `credits_remaining`.
+  validation error or missing provider key costs 0, and a call that fails
+  after the debit is refunded, so only a call that succeeds costs 1. The
+  keyless lane takes one allowance call per material request and gives it back
+  when the call fails. Every material response reports `credit_cost`,
+  `credits_used`, and `credits_remaining`.
 
 After hosted OAuth activation, interactive MCP setup does not require the user
 to create or paste an API key. Route to `hive-build-onboarding` for direct CLI,
@@ -122,17 +123,24 @@ enablement.
 
 ## Staying current
 
-The hosted MCP endpoint is managed by Hive. Local `stdio` installs should
-keep `hive-intelligence@latest` in the client config so each restart
-re-resolves the newest version. When the server
-instructions or `hive doctor` report that a newer version is available,
-tell the user to run `hive upgrade` (updates a global install and clears
-the npx cache) and then restart the MCP client to load it:
+The hosted MCP endpoint is managed by Hive. Local `stdio` proxies to it by
+default, and its config must launch `hive-intelligence@latest` so each restart
+re-resolves the newest version. Never write `npx hive-mcp`: that name on npm is
+an unrelated package, and on machines with an old global install it runs that
+stale copy instead. When the server instructions or `hive doctor` report that a
+newer version is available, tell the user to run `hive upgrade` (updates a
+global install and clears the npx cache) and then restart the MCP client:
 
 ```bash
 npx -y -p hive-intelligence@latest hive upgrade
 ```
 
+If Hive answers with an old `server_version`, every vendor reports
+`missing_key`, or tools look stale, run `hive doctor`. It flags stale global
+installs, configs that launch `hive-mcp` or the retired
+`https://hiveintelligence.xyz/mcp` URL, and duplicate Hive entries;
+`hive doctor --fix` rewrites them after backing each file up.
+
 ## Common failures
 
 - **"401 / Authentication failed" (interactive)** — remove the cached Hive

package/agent-skills/packs/hive-mcp/references/client-install-matrix.md

@@ -8,8 +8,9 @@ https://mcp.hiveintelligence.xyz/mcp
 
 After the hosted deployment exposes protected-resource metadata, interactive
 clients should store only this public URL and complete Hive OAuth in the
-browser. Use local `stdio` for Hive development, self-hosting, provider key
-experiments, or clients that cannot use remote Streamable HTTP. Use a Hive API
+browser. Use local `stdio` for clients that cannot use remote Streamable HTTP
+(it proxies to the hosted MCP by default), or `hive serve --local` for
+self-hosting and provider-key experiments. Use a Hive API
 key for headless backends and as the trusted-client fallback while OAuth is not
 active.
 
@@ -79,8 +80,9 @@ prompt, screenshot, or browser bundle.
 
 ## Local stdio MCP
 
-Local stdio does not require a hosted Hive key. Optional upstream provider keys
-belong in the local environment when the user wants provider-key experiments:
+Local stdio proxies to the hosted MCP with the key saved by `hive auth login`
+(keyless without one). For self-hosting with your own upstream provider keys,
+append `"serve", "--local"` to `args` and put those keys in `env`:
 
 ```json
 {

package/agent-skills/packs/hive-mcp/references/clients.md

@@ -137,7 +137,8 @@ keep the key in the launching process's secret store, never in a shared file.
 
 ## Local stdio fallback
 
-For local-only clients, self-hosting, or provider-key experiments:
+For clients that only launch local processes. The stdio server proxies to the
+hosted MCP and uses the key saved by `hive auth login` (keyless without one):
 
 ```json
 {
@@ -150,5 +151,7 @@ For local-only clients, self-hosting, or provider-key experiments:
 }
 ```
 
-Local stdio does not need `HIVE_API_KEY`; optional upstream provider keys can be
-supplied locally when needed.
+Do not put `HIVE_API_KEY` in this config; run `hive auth login` once instead.
+To self-host with your own upstream provider keys, add `"serve", "--local"` to
+`args` (or set `HIVE_STDIO_MODE=local`) and supply those keys in `env`. Never
+use `npx hive-mcp`: it installs an unrelated npm package.

package/agent-skills/packs/hive-token-diligence/SKILL.md

@@ -45,6 +45,8 @@ coverage, not an execution plan.
 5. Start with metadata and market/liquidity checks. Add holder distribution
    and enrichment only when the user needs depth, and security/risk checks
    when the user asks whether to trade, approve, or trust the token.
+   For "how many real holders" questions use `get_token_holder_distribution`
+   (holders by USD tier, dust separated); a raw holder count includes dust.
 6. For supply-dilution or unlock questions, use CoinGecko supply breakdown and
    circulating/total supply charts when the configured plan permits them.
    Report a plan gate instead of substituting market-cap fields.

package/build/{chunk-L4KVJDA7.js → chunk-5IQUEFCD.js}

@@ -96,7 +96,11 @@ async function runUpgrade() {
     return;
   }
   const updateAvailable = isNewerVersion(latest, SERVER_VERSION);
-  if (!updateAvailable) {
+  const { readGlobalInstalls, npmGlobalRoot } = await import("./config-audit-7GC42QX7.js");
+  const staleGlobal = mode !== "global" && readGlobalInstalls(npmGlobalRoot()).some(
+    (i) => i.name === REGISTRY_PACKAGE && isNewerVersion(latest, i.version)
+  );
+  if (!updateAvailable && !staleGlobal) {
     if (shouldOutputJson()) {
       await writeOutput(
         successEnvelope(
@@ -116,7 +120,7 @@ async function runUpgrade() {
 `);
     return;
   }
-  if (mode === "global") {
+  if (mode === "global" || staleGlobal) {
     const ok = updateGlobal();
     actions.push(ok ? "updated global install" : "global update failed");
   }
@@ -131,7 +135,8 @@ async function runUpgrade() {
         {
           current: SERVER_VERSION,
           latest,
-          updateAvailable: true,
+          updateAvailable,
+          staleGlobal,
           mode,
           actions
         },
@@ -140,10 +145,12 @@ async function runUpgrade() {
     );
     return;
   }
-  info(`
+  if (updateAvailable) {
+    info(`
 Update available: ${SERVER_VERSION} -> ${latest}
 `);
-  if (mode === "global") {
+  }
+  if (mode === "global" || staleGlobal) {
     info(
       actions.includes("updated global install") ? `Updated global hive-intelligence to ${latest}.
 ` : `Global update failed. Run: npm install -g ${REGISTRY_PACKAGE}@latest
@@ -154,7 +161,7 @@ Update available: ${SERVER_VERSION} -> ${latest}
     info(`Cleared npx cache so the next run pulls ${latest}.
 `);
   }
-  if (mode === "local") {
+  if (mode === "local" && updateAvailable) {
     info(
       "Running from a local checkout; pull the latest source with git instead.\n"
     );

package/build/{chunk-ORJIFYF4.js → chunk-E2FAHUXM.js}

@@ -7,7 +7,7 @@ import {
   getSupabaseAdmin,
   resolveEndpoint,
   secureLogger
-} from "./chunk-HWV3XFXH.js";
+} from "./chunk-Z42XNN47.js";
 
 // src/services/wallet-service.ts
 async function consumeCredits(args) {
@@ -34,6 +34,29 @@ async function consumeCredits(args) {
     cycleEnd: row.cycle_end ?? null
   };
 }
+async function refundCredits(args) {
+  const { userId, debitIdempotencyKey, detail } = args;
+  const { data, error } = await getSupabaseAdmin().rpc("refund_credits", {
+    p_user_id: userId,
+    p_debit_idempotency_key: debitIdempotencyKey,
+    p_detail: detail ?? {}
+  });
+  if (error) {
+    secureLogger.error("refund_credits RPC failed", error, { userId });
+    throw new Error(`refund_credits failed: ${error.message}`);
+  }
+  const row = Array.isArray(data) ? data[0] : data;
+  if (!row) {
+    throw new Error("refund_credits returned no row");
+  }
+  return {
+    code: row.code,
+    balance: row.balance ?? null
+  };
+}
+function refundSettled(code) {
+  return code === "ok" || code === "unlimited" || code === "already_refunded";
+}
 async function ensureWallet(userId, planId) {
   const { error } = await getSupabaseAdmin().rpc("ensure_wallet", {
     p_user_id: userId,
@@ -175,6 +198,8 @@ async function executeToolByName(toolName, args, options) {
 
 export {
   consumeCredits,
+  refundCredits,
+  refundSettled,
   ensureWallet,
   getWalletStatus,
   applyPlanChange,