@forgeintel/sdk 0.5.0-beta.1 → 0.5.0-beta.11

package/dist/core.js

@@ -4,16 +4,17 @@ import { randomUUID } from "node:crypto";
 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.
@@ -36,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;
@@ -61,7 +64,15 @@ 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 }");
+    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).
@@ -97,6 +108,8 @@ export function checkOptions(input) {
 function disabledCore(errors, warnings) {
     const passThrough = {
         feedbackId: undefined,
+        contextRequired: false,
+        contextError: () => null,
         json: (_status, body) => body,
         text: (_status, _type, body) => body,
         headers: () => ({}),
@@ -144,17 +157,24 @@ 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 feedback = options.feedback !== false;
@@ -162,9 +182,11 @@ function enabledCore(options, configWarnings) {
     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
@@ -189,30 +211,48 @@ function enabledCore(options, configWarnings) {
             lastLogged = message;
         });
     const reporter = new EventReporter(backend("events"), apiKey, fetchImpl, onError, options.flushIntervalMs ?? 2000);
-    const challengeSentence = feedback ? (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 } : {}),
-        ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery }) : undefined) }),
-    };
-    if (!feedback && collectContext)
-        challengeAdditions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery }), optional: true } };
-    const touchChallenges = Boolean(challengeAdditions.sentence || challengeAdditions.extension || challengeAdditions.contextExtension);
+    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)
@@ -227,30 +267,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" });
@@ -294,6 +369,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);
         }
@@ -307,7 +383,7 @@ function enabledCore(options, configWarnings) {
         const { method, path } = request;
         if (feedback && path === basePath) {
             if (method === "GET" || method === "HEAD")
-                return reply(200, form);
+                return reply(200, formDoc());
             if (method === "POST") {
                 let body;
                 try {
@@ -342,6 +418,8 @@ function enabledCore(options, configWarnings) {
     }
     const passThrough = {
         feedbackId: undefined,
+        contextRequired: false,
+        contextError: () => null,
         json: (_status, body) => body,
         text: (_status, _type, body) => body,
         headers: () => ({}),
@@ -368,14 +446,20 @@ function enabledCore(options, configWarnings) {
         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 };
@@ -383,12 +467,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;
@@ -400,15 +496,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) } : {}),
+                            },
                         };
                     }
                 }
