@indigoai-us/hq-cli 5.342.9 → 5.342.10

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+## [5.342.10] — 2026-10-04
+- Attach bounded status, gateway error-class, and integrations subcommand tags to captured gateway faults.
+
 ## [5.342.9] — 2026-10-04
 - Child wrappers now release their package-use lease after startup modules are preloaded, so long-running child processes do not block CLI updates.
 - Keep nested HQ child leases and materialize core-job post-exit helpers before releasing the parent package lease.

package/dist/commands/integrations-core.d.ts

@@ -150,6 +150,8 @@ export declare class IntegrationsCliError extends Error {
      * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
      */
     readonly rpcCode?: number;
+    /** Fixed vocabulary for the integrations subcommand that called the gateway. */
+    readonly gatewaySubcommand?: "tools_list" | "tools_call" | "other";
     /**
      * HQ's own OAuth callback URL, carried on the errors that say a provider
      * refused to register HQ automatically. The provider must register the exact
@@ -164,6 +166,7 @@ export declare class IntegrationsCliError extends Error {
         status?: number;
         oauthProtected?: boolean;
         rpcCode?: number;
+        gatewaySubcommand?: "tools_list" | "tools_call" | "other";
         redirectUri?: string;
     });
 }

package/dist/commands/integrations-core.js

@@ -55,6 +55,8 @@ export class IntegrationsCliError extends Error {
      * fingerprint as anything but the finite allowlist in sentry-fingerprint.ts.
      */
     rpcCode;
+    /** Fixed vocabulary for the integrations subcommand that called the gateway. */
+    gatewaySubcommand;
     /**
      * HQ's own OAuth callback URL, carried on the errors that say a provider
      * refused to register HQ automatically. The provider must register the exact
@@ -75,6 +77,8 @@ export class IntegrationsCliError extends Error {
             this.oauthProtected = opts.oauthProtected;
         if (opts.rpcCode !== undefined)
             this.rpcCode = opts.rpcCode;
+        if (opts.gatewaySubcommand !== undefined)
+            this.gatewaySubcommand = opts.gatewaySubcommand;
         if (opts.redirectUri !== undefined) {
             Object.defineProperty(this, "redirectUri", {
                 value: opts.redirectUri,
@@ -175,6 +179,18 @@ const EXPECTED_GATEWAY_ERROR_CODES = new Set([-32003, -32602, -32050]);
 function isExpectedGatewayError(code) {
     return code != null && EXPECTED_GATEWAY_ERROR_CODES.has(code);
 }
+function expectedGatewayErrorFallback(code) {
+    switch (code) {
+        case -32003:
+            return "You do not have access to this integration. Ask its owner to share it with you.";
+        case -32602:
+            return "The integration rejected this request. Check the tool name and arguments.";
+        case -32050:
+            return "The connected provider could not complete this request. Wait a moment and try again.";
+        default:
+            return undefined;
+    }
+}
 // A 401 from ANY integration-gateway vault call means the caller's HQ session
 // is expired or missing — an expected auth state fixed by `hq login`, not an
 // hq-cli defect. Raise the same typed AuthError the vault company-resolution
@@ -399,7 +415,18 @@ export async function resolveConnection(token, companyUid, app, opts, recoveryOp
     }
     return selectConnection(connections, opts);
 }
+function gatewaySubcommandFor(params) {
+    const name = params.name;
+    if (typeof name !== "string")
+        return "other";
+    if (name.endsWith(".mcp.tools.list"))
+        return "tools_list";
+    if (name.endsWith(".mcp.tools.call"))
+        return "tools_call";
+    return "other";
+}
 export async function callGateway(token, params, idempotencyKey) {
+    const gatewaySubcommand = gatewaySubcommandFor(params);
     const deadline = Date.now() + ASYNC_GATEWAY_DEADLINE_MS;
     const res = await vaultApiFetch({
         token,
@@ -414,6 +441,7 @@ export async function callGateway(token, params, idempotencyKey) {
     });
     const message = (await res.json().catch(() => null));
     let terminalMessage = message;
+    let terminalStatus = res.status;
     if (res.status === 202) {
         const accepted = message;
         const jobId = accepted && typeof accepted.jobId === "string" ? accepted.jobId : "";
@@ -427,7 +455,9 @@ export async function callGateway(token, params, idempotencyKey) {
         if (!idempotencyKey) {
             throw new IntegrationsCliError(`Integration gateway accepted async job ${jobId} without an idempotency key.`, { expected: false, status: 202 });
         }
-        terminalMessage = await pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline);
+        const terminal = await pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline);
+        terminalMessage = terminal.message;
+        terminalStatus = terminal.status;
     }
     if (res.status !== 202 && (!res.ok || !terminalMessage)) {
         raiseIfUnauthorized(res);
@@ -437,7 +467,7 @@ export async function callGateway(token, params, idempotencyKey) {
         // reaches the Sentry fingerprint's HTTP bucket instead of colliding under
         // default grouping. Same reasoning as raiseForResponse, which already sets
         // `status`. This does not change the `expected` decision above.
-        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status });
+        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status, gatewaySubcommand });
     }
     if (terminalMessage?.error) {
         // The gateway's error text is minted UPSTREAM (hq-pro, the integration
@@ -449,8 +479,11 @@ export async function callGateway(token, params, idempotencyKey) {
         // no-op. This preserves PR #298's user-visible diagnostic; it only makes
         // it safe on the newly-expected path.
         throw new IntegrationsCliError(redactErrorText(terminalMessage.error.message ?? "") ||
+            expectedGatewayErrorFallback(terminalMessage.error.code) ||
             "Integration gateway returned an error.", {
             expected: isExpectedGatewayError(terminalMessage.error.code),
+            status: terminalStatus,
+            gatewaySubcommand,
             // Carry the protocol code to the capture site as a bounded grouping
             // discriminator (HQ-CLI collision, Sentry 7642756130). This does not
             // alter the `expected` decision above; it only labels the error.
@@ -518,7 +551,7 @@ async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, dea
             if (!hasJsonRpcOutcome) {
                 throw new IntegrationsCliError(`Integration job ${jobId} returned an invalid JSON-RPC response.`, { expected: false });
             }
-            return response;
+            return { message: response, status: res.status };
         }
         if (poll.status !== "pending") {
             throw new IntegrationsCliError(`Integration job ${jobId} returned unknown status '${String(poll.status)}'.`, { expected: true });

package/dist/main.js

@@ -335,6 +335,39 @@ function qmdSpawnFailureCaptureContext(err) {
         return undefined;
     return { contexts: { qmd_spawn_failure: diagnostics } };
 }
+const GATEWAY_RPC_CODE_TAGS = new Map([
+    [-32603, "internal_error"],
+    [-32009, "conflict"],
+    [-32003, "unauthorized"],
+    [-32602, "invalid_params"],
+    [-32050, "provider_error"],
+]);
+function integrationsGatewayCaptureContext(err) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    const record = err;
+    const subcommand = record.gatewaySubcommand;
+    if (subcommand === undefined)
+        return undefined;
+    const subcommandTag = subcommand === "tools_list" || subcommand === "tools_call"
+        ? subcommand
+        : "other";
+    const status = record.status;
+    const statusTag = typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599
+        ? String(status)
+        : status === undefined ? "unknown" : "other";
+    const rpcCode = record.rpcCode;
+    const codeTag = typeof rpcCode === "number" && Number.isInteger(rpcCode)
+        ? GATEWAY_RPC_CODE_TAGS.get(rpcCode) ?? "other"
+        : rpcCode === undefined ? "missing" : "other";
+    return {
+        tags: {
+            integration_gateway_status: statusTag,
+            integration_gateway_code: codeTag,
+            integration_subcommand: subcommandTag,
+        },
+    };
+}
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
     // A typed plan gate, or an hq-cloud vault error carrying a plan-limit
@@ -853,9 +886,11 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
             const qmdContext = qmdExitCaptureContext(err);
-            if (spawnContext || installContext || qmdContext) {
+            const gatewayContext = integrationsGatewayCaptureContext(err);
+            if (spawnContext || installContext || qmdContext || gatewayContext) {
                 deps.sentry.captureException(err, {
                     ...qmdContext,
+                    ...(gatewayContext ? { tags: gatewayContext.tags } : {}),
                     ...((spawnContext || installContext)
                         ? { contexts: { ...spawnContext?.contexts, ...installContext } }
                         : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.342.9",
+  "version": "5.342.10",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {