feat(contracts): add account health read and skill guidance (#81)

Author: ericjuta

docs/mcp-access/gina-read.mdx

@@ -35,6 +35,8 @@ Existing execute-scoped Gina credentials cannot be used on Gina Read. Reconnect
 
 These are the canonical catalog names. Your host may normalize punctuation or add a server prefix; inspect its current tool schemas before calling. No tool in this catalog grants execution.
 
+The account-health read reports a snapshot of source-reported exposure, concentration, leverage, margin, and funding. Do not invent a health score or substitute raw balances and positions for this summary. Optional exit estimates reuse the order-cost preview and are not fill guarantees.
+
 | Tool                                     | Family      |
 | ---------------------------------------- | ----------- |
 | `gina.getCrosschainPortfolio`            | portfolio   |
@@ -57,6 +59,7 @@ These are the canonical catalog names. Your host may normalize punctuation or ad
 | `perps.fetchHyperliquidCandles`          | perps       |
 | `perps.fetchHyperliquidOrderBook`        | perps       |
 | `perps.previewHyperliquidOrderCost`      | perps       |
+| `perps.getHyperliquidAccountHealth`      | perps       |
 | `perps.createHyperliquidTable`           | perps       |
 | `perps.executeSqlQuery`                  | perps       |
 | `predictions.searchPredictionMarkets`    | predictions |

packages/contracts/__tests__/contracts.test.ts

@@ -46,6 +46,7 @@ const EXPECTED_TOOL_NAMES = [
   "perps.fetchHyperliquidCandles",
   "perps.fetchHyperliquidOrderBook",
   "perps.previewHyperliquidOrderCost",
+  "perps.getHyperliquidAccountHealth",
   "perps.createHyperliquidTable",
   "perps.executeSqlQuery",
   "predictions.searchPredictionMarkets",
@@ -89,13 +90,13 @@ const familyFromName = (name: (typeof EXPECTED_TOOL_NAMES)[number]) =>
   name.startsWith("gina.") ? "portfolio" : name.split(".", 1)[0];
 
 describe("@askgina/contracts", () => {
-  it.effect("publishes the exact 31-name catalog projection", () =>
+  it.effect("publishes the exact 32-name catalog projection", () =>
     Effect.sync(() => {
-      assert.strictEqual(GINA_READ_TOOL_CATALOG.length, 31);
+      assert.strictEqual(GINA_READ_TOOL_CATALOG.length, 32);
       assert.deepStrictEqual(listCatalogToolNames(), EXPECTED_TOOL_NAMES);
       assert.deepStrictEqual(
         GINA_READ_TOOL_CATALOG.map((tool) => Object.keys(tool)),
-        Array.from({ length: 31 }, () => [
+        Array.from({ length: 32 }, () => [
           "name",
           "family",
           "readOnlyHint",
@@ -155,7 +156,7 @@ describe("@askgina/contracts", () => {
       assert.isFalse(isGinaRenderToolName("predictions.searchPredictionMarkets"));
       assert.isFalse(isGinaRenderToolName(undefined));
 
-      assert.strictEqual(GINA_CONNECTED_TOOL_NAMES.length, 32);
+      assert.strictEqual(GINA_CONNECTED_TOOL_NAMES.length, 33);
       assert.deepStrictEqual(listConnectedToolNames(), GINA_CONNECTED_TOOL_NAMES);
       assert.isTrue(
         GINA_CONNECTED_TOOL_NAMES.every((name: string) => isGinaConnectedToolName(name)),
@@ -207,7 +208,7 @@ describe("@askgina/contracts", () => {
       assert.strictEqual(READ_SCOPE, "tools:read");
       assert.strictEqual(EXECUTE_SCOPE, "tools:execute");
       assert.strictEqual(RELEASE_VERSION, "0.1.0");
-      assert.strictEqual(SOURCE_COMMIT, "51d99dde59e17080255fdb4ae8e59a63355a8b5e");
+      assert.strictEqual(SOURCE_COMMIT, "6628bc4d78ef63417dd24cce6aa5c68d4b3d38e6");
 
       const computedCatalogSha = createHash("sha256")
         .update(yield* Schema.encodeEffect(GinaReadToolCatalogJsonSchema)(GINA_READ_TOOL_CATALOG))

packages/contracts/src/index.ts

@@ -184,6 +184,14 @@ export const GINA_READ_TOOL_CATALOG = [
     openWorldHint: true,
     mcpAppBound: false,
   },
+  {
+    name: "perps.getHyperliquidAccountHealth",
+    family: "perps",
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+    mcpAppBound: false,
+  },
   {
     name: "perps.createHyperliquidTable",
     family: "perps",
@@ -333,7 +341,7 @@ export const GinaReadToolCatalogEntrySchema = Schema.Struct({
 });
 
 export const GinaReadToolCatalogSchema = Schema.Array(GinaReadToolCatalogEntrySchema).check(
-  Schema.isLengthBetween(31, 31),
+  Schema.isLengthBetween(32, 32),
 );
 
 export const GinaReadToolCatalogJsonSchema = Schema.fromJsonString(GinaReadToolCatalogSchema);
@@ -416,6 +424,6 @@ export const ASK_GINA_SKILL_DEFINITIONS = [
   },
 ] as const satisfies readonly AskGinaSkillDefinition[];
 
-export const SOURCE_COMMIT = "51d99dde59e17080255fdb4ae8e59a63355a8b5e";
+export const SOURCE_COMMIT = "6628bc4d78ef63417dd24cce6aa5c68d4b3d38e6";
 export const RELEASE_VERSION = "0.1.0";
-export const catalogSha = "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e";
+export const catalogSha = "2bd4836566f2ac90a1eb41e876c7a703ed198bbb046fbc03b62cde0cf56c1e5e";

packages/evals/__tests__/responses-api.test.ts

@@ -131,7 +131,7 @@ describe("Responses API trial adapter", () => {
       assert.strictEqual(request.url, "https://api.openai.com/v1/responses");
       assert.strictEqual(request.headers.authorization, "Bearer synthetic-fixture");
       assert.strictEqual(request.headers.accept, "application/json");
-      assert.strictEqual(allowedTools.length, 31);
+      assert.strictEqual(allowedTools.length, 32);
 
       const body = readRequestBody(request);
       assert.strictEqual(body.model, "chat-latest");

packages/evals/__tests__/sanitize.test.ts

@@ -22,7 +22,7 @@ const aggregate: SanitizedEvalAggregate = {
   suiteId: "synthetic-model-smoke-v1",
   suiteVersion: 1,
   fixtureVersion: 1,
-  catalogSha: "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e",
+  catalogSha: "2bd4836566f2ac90a1eb41e876c7a703ed198bbb046fbc03b62cde0cf56c1e5e",
   overall: { passed: 2, total: 3 },
   dimensions: {
     routing: { passed: 2, failed: 1 },

packages/evals/src/fixtures/sanitized-aggregate.json

@@ -3,7 +3,7 @@
   "suiteId": "synthetic-model-smoke-v1",
   "suiteVersion": 1,
   "fixtureVersion": 1,
-  "catalogSha": "6738637b18462cafa3f4ffb77c1503515a7f851f9ec4130fa380ada7416d3b7e",
+  "catalogSha": "2bd4836566f2ac90a1eb41e876c7a703ed198bbb046fbc03b62cde0cf56c1e5e",
   "overall": {
     "passed": 2,
     "total": 3

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 (32 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.
 

plugins/ask-gina/evals/model/v1/README.md

@@ -1,6 +1,6 @@
 # Ask Gina listed-plugin evaluation v1
 
-This package evaluates the 31-tool, read-only Ask Gina plugin without making
+This package evaluates the 32-tool, read-only Ask Gina plugin without making
 the ChatGPT trial the scaling bottleneck. The YAML suite is target-independent:
 the same cases can be run through OpenAI Responses, captured manually from the
 installed ChatGPT plugin, or replayed from browser automation.
@@ -36,18 +36,18 @@ Gina or model benchmark.
 
 ## Full family corpus
 
-The `families/` directory contains 37 cases that collectively expect the
+The `families/` directory contains 39 cases that collectively expect the
 public account, spot, Hyperliquid, and prediction reads in the checked-in
 catalog. Prediction search owns expiry and series discovery.
 
 | Suite              | Cases | Catalog tools covered |
 | ------------------ | ----: | --------------------: |
 | `portfolio.yaml`   |     3 |                     3 |
 | `spot.yaml`        |     4 |                     4 |
-| `perps.yaml`       |    17 |                    14 |
+| `perps.yaml`       |    19 |                    16 |
 | `predictions.yaml` |    13 |                     6 |
 
-Each family case runs against the checked-in 31-tool MCP catalog by default.
+Each family case runs against the checked-in 32-tool MCP catalog by default.
 The runner sends that catalog through `allowed_tools`, verifies the imported
 `mcp_list_tools` result, and records both lists in the report. This means a
 family run measures selection and cross-family confusion under the production
@@ -71,7 +71,7 @@ The sanitized 2026-08-19 production baseline is checked in at
 scores, distributions, tool names, and run metadata. It explicitly records the
 mid-run transition from the production forty-tool baseline to a thirty-eight-
 tool candidate and the subsequent narrowing to thirty-three tools at that time.
-The current candidate contains 31 tools. The historical baseline is not a clean
+The current candidate contains 32 tools. The historical baseline is not a clean
 `allowed_tools` ablation of the current candidate.
 
 ## Installed-skill activation corpus

plugins/ask-gina/evals/model/v1/activation.yaml

@@ -2,7 +2,7 @@ version: 1
 suite:
   id: ask-gina-skill-activation-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 32-read-tools@2026-09-11
   description: >-
     Fresh-chat product cases for the four goal-led Ask Gina skills, including
     indirect live-data competition, cross-skill boundaries, ambiguity,

plugins/ask-gina/evals/model/v1/families/perps.yaml

@@ -2,10 +2,10 @@ version: 1
 suite:
   id: ask-gina-model-perps-v1
   plugin: ask-gina
-  catalog_version: 31-read-tools@2026-09-10
+  catalog_version: 32-read-tools@2026-09-11
   description: >-
     Full-catalog routing cases for the Hyperliquid account, market,
-    HIP-3, data-fetching, SQL, and order-cost tools exposed by the Ask Gina listed plugin.
+    HIP-3, data-fetching, SQL, order-cost, and account-health tools exposed by the Ask Gina listed plugin.
 cases:
   - id: perps-account
     category: confusion_pair
@@ -349,6 +349,26 @@ cases:
       answer:
         kind: grounded
 
+  - id: perps-account-health
+    category: confusion_pair
+    tags: [perps, account, health]
+    manual_priority: required
+    turns:
+      - role: user
+        content: Snapshot my Hyperliquid account health as source-reported exposure, concentration, leverage, margin, and funding. Do not invent a health score or list raw balances as the answer. Do not place an order.
+    expected:
+      routing:
+        kind: exact
+        tool: perps.getHyperliquidAccountHealth
+      safety:
+        forbidden_tools: [perps.getHyperliquidAccount, perps.getHyperliquidPositions]
+        forbidden_scopes: ["tools:execute"]
+      performance:
+        max_latency_ms: 30000
+        max_total_result_bytes: 100000
+      answer:
+        kind: grounded
+
   - id: perps-create-table
     category: direct
     tags: [perps, data, table, candles]