Inline vault tool schemas and restrict observation waits

Author: hiroTamada

docs/vault-payments.md

@@ -181,7 +181,8 @@ A reusable card remaining `ready` does not establish that the last payment succe
 - Vault lists return `{items, has_more, next_offset}`. Item lists return `{items}`.
   `get` with `expand: ["payment_methods"]` is equivalent to the wallet
   `payment_methods` action. An unavailable expansion returns an API error.
-- `get` and `events` accept `wait: 0..60`. Each call is one bounded observation,
+- Only `get` and `events` accept `wait: 0..60`; other actions reject it.
+  `invoke` does not wait for authorization. Each observation is bounded,
   not a background polling loop or readiness guarantee. The SDK timeout is the
   wait plus 30 seconds; configure the MCP client's timeout accordingly, or use
   shorter waits. Request cancellation is propagated to the SDK.

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

@@ -4,6 +4,18 @@ import { connectTestMcp } from "@/lib/mcp/mcp-test-fixtures";
 import { registerBrowserCapabilities } from "@/lib/mcp/tools/browsers";
 
 describe("browser vault attachment", () => {
+  test("advertises inline vault references without JSON Schema refs", async () => {
+    const fixture = await connectTestMcp(registerBrowserCapabilities, {});
+    try {
+      const { tools } = await fixture.client.listTools();
+      const browser = tools.find((tool) => tool.name === "manage_browsers");
+      expect(browser?.inputSchema.properties).toHaveProperty("vaults");
+      expect(JSON.stringify(browser?.inputSchema)).not.toContain('"$ref"');
+    } finally {
+      await fixture.close();
+    }
+  });
+
   test("forwards creation-only references by ID and name", async () => {
     const requests: Array<{ body: unknown; options: unknown }> = [];
     const fixture = await connectTestMcp(registerBrowserCapabilities, {

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

@@ -20,7 +20,7 @@ export function registerVaultCardTools(
     '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.',
     {
       ...vaultItemSchema,
-      key: vaultKeySchema,
+      key: vaultKeySchema(),
       action: z.enum(["create", "update"]),
       provider: vaultProviderSchema,
       spec: z

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

@@ -141,6 +141,46 @@ describe("advertised vault operations", () => {
 });
 
 describe("vault observation and deletion", () => {
+  test("advertises wait as get/events-only", async () => {
+    const fixture = await connectVaultTest([]);
+    try {
+      const { tools } = await fixture.client.listTools();
+      const tool = tools.find((tool) => tool.name === "manage_vault_items");
+      expect(tool?.inputSchema.properties?.wait).toMatchObject({
+        description: expect.stringContaining("(get, events)"),
+        minimum: 0,
+        maximum: 60,
+      });
+    } finally {
+      await fixture.close();
+    }
+  });
+
+  test.each(["list", "invoke", "delete"])(
+    "rejects wait on %s without making a request",
+    async (action) => {
+      const fixture = await connectVaultTest([]);
+      try {
+        for (const wait of [0, 60]) {
+          const result = await fixture.call("manage_vault_items", {
+            action,
+            vault: "checkout",
+            key: "order-1",
+            operation: "authorize",
+            wait,
+          });
+          expect(result.isError).toBe(true);
+          expect(JSON.stringify(result)).toContain(
+            "wait is only supported for get and events",
+          );
+        }
+        expect(fixture.requests).toHaveLength(0);
+      } finally {
+        await fixture.close();
+      }
+    },
+  );
+
   test("returns pending state without polling, and preserves the event cursor on an empty wait", async () => {
     const event = {
       id: "evt_2",

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

@@ -28,7 +28,7 @@ export function registerVaultItemTools(
     {
       ...vaultItemSchema,
       action: z.enum(["list", "get", "invoke", "events", "delete"]),
-      key: vaultKeySchema
+      key: vaultKeySchema()
         .describe("Required except for list. Immutable item key, not ID.")
         .optional(),
       operation: z
@@ -69,6 +69,15 @@ export function registerVaultItemTools(
       );
       const options = { maxRetries: 0, signal: extra.signal };
       try {
+        if (
+          params.wait !== undefined &&
+          params.action !== "get" &&
+          params.action !== "events"
+        ) {
+          return errorResponse(
+            "wait is only supported for get and events; invoke does not wait for authorization.",
+          );
+        }
         if (params.action === "list") {
           const items = await client.vaults.items.list(params.vault, options);
           return jsonResponse({

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

@@ -22,7 +22,7 @@ export function registerVaultWalletTools(
     'Connect payment wallets without exposing secrets. "create" creates or retrieves an identical wallet by immutable key and returns a provider connection/enrollment action for the user to complete. "payment_methods" requests the advertised live payment_methods expansion (unavailable expansions return an API error). Select Link payment_method_id explicitly; never automatically choose a default. AgentCard card_id may be omitted for cardholder selection at checkout approval. Capabilities are advisory; absent means unknown. Never provide card data or OAuth codes/tokens. Requests are not automatically retried.',
     {
       ...vaultItemSchema,
-      key: vaultKeySchema,
+      key: vaultKeySchema(),
       action: z.enum(["create", "payment_methods"]),
       provider: vaultProviderSchema
         .describe("(create) Payment provider.")

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

@@ -25,6 +25,7 @@ describe("vault SDK request contracts", () => {
       ]);
       for (const tool of tools) {
         expect(tool.inputSchema.properties).toHaveProperty("project");
+        expect(JSON.stringify(tool.inputSchema)).not.toContain('"$ref"');
         expect(tool.annotations).toMatchObject({
           readOnlyHint: false,
           idempotentHint: false,

src/lib/mcp/tools/vaults.ts

@@ -39,10 +39,10 @@ export function registerVaultCapabilities(
     {
       ...vaultProjectSchema,
       action: z.enum(["create", "list", "get", "delete"]),
-      vault: vaultSelectorSchema
+      vault: vaultSelectorSchema()
         .describe("(get, delete) Vault ID or immutable name.")
         .optional(),
-      name: vaultSelectorSchema
+      name: vaultSelectorSchema()
         .describe("(create) Immutable vault name.")
         .optional(),
       ...paginationParams,

src/lib/mcp/vault-schemas.ts

@@ -1,13 +1,16 @@
 import { z } from "zod";
 import { projectSelectionInputSchema } from "@/lib/mcp/project-selection";
 
-export const vaultSelectorSchema = z
-  .string()
-  .regex(/^[a-zA-Z0-9._-]{1,255}$/)
-  .refine(
-    (value) => value !== "." && value !== "..",
-    "Invalid vault selector.",
-  );
+// Fresh schemas per property keep tools/list contracts inline instead of emitting $refs.
+export function vaultSelectorSchema() {
+  return z
+    .string()
+    .regex(/^[a-zA-Z0-9._-]{1,255}$/)
+    .refine(
+      (value) => value !== "." && value !== "..",
+      "Invalid vault selector.",
+    );
+}
 
 export const vaultProjectSchema = projectSelectionInputSchema({
   project:
@@ -16,25 +19,27 @@ export const vaultProjectSchema = projectSelectionInputSchema({
 
 export const vaultItemSchema = {
   ...vaultProjectSchema,
-  vault: vaultSelectorSchema.describe("Vault ID or immutable name."),
+  vault: vaultSelectorSchema().describe("Vault ID or immutable name."),
 };
 
-export const vaultKeySchema = vaultSelectorSchema.describe(
-  "Immutable item key within the vault, not the item ID.",
-);
+export function vaultKeySchema() {
+  return vaultSelectorSchema().describe(
+    "Immutable item key within the vault, not the item ID.",
+  );
+}
 export const vaultProviderSchema = z.enum(["link", "agentcard"]);
 export const vaultWaitSchema = z
   .number()
   .int()
   .min(0)
   .max(60)
   .describe(
-    "One bounded server-side observation, in seconds (0-60). Pending state is returned as-is; this never retries a payment or guarantees readiness.",
+    "(get, events) One bounded server-side observation, in seconds (0-60). Not supported for invoke, list, or delete. Pending state is returned as-is; this never retries a payment or guarantees readiness.",
   )
   .optional();
 
-const integer = z.number().int().safe();
-const currency = z.string().regex(/^[A-Za-z]{3}$/);
+const integer = () => z.number().int().safe();
+const currency = () => z.string().regex(/^[A-Za-z]{3}$/);
 
 // Keep provider specifications in sync with https://api.onkernel.com/spec.yaml.
 export const linkWalletSpecSchema = z
@@ -60,60 +65,62 @@ export const agentcardWalletSpecSchema = z
   })
   .strict();
 
-const linkTotalSchema = z
-  .object({
-    type: z.string(),
-    display_text: z.string(),
-    amount: integer.describe("Integer minor currency units."),
-  })
-  .strict();
+function linkTotalSchema() {
+  return z
+    .object({
+      type: z.string(),
+      display_text: z.string(),
+      amount: integer().describe("Integer minor currency units."),
+    })
+    .strict();
+}
 
 const linkLineItemSchema = z
   .object({
     name: z.string(),
-    quantity: integer.min(1).optional(),
-    unit_amount: integer.optional(),
+    quantity: integer().min(1).optional(),
+    unit_amount: integer().optional(),
     description: z.string().optional(),
     sku: z.string().optional(),
     url: z.string().optional(),
     image_url: z.string().optional(),
     product_url: z.string().optional(),
-    totals: z.array(linkTotalSchema).optional(),
+    totals: z.array(linkTotalSchema()).optional(),
   })
   .strict();
 
 export const linkCardSpecSchema = z
   .object({
     provider: z.literal("link").optional(),
-    wallet: vaultKeySchema,
+    wallet: vaultKeySchema(),
     payment_method_id: z
       .string()
       .min(1)
       .describe(
         "Explicitly selected ID from the wallet's payment_methods expansion.",
       ),
-    amount: integer
+    amount: integer()
       .min(1)
       .max(500000)
       .describe("Integer minor currency units."),
-    currency,
+    currency: currency(),
     merchant_name: z.string().min(1).max(255),
     merchant_url: z.string().url(),
     context: z.string().min(100),
     line_items: z.array(linkLineItemSchema).optional(),
-    totals: z.array(linkTotalSchema).optional(),
+    totals: z.array(linkTotalSchema()).optional(),
     metadata: z.record(z.string()).optional(),
-    expires_at: integer.optional(),
+    expires_at: integer().optional(),
   })
   .strict();
 
 export const agentcardCardSpecSchema = z
   .object({
     provider: z.literal("agentcard").optional(),
-    wallet: vaultKeySchema,
+    wallet: vaultKeySchema(),
     merchant: z.string().min(1).max(120),
-    amount: integer.min(1).describe("Integer minor currency units."),
-    currency,
+    amount: integer().min(1).describe("Integer minor currency units."),
+    currency: currency(),
     card_id: z
       .string()
       .regex(/^vc_[A-Za-z0-9_]+$/)
@@ -128,8 +135,8 @@ export const browserVaultsSchema = z
   .array(
     z
       .object({
-        id: vaultSelectorSchema.optional(),
-        name: vaultSelectorSchema.optional(),
+        id: vaultSelectorSchema().optional(),
+        name: vaultSelectorSchema().optional(),
       })
       .strict()
       .refine(