Curate vault errors and document live-only cards

Author: hiroTamada

docs/vault-payments.md

@@ -4,6 +4,9 @@ The vault tools prepare and observe payment credentials. They do **not** submit
 merchant payments, expose real card values, or complete provider approval actions.
 They use the same vault API as the Kernel CLI.
 
+**These are live payment cards. Test-mode creation is unsupported.** Do not assume
+that a development or staging MCP endpoint makes a card request a test transaction.
+
 ## Tools and scope
 
 | Tool                   | Actions                                     |
@@ -177,6 +180,8 @@ A reusable card remaining `ready` does not establish that the last payment succe
   public state, non-secret aliases, masks, safe action/approval URLs, advertised
   operations/expansions, and payment outcomes. Unknown provider fields, opaque
   event data, free-form metadata, and URLs carrying OAuth codes/tokens are omitted.
+  API errors retain the HTTP status but use curated messages for recognized error
+  codes. Unknown codes use a generic fallback; upstream error text is never returned.
   There is no raw-output or raw-card tool.
 - Vault lists return `{items, has_more, next_offset}`. Item lists return `{items}`.
   `get` with `expand: ["payment_methods"]` is equivalent to the wallet

src/lib/mcp/tools/vault-cards.ts

@@ -17,7 +17,7 @@ export function registerVaultCardTools(
 ) {
   server.tool(
     "manage_vault_cards",
-    'Configure payment card requests, not merchant payments. "create" creates or retrieves an identical card request by immutable key. "update" replaces the ENTIRE spec, removing omitted optional fields, only when the API permits it. Neither implicitly authorizes Link: inspect available_operations with manage_vault_items and obtain explicit user approval before invoking. AgentCard authorizes at checkout. Amounts are integer minor currency units. No card data, OAuth tokens, provider secrets, or domain configuration. Never reconfigure a card to retry a failed, timed-out, rejected, or indeterminate payment. Requests are not automatically retried.',
+    'Configure requests for live payment cards, not merchant payments. Test-mode creation is unsupported. "create" creates or retrieves an identical card request by immutable key. "update" replaces the ENTIRE spec, removing omitted optional fields, only when the API permits it. Neither implicitly authorizes Link: inspect available_operations with manage_vault_items and obtain explicit user approval before invoking. AgentCard authorizes at checkout. Amounts are integer minor currency units. No card data, OAuth tokens, provider secrets, or domain configuration. Never reconfigure a card to retry a failed, timed-out, rejected, or indeterminate payment. Requests are not automatically retried.',
     {
       ...vaultItemSchema,
       key: vaultKeySchema(),

src/lib/mcp/tools/vault-items.test.ts

@@ -113,7 +113,7 @@ describe("advertised vault operations", () => {
     async (stage) => {
       const failure = Response.json(
         {
-          code: "provider_unavailable",
+          code: "provider_error",
           message: "Provider unavailable",
           opaque: "hidden",
         },
@@ -130,7 +130,7 @@ describe("advertised vault operations", () => {
           operation: "authorize",
         });
         expect(result.isError).toBe(true);
-        expect(JSON.stringify(result)).toContain("provider_unavailable");
+        expect(JSON.stringify(result)).toContain("provider_error");
         expect(JSON.stringify(result)).not.toContain("hidden");
         expect(fixture.requests).toHaveLength(stage === "get" ? 1 : 2);
       } finally {

src/lib/mcp/tools/vaults.test.ts

@@ -32,6 +32,9 @@ describe("vault SDK request contracts", () => {
           openWorldHint: true,
         });
       }
+      const cards = tools.find((tool) => tool.name === "manage_vault_cards");
+      expect(cards?.description).toContain("live payment cards");
+      expect(cards?.description).toContain("Test-mode creation is unsupported");
       expect(fixture.requests).toHaveLength(0);
     } finally {
       await fixture.close();

src/lib/mcp/vault-responses.test.ts

@@ -218,6 +218,90 @@ describe("vault public responses", () => {
     }
   });
 
+  test.each([
+    [400, "invalid_request", "Invalid vault request."],
+    [404, "not_found", "Vault, item, or project not found or unavailable."],
+    [409, "conflict", "conflicts with the current configuration or state"],
+    [500, "project_error", "Unable to resolve the vault's project."],
+    [500, "db_error", "The vault storage request could not be completed."],
+    [
+      500,
+      "provider_error",
+      "The payment provider could not complete the vault request.",
+    ],
+    [500, "provider_rate_limited", "rate limited requests"],
+    [429, "spend_request_rate_limited", "rate limited spend requests"],
+  ] as const)(
+    "returns curated text for HTTP %s / %s",
+    async (status, code, message) => {
+      const fixture = await connectVaultTest([
+        Response.json(
+          {
+            code,
+            message: "access_token=hidden-free-text",
+            details: "hidden-details",
+          },
+          { status },
+        ),
+      ]);
+      try {
+        const result = await fixture.call("manage_vault_items", {
+          action: "get",
+          vault: "checkout",
+          key: "order-1",
+        });
+        const text = JSON.stringify(result);
+        expect(result.isError).toBe(true);
+        expect(text).toContain(`${status} `);
+        expect(text).toContain(message);
+        expect(text).toContain(`[code: ${code}]`);
+        expect(text).toContain("Do not replay a payment.");
+        expect(text).not.toContain("hidden");
+      } finally {
+        await fixture.close();
+      }
+    },
+  );
+
+  test.each(
+    [
+      undefined,
+      null,
+      123,
+      {},
+      [],
+      "",
+      "unknown_error",
+      "__proto__",
+      "constructor",
+      "invalid_request hidden-suffix",
+    ].map((code) => ({ code })),
+  )(
+    "uses a generic fallback for unrecognized error codes",
+    async ({ code }) => {
+      const fixture = await connectVaultTest([
+        Response.json(
+          { code, message: "password=hidden-password" },
+          { status: 400 },
+        ),
+      ]);
+      try {
+        const result = await fixture.call("manage_vault_items", {
+          action: "get",
+          vault: "checkout",
+          key: "order-1",
+        });
+        const text = JSON.stringify(result);
+        expect(result.isError).toBe(true);
+        expect(text).toContain("400 Vault request failed.");
+        expect(text).not.toContain("[code:");
+        expect(text).not.toContain("hidden");
+      } finally {
+        await fixture.close();
+      }
+    },
+  );
+
   test.each([
     {
       message: "Expansion unavailable",
@@ -226,6 +310,12 @@ describe("vault public responses", () => {
       headers: { authorization: "hidden-auth" },
     },
     { raw_provider: { secret: "hidden-without-message" } },
+    {
+      code: "invalid_request",
+      message: "access_token=hidden-plaintext-secret",
+    },
+    { code: "access_token=hidden-code-secret", message: "Invalid request" },
+    { code: "conflict", message: "password=hidden-password-secret" },
     {
       message: "Follow https://provider.example/?code=hidden-code",
       code: "action_required",
@@ -245,9 +335,17 @@ describe("vault public responses", () => {
         });
         expect(result.isError).toBe(true);
         expect(JSON.stringify(result)).not.toContain("hidden");
-        if (body.code) expect(JSON.stringify(result)).toContain(body.code);
+        if (
+          ["provider_error", "invalid_request", "conflict"].includes(
+            body.code ?? "",
+          )
+        ) {
+          expect(JSON.stringify(result)).toContain(`[code: ${body.code}]`);
+        } else {
+          expect(JSON.stringify(result)).not.toContain("[code:");
+        }
         if (body.message === "Expansion unavailable")
-          expect(JSON.stringify(result)).toContain(body.message);
+          expect(JSON.stringify(result)).not.toContain(body.message);
       } finally {
         await fixture.close();
       }

src/lib/mcp/vault-responses.ts

@@ -139,12 +139,36 @@ export function vaultItemResponse(item: unknown) {
   });
 }
 
-function publicErrorMessage(value: unknown): string {
-  if (typeof value !== "string") return "Vault request failed";
-  return value.replace(/https?:\/\/[^\s"'<>]+/g, (url) =>
-    isDisplaySafeVaultURL(url) ? url : "[redacted URL]",
-  );
-}
+const vaultErrorMessages = new Map([
+  [
+    "invalid_request",
+    "Invalid vault request. Check the tool's documented inputs.",
+  ],
+  ["not_found", "Vault, item, or project not found or unavailable."],
+  [
+    "conflict",
+    "The vault request conflicts with the current configuration or state. Inspect the item and its advertised operations and expansions.",
+  ],
+  [
+    "project_error",
+    "Unable to resolve the vault's project. Check connection scope and project selection.",
+  ],
+  ["db_error", "The vault storage request could not be completed."],
+  [
+    "provider_error",
+    "The payment provider could not complete the vault request.",
+  ],
+  [
+    "provider_rate_limited",
+    "The payment provider has rate limited requests. Stop and wait before taking further action.",
+  ],
+  [
+    "spend_request_rate_limited",
+    "The payment provider has rate limited spend requests. Stop and wait before taking further action.",
+  ],
+]);
+const vaultErrorGuidance =
+  "Inspect item state/events before taking further action. Do not replay a payment.";
 
 export function throwVaultError(
   tool: string,
@@ -159,27 +183,26 @@ export function throwVaultError(
     );
   }
   if (error instanceof APIError && typeof error.status === "number") {
-    // SDK errors can stringify the entire provider body when no message is present.
-    // Retain only the standard public message/code, never that fallback or headers.
+    // Neither provider messages nor unknown codes are safe to return, even as strings.
     const body = error.error;
-    const message = publicErrorMessage(
-      body && typeof body === "object" && "message" in body
-        ? body.message
-        : undefined,
-    );
     const code =
       body &&
       typeof body === "object" &&
       "code" in body &&
       typeof body.code === "string"
         ? body.code
         : undefined;
+    const message =
+      code === undefined ? undefined : vaultErrorMessages.get(code);
     throwToolError(
       tool,
       action,
       APIError.generate(
         error.status,
-        { message, code },
+        {
+          message: `${message ?? "Vault request failed."} ${vaultErrorGuidance}`,
+          ...(message !== undefined && { code }),
+        },
         undefined,
         new Headers(),
       ),