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

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);
@@ -61,9 +113,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 +127,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,8 +160,15 @@ export function createForge(options) {
         }
         catch (error) {
             core.onError(error);
+            if (call?.contextRequired) {
+                call.finish(400);
+                return unreadableContext();
+            }
             return next(request);
         }
+        // Disabled by invalid options: agent context is removed (above), nothing else.
+        if (!core.enabled)
+            return next(forwarded);
         const response = await next(forwarded);
         // After the handler: decorate the 402 or the paid response. Any failure before the body is read: the original
         // response goes out. Once read, the body is always sent from what was read (decorated or not).
@@ -165,6 +233,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,9 +8,8 @@ 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();
             return async (c, next) => {
                 let ranNext = false;
                 const response = await forge.handle(c.req.raw, async (request) => {

package/dist/index.d.ts

@@ -8,10 +8,11 @@ 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";
 export type { AskTexts, Tone } from "./ask.js";
 export type { ChallengeAdditions } from "./x402.js";
 export type { ForgeEvent } from "./reporter.js";
+export type { ClientHeaders } from "./client-signals.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)

package/dist/openapi.d.ts

@@ -2,8 +2,10 @@ 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 {
-    /** Merchant public origin, e.g. https://api.example.com */
-    publicUrl: string;
+    /** Disable all feedback additions while retaining agent context. */
+    feedback?: boolean;
+    /** Optional merchant public origin. Without it, feedback links use same-origin paths. */
+    publicUrl?: string;
     /** Public path of the feedback routes, e.g. /feedback */
     basePath: string;
     /** Sentence appended to x-guidance and paid operation descriptions. */
@@ -16,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 {
@@ -27,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 agent context was documented, if asked to. */
     agentContext?: "body" | "query" | "not_added";
     reasons: string[];
 }

package/dist/openapi.js

@@ -3,6 +3,7 @@
 // and on any unexpected input return the original document unchanged.
 import { CONTEXT_FIELD, agentContextParameters, agentContextSchema } from "./context.js";
 import { FEEDBACK_ID_PATTERN } from "./id.js";
+import { FEEDBACK_FIELD } from "./x402.js";
 import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL } from "./values.js";
 const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
 const ANNOTATIONS = new Set(["$ref", "description", "title", "summary", "example", "examples", "deprecated", "readOnly", "writeOnly", "$comment"]);
@@ -38,21 +39,30 @@ function resolveRef(doc, ref) {
 }
 function feedbackProperties(rateUrl, hintField = false) {
     return {
-        ...(hintField ? { rate_this_call: { type: "string", description: "How to rate this paid call in one free request." } } : {}),
-        feedback_id: {
-            type: "string",
-            pattern: FEEDBACK_ID_PATTERN.source,
-            description: "Rating ID for this paid call (also sent as the Forge-Feedback-Id header). See x-forge-feedback.",
-        },
-        feedback_url: {
-            type: "string",
-            format: "uri",
-            description: `Quick-rating URL with outcome left blank; outcome values: ${Object.keys(OUTCOMES).join(", ")}. Base: ${rateUrl}`,
+        [FEEDBACK_FIELD]: {
+            type: "object",
+            description: "Added by Forge to paid responses: how to rate this call. See x-forge-feedback.",
+            required: ["feedback_id", "feedback_url"],
+            properties: {
+                feedback_id: {
+                    type: "string",
+                    pattern: FEEDBACK_ID_PATTERN.source,
+                    description: "Rating ID for this paid call (also sent as the Forge-Feedback-Id header).",
+                },
+                feedback_url: {
+                    type: "string",
+                    format: "uri-reference",
+                    description: `Quick-rating URL with outcome left blank; outcome values: ${Object.keys(OUTCOMES).join(", ")}. Base: ${rateUrl}`,
+                },
+                ...(hintField ? { rate_this_call: { type: "string", description: "How to rate this paid call in one free request." } } : {}),
+            },
         },
     };
 }
 /** Returns an extended copy of an object schema, or a reason it can't be extended safely. */
 function extendSchema(doc, schema, props) {
+    if (schema === true)
+        schema = {}; // `true` accepts any value, like {}
     if (!isObj(schema))
         return { reason: "no_schema" };
     let target = schema;
@@ -75,7 +85,10 @@ function extendSchema(doc, schema, props) {
     if (COMPOSITION.some((k) => k in copy))
         return { reason: "composition" };
     const types = Array.isArray(copy.type) ? copy.type : [copy.type];
-    const objectish = types.includes("object") || (copy.type === undefined && (isObj(copy.properties) || Array.isArray(copy.allOf)));
+    // {} (annotations only) accepts any value, e.g. FastAPI's default response schema. `properties` only constrains
+    // objects, so documenting the field there narrows nothing.
+    const anyValue = Object.keys(copy).every((k) => ANNOTATIONS.has(k));
+    const objectish = anyValue || types.includes("object") || (copy.type === undefined && (isObj(copy.properties) || Array.isArray(copy.allOf)));
     if (!objectish)
         return { reason: "not_object" };
     if ("propertyNames" in copy || "maxProperties" in copy)
@@ -100,7 +113,7 @@ 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) {
     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);
@@ -115,8 +128,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 +143,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 +163,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";
 }
@@ -161,20 +182,21 @@ function appendSentence(text, sentence, marker) {
 }
 /** Work out the path prefix document paths are relative to, and whether it's this service's origin. */
 function serverBase(doc, version, publicUrl) {
-    const origin = new URL(publicUrl).origin;
+    const origin = publicUrl ? new URL(publicUrl).origin : undefined;
+    const baseUrl = publicUrl ?? "https://forge.invalid";
     try {
         if (version === "2.0") {
-            const scheme = Array.isArray(doc.schemes) && doc.schemes[0] ? doc.schemes[0] : new URL(publicUrl).protocol.slice(0, -1);
+            const scheme = Array.isArray(doc.schemes) && doc.schemes[0] ? doc.schemes[0] : new URL(baseUrl).protocol.slice(0, -1);
             const base = typeof doc.basePath === "string" ? doc.basePath : "";
-            const url = typeof doc.host === "string" ? new URL(`${scheme}://${doc.host}${base}`) : new URL(base || "/", publicUrl);
-            return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+            const url = typeof doc.host === "string" ? new URL(`${scheme}://${doc.host}${base}`) : new URL(base || "/", baseUrl);
+            return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: !origin || url.origin === origin };
         }
         const server = Array.isArray(doc.servers) ? doc.servers[0] : undefined;
         if (!isObj(server) || typeof server.url !== "string")
             return { prefix: "", sameOrigin: true };
         const raw = server.url.replace(/\{([^}]+)\}/g, (_, name) => server.variables?.[name]?.default ?? "");
-        const url = new URL(raw, publicUrl);
-        return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+        const url = new URL(raw, baseUrl);
+        return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: !origin || url.origin === origin };
     }
     catch {
         return { prefix: "", sameOrigin: false };
@@ -253,7 +275,7 @@ export function enrichOpenApi(input, options) {
     }
     try {
         const doc = clone(original);
-        const origin = new URL(options.publicUrl).origin;
+        const origin = options.publicUrl ? new URL(options.publicUrl).origin : "";
         const base = options.basePath.replace(/\/+$/, "");
         const rateUrl = `${origin}${base}/rate`;
         const formUrl = `${origin}${base}`;
@@ -287,6 +309,11 @@ export function enrichOpenApi(input, options) {
                     continue;
                 const opReport = { method: method.toUpperCase(), path, responses: {}, reasons: [] };
                 report.operations.push(opReport);
+                if (options.feedback === false) {
+                    if (options.agentContext)
+                        addAgentContext(doc, version, item, method, op, options.agentContext, opReport);
+                    continue;
+                }
                 if (options.describeOperations ?? true)
                     op.description = appendSentence(op.description, options.sentence, options.marker);
                 const produces = (op.produces ?? doc.produces);
@@ -344,6 +371,10 @@ export function enrichOpenApi(input, options) {
                 }
             }
         }
+        if (options.feedback === false) {
+            report.enriched = Boolean(options.agentContext);
+            return { document: doc, report };
+        }
         // Feedback routes. Paths are relative to the server prefix when it's this origin;
         // otherwise (3.x) the path items carry their own servers entry.
         const inPrefix = sameOrigin && (base === prefix || base.startsWith(`${prefix}/`));
@@ -359,7 +390,7 @@ export function enrichOpenApi(input, options) {
         }
         else {
             const ops = feedbackOperations(version, formUrl, rateUrl, operationIds);
-            const servers = inPrefix ? {} : { servers: [{ url: origin }] };
+            const servers = inPrefix ? {} : { servers: [{ url: origin || "/" }] };
             paths[docBase] = { ...servers, get: ops.form, post: ops.submit };
             paths[`${docBase}/rate`] = { ...servers, get: ops.rate };
             paths[`${docBase}/summary`] = { ...servers, get: ops.summary };

package/dist/reporter.d.ts

@@ -1,13 +1,23 @@
 import type { AgentContext } from "./context.js";
+import type { ClientHeaders } from "./client-signals.js";
 export type ForgeEvent = {
+    type: "discovery";
+    route: string;
+    ts: number;
+    user_agent?: string;
+    request_headers?: ClientHeaders;
+} | {
     type: "challenge";
     route: string;
     ts: number;
     user_agent?: string;
+    request_headers?: ClientHeaders;
     agent_context?: AgentContext;
 } | {
     type: "interaction";
-    feedback_id: string;
+    feedback_id?: string;
+    /** Independent telemetry identifier when feedback is disabled. */
+    interaction_id?: string;
     route: string;
     status: number;
     latency_ms: number;
@@ -19,6 +29,7 @@ export type ForgeEvent = {
     /** Settlement transaction reference from the receipt. */
     transaction?: string;
     user_agent?: string;
+    request_headers?: ClientHeaders;
     agent_context?: AgentContext;
     ts: number;
 };

package/dist/x402.d.ts

@@ -1,14 +1,23 @@
 import { type Tone } from "./ask.js";
+import type { ContextOptions } from "./context.js";
 /** Key of the Forge extension in x402 v2 `extensions`: in the 402 challenge (next to e.g. `bazaar`) and in the payment receipt. */
 export declare const FEEDBACK_EXTENSION = "forge-feedback";
+/** Key of the object the SDK adds to paid JSON response bodies: feedback_id, feedback_url, and optionally rate_this_call. */
+export declare const FEEDBACK_FIELD = "forge_feedback";
+/**
+ * The service origin a challenge was issued for: v2 `resource.url` (header or body), or v1 `accepts[].resource`.
+ * Used for absolute rating links when no origin is configured or registered. Never throws.
+ */
+export declare function challengeOrigin(challenge: string | unknown): string | undefined;
+/** The service origin a payment was made for (x402 v2 `resource.url` in the payment header). Never throws. */
+export declare function paymentOrigin(headerValue: string): string | undefined;
 /**
  * The `forge-feedback` challenge extension: how to rate the call, as structured data. Clients that inspect
  * the 402 (e.g. `awal x402 details`) print every extension, so this reaches agents before they pay.
- * With `agentContext`, it also says how to report agent context with the paid request.
+ * Agent context is a separate switch with its own extension (`forge-agent-context`).
  */
-export declare function feedbackExtension(rateUrl: string, tone?: Tone, agentContext?: string): {
+export declare function feedbackExtension(rateUrl: string, tone?: Tone): {
     info: {
-        agent_context?: string | undefined;
         rate: string;
         outcome: string[];
         issue: {
@@ -42,19 +51,30 @@ export declare function receiptExtension(rateUrl: string, feedbackId: string, to
  * Returns undefined when the header can't be parsed, settlement failed, or the extension is already there.
  */
 export declare function describeReceipt(headerValue: string, extension: unknown): string | undefined;
+/**
+ * The longest challenge description the SDK produces. Clients copy the description into the payment payload,
+ * and the CDP facilitator rejects a payload whose resource.description exceeds 500 characters, failing the payment.
+ */
+export declare const MAX_DESCRIPTION = 500;
 /** What the SDK adds to a challenge. Each part is skipped when already present. */
 export interface ChallengeAdditions {
     /** Appended to the description (v2 resource.description, v1 accepts[].description). */
     sentence?: string;
+    /** Appended instead when `sentence` would pass MAX_DESCRIPTION; the description is left alone when this doesn't fit either. */
+    shortSentence?: string;
     /** Idempotency marker for the sentence. Default: the sentence itself. */
     marker?: string;
     /** Added as extensions["forge-feedback"] (v2 only; v1 challenges have no extensions). */
     extension?: unknown;
+    /** Added as extensions["forge-agent-context"] whenever agent context is enabled, independent of feedback. */
+    contextExtension?: unknown;
+    /** Declare agent context in the merchant's `bazaar` extension (schema and example together). */
+    bazaarContext?: ContextOptions;
 }
 /**
- * Add the rating sentence and/or the forge-feedback extension to a base64 PAYMENT-REQUIRED header (x402 v2).
- * `accepts` is untouched: v2 matches payments on `accepts`, and @x402/core only checks echoed extensions
- * the server itself advertised, so an added extension doesn't affect payment.
+ * Add the rating sentence, Forge's extensions and Bazaar agent context to a base64 PAYMENT-REQUIRED header (x402 v2).
+ * `accepts` is untouched: v2 matches payments on `accepts`. @x402/core checks that each echoed extension's `info`
+ * contains what the server advertised, so added extensions and added Bazaar fields don't affect payment.
  * Returns undefined when the header can't be parsed or already has everything.
  */
 export declare function describeChallenge(headerValue: string, additions: ChallengeAdditions): string | undefined;

package/dist/x402.js

@@ -1,13 +1,48 @@
 import { ASK } from "./ask.js";
+import { addContextToBazaar } from "./bazaar.js";
 import { ISSUES, PROTOCOL } from "./values.js";
 /** Key of the Forge extension in x402 v2 `extensions`: in the 402 challenge (next to e.g. `bazaar`) and in the payment receipt. */
 export const FEEDBACK_EXTENSION = "forge-feedback";
+/** Key of the object the SDK adds to paid JSON response bodies: feedback_id, feedback_url, and optionally rate_this_call. */
+export const FEEDBACK_FIELD = "forge_feedback";
+const originOf = (url) => {
+    try {
+        const parsed = new URL(String(url));
+        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The service origin a challenge was issued for: v2 `resource.url` (header or body), or v1 `accepts[].resource`.
+ * Used for absolute rating links when no origin is configured or registered. Never throws.
+ */
+export function challengeOrigin(challenge) {
+    try {
+        const value = typeof challenge === "string" ? JSON.parse(Buffer.from(challenge, "base64").toString("utf8")) : challenge;
+        const resource = value?.resource?.url ?? (Array.isArray(value?.accepts) ? value.accepts[0]?.resource : undefined);
+        return originOf(resource);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The service origin a payment was made for (x402 v2 `resource.url` in the payment header). Never throws. */
+export function paymentOrigin(headerValue) {
+    try {
+        return originOf(JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"))?.resource?.url);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * The `forge-feedback` challenge extension: how to rate the call, as structured data. Clients that inspect
  * the 402 (e.g. `awal x402 details`) print every extension, so this reaches agents before they pay.
- * With `agentContext`, it also says how to report agent context with the paid request.
+ * Agent context is a separate switch with its own extension (`forge-agent-context`).
  */
-export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
+export function feedbackExtension(rateUrl, tone = "soft") {
     return {
         info: {
             protocol: PROTOCOL,
@@ -16,9 +51,8 @@ export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
             rate: `GET ${rateUrl}?feedback_id=FEEDBACK_ID&outcome=fully`,
             outcome: ["fully", "partially", "no"],
             issue: { when: "The outcome is not fully. Tells the merchant what to fix.", values: Object.keys(ISSUES) },
-            feedback_id: "In the paid response body (feedback_id) and the Forge-Feedback-Id header.",
+            feedback_id: `In the paid response body (${FEEDBACK_FIELD}.feedback_id) and the Forge-Feedback-Id header.`,
             payment: "None. Plain GET, not an x402 endpoint.",
-            ...(agentContext ? { agent_context: agentContext } : {}),
         },
     };
 }
@@ -57,39 +91,59 @@ export function describeReceipt(headerValue, extension) {
     receipt.extensions = { ...extensions, [FEEDBACK_EXTENSION]: extension };
     return Buffer.from(JSON.stringify(receipt), "utf8").toString("base64");
 }
-function appendSentence(description, sentence, marker) {
+/**
+ * The longest challenge description the SDK produces. Clients copy the description into the payment payload,
+ * and the CDP facilitator rejects a payload whose resource.description exceeds 500 characters, failing the payment.
+ */
+export const MAX_DESCRIPTION = 500;
+function appendSentence(description, sentence, marker, shortSentence) {
     const current = typeof description === "string" ? description.trim() : "";
-    return current.includes(marker) ? current : current ? `${current} ${sentence}` : sentence;
+    if (current.includes(marker))
+        return current;
+    for (const candidate of [sentence, shortSentence]) {
+        if (!candidate)
+            continue;
+        const next = current ? `${current} ${candidate}` : candidate;
+        if (next.length <= MAX_DESCRIPTION)
+            return next;
+    }
+    // Nothing fits: the forge-feedback extension still carries the ask.
+    return current;
 }
 /** Apply additions to a v2 PaymentRequired in place. Returns whether anything changed. */
 function addToV2(challenge, add) {
     let changed = false;
     const resource = challenge.resource;
     if (add.sentence && resource && typeof resource === "object") {
-        const next = appendSentence(resource.description, add.sentence, add.marker ?? add.sentence);
+        const next = appendSentence(resource.description, add.sentence, add.marker ?? add.sentence, add.shortSentence);
         if (next !== resource.description) {
             resource.description = next;
             changed = true;
         }
     }
-    if (add.extension) {
+    for (const [key, extension] of [[FEEDBACK_EXTENSION, add.extension], ["forge-agent-context", add.contextExtension]]) {
+        if (!extension)
+            continue;
         const extensions = challenge.extensions;
         if (extensions === undefined || extensions === null) {
-            challenge.extensions = { [FEEDBACK_EXTENSION]: add.extension };
+            challenge.extensions = { [key]: extension };
             changed = true;
         }
-        else if (typeof extensions === "object" && !Array.isArray(extensions) && !(FEEDBACK_EXTENSION in extensions)) {
-            // Added last, so the merchant's own extensions (e.g. bazaar) keep their order and content.
-            challenge.extensions = { ...extensions, [FEEDBACK_EXTENSION]: add.extension };
+        else if (typeof extensions === "object" && !Array.isArray(extensions) && !(key in extensions)) {
+            // Added last, so the merchant's own extensions (e.g. bazaar) keep their order.
+            challenge.extensions = { ...extensions, [key]: extension };
             changed = true;
         }
     }
+    const extensions = challenge.extensions;
+    if (add.bazaarContext && extensions && typeof extensions === "object" && addContextToBazaar(extensions.bazaar, add.bazaarContext))
+        changed = true;
     return changed;
 }
 /**
- * Add the rating sentence and/or the forge-feedback extension to a base64 PAYMENT-REQUIRED header (x402 v2).
- * `accepts` is untouched: v2 matches payments on `accepts`, and @x402/core only checks echoed extensions
- * the server itself advertised, so an added extension doesn't affect payment.
+ * Add the rating sentence, Forge's extensions and Bazaar agent context to a base64 PAYMENT-REQUIRED header (x402 v2).
+ * `accepts` is untouched: v2 matches payments on `accepts`. @x402/core checks that each echoed extension's `info`
+ * contains what the server advertised, so added extensions and added Bazaar fields don't affect payment.
  * Returns undefined when the header can't be parsed or already has everything.
  */
 export function describeChallenge(headerValue, additions) {
@@ -122,7 +176,7 @@ export function describeChallengeBody(body, additions) {
         const marker = additions.marker ?? sentence;
         return {
             ...b,
-            accepts: b.accepts.map((a) => a && typeof a === "object" ? { ...a, description: appendSentence(a.description, sentence, marker) } : a),
+            accepts: b.accepts.map((a) => a && typeof a === "object" ? { ...a, description: appendSentence(a.description, sentence, marker, additions.shortSentence) } : a),
         };
     }
     if (b.x402Version === 2 && b.resource && typeof b.resource === "object") {