@senpi/runtime 3.0.64 → 3.0.66

package/dist/senpi/client.js

@@ -28,12 +28,212 @@ const logger = createLogger("[senpi][client]");
 export class SenpiClientError extends Error {
     code;
     details;
-    constructor(code, message, details) {
-        super(message);
+    /**
+     * The venue may have acted despite the failure — set when the envelope reports
+     * an ambiguous upstream code (the server's own execution-timeout abort) on a
+     * mutating call. Callers must reconcile rather than re-send.
+     */
+    mayHaveExecuted;
+    /** Envelope `error.code`, kept so telemetry and callers can key on it. */
+    upstreamCode;
+    constructor(code, message, details, opts) {
+        super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
         this.name = "SenpiClientError";
         this.code = code;
         this.details = details;
+        this.mayHaveExecuted = opts?.mayHaveExecuted ?? false;
+        this.upstreamCode = opts?.upstreamCode;
+    }
+}
+/** JSON-RPC code the MCP SDK uses for a client-side request timeout. */
+export const MCP_REQUEST_TIMEOUT_CODE = -32001;
+/**
+ * Server-side ALO wait window when the recipe doesn't override it
+ * (`FeeOptimizedLimitOptions.executionTimeoutSeconds`, see types.ts).
+ */
+const SERVER_DEFAULT_ALO_SECONDS = 45;
+/**
+ * Slack added on top of the ALO budget: the venue round-trip and the taker
+ * crossing that `ensure_execution_as_taker` performs *after* the maker window
+ * closes both land outside the budget the recipe asked for.
+ */
+const ALO_TIMEOUT_HEADROOM_MS = 30_000;
+/**
+ * Floor for a **mutating** MCP request. Sized just above the trading-engine
+ * dependency's own ~70s ceiling (453k calls/7d: p50 90ms, p95 19.8s, max 70.0s) —
+ * a client that gives up earlier abandons work that then succeeds, and for a
+ * mutation that ambiguity is the expensive kind.
+ *
+ * Deliberately not larger: signal processing is strictly serial (one consumer, see
+ * CLAUDE.md), so a hung call blocks every queued signal behind it for the whole
+ * timeout. 90s clears the measured ceiling with ~20s of margin while keeping that
+ * worst-case stall as short as the evidence allows.
+ */
+const MCP_MUTATION_TIMEOUT_FLOOR_MS = 90_000;
+/**
+ * Timeout for a **read**. Much shorter than a mutation's, because the two fail
+ * asymmetrically: a timed-out read is idempotent and simply retried, while a
+ * timed-out mutation may have executed. Waiting longer on a read buys almost
+ * nothing and costs real time in the two places that block on one.
+ *
+ * The DSL monitor is strictly serial (`dsl/plugin/index.ts` schedules the next
+ * tick only after the previous finishes) and wraps its reads in `withRetry(2)`,
+ * so the per-tick worst case is 3× this value with no trailing-floor update on
+ * live positions. Positions keep their exchange-side stop throughout — what a
+ * blind tick loses is the ratchet, not the protection.
+ *
+ * 45s is >6× the measured p99.9 (`market_get_prices` 7.08s over 4.14M calls,
+ * `execution_get_order_status` 2.60s over 2.84M), giving a 135s worst-case blind
+ * window against 180s before this change and 270s under a single shared floor.
+ *
+ * Only reads landing between 45s and the old 60s cutoff fail where they would
+ * previously have returned; they are retried, since reads are retriable. The
+ * whole 30–60s band is 127 calls/week out of ~7M, so the affected slice is a
+ * fraction of 0.002%. Chosen over a tighter 30s (90s worst case) deliberately:
+ * the extra 45s of blind window is cheap next to failing reads that were about
+ * to succeed, and the telemetry has no 30–45s sub-band to distinguish them.
+ */
+const MCP_READ_TIMEOUT_MS = 45_000;
+/** MCP request timeout for a call carrying an ALO execution budget. */
+export function mcpTimeoutForAlo(opts) {
+    const budgetSeconds = opts?.executionTimeoutSeconds ?? SERVER_DEFAULT_ALO_SECONDS;
+    return Math.max(budgetSeconds * 1000 + ALO_TIMEOUT_HEADROOM_MS, MCP_MUTATION_TIMEOUT_FLOOR_MS);
+}
+/**
+ * A `tools/call` the client stopped waiting for. **Not a failed order.**
+ *
+ * The server returns 200 on this work — an ALO order is *designed* to occupy the
+ * connection for its full `execution_timeout_seconds`, so a timeout means we
+ * stopped listening, not that nothing happened. Retrying a timed-out mutation
+ * can double it (a second close against a closing position opens the reverse).
+ *
+ * `mayHaveExecuted` marks that ambiguity so callers reconcile instead of
+ * retrying, and so the agent narrates a timeout rather than inventing an auth
+ * fault from a bare `exception`.
+ */
+export class SenpiTimeoutError extends Error {
+    /**
+     * Numeric so `jsonRpcErrorCode` still resolves it: the span attribute
+     * `rpc.response.status_code` and the `mcp.call_failed` event stay keyed on
+     * `-32001`, which is what existing saved queries and alerts match on — and what
+     * this class exists to make visible.
+     */
+    code = MCP_REQUEST_TIMEOUT_CODE;
+    toolName;
+    timeoutMs;
+    /** Mutations may have landed server-side; reads cannot have side effects. */
+    mayHaveExecuted;
+    /** Safe to re-issue verbatim. False for mutations — reconcile instead. */
+    retriable;
+    constructor(toolName, timeoutMs, mayHaveExecuted, cause) {
+        super(mayHaveExecuted
+            ? `${toolName} timed out after ${Math.round(timeoutMs / 1000)}s waiting for the Senpi MCP server. ` +
+                `This is a client-side timeout, NOT a rejected order and NOT an authentication problem — the server ` +
+                `may have executed it. Do not retry: read the current position and order state, and act on what is ` +
+                `actually there.`
+            : `${toolName} timed out after ${Math.round(timeoutMs / 1000)}s waiting for the Senpi MCP server. ` +
+                `This is a client-side timeout, NOT an authentication problem. The call has no side effects and is ` +
+                `safe to retry.`, 
+        // Keep the SDK error's stack — the classification replaces the message, not
+        // the evidence of where it came from.
+        cause !== undefined ? { cause } : undefined);
+        this.name = "SenpiTimeoutError";
+        this.toolName = toolName;
+        this.timeoutMs = timeoutMs;
+        this.mayHaveExecuted = mayHaveExecuted;
+        this.retriable = !mayHaveExecuted;
+    }
+}
+/**
+ * Tools with no side effects. Everything else is treated as mutating.
+ *
+ * Deliberately an allowlist of reads rather than a denylist of writes: an
+ * unrecognised tool is then assumed to move money, which costs at most a retry
+ * we could have taken. The inverse fails open — a mutation added later would
+ * default to retriable, and a re-sent withdraw or close is not recoverable.
+ */
+const READ_ONLY_TOOLS = new Set([
+    "audit_query",
+    "discovery_get_trader_history",
+    "discovery_get_trader_state",
+    "execution_get_order_status",
+    "market_get_prices",
+    "market_list_instruments",
+    "ratchet_stop_events",
+    "ratchet_stop_list",
+    "strategy_get_asset_trading_limits",
+    "strategy_get_clearinghouse_state",
+    "strategy_get_open_orders",
+    "strategy_get_pnl_and_account_value_history",
+    "strategy_list",
+    // Reached via asToolClient(), which passes arbitrary tool names through — the
+    // scanner data providers call these two. Without them a market-data read would
+    // be narrated as "the server may have executed it".
+    "market_get_asset_data",
+    "leaderboard_get_markets",
+]);
+/** True for a `tools/call` that can change venue or account state if it lands. */
+function isMutatingTool(toolName) {
+    return !READ_ONLY_TOOLS.has(toolName);
+}
+/** A timeout thrown by the MCP SDK, whatever its surface shape. */
+function isMcpTimeout(err) {
+    if (err instanceof SenpiTimeoutError)
+        return true;
+    if (err && typeof err === "object" && "code" in err) {
+        const code = err.code;
+        if (code === MCP_REQUEST_TIMEOUT_CODE)
+            return true;
     }
+    return err instanceof Error && /request timed out/i.test(err.message);
+}
+/**
+ * Envelope `error.code` values that leave the outcome unknown.
+ *
+ * The MCP server aborts its own trading-engine call at
+ * `SENPI_TRADING_EXECUTION_TIMEOUT_MS` (70s by default) and reports it as
+ * `UNAVAILABLE` via `isNetworkError`. That abort says nothing about whether the
+ * venue accepted the order — so for a mutation it carries the same ambiguity a
+ * client-side timeout does. `INTERNAL` is the unclassified bucket and is treated
+ * the same way.
+ *
+ * Everything else the server emits — INVALID_ARGUMENT, UNAUTHENTICATED,
+ * PERMISSION_DENIED, NOT_FOUND, RESOURCE_EXHAUSTED — is a rejection *before*
+ * execution, so those stay retriable.
+ */
+const AMBIGUOUS_UPSTREAM_CODES = new Set(["UNAVAILABLE", "INTERNAL"]);
+/** Envelope `error.code`, wherever the failure surfaced. */
+function envelopeErrorCode(error) {
+    if (!isRecord(error))
+        return undefined;
+    return asString(error.code) ?? undefined;
+}
+/**
+ * True when a `success:false` envelope leaves it unknown whether the venue acted.
+ * Only meaningful for a mutating tool: a read that fails changed nothing either way.
+ */
+function envelopeOutcomeUnknown(error) {
+    const code = envelopeErrorCode(error);
+    return code !== undefined && AMBIGUOUS_UPSTREAM_CODES.has(code);
+}
+/**
+ * Whether a thrown MCP failure is safe to re-issue verbatim.
+ *
+ * Two distinct paths reach here for the same underlying event — a slow order:
+ * the client giving up (`SenpiTimeoutError`) and the *server* giving up at its
+ * own 70s cap and returning `UNAVAILABLE`. Raising the client timeout above the
+ * server's makes the second the common one, so guarding only the first would
+ * move the duplicate-submission hazard rather than remove it.
+ *
+ * Exported so DSL and action call sites pass it to `withRetry`'s `shouldRetry`
+ * rather than each re-deriving the rule.
+ */
+export function isRetriableMcpError(err) {
+    if (err instanceof SenpiTimeoutError)
+        return err.retriable;
+    if (err instanceof SenpiClientError)
+        return !err.mayHaveExecuted;
+    return true;
 }
 /**
  * Best-effort engine error message extraction. Mirrors the resolver used
@@ -196,12 +396,21 @@ function assertClosePositionSucceeded(raw, ctx) {
     }
     const hasData = "data" in raw;
     if (raw.success === false && (!hasData || raw.data == null)) {
-        throw new Error(`close_position failed (${ctx.wallet} ${ctx.coin}): ${formatSenpiCloseFailureError(raw.error) || "unknown error"}`);
+        // An UNAVAILABLE here is the server's own 70s execution-timeout abort, which
+        // says nothing about whether the venue filled. Carry that forward so the DSL
+        // reconciles instead of submitting a second close.
+        throw new SenpiClientError("UPSTREAM_ERROR", `close_position failed (${ctx.wallet} ${ctx.coin}): ${formatSenpiCloseFailureError(raw.error) || "unknown error"}`, raw.error, {
+            mayHaveExecuted: envelopeOutcomeUnknown(raw.error),
+            upstreamCode: envelopeErrorCode(raw.error),
+        });
     }
     const payload = unwrapEnvelope(raw) ?? raw;
     if (isRecord(payload) && payload.success === false) {
         const detail = formatSenpiCloseFailureError(payload.error);
-        throw new Error(`close_position rejected (${ctx.wallet} ${ctx.coin}): ${detail || "success=false"}`);
+        throw new SenpiClientError("ENGINE_FAILURE", `close_position rejected (${ctx.wallet} ${ctx.coin}): ${detail || "success=false"}`, payload.error, {
+            mayHaveExecuted: envelopeOutcomeUnknown(payload.error),
+            upstreamCode: envelopeErrorCode(payload.error),
+        });
     }
 }
 /**
@@ -436,9 +645,32 @@ export class SenpiClient {
         if (!this.mcpClient) {
             throw new Error('SenpiClient not connected — connect() did not establish a client');
         }
-        const result = opts?.signal
-            ? await this.mcpClient.callTool({ name: toolName, arguments: args }, undefined, { signal: opts.signal })
-            : await this.mcpClient.callTool({ name: toolName, arguments: args });
+        // A timeout is always passed. Leaving RequestOptions off falls back to the SDK's
+        // DEFAULT_REQUEST_TIMEOUT_MSEC (60s), which is below both the ALO budgets recipes
+        // request and the trading engine's own ~70s ceiling — so the client abandons work
+        // the server then completes.
+        //
+        // Reads and mutations get different defaults on purpose: they fail asymmetrically,
+        // so patience is worth buying for one and not the other. See the two constants.
+        const timeoutMs = opts?.timeoutMs ??
+            (isMutatingTool(toolName) ? MCP_MUTATION_TIMEOUT_FLOOR_MS : MCP_READ_TIMEOUT_MS);
+        const requestOptions = {
+            timeout: timeoutMs,
+            ...(opts?.signal ? { signal: opts.signal } : {}),
+        };
+        let result;
+        try {
+            result = await this.mcpClient.callTool({ name: toolName, arguments: args }, undefined, requestOptions);
+        }
+        catch (err) {
+            // A deliberate cancellation (shutdown drain) stays an AbortError — only a real
+            // timeout is reclassified, so callers can tell "we stopped waiting" apart from
+            // "it was rejected" and reconcile rather than retry.
+            if (opts?.signal?.aborted !== true && isMcpTimeout(err)) {
+                throw new SenpiTimeoutError(toolName, timeoutMs, isMutatingTool(toolName), err);
+            }
+            throw err;
+        }
         if (result.content && Array.isArray(result.content) && result.content.length > 0) {
             const part = result.content[0];
             if (part && 'text' in part && typeof part.text === 'string') {
@@ -561,11 +793,16 @@ export class SenpiClient {
     }
     async createPosition(request) {
         logger.debug('createPosition request', { request });
+        // Orders are worked one at a time server-side, so the longest single ALO budget
+        // bounds the call — not their sum.
+        const aloTimeoutMs = Math.max(...request.orders.map((o) => o.orderType === 'FEE_OPTIMIZED_LIMIT'
+            ? mcpTimeoutForAlo(o.feeOptimizedLimitOptions)
+            : MCP_MUTATION_TIMEOUT_FLOOR_MS), MCP_MUTATION_TIMEOUT_FLOOR_MS);
         const raw = await this.callTool('create_position', {
             strategyWalletAddress: request.strategyWalletAddress,
             orders: request.orders,
             ...(request.reason != null ? { reason: request.reason } : {}),
-        });
+        }, { timeoutMs: aloTimeoutMs });
         logger.debug('createPosition raw response', { raw });
         return parseCreatePositionResult(raw);
     }
@@ -821,7 +1058,7 @@ export class SenpiClient {
             ...(params.feeOptimizedLimitOptions ? { feeOptimizedLimitOptions: params.feeOptimizedLimitOptions } : {}),
             ...(params.closeLimitMinutes !== undefined ? { closeLimitMinutes: params.closeLimitMinutes } : {}),
             ...(params.closePeakRoe !== undefined ? { closePeakRoe: params.closePeakRoe } : {}),
-        });
+        }, { timeoutMs: mcpTimeoutForAlo(params.feeOptimizedLimitOptions) });
         assertClosePositionSucceeded(raw, { wallet, coin: effectiveCoin });
         return unwrapEnvelope(raw) ?? raw;
     }
@@ -975,7 +1212,7 @@ export class SenpiClient {
         const data = unwrapEnvelope(raw);
         if (!isRecord(data))
             return { success: false };
-        return { success: data.success === true, message: asString(data.message) ?? undefined };
+        return { success: data.success === true, ...readFailureFields(data) };
     }
     /**
      * Raw portfolio from account_get_portfolio. Interpretation (the funding
@@ -1002,22 +1239,39 @@ export class SenpiClient {
         const data = unwrapEnvelope(raw);
         if (!isRecord(data))
             return { success: false };
-        const strategyId = asString(data.strategyId) ?? asString(data.id) ?? asString(data.strategy_id) ?? undefined;
-        return { success: data.success === true, strategyId, message: asString(data.message) ?? undefined };
+        // The MCP nests the created record: `data.strategy.{id,strategyWalletAddress,status,…}` beside
+        // an async-start `data.message` — there is no top-level id (senpi-hyperliquid-mcp
+        // `execution.tools.ts`, `createResponse(tool, 'create', { strategy, message })`). Reading only
+        // the flat keys returned `strategyId: undefined` for a create that had already made AND FUNDED
+        // a wallet, which the deploy then reported as a failure.
+        //
+        // The nested record WINS over a flat id when both appear. It is the object the backend
+        // actually created — the same one `strategy_list` returns, carrying the wallet and status the
+        // rest of the deploy binds to — so its id is guaranteed to belong to the wallet that just took
+        // the money. A flat id sitting beside it could only be a second, unattached identifier, and on
+        // a money call the expensive mistake is attaching a funded wallet to the wrong id. Flat shapes
+        // stay accepted for the reason the Python lifecycle reader keeps them (senpi-skills
+        // `_cli.py` `strategy_obj`: list entries "may be flat or wrapped").
+        // Read UNCONDITIONALLY, not only on `success: true`: a create that made and funded a wallet
+        // and then reported it oddly must still hand back the id — losing it is the defect 6f2cd917
+        // fixed, and it costs a funded wallet. A refusal envelope carries no id at any of these keys
+        // (`{ success, error, meta }`), so there is nothing there to mint one out of.
+        const strategyId = readStrategyId(isRecord(data.strategy) ? data.strategy : undefined) ?? readStrategyId(data);
+        return { success: data.success === true, strategyId, ...readFailureFields(data) };
     }
     async withdrawFunds(wallet, amount) {
         const raw = await this.callTool("strategy_withdraw_funds", { strategy_wallet: wallet, amount });
         const data = unwrapEnvelope(raw);
         if (!isRecord(data))
             return { success: false };
-        return { success: data.success === true, message: asString(data.message) ?? undefined };
+        return { success: data.success === true, ...readFailureFields(data) };
     }
     async closeStrategy(wallet, opts) {
         const raw = await this.callTool("strategy_close", { strategy_wallet: wallet }, opts);
         const data = unwrapEnvelope(raw);
         if (!isRecord(data))
             return { success: false };
-        return { success: data.success === true, message: asString(data.message) ?? undefined };
+        return { success: data.success === true, ...readFailureFields(data) };
     }
     /**
      * Submit a batch close_positions MCP call.
@@ -1228,6 +1482,56 @@ function extractSlOrderId(unwrapped, raw) {
     }
     return null;
 }
+/**
+ * The `errorCode`/`message` pair for the strategy lifecycle calls that report failure by RETURNING
+ * rather than throwing (`topUp`, `createCustomStrategy`, `withdrawFunds`, `closeStrategy`).
+ *
+ * A backend refusal reaches these methods as `{ success: false, error: { code, message, … }, meta }`
+ * — `createErrorResponse` in senpi-hyperliquid-mcp `src/services/response.service.ts`, returned by
+ * `server.ts` as an ordinary tool result with no `isError`, so nothing throws. That shape has **no
+ * `data` key**, and `unwrapEnvelope` returns any payload without one untouched: `data` therefore IS
+ * the envelope, and the old flat `asString(data.message)` read was looking one level above the
+ * text. Every backend refusal arrived as `message: undefined`, and deploy reported "backend
+ * returned no strategyId" over a refusal that had said exactly why it refused.
+ *
+ * `data.message` stays as the fallback because that is where a SUCCESS envelope puts its text (the
+ * create's async-start message arrives that way), and a string-shaped `error` is read only after it
+ * — `unwrapEnvelope` hoists such an `error` onto the inner record, and other parsers in this client
+ * accept that legacy shape (`parseCreatePositionResult`, `parseClosePositionResult`), though these
+ * four methods never did: at `cfecb432` they read `data.message` and nothing else.
+ *
+ * That last point is why the order is `error.message` → `data.message` → string `error`, and not
+ * the other way round — deliberately UNLIKE `extractEngineMessage` and `parseCreatePositionResult`,
+ * which rank a string `error` above `data.message`. Those read engine mutation results, where
+ * `error` is the failure channel and `message` is often the generic line beside it. These four read
+ * a lifecycle envelope whose `message` is the real text on the success path, and they read nothing
+ * else at `cfecb432`. A payload carrying BOTH a top-level string `error` and a `data.message` is a
+ * shape no MCP response produces (`createResponse` never emits a top-level `error`), so no evidence
+ * decides the tie: what decides it is that ranking the legacy string first would silently change
+ * which text these four answer with — on a SUCCESS envelope — as a side effect of a change about
+ * refusals. The legacy arm keeps its value where it is the ONLY text (`{ success: false,
+ * error: "…" }`, no `data` key and no error object) and takes nothing away where it is not.
+ *
+ * The code is returned as its own field and never concatenated into the message: `deploy`'s
+ * unnamed-create retry branches on it, and a guard that re-derives a code by scanning prose is the
+ * guard this repo already had.
+ */
+function readFailureFields(data) {
+    const err = isRecord(data.error) ? data.error : undefined;
+    return {
+        errorCode: (err && asString(err.code)) ?? undefined,
+        message: (err && asString(err.message)) ?? asString(data.message) ?? asString(data.error) ?? undefined,
+    };
+}
+/**
+ * The strategy id out of a strategy-shaped record, trying the key spellings the strategy surface
+ * uses in the order the Python lifecycle reader tries them (`_cli.py` `strategy_id_of`).
+ */
+function readStrategyId(obj) {
+    if (obj == null)
+        return undefined;
+    return asString(obj.strategyId) ?? asString(obj.id) ?? asString(obj.strategy_id) ?? undefined;
+}
 function parseCreatePositionResult(raw) {
     const data = unwrapEnvelope(raw);
     if (!isRecord(data)) {