@pgnio/helios-mcp 0.2.7 → 0.2.9

package/dist/cli.js

@@ -139,19 +139,21 @@ var protectiveOrderKindSchema = import_zod.z.enum(["STOP_LOSS", "TAKE_PROFIT"]);
 var protectiveOrderSideSchema = import_zod.z.enum(["BUY", "SELL"]);
 var protectiveOrderPositionSideSchema = import_zod.z.enum(["BOTH", "LONG", "SHORT"]);
 var protectiveOrderSchema = import_zod.z.object({
+  /** Helios's record id: what helios_positions_delete_tp_sl takes (the Hyperliquid order id works there too). */
   id: import_zod.z.string(),
-  binanceOrderId: import_zod.z.number().int().nonnegative().optional(),
-  clientOrderId: import_zod.z.string().optional(),
+  /** The Hyperliquid order id (named after the retired Binance field). */
+  binanceOrderId: import_zod.z.number().int().nonnegative().nullish(),
+  clientOrderId: import_zod.z.string().nullish(),
   symbol: import_zod.z.string(),
   side: protectiveOrderSideSchema,
-  positionSide: protectiveOrderPositionSideSchema,
+  positionSide: protectiveOrderPositionSideSchema.nullish().transform((value) => value ?? "BOTH"),
   status: import_zod.z.string(),
   kind: protectiveOrderKindSchema,
-  groupId: import_zod.z.string(),
-  stopPrice: import_zod.z.string().optional(),
-  parentClientOrderId: import_zod.z.string().optional(),
-  assetId: import_zod.z.number().int().nonnegative().optional(),
-  createdAt: import_zod.z.string().datetime()
+  groupId: import_zod.z.string().nullish(),
+  stopPrice: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).nullish().transform((value) => value == null ? value : String(value)),
+  parentClientOrderId: import_zod.z.string().nullish(),
+  assetId: import_zod.z.number().int().nonnegative().nullish(),
+  createdAt: import_zod.z.string().nullish()
 });
 var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   provider: import_zod.z.literal("hyperliquid"),
@@ -160,6 +162,7 @@ var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   totalMargin: import_zod.z.number(),
   unrealizedPnl: import_zod.z.number(),
   positions: import_zod.z.array(openPositionSchema),
