@forgeintel/sdk 0.5.0-beta.2 → 0.5.0-beta.4

package/README.md

@@ -93,7 +93,7 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `challengeSentence` | built-in | Override for wording experiments. `{rate_url}` and `{summary_url}` are substituted. Wording that presents the rating as required, makes anything depend on it, or asks for user data is refused (with a warning). |
 | `challengeExtension` | `true` | Add the `forge-feedback` extension to x402 v2 challenges. |
 | `receiptExtension` | `true` | Add it, with the real `feedback_id`, to the x402 v2 payment receipt (`PAYMENT-RESPONSE`). |
-| `agentContext` | `true` | Ask for self-reported `agent_context` (agent name, search query), record it, and remove it before your code runs. `{ searchQuery: false }` or `false` to limit. |
+| `agentContext` | `true` | Require self-reported `agent_context` (agent name, search query) on paid requests before payment processing; record and strip it before your code runs. `{ searchQuery: false }` requires only the agent name; `false` disables collection and enforcement. |
 | `injectBody` | `true` | Add `feedback_id` / `feedback_url` to paid JSON bodies. |
 | `rateHint` | built-in | The `rate_this_call` field. A string overrides it (`{feedback_url}` is substituted); `false` removes it. |
 | `injectText` | `false` | Append a two-line trailer to paid `text/plain` bodies. |
