@aipermission/mcp 0.2.43 → 0.2.44

package/README.md

@@ -85,6 +85,20 @@ does this automatically.
 
 ## Tools
 
+`AIPERMISSION_HTTP_TIMEOUT_MS` sets the gateway request deadline (default:
+60000 milliseconds). It covers both response headers and the complete response
+body, including streamed bodies. A timeout does not prove that a submitted
+operation failed; do not retry mutations with a new idempotency key blindly.
+If a POST response is lost or incomplete, the bridge returns
+`status: outcome_unknown` and `code: gateway_transport_outcome_unknown`.
+Action calls also return the original `idempotency_key`; no request ID is
+invented. Reconcile using that same key and unchanged input, not a new logical
+operation. Known gateway errors retain their original status and request ID.
+Local input-validation failures do not imply that execution occurred.
+Malformed or incomplete JSON responses are not treated as success. Invalid
+local headers are rejected before dispatch without echoing the API token;
+transport errors never echo raw response fragments or header values.
+
 - `list_connector_targets`
 - `get_connector_help`
 - `get_connector_actions`

package/dist/results.js

@@ -16,6 +16,8 @@ export function errorResult(error) {
   const status = error instanceof Error && typeof error.resultStatus === "string" ? error.resultStatus : "error";
   const requestID = error instanceof Error && Number.isSafeInteger(error.requestID) && error.requestID > 0 ? error.requestID : null;
   const assistantHint = error instanceof Error && typeof error.assistantHint === "string" ? error.assistantHint : "";
+  const idempotencyKey =
+    error instanceof Error && typeof error.idempotencyKey === "string" && error.idempotencyKey.length <= 128 ? error.idempotencyKey : "";
   const retryAfterSeconds =
     error instanceof Error && Number.isSafeInteger(error.retryAfterSeconds) && error.retryAfterSeconds >= 0
       ? error.retryAfterSeconds
@@ -31,6 +33,7 @@ export function errorResult(error) {
             ...(code ? { code } : {}),
             ...(requestID ? { request_id: requestID } : {}),
             ...(assistantHint ? { assistant_hint: assistantHint } : {}),
+            ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
             ...(retryAfterSeconds !== null ? { retry_after_seconds: retryAfterSeconds } : {}),
             error: message,
           },

package/dist/server.js

@@ -163,60 +163,104 @@ async function apiGet(path) {
 }
 
 async function apiPost(path, body) {
-  return apiRequest(path, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
+  return apiRequest(
+    path,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
     },
-    body: JSON.stringify(body),
-  });
-}
-
-async function apiRequest(path, options) {
-  const response = await apiFetch(path, options);
-  const text = await response.text();
-  const data = parseResponseBody(text);
-  if (!response.ok) {
-    throw gatewayAPIError(data, response.status);
-  }
-  return data;
+    body?.idempotency_key,
+  );
 }
 
-async function apiFetch(path, options) {
+async function apiRequest(path, options, idempotencyKey) {
   if (!apiToken) {
     throw new Error("AIPERMISSION_API_TOKEN is required.");
   }
+  let request;
+  try {
+    request = new Request(`${apiUrl}${path}`, {
+      ...options,
+      headers: new Headers({ Authorization: `Bearer ${apiToken}`, ...(options.headers || {}) }),
+    });
+  } catch {
+    throw new Error("Invalid local gateway request configuration; check the API URL and token.");
+  }
   const timeout = Number.isFinite(apiTimeoutMs) && apiTimeoutMs > 0 ? apiTimeoutMs : 60000;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
-  let response;
+  let bodyReceived = false;
   try {
-    response = await fetch(`${apiUrl}${path}`, {
-      ...options,
-      signal: controller.signal,
-      headers: {
-        Authorization: `Bearer ${apiToken}`,
-        ...(options.headers || {}),
-      },
-    });
+    const response = await fetch(request, { signal: controller.signal });
+    const text = await response.text();
+    const data = response.status === 204 ? null : parseResponseBody(text);
+    bodyReceived = true;
+    if (!response.ok) {
+      throw gatewayAPIError(data, response.status);
+    }
+    return data;
   } catch (error) {
-    if (error?.name === "AbortError") {
-      throw new Error(`AIPermission API request timed out after ${timeout}ms`, { cause: error });
+    let failure = bodyReceived ? error : new Error("Gateway response unavailable or invalid.", { cause: error });
+    if (controller.signal.aborted) {
+      failure = new Error(`AIPermission API request timed out after ${timeout}ms`, { cause: error });
+    }
+    const definitelyNotDispatched = !bodyReceived && isDefinitePredispatchTransportError(error);
+    if (definitelyNotDispatched) {
+      throw new Error("AIPermission gateway connection failed before request dispatch.", { cause: error });
     }
-    throw error;
+    if (options.method === "POST" && !bodyReceived) {
+      const uncertain = new Error(failure.message || "Gateway response unavailable", { cause: failure });
+      uncertain.resultStatus = "outcome_unknown";
+      uncertain.code = "gateway_transport_outcome_unknown";
+      uncertain.idempotencyKey = idempotencyKey;
+      uncertain.assistantHint = idempotencyKey
+        ? "The gateway response was lost; execution may have occurred. Reconcile the original request using the same idempotency key and unchanged input. Never retry with a new key blindly."
+        : "The gateway response was lost; execution may have occurred. Inspect the original request status before repeating the operation.";
+      throw uncertain;
+    }
+    throw failure;
   } finally {
     clearTimeout(timer);
   }
-  return response;
 }
 
-function parseResponseBody(text) {
-  if (!text) {
-    return null;
+const definitePredispatchErrorCodes = new Set([
+  "ECONNREFUSED",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "CERT_HAS_EXPIRED",
+]);
+
+function isDefinitePredispatchTransportError(error) {
+  const pending = [error];
+  const visited = new Set();
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current || (typeof current !== "object" && typeof current !== "function") || visited.has(current)) continue;
+    visited.add(current);
+    if (definitePredispatchErrorCodes.has(current.code)) return true;
+    if (current.cause) pending.push(current.cause);
+    if (Array.isArray(current.errors)) pending.push(...current.errors);
   }
+  return false;
+}
+
+function parseResponseBody(text) {
   try {
-    return JSON.parse(text);
+    const data = JSON.parse(text);
+    if (!data || typeof data !== "object") throw new Error("Invalid response shape");
+    return data;
   } catch {
-    return { error: text };
+    throw new Error("Gateway returned an invalid JSON response.");
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.2.43",
+  "version": "0.2.44",
   "mcpName": "io.github.aipermission/aipermission-mcp",
   "description": "Local-first MCP bridge for the aipermission gateway.",
   "license": "AGPL-3.0-only",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.aipermission/aipermission-mcp",
   "title": "AIPermission",
   "description": "Local-first MCP bridge for the AIPermission gateway.",
-  "version": "0.2.43",
+  "version": "0.2.44",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.43",
+      "version": "0.2.44",
       "transport": {
         "type": "stdio"
       }