@tangle-network/agent-gateway 0.7.1 → 0.8.1

package/dist/{types-DEsMmS-X.d.ts → types-oQ58UakD.d.ts}

@@ -1,5 +1,6 @@
 import { NonceStore } from './nonce-store.js';
 import { RateLimitStore } from './rate-limit.js';
+import { S as SandboxUsageReceipt, b as PaymentSettlementBasis, P as PaymentMethod, c as SandboxExecutionBudget, a as GatewayUsageEvent, G as GatewayObserver } from './observer-types-A0RtA8uL.js';
 
 /**
  * A2A protocol types (Google Agent-to-Agent, April 2025).
@@ -51,6 +52,7 @@ declare const A2A_ERROR_CODES: {
     readonly CONTENT_TYPE_NOT_SUPPORTED: -32005;
     readonly INVALID_AGENT_RESPONSE: -32006;
     readonly AUTHENTICATED_EXTENDED_CARD_NOT_CONFIGURED: -32007;
+    readonly TASK_ACCESS_DENIED: -32008;
 };
 interface TextPart {
     kind: 'text';
@@ -193,6 +195,12 @@ interface AgentCard {
 interface TaskStore {
     get(id: string): Promise<Task | undefined>;
     put(task: Task): Promise<void>;
+    /** Insert only when the task id is absent. Required outside explicit demo mode. */
+    createIfAbsent?(task: Task): Promise<boolean>;
+    /** Replace only when the stored task still equals `expected`. Required for production races. */
+    compareAndSet?(expected: Task, next: Task): Promise<boolean>;
+    /** Replace an execution marker only while its owner lease is still live. */
+    compareAndSetExecution?(expected: Task, next: Task, requestId: string, now: number): Promise<boolean>;
     delete(id: string): Promise<void>;
 }
 declare class InMemoryTaskStore implements TaskStore {
@@ -201,6 +209,9 @@ declare class InMemoryTaskStore implements TaskStore {
     constructor(ttlMs?: number);
     get(id: string): Promise<Task | undefined>;
     put(task: Task): Promise<void>;
+    createIfAbsent(task: Task): Promise<boolean>;
+    compareAndSet(expected: Task, next: Task): Promise<boolean>;
+    compareAndSetExecution(expected: Task, next: Task, requestId: string, now: number): Promise<boolean>;
     delete(id: string): Promise<void>;
     /**
      * Sweep expired tasks. Called inline on every read/write — cheap for the
@@ -220,9 +231,8 @@ declare class InMemoryTaskStore implements TaskStore {
  * Schema is one table: tasks keyed by id with the full JSON payload, plus a
  * secondary index on `context_id` so `tasks/resubscribe` and conversational
  * lookups by context are O(log n). TTL is enforced at read time the same way
- * `InMemoryTaskStore` does — the gateway is single-writer per task id so a
- * stale row is invisible to callers regardless of when the row is physically
- * deleted.
+ * `InMemoryTaskStore` does — `createIfAbsent` and `compareAndSet` make task
+ * ownership safe when multiple gateway workers share the database.
  *
  * Why not bake in a specific driver? Hono workers run on Cloudflare (D1),
  * Node (pg / sqlite), Bun, Deno. Burning a hard dependency on one client
@@ -295,10 +305,17 @@ declare class SqlTaskStore implements TaskStore {
     });
     private get ttlMs();
     private get table();
+    private readRow;
+    private isExpired;
+    private deleteObservedRow;
     /** Idempotent. Call once at deploy. */
     migrate(): Promise<void>;
     get(id: string): Promise<Task | undefined>;
+    private insert;
     put(task: Task): Promise<void>;
+    createIfAbsent(task: Task): Promise<boolean>;
+    compareAndSet(expected: Task, next: Task): Promise<boolean>;
+    compareAndSetExecution(expected: Task, next: Task, requestId: string, now: number): Promise<boolean>;
     delete(id: string): Promise<void>;
     /**
      * Lookup tasks by contextId — used by `tasks/resubscribe` and the multi-turn
@@ -394,6 +411,14 @@ interface PushNotificationStore {
     list(taskId: string): Promise<PushNotificationConfig[]>;
     delete(taskId: string, configId: string): Promise<void>;
 }
+/**
+ * Validate a push destination before the gateway sends task data to it.
+ *
+ * The default policy rejects URL credentials, non-HTTPS schemes, IP literals
+ * in reserved ranges, and common private hostnames. Production deployments
+ * should also provide `GatewayConfig.a2a.pushUrlValidator` for DNS policy.
+ */
+declare function validatePushNotificationUrl(value: string): URL | undefined;
 declare class InMemoryPushNotificationStore implements PushNotificationStore {
     private readonly byTask;
     set(taskId: string, config: PushNotificationConfig): Promise<void>;
@@ -412,24 +437,37 @@ declare class SqlPushNotificationStore implements PushNotificationStore {
     list(taskId: string): Promise<PushNotificationConfig[]>;
     delete(taskId: string, configId: string): Promise<void>;
 }
-/**
- * Send the webhook for each registered config on a task. Signs the body with
- * HMAC-SHA256 against `webhookSecret` so the consumer can verify authenticity.
- * Fire-and-forget per the design note above — the function awaits delivery
- * (so observability hooks see the result) but does not retry on failure.
- *
- * The caller decides *when* to deliver — typically on terminal-state
- * transitions emitted from `message/send` and `message/stream`.
- */
-declare function deliverPushNotifications(args: {
+interface PushDeliveryOptions {
     task: Task;
     store: PushNotificationStore;
-    webhookSecret: string | undefined;
+    webhookSecret?: string;
+    /** Atomically claim one terminal delivery before its external side effect. */
+    claimDelivery?: (taskId: string, configId: string, terminalState: Task['status']['state']) => Promise<boolean>;
     /** Inject for tests. Defaults to global `fetch`. */
     fetcher?: typeof fetch;
+    /** Optional DNS-aware host policy for production deployments. */
+    urlValidator?: (url: URL) => boolean | Promise<boolean>;
+    /** Require `urlValidator` before sending from a production gateway. */
+    requireUrlValidator?: boolean;
     /** Optional callback so the gateway's observer can log delivery outcomes. */
     onDelivery?: (result: PushDeliveryResult) => void;
-}): Promise<PushDeliveryResult[]>;
+}
+type PushNotificationDeliveryOptions = Omit<PushDeliveryOptions, 'webhookSecret'> & {
+    webhookSecret: string;
+};
+/**
+ * Send signed webhooks for a terminal task.
+ *
+ * A non-empty HMAC secret is mandatory. This public production path cannot
+ * send an unsigned request.
+ */
+declare function deliverPushNotifications(args: PushNotificationDeliveryOptions): Promise<PushDeliveryResult[]>;
+/**
+ * Deliver unsigned webhooks only for explicit local demo mode.
+ *
+ * Production callers must use `deliverPushNotifications`.
+ */
+declare function deliverDemoPushNotifications(args: Omit<PushNotificationDeliveryOptions, 'webhookSecret'>): Promise<PushDeliveryResult[]>;
 interface PushDeliveryResult {
     taskId: string;
     configId: string;
@@ -439,133 +477,270 @@ interface PushDeliveryResult {
     error?: string;
 }
 
+/** Version negotiated by gateways that use durable payment operations. */
+declare const PAYMENT_PROTOCOL_VERSION: 2;
+type PaymentOperationState = 'claiming' | 'claimed' | 'executing' | 'retained' | 'settling' | 'settled' | 'releasing' | 'released' | 'reclaimable' | 'reclaimed';
+/** Fenced result for a recovery lookup that found no provider operation. */
+interface PaymentOperationNotFound {
+    protocolVersion: typeof PAYMENT_PROTOCOL_VERSION;
+    operationId: string;
+    state: 'not-found';
+}
+type PaymentOperationRecoveryResult = PaymentOperation | PaymentOperationNotFound;
+/** Durable ownership of one signed payment authorization. */
+interface PaymentOperation {
+    protocolVersion: typeof PAYMENT_PROTOCOL_VERSION;
+    operationId: string;
+    /** Request that atomically created this operation. Idempotent reads retain the original value. */
+    acquiredByRequestId: string;
+    executionStartedAt?: number;
+    retentionReason?: string;
+    nonceKey: string;
+    authorizationId: string;
+    reservedAmount: bigint;
+    settledAmount: bigint;
+    refundAmount: bigint;
+    expiresAt: number;
+    state: PaymentOperationState;
+}
+interface PaymentAuthorizationContext {
+    requestId: string;
+    agentId: string;
+    requiredAmount: bigint;
+    maxOutputTokens: number;
+    executionBudget: {
+        maxInputTokens: number;
+        maxOutputTokens: number;
+        maxReasoningTokens: number;
+        maxToolTokens: number;
+        maxToolCalls: number;
+        maxProviderCostUsd: number;
+    };
+}
+interface PaymentSettlementInput {
+    amount: bigint;
+    totalCostUsd: number;
+    usage: SandboxUsageReceipt;
+    /** Distinguishes a provider receipt from the bounded missing-receipt fallback. */
+    basis: PaymentSettlementBasis;
+}
 /**
- * Observability hook surface.
- *
- * Consumers implement GatewayObserver to wire the gateway into their existing
- * telemetry stack (Langfuse, OTEL, structured logs, Prometheus, etc.) without
- * the gateway itself depending on any of those libraries.
- *
- * Every event carries a requestId so downstream metrics can correlate the
- * payment verification, sandbox execution, and settlement for one request.
- * When no observer is configured, the gateway stays silent.
+ * One payment lifecycle shared by every payment-backed gateway surface.
+ * Implementations must persist the operation before external side effects.
  */
+interface PaymentOperations {
+    readonly protocolVersion: typeof PAYMENT_PROTOCOL_VERSION;
+    claimPayment(payload: Record<string, unknown>, context: PaymentAuthorizationContext): Promise<PaymentOperation>;
+    /** Prevent expiry reclaim while the sandbox can consume provider resources. */
+    beginPaymentExecution(operation: PaymentOperation): Promise<PaymentOperation>;
+    /** Preserve funds after work when the final usage receipt is still missing. */
+    retainPayment(operation: PaymentOperation, reason: string): Promise<PaymentOperation>;
+    settlePayment(operation: PaymentOperation, input: PaymentSettlementInput): Promise<PaymentOperation>;
+    /**
+     * Read the authoritative durable operation without changing its state.
+     * Recovery uses this to avoid repeating a provider settlement after the
+     * provider committed but the task finalization write lost its acknowledgement.
+     */
+    getPaymentOperation(operationId: string): Promise<PaymentOperationRecoveryResult>;
+    /**
+     * Release an unused authorization.
+     * Repeated calls must recover an ambiguous acknowledgement by operationId.
+     */
+    releasePayment(operation: PaymentOperation, reason: string): Promise<PaymentOperation>;
+    reclaimPayment(operationId: string): Promise<PaymentOperationRecoveryResult>;
+}
+interface MemoryPaymentOperationsOptions {
+    now?: () => number;
+    onClaim?: (operation: PaymentOperation) => Promise<void>;
+    onSettle?: (operation: PaymentOperation, input: PaymentSettlementInput) => Promise<void>;
+    onRelease?: (operation: PaymentOperation, reason: string) => Promise<void>;
+    onReclaim?: (operation: PaymentOperation) => Promise<void>;
+}
+/** Small atomic implementation used by single-process deployments and tests. */
+declare class MemoryPaymentOperations implements PaymentOperations {
+    private readonly options;
+    readonly protocolVersion: 2;
+    private readonly operations;
+    private readonly claimFlights;
+    private readonly claimTokens;
+    private readonly settleFlights;
+    private readonly releaseFlights;
+    private readonly reclaimFlights;
+    private readonly now;
+    constructor(options?: MemoryPaymentOperationsOptions);
+    claimPayment(payload: Record<string, unknown>, context: PaymentAuthorizationContext): Promise<PaymentOperation>;
+    settlePayment(operation: PaymentOperation, input: PaymentSettlementInput): Promise<PaymentOperation>;
+    beginPaymentExecution(operation: PaymentOperation): Promise<PaymentOperation>;
+    retainPayment(operation: PaymentOperation, reason: string): Promise<PaymentOperation>;
+    releasePayment(operation: PaymentOperation, reason: string): Promise<PaymentOperation>;
+    reclaimPayment(operationId: string): Promise<PaymentOperationRecoveryResult>;
+    private runSettlement;
+    private recoverSettlement;
+    private runReclaim;
+    private runRelease;
+    get(operationId: string): PaymentOperation | undefined;
+    getPaymentOperation(operationId: string): Promise<PaymentOperationRecoveryResult>;
+    private requireCurrent;
+}
 
-interface RequestContext {
-    requestId: string;
-    agentSlug: string;
-    startMs: number;
+/** Version of the gateway's method-specific MPP charge contract. */
+declare const MPP_CHARGE_PROTOCOL_VERSION: 1;
+type MppChargeOperationState = 'confirmed' | 'releasing' | 'released';
+/** Pure authentication result for one method credential. */
+interface MppAuthenticatedCredential {
+    consumerId: string;
+    /**
+     * Stable, non-secret processor identity for this payment credential.
+     * Return the same value for equivalent encodings of one credential.
+     * The gateway hashes this value before it persists or claims it.
+     */
+    paymentIdentity: string;
 }
-interface AuthFailureReason {
-    method: 'x402' | 'mpp' | 'apikey' | 'none';
-    code: string;
-    httpStatus: number;
+/** Durable result of one immediate MPP charge. */
+interface MppChargeOperation {
+    protocolVersion: typeof MPP_CHARGE_PROTOCOL_VERSION;
+    operationId: string;
+    acquiredByRequestId: string;
+    method: string;
+    /** A complete Payment-Receipt header value. */
+    receipt: string;
+    state: MppChargeOperationState;
 }
-interface GatewayObserver {
-    /** Called at the start of every chat completions POST. */
-    onRequestStart?: (ctx: RequestContext) => void | Promise<void>;
-    /** Called when a payment method has been successfully verified. */
-    onPaymentVerified?: (ctx: RequestContext, info: {
-        method: PaymentMethod;
-        consumerId: string;
-        keyId?: string;
-    }) => void | Promise<void>;
-    /** Called when auth fails — every branch. */
-    onAuthFailure?: (ctx: RequestContext, reason: AuthFailureReason) => void | Promise<void>;
-    /** Called when a consumer hits the rate limit. */
-    onRateLimited?: (ctx: RequestContext, info: {
-        consumerId: string;
-        retryAfterSeconds: number;
-    }) => void | Promise<void>;
-    /** Called when the request body exceeds the 64KB limit. */
-    onBodyTooLarge?: (ctx: RequestContext, contentLength: number) => void | Promise<void>;
+interface MppChargeRequest {
     /**
-     * Called when prompt-injection patterns are detected.
-     * `blocked` is true when blockInjection config is on and the request was
-     * rejected; false when the patterns were logged but the request proceeded.
+     * Stable provider idempotency key. The adapter must bind every processor
+     * operation to this value before it attempts confirmation.
      */
-    onInjectionDetected?: (ctx: RequestContext, info: {
-        consumerId: string;
-        patterns: string[];
-        blocked: boolean;
-    }) => void | Promise<void>;
-    /** Called after a successful stream completes and recordUsage has fired. */
-    onRequestComplete?: (ctx: RequestContext, usage: GatewayUsageEvent) => void | Promise<void>;
-    /** Called when the sandbox throws. The error message is pre-scrubbed. */
-    onStreamError?: (ctx: RequestContext, info: {
-        consumerId: string;
-        errorMessage: string;
-    }) => void | Promise<void>;
-    /** Called when settlement fails. Payment already occurred; this is async bookkeeping. */
-    onSettlementError?: (ctx: RequestContext, info: {
-        consumerId: string;
-        method: PaymentMethod;
-        errorMessage: string;
-    }) => void | Promise<void>;
+    operationId: string;
+    requestId: string;
+    agentId: string;
+    consumerId: string;
+    method: string;
+    /** Original decoded credential. It is available only on the live request. */
+    credential: string;
+    amount: bigint;
+    currencyDecimals: number;
 }
+type MppChargeRecoveryResult = MppChargeOperation
+/** `not-found` is final and must fence this operation ID against a later charge. */
+ | {
+    operationId: string;
+    state: 'not-found' | 'pending';
+};
 /**
- * Structured-log observer. Emits one JSON line per event on the `log` function.
- * Default sink: console.log. Production consumers usually pipe their own
- * structured logger (pino, winston, the cf Logs binding).
+ * Immediate-charge lifecycle for a non-BlueprinTEVM MPP method.
+ *
+ * `confirmPayment` runs after every request denial and before a response or
+ * sandbox call. It must use `operationId` as its processor idempotency key,
+ * confirm payment, verify final success, and only then return `confirmed`.
  *
- * Usage:
- *   new ConsoleObserver(({ level, event, ...rest }) => logger.info({ event, ...rest }))
+ * Every method must also support id-only recovery and an idempotent release.
+ * Recovery must inspect the existing processor operation. It must never
+ * create a second charge when an acknowledgement is ambiguous.
  */
-declare class ConsoleObserver implements GatewayObserver {
-    private readonly log;
-    constructor(log?: (entry: Record<string, unknown>) => void);
-    private emit;
-    onRequestStart(ctx: RequestContext): void;
-    onPaymentVerified(ctx: RequestContext, info: {
-        method: PaymentMethod;
-        consumerId: string;
-        keyId?: string;
-    }): void;
-    onAuthFailure(ctx: RequestContext, reason: AuthFailureReason): void;
-    onRateLimited(ctx: RequestContext, info: {
-        consumerId: string;
-        retryAfterSeconds: number;
-    }): void;
-    onBodyTooLarge(ctx: RequestContext, contentLength: number): void;
-    onInjectionDetected(ctx: RequestContext, info: {
-        consumerId: string;
-        patterns: string[];
-        blocked: boolean;
-    }): void;
-    onRequestComplete(ctx: RequestContext, usage: GatewayUsageEvent): void;
-    onStreamError(ctx: RequestContext, info: {
-        consumerId: string;
-        errorMessage: string;
-    }): void;
-    onSettlementError(ctx: RequestContext, info: {
-        consumerId: string;
-        method: PaymentMethod;
-        errorMessage: string;
-    }): void;
+interface MppChargeLifecycle {
+    readonly protocolVersion: typeof MPP_CHARGE_PROTOCOL_VERSION;
+    confirmPayment(request: MppChargeRequest): Promise<MppChargeOperation>;
+    releasePayment(operation: MppChargeOperation, reason: string): Promise<MppChargeOperation>;
+    recoverPayment(operationId: string): Promise<MppChargeRecoveryResult>;
 }
-/**
- * Compose multiple observers into one. Errors in any individual observer
- * don't break the others (fire-and-forget telemetry).
- */
-declare class CompositeObserver implements GatewayObserver {
-    private readonly observers;
-    constructor(observers: GatewayObserver[]);
-    private fanOut;
-    onRequestStart: (ctx: RequestContext) => Promise<void>;
-    onPaymentVerified: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onPaymentVerified"]>[1]) => Promise<void>;
-    onAuthFailure: (ctx: RequestContext, reason: AuthFailureReason) => Promise<void>;
-    onRateLimited: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onRateLimited"]>[1]) => Promise<void>;
-    onBodyTooLarge: (ctx: RequestContext, contentLength: number) => Promise<void>;
-    onInjectionDetected: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onInjectionDetected"]>[1]) => Promise<void>;
-    onRequestComplete: (ctx: RequestContext, usage: GatewayUsageEvent) => Promise<void>;
-    onStreamError: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onStreamError"]>[1]) => Promise<void>;
-    onSettlementError: (ctx: RequestContext, info: Parameters<Required<GatewayObserver>["onSettlementError"]>[1]) => Promise<void>;
+/** Stable gateway identity. Neither the credential nor adapter identity is persisted. */
+declare function mppPaymentOperationId(method: string, paymentIdentity: string): Promise<string>;
+
+declare const PAYMENT_RECOVERY_VERSION: 1;
+type PaymentRecoveryState = 'claiming' | 'claimed' | 'executing' | 'retained' | 'settling' | 'releasing' | 'reconciled';
+interface SerializedPaymentOperation {
+    protocolVersion: 2;
+    operationId: string;
+    acquiredByRequestId: string;
+    executionStartedAt?: number;
+    retentionReason?: string;
+    nonceKey: string;
+    authorizationId: string;
+    reservedAmount: string;
+    settledAmount: string;
+    refundAmount: string;
+    expiresAt: number;
+    state: PaymentOperation['state'];
+}
+interface PaymentRecoveryAttribution {
+    requestId: string;
+    agentId: string;
+    agentSlug: string;
+    consumerId: string;
+    paymentMethod: PaymentMethod;
+    startMs: number;
+    pricePerTokenUsd: number;
+    platformFeePercent: number;
+    requiredAmount: string;
+    currencyDecimals: number;
+    maxOutputTokens: number;
+    executionBudget: SandboxExecutionBudget;
+}
+type PaymentRecoveryTarget = {
+    kind: 'x402';
+    operationId: string;
+    operation?: SerializedPaymentOperation;
+} | {
+    kind: 'mpp-charge';
+    method: string;
+    operationId: string;
+    operation?: MppChargeOperation;
+};
+/** Durable outbox row for one payment identity. Rows are never deleted here. */
+interface PaymentRecoveryRecord {
+    version: typeof PAYMENT_RECOVERY_VERSION;
+    id: string;
+    revision: number;
+    state: PaymentRecoveryState;
+    payment: PaymentRecoveryTarget;
+    attribution: PaymentRecoveryAttribution;
+    workStarted: boolean;
+    /** Earliest time a missing receipt may settle at the quoted ceiling. */
+    fallbackAt?: number;
+    usage?: SandboxUsageReceipt;
+    usageRecorded: boolean;
+    settlementBasis?: PaymentSettlementBasis;
+    reason?: string;
+    attempts: number;
+    lastError?: string;
+    nextAttemptAt: number;
+    lease?: {
+        id: string;
+        expiresAt: number;
+    };
+    createdAt: number;
+    updatedAt: number;
+    reconciledAt?: number;
+}
+interface PaymentRecoveryStore {
+    createIfAbsent(record: PaymentRecoveryRecord): Promise<boolean>;
+    get(id: string): Promise<PaymentRecoveryRecord | undefined>;
+    compareAndSet(expected: PaymentRecoveryRecord, next: PaymentRecoveryRecord): Promise<boolean>;
+    listDue(now: number, limit: number): Promise<PaymentRecoveryRecord[]>;
+}
+interface PaymentRecoveryConfig {
+    store: PaymentRecoveryStore;
+    /** Claimed payment with no execution becomes recoverable after this delay. */
+    staleRequestMs?: number;
+    /** Work without a final receipt settles at the quoted ceiling after this delay. */
+    receiptTimeoutMs?: number;
+    /** Failed provider recovery waits this long before its next attempt. */
+    retryDelayMs?: number;
+    /** One recovery worker owns a row for this duration. */
+    leaseMs?: number;
+}
+/** Atomic single-process store for tests and explicit local demo mode. */
+declare class MemoryPaymentRecoveryStore implements PaymentRecoveryStore {
+    private readonly records;
+    createIfAbsent(record: PaymentRecoveryRecord): Promise<boolean>;
+    get(id: string): Promise<PaymentRecoveryRecord | undefined>;
+    compareAndSet(expected: PaymentRecoveryRecord, next: PaymentRecoveryRecord): Promise<boolean>;
+    listDue(now: number, limit: number): Promise<PaymentRecoveryRecord[]>;
+}
+declare class PaymentRecoveryFenceError extends Error {
+    constructor(id: string);
 }
-/**
- * Generate a request-id. Crypto-random 16 bytes, hex-encoded with an `req_` prefix.
- * Works in Workers, Node, and browsers — all have globalThis.crypto.
- */
-declare function generateRequestId(): string;
 
 interface AgentMeta {
     /** Unique agent identifier (workspace ID, session ID, etc.) */
@@ -635,7 +810,6 @@ interface AgentMeta {
      */
     skills?: AgentSkill[];
 }
-type PaymentMethod = 'x402' | 'mpp' | 'apikey' | 'none';
 interface X402Config {
     /** Ethereum operator address for SpendAuth verification */
     operatorAddress: string;
@@ -647,8 +821,32 @@ interface X402Config {
     rpcUrl?: string;
     /** Demo mode: skip signature verification (default: false). NEVER enable in production. */
     demoMode?: boolean;
-    /** Production signer verification. Called with the raw SpendAuth payload. Return true if signature is valid. */
-    verifySigner?: (payload: Record<string, unknown>) => Promise<boolean>;
+    /** Protocol version for new durable payment operations. Production version 1 is read-only. */
+    paymentProtocolVersion?: 1 | 2;
+    /**
+     * Production signature verification. This callback must not reserve, claim,
+     * or mutate payment state.
+     */
+    verifySigner?: (payload: Record<string, unknown>, context?: {
+        protocolVersion: 1 | 2;
+        requestId?: string;
+    }) => Promise<boolean>;
+    /**
+     * Claim the verified payment after all request checks pass and immediately
+     * before sandbox work starts. Version 2 returns durable operation ownership.
+     * A boolean return is the version 1 demo-only compatibility path.
+     * Production version 1 must omit this callback because it has no durable
+     * provider operation or recovery identity.
+     */
+    authorizePayment?: (payload: Record<string, unknown>, context: PaymentAuthorizationContext) => Promise<boolean | PaymentOperation>;
+    /** Version 2 operation store. It owns claim, settle, release, and reclaim. */
+    paymentOperations?: PaymentOperations;
+    /**
+     * Number of base-unit decimals used by the payment token. Defaults to 6.
+     * The gateway uses this value to reject a payment that cannot cover the
+     * request's maximum token charge before it calls `verifySigner`.
+     */
+    currencyDecimals?: number;
 }
 interface MppConfig {
     /** MPP realm (e.g. "agents.tangle.tools") */
@@ -656,17 +854,24 @@ interface MppConfig {
     /** MPP method name (default: "blueprintevm") */
     method?: string;
     /**
-     * Production verifier for the method-specific credential. Return the
-     * authenticated consumer id, or null when the credential is invalid.
-     * The callback receives the decoded JSON payload when one exists plus the
-     * original decoded credential so non-JSON methods can verify their own form.
-     * Omit only when x402.demoMode is explicitly enabled for local testing, or
-     * when x402.verifySigner handles an x402-compatible MPP credential.
+     * Pure credential authentication. Return stable method-owned identity, or null.
+     * This callback must not consume a credential, create a processor object,
+     * reserve funds, confirm payment, or perform any other financial mutation.
+     */
+    authenticateCredential?: (payload: Record<string, unknown>, context: {
+        method: string;
+        credential: string;
+    }) => Promise<MppAuthenticatedCredential | null>;
+    /**
+     * @deprecated Use authenticateCredential and return a stable payment identity.
+     * This 0.7.1 callback remains supported through an explicit compatibility adapter.
      */
     verifySigner?: (payload: Record<string, unknown>, context: {
         method: string;
         credential: string;
     }) => Promise<string | null>;
+    /** Required immediate-charge lifecycle for every non-BlueprinTEVM method. */
+    charge?: MppChargeLifecycle;
 }
 interface PaymentResult {
     method: PaymentMethod;
@@ -692,27 +897,6 @@ interface ApiKeyInfo {
     /** Per-key daily limit override. */
     dailyLimit?: number;
 }
-interface GatewayUsageEvent {
-    /**
-     * Per-request id (matches `RequestContext.requestId`). Lets
-     * `recordUsage` correlate the usage row to the same request that
-     * `settlePayment` settles, observability hooks observe, and
-     * `onRequestComplete` reports — without re-deriving from a
-     * synthetic key. Required field as of 0.4.0; the gateway always has
-     * it in scope at the recordUsage call site.
-     */
-    requestId: string;
-    agentId: string;
-    agentSlug: string;
-    consumerId: string;
-    paymentMethod: PaymentMethod;
-    inputTokens: number;
-    outputTokens: number;
-    totalCostUsd: number;
-    ownerEarnedUsd: number;
-    platformFeeUsd: number;
-    durationMs: number;
-}
 interface SandboxStreamEvent {
     type?: string;
     data?: {
@@ -733,19 +917,46 @@ interface SandboxStreamEvent {
         inputRequired?: {
             prompt?: string;
         };
+        /** Provider receipt fields. Version 2 operations require every field. */
+        usage?: Partial<SandboxUsageReceipt>;
+        /** Tool or reasoning events may carry hidden usage without visible text. */
+        tool?: {
+            name?: string;
+            inputTokens?: number;
+            outputTokens?: number;
+        };
+        reasoning?: {
+            tokens?: number;
+        };
     };
 }
 interface SandboxBox {
     streamPrompt(message: string, opts?: {
         sessionId?: string;
         systemPrompt?: string;
+        maxOutputTokens?: number;
+        executionBudget?: SandboxExecutionBudget;
+        signal?: AbortSignal;
     }): AsyncIterable<SandboxStreamEvent>;
 }
+/** Authenticated request identity supplied when the host resolves a sandbox. */
+interface GatewaySandboxContext {
+    consumerId: string;
+    paymentMethod: PaymentMethod;
+    keyInfo: ApiKeyInfo | null;
+    requestId: string;
+    messages: ChatMessage[];
+    /** Stable UI conversation id when `conversationMode` is `thread`. */
+    threadId?: string;
+}
 interface GatewayConfig {
     /** Resolve agent metadata by slug. Return null if not found or not published. */
     resolveAgent: (slug: string) => Promise<AgentMeta | null>;
-    /** Get a sandbox instance for the agent. Called after payment is verified. */
-    getSandbox: (agent: AgentMeta) => Promise<SandboxBox>;
+    /**
+     * Get the agent execution adapter after payment is verified.
+     * Hosts that use agent-app can drive their normal persisted chat route here.
+     */
+    getSandbox: (agent: AgentMeta, context?: GatewaySandboxContext) => Promise<SandboxBox>;
     /**
      * Optional host authorization hook fired after payment verification
      * and before sandbox resolution. Use it for per-agent allowlists,
@@ -756,6 +967,8 @@ interface GatewayConfig {
         consumerId: string;
         keyId?: string;
         requestId: string;
+        /** Requested stable conversation id, after syntax validation. */
+        threadId?: string;
     }) => Promise<{
         allow: true;
     } | {
@@ -763,12 +976,22 @@ interface GatewayConfig {
         reason: string;
         code: string;
     }>;
-    /** Record a usage event after request completes. */
+    /**
+     * Record a usage event after request completes.
+     * The implementation must atomically upsert by requestId and return
+     * success when the row already exists. Recovery may retry after an
+     * acknowledgement is lost, so one request ID must produce one usage row.
+     */
     recordUsage: (event: GatewayUsageEvent) => Promise<void>;
     /** x402 payment configuration */
     x402: X402Config;
     /** MPP (Machine Payments Protocol) configuration. It is advertised only when a production verifier or explicit demo mode is available. */
     mpp?: MppConfig;
+    /**
+     * Durable payment recovery outbox. Production payment protocol version 2
+     * and generic MPP charge methods require this configuration.
+     */
+    paymentRecovery?: PaymentRecoveryConfig;
     /**
      * Verify an API key. Return key info if valid, null if invalid.
      * In explicit x402 demo mode, the built-in verifier accepts `sk_agent_*` keys.
@@ -776,16 +999,44 @@ interface GatewayConfig {
      */
     verifyApiKey?: (authHeader: string) => Promise<ApiKeyInfo | null>;
     /**
-     * Settle payment after successful response.
-     * For x402: call ShieldedCredits.claimPayment()
-     * For API key: deduct from spending limit
-     * Default: no-op (demo mode).
+     * Settle a legacy payment after usage attribution is recorded.
+     * Version 2 x402 operations use `x402.paymentOperations` instead.
+     * Production x402 version 1 rejects this callback before nonce claim.
+     * For API keys, deduct from the spending limit.
+     * Default: no-op in explicit demo mode.
      */
     settlePayment?: (payment: PaymentResult, cost: number) => Promise<void>;
     /** Base URL for API key purchase links (e.g. "https://film.tangle.tools") */
     baseUrl?: string;
+    /** Public API key prefix shown by discovery. Defaults to `sk_agent_`. */
+    apiKeyPrefix?: string;
+    /**
+     * `consumer` keeps the historical session per API consumer.
+     * `thread` accepts `X-Tangle-Thread-Id` or creates one per request and returns
+     * it in the response, so a host can display the same conversation.
+     */
+    conversationMode?: 'consumer' | 'thread';
     /** Max message length in chars (default: 8000) */
     maxMessageLength?: number;
+    /** Maximum output token request the gateway accepts. Defaults to 4096. */
+    maxOutputTokens?: number;
+    /** Output token limit used when a request omits `max_tokens`. Defaults to 1024. */
+    defaultOutputTokens?: number;
+    /**
+     * Return a safe upper bound for the complete provider input.
+     * Include system, chat framing, retained history, tools, harness, and workspace context.
+     */
+    inputTokenBound?: (input: {
+        agent: AgentMeta;
+        messages: ChatMessage[];
+    }) => number;
+    /** Hidden provider spend limits included in the pre-execution payment quote. */
+    executionBudget?: {
+        maxReasoningTokens?: number;
+        maxToolTokens?: number;
+        maxToolCalls?: number;
+        maxProviderCostUsd?: number;
+    };
     /** Required scope for chat endpoint (default: "chat"). API keys must include this scope. */
     requiredScope?: string;
     /** Block requests with detected injection patterns (default: false — log only) */
@@ -807,16 +1058,27 @@ interface GatewayConfig {
      */
     observer?: GatewayObserver;
     /**
-     * A2A protocol configuration. When set, the gateway exposes the A2A
-     * surface alongside its OpenAI-compatible endpoints:
+     * A2A protocol configuration. The gateway exposes A2A with an in-memory
+     * task store by default. Set this object to provide durable storage or push:
      *   GET  /:slug/.well-known/agent.json   — AgentCard discovery
      *   POST /:slug                          — JSON-RPC 2.0 endpoint
      *     methods: message/send, message/stream, tasks/get, tasks/cancel
      * Auth + rate-limit + injection-filter + authorization all share the
      * same pipeline as the OpenAI-compat path. `taskStore` defaults to
      * `InMemoryTaskStore`; swap in D1/postgres/DO for durable deployments.
-     */
+    */
     a2a?: {
+        /**
+         * Authorize reads, cancellation, resubscription, and push configuration
+         * for an existing task. Production control methods fail closed when this
+         * hook is absent; explicit demo mode permits local tests.
+         */
+        authorizeTaskAccess?: (task: Task, context: {
+            method: string;
+            agentSlug: string;
+            authorization: string;
+            paymentSignature: string;
+        }) => Promise<boolean>;
         /**
          * Where tasks live. Defaults to `InMemoryTaskStore`; swap in
          * `SqlTaskStore` (D1, postgres, sqlite, libSQL) for durability across
@@ -835,8 +1097,8 @@ interface GatewayConfig {
          * Shared HMAC secret used to sign webhook deliveries (`X-A2A-Signature:
          * sha256=<hex>`). The consumer's webhook verifies the body against this
          * secret to confirm the call originated from this gateway. Required when
-         * `pushStore` is set; without it, deliveries fire unsigned and a
-         * malicious party that knows the webhook URL can forge deliveries.
+         * `pushStore` is set in production. Explicit demo mode may omit it for
+         * local tests; production deliveries never run unsigned.
          */
         webhookSecret?: string;
         /**
@@ -844,8 +1106,21 @@ interface GatewayConfig {
          * `fetch`. Override for tests or to wire a queue-backed sender.
          */
         pushFetcher?: typeof fetch;
+        /**
+         * DNS-aware policy for push destinations. Required when production
+         * push delivery is enabled so private DNS names cannot receive task data.
+         */
+        pushUrlValidator?: (url: URL) => boolean | Promise<boolean>;
     };
 }
+/** API-key-only gateway input. Payment transports stay disabled. */
+type ApiKeyGatewayConfig = Omit<GatewayConfig, 'mpp' | 'verifyApiKey' | 'x402'> & {
+    mpp?: never;
+    verifyApiKey: NonNullable<GatewayConfig['verifyApiKey']>;
+    x402?: never;
+};
+/** Configuration accepted by `createAgentGateway`. */
+type CreateAgentGatewayConfig = GatewayConfig | ApiKeyGatewayConfig;
 interface ChatMessage {
     role: 'system' | 'user' | 'assistant' | 'tool';
     content: string;
@@ -872,4 +1147,4 @@ interface ChatCompletionChunk {
     }>;
 }
 
-export { type TaskStatusUpdateEvent as $, type ApiKeyInfo as A, type PushNotificationAuthentication as B, type ChatMessage as C, type D1DatabaseLike as D, type PushNotificationConfig as E, type FilePart as F, type GatewayConfig as G, type PushNotificationStore as H, InMemoryPushNotificationStore as I, type JSONRPCErrorResponse as J, type SandboxStreamEvent as K, type SqlAdapter as L, type MppConfig as M, SqlPushNotificationStore as N, SqlTaskStore as O, type Part as P, type StreamingEvent as Q, type RequestContext as R, type SandboxBox as S, type Task as T, type TaskArtifactUpdateEvent as U, type TaskIdParams as V, type TaskPushNotificationConfig as W, type X402Config as X, type TaskPushNotificationConfigGetParams as Y, type TaskState as Z, type TaskStatus as _, A2A_ERROR_CODES as a, type TaskStore as a0, type TextPart as a1, d1ToSqlAdapter as a2, deliverPushNotifications as a3, generateRequestId as a4, type AgentCapabilities as b, type AgentCard as c, type AgentCardAuthentication as d, type AgentMeta as e, type AgentProvider as f, type AgentSkill as g, type Artifact as h, type AuthFailureReason as i, type ChatCompletionChunk as j, type ChatCompletionRequest as k, CompositeObserver as l, ConsoleObserver as m, type D1StmtLike as n, type DataPart as o, type GatewayObserver as p, type GatewayUsageEvent as q, InMemoryTaskStore as r, type JSONRPCRequest as s, type JSONRPCResponse as t, type JSONRPCSuccessResponse as u, type Message as v, type MessageSendParams as w, type PaymentMethod as x, type PaymentResult as y, type PushDeliveryResult as z };
+export { PaymentRecoveryFenceError as $, type ApiKeyInfo as A, type MessageSendParams as B, type ChatMessage as C, type D1DatabaseLike as D, type MppChargeLifecycle as E, type FilePart as F, type GatewayConfig as G, type MppChargeOperation as H, InMemoryPushNotificationStore as I, type JSONRPCErrorResponse as J, type MppChargeOperationState as K, type MppChargeRecoveryResult as L, type MppAuthenticatedCredential as M, type MppChargeRequest as N, PAYMENT_PROTOCOL_VERSION as O, type PaymentOperationRecoveryResult as P, PAYMENT_RECOVERY_VERSION as Q, type Part as R, type SqlAdapter as S, type PaymentAuthorizationContext as T, type PaymentOperation as U, type PaymentOperationNotFound as V, type PaymentOperationState as W, type X402Config as X, type PaymentOperations as Y, type PaymentRecoveryAttribution as Z, type PaymentRecoveryConfig as _, type PaymentRecoveryRecord as a, type PaymentRecoveryState as a0, type PaymentRecoveryTarget as a1, type PaymentResult as a2, type PaymentSettlementInput as a3, type PushDeliveryResult as a4, type PushNotificationAuthentication as a5, type PushNotificationConfig as a6, type PushNotificationDeliveryOptions as a7, type PushNotificationStore as a8, type SandboxBox as a9, type SandboxStreamEvent as aa, SqlPushNotificationStore as ab, SqlTaskStore as ac, type StreamingEvent as ad, type Task as ae, type TaskArtifactUpdateEvent as af, type TaskIdParams as ag, type TaskPushNotificationConfig as ah, type TaskPushNotificationConfigGetParams as ai, type TaskState as aj, type TaskStatus as ak, type TaskStatusUpdateEvent as al, type TaskStore as am, type TextPart as an, d1ToSqlAdapter as ao, deliverDemoPushNotifications as ap, deliverPushNotifications as aq, mppPaymentOperationId as ar, validatePushNotificationUrl as as, type GatewaySandboxContext as at, type MppConfig as b, type PaymentRecoveryStore as c, A2A_ERROR_CODES as d, type AgentCapabilities as e, type AgentCard as f, type AgentCardAuthentication as g, type AgentMeta as h, type AgentProvider as i, type AgentSkill as j, type ApiKeyGatewayConfig as k, type Artifact as l, type ChatCompletionChunk as m, type ChatCompletionRequest as n, type CreateAgentGatewayConfig as o, type D1StmtLike as p, type DataPart as q, InMemoryTaskStore as r, type JSONRPCRequest as s, type JSONRPCResponse as t, type JSONRPCSuccessResponse as u, MPP_CHARGE_PROTOCOL_VERSION as v, MemoryPaymentOperations as w, type MemoryPaymentOperationsOptions as x, MemoryPaymentRecoveryStore as y, type Message as z };