Feature: Implement CEP-8 Explicit Gating Lifecycle in Chat

[1amKhush]

Context

With the recent release of @contextvm/sdk@0.12.5, the core SDK now fully supports the CEP-8 explicit payment gating lifecycle (-32042 Payment Required and -32043 Payment Pending).

Currently, contextvm-site relies on the legacy transparent payment flow, which requires the server to wait for out-of-band payments. We need to update the web client to request the explicit_gating mode. This will allow the UI to capture payment requirements, show the invoice in the chat, and explicitly signal the SDK to retry the request once the user completes the payment.

Proposed Implementation

1. Update Dependencies

• Bump @contextvm/sdk to ^0.13.0 in package.json.

2. Add Promise Resolvers to Payment State

• Update PaymentNotificationsService (src/lib/services/payments/payment-notifications.svelte.ts) to include a resolver registry (pendingResolvers = new Map()).
• Add registerResolver(requestId, resolve) and resolvePayment(requestId, { paid, reason }) methods so the UI can communicate payment completion back to the SDK.

3. Configure Explicit Gating in the MCP Client

• In mcpClient.svelte.ts, update the withClientPayments wrapper configuration:

  • Set paymentInteraction: 'explicit_gating'.
  • Implement the onPaymentRequired callback.
  • Inside the callback, format the first available PaymentOption into the existing PaymentUiState shape and publish it to the paymentNotificationsService.
  • Return a Promise that registers its resolve function with the paymentNotificationsService (keyed by the original request ID).

4. Update the Payment UI Panel

• In PaymentStatusPanel.svelte, add user interaction buttons beneath the QR code:

  • "I have paid": Calls paymentNotificationsService.resolvePayment(payment.requestEventId, { paid: true }), which triggers the SDK to autonomously retry the original request.
  • "Cancel": Calls resolvePayment(..., { paid: false, reason: 'user_cancelled' }).

• (Optional) Add WebLN integration for 1-click payments.

[1amKhush]

Implementation Plan: Agentic Explicit Gating in contextvm-site

This updated plan outlines the steps to migrate the ContextVM web client to the CEP-8 explicit gating lifecycle (@contextvm/sdk@0.12.5).

Based on the agentic design philosophy, we will not use the SDK's autonomous retry wrapper (onPaymentRequired). Instead, the -32042 Payment Required error will bubble up to the caller (the agent). The agent can then pay the invoice autonomously (if equipped with a wallet tool) or surface the invoice to the user and wait for the user to confirm payment before the agent manually retries the tool call.

Objective

1. Enable explicit_gating in the SDK but let errors bubble up to the caller.
2. Ensure the LLM tool-calling loop gracefully handles -32042 errors, rendering the invoice in the chat using reusable components.
3. Add a debugging toggle on the server page to switch between transparent and explicit_gating modes.

---

Step 1: Update the SDK Dependency

• Bump @contextvm/sdk to ^0.13.0 in package.json.
• Run bun install to update the lockfile.

---

Step 2: Configure the MCP Client for Agentic Gating

We need to request explicit_gating during session negotiation but omit the onPaymentRequired callback so the SDK forwards the raw errors.

File: src/lib/services/mcpClient.svelte.ts

1. Modify createTransport to accept an optional mode override for debugging.
2. Update the withClientPayments configuration:

// allow mode to be passed in, defaulting to explicit_gating for the chat
const mode: PaymentInteractionMode = requestedMode ?? 'explicit_gating';

return withClientPayments(baseTransport, {
    paymentInteraction: mode,
    handlers: [uiHandler],
    // CRITICAL: We intentionally omit `onPaymentRequired` here.
    // This forces the SDK to bubble the -32042 JSON-RPC error directly
    // back to `client.callTool()`, allowing the agent to handle it.
});

3. Add a method to allow disconnecting and reconnecting a specific server with a new mode (to support the debugging toggle).

---

Step 3: Handle -32042 in the Chat / LLM Loop

When the agent attempts to call a priced tool, client.callTool() will throw an error if payment is required.

Files: Chat orchestration logic / Tool calling loop

1. Wrap client.callTool() in a try-catch block.

2. If the caught error has code === -32042 (Payment Required):

   • Render: Surface the error's payment_options data to the UI. Reuse the existing PaymentStatusPanel or a similar component to render the invoice/QR code gracefully in the chat stream.

   • Agent Context: Feed the -32042 error and the pay_req back into the LLM's context.

   • Execution Halted: The tool call is suspended. The agent can now either:

     • Use a registered "pay_invoice" tool if it holds a wallet.
     • Respond to the user: "This tool requires payment. Here is the invoice. Let me know when you have paid."

3. When the user replies "payment is done", the agent will naturally formulate a new callTool request with the exact same arguments, which will succeed because the server has verified the out-of-band payment.

---

Step 4: Add Debugging Toggle on Server/Tools Page

To aid developers in testing both lifecycles, add a UI toggle to manually override the negotiation mode.

Files: src/routes/server/[id]/+page.svelte (or equivalent tool-testing page)

1. Add a Switch or Select component: "Payment Mode: [ Explicit Gating | Transparent ]".

2. When the user toggles this switch:

   • Call mcpClientService.disconnect(serverIdentifier).
   • Re-initialize the connection with the newly selected paymentInteraction mode.

3. When the user manually invokes a tool via the UI button, catch any -32042 errors and render them in the UI using the same reusable payment error component used in the chat.