Merge pull request #86 from askgina/fix/perps-only-plugin-contract

docs(perps): align health and radar access

Author: ericjuta

docs/perps-mcp/features.mdx

@@ -12,7 +12,9 @@ Start with `host-tools --brief` and `host-tools schema <toolName>` before using
 | Feature               | What It Does                                                | Example Prompts                                             | Direct Command                                                                                                    |
 | --------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | **Account State**     | View account, margin, positions, open orders, and portfolio | `"show my perps positions"` `"what open orders do I have?"` | `host-tools getHyperliquidPositions`                                                                              |
+| **Account Health**    | Snapshot authenticated account exposure and margin          | `"check my perps account health"`                           | `host-tools perps.accountHealth includeExitEstimates=true`                                                        |
 | **Markets**           | List canonical Hyperliquid markets and asset metadata       | `"show Hyperliquid markets"` `"what is BTC funding?"`       | `host-tools getHyperliquidMarkets`                                                                                |
+| **Market Radar**      | Rank markets by activity and compare retained samples       | `"radar for active perp markets"`                           | `host-tools perps.marketRadar limit=10`                                                                           |
 | **Prices**            | Fetch one or many live perps prices                         | `"BTC perps price"` `"price BTC ETH SOL"`                   | `host-tools getHyperliquidPrice '{\"asset\":\"BTC\"}'`                                                            |
 | **HIP-3 Discovery**   | Search HIP-3 markets and list builder-deployed DEXes        | `"search HIP-3 markets for CL"` `"list HIP-3 DEXes"`        | `host-tools perps.hip3.search query=CL`                                                                           |
 | **HIP-3 Prices**      | Read venue-scoped HIP-3 prices                              | `"price CL on xyz"`                                         | `host-tools perps.hip3.price '{\"dex\":\"xyz\",\"coin\":\"CL\"}'`                                                 |
@@ -25,6 +27,28 @@ Start with `host-tools --brief` and `host-tools schema <toolName>` before using
 | **Data Fetching**     | Fetch trades, candles, and order books into sandbox tables  | `"fetch BTC candles into SQL"`                              | `host-tools fetchHyperliquidCandles '{\"coin\":\"BTC\",\"interval\":\"1h\"}'`                                     |
 | **SQL Analysis**      | Query fetched perps data with DuckDB/SQLite-style workflows | `"query large BTC trades"`                                  | `sql query "SELECT * FROM <table> LIMIT 10"`                                                                      |
 
+<Note>
+  Account health and market radar require a separately authorized [Perps MCP
+  connection](/perps-mcp/client-setup) with `tools:execute`. They are not read tools in the Ask Gina
+  listed plugin.
+</Note>
+
+## Account health
+
+`perps.accountHealth` requires an authenticated account. It defaults to canonical Hyperliquid. Pass `providerContext` with `{"providerId":"hip3:xyz"}` for an enabled HIP-3 venue.
+
+The response includes at most 64 positions. Set `includeExitEstimates=true` for indicative exit estimates on at most eight positions, not fill guarantees. The tool does not assign a health score or calculate historical performance.
+
+## Market radar
+
+`perps.marketRadar` accepts `limit` from 1 to 50, defaulting to 10, and an optional `dex`, such as `dex=xyz`. Omit `dex` for canonical Hyperliquid.
+
+Eligible markets rank by descending 24-hour traded volume, then open interest, then absolute 24-hour price change, with coin name breaking ties. This measures activity and exposure, not liquidity, depth, or executable size. Excluded-market details are capped at 100.
+
+Rank, volume, open-interest, and mark-price deltas compare with a shared sample for that venue, not the caller's previous request. Samples rotate no more often than every five minutes and expire after seven days. Rows without a prior entry are marked `firstSeen`.
+
+Radar returns the complete JSON response inline or in an artifact. It does not automatically extract the rows into SQL tables.
+
 ## Discovery Flow
 
 Use this sequence when you are unsure which tool to call:

packages/contracts/__tests__/contracts.test.ts

@@ -11,8 +11,6 @@ import {
   GinaReadToolCatalogJsonSchema,
   PRODUCTION_MCP_URL,
   READ_SCOPE,
-  RELEASE_VERSION,
-  SOURCE_COMMIT,
   catalogSha,
   getGinaReadToolAnnotations,
   getGinaReadToolFamily,
@@ -201,13 +199,11 @@ describe("@askgina/contracts", () => {
     }),
   );
 
-  it.effect("pins endpoints, scopes, and source compatibility", () =>
+  it.effect("publishes endpoints and scopes with a computed catalog digest", () =>
     Effect.gen(function* () {
       assert.strictEqual(PRODUCTION_MCP_URL, "https://askgina.ai/ai/gina/mcp");
       assert.strictEqual(READ_SCOPE, "tools:read");
       assert.strictEqual(EXECUTE_SCOPE, "tools:execute");
-      assert.strictEqual(RELEASE_VERSION, "0.1.0");
-      assert.strictEqual(SOURCE_COMMIT, "51d99dde59e17080255fdb4ae8e59a63355a8b5e");
 
       const computedCatalogSha = createHash("sha256")
         .update(yield* Schema.encodeEffect(GinaReadToolCatalogJsonSchema)(GINA_READ_TOOL_CATALOG))

packages/contracts/src/index.ts

@@ -416,6 +416,6 @@ export const ASK_GINA_SKILL_DEFINITIONS = [
   },
 ] as const satisfies readonly AskGinaSkillDefinition[];
 
-export const SOURCE_COMMIT = "51d99dde59e17080255fdb4ae8e59a63355a8b5e";
+export const SOURCE_COMMIT = "ea8c56a0b065ea44cde89d05567999f976c61071";
 export const RELEASE_VERSION = "0.1.0";
 export const catalogSha = "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e";

plugins/ask-gina/README.md

@@ -61,7 +61,7 @@ Scope: `tools:read` only. This plugin does not include transaction execution or
 
 1. Install **Ask Gina** from the Cursor / Grok Bot plugin marketplace, or load this folder as a local Cursor plugin (`~/.cursor/plugins/local/ask-gina` as a real directory, not an external symlink).
 2. Open the Gina connector and choose **Connect**. Complete Ask Gina OAuth in the browser.
-3. Confirm the connector shows the read tools (30 catalog tools). Skills below should appear as well. In Cursor, the four slash commands and the always-on read-only rule should appear too.
+3. Confirm the connector shows the read tools (31 catalog tools). Skills below should appear as well. In Cursor, the four slash commands and the always-on read-only rule should appear too.
 
 Grok Bot loads plugins only from the Cursor marketplace. A local `~/.cursor/plugins/local` install proves the Cursor IDE loader, not Grok Bot.