@aipermission/mcp 0.2.54 → 0.2.56

package/README.md

@@ -86,7 +86,7 @@ does this automatically.
 ## Tools
 
 `AIPERMISSION_HTTP_TIMEOUT_MS` sets the gateway request deadline (default:
-60000 milliseconds; maximum: 600000). The value must be a positive base-10
+95000 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
@@ -228,12 +228,18 @@ disclose secrets. Never automatically retry `submission_unknown`.
 
 Connector responses can include `approval_pending` or `running`. Poll
 `get_connector_action_request(request_id)` until the request reaches a terminal
-status. `outcome_unknown` is terminal and means the gateway could not prove the
-remote outcome after interruption; inspect target state or ask the operator
+status. Failed action calls carry the MCP `isError` flag; reading a recorded
+failed request is a successful read and does not. A `stopped` call response is a
+gateway control result, not a recorded request. `outcome_unknown` is terminal
+and means the gateway could not prove the remote outcome after interruption;
+inspect target state or ask the operator
 before retrying. Gateway API errors with that status retain their request id,
-assistant hint, and bounded retry delay in the MCP error envelope. MCP tool
-responses never include file contents, gateway
-temporary paths, archive staging paths, or local upload contents.
+assistant hint, and bounded retry delay in the MCP error envelope. File-transfer
+queue and status responses do not include transferred file bytes, gateway
+temporary paths, archive staging paths, or local upload contents. Explicitly
+authorized connector read actions may return bounded content, such as S3
+`download_object` `content_base64` or SSH command output; treat it as sensitive
+target data.
 
 ## Operator Skill
 

package/dist/config.js

