@forgeintel/sdk 0.4.0-beta.1 → 0.5.0-alpha.oldfeedback.1.b13

package/dist/core.js

@@ -1,17 +1,20 @@
+import { randomUUID } from "node:crypto";
 // Framework-free Forge logic. Adapters (express.ts, later fetch.ts) translate their request/response
 // objects to the small interfaces below and write out what the core returns.
 import { DEFAULT_TTL_MS, deriveSigningKey, mintFeedbackId, verifyFeedbackId } from "./id.js";
 import { createOperationIndex, enrichOpenApi } from "./openapi.js";
 import { ASK, TONES, checkAskText } from "./ask.js";
-import { agentContextAsk, parseAgentContext, takeFromBody, takeFromUrl } from "./context.js";
+import { agentContextAsk, contextIssues, parseAgentContext, takeFromBody, takeFromUrl } from "./context.js";
 import { EventReporter } from "./reporter.js";
+import { captureClientHeaders } from "./client-signals.js";
 import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL, parseSubmission } from "./values.js";
-import { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, readPaymentHeader, readReceipt, receiptExtension } from "./x402.js";
+import { FEEDBACK_FIELD, challengeOrigin, describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, paymentOrigin, readPaymentHeader, readReceipt, receiptExtension } from "./x402.js";
 export const FEEDBACK_HEADERS = { "Cache-Control": "no-store", "X-Robots-Tag": "noindex" };
 /** Max JSON body for POST {basePath}. */
 export const BODY_LIMIT = 8 * 1024;
 /** Max OpenAPI document an adapter should buffer for enrichment. */
 export const SPEC_LIMIT = 10 * 1024 * 1024;
