@forgeintel/sdk 0.5.0-beta.7 → 0.5.0-beta.9

package/README.md

@@ -57,7 +57,7 @@ Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require
 
 | When | What happens |
 | --- | --- |
-| 402 challenge | Appends a soft ask to the description: *After your call, please rate this service for other agents: GET …/feedback/rate?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no)…*, and asks for `&issue=` when the outcome isn't `fully`, so a bad rating says why. On x402 v2 it also adds an `extensions["forge-feedback"]` block. Payment terms and your own extensions are never touched. |
+| 402 challenge | Appends a soft ask to the description: *After your call, please rate this service for other agents: GET …/feedback/rate?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no)…*, and asks for `&issue=` when the outcome isn't `fully`, so a bad rating says why. On x402 v2 it also adds an `extensions["forge-feedback"]` block. Payment terms and your own extensions are never touched. The description never exceeds 500 characters (the CDP facilitator rejects longer ones): a shorter ask is used when the full one doesn't fit, and none when neither does. |
 | Paid 2xx response | Adds the `Forge-Feedback-Id` header. JSON object bodies also get `feedback_id`, `feedback_url` (with `outcome=` left blank) and `rate_this_call`, unless your OpenAPI schema for that response couldn't safely take them. |
 | `GET /openapi.json` | Your document is served enriched: feedback routes documented, feedback fields added to paid response schemas, one sentence in `x-guidance`. |
 | `GET /feedback/rate` | Quick rating: `feedback_id`, `outcome`, optional `issue`. |