@@ -108,3 +108,22 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 Source, examples and design notes: [github.com/ClawCash/forge-feedback](https://github.com/ClawCash/forge-feedback).
 
 Client headers are captured automatically at discovery, challenge, payment, and rating stages, including unknown clients. Forge identifies awal, AgentCash, pay.sh and x402scan-mcp from known headers; other clients remain unknown. There is no client-signals switch. Legacy `agent_context.client` inputs remain accepted but are no longer requested.
+
+### Agent context on paid requests
+
+```ts
+const forge = createForge({
+  apiKey: process.env.FORGE_API_KEY!,
+  backendUrl: "https://your-forge-backend.example/api/sdk/v2",
+  publicUrl: "https://api.example.com",
+  agentContext: true,
+});
+```
+
+When enabled, context is always required on payment-bearing requests. `false` disables asking and recording. Forge documents `agent_context` and its `agent_type` and `search_query` fields as required. Use a listed agent name (or `Others` with `agent_type_other`), and the search query or `"direct"`. `{ searchQuery: false }` requires only the agent type. The legacy `required: false` option is ignored; disable `agentContext` to opt out. Context is self-reported, not authenticated identity.
+
+Mount Forge **before payment middleware**. A request carrying `PAYMENT-SIGNATURE` or `X-PAYMENT` gets HTTP 400 with field errors when context is missing or invalid, before the downstream payment handler runs. Initial unpaid requests can still receive a 402, and inspection and feedback routes stay accessible. Feedback remains optional and has its own `feedback` switch.
+
+Required mode reads JSON bodies up to 1 MiB, including chunked bodies, before payment processing. It rejects malformed or oversized JSON. Express parses these bodies even if your JSON parser is mounted later; mount a custom parser before Forge if you need one. For non-JSON bodies and bodyless requests, supply `agent_type` and `agent_search_query` query parameters. Forge strips context before forwarding to merchant validators. Next.js integrations that use a payment proxy should wrap both the proxy with `forge.proxy(...)` and the route with `forge.withForge(...)`.
+
+If using the framework-free core directly, call `requestUrl` and `requestBody`, then check `call.contextError()` **before** invoking your payment logic; send its response when non-null. Upgrading an existing integration to this version makes enabled context mandatory for paid requests.

package/dist/context.d.ts

@@ -31,17 +31,18 @@ export declare function takeFromUrl(url: string): {
     url: string;
     raw?: Record<string, string>;
 };
-/** JSON Schema for the optional `agent_context` body property. */
-export declare function agentContextSchema({ searchQuery }?: {
+export interface ContextOptions {
     searchQuery?: boolean;
-}): {
-    type: string;
-    description: string;
+    required?: boolean;
+}
+/** JSON Schema for the `agent_context` body property. */
+export declare function agentContextSchema({ searchQuery, required }?: ContextOptions): {
     properties: {
         search_query?: {
+            description: string;
+            minLength?: number | undefined;
             type: string;
             maxLength: number;
-            description: string;
         } | undefined;
         agent_type: {
             type: string;
@@ -49,11 +50,15 @@ export declare function agentContextSchema({ searchQuery }?: {
             description: string;
         };
         agent_type_other: {
+            description: string;
+            minLength?: number | undefined;
             type: string;
             maxLength: number;
-            description: string;
         };
     };
+    required?: string[] | undefined;
+    type: string;
+    description: string;
 };
 /** The optional query parameters, for operations without a request body. */
 export declare function agentContextParameters({ searchQuery }?: {
@@ -64,6 +69,6 @@ export declare function agentContextParameters({ searchQuery }?: {
     schema: Record<string, unknown>;
 }[];
 /** One line for the forge-feedback extension, so clients that only inspect the 402 learn about it too. */
-export declare function agentContextAsk({ searchQuery }?: {
-    searchQuery?: boolean;
-}): "Please add agent_context {agent_type, search_query} to your paid request's JSON body (without a body: agent_type, agent_search_query query parameters). search_query: share the query you used to find this service, or \"direct\" if you did not search." | "Please add agent_context {agent_type} to your paid request's JSON body (without a body: agent_type query parameter). Self-reported; omit what you don't know.";
+export declare function agentContextAsk({ searchQuery, required }?: ContextOptions): string;
+/** Validate the original values, before lenient parsing can truncate or discard them. */
+export declare function contextIssues(raw: Record<string, unknown>, { searchQuery }: ContextOptions): string[];

package/dist/context.js

@@ -1,7 +1,5 @@
-// Agent context: optional, self-reported facts about the calling agent, sent with the paid request.
-// Forge reads it and removes it before the merchant's validators and handlers run, so the merchant's
-// API contract never changes. Never required: a required field breaks strict validators and makes
-// agents invent answers.
+// Self-reported facts about the calling agent, removed before merchant validation.
+// Enabled context is required on payment-bearing requests.
 /** Suggested agent names; anything else is kept as given. */
 export const AGENT_TYPES = ["Claude Code", "Codex", "Cursor", "Grok Bot", "Muse", "Hermes", "Instinct", "OpenClaw", "Others"];
 /** Suggested x402 clients; anything else is kept as given. */
@@ -92,15 +90,16 @@ const DESCRIPTIONS = {
     agent_type_other: "Your agent's name, when agent_type is Others.",
     search_query: "The search query you used to find this service, or \"direct\" if you did not search.",
 };
-/** JSON Schema for the optional `agent_context` body property. */
-export function agentContextSchema({ searchQuery = true } = {}) {
+/** JSON Schema for the `agent_context` body property. */
+export function agentContextSchema({ searchQuery = true, required = true } = {}) {
     return {
         type: "object",
         description: DESCRIPTIONS.object,
+        ...(required ? { required: ["agent_type", ...(searchQuery ? ["search_query"] : [])] } : {}),
         properties: {
             agent_type: { type: "string", enum: [...AGENT_TYPES], description: DESCRIPTIONS.agent_type },
-            agent_type_other: { type: "string", maxLength: LIMITS.agent_type_other, description: DESCRIPTIONS.agent_type_other },
-            ...(searchQuery ? { search_query: { type: "string", maxLength: LIMITS.search_query, description: DESCRIPTIONS.search_query } } : {}),
+            agent_type_other: { type: "string", maxLength: LIMITS.agent_type_other, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.agent_type_other },
+            ...(searchQuery ? { search_query: { type: "string", maxLength: LIMITS.search_query, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.search_query } } : {}),
         },
     };
 }
@@ -115,8 +114,26 @@ export function agentContextParameters({ searchQuery = true } = {}) {
     return params;
 }
 /** One line for the forge-feedback extension, so clients that only inspect the 402 learn about it too. */
-export function agentContextAsk({ searchQuery = true } = {}) {
-    return searchQuery
-        ? "Please add agent_context {agent_type, search_query} to your paid request's JSON body (without a body: agent_type, agent_search_query query parameters). search_query: share the query you used to find this service, or \"direct\" if you did not search."
-        : "Please add agent_context {agent_type} to your paid request's JSON body (without a body: agent_type query parameter). Self-reported; omit what you don't know.";
+export function agentContextAsk({ searchQuery = true, required = true } = {}) {
+    const fields = searchQuery ? "agent_type, search_query" : "agent_type";
+    const query = searchQuery ? "agent_type, agent_search_query query parameters" : "agent_type query parameter";
+    return `${required ? "Required before payment" : "Please add"}: agent_context {${fields}} in your paid request's JSON body (without a body: ${query}).${searchQuery ? ' search_query: share the query you used to find this service, or "direct" if you did not search.' : ""}`;
+}
+/** Validate the original values, before lenient parsing can truncate or discard them. */
+export function contextIssues(raw, { searchQuery = true }) {
+    const issues = [];
+    for (const key of ["agent_type", ...(searchQuery ? ["search_query"] : [])]) {
+        const value = raw[key];
+        if (typeof value !== "string" || !value.trim() || value.length > LIMITS[key] || /[\u0000-\u001f\u007f]/.test(value)) {
+            issues.push(`${key} must be a non-empty string of at most ${LIMITS[key]} characters`);
+        }
+    }
+    const parsed = parseAgentContext(raw);
+    if (parsed?.agent_type && !AGENT_TYPES.includes(parsed.agent_type)) {
+        issues.push("agent_type must be a listed agent name, or Others with agent_type_other");
+    }
+    if (raw.agent_type_other !== undefined && (typeof raw.agent_type_other !== "string" || !raw.agent_type_other.trim() || raw.agent_type_other.length > 80)) {
+        issues.push("agent_type_other must be a non-empty string of at most 80 characters");
+    }
+    return issues;
 }

package/dist/core.d.ts

@@ -50,14 +50,17 @@ export interface ForgeOptions {
      */
     receiptExtension?: boolean;
     /**
-     * Agent context: optional, self-reported `agent_context` {agent_type, search_query} on the paid request
+     * Agent context: required, self-reported `agent_context` {agent_type, search_query} on the paid request
      * (JSON body, or agent_type / agent_search_query query parameters). Forge documents it in the
      * extension and OpenAPI, reads it, reports it with the call, and removes it before your validators and handlers
      * run. Default true. `{ searchQuery: false }` stops asking for (and recording) the search query; `false` stops
      * asking and recording altogether (the fields are still removed if an agent sends them).
+     * Enabled context rejects payment-bearing requests with missing/invalid context before payment middleware.
+     * `required` is retained for compatibility; `false` is ignored. Use `false` for agentContext to disable it.
      */
     agentContext?: boolean | {
         searchQuery?: boolean;
+        required?: boolean;
     };
     /** Add feedback_id and feedback_url to JSON object bodies of paid responses. Default true. */
     injectBody?: boolean;
@@ -106,6 +109,10 @@ export interface ForgeResponse {
 export interface ForgeCall {
     /** Set when the request carried a payment header (x402 v2 PAYMENT-SIGNATURE or v1 X-PAYMENT). */
     readonly feedbackId: string | undefined;
+    /** Whether this payment-bearing request must provide agent context. */
+    readonly contextRequired: boolean;
+    /** Call after requestUrl/requestBody and BEFORE payment processing. Null means context is acceptable. */
+    contextError(): ForgeResponse | null;
     /** A JSON body about to be sent: 402 challenges get the rating ask, paid 2xx objects get the feedback fields. */
     json(status: number, body: unknown): unknown;
     /** A text body about to be sent: gets the two-line trailer on paid 2xx text/plain when injectText is on. */

package/dist/core.js

@@ -4,7 +4,7 @@ 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";
@@ -61,7 +61,17 @@ 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;
+        if (context.required === false)
+            warnings.push("agentContext.required: false is no longer supported; enabled context is required on paid requests. Set agentContext: false to disable context");
+        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 +107,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: () => ({}),
@@ -165,6 +177,7 @@ function enabledCore(options, configWarnings) {
     const contextOption = options.agentContext ?? true;
     const collectContext = contextOption !== false;
     const searchQuery = collectContext && (typeof contextOption !== "object" || contextOption.searchQuery !== false);
+    const requiredContext = collectContext;
     const receipts = options.receiptExtension ?? true;
     const rateHint = options.rateHint === false
         ? null
@@ -194,10 +207,10 @@ function enabledCore(options, configWarnings) {
     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) }),
+        ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery, required: requiredContext }) : undefined) }),
     };
     if (!feedback && collectContext)
-        challengeAdditions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery }), optional: true } };
+        challengeAdditions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery, required: requiredContext }), optional: !requiredContext } };
     const touchChallenges = Boolean(challengeAdditions.sentence || challengeAdditions.extension || challengeAdditions.contextExtension);
     // Set once a document has been enriched; lets body injection respect strict response schemas.
     let allowInjection = null;