@@ -430,7 +527,7 @@ 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++;
@@ -440,7 +537,7 @@ function enabledCore(options, configWarnings) {
                         receiptFacts = readReceipt(paymentResponse);
                     if (feedbackId && ok(status)) {
                         set["Forge-Feedback-Id"] = feedbackId;
-                        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;
                     }
@@ -510,7 +607,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,
@@ -192,14 +213,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. */

package/dist/fetch.js

@@ -1,7 +1,7 @@
 // Web-standard adapter: Request in, Response out. Works wherever handlers are (request) => Response:
 // Hono, Next.js route handlers, Cloudflare Workers, Bun, Deno. The Hono and Next adapters build on this.
 import { BODY_LIMIT, SPEC_LIMIT, createForgeCore } from "./core.js";
-/** Bodies Forge will buffer to remove agent_context or add feedback fields. Larger ones pass through untouched. */
+/** Buffer limit; required context rejects oversized paid JSON before payment processing. */
 const JSON_LIMIT = 1024 * 1024;
 const isJson = (type) => /^application\/(?:[\w.+-]+\+)?json\b/i.test(type ?? "");
 export function toResponse(response) {
@@ -20,6 +20,40 @@ const smallEnough = (headers, limit) => {
     const length = Number(headers.get("content-length"));
     return Number.isFinite(length) && length > 0 && length <= limit;
 };
+/** Bound reads even when a client sends chunked JSON or an inaccurate Content-Length. */
+async function boundedJson(request) {
+    const reader = request.clone().body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > JSON_LIMIT)
+                throw new Error("body_too_large");
+            chunks.push(value);
+        }
+        const data = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            data.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return JSON.parse(new TextDecoder().decode(data));
+    }
+    finally {
+        // A clone is a tee: awaiting cancellation would wait for the untouched original stream.
+        void reader.cancel().catch(() => { });
+    }
+}
+function unreadableContext() {
+    return toResponse({ status: 400, headers: {}, body: {
+            error: "agent_context_invalid",
+            message: "Required agent context could not be read. Send valid JSON up to 1 MiB, or use agent_type and agent_search_query query parameters with a non-JSON body.",
+        } });
+}
 export function createForge(options) {
     const core = createForgeCore(options);
     const forgeRequest = (request, url) => ({
@@ -35,6 +69,24 @@ export function createForge(options) {
         const own = await core.route(forgeRequest(request, new URL(request.url)));
         return own ? toResponse(own) : null;
     }
+    async function validate(request) {
+        if (!core.enabled || options.agentContext === false)
+            return null;
+        const url = new URL(request.url);
+        const call = core.call(forgeRequest(request, url));
+        if (!call.contextRequired)
+            return null;
+        try {
+            call.requestUrl(`${url.pathname}${url.search}`);
+            if (request.body && isJson(request.headers.get("content-type")))
+                call.requestBody(await boundedJson(request));
+            const error = call.contextError();
+            return error ? toResponse(error) : null;
+        }
+        catch {
+            return unreadableContext();
+        }
+    }
     /** The merchant's own OpenAPI route: fetch it without validators, enrich JSON 200s, pass anything else through. */
     async function spec(request, next) {
         const headers = new Headers(request.headers);
@@ -63,7 +115,7 @@ export function createForge(options) {
     async function handle(request, next) {
         if (!core.enabled)
             return next(request);
-        // Before the handler: our own routes, the spec, and agent context. Any failure here: the original request goes on.
+        // Before the handler: our own routes, the spec, and agent context. Required-context errors stop paid attempts.
         let call;
         let forwarded = request;
         try {
@@ -77,15 +129,26 @@ export function createForge(options) {
             const stripped = call.requestUrl(`${url.pathname}${url.search}`);
             const nextUrl = stripped === `${url.pathname}${url.search}` ? request.url : new URL(stripped, url).href;
             let body;
-            if (request.body && isJson(request.headers.get("content-type")) && smallEnough(request.headers, JSON_LIMIT)) {
-                const text = await request.clone().text();
-                if (text.includes('"agent_context"')) {
-                    const parsed = JSON.parse(text);
+            if (call.contextRequired && request.body && isJson(request.headers.get("content-type"))) {
+                const parsed = await boundedJson(request);
+                const without = call.requestBody(parsed);
+                if (without !== parsed)
+                    body = JSON.stringify(without);
+            }
+            else if (request.body && isJson(request.headers.get("content-type")) && (smallEnough(request.headers, JSON_LIMIT) || !request.headers.has("content-length"))) {
+                // Optional context, best effort: a body that is too large or not JSON goes to the handler untouched.
+                const parsed = await boundedJson(request).catch(() => undefined);
+                if (parsed !== undefined) {
                     const without = call.requestBody(parsed);
                     if (without !== parsed)
                         body = JSON.stringify(without);
                 }
             }
+            const contextError = call.contextError();
+            if (contextError) {
+                call.finish(contextError.status);
+                return toResponse(contextError);
+            }
             if (nextUrl !== request.url || body !== undefined) {
                 const headers = new Headers(request.headers);
                 if (body !== undefined)
@@ -99,6 +162,10 @@ export function createForge(options) {
         }
         catch (error) {
             core.onError(error);
+            if (call?.contextRequired) {
+                call.finish(400);
+                return unreadableContext();
+            }
             return next(request);
         }
         const response = await next(forwarded);
@@ -165,6 +232,7 @@ export function createForge(options) {
         diagnostics: core.diagnostics,
         shutdown: core.shutdown,
         handle,
+        validate,
         route,
         wrap: (handler) => (request, ...rest) => handle(request, (r) => handler(r, ...rest)),
     };

package/dist/hono.js

@@ -8,6 +8,7 @@ export function createForge(options) {
         enrichOpenApi: forge.enrichOpenApi,
         diagnostics: forge.diagnostics,
         shutdown: forge.shutdown,
+        validate: forge.validate,
         middleware() {
             if (!forge.enabled)
                 return async (_c, next) => next();

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { deriveSigningKey, mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN
 export type { FeedbackIdCheck } from "./id.js";
 export { OUTCOMES, ISSUES, NOTE_MAX_LENGTH, PROTOCOL, parseSubmission } from "./values.js";
 export type { Outcome, Issue, Submission } from "./values.js";
-export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader, readReceipt } from "./x402.js";
+export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, FEEDBACK_FIELD, readPaymentHeader, readReceipt } from "./x402.js";
 export { ASK, TONES, checkAskText } from "./ask.js";
 export { AGENT_TYPES, CLIENTS, CONTEXT_FIELD, CONTEXT_QUERY, agentContextSchema, parseAgentContext } from "./context.js";
 export type { AgentContext } from "./context.js";

package/dist/index.js

@@ -3,6 +3,6 @@ export { createForgeCore, checkOptions, BODY_LIMIT, SPEC_LIMIT } from "./core.js
 export { enrichOpenApi, detectVersion } from "./openapi.js";
 export { deriveSigningKey, mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS } from "./id.js";
 export { OUTCOMES, ISSUES, NOTE_MAX_LENGTH, PROTOCOL, parseSubmission } from "./values.js";
-export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader, readReceipt } from "./x402.js";
+export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, FEEDBACK_FIELD, readPaymentHeader, readReceipt } from "./x402.js";
 export { ASK, TONES, checkAskText } from "./ask.js";
 export { AGENT_TYPES, CLIENTS, CONTEXT_FIELD, CONTEXT_QUERY, agentContextSchema, parseAgentContext } from "./context.js";

package/dist/next.js

@@ -17,9 +17,13 @@ export function createForge(options) {
         diagnostics: forge.diagnostics,
         shutdown: forge.shutdown,
         handle: forge.handle,
+        validate: forge.validate,
         withForge: (handler) => (request, context) => forge.handle(request, (forwarded) => handler(forwarded === request ? request : sameKind(request, forwarded), context)),
         routes: { GET: own, POST: own, HEAD: own },
         proxy: (proxy) => async (request) => {
+            const invalid = await forge.validate(request);
+            if (invalid)
+                return invalid;
             const response = await proxy(request);
             // Only the 402: the proxy passes paid requests on to the route, where withForge mints the feedback ID.
             if (response.status !== 402 || !forge.enabled)