+  /** Unreadable entries are dropped (see readProtectiveOrders) rather than failing the read. */
   protectiveOrders: import_zod.z.array(protectiveOrderSchema)
 });
 var portfolioInputSchema = import_zod.z.object({
@@ -354,6 +357,8 @@ var closePositionInputSchema = import_zod.z.object({
 });
 var closePositionResultSchema = import_zod.z.object({
   status: import_zod.z.literal("submitted"),
+  /** `no_position`: nothing was open on this coin, so no order was sent. Absent from older data-bridges. */
+  outcome: import_zod.z.enum(["closed", "no_position"]).optional(),
   provider: providerSchema.optional(),
   symbol: import_zod.z.string(),
   mode: import_zod.z.literal("FULL"),
@@ -544,7 +549,8 @@ var HeliosAgentDataBridgeClient = class {
     }
     return portfolioSnapshotSchema.parse({
       ...result,
-      provider: parsedInput.provider
+      provider: parsedInput.provider,
+      protectiveOrders: readProtectiveOrders(result.protectiveOrders)
     });
   }
   async getLedgerFills(accessToken, input = {}) {
@@ -597,7 +603,7 @@ var HeliosAgentDataBridgeClient = class {
   }
   async closePosition(accessToken, input) {
     const parsedInput = closePositionInputSchema.parse(input);
-    await this.request(
+    const payload = await this.request(
       accessToken,
       "positions.close",
       {
@@ -608,8 +614,10 @@ var HeliosAgentDataBridgeClient = class {
       },
       "POST"
     );
+    const outcome = this.tryUnwrapResult(payload)?.outcome;
     return closePositionResultSchema.parse({
       status: "submitted",
+      ...outcome === "closed" || outcome === "no_position" ? { outcome } : {},
       provider: parsedInput.provider,
       symbol: parsedInput.symbol,
       mode: "FULL",
@@ -707,6 +715,14 @@ var HeliosAgentDataBridgeClient = class {
       });
     }
   }
+  /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+  tryUnwrapResult(payload) {
+    try {
+      return this.unwrapResult(payload) ?? null;
+    } catch {
+      return null;
+    }
+  }
   unwrapResult(payload) {
     if (!payload || typeof payload !== "object") {
       throw new HeliosAgentApiError({
@@ -767,6 +783,13 @@ var HeliosAgentDataBridgeClient = class {
     return envelope;
   }
 };
+function readProtectiveOrders(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const parsed = protectiveOrderSchema.safeParse(entry);
+    return parsed.success ? [parsed.data] : [];
+  });
+}
 var DEFAULT_AGENT_REFRESH_WINDOW_MS = 60 * 1e3;
 var agentConnectionStatusSchema = import_zod3.z.enum([
   "disconnected",
@@ -1220,6 +1243,9 @@ var HeliosAgentMcpDocsService = class {
   }
   async getDocument(input) {
     const documentPath = resolveDocumentPath(this.docsRoot, input.path);
+    if (!(0, import_node_fs.existsSync)(documentPath) || !(0, import_node_fs.statSync)(documentPath).isFile()) {
+      throw new Error(`No document "${input.path}". helios_docs_get_index lists the documents.`);
+    }
     const body = (0, import_node_fs.readFileSync)(documentPath, "utf8");
     const stats = (0, import_node_fs.statSync)(documentPath);
     const relativePath = toPosixPath(import_node_path.default.relative(this.docsRoot, documentPath));
@@ -2522,7 +2548,7 @@ function createHeliosAccountToolDefinitions(service) {
     {
       name: "helios_portfolio_get",
       title: "Get Helios Portfolio",
-      description: "Returns a provider-specific portfolio snapshot. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Returns balances, open positions and their TP/SL (protectiveOrders, each with the id helios_positions_delete_tp_sl takes). Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: providerSelectionInputSchema,
       async execute(input) {
         const result = portfolioToolOutputSchema.parse(await service.getPortfolio(input));
@@ -2618,7 +2644,7 @@ function createHeliosMarketToolDefinitions(service) {
     {
       name: "helios_market_get_snapshot",
       title: "Get Helios Market Snapshot",
-      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns.",
+      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns. What each column means: helios_docs_get_document with path ai-agent-indicators/00_columns.txt (read it once).",
       inputSchema: marketSnapshotInputSchema,
       async execute(input) {
         const result = marketSnapshotToolOutputSchema.parse(await service.getSnapshot(input));
@@ -2759,7 +2785,7 @@ function createHeliosTradingToolDefinitions(service) {
           content: [
             {
               type: "text",
-              text: result.status === "connected" ? `Submitted Helios full close for ${result.closure.provider ?? input.provider} ${result.closure.symbol}.` : result.message
+              text: result.status !== "connected" ? result.message : result.closure.outcome === "no_position" ? `No open ${result.closure.symbol} position: nothing was closed and no order was sent.` : `Sent a market order closing the full ${result.closure.provider ?? input.provider ?? "hyperliquid"} ${result.closure.symbol} position. Check helios_positions_get_open to confirm.`
             }
           ],
           structuredContent: result.status === "connected" ? result : {
@@ -2793,7 +2819,7 @@ function createHeliosTradingToolDefinitions(service) {
     {
       name: "helios_positions_delete_tp_sl",
       title: "Delete Helios TP/SL",
-      description: "Deletes an existing Helios take-profit or stop-loss order by order id. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Deletes a take-profit or stop-loss. orderId is the id from helios_portfolio_get protectiveOrders, or the Hyperliquid order id of the TP/SL. Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: deleteTpSlInputSchema,
       async execute(input) {
         const result = deleteTpSlToolOutputSchema.parse(await service.deleteTpSl(input));
@@ -2886,7 +2912,7 @@ async function createHeliosAgentMcpServer(options) {
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const server = new McpServer({
     name: "helios",
-    version: "0.2.7"
+    version: "0.2.9"
   });
   const sessionStore = options.sessionStore ?? new FileAgentSessionStore(options.sessionPath ?? getDefaultHeliosAgentMcpSessionPath());
   const client = new HeliosAgentAuthClient({

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createHeliosAgentMcpServer
-} from "./chunk-V453JYRN.mjs";
+} from "./chunk-7TMDGB6C.mjs";
 
 // src/cli.ts
 async function main() {

package/dist/index.d.mts

@@ -94,28 +94,28 @@ declare const portfolioSnapshotSchema: z.ZodObject<{
     }, z.core.$strip>>;
     protectiveOrders: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        binanceOrderId: z.ZodOptional<z.ZodNumber>;
-        clientOrderId: z.ZodOptional<z.ZodString>;
+        binanceOrderId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        clientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";
             SELL: "SELL";
         }>;
-        positionSide: z.ZodEnum<{
+        positionSide: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             LONG: "LONG";
             SHORT: "SHORT";
             BOTH: "BOTH";
-        }>;
+        }>>>, z.ZodTransform<"LONG" | "SHORT" | "BOTH", "LONG" | "SHORT" | "BOTH" | null | undefined>>;
         status: z.ZodString;
         kind: z.ZodEnum<{
             STOP_LOSS: "STOP_LOSS";
             TAKE_PROFIT: "TAKE_PROFIT";
         }>;
-        groupId: z.ZodString;
-        stopPrice: z.ZodOptional<z.ZodString>;
-        parentClientOrderId: z.ZodOptional<z.ZodString>;
-        assetId: z.ZodOptional<z.ZodNumber>;
-        createdAt: z.ZodString;
+        groupId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        stopPrice: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | null | undefined, string | number | null | undefined>>;
+        parentClientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        assetId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const ledgerFillsInputSchema: z.ZodObject<{
@@ -440,6 +440,10 @@ declare const closePositionInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const closePositionResultSchema: z.ZodObject<{
     status: z.ZodLiteral<"submitted">;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        closed: "closed";
+        no_position: "no_position";
+    }>>;
     provider: z.ZodOptional<z.ZodEnum<{
         hyperliquid: "hyperliquid";
     }>>;
@@ -606,6 +610,8 @@ declare class HeliosAgentDataBridgeClient {
     private request;
     private buildProcedureUrl;
     private parseJson;
+    /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+    private tryUnwrapResult;
     private unwrapResult;
     private extractErrorCode;
     private extractErrorMessage;

package/dist/index.d.ts

@@ -94,28 +94,28 @@ declare const portfolioSnapshotSchema: z.ZodObject<{
     }, z.core.$strip>>;
     protectiveOrders: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        binanceOrderId: z.ZodOptional<z.ZodNumber>;
-        clientOrderId: z.ZodOptional<z.ZodString>;
+        binanceOrderId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        clientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";
             SELL: "SELL";
         }>;
-        positionSide: z.ZodEnum<{
+        positionSide: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             LONG: "LONG";
             SHORT: "SHORT";
             BOTH: "BOTH";
-        }>;
+        }>>>, z.ZodTransform<"LONG" | "SHORT" | "BOTH", "LONG" | "SHORT" | "BOTH" | null | undefined>>;
         status: z.ZodString;
         kind: z.ZodEnum<{
             STOP_LOSS: "STOP_LOSS";
             TAKE_PROFIT: "TAKE_PROFIT";
         }>;
-        groupId: z.ZodString;
-        stopPrice: z.ZodOptional<z.ZodString>;
-        parentClientOrderId: z.ZodOptional<z.ZodString>;
-        assetId: z.ZodOptional<z.ZodNumber>;
-        createdAt: z.ZodString;
+        groupId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        stopPrice: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | null | undefined, string | number | null | undefined>>;
+        parentClientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        assetId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const ledgerFillsInputSchema: z.ZodObject<{
@@ -440,6 +440,10 @@ declare const closePositionInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const closePositionResultSchema: z.ZodObject<{
     status: z.ZodLiteral<"submitted">;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        closed: "closed";
+        no_position: "no_position";
+    }>>;
     provider: z.ZodOptional<z.ZodEnum<{
         hyperliquid: "hyperliquid";
     }>>;
@@ -606,6 +610,8 @@ declare class HeliosAgentDataBridgeClient {
     private request;
     private buildProcedureUrl;
     private parseJson;
+    /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+    private tryUnwrapResult;
     private unwrapResult;
     private extractErrorCode;
     private extractErrorMessage;

package/dist/index.js

@@ -179,19 +179,21 @@ var protectiveOrderKindSchema = import_zod.z.enum(["STOP_LOSS", "TAKE_PROFIT"]);
 var protectiveOrderSideSchema = import_zod.z.enum(["BUY", "SELL"]);
 var protectiveOrderPositionSideSchema = import_zod.z.enum(["BOTH", "LONG", "SHORT"]);
 var protectiveOrderSchema = import_zod.z.object({
+  /** Helios's record id: what helios_positions_delete_tp_sl takes (the Hyperliquid order id works there too). */
   id: import_zod.z.string(),
-  binanceOrderId: import_zod.z.number().int().nonnegative().optional(),
-  clientOrderId: import_zod.z.string().optional(),
+  /** The Hyperliquid order id (named after the retired Binance field). */
+  binanceOrderId: import_zod.z.number().int().nonnegative().nullish(),
+  clientOrderId: import_zod.z.string().nullish(),
   symbol: import_zod.z.string(),
   side: protectiveOrderSideSchema,
-  positionSide: protectiveOrderPositionSideSchema,
+  positionSide: protectiveOrderPositionSideSchema.nullish().transform((value) => value ?? "BOTH"),
   status: import_zod.z.string(),
   kind: protectiveOrderKindSchema,
-  groupId: import_zod.z.string(),
-  stopPrice: import_zod.z.string().optional(),
-  parentClientOrderId: import_zod.z.string().optional(),
-  assetId: import_zod.z.number().int().nonnegative().optional(),
-  createdAt: import_zod.z.string().datetime()
+  groupId: import_zod.z.string().nullish(),
+  stopPrice: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).nullish().transform((value) => value == null ? value : String(value)),
+  parentClientOrderId: import_zod.z.string().nullish(),
+  assetId: import_zod.z.number().int().nonnegative().nullish(),
+  createdAt: import_zod.z.string().nullish()
 });
 var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   provider: import_zod.z.literal("hyperliquid"),
@@ -200,6 +202,7 @@ var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   totalMargin: import_zod.z.number(),
   unrealizedPnl: import_zod.z.number(),
   positions: import_zod.z.array(openPositionSchema),
+  /** Unreadable entries are dropped (see readProtectiveOrders) rather than failing the read. */
   protectiveOrders: import_zod.z.array(protectiveOrderSchema)
 });
 var portfolioInputSchema = import_zod.z.object({
@@ -394,6 +397,8 @@ var closePositionInputSchema = import_zod.z.object({
 });
 var closePositionResultSchema = import_zod.z.object({
   status: import_zod.z.literal("submitted"),
+  /** `no_position`: nothing was open on this coin, so no order was sent. Absent from older data-bridges. */
+  outcome: import_zod.z.enum(["closed", "no_position"]).optional(),
   provider: providerSchema.optional(),
   symbol: import_zod.z.string(),
   mode: import_zod.z.literal("FULL"),
@@ -584,7 +589,8 @@ var HeliosAgentDataBridgeClient = class {
     }
     return portfolioSnapshotSchema.parse({
       ...result,
-      provider: parsedInput.provider
+      provider: parsedInput.provider,
+      protectiveOrders: readProtectiveOrders(result.protectiveOrders)
     });
   }
   async getLedgerFills(accessToken, input = {}) {
@@ -637,7 +643,7 @@ var HeliosAgentDataBridgeClient = class {
   }
   async closePosition(accessToken, input) {
     const parsedInput = closePositionInputSchema.parse(input);
-    await this.request(
+    const payload = await this.request(
       accessToken,
       "positions.close",
       {
@@ -648,8 +654,10 @@ var HeliosAgentDataBridgeClient = class {
       },
       "POST"
     );
+    const outcome = this.tryUnwrapResult(payload)?.outcome;
     return closePositionResultSchema.parse({
       status: "submitted",
+      ...outcome === "closed" || outcome === "no_position" ? { outcome } : {},
       provider: parsedInput.provider,
       symbol: parsedInput.symbol,
       mode: "FULL",
@@ -747,6 +755,14 @@ var HeliosAgentDataBridgeClient = class {
       });
     }
   }
+  /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+  tryUnwrapResult(payload) {
+    try {
+      return this.unwrapResult(payload) ?? null;
+    } catch {
+      return null;
+    }
+  }
   unwrapResult(payload) {
     if (!payload || typeof payload !== "object") {
       throw new HeliosAgentApiError({
@@ -807,6 +823,13 @@ var HeliosAgentDataBridgeClient = class {
     return envelope;
   }
 };
+function readProtectiveOrders(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const parsed = protectiveOrderSchema.safeParse(entry);
+    return parsed.success ? [parsed.data] : [];
+  });
+}
 var DEFAULT_AGENT_REFRESH_WINDOW_MS = 60 * 1e3;
 var agentConnectionStatusSchema = import_zod3.z.enum([
   "disconnected",
@@ -1260,6 +1283,9 @@ var HeliosAgentMcpDocsService = class {
   }
   async getDocument(input) {
     const documentPath = resolveDocumentPath(this.docsRoot, input.path);
+    if (!(0, import_node_fs.existsSync)(documentPath) || !(0, import_node_fs.statSync)(documentPath).isFile()) {
+      throw new Error(`No document "${input.path}". helios_docs_get_index lists the documents.`);
+    }
     const body = (0, import_node_fs.readFileSync)(documentPath, "utf8");
     const stats = (0, import_node_fs.statSync)(documentPath);
     const relativePath = toPosixPath(import_node_path.default.relative(this.docsRoot, documentPath));
@@ -2596,7 +2622,7 @@ function createHeliosAccountToolDefinitions(service) {
     {
       name: "helios_portfolio_get",
       title: "Get Helios Portfolio",
-      description: "Returns a provider-specific portfolio snapshot. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Returns balances, open positions and their TP/SL (protectiveOrders, each with the id helios_positions_delete_tp_sl takes). Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: providerSelectionInputSchema,
       async execute(input) {
         const result = portfolioToolOutputSchema.parse(await service.getPortfolio(input));
@@ -2692,7 +2718,7 @@ function createHeliosMarketToolDefinitions(service) {
     {
       name: "helios_market_get_snapshot",
       title: "Get Helios Market Snapshot",
-      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns.",
+      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns. What each column means: helios_docs_get_document with path ai-agent-indicators/00_columns.txt (read it once).",
       inputSchema: marketSnapshotInputSchema,
       async execute(input) {
         const result = marketSnapshotToolOutputSchema.parse(await service.getSnapshot(input));
@@ -2833,7 +2859,7 @@ function createHeliosTradingToolDefinitions(service) {
           content: [
             {
               type: "text",
-              text: result.status === "connected" ? `Submitted Helios full close for ${result.closure.provider ?? input.provider} ${result.closure.symbol}.` : result.message
+              text: result.status !== "connected" ? result.message : result.closure.outcome === "no_position" ? `No open ${result.closure.symbol} position: nothing was closed and no order was sent.` : `Sent a market order closing the full ${result.closure.provider ?? input.provider ?? "hyperliquid"} ${result.closure.symbol} position. Check helios_positions_get_open to confirm.`
             }
           ],
           structuredContent: result.status === "connected" ? result : {
@@ -2867,7 +2893,7 @@ function createHeliosTradingToolDefinitions(service) {
     {
       name: "helios_positions_delete_tp_sl",
       title: "Delete Helios TP/SL",
-      description: "Deletes an existing Helios take-profit or stop-loss order by order id. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Deletes a take-profit or stop-loss. orderId is the id from helios_portfolio_get protectiveOrders, or the Hyperliquid order id of the TP/SL. Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: deleteTpSlInputSchema,
       async execute(input) {
         const result = deleteTpSlToolOutputSchema.parse(await service.deleteTpSl(input));
@@ -2960,7 +2986,7 @@ async function createHeliosAgentMcpServer(options) {
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const server = new McpServer({
     name: "helios",
-    version: "0.2.7"
+    version: "0.2.9"
   });
   const sessionStore = options.sessionStore ?? new FileAgentSessionStore(options.sessionPath ?? getDefaultHeliosAgentMcpSessionPath());
   const client = new HeliosAgentAuthClient({

package/dist/index.mjs

@@ -29,7 +29,7 @@ import {
   topOfSnapshot,
   withDataText,
   withSnapshotDefaults
-} from "./chunk-V453JYRN.mjs";
+} from "./chunk-7TMDGB6C.mjs";
 export {
   DEFAULT_SNAPSHOT_FIELDS,
   DEFAULT_SNAPSHOT_TOP,

package/docs/ai-agent-indicators/00_columns.txt

@@ -0,0 +1,76 @@
+HELIOS SNAPSHOT COLUMNS: HOW TO READ THEM
+Short guide to the column ids in helios_market_get_snapshot, _chunk and symbol detail `row`.
+All % values are already percent (2.5 = 2.5%). null = unavailable, never zero.
+Longer guides for single indicators are in this folder (see 00_index.txt).
+
+PRICE AND SIZE
+rank   market cap rank (1 = largest). null = unranked.
+lp     last price.
+qv     24h quote volume in USD. Low qv = thin market, wider fills.
+bv     24h base volume (coins).
+
+RETURNS (% change over the window)
+r1m r3m r5m r15m r30m r1h r2h r4h r6h r8h r12h r24h r3d r7d
+
+DISTANCE FROM RECENT RANGE
+fh24 fh7   % from the 24h / 7d high. Always <= 0. -10 = 10% below the high.
+fl24 fl7   % from the 24h / 7d low. Always >= 0. 2 = 2% above the low.
+           Near 0 on fl = sitting on the low; near 0 on fh = at the high.
+
+REGIME AND MOMENTUM
+reg    regime label from 12 timeframe changes:
+       up:      CASCADE UP, PARABOLIC, BREAKOUT, TREND UP, GRIND UP, SPIKE UP
+       down:    CASCADE DOWN, CRASH, BREAKDOWN, TREND DN, BLEED, SPIKE DN
+       turning: REVERSAL (down->up), ROLLOVER (up->down), EXHAUST UP, EXHAUST DN
+       no trend: CHOP, CONSOL, RANGING (momentum signals are weak here)
+       Known quirk: a steady fall can read CRASH even when not accelerating.
+hmi    Helios momentum index, -100..100. Cross-timeframe momentum, 1h-4h weigh most.
+       > 40 strong up, 15..40 up, -15..15 no direction, < -40 strong down.
+hmiv   hmi velocity (rate of change of hmi). > 0 momentum improving, < 0 fading.
+       Meaningless when hmi is between -15 and 15.
+tri    trend strength label: STRONG TREND, MODERATE TREND, WEAK TREND, RANGING/CHOPPY.
+       No direction: use hmi or reg for which way.
+trv    trend strength 0..100 (> 60 STRONG, > 40 MODERATE, > 20 WEAK).
+de     directional efficiency -1..1. +1 every timeframe moving up cleanly,
+       -1 every timeframe moving down cleanly, near 0 choppy.
+
+STRETCH
+ob     overbought, 0..100 (weighted RSI across timeframes). >= 70 stretched up,
+       <= 30 stretched down.
+obosp  probability ob is high versus its own last 60 readings, 0..1.
+       > 0.9 extreme for this coin right now, < 0.1 extreme low.
+       In a strong trend ob can be 95 while obosp is low; read both.
+vwz    VWAP z-score vs the 7d VWAP. > +2 far above, -0.5..0.5 at VWAP, < -2 far below.
+
+STRUCTURE
+ms     market structure: RANGING, CONSOL (compressed), BREAKING↑ / BREAKING↓,
+       CONFIRMED-BREAK↑ / ↓, TEST-S (testing support), TEST-R (testing resistance),
+       FAILED-BREAK (breakout that reversed).
+srs    nearest support price. srr nearest resistance price (null = none found).
+
+SCORE
+hs     Helios score, a mean-reversion setup score. Positive = long setup
+       (needs ob <= 30 and de <= -0.4), negative = short setup (ob >= 60, de >= 0.4),
+       0 = no setup. Size: 5+ notable, 7+ strong, 9+ rare. Short scores have not
+       held up in backtests; long scores in a falling market have.
+
+OTHER COLUMNS (only with fields)
+hfi    Helios flow index (funding, OI, CVD), -100..100. Its OI part saturates; treat as rough.
+ar az  activity ratio and z-score (volume now vs baseline; ar < 0.5 = dead).
+vwap poc pocd vap   VWAP price, volume point of control, % from it, value-area position.
+macdh macds macdd   MACD histogram, signal label, divergence.
+vcc vcp             volatility clustering and change-point probability.
+obosd               overbought/oversold divergence. trh trend Hurst (> 0.5 trending).
+
+MARKET BLOCK (every response)
+os     how many of 23 large coins are down more than 7% in 24h (0..23). High = broad selloff.
+mti    micro trend: 5m + 1h moves of BTC, ETH, BNB, SOL, scaled. > 0 majors rising now.
+Mti    macro trend: weighted 5m/1h/6h/24h momentum of six majors, in %. > 0 market up.
+
+WHAT HAS HELD UP IN BACKTESTS (out of sample, last 2 years)
+- Buying a sharp turn up (hmiv > 0, r15m and r1h turning positive) in a coin whose
+  reg is BREAKDOWN or CRASH, especially when the whole market is down (os high, Mti < 0).
+- Fading stretched moves beat chasing them.
+- Shorts did not hold up. Edges are small: about +0.1% a trade after a 0.38% round-trip cost,
+  on holds of 1-3 days. Frequent in-and-out trading pays fees without that edge.
+  Size small, always use a stop.

package/docs/ai-agent-indicators/00_index.txt

@@ -1,8 +1,9 @@
 ================================================================================
 HELIOS INDICATOR INDEX — AI AGENT REFERENCE
 ================================================================================
-# One entry per indicator. Format: file | data_field | type | range | purpose
-# All fields accessed via: indicators.<data_field>
+# START WITH 00_columns.txt: a short guide to every snapshot column id (hmi, reg, ob, hs...).
+# The entries below are longer guides, one per indicator. Format: file | data_field | type | range | purpose
+# data_field names here are the long names; snapshot columns use the short ids in 00_columns.txt.
 
 --------------------------------------------------------------------------------
 MOMENTUM / DIRECTION
@@ -22,10 +23,6 @@ regime.txt
   19-state market regime classifier (e.g. CASCADE_UP, CHOP, REVERSAL).
   PRIMARY GATE: invalidates all momentum indicators when CHOP/CONSOL/RANGING.
 
-tf_alignment.txt
-  indicators.tf_alignment | NUMERIC | 0..100
-  % of short-TF (1m-2h) movement aligned with macro (4h-24h) direction.
-  Breadth complement to HMI magnitude.
 
 directional_efficiency.txt
   indicators.directional_efficiency | NUMERIC | -1..1
@@ -135,21 +132,10 @@ hfi_weights.txt
   Any weight < 0.10 = that data source is degraded.
 
 --------------------------------------------------------------------------------
-VOLATILITY / SQUEEZE
+VOLATILITY
 --------------------------------------------------------------------------------
-volatility_squeeze.txt
-  indicators.volatility_squeeze | NUMERIC | [0, ∞); typical [0.1, 1.5]
-  Short/long GARCH(1,1) ratio. LOWER = MORE compressed (< 0.8 = in squeeze).
-  Counterintuitive scale: value 0.2 = maximum squeeze, NOT minimum.
 
-squeeze_duration.txt
-  indicators.squeeze_duration | INTEGER | [0, ∞)
-  Count of consecutive ticks with volatility_squeeze < 0.8. Resets to 0 on break.
 
-squeeze_energy.txt
-  indicators.squeeze_energy | NUMERIC | [0, ∞)
-  Integrated compression: squeeze_duration × (0.8 - volatility_squeeze).
-  Summary measure of pent-up energy. Zero = no active squeeze.
 
 volatility_clustering.txt
   indicators.volatility_clustering | NUMERIC | [0.7, 1.5]  ← NOT [0, 1]
@@ -200,7 +186,6 @@ DEPENDENCY MAP — KEY RELATIONSHIPS
   macd_signal           →  macd_histogram (state without magnitude is incomplete)
   macd_divergence       →  macd_signal (divergence leads; cross confirms)
   hfi                   →  hfi_weights (composite without component split is opaque)
-  squeeze_energy        →  volatility_squeeze + squeeze_duration (derived from both)
   vwap_zscore           →  vwap + volatility_clustering (both required for interpretation)
   poc_distance          →  poc (normalized deviation requires knowing the level)
   value_area_position   →  regime (same state is opposite signal in different regimes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgnio/helios-mcp",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Helios MCP server: connect an AI agent to your Helios account to read markets and your portfolio and to trade on Hyperliquid. Most apps can use the hosted URL https://helios.pgn.io/mcp instead.",
   "license": "UNLICENSED",
   "homepage": "https://helios.pgn.io/?connect=ai",