@@ -212,7 +225,7 @@ function enabledCore(options, configWarnings) {
             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)
@@ -342,6 +355,8 @@ function enabledCore(options, configWarnings) {
     }
     const passThrough = {
         feedbackId: undefined,
+        contextRequired: false,
+        contextError: () => null,
         json: (_status, body) => body,
         text: (_status, _type, body) => body,
         headers: () => ({}),
@@ -372,10 +387,13 @@ function enabledCore(options, configWarnings) {
         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,6 +401,18 @@ 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) {

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) {
+            // Enabled 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; enabled 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,7 +129,13 @@ 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)) {
+            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)) {
                 const text = await request.clone().text();
                 if (text.includes('"agent_context"')) {
                     const parsed = JSON.parse(text);
@@ -86,6 +144,11 @@ export function createForge(options) {
                         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/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)

package/dist/openapi.d.ts

@@ -2,7 +2,7 @@ type Json = Record<string, any>;
 export type SpecVersion = "2.0" | "3.0" | "3.1" | "3.2";
 export type ResponseSupport = "extended" | "incompatible" | "undocumented";
 export interface EnrichOptions {
-    /** Disable all feedback additions while retaining optional agent context. */
+    /** Disable all feedback additions while retaining enabled agent context. */
     feedback?: boolean;
     /** Merchant public origin, e.g. https://api.example.com */
     publicUrl: string;
@@ -18,9 +18,10 @@ export interface EnrichOptions {
     describeOperations?: boolean;
     /** Also document the optional rate_this_call body field (when the SDK's rateHint is on). */
     hintField?: boolean;
-    /** Document optional agent context on paid operations: `agent_context` in JSON request bodies, agent_* query parameters otherwise. */
+    /** Document agent context on paid operations: `agent_context` in JSON request bodies, agent_* query parameters otherwise. */
     agentContext?: {
         searchQuery: boolean;
+        required?: boolean;
     };
 }
 export interface OperationReport {
@@ -29,7 +30,7 @@ export interface OperationReport {
     path: string;
     /** Per 2xx status code: whether feedback_id was added to its JSON schema. */
     responses: Record<string, ResponseSupport>;
-    /** Where optional agent context was documented, if asked to. */
+    /** Where enabled agent context was documented, if asked to. */
     agentContext?: "body" | "query" | "not_added";
     reasons: string[];
 }

package/dist/openapi.js

@@ -100,8 +100,9 @@ function extendSchema(doc, schema, props) {
     return { schema: copy };
 }
 const BODYLESS = new Set(["get", "head", "delete", "options", "trace"]);
-/** Document optional agent context on one paid operation. Never required; skipped when a schema can't take it safely. */
+/** Document agent context on a paid operation; skip schemas that cannot be extended safely. */
 function addAgentContext(doc, version, item, method, op, opts, report) {
+    opts = { ...opts, required: true }; // Enabled context cannot be made optional by a legacy option.
     const resolve = (v) => (isObj(v) && typeof v.$ref === "string" ? resolveRef(doc, v.$ref) : v);
     const listed = [...(Array.isArray(item.parameters) ? item.parameters : []), ...(Array.isArray(op.parameters) ? op.parameters : [])].map(resolve).filter(isObj);
     const props = { [CONTEXT_FIELD]: agentContextSchema(opts) };
@@ -115,8 +116,8 @@ function addAgentContext(doc, version, item, method, op, opts, report) {
         if (!params.length)
             return notAdded("parameter_collision");
         const documented = params.map((p) => version === "2.0"
-            ? { name: p.name, in: "query", required: false, description: p.description, ...p.schema }
-            : { name: p.name, in: "query", required: false, description: p.description, schema: p.schema });
+            ? { name: p.name, in: "query", required: !!opts.required && p.name !== "agent_type_other", description: p.description, ...p.schema }
+            : { name: p.name, in: "query", required: !!opts.required && p.name !== "agent_type_other", description: p.description, schema: p.schema });
         op.parameters = [...(Array.isArray(op.parameters) ? op.parameters : []), ...documented];
         report.agentContext = "query";
         return;
@@ -130,6 +131,10 @@ function addAgentContext(doc, version, item, method, op, opts, report) {
         const result = extendSchema(doc, param.schema, props);
         if ("reason" in result)
             return notAdded(result.reason);
+        if (opts.required) {
+            result.schema.required = [...new Set([...(Array.isArray(result.schema.required) ? result.schema.required : []), CONTEXT_FIELD])];
+            param.required = true;
+        }
         param.schema = result.schema;
         op.parameters = params.map((p, i) => (i === index ? param : p)); // inline copy if it was a shared $ref
         report.agentContext = "body";
@@ -146,8 +151,12 @@ function addAgentContext(doc, version, item, method, op, opts, report) {
         const result = extendSchema(doc, entry.schema, props);
         if ("reason" in result)
             return notAdded(result.reason);
+        if (opts.required)
+            result.schema.required = [...new Set([...(Array.isArray(result.schema.required) ? result.schema.required : []), CONTEXT_FIELD])];
         entry.schema = result.schema;
     }
+    if (opts.required)
+        copy.required = true;
     op.requestBody = copy; // inline copy if it was a shared $ref
     report.agentContext = "body";
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.5.0-beta.2",
-  "description": "The Forge SDK for x402 paid APIs: agent feedback (feedback IDs, one-request GET ratings), agent context, OpenAPI and challenge enrichment, and passive call signals. Express, Hono, Next.js and any fetch handler. Never on your critical path.",
+  "version": "0.5.0-beta.4",
+  "description": "The Forge SDK for x402 paid APIs: agent feedback, required agent context, OpenAPI and challenge enrichment, and passive call signals. Express, Hono, Next.js and fetch handlers. No Forge network request on the merchant response path.",
   "license": "MIT",
   "type": "module",
   "engines": {