@aipermission/mcp 0.2.55 → 0.2.56

package/README.md

@@ -234,9 +234,12 @@ 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/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

@@ -237,24 +237,46 @@ 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),
@@ -266,12 +288,25 @@ export const responseContracts = Object.freeze({
   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/server.js

@@ -113,7 +113,7 @@ server.tool(
           },
           { signal },
         ),
-      (value) => projectGatewaySuccess(responseContracts.connectorActionCall, 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.connectorActionRequest, value),
+      (value) => projectGatewaySuccess(responseContracts.connectorActionRequest, value, { request_id }),
     );
   },
 );
@@ -154,7 +154,7 @@ 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 }) => {
@@ -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.55",
+  "version": "0.2.56",
   "mcpName": "io.github.aipermission/aipermission-mcp",
   "description": "Local-only MCP bridge for the aipermission gateway.",
   "license": "AGPL-3.0-only",
@@ -58,6 +58,6 @@
     "@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.55",
+  "version": "0.2.56",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@aipermission/mcp",
-      "version": "0.2.55",
+      "version": "0.2.56",
       "transport": {
         "type": "stdio"
       }