Add scoped vault operation and observation hints

Author: hiroTamada

docs/vault-payments.md

@@ -184,13 +184,21 @@ A reusable card remaining `ready` does not establish that the last payment succe
 
 ## Observation, updates, and safety
 
-- Single-item responses are JSON text containing `{item, guidance}`. They preserve
+- Single-item responses are JSON text containing `{item, hints, guidance}`. They preserve
   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.
+- `hints.observation` contains `{tool, arguments}` entries for non-blocking `get`
+  and `events` calls. `hints.invocation` contains only currently advertised
+  operations, each with `requires_user_approval: true`. Hints preserve the resolved
+  project selector (when present), vault, and item key. Pass `tool` as the MCP
+  call's `name` and `arguments` unchanged. Provider-hosted actions remain separate
+  in `item.action` and approval URLs; they are not callable operation hints.
+  **A hint is not user approval or a recommendation to retry a payment.**
+  Availability can change; `invoke` still fetches the item and rechecks it.
 - 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.
@@ -199,9 +207,11 @@ A reusable card remaining `ready` does not establish that the last payment succe
   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.
-- `events` accepts `after` and returns `{events, next_after, guidance}`. Pass
-  `next_after` on the next call for the same vault/key. An empty result preserves
-  the input cursor (or returns `null` without one).
+- `events` accepts `after` and returns `{events, next_after, hints, guidance}`.
+  Its observation hints include the next events cursor, preserving the input
+  cursor on an empty result (or omitting `after` when there is no cursor).
+  Event responses do not include invocation hints because they do not establish
+  current operation availability.
 - **Ready does not mean paid.** Inspect state and immutable events for outcomes.
   No vault request is automatically retried. After a failed, timed-out, rejected,
   or indeterminate payment, inspect state/events; do not replay checkout, invoke

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

@@ -38,9 +38,11 @@ export function registerVaultCardTools(
     },
     async (params, extra) => {
       if (!extra.authInfo) throw new Error("Authentication required");
+      const project = projectForOperation(extra.authInfo, params);
+      const target = { project, vault: params.vault, key: params.key };
       const client = dependencies.createKernelClient(
         extra.authInfo.token,
-        projectForOperation(extra.authInfo, params),
+        project,
       );
       const options = { maxRetries: 0, signal: extra.signal };
       try {
@@ -66,7 +68,7 @@ export function registerVaultCardTools(
                 { id_or_name: params.vault, spec },
                 options,
               );
-        return vaultItemResponse(item);
+        return vaultItemResponse(item, target);
       } catch (error) {
         throwVaultError("manage_vault_cards", params.action, error);
       }

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

@@ -11,6 +11,7 @@ import {
   vaultEventFields,
   vaultItemFields,
   vaultItemResponse,
+  vaultObservationHints,
 } from "@/lib/mcp/vault-responses";
 import {
   vaultItemSchema,
@@ -63,9 +64,10 @@ export function registerVaultItemTools(
     },
     async (params, extra) => {
       if (!extra.authInfo) throw new Error("Authentication required");
+      const project = projectForOperation(extra.authInfo, params);
       const client = dependencies.createKernelClient(
         extra.authInfo.token,
-        projectForOperation(extra.authInfo, params),
+        project,
       );
       const options = { maxRetries: 0, signal: extra.signal };
       try {
@@ -86,6 +88,7 @@ export function registerVaultItemTools(
         }
         if (!params.key)
           return errorResponse("key is required except for list.");
+        const target = { project, vault: params.vault, key: params.key };
         switch (params.action) {
           case "get": {
             const item = await client.vaults.items.retrieve(
@@ -100,7 +103,7 @@ export function registerVaultItemTools(
                 signal: extra.signal,
               },
             );
-            return vaultItemResponse(item);
+            return vaultItemResponse(item, target);
           }
           case "invoke": {
             if (!params.operation)
@@ -125,7 +128,7 @@ export function registerVaultItemTools(
               },
               options,
             );
-            return vaultItemResponse(updated);
+            return vaultItemResponse(updated, target);
           }
           case "events": {
             const events = await client.vaults.items.events(
@@ -144,9 +147,11 @@ export function registerVaultItemTools(
             if (lastEventID !== undefined && typeof lastEventID !== "string") {
               throw new Error("Invalid vault event cursor");
             }
+            const nextAfter = lastEventID ?? params.after;
             return jsonResponse({
               events: projectVaultOutput(events, vaultEventFields),
-              next_after: lastEventID ?? params.after ?? null,
+              next_after: nextAfter ?? null,
+              hints: { observation: vaultObservationHints(target, nextAfter) },
               guidance:
                 "Observing events never retries a payment. Do not retry failed, timed-out, rejected, or indeterminate payments.",
             });

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

@@ -43,9 +43,11 @@ export function registerVaultWalletTools(
     },
     async (params, extra) => {
       if (!extra.authInfo) throw new Error("Authentication required");
+      const project = projectForOperation(extra.authInfo, params);
+      const target = { project, vault: params.vault, key: params.key };
       const client = dependencies.createKernelClient(
         extra.authInfo.token,
-        projectForOperation(extra.authInfo, params),
+        project,
       );
       const options = { maxRetries: 0, signal: extra.signal };
       try {
@@ -74,7 +76,7 @@ export function registerVaultWalletTools(
               },
               options,
             );
-            return vaultItemResponse(item);
+            return vaultItemResponse(item, target);
           }
           case "payment_methods": {
             const item = await client.vaults.items.retrieve(
@@ -85,7 +87,7 @@ export function registerVaultWalletTools(
               },
               { ...longOperationOptions(0), signal: extra.signal },
             );
-            return vaultItemResponse(item);
+            return vaultItemResponse(item, target);
           }
         }
       } catch (error) {