@oobe-protocol-labs/synapse-client-sdk 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -7,6 +7,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.2.2] — 2026-03-02
+
+### Added
+
+- **`toJsonSafe()` & `bigIntReplacer()`** — Recursive BigInt→string serializer and
+  `JSON.stringify` replacer. Eliminates the "Do not know how to serialize a BigInt"
+  crash in Next.js API Routes and Express handlers.
+  (`import { toJsonSafe, bigIntReplacer } from '…/utils'`)
+
+- **`createSingleton()`** — HMR-safe singleton factory using `globalThis.__synapse_singletons`.
+  Survives Next.js / Vite hot-module reloads in development. Supports `version` option
+  for cache invalidation.
+  (`import { createSingleton } from '…/utils'`)
+
+- **`client.getTransport()`** — Public accessor for the underlying `HttpTransport`,
+  replacing the `(client as any)._transport` pattern.
+
+- **`gateway.snapshot(depth?)`** — JSON-safe serialization of the entire AgentGateway
+  state with three depth levels: `'minimal'`, `'standard'`, `'full'`.
+  Also adds `gateway.toJSON()` enabling `JSON.stringify(gateway)`.
+
+- **`gateway.createPaymentIntent(opts)`** — Builder for `PaymentIntent` objects with
+  auto-generated nonce, timestamp, token. Accepts buyer as `AgentId`, string, or
+  `AgentGateway` instance.
+
+- **Retry on `gateway.execute()`** — Configurable retry with exponential backoff via
+  `RetryConfig`. Supports per-call overrides, transient error detection, and optional
+  fallback to direct RPC on the last attempt. Emits `call:retry` events.
+
+- **x402 pipeline hooks & observability** — `executeWithX402()` now emits granular
+  `x402:pipeline:*` events for each pipeline step (paywall → verify → execute → settle).
+  Accepts `onStep` callback and returns full pipeline trace with per-step timing.
+
+- **`AgentRegistry`** — Multi-agent lifecycle manager with CRUD, `filter()`,
+  `searchMarketplace()`, `getAggregateMetrics()`, `snapshot()`, pluggable persistence
+  via `PersistenceAdapter`, and `[Symbol.iterator]` support.
+
+- **`FacilitatorDiscovery`** — Runtime-aware facilitator discovery wrapping the static
+  `FACILITATOR_REGISTRY`. Adds `filter()`, `query()`, `healthCheck()`, and `findBest()`
+  with optional health-check-based selection and gas-sponsoring preference.
+
+- **Persistence module (`ai/persistence`)** — Full long-term storage layer for agent
+  gateway data:
+  - `MemoryStore` — in-process, for testing and dev
+  - `RedisPersistence` — Redis/Valkey adapter (ioredis, node-redis, @upstash/redis)
+  - `PostgresPersistence` — PostgreSQL adapter with auto-migration (pg, @vercel/postgres,
+    @neondatabase/serverless)
+  - Universal `PersistenceStore` interface covering agents, sessions, receipts, metrics,
+    and generic key-value with TTL
+  - All adapters implement `PersistenceAdapter` for drop-in use with `AgentRegistry`
+  - Helpers: `serialize()`, `deserialize()`, `buildKey()`, `buildSchema()` (DDL generator)
+  - New optional peer deps: `ioredis >=5.0.0`, `pg >=8.0.0`
+
+- **Next.js integration (`./next`)** — Drop-in helpers for App Router:
+  - `synapseResponse(data)` — BigInt-safe `Response` factory
+  - `withSynapseError(handler)` — API Route error boundary
+  - `createSynapseProvider(config)` — HMR-safe SynapseClient singleton
+  - `createGatewayProvider(clientProvider, configFactory)` — HMR-safe AgentGateway singleton
+
+### New types
+
+- `RetryConfig`, `SnapshotDepth`, `GatewaySnapshot`, `X402PipelineStep`
+- `SessionRecord`, `ReceiptRecord`, `MetricPoint`, `PersistenceStore`
+- `RedisLike`, `PgLike`, `RedisStoreConfig`, `PostgresStoreConfig`, `MemoryStoreConfig`
+- `FacilitatorHealthResult`, `FindBestOptions`, `AgentRegistryConfig`
+- `SynapseResponseInit`, `SingletonOptions`
+
+### New subpath exports
+
+- `@oobe-protocol-labs/synapse-client-sdk/next`
+- `@oobe-protocol-labs/synapse-client-sdk/ai/persistence`
+
+---
+
 ## [1.2.1] — 2025-07-22
 
 ### Fixed

