mppx 0.8.11 → 0.8.13

package/src/cli/utils.test.ts

@@ -3,12 +3,35 @@ import { afterEach, describe, expect, test, vi } from 'vp/test'
 
 import {
   fetchTokenInfo,
+  isAgentEnvironment,
   networkRpcUrls,
   resolveChain,
   resolveFundingNetwork,
   resolveRpcUrl,
 } from './utils.js'
 
+describe('isAgentEnvironment', () => {
+  test('detects Claude Code', () => {
+    expect(isAgentEnvironment({ CLAUDECODE: '1' })).toBe(true)
+  })
+
+  test('detects Codex by exact env var', () => {
+    expect(isAgentEnvironment({ CODEX: '1' })).toBe(true)
+  })
+
+  test('detects Codex wrapper env vars', () => {
+    expect(isAgentEnvironment({ CODEX_CI: '1' })).toBe(true)
+    expect(isAgentEnvironment({ CODEX_SANDBOX: 'seatbelt' })).toBe(true)
+    expect(isAgentEnvironment({ CODEX_THREAD_ID: '019f6bc0-b80f-7061-ac1b-7af8ba1ea513' })).toBe(
+      true,
+    )
+  })
+
+  test('ignores empty and unrelated env vars', () => {
+    expect(isAgentEnvironment({ CODEX_CI: '', CI: '1' })).toBe(false)
+  })
+})
+
 describe('resolveRpcUrl', () => {
   afterEach(() => {
     delete process.env.MPPX_RPC_URL

package/src/cli/utils.ts

@@ -179,6 +179,16 @@ export function parseMethodOpts(raw: string | string[] | undefined): Record<stri
   return result
 }
 
+/** Returns true when the CLI is running inside an agent wrapper that prefers machine-readable output. */
+export function isAgentEnvironment(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.CLAUDECODE) return true
+  for (const [key, value] of Object.entries(env)) {
+    if (!value) continue
+    if (key === 'CODEX' || key.startsWith('CODEX_')) return true
+  }
+  return false
+}
+
 export function isTempoAccount(accountName: string): boolean {
   return accountName.startsWith('tempo:')
 }

package/src/cli/validate/index.ts

@@ -1,9 +1,10 @@
 import { Cli, z } from 'incur'
 
 import { validate as validateCore, validateStream } from '../../validation/core.js'
-import { pc } from '../utils.js'
+import { isAgentEnvironment, pc } from '../utils.js'
 import type { Counts } from './helpers.js'
 import { printResults, printSection } from './helpers.js'
+import { missingDiscoverySuggestion } from './messages.js'
 
 const validate = Cli.create('validate', {
   description: 'Validate an MPP server implementation end-to-end',
@@ -22,7 +23,10 @@ const validate = Cli.create('validate', {
     header: z.array(z.string()).optional().describe('Request header (key:value, repeatable)'),
     verbose: z.number().default(0).meta({ count: true }).describe('Verbosity level'),
     yes: z.boolean().default(false).describe('Auto-approve mainnet payments'),
-    outputJson: z.boolean().default(false).describe('Output results as JSON'),
+    outputJson: z
+      .boolean()
+      .default(false)
+      .describe('Output results as JSON (auto-enabled in known agent environments)'),
   }),
   alias: {
     endpoint: 'e',
@@ -32,8 +36,10 @@ const validate = Cli.create('validate', {
     outputJson: 'j',
   },
   async run(c) {
+    const outputJson = c.options.outputJson || isAgentEnvironment()
+
     // JSON mode: batch everything
-    if (c.options.outputJson) {
+    if (outputJson) {
       const result = await validateCore({
         url: c.args.url,
         endpoint: c.options.endpoint,
@@ -82,17 +88,9 @@ const validate = Cli.create('validate', {
           discoveryFound = event.discovery.found
           if (!discoveryFound && !c.options.endpoint) {
             console.log('')
-            console.log(pc.yellow('  No discovery document found.'))
-            console.log(
-              pc.dim(
-                '  MPP servers must serve an OpenAPI document at /openapi.json with x-payment-info extensions.',
-              ),
-            )
-            console.log(
-              pc.dim(
-                '  To test a specific endpoint: mppx validate <url> --endpoint POST:/your/path',
-              ),
-            )
+            const [headline, ...lines] = missingDiscoverySuggestion.split('\n')
+            console.log(pc.yellow(`  ${headline}`))
+            for (const line of lines) console.log(line ? pc.dim(`  ${line}`) : '')
             console.log('')
             process.exit(1)
           }

package/src/cli/validate/messages.ts

@@ -0,0 +1,7 @@
+export const missingDiscoverySuggestion = [
+  'No discovery document found, endpoints could not be automatically found.',
+  'MPP servers must serve an OpenAPI document at /openapi.json with x-payment-info extensions.',
+  'The MPP SDKs can automatically expose this endpoint. See https://mpp.dev/sdk.',
+  '',
+  'To test a specific endpoint: mppx validate <url> --endpoint POST:/your/path',
+].join('\n')

package/src/cli/validate.test.ts

@@ -6,6 +6,10 @@ import * as Http from '~test/Http.js'
 import * as Challenge from '../Challenge.js'
 import * as Constants from '../Constants.js'
 import * as Receipt from '../Receipt.js'
+import { missingDiscoverySuggestion } from './validate/messages.js'
+
+// Keep validate tests out of JSON mode by default, even when the suite runs inside an agent.
+const isAgentEnvironmentMock = vi.fn(() => false)
 
 // Keep CLI orchestration tests independent of the public Tempo RPC and faucet.
 vi.doMock('viem/tempo', async () => {
@@ -28,11 +32,20 @@ vi.doMock('viem/actions', async () => {
   }
 })
 
+vi.doMock('./utils.js', async () => {
+  const actual = await vi.importActual<typeof import('./utils.js')>('./utils.js')
+  return {
+    ...actual,
+    isAgentEnvironment: isAgentEnvironmentMock,
+  }
+})
+
 // Auto-cleanup for test servers
 const servers: Http.TestServer[] = []
 afterEach(() => {
   servers.forEach((s) => s.close())
   servers.length = 0
+  isAgentEnvironmentMock.mockReturnValue(false)
 })
 
 async function testServer(handler: http.RequestListener) {
@@ -167,11 +180,8 @@ describe('validate: discovery', () => {
     })
     const { output, exitCode } = await serve(['validate', server.url])
     expect(exitCode).toBe(1)
-    expect(output).toContain('No discovery document found.')
-    expect(output).toContain('MPP servers must serve an OpenAPI document at /openapi.json')
-    expect(output).toContain(
-      'To test a specific endpoint: mppx validate <url> --endpoint POST:/your/path',
-    )
+    for (const line of missingDiscoverySuggestion.split('\n').filter(Boolean))
+      expect(output).toContain(line)
   })
 
   test('strips /openapi.json from input URL', { timeout: 15_000 }, async () => {
@@ -774,6 +784,19 @@ describe('validate: JSON mode', () => {
     expect(allPayment.every((r: { severity: string }) => r.severity === 'skip')).toBe(true)
   })
 
+  test(
+    'auto-enables JSON output when an agent environment is detected',
+    { timeout: 15_000 },
+    async () => {
+      const server = await mppServer(mainnetChallenge())
+      isAgentEnvironmentMock.mockReturnValue(true)
+      const { output } = await serve(['validate', server.url])
+      const result = parseJson(output)
+      expect(result.summary.skipped).toBeGreaterThan(0)
+      expect(result.endpoints.length).toBeGreaterThan(0)
+    },
+  )
+
   test('no console leaks before JSON', { timeout: 15_000 }, async () => {
     const server = await mppServer(mainnetChallenge())
     const { output } = await serve(['validate', server.url, '--outputJson', '--yes'])
@@ -791,4 +814,14 @@ describe('validate: JSON mode', () => {
     const result = parseJson(output)
     expect(Array.isArray(result.suggestions)).toBe(true)
   })
+
+  test('includes missing discovery suggestions', { timeout: 15_000 }, async () => {
+    const server = await testServer((_req, res) => {
+      res.writeHead(404)
+      res.end()
+    })
+    const { output } = await serve(['validate', server.url, '--outputJson'])
+    const result = parseJson(output)
+    expect(result.suggestions).toEqual([missingDiscoverySuggestion])
+  })
 })

package/src/client/internal/Fetch.test.ts

@@ -10,6 +10,7 @@ import { rpcUrl } from '~test/tempo/rpc.js'
 import { accounts, asset, chain, client, http } from '~test/tempo/viem.js'
 
 import * as Fetch from './Fetch.js'
+import * as MethodResponse from './MethodResponse.js'
 
 const realm = 'api.example.com'
 const secretKey = 'test-secret-key-test-secret-key-32'
@@ -391,6 +392,34 @@ function encodeRawPaymentRequiredHeader(value: unknown): string {
   return Base64.fromString(JSON.stringify(value))
 }
 
+describe('Fetch.from: method responses', () => {
+  test('handles successful paid responses without touching free responses', async () => {
+    const method = { ...noopMethod }
+    const handle = vi.fn(
+      async ({ response }: MethodResponse.HandlerParameters) =>
+        new Response(`handled:${await response.text()}`, response),
+    )
+    MethodResponse.register(method, handle)
+
+    let paidResponse: Response | undefined
+    const mockFetch: typeof globalThis.fetch = async (input, init) => {
+      if (input.toString().endsWith('/free')) return new Response('free')
+      if (!new Headers(init?.headers).has('Authorization')) return make402()
+      paidResponse = new Response('paid')
+      vi.spyOn(paidResponse, 'clone')
+      return paidResponse
+    }
+    const fetch = Fetch.from({ fetch: mockFetch, methods: [method] })
+
+    expect(await (await fetch('https://example.com/free')).text()).toBe('free')
+    expect(handle).not.toHaveBeenCalled()
+    expect(await (await fetch('https://example.com/paid')).text()).toBe('handled:paid')
+    expect(handle).toHaveBeenCalledOnce()
+    expect(handle).toHaveBeenCalledWith(expect.objectContaining({ credential: 'credential' }))
+    expect(paidResponse?.clone).not.toHaveBeenCalled()
+  })
+})
+
 describe('Fetch.from: init passthrough (non-402)', () => {
   test('preserves init object identity while adding Accept-Payment', async () => {
     const receivedInits: (RequestInit | undefined)[] = []

package/src/client/internal/Fetch.ts

@@ -6,6 +6,7 @@ import type { MaybePromise } from '../../internal/types.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
 import * as Transport from '../Transport.js'
+import * as MethodResponse from './MethodResponse.js'
 
 // We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
 // even across multiple module instances/bundles. This lets restore() avoid clobbering
@@ -18,6 +19,7 @@ type WrappedFetch = typeof globalThis.fetch & {
 }
 
 let originalFetch: typeof globalThis.fetch | undefined
+const eventObserverChecks = new WeakMap<object, (name: keyof ClientEventMap) => boolean>()
 
 export type ClientEventMap<
   methods extends readonly Method.AnyClient[] = readonly Method.AnyClient[],
@@ -174,7 +176,11 @@ export function from<const methods extends readonly Method.AnyClient[]>(
   // which can duplicate retries and make restore semantics fragile.
   const baseFetch = unwrapFetch(fetch)
 
-  const wrappedFetch = async (input: RequestInfo | URL, init?: from.RequestInit<methods>) => {
+  const request = async (
+    input: RequestInfo | URL,
+    init: from.RequestInit<methods> | undefined,
+    canRefetch: boolean,
+  ): Promise<Response> => {
     const callerHeaders = getCallerHeaders(input, init?.headers)
     const hasExplicitAcceptPayment = callerHeaders.has(Constants.Headers.acceptPayment)
     const paymentPreferences = resolvePaymentPreferences(callerHeaders, resolvedAcceptPayment)
@@ -272,8 +278,13 @@ export function from<const methods extends readonly Method.AnyClient[]>(
           }),
         )
 
+        const paymentInput = resolvePaymentRetryInput(
+          response,
+          initialRequest.input,
+          initialRequest.input,
+        )
         response = await baseFetch(
-          resolvePaymentRetryInput(response, initialRequest.input, initialRequest.input),
+          paymentInput,
           transport.setCredential(
             {
               ...fetchInit,
@@ -283,7 +294,8 @@ export function from<const methods extends readonly Method.AnyClient[]>(
             { challenge: selectedChallenge },
           ),
         )
-        if (response.ok)
+        // Cloning an unobserved stream would tee and buffer it indefinitely.
+        if (response.ok && hasEventObservers(events, 'payment.response'))
           await events.emit(
             'payment.response',
             createPaymentResponsePayload({
@@ -295,8 +307,23 @@ export function from<const methods extends readonly Method.AnyClient[]>(
               response,
             }),
           )
-        if (!(await transport.isPaymentRequired(response, transportRequest as never)))
-          return response
+        if (!(await transport.isPaymentRequired(response, transportRequest as never))) {
+          if (!response.ok) return response
+          return MethodResponse.handle(selected.method, {
+            challenge: selectedChallenge,
+            credential,
+            fetch: baseFetch,
+            headers: initialRequest.headers,
+            input: paymentInput,
+            ...(canRefetch
+              ? {
+                  refetch: () => request(cloneRequestInput(initialRequest.input), init, false),
+                }
+              : {}),
+            response,
+            signal: resolveRequestSignal(input, init),
+          })
+        }
       }
       return response
     } catch (error) {
@@ -315,6 +342,8 @@ export function from<const methods extends readonly Method.AnyClient[]>(
       throw error
     }
   }
+  const wrappedFetch = (input: RequestInfo | URL, init?: from.RequestInit<methods>) =>
+    request(input, init, true)
 
   // Record the wrapped target so future polyfill() / restore() calls can detect origin
   // and safely unwrap only mppx-installed wrappers.
@@ -491,7 +520,7 @@ export function createEventDispatcher<
     }
   }
 
-  return {
+  const dispatcher: ClientEventDispatcher<methods, response> = {
     async emit(name, payload) {
       switch (name) {
         case 'challenge.received': {
@@ -525,6 +554,15 @@ export function createEventDispatcher<
     },
     on,
   }
+  eventObserverChecks.set(
+    dispatcher,
+    (name) => handlers[name as keyof typeof handlers].size > 0 || handlers['*'].size > 0,
+  )
+  return dispatcher
+}
+
+function hasEventObservers(dispatcher: ClientEventDispatcher, name: keyof ClientEventMap): boolean {
+  return eventObserverChecks.get(dispatcher)?.(name) ?? true
 }
 
 async function emitChallengeReceived<methods extends readonly Method.AnyClient[], response>(
@@ -812,6 +850,13 @@ function cloneRequestInput(input: RequestInfo | URL): RequestInfo | URL {
   }
 }
 
+function resolveRequestSignal(
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+): AbortSignal | undefined {
+  return init?.signal ?? (input instanceof Request ? input.signal : undefined)
+}
+
 /** @internal */
 function isWrappedFetch(fetch: typeof globalThis.fetch): fetch is WrappedFetch {
   return Boolean((fetch as WrappedFetch)[MPPX_FETCH_WRAPPER])

package/src/client/internal/MethodResponse.ts

@@ -0,0 +1,39 @@
+import type * as Challenge from '../../Challenge.js'
+import type { MaybePromise } from '../../internal/types.js'
+import type * as Method from '../../Method.js'
+
+const handlers = new WeakMap<Method.AnyClient, Handler>()
+
+/** Inputs available when a client method handles a successful paid response. */
+export type HandlerParameters = {
+  challenge: Challenge.Challenge
+  credential: string
+  fetch: typeof globalThis.fetch
+  headers: Headers
+  input: RequestInfo | URL
+  refetch?: (() => Promise<Response>) | undefined
+  response: Response
+  signal?: AbortSignal | undefined
+}
+
+/** Internal client-method response adapter. */
+export type Handler = (parameters: HandlerParameters) => MaybePromise<Response>
+
+/** Registers an internal response adapter without changing the public method shape. */
+export function register<const method extends Method.AnyClient>(
+  method: method,
+  handler: Handler,
+): method {
+  handlers.set(method, handler)
+  return method
+}
+
+/** Removes response handling from a method whose caller owns the response lifecycle. */
+export function unregister(method: Method.AnyClient): void {
+  handlers.delete(method)
+}
+
+/** Lets the selected client method handle a successful paid response. */
+export function handle(method: Method.AnyClient, parameters: HandlerParameters): Promise<Response> {
+  return Promise.resolve(handlers.get(method)?.(parameters) ?? parameters.response)
+}

package/src/client/node.test.ts

@@ -0,0 +1,115 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+import { describe, expect, test } from 'vp/test'
+
+import type { ChannelEntry } from '../tempo/session/client/ChannelOps.js'
+import { entryKey } from '../tempo/session/client/ChannelStore.js'
+import { createSqliteChannelStore, defaultChannelDatabasePath } from './node.js'
+
+const channel: ChannelEntry = {
+  channelId: `0x${'11'.repeat(32)}`,
+  cumulativeAmount: 2_000_000n,
+  deposit: 10_000_000n,
+  descriptor: {
+    authorizedSigner: '0x0000000000000000000000000000000000000001',
+    expiringNonceHash: `0x${'22'.repeat(32)}`,
+    operator: '0x0000000000000000000000000000000000000000',
+    payee: '0x0000000000000000000000000000000000000002',
+    payer: '0x0000000000000000000000000000000000000003',
+    salt: `0x${'33'.repeat(32)}`,
+    token: '0x0000000000000000000000000000000000000004',
+  },
+  escrow: '0x0000000000000000000000000000000000000005',
+  chainId: 4217,
+  opened: true,
+}
+
+describe('SQLite ChannelStore', () => {
+  test('defaults to the shared Tempo wallet channels database', () => {
+    expect(defaultChannelDatabasePath()).toBe(join(homedir(), '.tempo', 'wallet', 'channels.db'))
+  })
+
+  test('persists a namespaced channel across fresh client instances', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'mppx-channels-'))
+    const path = join(directory, 'channels.db')
+    try {
+      const first = createSqliteChannelStore({ namespace: 'https://api.example.com', path })
+      first.set(channel)
+      first.close()
+
+      const second = createSqliteChannelStore({ namespace: 'https://api.example.com', path })
+      expect(second.get(entryKey(channel))).toEqual(channel)
+      second.set({ ...channel, cumulativeAmount: 1_000_000n, deposit: 5_000_000n })
+      expect(second.get(entryKey(channel))).toMatchObject({
+        cumulativeAmount: 2_000_000n,
+        deposit: 10_000_000n,
+      })
+      second.close()
+    } finally {
+      rmSync(directory, { recursive: true })
+    }
+  })
+
+  test('rehydrates an existing wallet-cli v2 channel row', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'mppx-wallet-channels-'))
+    const path = join(directory, 'channels.db')
+    try {
+      const database = new DatabaseSync(path)
+      database.exec(`CREATE TABLE channels (
+        channel_id TEXT PRIMARY KEY,
+        version INTEGER NOT NULL DEFAULT 1,
+        origin TEXT NOT NULL,
+        request_url TEXT NOT NULL DEFAULT '',
+        chain_id INTEGER NOT NULL,
+        escrow_contract TEXT NOT NULL,
+        token TEXT NOT NULL,
+        payee TEXT NOT NULL,
+        payer TEXT NOT NULL,
+        authorized_signer TEXT NOT NULL,
+        salt TEXT NOT NULL,
+        deposit TEXT NOT NULL,
+        cumulative_amount TEXT NOT NULL,
+        challenge_echo TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'active',
+        close_requested_at INTEGER NOT NULL DEFAULT 0,
+        grace_ready_at INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL,
+        last_used_at INTEGER NOT NULL,
+        accepted_cumulative TEXT NOT NULL DEFAULT '0',
+        server_spent TEXT NOT NULL DEFAULT '0',
+        session_protocol TEXT NOT NULL DEFAULT 'v1',
+        descriptor_json TEXT
+      )`)
+      database
+        .prepare(`INSERT INTO channels (
+          channel_id, origin, chain_id, escrow_contract, token, payee, payer,
+          authorized_signer, salt, deposit, cumulative_amount, challenge_echo,
+          state, created_at, last_used_at, session_protocol, descriptor_json
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, '{}', 'active', 1, 1, 'v2', ?)`)
+        .run(
+          channel.channelId,
+          'https://api.example.com',
+          channel.chainId,
+          channel.escrow,
+          channel.descriptor.token,
+          channel.descriptor.payee,
+          channel.descriptor.payer,
+          channel.descriptor.authorizedSigner,
+          channel.descriptor.salt,
+          channel.deposit.toString(),
+          channel.cumulativeAmount.toString(),
+          JSON.stringify(channel.descriptor),
+        )
+      database.close()
+
+      const store = createSqliteChannelStore({ namespace: 'https://api.example.com', path })
+      expect(store.get(entryKey(channel))).toEqual(channel)
+      store.close()
+    } finally {
+      rmSync(directory, { recursive: true })
+    }
+  })
+})