@@ -118,7 +118,7 @@ const forge = createForge({
 });
 ```
 
-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.
+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. Any agent name is accepted; known spellings are normalized (`Claude` and `claude-code` become `Claude Code`). Send the search query, or `"direct"`. When the merchant declares a `bazaar` extension, Forge adds the same field there (schema and example), so agents that discover the service through Bazaar see it too. `{ 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.
 

package/dist/ask.d.ts

@@ -8,6 +8,8 @@ export declare const TONES: readonly Tone[];
 export interface AskTexts {
     /** Appended to 402 challenge descriptions. "{rate_url}" and "{summary_url}" are substituted. */
     challengeSentence: string;
+    /** Used instead when the full sentence would push the description past MAX_DESCRIPTION. "{rate_url}" is substituted. */
+    shortChallengeSentence: string;
     /** The rate_this_call body field. "{feedback_url}" and "{summary_url}" are substituted. */
     rateHint: string;
     /** The `ask` line of the forge-feedback extension (challenge and receipt). */

package/dist/ask.js

@@ -3,12 +3,14 @@ export const TONES = ["soft", "lifecycle"];
 export const ASK = {
     soft: {
         challengeSentence: "After your call, please rate this service for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no), using the feedback_id from the response. Free, one request. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
+        shortChallengeSentence: "After your call, please rate it for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully. Free.",
         rateHint: "Please rate this service for other agents: GET {feedback_url} with fully, partially or no appended (e.g. {feedback_url}fully). Free, one request. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
         extensionAsk: "After your call, please rate this service for other agents. Free, one request. When the outcome is not fully, the issue field tells the merchant what to fix.",
         extensionExtras: {},
     },
     lifecycle: {
         challengeSentence: "This service's x402 flow has four steps: 1) this 402 challenge, 2) pay, 3) get the response, 4) rate the call for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no), using the feedback_id from the response. Step 4 is free and one request. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
+        shortChallengeSentence: "Step 4 of 4: rate the call for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully. Free.",
         rateHint: "Step 4 of 4: rate this call for other agents. GET {feedback_url} with fully, partially or no appended (e.g. {feedback_url}fully). Free, one request. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
         extensionAsk: "Step 4 of this service's flow: after the response, please rate the call for other agents. Free, one request. When the outcome is not fully, the issue field tells the merchant what to fix.",
         extensionExtras: { flow: ["402 challenge", "pay", "response", "rate"] },

package/dist/bazaar.d.ts

@@ -0,0 +1,7 @@
+import { type ContextOptions } from "./context.js";
+/**
+ * Declare agent context in a v2 challenge's `bazaar` extension, in place: an `agent_context` object on JSON
+ * bodies, or the `agent_*` query parameters on routes without a body. Other body types, composed or
+ * referenced schemas, and fields the merchant already declares are left alone. Returns whether it changed.
+ */
+export declare function addContextToBazaar(bazaar: unknown, options: ContextOptions): boolean;

package/dist/bazaar.js

@@ -0,0 +1,58 @@
+import { CONTEXT_FIELD, agentContextExample, agentContextQuerySchema, agentContextSchema } from "./context.js";
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** Keywords whose meaning an added property could change; such schemas are left alone. */
+const COMPOSED = ["$ref", "allOf", "anyOf", "oneOf", "not", "if", "then", "else", "dependentSchemas", "patternProperties"];
+function declarable(schema) {
+    if (!isObj(schema) || COMPOSED.some((key) => key in schema))
+        return false;
+    if (schema.type !== undefined && schema.type !== "object")
+        return false;
+    if (schema.properties !== undefined && !isObj(schema.properties))
+        return false;
+    return schema.required === undefined || Array.isArray(schema.required);
+}
+/**
+ * Add properties to one part of the Bazaar input (`body` or `queryParams`): the JSON Schema in `schema` and
+ * the example in `info`, together. Facilitators index the Bazaar copy a client echoes with its payment only
+ * when `info` validates against `schema`, so declaring a required field without an example drops the listing.
+ * `@x402/core` checks the echo as a superset of what the server advertised, so adding keys keeps payments valid.
+ */
+function extend(schemas, info, key, properties, required, example) {
+    const schema = schemas[key];
+    if (!declarable(schema))
+        return false;
+    const current = info[key];
+    if (current !== undefined && !isObj(current))
+        return false;
+    const declared = isObj(schema.properties) ? schema.properties : {};
+    const listed = (schema.required ?? []);
+    // The merchant already describes these fields: their declaration wins.
+    if (Object.keys(properties).some((name) => name in declared || listed.includes(name) || (isObj(current) && name in current)))
+        return false;
+    schema.properties = { ...declared, ...properties };
+    if (required.length)
+        schema.required = [...new Set([...listed, ...required])];
+    info[key] = { ...current, ...example };
+    return true;
+}
+/**
+ * Declare agent context in a v2 challenge's `bazaar` extension, in place: an `agent_context` object on JSON
+ * bodies, or the `agent_*` query parameters on routes without a body. Other body types, composed or
+ * referenced schemas, and fields the merchant already declares are left alone. Returns whether it changed.
+ */
+export function addContextToBazaar(bazaar, options) {
+    if (!isObj(bazaar) || !isObj(bazaar.info) || !isObj(bazaar.info.input) || !isObj(bazaar.schema))
+        return false;
+    const inputSchema = bazaar.schema.properties?.input;
+    if (!isObj(inputSchema) || !isObj(inputSchema.properties))
+        return false;
+    const info = bazaar.info.input;
+    const required = options.required !== false;
+    if (info.bodyType !== undefined || "body" in inputSchema.properties) {
+        if (info.bodyType !== "json")
+            return false;
+        return extend(inputSchema.properties, info, "body", { [CONTEXT_FIELD]: agentContextSchema(options) }, required ? [CONTEXT_FIELD] : [], { [CONTEXT_FIELD]: agentContextExample(options) });
+    }
+    const query = agentContextQuerySchema(options);
+    return extend(inputSchema.properties, info, "queryParams", query.properties, query.required, agentContextExample(options, "query"));
+}

package/dist/context.d.ts

@@ -1,5 +1,13 @@
 /** Suggested agent names; anything else is kept as given. */
 export declare const AGENT_TYPES: readonly ["Claude Code", "Codex", "Cursor", "Grok Bot", "Muse", "Hermes", "Instinct", "OpenClaw", "Others"];
+/**
+ * Example values for discovery documents that need one (Bazaar's `info`). Agents sometimes copy examples
+ * verbatim, so they are placeholders, and an unedited placeholder is recorded as missing rather than as a name.
+ */
+export declare const CONTEXT_PLACEHOLDERS: {
+    readonly agent_type: "your agent name";
+    readonly search_query: "your search query, or direct";
+};
 /** Suggested x402 clients; anything else is kept as given. */
 export declare const CLIENTS: readonly ["agentcash", "awal", "pay.sh", "other", "unknown"];
 /** JSON body field (POST, PUT, …). */
@@ -45,11 +53,6 @@ export declare function agentContextSchema({ searchQuery, required }?: ContextOp
             maxLength: number;
         } | undefined;
         agent_type: {
-            type: string;
-            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok Bot" | "Muse" | "Hermes" | "Instinct" | "OpenClaw" | "Others")[];
-            description: string;
-        };
-        agent_type_other: {
             description: string;
             minLength?: number | undefined;
             type: string;
@@ -60,7 +63,7 @@ export declare function agentContextSchema({ searchQuery, required }?: ContextOp
     type: string;
     description: string;
 };
-/** The optional query parameters, for operations without a request body. */
+/** The query parameters, for operations without a request body. */
 export declare function agentContextParameters({ searchQuery }?: {
     searchQuery?: boolean;
 }): {
@@ -68,7 +71,16 @@ export declare function agentContextParameters({ searchQuery }?: {
     description: string;
     schema: Record<string, unknown>;
 }[];
-/** One line for the forge-feedback extension, so clients that only inspect the 402 learn about it too. */
+/** The same parameters as JSON Schema properties, for discovery documents that describe a query object (Bazaar). */
+export declare function agentContextQuerySchema({ searchQuery, required }?: ContextOptions): {
+    properties: Record<string, Record<string, unknown>>;
+    required: string[];
+};
+/** Placeholder values matching agentContextSchema (body) or agentContextQuerySchema (query). */
+export declare function agentContextExample({ searchQuery }?: ContextOptions, where?: "body" | "query"): {
+    [x: string]: "your agent name" | "your search query, or direct";
+};
+/** One line for the forge-agent-context extension, so clients that only inspect the 402 learn about it too. */
 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

@@ -2,6 +2,20 @@
 // 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"];
+/** Spellings agents use for the suggested names, compared lowercase with only letters and digits kept. */
+const AGENT_ALIASES = {
+    claude: "Claude Code", claudecode: "Claude Code", claudecodecli: "Claude Code", anthropicclaudecode: "Claude Code",
+    codex: "Codex", codexcli: "Codex", openaicodex: "Codex",
+    cursor: "Cursor", cursoragent: "Cursor", cursorai: "Cursor",
+    grok: "Grok Bot", grokbot: "Grok Bot",
+    muse: "Muse", hermes: "Hermes", hermesagent: "Hermes", instinct: "Instinct", openclaw: "OpenClaw",
+    other: "Others", others: "Others", othersspecify: "Others", unknown: "Others",
+};
+/**
+ * Example values for discovery documents that need one (Bazaar's `info`). Agents sometimes copy examples
+ * verbatim, so they are placeholders, and an unedited placeholder is recorded as missing rather than as a name.
+ */
+export const CONTEXT_PLACEHOLDERS = { agent_type: "your agent name", search_query: "your search query, or direct" };
 /** Suggested x402 clients; anything else is kept as given. */
 export const CLIENTS = ["agentcash", "awal", "pay.sh", "other", "unknown"];
 /** JSON body field (POST, PUT, …). */
@@ -29,15 +43,13 @@ export function parseAgentContext(input, { searchQuery = true } = {}) {
         let text = raw.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, LIMITS[key]);
         if (!text)
             continue;
-        if (key === "agent_type") {
-            if (/^grok(?: bot)?$/i.test(text))
-                text = "Grok Bot";
-            if (/^(?:others?(?: \(specify\))?|unknown)$/i.test(text))
-                text = "Others";
-        }
+        if ((key === "agent_type" || key === "search_query") && text.toLowerCase() === CONTEXT_PLACEHOLDERS[key])
+            continue;
+        if (key === "agent_type")
+            text = AGENT_ALIASES[text.toLowerCase().replace(/[^a-z0-9]/g, "")] ?? text;
         if (key === "search_query" && /^direct$/i.test(text))
             text = "direct";
-        const known = key === "agent_type" ? AGENT_TYPES : key === "client" ? CLIENTS : null;
+        const known = key === "client" ? CLIENTS : null;
         context[key] = known?.find((v) => v.toLowerCase() === text.toLowerCase()) ?? text;
     }
     return Object.keys(context).length ? context : undefined;
@@ -86,8 +98,7 @@ export function takeFromUrl(url) {
 }
 const DESCRIPTIONS = {
     object: "information about the calling agent and how it found this service.",
-    agent_type: "Which agent are you? Choose Others if yours is not listed and share its name in agent_type_other.",
-    agent_type_other: "Your agent's name, when agent_type is Others.",
+    agent_type: `Your agent's name, for example ${AGENT_TYPES.filter((name) => name !== "Others").join(", ")}. Any name works.`,
     search_query: "The search query you used to find this service, or \"direct\" if you did not search.",
 };
 /** JSON Schema for the `agent_context` body property. */
@@ -97,23 +108,36 @@ export function agentContextSchema({ searchQuery = true, required = true } = {})
         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, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.agent_type_other },
+            agent_type: { type: "string", maxLength: LIMITS.agent_type, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.agent_type },
             ...(searchQuery ? { search_query: { type: "string", maxLength: LIMITS.search_query, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.search_query } } : {}),
         },
     };
 }
-/** The optional query parameters, for operations without a request body. */
+/** The query parameters, for operations without a request body. */
 export function agentContextParameters({ searchQuery = true } = {}) {
     const params = [
-        { name: CONTEXT_QUERY.agent_type, description: DESCRIPTIONS.agent_type, schema: { type: "string", enum: [...AGENT_TYPES] } },
-        { name: CONTEXT_QUERY.agent_type_other, description: DESCRIPTIONS.agent_type_other, schema: { type: "string", maxLength: LIMITS.agent_type_other } },
+        { name: CONTEXT_QUERY.agent_type, description: DESCRIPTIONS.agent_type, schema: { type: "string", maxLength: LIMITS.agent_type } },
     ];
     if (searchQuery)
         params.push({ name: CONTEXT_QUERY.search_query, description: DESCRIPTIONS.search_query, schema: { type: "string", maxLength: LIMITS.search_query } });
     return params;
 }
-/** One line for the forge-feedback extension, so clients that only inspect the 402 learn about it too. */
+/** The same parameters as JSON Schema properties, for discovery documents that describe a query object (Bazaar). */
+export function agentContextQuerySchema({ searchQuery = true, required = true } = {}) {
+    const properties = {};
+    for (const p of agentContextParameters({ searchQuery }))
+        properties[p.name] = { ...p.schema, ...(required ? { minLength: 1 } : {}), description: p.description };
+    return { properties, required: required ? Object.keys(properties) : [] };
+}
+/** Placeholder values matching agentContextSchema (body) or agentContextQuerySchema (query). */
+export function agentContextExample({ searchQuery = true } = {}, where = "body") {
+    const names = where === "query" ? { agent_type: CONTEXT_QUERY.agent_type, search_query: CONTEXT_QUERY.search_query } : { agent_type: "agent_type", search_query: "search_query" };
+    return {
+        [names.agent_type]: CONTEXT_PLACEHOLDERS.agent_type,
+        ...(searchQuery ? { [names.search_query]: CONTEXT_PLACEHOLDERS.search_query } : {}),
+    };
+}
+/** One line for the forge-agent-context extension, so clients that only inspect the 402 learn about it too. */
 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";
@@ -128,12 +152,6 @@ export function contextIssues(raw, { searchQuery = true }) {
             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");
-    }
+    // Any name is accepted: known spellings are normalized by parseAgentContext, others are kept as given.
     return issues;
 }

package/dist/core.js

@@ -210,12 +210,16 @@ function enabledCore(options, configWarnings) {
     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;
+    // The short form always contains the rate URL, so the marker still recognizes a described challenge.
+    const shortChallengeSentence = ASK[tone].shortChallengeSentence.replaceAll("{rate_url}", rateUrl);
     const challengeAdditions = {
-        ...(describe ? { sentence: challengeSentence, marker: challengeMarker } : {}),
-        ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery, required: requiredContext }) : undefined) }),
+        ...(describe ? { sentence: challengeSentence, marker: challengeMarker, ...(challengeMarker === rateUrl ? { shortSentence: shortChallengeSentence } : {}) } : {}),
+        ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone) }),
     };
-    if (!feedback && collectContext)
+    if (collectContext)
         challengeAdditions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery, required: requiredContext }), optional: !requiredContext } };
+    if (collectContext)
+        challengeAdditions.bazaarContext = { searchQuery, required: 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;

package/dist/x402.d.ts

@@ -1,14 +1,14 @@
 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";
 /**
  * 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,21 +42,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;
-    /** Independent context prompt when feedback is disabled. */
+    /** 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,14 @@
 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";
 /**
  * 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,
@@ -18,7 +19,6 @@ export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
             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.",
             payment: "None. Plain GET, not an x402 endpoint.",
-            ...(agentContext ? { agent_context: agentContext } : {}),
         },
     };
 }
@@ -57,16 +57,31 @@ 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;
@@ -81,17 +96,20 @@ function addToV2(challenge, add) {
             changed = true;
         }
         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 and content.
+            // 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) {
@@ -124,7 +142,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") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.5.0-beta.7",
+  "version": "0.5.0-beta.9",
   "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",