@tangle-network/agent-gateway 0.7.1 → 0.8.1

package/src/dispatch-pricing.ts

@@ -0,0 +1,108 @@
+import type { AgentMeta, ChatMessage } from './types'
+
+function decimalFraction(value: number): { numerator: bigint; denominator: bigint } {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error('agent pricePerTokenUsd must be a finite non-negative number')
+  }
+  const [mantissa, exponentText] = value.toString().toLowerCase().split('e')
+  const exponent = exponentText ? Number(exponentText) : 0
+  const [whole, fraction = ''] = mantissa.split('.')
+  let numerator = BigInt(`${whole}${fraction}`)
+  let scale = fraction.length - exponent
+  if (scale < 0) {
+    numerator *= 10n ** BigInt(-scale)
+    scale = 0
+  }
+  return { numerator, denominator: 10n ** BigInt(scale) }
+}
+
+function amountForTokens(
+  pricePerTokenUsd: number,
+  tokenCount: number,
+  currencyDecimals: number,
+  providerCostUsd: number,
+): bigint {
+  const { numerator, denominator } = decimalFraction(pricePerTokenUsd)
+  const scaled = BigInt(tokenCount) * numerator * 10n ** BigInt(currencyDecimals)
+  const tokenAmount = (scaled + denominator - 1n) / denominator
+  const provider = providerCostUsd === 0
+    ? { numerator: 0n, denominator: 1n }
+    : decimalFraction(providerCostUsd)
+  const providerScaled = provider.numerator * 10n ** BigInt(currencyDecimals)
+  const providerAmount = (providerScaled + provider.denominator - 1n) / provider.denominator
+  return tokenAmount > providerAmount ? tokenAmount : providerAmount
+}
+
+/** Exact base-unit reservation required to cover the request's token ceiling. */
+export function requiredX402Amount(
+  pricePerTokenUsd: number,
+  inputTokens: number,
+  maxOutputTokens: number,
+  currencyDecimals = 6,
+  maxReasoningTokens = 0,
+  maxToolTokens = 0,
+  maxProviderCostUsd = 0,
+): bigint {
+  if (!Number.isSafeInteger(inputTokens) || inputTokens < 0) {
+    throw new Error('input token estimate must be a non-negative safe integer')
+  }
+  if (!Number.isSafeInteger(maxOutputTokens) || maxOutputTokens <= 0) {
+    throw new Error('max output tokens must be a positive safe integer')
+  }
+  if (!Number.isInteger(currencyDecimals) || currencyDecimals < 0 || currencyDecimals > 18) {
+    throw new Error('x402 currencyDecimals must be an integer between 0 and 18')
+  }
+  for (const [name, value] of [
+    ['maxReasoningTokens', maxReasoningTokens],
+    ['maxToolTokens', maxToolTokens],
+  ] as const) {
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a non-negative safe integer`)
+  }
+  if (!Number.isFinite(maxProviderCostUsd) || maxProviderCostUsd < 0) {
+    throw new Error('maxProviderCostUsd must be finite and non-negative')
+  }
+  const tokenCount = inputTokens + maxOutputTokens + maxReasoningTokens + maxToolTokens
+  if (!Number.isSafeInteger(tokenCount)) throw new Error('token budget exceeds safe integer range')
+  return amountForTokens(pricePerTokenUsd, tokenCount, currencyDecimals, maxProviderCostUsd)
+}
+
+export function actualX402Amount(
+  pricePerTokenUsd: number,
+  inputTokens: number,
+  outputTokens: number,
+  reasoningTokens: number,
+  toolTokens: number,
+  currencyDecimals = 6,
+  providerCostUsd = 0,
+): bigint {
+  return amountForTokens(
+    pricePerTokenUsd,
+    inputTokens + outputTokens + reasoningTokens + toolTokens,
+    currencyDecimals,
+    providerCostUsd,
+  )
+}
+
+/** Token estimate matching the existing chat-completions handler (4 chars ≈ 1 token). */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4)
+}
+
+/** Include the host-owned system prompt because the provider bills it too. */
+export function estimateBillableInputTokens(agent: AgentMeta, userMessage: string): number {
+  return estimateTokens(userMessage) + estimateTokens(agent.systemPrompt ?? '')
+}
+
+/** A tokenizer cannot emit more tokens than the UTF-8 bytes it consumes. */
+export function maximumBillableInputTokens(agent: AgentMeta, userMessage: string): number
+export function maximumBillableInputTokens(agent: AgentMeta, messages: readonly ChatMessage[]): number
+export function maximumBillableInputTokens(
+  agent: AgentMeta,
+  userMessageOrMessages: string | readonly ChatMessage[],
+): number {
+  const encoder = new TextEncoder()
+  const prompt = typeof userMessageOrMessages === 'string'
+    ? userMessageOrMessages
+    : JSON.stringify(userMessageOrMessages)
+  return encoder.encode(prompt).byteLength + encoder.encode(agent.systemPrompt ?? '').byteLength
+}

package/src/dispatch-sandbox.ts

@@ -0,0 +1,424 @@
+import { redactSystemPromptFromOutput } from './filter'
+import type { A2ADispatchEvent } from './dispatch-types'
+import {
+  estimateTokens,
+  maximumBillableInputTokens,
+} from './dispatch-pricing'
+import type {
+  AgentMeta,
+  GatewayConfig,
+  GatewaySandboxContext,
+  SandboxExecutionBudget,
+  SandboxStreamEvent,
+  SandboxUsageReceipt,
+} from './types'
+
+export async function* dispatchSandboxStream(
+  agent: AgentMeta,
+  userMessage: string,
+  consumerId: string,
+  config: GatewayConfig,
+  signal?: AbortSignal,
+  sessionId?: string,
+  maxOutputTokens?: number,
+): AsyncIterable<string> {
+  for await (const event of dispatchSandboxStreamRich(
+    agent,
+    userMessage,
+    consumerId,
+    config,
+    signal,
+    sessionId,
+    maxOutputTokens,
+  )) {
+    if (event.kind === 'text') yield event.delta
+  }
+}
+
+/**
+ * Like `dispatchSandboxStream` but yields a discriminated union so callers can
+ * react to `input-required` signals from the sandbox. The sandbox opts in by
+ * emitting `{ type: 'input-required', data: { inputRequired: { prompt? } } }`
+ * (or by setting `data.inputRequired` on any event); sandboxes that don't emit
+ * such events see identical behavior.
+ *
+ * `sessionId` defaults to `consumer:<id>` matching the existing single-turn
+ * path; multi-turn continuations pass an explicit `taskId` so the sandbox can
+ * keep per-task conversation memory.
+ */
+export async function* dispatchSandboxStreamRich(
+  agent: AgentMeta,
+  userMessage: string,
+  consumerId: string,
+  config: GatewayConfig,
+  signal?: AbortSignal,
+  sessionId?: string,
+  maxOutputTokens?: number,
+  onExecutionStart?: () => Promise<void>,
+  requiresReceipt = config.x402.paymentOperations !== undefined,
+  onSandboxStart?: () => void | Promise<void>,
+  maxInputTokens?: number,
+  onExecutionHeartbeat?: () => Promise<void>,
+  sandboxContext?: GatewaySandboxContext,
+): AsyncIterable<A2ADispatchEvent> {
+  if (signal?.aborted) return
+  const box = await config.getSandbox(agent, sandboxContext)
+  if (signal?.aborted) return
+  const outputLimit = maxOutputTokens ?? config.defaultOutputTokens ?? 1024
+  if (!Number.isSafeInteger(outputLimit) || outputLimit <= 0) {
+    throw new Error('max output tokens must be a positive safe integer')
+  }
+  let outputBytes = 0
+  // Bound untrusted adapters while the final receipt is pending. The receipt
+  // remains authoritative for token count, so over-limit output is never sent.
+  const maxOutputBytes = outputLimit * 4
+  if (!Number.isSafeInteger(maxOutputBytes)) {
+    throw new Error('max output token bound exceeds safe integer range')
+  }
+  const encoder = new TextEncoder()
+  let usageParts: Partial<SandboxUsageReceipt> = {}
+  let observedReasoningTokens = 0
+  let observedToolTokens = 0
+  let observedToolCalls = 0
+  let legacyOutputText = ''
+  const executionController = new AbortController()
+  const forwardAbort = () => executionController.abort()
+  if (signal?.aborted) return
+  signal?.addEventListener('abort', forwardAbort, { once: true })
+  const executionBudget: SandboxExecutionBudget = {
+    maxInputTokens: maxInputTokens ?? maximumBillableInputTokens(agent, userMessage),
+    maxOutputTokens: outputLimit,
+    maxReasoningTokens: config.executionBudget?.maxReasoningTokens ?? outputLimit,
+    maxToolTokens: config.executionBudget?.maxToolTokens ?? outputLimit,
+    maxToolCalls: config.executionBudget?.maxToolCalls ?? 8,
+    maxProviderCostUsd: config.executionBudget?.maxProviderCostUsd ?? (
+      (maxInputTokens ?? maximumBillableInputTokens(agent, userMessage)) + outputLimit +
+        (config.executionBudget?.maxReasoningTokens ?? outputLimit) +
+        (config.executionBudget?.maxToolTokens ?? outputLimit)
+    ) * agent.pricePerTokenUsd,
+  }
+  if (executionController.signal.aborted) return
+  await onExecutionStart?.()
+  if (executionController.signal.aborted) return
+  let heartbeatError: unknown
+  let heartbeatInFlight: Promise<void> | undefined
+  let heartbeatTimer: ReturnType<typeof setInterval> | undefined
+  let iterator: AsyncIterator<SandboxStreamEvent> | undefined
+  try {
+    // This durable handoff is after sandbox acquisition and immediately before
+    // the adapter call that may start paid work.
+    await onSandboxStart?.()
+    const promptStream = box.streamPrompt(userMessage, {
+      sessionId: sessionId ?? `consumer:${consumerId}`,
+      systemPrompt: agent.systemPrompt,
+      maxOutputTokens: outputLimit,
+      executionBudget,
+      signal: executionController.signal,
+    })
+    iterator = promptStream[Symbol.asyncIterator]()
+    const heartbeatMs = onExecutionHeartbeat
+      ? Math.max(100, Math.min(
+          Math.floor((config.paymentRecovery?.receiptTimeoutMs ?? 5 * 60_000) / 3),
+          5_000,
+        ))
+      : 0
+    if (onExecutionHeartbeat) {
+      heartbeatTimer = setInterval(() => {
+        if (heartbeatInFlight || heartbeatError !== undefined) return
+        heartbeatInFlight = onExecutionHeartbeat()
+          .catch((error: unknown) => {
+            heartbeatError = error
+            executionController.abort()
+          })
+          .finally(() => {
+            heartbeatInFlight = undefined
+          })
+      }, heartbeatMs)
+    }
+    while (true) {
+      const next = await readSandboxEvent(iterator, executionController.signal)
+      if (next === ABORTED_SANDBOX_READ) {
+        if (heartbeatError !== undefined) throw heartbeatError
+        return
+      }
+      if (next.done) break
+      const event = next.value
+      if (event.data?.usage) usageParts = mergeUsage(usageParts, event.data.usage)
+      if (event.data?.reasoning?.tokens !== undefined) {
+        observedReasoningTokens += nonNegativeSafeInteger(event.data.reasoning.tokens, 'reasoning tokens')
+        yield { kind: 'activity' }
+      }
+      if (event.data?.tool) {
+        observedToolCalls += 1
+        observedToolTokens +=
+          nonNegativeSafeInteger(event.data.tool.inputTokens ?? 0, 'tool input tokens') +
+          nonNegativeSafeInteger(event.data.tool.outputTokens ?? 0, 'tool output tokens')
+        yield { kind: 'activity' }
+      }
+      enforceUsageBudget(withObservedUsage(
+        usageParts,
+        observedReasoningTokens,
+        observedToolTokens,
+        observedToolCalls,
+      ), executionBudget)
+      if (
+        event.type === 'message.part.updated' &&
+        event.data?.part?.type === 'text' &&
+        event.data.delta
+      ) {
+        const remainingBytes = maxOutputBytes - outputBytes
+        if (remainingBytes <= 0) throw new Error('sandbox exceeded max output tokens')
+        const bounded = truncateUtf8(event.data.delta, remainingBytes, encoder)
+        if (bounded.truncated) {
+          yield { kind: 'activity' }
+          throw new Error('sandbox exceeded max output tokens')
+        }
+        outputBytes += bounded.bytes
+        legacyOutputText += bounded.text
+        yield { kind: 'activity' }
+        yield { kind: 'text', delta: redactSystemPromptFromOutput(bounded.text, agent.systemPrompt) }
+        continue
+      }
+      if (event.type === 'input-required' || event.data?.inputRequired) {
+        const usage = completeUsage(
+          usageParts,
+          observedReasoningTokens,
+          observedToolTokens,
+          observedToolCalls,
+          userMessage,
+          legacyOutputText,
+          executionBudget,
+          requiresReceipt,
+        )
+        yield { kind: 'input-required', prompt: event.data?.inputRequired?.prompt }
+        // Terminal for the sandbox stream — sandbox SHOULD stop emitting until
+        // the gateway dispatches a continuation message with the new user input.
+        yield { kind: 'usage', usage }
+        return
+      }
+    }
+    const usage = completeUsage(
+      usageParts,
+      observedReasoningTokens,
+      observedToolTokens,
+      observedToolCalls,
+      userMessage,
+      legacyOutputText,
+      executionBudget,
+      requiresReceipt,
+    )
+    yield { kind: 'usage', usage }
+  } finally {
+    if (heartbeatTimer !== undefined) clearInterval(heartbeatTimer)
+    const pendingHeartbeat = heartbeatInFlight
+    if (pendingHeartbeat) await pendingHeartbeat
+    signal?.removeEventListener('abort', forwardAbort)
+    if (iterator) await closeSandboxIterator(iterator)
+    if (heartbeatError !== undefined && !signal?.aborted) throw heartbeatError
+  }
+}
+
+const ABORTED_SANDBOX_READ = Symbol('aborted-sandbox-read')
+
+async function readSandboxEvent(
+  iterator: AsyncIterator<SandboxStreamEvent>,
+  signal?: AbortSignal,
+): Promise<IteratorResult<SandboxStreamEvent> | typeof ABORTED_SANDBOX_READ> {
+  if (!signal) return iterator.next()
+  if (signal.aborted) return ABORTED_SANDBOX_READ
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener('abort', onAbort)
+      resolve(ABORTED_SANDBOX_READ)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    iterator.next().then(
+      (result) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(result)
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(error)
+      },
+    )
+  })
+}
+
+const SANDBOX_CLEANUP_TIMEOUT_MS = 50
+
+async function closeSandboxIterator(iterator: AsyncIterator<SandboxStreamEvent>): Promise<void> {
+  let closing: PromiseLike<unknown> | undefined
+  try {
+    const result = iterator.return?.()
+    if (result) closing = Promise.resolve(result)
+  } catch {
+    return
+  }
+  if (!closing) return
+  let timeout: ReturnType<typeof setTimeout> | undefined
+  try {
+    await Promise.race([
+      Promise.resolve(closing).catch(() => undefined),
+      new Promise<void>((resolve) => {
+        timeout = setTimeout(resolve, SANDBOX_CLEANUP_TIMEOUT_MS)
+      }),
+    ])
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout)
+  }
+}
+
+function mergeUsage(
+  current: Partial<SandboxUsageReceipt>,
+  update: Partial<SandboxUsageReceipt>,
+): Partial<SandboxUsageReceipt> {
+  const merged = { ...current, ...update }
+  for (const key of ['inputTokens', 'outputTokens', 'reasoningTokens', 'toolTokens', 'toolCallCount', 'providerCostUsd'] as const) {
+    const value = update[key]
+    if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+      throw new Error(`sandbox usage field ${key} is invalid`)
+    }
+    if (value !== undefined && current[key] !== undefined) {
+      // Usage events are cumulative receipts. Never let a later partial or
+      // final event erase spend observed earlier in the same execution.
+      merged[key] = Math.max(current[key]!, value)
+    }
+  }
+  if (current.budgetEnforced === false || update.budgetEnforced === false) {
+    merged.budgetEnforced = false
+  }
+  return merged
+}
+
+function withObservedUsage(
+  usage: Partial<SandboxUsageReceipt>,
+  reasoningTokens: number,
+  toolTokens: number,
+  toolCallCount: number,
+): Partial<SandboxUsageReceipt> {
+  return {
+    ...usage,
+    ...(usage.reasoningTokens !== undefined || reasoningTokens > 0
+      ? { reasoningTokens: Math.max(usage.reasoningTokens ?? 0, reasoningTokens) }
+      : {}),
+    ...(usage.toolTokens !== undefined || toolTokens > 0
+      ? { toolTokens: Math.max(usage.toolTokens ?? 0, toolTokens) }
+      : {}),
+    ...(usage.toolCallCount !== undefined || toolCallCount > 0
+      ? { toolCallCount: Math.max(usage.toolCallCount ?? 0, toolCallCount) }
+      : {}),
+  }
+}
+
+function nonNegativeSafeInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`sandbox ${name} is invalid`)
+  }
+  return value
+}
+
+function enforceUsageBudget(
+  usage: Partial<SandboxUsageReceipt>,
+  budget: SandboxExecutionBudget,
+): void {
+  if (usage.inputTokens !== undefined && usage.inputTokens > budget.maxInputTokens) {
+    throw new Error('sandbox exceeded max input tokens')
+  }
+  if (usage.outputTokens !== undefined && usage.outputTokens > budget.maxOutputTokens) {
+    throw new Error('sandbox exceeded max output tokens')
+  }
+  if (usage.reasoningTokens !== undefined && usage.reasoningTokens > budget.maxReasoningTokens) {
+    throw new Error('sandbox exceeded max reasoning tokens')
+  }
+  if (usage.toolTokens !== undefined && usage.toolTokens > budget.maxToolTokens) {
+    throw new Error('sandbox exceeded max tool tokens')
+  }
+  if (usage.toolCallCount !== undefined && usage.toolCallCount > budget.maxToolCalls) {
+    throw new Error('sandbox exceeded max tool calls')
+  }
+  if (usage.providerCostUsd !== undefined && usage.providerCostUsd > budget.maxProviderCostUsd) {
+    throw new Error('sandbox exceeded max provider cost')
+  }
+}
+
+function finalizeUsage(
+  parts: Partial<SandboxUsageReceipt>,
+  budget: SandboxExecutionBudget,
+): SandboxUsageReceipt {
+  const fields = ['inputTokens', 'outputTokens', 'reasoningTokens', 'toolTokens', 'toolCallCount', 'providerCostUsd', 'budgetEnforced'] as const
+  if (fields.some((field) => parts[field] === undefined)) {
+    throw new Error('sandbox did not provide a complete usage receipt')
+  }
+  const usage = parts as SandboxUsageReceipt
+  for (const field of ['inputTokens', 'outputTokens', 'reasoningTokens', 'toolTokens', 'toolCallCount'] as const) {
+    if (!Number.isSafeInteger(usage[field]) || usage[field] < 0) {
+      throw new Error(`sandbox usage field ${field} is invalid`)
+    }
+  }
+  if (!Number.isFinite(usage.providerCostUsd) || usage.providerCostUsd < 0) {
+    throw new Error('sandbox usage provider cost is invalid')
+  }
+  if (typeof usage.budgetEnforced !== 'boolean') {
+    throw new Error('sandbox usage budget flag is invalid')
+  }
+  if (!Number.isSafeInteger(
+    usage.inputTokens + usage.outputTokens + usage.reasoningTokens + usage.toolTokens,
+  )) {
+    throw new Error('sandbox usage token total exceeds safe integer range')
+  }
+  enforceUsageBudget(usage, budget)
+  if (!usage.budgetEnforced) throw new Error('sandbox did not enforce the execution budget')
+  return usage
+}
+
+function completeUsage(
+  parts: Partial<SandboxUsageReceipt>,
+  reasoningTokens: number,
+  toolTokens: number,
+  toolCallCount: number,
+  userMessage: string,
+  outputText: string,
+  budget: SandboxExecutionBudget,
+  requiresReceipt: boolean,
+): SandboxUsageReceipt {
+  const observed = withObservedUsage(parts, reasoningTokens, toolTokens, toolCallCount)
+  if (
+    !requiresReceipt &&
+    Object.keys(parts).length === 0 &&
+    reasoningTokens === 0 &&
+    toolTokens === 0 &&
+    toolCallCount === 0
+  ) {
+    // Preserve the pre-receipt SandboxBox contract for legacy API-key
+    // adapters. Durable payment operations must use provider-enforced usage.
+    return {
+      inputTokens: estimateTokens(userMessage),
+      outputTokens: estimateTokens(outputText),
+      reasoningTokens: 0,
+      toolTokens: 0,
+      toolCallCount: 0,
+      providerCostUsd: 0,
+      budgetEnforced: false,
+    }
+  }
+  return finalizeUsage(observed, budget)
+}
+
+function truncateUtf8(
+  value: string,
+  maxBytes: number,
+  encoder: TextEncoder,
+): { text: string; bytes: number; truncated: boolean } {
+  const bytes = encoder.encode(value).byteLength
+  if (bytes <= maxBytes) return { text: value, bytes, truncated: false }
+  let text = ''
+  let used = 0
+  for (const character of value) {
+    const characterBytes = encoder.encode(character).byteLength
+    if (used + characterBytes > maxBytes) break
+    text += character
+    used += characterBytes
+  }
+  return { text, bytes: used, truncated: true }
+}

package/src/dispatch-settlement.ts

@@ -0,0 +1,139 @@
+import { type GatewayObserver, type RequestContext } from './observer'
+import { actualX402Amount } from './dispatch-pricing'
+import {
+  assertX402V1SettlementSafe,
+  markRecoveryReconciled,
+  markRecoverySettling,
+  markRecoveryUsageRecorded,
+} from './dispatch-payment-recovery'
+import type {
+  AuthorizedRequest,
+  SettleAndRecordOptions,
+} from './dispatch-types'
+import type { AgentMeta, GatewayConfig, SandboxUsageReceipt } from './types'
+
+/**
+ * Record usage, settle payment, and invoke the observer. Both wire formats
+ * call this once their stream has drained, so settlement happens exactly once
+ * per request regardless of protocol.
+ */
+export async function settleAndRecord(
+  agent: AgentMeta,
+  authz: AuthorizedRequest,
+  usage: SandboxUsageReceipt,
+  config: GatewayConfig,
+  obs: GatewayObserver | undefined,
+  options: SettleAndRecordOptions = {},
+): Promise<void> {
+  assertX402V1SettlementSafe(authz, config)
+  const settlementBasis = options.settlementBasis ?? 'usage-receipt'
+  await markRecoverySettling(authz, usage, settlementBasis, config)
+  if (options.usageAlreadyRecorded) await markRecoveryUsageRecorded(authz, config)
+  const tokenCost = (
+    usage.inputTokens + usage.outputTokens + usage.reasoningTokens + usage.toolTokens
+  ) * agent.pricePerTokenUsd
+  const totalCost = Math.max(tokenCost, usage.providerCostUsd)
+  const ownerEarned = totalCost * (1 - agent.platformFeePercent)
+  const platformFee = totalCost * agent.platformFeePercent
+  const usageEvent = {
+    requestId: authz.requestId,
+    agentId: agent.id,
+    agentSlug: agent.slug,
+    consumerId: authz.consumerId,
+    paymentMethod: authz.paymentMethod,
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    reasoningTokens: usage.reasoningTokens,
+    toolTokens: usage.toolTokens,
+    toolCallCount: usage.toolCallCount,
+    providerCostUsd: usage.providerCostUsd,
+    totalCostUsd: totalCost,
+    ownerEarnedUsd: ownerEarned,
+    platformFeeUsd: platformFee,
+    durationMs: Date.now() - authz.startMs,
+    settlementBasis,
+  }
+  const ctx: RequestContext = {
+    requestId: authz.requestId,
+    agentSlug: agent.slug,
+    startMs: authz.startMs,
+  }
+  try {
+    if (authz.paymentOperation && config.x402.paymentOperations) {
+      const amount = options.paymentAmount ?? actualX402Amount(
+        agent.pricePerTokenUsd,
+        usage.inputTokens,
+        usage.outputTokens,
+        usage.reasoningTokens,
+        usage.toolTokens,
+        config.x402.currencyDecimals,
+        usage.providerCostUsd,
+      )
+      if (options.paymentAlreadySettled) {
+        if (
+          authz.paymentOperation.state !== 'settled' ||
+          authz.paymentOperation.settledAmount !== amount
+        ) {
+          throw new Error('authoritative payment state does not match finalization')
+        }
+      } else {
+        authz.paymentOperation = await config.x402.paymentOperations.settlePayment(
+          authz.paymentOperation,
+          { amount, totalCostUsd: totalCost, usage, basis: settlementBasis },
+        )
+      }
+      // Durable settlement happens first. If attribution storage is
+      // unavailable, recovery must never refund delivered work.
+      if (!options.usageAlreadyRecorded) {
+        await config.recordUsage(usageEvent)
+        await options.onUsageRecorded?.()
+        await markRecoveryUsageRecorded(authz, config)
+      }
+    } else if (authz.mppChargeOperation) {
+      // Generic MPP charge methods confirm before the response. Finalization
+      // records attribution only; it never invokes the legacy settlement hook.
+      if (!options.usageAlreadyRecorded) {
+        await config.recordUsage(usageEvent)
+        await options.onUsageRecorded?.()
+        await markRecoveryUsageRecorded(authz, config)
+      }
+    } else {
+      // Legacy adapters retain attribution-before-charge because their
+      // settlement callback may resolve that usage row.
+      if (!options.usageAlreadyRecorded) {
+        await config.recordUsage(usageEvent)
+        await options.onUsageRecorded?.()
+      }
+      if (config.settlePayment) {
+        await config.settlePayment(
+          {
+            method: authz.paymentMethod,
+            consumerId: authz.consumerId,
+            requestId: authz.requestId,
+          },
+          totalCost,
+        )
+      }
+    }
+    await markRecoveryReconciled(authz, config)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    console.error(`[agent-gateway] settlement failed for ${authz.consumerId}: ${msg}`)
+    await obs?.onSettlementError?.(ctx, {
+      consumerId: authz.consumerId,
+      method: authz.paymentMethod,
+      errorMessage: msg,
+    })
+    throw err
+  }
+  try {
+    await obs?.onRequestComplete?.(ctx, usageEvent)
+  } catch (error) {
+    console.error(
+      `[agent-gateway] completion observer failed for ${authz.requestId}:`,
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+}
+
+export type { SettleAndRecordOptions }