package/dist/cjs/ai/gateway/index.d.ts

@@ -20,7 +20,7 @@
  * @since 1.0.0
  */
 import type { SynapseClientLike } from '../../core/client';
-import type { AgentId, AgentIdentity, GatewayConfig, GatewayEventHandler, GatewayEventType, PaymentIntent, PaymentReceipt, PricingTier, AttestedResult, ToolBundle, SessionState } from './types';
+import type { AgentId, AgentIdentity, GatewayConfig, GatewayEventHandler, GatewayEventType, PaymentIntent, PaymentReceipt, PricingTier, AttestedResult, ToolBundle, SessionState, RetryConfig, SnapshotDepth, GatewaySnapshot, X402PipelineStep } from './types';
 import { AgentSession } from './session';
 import { PricingEngine } from './pricing';
 import { ResponseValidator } from './validator';
@@ -194,13 +194,19 @@ export declare class AgentGateway {
      *  4. `session.postCall()`     — deduct budget, increment counters
      *  5. `pricing.reportLatency()`— feed latency into dynamic pricing
      *
+     * If `config.retry` is set, transient errors are retried with exponential
+     * backoff. Pass per-call `opts.retry` to override.
+     *
      * @param {string} sessionId - The session to charge
      * @param {string} method - Solana JSON-RPC method name
      * @param {unknown[]} [params=[]] - Method parameters
+     * @param {{ retry?: RetryConfig }} [opts] - Per-call overrides
      * @returns {Promise<AttestedResult<T>>} The attested result
      * @since 1.0.0
      */
-    execute<T = unknown>(sessionId: string, method: string, params?: unknown[]): Promise<AttestedResult<T>>;
+    execute<T = unknown>(sessionId: string, method: string, params?: unknown[], opts?: {
+        retry?: RetryConfig;
+    }): Promise<AttestedResult<T>>;
     /**
      * @description Execute a batch of methods within a metered session.
      * Each method is individually metered.
@@ -244,18 +250,31 @@ export declare class AgentGateway {
      * This combines processX402Request + execute + settleX402Payment
      * into a single call for convenience.
      *
+     * Emits granular `x402:pipeline:*` events for each step so consumers
+     * can build step-by-step UI animations, logging, or monitoring without
+     * reconstructing the pipeline manually.
+     *
      * @param {string | null} sessionId - Session to charge (or null for x402-only billing)
      * @param {string} method - RPC method
      * @param {unknown[]} [params=[]] - Method params
      * @param {Record<string, string | undefined>} [incomingHeaders={}] - HTTP headers with PAYMENT-SIGNATURE
-     * @returns {Promise<{ result: AttestedResult<T> | null; x402: PaywallResult; settlement: SettleResult | null; responseHeaders: Record<string, string> }>} Attested result + x402 settlement info + response headers
+     * @param {{ onStep?: (step: X402PipelineStep) => void }} [opts] - Pipeline callbacks
+     * @returns {Promise<{ result: AttestedResult<T> | null; x402: PaywallResult; settlement: SettleResult | null; responseHeaders: Record<string, string>; pipeline: { steps: X402PipelineStep[]; totalDurationMs: number } }>}
      * @since 1.0.0
      */
-    executeWithX402<T = unknown>(sessionId: string | null, method: string, params?: unknown[], incomingHeaders?: Record<string, string | undefined>): Promise<{
+    executeWithX402<T = unknown>(sessionId: string | null, method: string, params?: unknown[], incomingHeaders?: Record<string, string | undefined>, opts?: {
+        /** Callback invoked after each pipeline step completes. */
+        onStep?: (step: X402PipelineStep) => void;
+    }): Promise<{
         result: AttestedResult<T> | null;
         x402: PaywallResult;
         settlement: SettleResult | null;
         responseHeaders: Record<string, string>;
+        /** Pipeline execution trace — always populated since v1.2.2. */
+        pipeline: {
+            steps: X402PipelineStep[];
+            totalDurationMs: number;
+        };
     }>;
     /**
      * @description Execute an RPC call on a remote x402-enabled server.
@@ -346,6 +365,67 @@ export declare class AgentGateway {
             clientPayments: number;
         };
     };
+    /**
+     * @description Return a JSON-safe snapshot of the entire gateway state.
+     *
+     * All `BigInt` values are converted to strings. The result can be passed
+     * directly to `JSON.stringify()` or `NextResponse.json()` without any
+     * manual serialization.
+     *
+     * @param {{ depth?: SnapshotDepth }} [opts] - Control how much data is included.
+     *   - `'minimal'`  — identity + metrics only (for lists)
+     *   - `'standard'` — identity + metrics + sessions + tiers + marketplace (default)
+     *   - `'full'`     — everything including full session snapshots
+     * @returns {GatewaySnapshot} A plain object safe for JSON serialization.
+     * @since 1.2.2
+     *
+     * @example
+     * ```ts
+     * const snap = gateway.snapshot();
+     * return NextResponse.json(snap); // no bigIntToString() needed
+     * ```
+     */
+    snapshot(opts?: {
+        depth?: SnapshotDepth;
+    }): GatewaySnapshot;
+    /**
+     * Alias for `snapshot()` — enables `JSON.stringify(gateway)`.
+     * @since 1.2.2
+     */
+    toJSON(): GatewaySnapshot;
+    /**
+     * @description Build a {@link PaymentIntent} with sensible defaults.
+     *
+     * Generates `nonce`, `createdAt`, and `token` automatically. Accepts
+     * `budget` as a string or number that is converted to `BigInt` internally.
+     *
+     * @param {object} opts - Intent parameters
+     * @param {AgentId | string | AgentGateway} opts.buyer - Buyer agent ID, DID string, or gateway instance
+     * @param {string} [opts.tier='standard'] - Pricing tier ID
+     * @param {string | number | bigint} opts.budget - Max budget (converted to BigInt)
+     * @param {number} [opts.ttl] - TTL in seconds (default: config.sessionTtl or 3600)
+     * @param {string} [opts.signature='sdk-generated'] - Payment signature
+     * @returns {PaymentIntent} A ready-to-use PaymentIntent
+     * @since 1.2.2
+     *
+     * @example
+     * ```ts
+     * const intent = gateway.createPaymentIntent({
+     *   buyer: buyerGateway,
+     *   tier: 'standard',
+     *   budget: '100000',
+     * });
+     * const session = gateway.openSession(intent);
+     * ```
+     */
+    createPaymentIntent(opts: {
+        buyer: AgentId | string | AgentGateway;
+        tier?: string;
+        budget: string | number | bigint;
+        ttl?: number;
+        signature?: string;
+        token?: PricingTier['token'];
+    }): PaymentIntent;
     private getSessionOrThrow;
     /**
      * Basic intent verification (signature is deferred to wallet integration).
@@ -370,11 +450,12 @@ export declare class AgentGateway {
  * @since 1.0.0
  */
 export declare function createAgentGateway(client: SynapseClientLike, config: GatewayConfig): AgentGateway;
-export type { AgentId, AgentIdentity, AgentCredential, PaymentToken, PricingTier, PaymentIntent, PaymentReceipt, SessionState, SessionStatus, ResponseAttestation, AttestedResult, ToolListing, ToolBundle, GatewayEventType, GatewayEvent, GatewayEventHandler, GatewayConfig, } from './types';
+export type { AgentId, AgentIdentity, AgentCredential, PaymentToken, PricingTier, PaymentIntent, PaymentReceipt, SessionState, SessionStatus, ResponseAttestation, AttestedResult, ToolListing, ToolBundle, GatewayEventType, GatewayEvent, GatewayEventHandler, GatewayConfig, RetryConfig, SnapshotDepth, GatewaySnapshot, X402PipelineStep, } from './types';
 export { AgentId as createAgentId } from './types';
 export { AgentSession, SessionError, BudgetExhaustedError, RateLimitExceededError, SessionExpiredError, CallLimitExceededError, } from './session';
 export { PricingEngine, DEFAULT_TIERS, type DynamicPricingConfig } from './pricing';
 export { ResponseValidator } from './validator';
 export { ToolMarketplace, type MarketplaceQuery, type MarketplaceStats } from './marketplace';
+export { AgentRegistry, MemoryAdapter, type PersistenceAdapter, type AgentRegistryConfig, } from './registry';
 export * from './x402';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/ai/gateway/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ai/gateway/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ai/gateway/index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/ai/gateway/index.js

@@ -57,7 +57,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolMarketplace = exports.ResponseValidator = exports.DEFAULT_TIERS = exports.PricingEngine = exports.CallLimitExceededError = exports.SessionExpiredError = exports.RateLimitExceededError = exports.BudgetExhaustedError = exports.SessionError = exports.AgentSession = exports.createAgentId = exports.AgentGateway = exports.IntentVerificationError = exports.MaxSessionsError = exports.SessionNotFoundError = exports.GatewayError = void 0;
+exports.MemoryAdapter = exports.AgentRegistry = exports.ToolMarketplace = exports.ResponseValidator = exports.DEFAULT_TIERS = exports.PricingEngine = exports.CallLimitExceededError = exports.SessionExpiredError = exports.RateLimitExceededError = exports.BudgetExhaustedError = exports.SessionError = exports.AgentSession = exports.createAgentId = exports.AgentGateway = exports.IntentVerificationError = exports.MaxSessionsError = exports.SessionNotFoundError = exports.GatewayError = void 0;
 exports.createAgentGateway = createAgentGateway;
 const crypto_1 = require("crypto");
 const session_1 = require("./session");
@@ -343,52 +343,88 @@ class AgentGateway {
      *  4. `session.postCall()`     — deduct budget, increment counters
      *  5. `pricing.reportLatency()`— feed latency into dynamic pricing
      *
+     * If `config.retry` is set, transient errors are retried with exponential
+     * backoff. Pass per-call `opts.retry` to override.
+     *
      * @param {string} sessionId - The session to charge
      * @param {string} method - Solana JSON-RPC method name
      * @param {unknown[]} [params=[]] - Method parameters
+     * @param {{ retry?: RetryConfig }} [opts] - Per-call overrides
      * @returns {Promise<AttestedResult<T>>} The attested result
      * @since 1.0.0
      */
-    async execute(sessionId, method, params = []) {
+    async execute(sessionId, method, params = [], opts = {}) {
         const session = this.getSessionOrThrow(sessionId);
         const snap = session.snapshot();
         // ── Pre-flight
         this.emit('call:before', { method, params }, sessionId);
         const cost = session.preCall(method);
-        // ── Execute
-        const start = performance.now();
-        let result;
-        try {
-            result = await this.transport.request(method, params);
-        }
-        catch (err) {
-            this.emit('call:error', { method, error: String(err) }, sessionId);
-            throw err;
-        }
-        const latencyMs = Math.round(performance.now() - start);
-        // ── Attest
-        const shouldAttest = snap.tier.includesAttestation ||
-            (this.config.attestByDefault ?? false);
-        // Get slot from the response context if available, otherwise 0
-        const slot = typeof result === 'object' && result !== null && 'context' in result
-            ? result.context?.slot ?? 0
-            : 0;
-        const attested = await this.validator.wrapResult(result, sessionId, method, params, slot, latencyMs, snap.callsMade + 1, shouldAttest);
-        // ── Post-call
-        session.postCall(method, cost);
-        this.totalCallsServed++;
-        // ── Feed latency into pricing engine
-        this.pricing.reportLatency(latencyMs);
-        this.emit('call:after', {
-            method,
-            latencyMs,
-            cost: cost.toString(),
-            attested: shouldAttest,
-        }, sessionId);
-        if (shouldAttest && attested.attestation) {
-            this.emit('call:attested', { attestation: attested.attestation }, sessionId);
+        // ── Retry config (per-call > gateway-level > none)
+        const retryCfg = opts.retry ?? this.config.retry;
+        const maxAttempts = retryCfg?.maxAttempts ?? 1;
+        const backoffMs = retryCfg?.backoffMs ?? 500;
+        const backoffMul = retryCfg?.backoffMultiplier ?? 2;
+        const retryableErrors = retryCfg?.retryableErrors ?? [
+            'fetch failed', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'socket hang up',
+        ];
+        const fallback = retryCfg?.fallbackToDirectRpc ?? false;
+        let lastErr;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const start = performance.now();
+            try {
+                const result = await this.transport.request(method, params);
+                const latencyMs = Math.round(performance.now() - start);
+                // ── Attest
+                const shouldAttest = snap.tier.includesAttestation ||
+                    (this.config.attestByDefault ?? false);
+                const slot = typeof result === 'object' && result !== null && 'context' in result
+                    ? result.context?.slot ?? 0
+                    : 0;
+                const attested = await this.validator.wrapResult(result, sessionId, method, params, slot, latencyMs, snap.callsMade + 1, shouldAttest);
+                // ── Post-call
+                session.postCall(method, cost);
+                this.totalCallsServed++;
+                this.pricing.reportLatency(latencyMs);
+                this.emit('call:after', {
+                    method, latencyMs, cost: cost.toString(), attested: shouldAttest, attempt,
+                }, sessionId);
+                if (shouldAttest && attested.attestation) {
+                    this.emit('call:attested', { attestation: attested.attestation }, sessionId);
+                }
+                return attested;
+            }
+            catch (err) {
+                lastErr = err;
+                const errMsg = String(err);
+                const isRetryable = retryableErrors.some(s => errMsg.includes(s));
+                if (attempt < maxAttempts && isRetryable) {
+                    const delay = backoffMs * (backoffMul ** (attempt - 1));
+                    this.emit('call:retry', {
+                        method, attempt, maxAttempts, error: errMsg, delayMs: delay,
+                    }, sessionId);
+                    await new Promise(r => setTimeout(r, delay));
+                    continue;
+                }
+                // ── Fallback to raw RPC on last attempt
+                if (fallback && attempt === maxAttempts) {
+                    try {
+                        const fbStart = performance.now();
+                        const fbResult = await this.transport.request(method, params);
+                        const fbLatency = Math.round(performance.now() - fbStart);
+                        const attested = await this.validator.wrapResult(fbResult, sessionId, method, params, 0, fbLatency, snap.callsMade + 1, false);
+                        session.postCall(method, cost);
+                        this.totalCallsServed++;
+                        this.pricing.reportLatency(fbLatency);
+                        return attested;
+                    }
+                    catch {
+                        // fallback also failed — throw original error
+                    }
+                }
+            }
         }
-        return attested;
+        this.emit('call:error', { method, error: String(lastErr) }, sessionId);
+        throw lastErr;
     }
     /**
      * @description Execute a batch of methods within a metered session.
@@ -469,32 +505,62 @@ class AgentGateway {
      * This combines processX402Request + execute + settleX402Payment
      * into a single call for convenience.
      *
+     * Emits granular `x402:pipeline:*` events for each step so consumers
+     * can build step-by-step UI animations, logging, or monitoring without
+     * reconstructing the pipeline manually.
+     *
      * @param {string | null} sessionId - Session to charge (or null for x402-only billing)
      * @param {string} method - RPC method
      * @param {unknown[]} [params=[]] - Method params
      * @param {Record<string, string | undefined>} [incomingHeaders={}] - HTTP headers with PAYMENT-SIGNATURE
-     * @returns {Promise<{ result: AttestedResult<T> | null; x402: PaywallResult; settlement: SettleResult | null; responseHeaders: Record<string, string> }>} Attested result + x402 settlement info + response headers
+     * @param {{ onStep?: (step: X402PipelineStep) => void }} [opts] - Pipeline callbacks
+     * @returns {Promise<{ result: AttestedResult<T> | null; x402: PaywallResult; settlement: SettleResult | null; responseHeaders: Record<string, string>; pipeline: { steps: X402PipelineStep[]; totalDurationMs: number } }>}
      * @since 1.0.0
      */
-    async executeWithX402(sessionId, method, params = [], incomingHeaders = {}) {
+    async executeWithX402(sessionId, method, params = [], incomingHeaders = {}, opts = {}) {
+        const pipelineStart = performance.now();
+        const steps = [];
+        let stepId = 0;
+        const pushStep = (step) => {
+            const s = { ...step, id: ++stepId, totalSteps: 0 };
+            steps.push(s);
+            this.emit(`x402:pipeline:${step.actor === 'facilitator' ? 'verify' : step.action.toLowerCase().includes('paywall') ? 'paywall' : step.action.toLowerCase().includes('settle') ? 'settle' : 'execute'}`, s, sessionId ?? '');
+            opts.onStep?.(s);
+        };
         // ── Step 1: x402 paywall check
+        let t = performance.now();
         const x402Result = await this.processX402Request(method, incomingHeaders);
+        pushStep({
+            actor: 'seller',
+            action: `Paywall → ${x402Result.type}`,
+            detail: x402Result.type === 'payment-required'
+                ? 'Payment required — returning 402'
+                : x402Result.type === 'payment-valid'
+                    ? 'Payment verified — proceeding'
+                    : 'No payment needed',
+            data: { type: x402Result.type, method },
+            durationMs: Math.round(performance.now() - t),
+            status: 'real',
+        });
         if (x402Result.type === 'payment-required') {
+            // Finalize totalSteps
+            for (const s of steps)
+                s.totalSteps = stepId;
             return {
                 result: null,
                 x402: x402Result,
                 settlement: null,
                 responseHeaders: x402Result.headers,
+                pipeline: { steps, totalDurationMs: Math.round(performance.now() - pipelineStart) },
             };
         }
         // ── Step 2: Execute the RPC call
+        t = performance.now();
         let attested;
         if (sessionId) {
-            // Metered execution within a session
             attested = await this.execute(sessionId, method, params);
         }
         else {
-            // Direct execution (x402-only billing, no session metering)
             const start = performance.now();
             const result = await this.transport.request(method, params);
             const latencyMs = Math.round(performance.now() - start);
@@ -502,16 +568,43 @@ class AgentGateway {
             this.totalCallsServed++;
             this.pricing.reportLatency(latencyMs);
         }
+        pushStep({
+            actor: 'seller',
+            action: `Execute ${method}`,
+            detail: `RPC call completed in ${attested.latencyMs}ms`,
+            data: { method, latencyMs: attested.latencyMs, hasAttestation: !!attested.attestation },
+            durationMs: Math.round(performance.now() - t),
+            status: 'real',
+        });
         // ── Step 3: Settle (if x402 payment was provided)
         let settlement = null;
         const responseHeaders = {};
         if (x402Result.type === 'payment-valid') {
+            t = performance.now();
             settlement = await this.settleX402Payment(x402Result.paymentPayload, x402Result.requirements);
             if (settlement.responseHeader) {
                 responseHeaders['PAYMENT-RESPONSE'] = settlement.responseHeader;
             }
+            pushStep({
+                actor: 'facilitator',
+                action: 'Settle payment',
+                detail: settlement.success ? 'Payment settled on-chain' : 'Settlement failed',
+                data: {
+                    success: settlement.success,
+                    transaction: settlement.settleResponse?.transaction,
+                },
+                durationMs: Math.round(performance.now() - t),
+                status: 'real',
+            });
         }
-        return { result: attested, x402: x402Result, settlement, responseHeaders };
+        // Finalize totalSteps
+        for (const s of steps)
+            s.totalSteps = stepId;
+        const totalDurationMs = Math.round(performance.now() - pipelineStart);
+        this.emit('x402:pipeline:complete', {
+            steps, totalDurationMs, method, sessionId,
+        }, sessionId ?? '');
+        return { result: attested, x402: x402Result, settlement, responseHeaders, pipeline: { steps, totalDurationMs } };
     }
     /* ═══════════════════════════════════════════════════════════
      *  x402 Protocol — Buyer Side (Client)
@@ -727,6 +820,147 @@ class AgentGateway {
             },
         };
     }
+    /* ═══════════════════════════════════════════════════════════
+     *  Snapshot — JSON-safe serialization
+     * ═══════════════════════════════════════════════════════════ */
+    /**
+     * @description Return a JSON-safe snapshot of the entire gateway state.
+     *
+     * All `BigInt` values are converted to strings. The result can be passed
+     * directly to `JSON.stringify()` or `NextResponse.json()` without any
+     * manual serialization.
+     *
+     * @param {{ depth?: SnapshotDepth }} [opts] - Control how much data is included.
+     *   - `'minimal'`  — identity + metrics only (for lists)
+     *   - `'standard'` — identity + metrics + sessions + tiers + marketplace (default)
+     *   - `'full'`     — everything including full session snapshots
+     * @returns {GatewaySnapshot} A plain object safe for JSON serialization.
+     * @since 1.2.2
+     *
+     * @example
+     * ```ts
+     * const snap = gateway.snapshot();
+     * return NextResponse.json(snap); // no bigIntToString() needed
+     * ```
+     */
+    snapshot(opts = {}) {
+        const depth = opts.depth ?? 'standard';
+        const identity = this.config.identity;
+        const result = {
+            agentId: this.agentId,
+            identity: {
+                name: identity.name,
+                walletPubkey: identity.walletPubkey,
+                description: identity.description,
+                tags: identity.tags,
+                createdAt: identity.createdAt,
+            },
+            metrics: {
+                totalCallsServed: this.totalCallsServed,
+                totalRevenue: this.totalRevenue.toString(),
+                activeSessions: [...this.sessions.values()].filter(s => s.status === 'active').length,
+                totalSessions: this.sessions.size,
+                avgLatencyMs: this.pricing.getAvgLatency(),
+                totalAttestations: this.validator.totalAttestations,
+            },
+            sessions: [],
+            tiers: [],
+            marketplace: { totalListings: 0, totalBundles: 0 },
+            x402: {
+                paywallEnabled: this.paywall !== null,
+                clientEnabled: this.x402Client !== null,
+                clientPayments: this.x402Client?.payments ?? 0,
+            },
+        };
+        if (depth === 'minimal')
+            return result;
+        // Sessions
+        for (const session of this.sessions.values()) {
+            const snap = session.snapshot();
+            const entry = {
+                id: snap.id,
+                status: snap.status,
+                buyer: snap.buyer,
+            };
+            if (depth === 'full') {
+                entry.budgetRemaining = snap.budgetRemaining.toString();
+                entry.callsMade = snap.callsMade;
+                entry.createdAt = snap.createdAt;
+            }
+            result.sessions.push(entry);
+        }
+        // Tiers
+        for (const tier of this.config.defaultTiers) {
+            result.tiers.push({
+                id: tier.id,
+                label: tier.label,
+                pricePerCall: tier.pricePerCall.toString(),
+                maxCallsPerSession: tier.maxCallsPerSession,
+                rateLimit: tier.rateLimit,
+                includesAttestation: tier.includesAttestation,
+            });
+        }
+        // Marketplace
+        const mpStats = this.marketplace.getStats();
+        result.marketplace = {
+            totalListings: mpStats.totalListings,
+            totalBundles: mpStats.totalBundles,
+        };
+        return result;
+    }
+    /**
+     * Alias for `snapshot()` — enables `JSON.stringify(gateway)`.
+     * @since 1.2.2
+     */
+    toJSON() {
+        return this.snapshot({ depth: 'standard' });
+    }
+    /* ═══════════════════════════════════════════════════════════
+     *  PaymentIntent builder
+     * ═══════════════════════════════════════════════════════════ */
+    /**
+     * @description Build a {@link PaymentIntent} with sensible defaults.
+     *
+     * Generates `nonce`, `createdAt`, and `token` automatically. Accepts
+     * `budget` as a string or number that is converted to `BigInt` internally.
+     *
+     * @param {object} opts - Intent parameters
+     * @param {AgentId | string | AgentGateway} opts.buyer - Buyer agent ID, DID string, or gateway instance
+     * @param {string} [opts.tier='standard'] - Pricing tier ID
+     * @param {string | number | bigint} opts.budget - Max budget (converted to BigInt)
+     * @param {number} [opts.ttl] - TTL in seconds (default: config.sessionTtl or 3600)
+     * @param {string} [opts.signature='sdk-generated'] - Payment signature
+     * @returns {PaymentIntent} A ready-to-use PaymentIntent
+     * @since 1.2.2
+     *
+     * @example
+     * ```ts
+     * const intent = gateway.createPaymentIntent({
+     *   buyer: buyerGateway,
+     *   tier: 'standard',
+     *   budget: '100000',
+     * });
+     * const session = gateway.openSession(intent);
+     * ```
+     */
+    createPaymentIntent(opts) {
+        const buyerId = opts.buyer instanceof AgentGateway
+            ? opts.buyer.agentId
+            : opts.buyer;
+        const tierId = opts.tier ?? 'standard';
+        const tier = this.pricing.getTier(tierId);
+        return {
+            nonce: (0, crypto_1.randomUUID)(),
+            buyer: buyerId,
+            seller: this.agentId,
+            tierId,
+            maxBudget: BigInt(opts.budget),
+            token: opts.token ?? tier?.token ?? { type: 'USDC' },
+            signature: opts.signature ?? 'sdk-generated',
+            createdAt: Date.now(),
+            ttl: opts.ttl ?? this.config.sessionTtl ?? 3600,
+        };
+    }
     /* ═══════════════════════════════════════════════════════════
      *  Internals
      * ═══════════════════════════════════════════════════════════ */
@@ -795,6 +1029,10 @@ var validator_2 = require("./validator");
 Object.defineProperty(exports, "ResponseValidator", { enumerable: true, get: function () { return validator_2.ResponseValidator; } });
 var marketplace_2 = require("./marketplace");
 Object.defineProperty(exports, "ToolMarketplace", { enumerable: true, get: function () { return marketplace_2.ToolMarketplace; } });
+/* ── Agent Registry ────────────────────────────────────────── */
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "AgentRegistry", { enumerable: true, get: function () { return registry_1.AgentRegistry; } });
+Object.defineProperty(exports, "MemoryAdapter", { enumerable: true, get: function () { return registry_1.MemoryAdapter; } });
 /* ── x402 Protocol ─────────────────────────────────────────── */
 __exportStar(require("./x402"), exports);
 //# sourceMappingURL=index.js.map