@agent-score/commerce 1.0.3 → 1.2.0

package/dist/identity/hono.mjs

@@ -90,10 +90,10 @@ var WALLET_NOT_TRUSTED_INSTRUCTIONS = JSON.stringify({
 var PAYMENT_REQUIRED_INSTRUCTIONS = JSON.stringify({
   action: "contact_merchant",
   steps: [
-    "The merchant's AgentScore tier does not include the assess feature, so agent identity cannot be evaluated. This is a merchant-side configuration gap \u2014 there is no agent-side recovery.",
-    "Contact the merchant (their support channel \u2014 typically listed in /llms.txt or the OpenAPI servers metadata) and request they upgrade their AgentScore plan."
+    "The merchant's AgentScore account does not have the assess endpoint enabled, so agent identity cannot be evaluated. This is a merchant-side configuration gap \u2014 there is no agent-side recovery.",
+    "Contact the merchant (their support channel \u2014 typically listed in /llms.txt or the OpenAPI servers metadata) so they can resolve the configuration on their side."
   ],
-  user_message: "This merchant's identity gate is misconfigured (AgentScore tier doesn't support assess). Contact the merchant \u2014 there's nothing to fix on the agent side."
+  user_message: "This merchant's identity gate is misconfigured. Contact the merchant \u2014 there's nothing to fix on the agent side."
 });
 var IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
   action: "deliver_verify_url_and_poll",
@@ -104,6 +104,24 @@ var IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
   ],
   user_message: "Identity verification is required. Visit verify_url, then poll poll_url for the operator token and retry."
 });
