Skip to content

feat: add CEP-8 explicit payment gating to cvmi call#5

Open
abhayguptas wants to merge 2 commits into
ContextVM:mainfrom
abhayguptas:feature/cep8-payment-gating
Open

feat: add CEP-8 explicit payment gating to cvmi call#5
abhayguptas wants to merge 2 commits into
ContextVM:mainfrom
abhayguptas:feature/cep8-payment-gating

Conversation

@abhayguptas

Copy link
Copy Markdown

Add CEP-8 Payment Lifecycle Support to cvmi call

Description

This PR brings full CEP-8 payment handling to the cvmi call command, bringing it up to parity with the contextvm-site client. Previously, calling a paid MCP endpoint via the CLI would fail or hang because the CLI had no awareness of notifications/payment_required.

This update upgrades @contextvm/sdk to 0.13.0 and utilizes its native withClientPayments middleware to handle all the heavy lifting (PMI capability advertisement, NIP-47 heartbeats, and waiting for server settlement).

Changes

  • SDK Upgrade: Bumped @contextvm/sdk to 0.13.0
  • Transport Wrapper: Wrapped NostrClientTransport in createRemoteClient with withClientPayments middleware.
  • CLI Payment Handler: Added a new CliPaymentHandler (mirroring UiOnlyPaymentHandler in contextvm-site). Instead of auto-paying, this handler simply prints the parsed lightning invoice to the terminal using standard UI tokens (BOLD, CYAN, DIM), and waits for human payment out-of-band while the SDK background loop awaits payment_accepted.
  • Payment Modes: Introduced the --payment-mode flag.
    • transparent (Default): Pauses execution, prints the invoice to the terminal, and waits for settlement.
    • explicit_gating: Designed for AI agents. If the server throws a -32042 Payment Required error, the CLI immediately outputs the raw payment schema as structured JSON to stdout and throws an exit code 2.

Usage Example

Human Usage (Transparent):

$ cvmi call <paid-server> <tool> --payment-mode transparent
# Output:
# ⚡ Payment Required
# ──────────────────────────────────────────────────
#   Amount:      50
#   Description: Paid tool execution
#   PMI:         bitcoin-lightning-bolt11
#   Expires in:  300s
# ──────────────────────────────────────────────────
#   Invoice:
#   lnbc...
# ──────────────────────────────────────────────────
#
# Pay the invoice above. The CLI is waiting for confirmation...

Agentic Usage (Explicit Gating):

$ cvmi call <paid-server> <tool> --payment-mode explicit_gating
# Output:
# { "instructions": "...", "payment_options": [ ... ] }
# Exit code: 2

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant