@aipermission/mcp 0.2.51 → 0.2.53

package/README.md

@@ -86,8 +86,10 @@ 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
+60000 milliseconds; maximum: 600000). The value must be a positive base-10
+integer; invalid configuration stops the bridge instead of silently changing
+the deadline. 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`.
@@ -103,6 +105,12 @@ and `Retry-After`. Respect that delay; immediate retry loops cannot bypass the
 gateway's per-workspace/token rate, persisted-running concurrency, input, or
 atomic projected-storage limits.
 
+The normal `npm test` command requires a full Git clone so its test-manifest
+ratchet can compare against trusted history. A GitHub source archive has no
+history; use `npm run test:source-archive` there to run the complete current
+behavior suite and current-manifest checks. That archive command intentionally
+does not claim to verify the historical anti-regression ratchet.
+
 - `list_connector_targets`
 - `get_connector_help`
 - `get_connector_actions`

package/dist/api-error.js

@@ -1,13 +1,20 @@
 const safeResultStatuses = new Set(["failed", "blocked", "stale", "declined", "canceled", "error", "outcome_unknown"]);
 
-export function gatewayAPIError(data, httpStatus) {
+export function gatewayAPIError(data, httpStatus, retryAfterHeader = null) {
   const error = new Error(data?.error || `AIPermission API request failed with ${httpStatus}`);
   if (typeof data?.code === "string" && data.code.length <= 128) error.code = data.code;
   if (safeResultStatuses.has(data?.status)) error.resultStatus = data.status;
   if (Number.isSafeInteger(data?.request_id) && data.request_id > 0) error.requestID = data.request_id;
   if (typeof data?.assistant_hint === "string" && data.assistant_hint.length <= 2048) error.assistantHint = data.assistant_hint;
-  if (Number.isSafeInteger(data?.retry_after_seconds) && data.retry_after_seconds >= 0 && data.retry_after_seconds <= 3600) {
-    error.retryAfterSeconds = data.retry_after_seconds;
-  }
+  const retryAfterSeconds = safeRetryAfterSeconds(data?.retry_after_seconds, retryAfterHeader);
+  if (retryAfterSeconds !== null) error.retryAfterSeconds = retryAfterSeconds;
   return error;
 }
+
+function safeRetryAfterSeconds(bodyValue, headerValue) {
+  if (Number.isSafeInteger(bodyValue) && bodyValue >= 0 && bodyValue <= 3600) return bodyValue;
+  const raw = typeof headerValue === "string" ? headerValue.trim() : "";
+  if (!/^\d{1,4}$/.test(raw)) return null;
+  const value = Number(raw);
+  return value <= 3600 ? value : null;
+}

package/dist/config.js

@@ -0,0 +1,15 @@
+const defaultHTTPTimeoutMs = 60_000;
+const maxHTTPTimeoutMs = 10 * 60_000;
+
+export function parseHTTPTimeout(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return defaultHTTPTimeoutMs;
+  if (!/^[1-9]\d*$/.test(raw)) {
+    throw new Error("AIPERMISSION_HTTP_TIMEOUT_MS must be a positive integer in milliseconds.");
+  }
+  const timeout = Number(raw);
+  if (!Number.isSafeInteger(timeout) || timeout > maxHTTPTimeoutMs) {
+    throw new Error(`AIPERMISSION_HTTP_TIMEOUT_MS must not exceed ${maxHTTPTimeoutMs} milliseconds.`);
+  }
+  return timeout;
+}

package/dist/idempotency-key.js

@@ -0,0 +1,8 @@
+import { Buffer } from "node:buffer";
+import { z } from "zod";
+
+export const idempotencyKeySchema = z
+  .string()
+  .min(1)
+  .refine((value) => Buffer.byteLength(value, "utf8") <= 128, "Idempotency key must not exceed 128 UTF-8 bytes.")
+  .describe("Caller-stable key used to prevent duplicate action requests.");

package/dist/server.js

@@ -13,6 +13,8 @@ import { z } from "zod";
 import { callVaultActionSchema, listVaultItemsSchema, vaultActionRequestSchema } from "./vault-tools.js";
 import { MCP_SERVER_INSTRUCTIONS } from "./instructions.js";
 import { gatewayAPIError } from "./api-error.js";
+import { parseHTTPTimeout } from "./config.js";
+import { idempotencyKeySchema } from "./idempotency-key.js";
 import { normalizeLocalAPIURL } from "./local-url.js";
 import { jsonToolResult } from "./results.js";
 
@@ -25,7 +27,7 @@ try {
   apiURLConfigurationError = new Error("Invalid local gateway URL configuration; update AIPERMISSION_API_URL.", { cause: error });
 }
 const apiToken = process.env.AIPERMISSION_API_TOKEN || "";
-const apiTimeoutMs = Number.parseInt(process.env.AIPERMISSION_HTTP_TIMEOUT_MS || "60000", 10);
+const apiTimeoutMs = parseHTTPTimeout(process.env.AIPERMISSION_HTTP_TIMEOUT_MS);
 
 const server = new McpServer(
   {
@@ -80,11 +82,7 @@ server.tool(
     action_name: z.string().min(1).describe("Action name from get_connector_actions."),
     input: z.record(z.unknown()).optional().describe("Connector-specific action input."),
     reason: z.string().optional().describe("Why this connector action is needed."),
-    idempotency_key: z
-      .string()
-      .min(1)
-      .max(128)
-      .describe("Caller-stable key that makes retries return the original request without running twice."),
+    idempotency_key: idempotencyKeySchema,
   },
   async ({ target_ref, action_name, input, reason, idempotency_key }) => {
     return jsonToolResult(() =>
@@ -155,7 +153,7 @@ server.tool(
   "Cancel one approval_pending Vault action request owned by this token. Running or terminal requests cannot be canceled.",
   vaultActionRequestSchema,
   async ({ request_id }) => {
-    return jsonToolResult(() => apiPost(`/api/mcp/vault-action-requests/${request_id}/cancel`, {}));
+    return jsonToolResult(() => apiPost(`/api/mcp/vault-action-requests/${request_id}/cancel`, {}, { requestID: request_id }));
   },
 );
 
@@ -168,7 +166,7 @@ async function apiGet(path) {
   });
 }
 
-async function apiPost(path, body) {
+async function apiPost(path, body, context = {}) {
   return apiRequest(
     path,
     {
@@ -179,10 +177,11 @@ async function apiPost(path, body) {
       body: JSON.stringify(body),
     },
     body?.idempotency_key,
+    context,
   );
 }
 
-async function apiRequest(path, options, idempotencyKey) {
+async function apiRequest(path, options, idempotencyKey, context = {}) {
   if (apiURLConfigurationError) {
     throw apiURLConfigurationError;
   }
@@ -198,7 +197,7 @@ async function apiRequest(path, options, idempotencyKey) {
   } 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 timeout = apiTimeoutMs;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   let bodyReceived = false;
@@ -208,7 +207,7 @@ async function apiRequest(path, options, idempotencyKey) {
     const data = response.status === 204 ? null : parseResponseBody(text);
     bodyReceived = true;
     if (!response.ok) {
-      throw gatewayAPIError(data, response.status);
+      throw gatewayAPIError(data, response.status, response.headers.get("Retry-After"));
     }
     return data;
   } catch (error) {
@@ -225,6 +224,7 @@ async function apiRequest(path, options, idempotencyKey) {
       uncertain.resultStatus = "outcome_unknown";
       uncertain.code = "gateway_transport_outcome_unknown";
       uncertain.idempotencyKey = idempotencyKey;
+      if (Number.isSafeInteger(context.requestID) && context.requestID > 0) uncertain.requestID = context.requestID;
       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.";

package/dist/vault-tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { idempotencyKeySchema } from "./idempotency-key.js";
 
 export const listVaultItemsSchema = {
   project_ref: z.string().min(1).optional().describe("Optional project id or slug. Omit to list every readable project."),
@@ -9,7 +10,7 @@ export const callVaultActionSchema = {
   action_name: z.enum(["generate_item", "restart_session_with_environment"]),
   input: z.record(z.unknown()).describe("Action input. Never include raw secret values."),
   reason: z.string().min(1).describe("Why this Vault action is needed."),
-  idempotency_key: z.string().min(1).max(128).describe("Caller-stable key used to prevent duplicate action requests."),
+  idempotency_key: idempotencyKeySchema,
 };
 
 export const vaultActionRequestSchema = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.2.51",
+  "version": "0.2.53",
   "mcpName": "io.github.aipermission/aipermission-mcp",
   "description": "Local-first MCP bridge for the aipermission gateway.",
   "license": "AGPL-3.0-only",
@@ -33,6 +33,7 @@
     "lint": "eslint src test scripts",
     "prepack": "npm run build",
     "test": "npm run build && node scripts/run-tests.js",
+    "test:source-archive": "npm run build && node scripts/run-tests.js --current-only",
     "test:windows-acl": "node scripts/run-windows-acl-tests.js",
     "start": "node dist/cli.js",
     "dev": "node src/cli.js"

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.51",
+  "version": "0.2.53",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.51",
+      "version": "0.2.53",
       "transport": {
         "type": "stdio"
       }