+var API_ERROR_INSTRUCTIONS = JSON.stringify({
+  action: "retry_with_backoff",
+  steps: [
+    "Verification is temporarily unavailable. Retry the request after 5\u201330 seconds with exponential backoff.",
+    "This is NOT a compliance denial \u2014 the user does not need to re-verify their identity. Send the same identity headers (X-Wallet-Address or X-Operator-Token) on retry.",
+    "If the request continues to fail after 3+ retries (~60 seconds total), surface the error to the user with the merchant's support contact."
+  ],
+  user_message: "Verification is temporarily unavailable. Please try again in a moment \u2014 this is a transient issue, not a problem with your account."
+});
+var QUOTA_EXCEEDED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_merchant",
+  steps: [
+    "AgentScore identity verification is unavailable for this merchant. This is a merchant-side issue and is NOT recoverable via retry.",
+    "Do not retry: the same 503 will be returned until the merchant resolves the issue on their side.",
+    "Surface to the user with the merchant's support contact. The merchant (not the agent) needs to act."
+  ],
+  user_message: "This merchant's identity verification is temporarily unavailable. Try again later, or contact the merchant directly."
+});
 var TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
   action: "deliver_verify_url_and_poll",
   steps: [
@@ -114,6 +132,7 @@ var TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
   user_message: "Operator token is expired or revoked. A new verification session has been minted \u2014 visit verify_url to refresh."
 });
 var DEFAULT_AGENT_INSTRUCTIONS = {
+  api_error: API_ERROR_INSTRUCTIONS,
   wallet_not_trusted: WALLET_NOT_TRUSTED_INSTRUCTIONS,
   payment_required: PAYMENT_REQUIRED_INSTRUCTIONS,
   identity_verification_required: IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS,
@@ -124,7 +143,7 @@ var DEFAULT_MESSAGES = {
   identity_verification_required: "Identity verification is required to access this resource. Visit verify_url to complete KYC.",
   wallet_not_trusted: "The wallet does not meet the merchant compliance policy.",
   api_error: "AgentScore is unreachable. This is transient \u2014 retry in a few seconds.",
-  payment_required: "AgentScore tier does not support assess. Contact support.",
+  payment_required: "Assess endpoint not enabled for this merchant. Contact support.",
   wallet_signer_mismatch: "Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the claimed wallet must both resolve to the same AgentScore operator.",
   wallet_auth_requires_wallet_signing: "X-Wallet-Address was sent with a rail that has no wallet signature (Stripe SPT / card). Switch to X-Operator-Token, or use a wallet-signing rail (Tempo MPP, x402).",
   token_expired: "The operator token is expired or revoked. A fresh verification session has been minted \u2014 visit verify_url to mint a new token.",
@@ -163,9 +182,6 @@ function denialReasonToBody(reason) {
   if (reason.expected_signer) body.expected_signer = reason.expected_signer;
   if (reason.actual_signer) body.actual_signer = reason.actual_signer;
   if (reason.linked_wallets && reason.linked_wallets.length > 0) body.linked_wallets = reason.linked_wallets;
-  if (reason.code === "api_error" && !(reason.extra && reason.extra.next_steps)) {
-    body.next_steps = { action: "retry", retry_after_seconds: 5 };
-  }
   if (reason.extra) {
     for (const [key, value] of Object.entries(reason.extra)) {
       if (RESERVED_FIELDS.has(key)) {
@@ -178,6 +194,16 @@ function denialReasonToBody(reason) {
   return body;
 }
 
+// src/core.ts
+import {
+  AgentScore,
+  InvalidCredentialError,
+  PaymentRequiredError,
+  QuotaExceededError,
+  TimeoutError as SdkTimeoutError,
+  TokenExpiredError
+} from "@agent-score/sdk";
+
 // src/address.ts
 var SOLANA_BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 var isSolanaAddress = (address) => SOLANA_BASE58_RE.test(address) && !address.startsWith("0x");
@@ -306,9 +332,23 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint();
-  const defaultUa = `@agent-score/commerce@${"1.0.3"}`;
+  const defaultUa = `@agent-score/commerce@${"1.2.0"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
-  const API_TIMEOUT_MS = 1e4;
+  const sdk = new AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
+  const sessionSdkCache = /* @__PURE__ */ new Map();
+  function getSessionSdk(sessionApiKey, sessionBaseUrl) {
+    const key = `${sessionApiKey}|${sessionBaseUrl ?? ""}`;
+    let s = sessionSdkCache.get(key);
+    if (!s) {
+      s = new AgentScore({
+        apiKey: sessionApiKey,
+        baseUrl: sessionBaseUrl ?? baseUrl,
+        userAgent: userAgentHeader
+      });
+      sessionSdkCache.set(key, s);
+    }
+    return s;
+  }
   const cache = new TTLCache(cacheSeconds * 1e3);
   async function tryMintSessionDenial(ctx) {
     if (!createSessionOnMissing) return void 0;
@@ -325,20 +365,11 @@ function createAgentScoreCore(options) {
           console.warn("[gate] createSessionOnMissing.getSessionOptions hook failed:", err instanceof Error ? err.message : err);
         }
       }
-      const sessionBaseUrl = stripTrailingSlashes(createSessionOnMissing.baseUrl ?? "https://api.agentscore.sh");
-      const sessionRes = await fetch(`${sessionBaseUrl}/v1/sessions`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": createSessionOnMissing.apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(sessionBody),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      const sessionSdk = getSessionSdk(createSessionOnMissing.apiKey, createSessionOnMissing.baseUrl);
+      const data = await sessionSdk.createSession({
+        ...sessionBody.context !== void 0 ? { context: sessionBody.context } : {},
+        ...sessionBody.product_name !== void 0 ? { product_name: sessionBody.product_name } : {}
       });
-      if (!sessionRes.ok) return void 0;
-      const data = await sessionRes.json();
       if (typeof data.session_id !== "string" || typeof data.poll_secret !== "string" || typeof data.verify_url !== "string") {
         console.warn("[gate] /v1/sessions returned 200 without required fields \u2014 falling back to bare denial");
         return void 0;
@@ -402,7 +433,13 @@ function createAgentScoreCore(options) {
     const cached = cache.get(cacheKey);
     if (cached) {
       if (cached.allow) {
-        return { kind: "allow", data: cached.raw };
+        const cachedRaw = cached.raw;
+        const cachedQuota = cachedRaw?.quota;
+        return {
+          kind: "allow",
+          data: cachedRaw,
+          ...cachedQuota !== void 0 && { quota: cachedQuota }
+        };
       }
       if (isFixableDenial(cached.reasons)) {
         const sessionReason = await tryMintSessionDenial(ctx);
@@ -419,130 +456,119 @@ function createAgentScoreCore(options) {
         }
       };
     }
+    const policy = {};
+    if (requireKyc != null) policy.require_kyc = requireKyc;
+    if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;
+    if (minAge != null) policy.min_age = minAge;
+    if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;
+    if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;
+    let data;
     try {
-      const body = {};
-      if (identity.address) body.address = identity.address;
-      if (identity.operatorToken) body.operator_token = identity.operatorToken;
-      if (gateChain) body.chain = gateChain;
-      const policy = {};
-      if (requireKyc != null) policy.require_kyc = requireKyc;
-      if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;
-      if (minAge != null) policy.min_age = minAge;
-      if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;
-      if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;
-      if (Object.keys(policy).length > 0) body.policy = policy;
-      const response = await fetch(`${baseUrl}/v1/assess`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (response.status === 402) {
+      const opts = {
+        chain: gateChain,
+        ...Object.keys(policy).length > 0 ? { policy } : {}
+      };
+      const result = identity.address ? await sdk.assess(identity.address, { ...opts, operatorToken: identity.operatorToken }) : await sdk.assess(null, { ...opts, operatorToken: identity.operatorToken });
+      data = result;
+    } catch (err) {
+      if (err instanceof PaymentRequiredError) {
         if (failOpen) return { kind: "allow" };
         return { kind: "deny", reason: { code: "payment_required" } };
       }
-      if (response.status === 401) {
-        try {
-          const errData = await response.clone().json();
-          const code = errData?.error?.code;
-          if (code === "token_expired") {
-            return {
-              kind: "deny",
-              reason: {
-                code,
-                data: errData,
-                ...typeof errData.verify_url === "string" ? { verify_url: errData.verify_url } : {},
-                ...typeof errData.session_id === "string" ? { session_id: errData.session_id } : {},
-                ...typeof errData.poll_secret === "string" ? { poll_secret: errData.poll_secret } : {},
-                ...typeof errData.poll_url === "string" ? { poll_url: errData.poll_url } : {},
-                ...errData.next_steps ? { agent_instructions: JSON.stringify(errData.next_steps) } : {},
-                ...errData.agent_memory ? { agent_memory: errData.agent_memory } : {}
-              }
-            };
-          }
-          if (code === "invalid_credential") {
-            return {
-              kind: "deny",
-              reason: {
-                code: "invalid_credential",
-                agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,
-                agent_memory: agentMemoryHint
-              }
-            };
-          }
-          if (code) {
-            console.warn(`[gate] /v1/assess returned 401 ${code} \u2014 no specific handler, surfacing as api_error.`);
+      if (err instanceof TokenExpiredError) {
+        return {
+          kind: "deny",
+          reason: {
+            code: "token_expired",
+            data: err.details,
+            ...err.verifyUrl ? { verify_url: err.verifyUrl } : {},
+            ...err.sessionId ? { session_id: err.sessionId } : {},
+            ...err.pollSecret ? { poll_secret: err.pollSecret } : {},
+            ...err.pollUrl ? { poll_url: err.pollUrl } : {},
+            ...err.nextSteps ? { agent_instructions: JSON.stringify(err.nextSteps) } : {},
+            ...err.agentMemory ? { agent_memory: err.agentMemory } : {}
           }
-        } catch (err) {
-          console.warn("[gate] /v1/assess 401 body parse failed:", err instanceof Error ? err.message : err);
-        }
+        };
       }
-      if (response.status >= 400 && response.status < 500 && response.status !== 402) {
-        try {
-          const errData = await response.clone().json();
-          const code = errData?.error?.code;
-          if (code && code !== "token_expired" && code !== "invalid_credential") {
-            console.warn(
-              `[gate] /v1/assess returned ${response.status} ${code} \u2014 surfacing as api_error. Validate input shape before invoking the gate to avoid this.`
-            );
+      if (err instanceof InvalidCredentialError) {
+        return {
+          kind: "deny",
+          reason: {
+            code: "invalid_credential",
+            agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,
+            agent_memory: agentMemoryHint
           }
-        } catch {
-        }
+        };
       }
-      if (!response.ok) {
-        throw new Error(`AgentScore API returned ${response.status}`);
+      if (err instanceof QuotaExceededError) {
+        console.warn("[gate] /v1/assess returned 429 quota_exceeded");
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "quota_exceeded" };
+        return {
+          kind: "deny",
+          reason: { code: "api_error", agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS }
+        };
       }
-      const data = await response.json();
-      const decision = data.decision;
-      const decisionReasons = data.decision_reasons ?? [];
-      const allow = decision === "allow" || decision == null;
-      cache.set(cacheKey, { allow, decision: decision ?? void 0, reasons: decisionReasons, raw: data });
-      if (allow) {
-        return { kind: "allow", data };
+      if (err instanceof SdkTimeoutError) {
+        console.warn("[gate] /v1/assess timed out:", err.message);
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "network_timeout" };
+        return { kind: "deny", reason: { code: "api_error" } };
       }
-      if (isFixableDenial(decisionReasons)) {
-        const sessionReason = await tryMintSessionDenial(ctx);
-        if (sessionReason) return { kind: "deny", reason: sessionReason };
+      const status = err?.status;
+      const errName = err instanceof Error ? err.name : "";
+      if (status === 429) {
+        console.warn("[gate] /v1/assess returned 429 (untyped \u2014 defensive)");
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "quota_exceeded" };
+        return {
+          kind: "deny",
+          reason: { code: "api_error", agent_instructions: QUOTA_EXCEEDED_INSTRUCTIONS }
+        };
+      }
+      if (errName === "TimeoutError" || errName === "AbortError") {
+        console.warn("[gate] /v1/assess timed out (by Error.name):", err instanceof Error ? err.message : err);
+        if (failOpen) return { kind: "allow", degraded: true, infraReason: "network_timeout" };
+        return { kind: "deny", reason: { code: "api_error" } };
       }
+      const errCode = err?.code;
+      const msg = err instanceof Error ? err.message : String(err);
+      const detail = errCode ? `${errCode}: ${msg}` : msg;
+      console.warn(`[gate] /v1/assess call failed \u2014 surfacing as api_error: ${detail}`);
+      if (failOpen) return { kind: "allow", degraded: true, infraReason: "api_error" };
+      return { kind: "deny", reason: { code: "api_error" } };
+    }
+    const decision = data.decision;
+    const decisionReasons = data.decision_reasons ?? [];
+    const allow = decision === "allow" || decision == null;
+    cache.set(cacheKey, { allow, decision: decision ?? void 0, reasons: decisionReasons, raw: data });
+    if (allow) {
+      const quota = data.quota;
       return {
-        kind: "deny",
-        reason: {
-          code: "wallet_not_trusted",
-          decision: decision ?? void 0,
-          reasons: decisionReasons,
-          verify_url: data.verify_url,
-          data
-        }
+        kind: "allow",
+        data,
+        ...quota !== void 0 && { quota }
       };
-    } catch (err) {
-      console.warn("[gate] /v1/assess call failed \u2014 surfacing as api_error:", err instanceof Error ? err.message : err);
-      if (failOpen) return { kind: "allow" };
-      return { kind: "deny", reason: { code: "api_error" } };
     }
+    if (isFixableDenial(decisionReasons)) {
+      const sessionReason = await tryMintSessionDenial(ctx);
+      if (sessionReason) return { kind: "deny", reason: sessionReason };
+    }
+    return {
+      kind: "deny",
+      reason: {
+        code: "wallet_not_trusted",
+        decision: decision ?? void 0,
+        reasons: decisionReasons,
+        verify_url: data.verify_url,
+        data
+      }
+    };
   }
   async function captureWallet2(options2) {
     try {
-      const body = {
-        operator_token: options2.operatorToken,
-        wallet_address: options2.walletAddress,
-        network: options2.network
-      };
-      if (options2.idempotencyKey) body.idempotency_key = options2.idempotencyKey;
-      await fetch(`${baseUrl}/v1/credentials/wallets`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      await sdk.associateWallet({
+        operatorToken: options2.operatorToken,
+        walletAddress: options2.walletAddress,
+        network: options2.network,
+        ...options2.idempotencyKey ? { idempotencyKey: options2.idempotencyKey } : {}
       });
     } catch (err) {
       console.warn("[agentscore-commerce] captureWallet failed:", err instanceof Error ? err.message : err);
@@ -567,19 +593,7 @@ function createAgentScoreCore(options) {
       return { ok: true, ...extractFromCached(resolveCached.raw) };
     }
     try {
-      const response = await fetch(`${baseUrl}/v1/assess`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify({ address: walletAddress }),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (!response.ok) return { ok: false };
-      const data = await response.json();
+      const data = await sdk.assess(walletAddress);
       cache.set(`resolve:${wallet}`, { allow: true, raw: data });
       return { ok: true, ...extractFromCached(data) };
     } catch (err) {
@@ -588,28 +602,37 @@ function createAgentScoreCore(options) {
     }
   }
   function reportSignerEvent(kind) {
-    try {
-      const pending = fetch(`${baseUrl}/v1/telemetry/signer-match`, {
-        method: "POST",
-        headers: {
-          "X-API-Key": apiKey,
-          "Content-Type": "application/json",
-          Accept: "application/json",
-          "User-Agent": userAgentHeader
-        },
-        body: JSON.stringify({ kind }),
-        signal: AbortSignal.timeout(API_TIMEOUT_MS)
-      });
-      if (pending && typeof pending.catch === "function") {
-        pending.catch((err) => {
-          console.warn("[agentscore-commerce] signer-match telemetry failed:", err instanceof Error ? err.message : err);
-        });
-      }
-    } catch {
+    void sdk.telemetrySignerMatch({ kind });
+  }
+  function projectSignerMatch(sm, claimedNorm, signerNorm) {
+    const kind = sm.kind;
+    if (kind === "pass") {
+      return {
+        kind: "pass",
+        claimedOperator: sm.claimed_operator ?? null,
+        signerOperator: sm.signer_operator ?? null
+      };
     }
+    if (kind === "wallet_auth_requires_wallet_signing") {
+      return {
+        kind: "wallet_auth_requires_wallet_signing",
+        claimedWallet: sm.claimed_wallet ?? claimedNorm,
+        agentInstructions: sm.agent_instructions ?? WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS
+      };
+    }
+    const linked = sm.linked_wallets;
+    return {
+      kind: "wallet_signer_mismatch",
+      claimedOperator: sm.claimed_operator ?? null,
+      actualSignerOperator: sm.signer_operator ?? null,
+      expectedSigner: sm.expected_signer ?? claimedNorm,
+      actualSigner: sm.actual_signer ?? signerNorm,
+      linkedWallets: Array.isArray(linked) ? linked.filter((w) => typeof w === "string") : [],
+      agentInstructions: sm.agent_instructions ?? WALLET_SIGNER_MISMATCH_INSTRUCTIONS
+    };
   }
   async function verifyWalletSignerMatch2(options2) {
-    const { claimedWallet, signer } = options2;
+    const { claimedWallet, signer, network } = options2;
     if (!signer) {
       reportSignerEvent("wallet_auth_requires_wallet_signing");
       return {
@@ -624,6 +647,35 @@ function createAgentScoreCore(options) {
       reportSignerEvent("pass");
       return { kind: "pass", claimedOperator: null, signerOperator: null };
     }
+    const cachedEntry = cache.get(claimedNorm);
+    const cachedMatch = cachedEntry?.signerMatchBySigner?.get(signerNorm);
+    if (cachedMatch) {
+      return projectSignerMatch(cachedMatch, claimedNorm, signerNorm);
+    }
+    const inferredNetwork = network ?? (signerNorm.startsWith("0x") ? "evm" : "solana");
+    let assessResponse;
+    try {
+      assessResponse = await sdk.assess(claimedNorm, {
+        resolveSigner: { address: signerNorm, network: inferredNetwork }
+      });
+    } catch (err) {
+      console.warn("[gate] verifyWalletSignerMatch assess failed:", err instanceof Error ? err.message : err);
+      reportSignerEvent("api_error");
+      return { kind: "api_error", claimedWallet: claimedNorm };
+    }
+    const signerMatch = assessResponse.signer_match;
+    if (signerMatch && typeof signerMatch === "object") {
+      if (cachedEntry) {
+        const map = cachedEntry.signerMatchBySigner ?? /* @__PURE__ */ new Map();
+        map.set(signerNorm, signerMatch);
+        cachedEntry.signerMatchBySigner = map;
+      } else {
+        const entry = { allow: true, raw: assessResponse };
+        entry.signerMatchBySigner = /* @__PURE__ */ new Map([[signerNorm, signerMatch]]);
+        cache.set(claimedNorm, entry);
+      }
+      return projectSignerMatch(signerMatch, claimedNorm, signerNorm);
+    }
     const [claimedResolve, signerResolve] = await Promise.all([
       resolveWalletToOperator(claimedNorm),
       resolveWalletToOperator(signerNorm)
@@ -645,8 +697,6 @@ function createAgentScoreCore(options) {
       actualSignerOperator: signerOperator,
       expectedSigner: claimedNorm,
       actualSigner: signerNorm,
-      // Populated from /v1/assess.linked_wallets on the claimed wallet — the full set of
-      // wallets the agent CAN sign with to satisfy the claim (same-operator rule).
       linkedWallets: claimedResolve.linkedWallets,
       agentInstructions: WALLET_SIGNER_MISMATCH_INSTRUCTIONS
     };
@@ -739,6 +789,14 @@ function agentscoreGate(options) {
     });
     const outcome = await core.evaluate(identity, c);
     if (outcome.kind === "allow") {
+      if (outcome.degraded || outcome.quota) {
+        const prev = c.get(GATE_STATE_KEY);
+        c.set(GATE_STATE_KEY, {
+          ...prev,
+          ...outcome.degraded && { degraded: true, infraReason: outcome.infraReason },
+          ...outcome.quota && { quota: outcome.quota }
+        });
+      }
       if (outcome.data) c.set(CONTEXT_KEY, outcome.data);
       await next();
       return;
@@ -749,6 +807,14 @@ function agentscoreGate(options) {
 function getAgentScoreData(c) {
   return c.get(CONTEXT_KEY);
 }
+function getGateDegradedState(c) {
+  const state = c.get(GATE_STATE_KEY);
+  return { degraded: state?.degraded ?? false, infraReason: state?.infraReason };
+}
+function getGateQuotaInfo(c) {
+  const state = c.get(GATE_STATE_KEY);
+  return state?.quota;
+}
 async function captureWallet(c, options) {
   const state = c.get(GATE_STATE_KEY);
   if (!state?.operatorToken) return;
@@ -781,6 +847,8 @@ export {
   denialReasonToBody,
   extractPaymentSignerAddress,
   getAgentScoreData,
+  getGateDegradedState,
+  getGateQuotaInfo,
   isFixableDenial,
   readX402PaymentHeader,
   verificationAgentInstructions,