@@ -1,4 +1,4 @@
-const defaultHTTPTimeoutMs = 60_000;
+const defaultHTTPTimeoutMs = 95_000;
 const maxHTTPTimeoutMs = 10 * 60_000;
 
 export function parseHTTPTimeout(value) {

package/dist/generated-connector-contract.js

@@ -0,0 +1,27 @@
+// Code generated by backend/cmd/openapi. DO NOT EDIT.
+
+export const connectorActionStatuses = Object.freeze([
+  "completed",
+  "failed",
+  "canceled",
+  "running",
+  "approval_pending",
+  "blocked",
+  "stale",
+  "declined",
+  "error",
+  "outcome_unknown",
+]);
+
+export const connectorRetryClasses = Object.freeze(["read_only", "idempotent", "conditional", "non_idempotent"]);
+
+export const executionRules = Object.freeze(["always_run", "approval_required", "blocked"]);
+
+export const connectorActionResponseRequiredFields = Object.freeze([
+  "status",
+  "request_id",
+  "target_ref",
+  "connector_kind",
+  "action_name",
+  "retry_policy",
+]);

package/dist/init.js

@@ -609,29 +609,40 @@ function removeTOMLServer(source, name) {
 }
 
 function scanTOMLHeader(line, state) {
-  if (state.multiline) {
-    if (hasMultilineDelimiter(line, state.multiline)) state.multiline = "";
-    return null;
-  }
   const trimmed = line.trimStart();
-  if (trimmed.startsWith("[")) {
+  if (!state.multiline && trimmed.startsWith("[")) {
     try {
       return findMarkerPath(parseTOML(`${line}\n__aipermission_header_marker = true\n`));
     } catch {
-      return null;
+      // A string can start with a bracket; scan it before the next line.
     }
   }
-  for (const delimiter of ['"""', "'''"]) {
-    if (!hasMultilineDelimiter(line, delimiter)) continue;
-    if ((line.split(delimiter).length - 1) % 2 === 1) state.multiline = delimiter;
-    break;
-  }
+  scanTOMLStrings(line, state);
   return null;
 }
 
-function hasMultilineDelimiter(line, delimiter) {
-  const comment = line.indexOf("#");
-  return (comment < 0 ? line : line.slice(0, comment)).includes(delimiter);
+function scanTOMLStrings(line, state) {
+  let quote = state.multiline;
+  for (let index = 0; index < line.length; index += 1) {
+    const character = line[index];
+    if (!quote && character === "#") break;
+    if (quote.startsWith('"') && character === "\\") {
+      index += 1;
+      continue;
+    }
+    if (quote) {
+      if (line.startsWith(quote, index)) {
+        index += quote.length - 1;
+        quote = "";
+      }
+      continue;
+    }
+    if (character !== '"' && character !== "'") continue;
+    const triple = character.repeat(3);
+    quote = line.startsWith(triple, index) ? triple : character;
+    index += quote.length - 1;
+  }
+  state.multiline = quote.length === 3 ? quote : "";
 }
 
 function findMarkerPath(value, pathParts = []) {

package/dist/resources/aipermission-operator/SKILL.md

@@ -113,6 +113,7 @@ Terminal statuses:
 ```text
 completed
 failed
+canceled
 declined
 blocked
 error
@@ -193,8 +194,11 @@ files or inspect remote paths. Prefer the smallest explicit path set. Do not use
 globs, recursive copy, or directory transfer unless a connector action
 explicitly supports that behavior.
 
-MCP connector responses never include file contents, gateway temp paths, archive
-staging paths, or local upload contents.
+File-transfer queue and status responses do not include transferred file bytes,
+gateway temp paths, archive staging paths, or local upload contents. Explicitly
+authorized connector read actions may return bounded content, such as S3
+`download_object` `content_base64` or SSH command output; treat it as sensitive
+target data.
 
 ## S3/Object Storage Practice
 
@@ -259,7 +263,8 @@ the operator how to rotate or redact it.
 Use Project Vault only through its dedicated tools:
 
 1. Call `list_vault_items(project_ref)` to discover names and non-secret
-   metadata. Never ask the gateway to reveal values.
+   metadata. Prefer an explicit `id:<id>` or `slug:<slug>` reference. Never ask
+   the gateway to reveal values.
 2. Use `call_vault_action` with `generate_item` only when the operator asked for
    a new secret. Use a stable, unique `idempotency_key`. Send `tags` as a string
    array, `shared_project_ids` as an integer array, and `usage_notes` as an

package/dist/response-contracts.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { connectorActionStatuses, connectorRetryClasses } from "./generated-connector-contract.js";
 
 const positiveID = z.number().int().positive();
 const nonNegativeInteger = z.number().int().nonnegative();
@@ -97,7 +98,7 @@ const outputHintSchema = z
   .strict();
 const retryPolicySchema = z
   .object({
-    class: z.string(),
+    class: z.enum([...connectorRetryClasses]),
     precondition_fields: z.array(z.string()).optional(),
     guidance: z.string(),
   })
@@ -119,28 +120,39 @@ const actionDefinitionSchema = z
 
 const connectorActionsSchema = z.object({ items: z.array(actionDefinitionSchema) }).strict();
 
-const connectorActionResponseSchema = z
+const connectorActionRequestSchema = z
   .object({
-    status: z.string(),
-    request_id: positiveID.optional(),
-    target_ref: z.string().optional(),
+    status: z.enum([...connectorActionStatuses]),
+    request_id: positiveID,
+    target_ref: z.string(),
     target_name: z.string().optional(),
-    connector_kind: z.string().optional(),
+    connector_kind: z.string(),
     profile_label: z.string().optional(),
-    action_name: z.string().optional(),
+    action_name: z.string(),
     input: z.record(z.unknown()).optional(),
     // Connector-owned output is intentionally opaque. The gateway credential
     // boundary redacts values; this schema owns only the shared MCP envelope.
     output: z.unknown().optional(),
     display_text: z.string().optional(),
     error: z.string().optional(),
-    retry_policy: retryPolicySchema.optional(),
-    retry_after_seconds: nonNegativeInteger.optional(),
+    retry_policy: retryPolicySchema,
+    retry_after_seconds: nonNegativeInteger.max(3600).optional(),
     assistant_hint: z.string().optional(),
     output_withheld: z.boolean().optional(),
     replayed: z.boolean().optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((value, context) => {
+    if (value.output_withheld) {
+      if (value.input !== undefined || value.output !== undefined || value.display_text !== undefined || value.error !== undefined) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "withheld action output must not contain request or result content" });
+      }
+    } else if (!value.target_ref || !value.connector_kind || !value.action_name) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "action response identity is required" });
+    }
+  });
+const connectorActionStoppedSchema = z.object({ status: z.literal("stopped"), error: z.string().min(1) }).strict();
+const connectorActionCallSchema = z.union([connectorActionRequestSchema, connectorActionStoppedSchema]);
 
 const vaultItemSchema = z
   .object({
@@ -225,40 +237,76 @@ const vaultSessionOutputSchema = z
   })
   .strict();
 
-const vaultActionResponseSchema = z
-  .object({
-    status: z.string(),
-    request_id: positiveID.optional(),
-    project_ref: z.string().optional(),
-    action_name: z.string().optional(),
-    input: z.union([vaultGenerateInputSchema, vaultSessionInputSchema]).optional(),
-    reason: z.string().optional(),
-    created_at: z.string().optional(),
-    expires_at: z.string().optional(),
-    secret_values_returned: z.literal(false).optional(),
-    output: z.union([generatedVaultOutputSchema, vaultSessionOutputSchema]).optional(),
-    output_withheld: z.boolean().optional(),
-    retry_after_seconds: nonNegativeInteger.optional(),
-    assistant_hint: z.string().optional(),
-    error: z.string().optional(),
-  })
-  .strict();
+const vaultActionStatuses = ["approval_pending", "running", "completed", "failed", "declined", "stale", "canceled", "expired"];
+const vaultActionRecordedShape = {
+  status: z.enum(vaultActionStatuses),
+  request_id: positiveID,
+  project_ref: z.string().min(1),
+  reason: z.string().optional(),
+  created_at: z.string().optional(),
+  expires_at: z.string().optional(),
+  secret_values_returned: z.literal(false),
+  output_withheld: z.literal(true).optional(),
+  retry_after_seconds: nonNegativeInteger.max(3600).optional(),
+  assistant_hint: z.string().optional(),
+  error: z.string().optional(),
+};
+const vaultActionRecordedSchema = z
+  .discriminatedUnion("action_name", [
+    z
+      .object({
+        ...vaultActionRecordedShape,
+        action_name: z.literal("generate_item"),
+        input: vaultGenerateInputSchema.optional(),
+        output: generatedVaultOutputSchema.optional(),
+      })
+      .strict(),
+    z
+      .object({
+        ...vaultActionRecordedShape,
+        action_name: z.literal("restart_session_with_environment"),
+        input: vaultSessionInputSchema.optional(),
+        output: vaultSessionOutputSchema.optional(),
+      })
+      .strict(),
+  ])
+  .superRefine((value, context) => {
+    if (value.output_withheld && value.output !== undefined) {
+      context.addIssue({ code: z.ZodIssueCode.custom, message: "withheld Vault output must not contain result content" });
+    }
+  });
+const vaultActionStoppedSchema = z.object({ status: z.literal("stopped"), error: z.string().min(1) }).strict();
+const vaultActionResponseSchema = z.union([vaultActionRecordedSchema, vaultActionStoppedSchema]);
 
 export const responseContracts = Object.freeze({
   connectorTargets: z.array(connectorTargetSchema),
   connectorHelp: connectorHelpSchema,
   connectorActions: connectorActionsSchema,
-  connectorAction: connectorActionResponseSchema,
+  connectorActionCall: connectorActionCallSchema,
+  connectorActionRequest: connectorActionRequestSchema,
   vaultItems: vaultItemsSchema,
   vaultAction: vaultActionResponseSchema,
 });
 
-export function projectGatewaySuccess(schema, value) {
+export function projectGatewaySuccess(schema, value, expected = undefined) {
   const result = schema.safeParse(value);
   if (!result.success) {
-    const error = new Error("Gateway success response failed MCP contract validation.");
-    error.code = "gateway_response_contract_invalid";
-    throw error;
+    throw gatewayContractError();
+  }
+  if (expected && result.data?.status !== "stopped") {
+    for (const [field, expectedValue] of Object.entries(expected)) {
+      if (expectedValue !== undefined && result.data?.[field] !== expectedValue) {
+        throw gatewayContractError();
+      }
+    }
+  } else if (expected && (expected.request_id !== undefined || expected.status !== undefined)) {
+    throw gatewayContractError();
   }
   return result.data;
 }
+
+function gatewayContractError() {
+  const error = new Error("Gateway success response failed MCP contract validation.");
+  error.code = "gateway_response_contract_invalid";
+  return error;
+}

package/dist/results.js

@@ -45,7 +45,7 @@ export function errorResult(error) {
   };
 }
 
-export async function jsonToolResult(callback, project, mutationContext = null) {
+export async function jsonToolResult(callback, project, mutationContext = null, isFailure = () => false) {
   if (typeof project !== "function") {
     return errorResult(new Error("MCP tool result projector is required."));
   }
@@ -56,12 +56,23 @@ export async function jsonToolResult(callback, project, mutationContext = null)
     return errorResult(error);
   }
   try {
-    return textResult(project(value));
+    const projected = project(value);
+    const result = textResult(projected);
+    return isFailure(projected) ? { ...result, isError: true } : result;
   } catch (error) {
     return errorResult(mutationContext ? projectionOutcomeUnknown(error, mutationContext) : error);
   }
 }
 
+export function jsonActionToolResult(callback, project, mutationContext) {
+  return jsonToolResult(
+    callback,
+    project,
+    mutationContext,
+    (value) => !["completed", "approval_pending", "running"].includes(value.status),
+  );
+}
+
 function projectionOutcomeUnknown(cause, context) {
   const error = new Error(
     "The gateway accepted the mutation, but its response failed MCP contract validation. The operation may have completed.",

package/dist/server.js

@@ -17,7 +17,7 @@ import { parseHTTPTimeout } from "./config.js";
 import { idempotencyKeySchema } from "./idempotency-key.js";
 import { normalizeLocalAPIURL } from "./local-url.js";
 import { projectGatewaySuccess, responseContracts } from "./response-contracts.js";
-import { jsonToolResult } from "./results.js";
+import { jsonActionToolResult, jsonToolResult } from "./results.js";
 import { externalActionAnnotations, localMutationAnnotations, localReadAnnotations } from "./tool-annotations.js";
 
 const packageMetadata = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -100,7 +100,7 @@ server.tool(
   },
   externalActionAnnotations,
   async ({ target_ref, action_name, input, reason, idempotency_key }, { signal }) => {
-    return jsonToolResult(
+    return jsonActionToolResult(
       () =>
         apiPost(
           "/api/mcp/connector-actions/call",
@@ -113,7 +113,7 @@ server.tool(
           },
           { signal },
         ),
-      (value) => projectGatewaySuccess(responseContracts.connectorAction, value),
+      (value) => projectGatewaySuccess(responseContracts.connectorActionCall, value, { target_ref, action_name }),
       { idempotencyKey: idempotency_key },
     );
   },
@@ -129,7 +129,7 @@ server.tool(
   async ({ request_id }, { signal }) => {
     return jsonToolResult(
       () => apiGet(`/api/mcp/connector-action-requests/${request_id}`, { signal }),
-      (value) => projectGatewaySuccess(responseContracts.connectorAction, value),
+      (value) => projectGatewaySuccess(responseContracts.connectorActionRequest, value, { request_id }),
     );
   },
 );
@@ -154,11 +154,11 @@ server.tool(
 
 server.tool(
   "call_vault_action",
-  "Run a Vault action under the configured project capability. Prompt waits for local approval; Always executes immediately through the same tracked request path. generate_item input accepts name, secret_type, generator_kind, provider, environment, description, expires_at, expiry_warning_days, tags (string array), usage_notes (array of {location, notes}), and shared_project_ids (integer array). restart_session_with_environment input requires target_ref and items with item_id, source_project_id, and optional replace_existing. Never include raw secret values.",
+  "Run a Vault action under the configured project capability. Prompt waits for local approval; Always executes immediately through the same tracked request path. generate_item input accepts name, optional secret_type (defaults to generic_secret), generator_kind, provider, environment, description, expires_at, expiry_warning_days, tags (string array), usage_notes (array of {location, notes}), and shared_project_ids (integer array). restart_session_with_environment input requires target_ref and items with item_id, source_project_id, and optional replace_existing. Never include raw secret values.",
   callVaultActionSchema,
   externalActionAnnotations,
   async ({ project_ref, action_name, input, reason, idempotency_key }, { signal }) => {
-    return jsonToolResult(
+    return jsonActionToolResult(
       () =>
         apiPost(
           "/api/mcp/vault-actions/call",
@@ -171,7 +171,7 @@ server.tool(
           },
           { signal },
         ),
-      (value) => projectGatewaySuccess(responseContracts.vaultAction, value),
+      (value) => projectGatewaySuccess(responseContracts.vaultAction, value, { project_ref, action_name }),
       { idempotencyKey: idempotency_key },
     );
   },
@@ -185,7 +185,7 @@ server.tool(
   async ({ request_id }, { signal }) => {
     return jsonToolResult(
       () => apiGet(`/api/mcp/vault-action-requests/${request_id}`, { signal }),
-      (value) => projectGatewaySuccess(responseContracts.vaultAction, value),
+      (value) => projectGatewaySuccess(responseContracts.vaultAction, value, { request_id }),
     );
   },
 );
@@ -198,7 +198,7 @@ server.tool(
   async ({ request_id }, { signal }) => {
     return jsonToolResult(
       () => apiPost(`/api/mcp/vault-action-requests/${request_id}/cancel`, {}, { requestID: request_id, signal }),
-      (value) => projectGatewaySuccess(responseContracts.vaultAction, value),
+      (value) => projectGatewaySuccess(responseContracts.vaultAction, value, { request_id, status: "canceled" }),
       { requestID: request_id },
     );
   },

package/dist/vault-tools.js

@@ -2,11 +2,16 @@ 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."),
+  project_ref: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Optional project reference. Prefer id:<id> or slug:<slug>; omit to list every readable project."),
 };
 
 export const callVaultActionSchema = {
-  project_ref: z.string().min(1).describe("Owning project id or slug."),
+  project_ref: z.string().trim().min(1).describe("Owning project reference. Prefer id:<id> or slug:<slug>."),
   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."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipermission/mcp",
-  "version": "0.2.54",
+  "version": "0.2.56",
   "mcpName": "io.github.aipermission/aipermission-mcp",
   "description": "Local-only MCP bridge for the aipermission gateway.",
   "license": "AGPL-3.0-only",
@@ -51,13 +51,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "smol-toml": "1.8.0",
-    "yaml": "2.9.0",
+    "yaml": "2.9.1",
     "zod": "3.25.76"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "eslint": "^10.10.0",
     "globals": "^17.11.0",
-    "prettier": "^3.9.6"
+    "prettier": "^3.9.8"
   }
 }

package/server.json

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