+export const DEFAULT_BACKEND_URL = "https://app-api.forgeintel.co/api/sdk/v2";
 /**
  * Check options without throwing. Invalid required options are errors (Forge runs disabled);
  * invalid optional values are warnings and fall back to their defaults.
@@ -34,10 +37,12 @@ export function checkOptions(input) {
     };
     if (typeof raw.apiKey !== "string" || !raw.apiKey.trim())
         errors.push("apiKey is missing (set it to your merchant key, ffk_…)");
-    if (!absoluteUrl(raw.backendUrl))
+    if (raw.backendUrl === undefined)
+        options.backendUrl = DEFAULT_BACKEND_URL;
+    else if (!absoluteUrl(raw.backendUrl))
         errors.push(`backendUrl must be an absolute http(s) URL (got ${JSON.stringify(raw.backendUrl ?? null)})`);
-    if (!absoluteUrl(raw.publicUrl))
-        errors.push(`publicUrl must be an absolute http(s) URL, this service's public origin (got ${JSON.stringify(raw.publicUrl ?? null)})`);
+    if (raw.publicUrl !== undefined && !absoluteUrl(raw.publicUrl))
+        errors.push(`publicUrl must be an absolute http(s) URL (got ${JSON.stringify(raw.publicUrl ?? null)})`);
     const fallback = (key, ok, expected) => {
         if (raw[key] === undefined || ok)
             return;
@@ -59,8 +64,16 @@ export function checkOptions(input) {
     fallback("tone", TONES.includes(raw.tone), `must be one of ${TONES.map((t) => `"${t}"`).join(", ")}`);
     fallback("challengeSentence", typeof raw.challengeSentence === "string" && raw.challengeSentence.trim() !== "", "must be a non-empty string");
     fallback("rateHint", boolean(raw.rateHint) || typeof raw.rateHint === "string", "must be a boolean or a string");
-    fallback("agentContext", boolean(raw.agentContext) || (!!raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)), "must be true, false or { searchQuery }");
-    for (const key of ["describeChallenges", "challengeExtension", "receiptExtension", "injectBody", "injectText", "strict"])
+    fallback("agentContext", boolean(raw.agentContext) || (!!raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)), "must be true, false or { searchQuery, required }");
+    if (raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)) {
+        const context = raw.agentContext;
+        for (const key of ["required", "searchQuery"]) {
+            if (context[key] !== undefined && typeof context[key] !== "boolean") {
+                errors.push(`agentContext.${key} must be a boolean`);
+            }
+        }
+    }
+    for (const key of ["feedback", "describeChallenges", "challengeExtension", "receiptExtension", "injectBody", "injectText", "strict"])
         fallback(key, boolean(raw[key]), "must be true or false");
     // The lines no wording may cross, whatever the merchant configures (see ask.ts).
     for (const key of ["challengeSentence", "rateHint"]) {
@@ -91,15 +104,20 @@ export function checkOptions(input) {
     }
     return { errors, warnings, options };
 }
-/** Everything passes through untouched. Used when invalid options turned Forge off. */
+/**
+ * Used when invalid options turned Forge off: nothing is recorded or added, but agent context is still removed from
+ * requests, so agents that learned about it (an earlier deploy, a cached listing) can't trip strict validators.
+ */
 function disabledCore(errors, warnings) {
     const passThrough = {
         feedbackId: undefined,
+        contextRequired: false,
+        contextError: () => null,
         json: (_status, body) => body,
         text: (_status, _type, body) => body,
         headers: () => ({}),
-        requestBody: (body) => body,
-        requestUrl: (url) => url,
+        requestBody: (body) => takeFromBody(body).body,
+        requestUrl: (url) => takeFromUrl(url).url,
         finish: () => { },
     };
     return {
@@ -142,26 +160,36 @@ export function createForgeCore(input) {
     }
 }
 function enabledCore(options, configWarnings) {
-    const { apiKey, backendUrl, publicUrl } = options;
+    const { apiKey, publicUrl } = options;
+    const backendUrl = options.backendUrl ?? DEFAULT_BACKEND_URL;
     // Feedback IDs are signed with a key derived from the API key, never with the API key itself.
     const signingKey = deriveSigningKey(apiKey);
     const backendPath = new URL(backendUrl).pathname.replace(/\/+$/, "") || "/v1";
     const backend = (name) => new URL(`${backendPath}/${name}`, backendUrl).href;
     const basePath = (options.basePath ?? "/feedback").replace(/\/+$/, "");
     const ratePath = `${basePath}/rate`;
-    const rateUrl = new URL(ratePath, publicUrl).href;
-    const formUrl = new URL(basePath, publicUrl).href;
     const summaryPath = `${basePath}/summary`;
-    const summaryUrl = new URL(summaryPath, publicUrl).href;
+    // Rating links are absolute whenever an origin is known: publicUrl, else the origin registered in Forge
+    // (fetched in the background, never on the request path), else the origin of the request's own x402 resource.
+    const explicitOrigin = publicUrl ? new URL(publicUrl).origin : undefined;
+    let registeredOrigin;
+    const linksFor = (requestOrigin) => {
+        const base = explicitOrigin ?? registeredOrigin ?? requestOrigin;
+        const at = (path) => (base ? new URL(path, base).href : path);
+        return { rate: at(ratePath), form: at(basePath), summary: at(summaryPath) };
+    };
     const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
     const fetchImpl = options.fetch ?? fetch;
-    const describe = options.describeChallenges ?? true;
+    const feedback = options.feedback !== false;
+    const describe = feedback && (options.describeChallenges ?? true);
     const injectBody = options.injectBody ?? true;
     const injectText = options.injectText ?? false;
     const tone = options.tone ?? "soft";
-    const contextOption = options.agentContext ?? true;
+    const contextOption = options.agentContext;
     const collectContext = contextOption !== false;
     const searchQuery = collectContext && (typeof contextOption !== "object" || contextOption.searchQuery !== false);
+    // Optional unless configured: true, or an object without required: false, keeps the strict (400) behavior.
+    const requiredContext = contextOption === true || (typeof contextOption === "object" && contextOption.required !== false);
     const receipts = options.receiptExtension ?? true;
     const rateHint = options.rateHint === false
         ? null
@@ -186,27 +214,48 @@ function enabledCore(options, configWarnings) {
             lastLogged = message;
         });
     const reporter = new EventReporter(backend("events"), apiKey, fetchImpl, onError, options.flushIntervalMs ?? 2000);
-    const challengeSentence = (options.challengeSentence ?? ASK[tone].challengeSentence).replaceAll("{rate_url}", rateUrl).replaceAll("{summary_url}", summaryUrl);
-    // Idempotency marker: the rate URL when the sentence contains it, otherwise the sentence itself.
-    const challengeMarker = challengeSentence.includes(rateUrl) ? rateUrl : challengeSentence;
-    const challengeAdditions = {
-        ...(describe ? { sentence: challengeSentence, marker: challengeMarker } : {}),
-        ...(options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery }) : undefined) }),
-    };
-    const touchChallenges = Boolean(challengeAdditions.sentence || challengeAdditions.extension);
+    const sentenceTemplate = options.challengeSentence ?? ASK[tone].challengeSentence;
+    // Idempotency marker: the rate path, which every described challenge contains whatever origin its link uses.
+    const describedBy = (sentence, rate) => (sentence.includes(rate) ? ratePath : sentence);
+    const sentenceFor = (links) => feedback ? sentenceTemplate.replaceAll("{rate_url}", links.rate).replaceAll("{summary_url}", links.summary) : "";
+    const additionsCache = new Map();
+    function challengeAdditions(requestOrigin) {
+        const links = linksFor(requestOrigin);
+        const cached = additionsCache.get(links.rate);
+        if (cached)
+            return cached;
+        const sentence = sentenceFor(links);
+        const marker = describedBy(sentence, links.rate);
+        const additions = {
+            ...(describe ? { sentence, marker, ...(marker === ratePath ? { shortSentence: ASK[tone].shortChallengeSentence.replaceAll("{rate_url}", links.rate) } : {}) } : {}),
+            ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(links.rate, tone) }),
+        };
+        if (collectContext)
+            additions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery, required: requiredContext }), optional: !requiredContext } };
+        if (collectContext)
+            additions.bazaarContext = { searchQuery, required: requiredContext };
+        if (additionsCache.size >= 16)
+            additionsCache.clear(); // one entry per origin; bounded against spoofed Host headers
+        additionsCache.set(links.rate, additions);
+        return additions;
+    }
+    const touchChallenges = Boolean((describe && feedback) || (feedback && options.challengeExtension !== false) || collectContext);
     // Set once a document has been enriched; lets body injection respect strict response schemas.
     let allowInjection = null;
     let lastWarnings = "";
     function enrich(document) {
+        const links = linksFor();
+        const sentence = sentenceFor(links);
         const result = enrichOpenApi(document, {
-            publicUrl,
+            publicUrl: explicitOrigin ?? registeredOrigin,
+            feedback,
             basePath,
-            sentence: challengeSentence,
-            marker: challengeMarker,
+            sentence,
+            marker: describedBy(sentence, links.rate),
             isPaidOperation: openapi?.isPaidOperation,
             describeOperations: openapi?.describeOperations,
             hintField: Boolean(rateHint),
-            agentContext: collectContext ? { searchQuery } : undefined,
+            agentContext: collectContext ? { searchQuery, required: requiredContext } : undefined,
         });
         stats.openapi = result.report;
         if (result.report.enriched)
@@ -221,30 +270,65 @@ function enabledCore(options, configWarnings) {
     // With interception or an async provider, that starts once the spec has been served.
     if (openapi && openapi.document !== undefined && typeof openapi.document !== "function")
         enrich(openapi.document);
-    const form = {
-        protocol: PROTOCOL,
-        cost: "free",
-        ratings_are_public_at: summaryUrl,
-        feedback_id: "Returned by paid responses as the feedback_id body field and the Forge-Feedback-Id header.",
-        quick: { method: "GET", url: `${rateUrl}?feedback_id=FEEDBACK_ID&outcome=OUTCOME`, optional_param: "issue=ISSUE" },
-        detailed: {
-            method: "POST",
-            url: formUrl,
-            content_type: "application/json",
-            body: { feedback_id: "FEEDBACK_ID", outcome: "OUTCOME", issue: "ISSUE (optional)", note: `NOTE (optional, max ${NOTE_MAX_LENGTH} chars, no user data)` },
-        },
-        fields: {
-            outcome: { required: true, values: OUTCOMES },
-            issue: { required: false, values: ISSUES },
-            note: { required: false, max_length: NOTE_MAX_LENGTH, post_only: true },
-        },
+    const formDoc = () => {
+        const links = linksFor();
+        return {
+            protocol: PROTOCOL,
+            cost: "free",
+            ratings_are_public_at: links.summary,
+            feedback_id: `Returned by paid responses in the ${FEEDBACK_FIELD} body object (feedback_id) and the Forge-Feedback-Id header.`,
+            quick: { method: "GET", url: `${links.rate}?feedback_id=FEEDBACK_ID&outcome=OUTCOME`, optional_param: "issue=ISSUE" },
+            detailed: {
+                method: "POST",
+                url: links.form,
+                content_type: "application/json",
+                body: { feedback_id: "FEEDBACK_ID", outcome: "OUTCOME", issue: "ISSUE (optional)", note: `NOTE (optional, max ${NOTE_MAX_LENGTH} chars, no user data)` },
+            },
+            fields: {
+                outcome: { required: true, values: OUTCOMES },
+                issue: { required: false, values: ISSUES },
+                note: { required: false, max_length: NOTE_MAX_LENGTH, post_only: true },
+            },
+        };
     };
+    // The origin registered in Forge, fetched in the background on first use and refreshed every few hours.
+    // Requests never wait on it; until it arrives, links fall back to the request's own resource origin.
+    let originCheckedAt = -Infinity;
+    const ORIGIN_REFRESH_MS = 6 * 3600_000;
+    function refreshRegisteredOrigin() {
+        if (explicitOrigin || Date.now() - originCheckedAt < ORIGIN_REFRESH_MS)
+            return;
+        originCheckedAt = Date.now();
+        void (async () => {
+            try {
+                const response = await fetchImpl(backend("project"), {
+                    headers: { Authorization: `Bearer ${apiKey}` },
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (!response.ok)
+                    return;
+                const origin = (await response.json())?.publicOrigin;
+                if (typeof origin !== "string" || !origin.startsWith("https://"))
+                    return;
+                const next = new URL(origin).origin;
+                if (next === registeredOrigin)
+                    return;
+                registeredOrigin = next;
+                additionsCache.clear();
+                if (openapi && openapi.document !== undefined && typeof openapi.document !== "function")
+                    enrich(openapi.document);
+            }
+            catch {
+                // Offline, older backend, or blocked: keep the fallbacks.
+            }
+        })();
+    }
     const reply = (status, body, headers = FEEDBACK_HEADERS) => body === undefined ? { status, headers } : { status, headers, body };
     const badRequest = (error) => reply(400, {
         recorded: false,
         error,
         allowed: { outcome: Object.keys(OUTCOMES), issue: Object.keys(ISSUES) },
-        example: `${rateUrl}?feedback_id=FEEDBACK_ID&outcome=fully`,
+        example: `${linksFor().rate}?feedback_id=FEEDBACK_ID&outcome=fully`,
     });
     async function submit(request, input, via) {
         const parsed = parseSubmission(input, { allowNote: via === "POST" });
@@ -258,7 +342,7 @@ function enabledCore(options, configWarnings) {
             const upstream = await fetchImpl(backend("feedback"), {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
-                body: JSON.stringify({ ...parsed.value, via, user_agent: request.header("user-agent") ?? null }),
+                body: JSON.stringify({ ...parsed.value, via, user_agent: request.header("user-agent") ?? null, request_headers: captureClientHeaders((name) => request.header(name)) }),
                 signal: AbortSignal.timeout(3000),
             });
             const body = await upstream.json().catch(() => ({ recorded: false, error: "feedback_unavailable" }));
@@ -288,6 +372,7 @@ function enabledCore(options, configWarnings) {
         return reply(summaryCache.status, summaryCache.body, { "Cache-Control": "public, max-age=30" });
     }
     async function route(request) {
+        refreshRegisteredOrigin();
         try {
             return await handleRoute(request);
         }
@@ -299,9 +384,9 @@ function enabledCore(options, configWarnings) {
     }
     async function handleRoute(request) {
         const { method, path } = request;
-        if (path === basePath) {
+        if (feedback && path === basePath) {
             if (method === "GET" || method === "HEAD")
-                return reply(200, form);
+                return reply(200, formDoc());
             if (method === "POST") {
                 let body;
                 try {
@@ -315,23 +400,29 @@ function enabledCore(options, configWarnings) {
                 return submit(request, body, "POST");
             }
         }
-        if (path === summaryPath && (method === "GET" || method === "HEAD"))
+        if (feedback && path === summaryPath && (method === "GET" || method === "HEAD"))
             return summary();
-        if (path === ratePath) {
+        if (feedback && path === ratePath) {
             // HEAD and other methods must never record a rating (link checkers send HEAD).
             if (method !== "GET")
                 return reply(405, undefined, { ...FEEDBACK_HEADERS, Allow: "GET" });
             const first = (v) => (Array.isArray(v) ? v[0] : v);
             return submit(request, { feedback_id: first(request.query("feedback_id")), outcome: first(request.query("outcome")), issue: first(request.query("issue")) }, "GET");
         }
-        if (openapi && openapi.document !== undefined && method === "GET" && specPaths.has(path)) {
-            const source = typeof openapi.document === "function" ? await openapi.document() : openapi.document;
-            return reply(200, enrich(source).document, { "Cache-Control": "no-store" });
+        if (openapi && method === "GET" && specPaths.has(path)) {
+            const requestHeaders = captureClientHeaders((name) => request.header(name));
+            reporter.push({ type: "discovery", route: `${method} ${path}`, ts: Date.now(), user_agent: requestHeaders?.["user-agent"], request_headers: requestHeaders });
+            if (openapi.document !== undefined) {
+                const source = typeof openapi.document === "function" ? await openapi.document() : openapi.document;
+                return reply(200, enrich(source).document, { "Cache-Control": "no-store" });
+            }
         }
         return null;
     }
     const passThrough = {
         feedbackId: undefined,
+        contextRequired: false,
+        contextError: () => null,
         json: (_status, body) => body,
         text: (_status, _type, body) => body,
         headers: () => ({}),
@@ -352,18 +443,26 @@ function enabledCore(options, configWarnings) {
         const started = Date.now();
         const route = `${request.method} ${request.path}`;
         const userAgent = request.header("user-agent") ?? undefined;
+        const requestHeaders = captureClientHeaders((name) => request.header(name));
         const paymentHeader = request.header("payment-signature") ?? request.header("x-payment"); // x402 v2 / v1
-        const feedbackId = paymentHeader ? mintFeedbackId(signingKey) : undefined;
+        const feedbackId = feedback && paymentHeader ? mintFeedbackId(signingKey) : undefined;
+        const interactionId = paymentHeader && !feedback ? randomUUID() : undefined;
         if (feedbackId)
             stats.minted++;
-        const feedbackUrl = feedbackId ? `${rateUrl}?feedback_id=${feedbackId}&outcome=` : "";
+        refreshRegisteredOrigin();
+        // Links in this paid response use the origin the payment was made for when none is configured or registered.
+        const callLinks = feedbackId ? linksFor(paymentOrigin(paymentHeader)) : undefined;
+        const feedbackUrl = callLinks ? `${callLinks.rate}?feedback_id=${feedbackId}&outcome=` : "";
         let bodyChallenge = false;
         let headerChallenge = false;
         let context;
+        let rawContext = {};
         let receiptFacts = {};
         const remember = (raw) => {
             if (!collectContext)
                 return;
+            if (raw && typeof raw === "object" && !Array.isArray(raw))
+                rawContext = { ...rawContext, ...raw };
             const parsed = parseAgentContext(raw, { searchQuery });
             if (parsed)
                 context = { ...context, ...parsed };
@@ -371,12 +470,24 @@ function enabledCore(options, configWarnings) {
         const ok = (status) => status >= 200 && status < 300;
         const handle = {
             feedbackId,
+            contextRequired: requiredContext && !!paymentHeader,
+            contextError() {
+                if (!handle.contextRequired)
+                    return null;
+                const issues = contextIssues(rawContext, { searchQuery });
+                return issues.length ? {
+                    status: 400, headers: {}, body: {
+                        error: "agent_context_required", issues,
+                        message: agentContextAsk({ searchQuery, required: true }),
+                    },
+                } : null;
+            },
             json(status, body) {
                 try {
                     if (status === 402) {
                         bodyChallenge = !!body && typeof body === "object" && "x402Version" in body;
                         // v1 challenges (and v2 challenges echoed in the body) live in the JSON body.
-                        const described = touchChallenges ? describeChallengeBody(body, challengeAdditions) : undefined;
+                        const described = touchChallenges ? describeChallengeBody(body, challengeAdditions(challengeOrigin(body))) : undefined;
                         if (described) {
                             stats.challengesDescribed++;
                             return described;
@@ -388,15 +499,16 @@ function enabledCore(options, configWarnings) {
                         body !== null &&
                         typeof body === "object" &&
                         Object.getPrototypeOf(body) === Object.prototype &&
-                        !("feedback_id" in body) &&
-                        !("feedback_url" in body) &&
-                        !(rateHint && "rate_this_call" in body) &&
+                        !(FEEDBACK_FIELD in body) &&
                         (allowInjection?.(request.method, request.path, status) ?? true)) {
+                        // One namespaced object, so the merchant's own fields stay recognizably theirs.
                         return {
                             ...body,
-                            feedback_id: feedbackId,
-                            feedback_url: feedbackUrl,
-                            ...(rateHint ? { rate_this_call: rateHint.replaceAll("{feedback_url}", feedbackUrl).replaceAll("{summary_url}", summaryUrl) } : {}),
+                            [FEEDBACK_FIELD]: {
+                                feedback_id: feedbackId,
+                                feedback_url: feedbackUrl,
+                                ...(rateHint ? { rate_this_call: rateHint.replaceAll("{feedback_url}", feedbackUrl).replaceAll("{summary_url}", callLinks.summary) } : {}),
+                            },
                         };
                     }
                 }
@@ -418,17 +530,17 @@ function enabledCore(options, configWarnings) {
                     if (status === 402 && paymentRequired)
                         headerChallenge = true;
                     if (status === 402 && touchChallenges && paymentRequired) {
-                        const next = describeChallenge(paymentRequired, challengeAdditions);
+                        const next = describeChallenge(paymentRequired, challengeAdditions(challengeOrigin(paymentRequired)));
                         if (next) {
                             set["PAYMENT-REQUIRED"] = next;
                             stats.challengesDescribed++;
                         }
                     }
+                    if (paymentHeader && ok(status) && paymentResponse)
+                        receiptFacts = readReceipt(paymentResponse);
                     if (feedbackId && ok(status)) {
                         set["Forge-Feedback-Id"] = feedbackId;
-                        if (paymentResponse)
-                            receiptFacts = readReceipt(paymentResponse);
-                        const receipt = receipts && paymentResponse ? describeReceipt(paymentResponse, receiptExtension(rateUrl, feedbackId, tone)) : undefined;
+                        const receipt = receipts && paymentResponse ? describeReceipt(paymentResponse, receiptExtension(callLinks.rate, feedbackId, tone)) : undefined;
                         if (receipt)
                             set["PAYMENT-RESPONSE"] = receipt;
                     }
@@ -475,19 +587,20 @@ function enabledCore(options, configWarnings) {
             const ts = Date.now();
             if (status === 402 && (hadChallengeHeader || headerChallenge || bodyChallenge)) {
                 // v2 carries the challenge in a header; v1 in the body. Both count as a challenge.
-                reporter.push({ type: "challenge", route, ts, user_agent: userAgent, ...(context ? { agent_context: context } : {}) });
+                reporter.push({ type: "challenge", route, ts, user_agent: userAgent, request_headers: requestHeaders, ...(context ? { agent_context: context } : {}) });
             }
-            if (feedbackId) {
+            if (feedbackId || interactionId) {
                 const facts = { ...readPaymentHeader(paymentHeader), ...receiptFacts };
                 reporter.push({
                     type: "interaction",
-                    feedback_id: feedbackId,
+                    ...(feedbackId ? { feedback_id: feedbackId } : { interaction_id: interactionId }),
                     route,
                     status,
                     latency_ms: ts - started,
                     // Only report the payer once the call succeeded (i.e. settlement went through).
                     ...(ok(status) ? facts : { network: facts.network, amount: facts.amount }),
                     user_agent: userAgent,
+                    request_headers: requestHeaders,
                     ...(context ? { agent_context: context } : {}),
                     ts,
                 });
@@ -497,7 +610,9 @@ function enabledCore(options, configWarnings) {
     }
     return {
         enabled: true,
-        challengeSentence,
+        get challengeSentence() {
+            return sentenceFor(linksFor());
+        },
         route,
         isSpecRequest: (method, path) => Boolean(openapi) && method === "GET" && specPaths.has(path),
         enrichOpenApi: enrich,

package/dist/express.js

@@ -1,3 +1,5 @@
+// Express adapter (4.21+ and 5): wires the framework-free core into req/res.
+import express from "express";
 import { CONTEXT_QUERY } from "./context.js";
 import { BODY_LIMIT, SPEC_LIMIT, createForgeCore } from "./core.js";
 /** Never throws (unless `strict`): with invalid options it warns and returns a middleware that only calls next(). */
@@ -124,7 +126,7 @@ export function createForge(options) {
             },
         });
     }
-    function observe(req, res) {
+    async function observe(req, res) {
         const call = core.call({ method: req.method, path: req.originalUrl.split("?")[0], header: (name) => req.get(name) });
         try {
             takeAgentContext(req, call);
@@ -132,6 +134,24 @@ export function createForge(options) {
         catch (error) {
             core.onError(error);
         }
+        if (call.contextRequired) {
+            // Required context: parse before payment middleware even when the merchant mounts express.json later.
+            // The body setter above captures context and leaves only merchant fields in req.body.
+            const parseError = await new Promise((resolve) => {
+                express.json({ limit: "1mb", type: ["application/json", "application/*+json"] })(req, res, resolve);
+            });
+            if (parseError) {
+                call.finish(400);
+                send(res, { status: 400, headers: {}, body: { error: "agent_context_invalid", message: "Send valid JSON up to 1 MiB with agent_context, or use agent_type and agent_search_query query parameters with a non-JSON body." } });
+                return false;
+            }
+            const invalid = call.contextError();
+            if (invalid) {
+                call.finish(invalid.status);
+                send(res, invalid);
+                return false;
+            }
+        }
         const originalJson = res.json.bind(res);
         res.json = ((body) => originalJson(call.json(res.statusCode, body)));
         if (call.feedbackId) {
@@ -173,6 +193,7 @@ export function createForge(options) {
             return originalWriteHead.call(this, statusCode, ...rest);
         };
         res.on("finish", () => call.finish(res.statusCode, Boolean(res.getHeader("payment-required"))));
+        return true;
     }
     return {
         enabled: core.enabled,
@@ -181,8 +202,18 @@ export function createForge(options) {
         diagnostics: core.diagnostics,
         shutdown: core.shutdown,
         middleware() {
-            if (!core.enabled)
-                return (_req, _res, next) => next();
+            if (!core.enabled) {
+                // Disabled by invalid options: only remove agent context, so strict validators never see it.
+                return (req, _res, next) => {
+                    try {
+                        takeAgentContext(req, core.call({ method: req.method, path: req.path, header: () => undefined }));
+                    }
+                    catch {
+                        // never break the business request
+                    }
+                    next();
+                };
+            }
             return (req, res, next) => {
                 core
                     .route({
@@ -192,14 +223,14 @@ export function createForge(options) {
                     query: (name) => req.query[name],
                     json: () => readJsonBody(req),
                 })
-                    .then((response) => {
+                    .then(async (response) => {
                     if (response)
                         return send(res, response);
                     try {
                         if (core.isSpecRequest(req.method, req.path))
                             captureSpec(req, res);
-                        else
-                            observe(req, res);
+                        else if (!await observe(req, res))
+                            return;
                     }
                     catch (error) {
                         core.onError(error); // never break the business request

package/dist/fetch.d.ts

@@ -5,9 +5,11 @@ export interface ForgeFetch extends Pick<ForgeCore, "enabled" | "challengeSenten
     /**
      * Run one request through Forge around `next` (your handler, including your x402 payment middleware).
      * Answers Forge's own routes, removes agent context from the request, and decorates the 402 and the paid response.
-     * Fails open: on any internal error the request reaches `next` unchanged, or its response is returned unchanged.
+     * Fails open by default. Required-context validation intentionally rejects invalid paid attempts before `next`.
      */
     handle(request: Request, next: Next): Promise<Response>;
+    /** Check required context without consuming or modifying the original request (e.g. before a payment proxy). */
+    validate(request: Request): Promise<Response | null>;
     /** Wrap a fetch handler, e.g. `export default { fetch: forge.wrap(app.fetch) }`. Extra arguments (env, ctx) pass through. */
     wrap<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>): (request: Request, ...rest: A) => Promise<Response>;
     /** Forge's own routes only (/feedback, /feedback/rate, /feedback/summary, a static openapi.document); null for anything else. */