feat(action-provider): add @vdm-nexus action provider — signed inference for agents

[2504VDM]

Description

This PR adds vdm-nexus, a new action provider at typescript/agentkit/src/action-providers/vdm-nexus/ that exposes VDM Nexus — a signed-inference rail — as a tool surface for any AgentKit-built agent. It ships three actions: nexus_chat, nexus_verify_receipt, and nexus_get_deposit_address.

What signed inference is. A signed-inference receipt pairs an LLM call with (a) a cryptographic hash of the prompt and response, (b) an Ed25519 signature from the inference operator over the canonical receipt body, and (c) an on-chain USDC settlement transaction proving the call was paid for by a specific agent wallet. Third parties can verify all of this without trusting the caller or the service operator — the operator's published public key plus the on-chain record are the only trust anchors. The wire format is open and documented as SIR v2.

What this action provider does. nexus_chat performs the x402 two-roundtrip handshake (probe → sign with the AgentKit-managed Solana wallet → paid retry) against a Nexus /chat/completions endpoint and returns the OpenAI chat completion plus the SIR v2 receipt plus the settlement record. nexus_verify_receipt runs the five-check verifier against any receipt: prompt-hash recompute, response-hash recompute, operator-signature check, on-chain settlement lookup, and payer-identity match. nexus_get_deposit_address returns the destination address for off-band prepaid top-ups (the per-call path doesn't need it — payment settles inline).

Why AgentKit users would want it. An AgentKit agent gains a paid LLM endpoint that produces tamper-evident receipts in one wired-in action provider — useful for compliance regimes that demand audit trails of what models returned (EU AI Act Article 12, NIST AI agent standards, OWASP LLM Top 10 logging), and for trustless multi-agent flows where Agent A hands a receipt to Agent B and Agent B verifies it without trusting Agent A. The wallet attached to AgentKit IS the agent identity — no separate `AGENT_SECRET_KEY` env var is needed.

Live mainnet receipts (rendered by the same verifier code path this PR ships):

• First mainnet receipt: https://vdmnexus.com/r/c9710ea7-9e1f-46ee-aaa9-903a536ae12e
• Fresh receipt from the smoke test on the exact AgentKit code path: https://vdmnexus.com/r/5cf63978-77e6-4541-934a-e5879f33ae7a

Project home: https://vdmnexus.com — Developer docs: https://docs.vdmnexus.com

Relationship to the existing `x402` action provider

The upstream `x402` action provider is a general-purpose client for calling any x402-protected API. `vdm-nexus` is a higher-level adapter targeting one specific x402 rail (Nexus) and adding the verifiable-receipt semantics on top — the wire-level handshake is the same, but the receipt verification, model selection, and OpenAI response shape are specific to the Nexus deployment. Use `x402` when you want to call arbitrary paid APIs; use `vdm-nexus` when you specifically want paid LLM inference with cryptographic receipts.

Dependencies

• One new top-level dependency: `@vdm-nexus/x402@^0.4.0` (MIT, ESM-only, two source files: the x402 client driver and the SIR v2 receipt verifier). All transitive deps (`@x402/core`, `@x402/svm`, `@solana/kit`, `bs58`, `tweetnacl`) are already in the AgentKit dep graph via the existing `x402` provider.
• A changeset is included at `typescript/.changeset/vdm-nexus-action-provider.md` (patch bump).

Tests

Includes a Jest suite at `vdmNexusActionProvider.test.ts` covering: schema validation (chat / verify / deposit), `supportsNetwork`, all three action paths with mocked `fetch` + mocked `@x402/*` + mocked `@vdm-nexus/x402`, and the constructor edge case. 20 tests, all passing locally.

Chatbot: tested via standalone Node smoke against live production rail (https://nexus.vdmnexus.com)
Network: solana:mainnet
Setup: TEST_AGENT mainnet wallet (BSKq2XtBCXHGZKvP9KStjJdpimTAJbmRP7FqZ1SBTshR) funded with mainnet USDC

Prompt: "Reply with exactly one sentence: 'AgentKit drop-in is live.'"

Agent output: "Great news! AgentKit drop-in is now live."

Receipt: https://vdmnexus.com/r/5cf63978-77e6-4541-934a-e5879f33ae7a
Five-check verification: all passed (prompt_hash_ok, response_hash_ok,
                         nexus_signature_ok, payment_on_chain_ok, payer_matches)

Local checks: `pnpm run check`, `pnpm run lint`, `pnpm run format:check`, and `pnpm exec jest src/action-providers/vdm-nexus/` all pass.

A langchain-cdp-smart-wallet-chatbot exercise is the next step — happy to add it in a follow-up if maintainers prefer or wire it now.

Notes for reviewers

• Provider is bound to `SvmWalletProvider` because the wallet keypair signs the SPL USDC transfer carried in the x402 `X-Payment` header. An EVM-bound sibling for Base settlement is on the roadmap.
• The test file mocks `jose` and `@coinbase/cdp-sdk` at the top to avoid a known ESM-transform issue in the test environment (the cascade comes from `actionProvider.ts → wallet-providers → cdpEvmWalletProvider → @coinbase/cdp-sdk → jose`). Mirrors what `setup-jest.js` does at the suite level, but hoisted to the test file so it lands before the module imports resolve.
• Happy to rework any of this — the action names, the schema shapes, the description prompt copy, and the choice to keep the deposit-address action all easy to revise.
• I'll re-sign commits if signing is a hard requirement for review; flagging because the PR template requests it.

🤖 Generated with Claude Code

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2