@forgeintel/sdk 0.2.0-beta.0 → 0.3.0-beta.0

package/README.md

@@ -19,7 +19,33 @@ app.use(forge.middleware());                        // 1. first: before payments
 app.use(paymentMiddleware(routes, resourceServer)); // 2. your existing x402 setup, unchanged
 ```
 
-Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5.
+Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5. The root export is the Express adapter (also at `@forgeintel/sdk/express`).
+
+## Hono (Node, Bun, Deno, Cloudflare Workers)
+
+```ts
+import { createForge } from "@forgeintel/sdk/hono";
+
+const forge = createForge({ apiKey, backendUrl, publicUrl });
+app.use(forge.middleware());                        // before paymentMiddleware from @x402/hono
+app.use(paymentMiddleware(routes, resourceServer));
+```
+
+## Next.js (App Router)
+
+```ts
+import { createForge } from "@forgeintel/sdk/next";
+
+export const forge = createForge({ apiKey, backendUrl, publicUrl });
+// app/api/…/route.ts: Forge outermost, around @x402/next's withX402
+export const POST = forge.withForge(withX402(handler, route, resourceServer));
+// app/feedback/[[...path]]/route.ts: Forge's own routes
+export const { GET, POST, HEAD } = forge.routes;
+```
+
+## Any fetch handler
+
+`@forgeintel/sdk/fetch`: `export default { fetch: forge.wrap(handler) }`, or `forge.handle(request, next)` per request.
 
 ## Any other framework
 
@@ -37,7 +63,9 @@ Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require
 | `GET /feedback/rate` | Quick rating: `feedback_id`, `outcome`, optional `issue`. |
 | `POST /feedback` | Same fields, plus an optional `note` (≤ 280 chars). |
 | `GET /feedback`, `GET /feedback/summary` | The form description, and public aggregate ratings. |
-| Every 402 and paid call | Sends a challenge or interaction event to the backend in the background. |
+| Payment receipt (v2) | Adds the `forge-feedback` extension, with the real ID, to the `PAYMENT-RESPONSE` settlement header. |
+| Paid request | Reads the agent's self-reported `agent_context` (JSON body) or `agent_*` query parameters, and removes them before your code runs. |
+| Every 402 and paid call | Sends a challenge or interaction event (with any agent context) to the backend in the background. |
 
 IDs are minted locally with an HMAC, so the paid path makes no network call. If the backend is down, paid calls still work, and ratings return `503 feedback_unavailable`.
 
@@ -59,9 +87,12 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `backendUrl` | required | Forge backend origin. |
 | `publicUrl` | required | This service's public origin. Used in rating URLs. |
 | `basePath` | `/feedback` | Feedback routes (`/feedback`, `/feedback/rate`, `/feedback/summary`). |
+| `tone` | `"soft"` | `"lifecycle"` describes this service's flow as four steps (402, pay, response, rate). Both stay soft asks. |
 | `describeChallenges` | `true` | Append the sentence to 402 challenges. |
-| `challengeSentence` | built-in | Override for wording experiments. `{rate_url}` and `{summary_url}` are substituted. |
+| `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, client, search query), record it, and remove it before your code runs. `{ searchQuery: false }` or `false` to limit. |
 | `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. |
@@ -69,6 +100,7 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `ttlMs` | 24h | Local pre-check; keep in sync with the backend. |
 | `flushIntervalMs` | `2000` | Event batching interval. |
 | `onError` | `console.warn` | Called for internal errors. Business requests are never affected. |
+| `strict` | `false` | Throw on invalid options (for CI). By default Forge warns and turns itself off. |
 
 `forge.diagnostics()` returns counters and the last OpenAPI report. `forge.enrichOpenApi(doc)` is available for build-time use. Call `await forge.shutdown()` in your shutdown handler to flush pending events.
 

package/dist/ask.d.ts

@@ -0,0 +1,25 @@
+/**
+ * How the rating is asked for. Both are soft asks; neither may claim the rating is required.
+ * - soft: "please rate this service for other agents" (the default)
+ * - lifecycle: describes this service's flow as four steps, the fourth being the rating
+ */
+export type Tone = "soft" | "lifecycle";
+export declare const TONES: readonly Tone[];
+export interface AskTexts {
+    /** Appended to 402 challenge descriptions. "{rate_url}" and "{summary_url}" are substituted. */
+    challengeSentence: 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). */
+    extensionAsk: string;
+    /** Extra extension fields for this tone. */
+    extensionExtras: Record<string, unknown>;
+}
+export declare const ASK: Record<Tone, AskTexts>;
+/**
+ * The lines Forge holds whatever a merchant configures: the rating is never presented as required,
+ * nothing is made to depend on it, and it never asks for user data. All Forge merchants share one
+ * reputation with agents; wording that reads as pressure gets Forge flagged as prompt injection for everyone.
+ * Returns why the text crosses a line, or null when it's fine.
+ */
+export declare function checkAskText(text: string): string | null;

package/dist/ask.js

@@ -0,0 +1,36 @@
+// What agents are asked, in each tone, and the lines no wording may cross.
+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.",
+        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.",
+        extensionAsk: "After your call, please rate this service for other agents. Free, one request.",
+        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.",
+        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.",
+        extensionAsk: "Step 4 of this service's flow: after the response, please rate the call for other agents. Free, one request.",
+        extensionExtras: { flow: ["402 challenge", "pay", "response", "rate"] },
+    },
+};
+const PRESSURE = /\b(required|requires?|mandatory|obligatory|compulsory|must|have to|has to|needs? to|necessary)\b/i;
+const CONDITIONS = /\b(refunds?|penalt(y|ies)|withh(o|e)ld|or else|otherwise|blocked|banned)\b/i;
+const USER_DATA = /\b(e-?mail|password|passphrase|seed phrase|private key|secret|credit card|phone number|your user'?s)\b/i;
+/**
+ * The lines Forge holds whatever a merchant configures: the rating is never presented as required,
+ * nothing is made to depend on it, and it never asks for user data. All Forge merchants share one
+ * reputation with agents; wording that reads as pressure gets Forge flagged as prompt injection for everyone.
+ * Returns why the text crosses a line, or null when it's fine.
+ */
+export function checkAskText(text) {
+    if (PRESSURE.test(text))
+        return `presents the rating as required ("${text.match(PRESSURE)[0]}")`;
+    if (CONDITIONS.test(text))
+        return `makes something depend on the rating ("${text.match(CONDITIONS)[0]}")`;
+    if (USER_DATA.test(text))
+        return `asks about user data ("${text.match(USER_DATA)[0]}")`;
+    if (/[<>]/.test(text))
+        return "uses angle brackets, which some viewers escape (use FEEDBACK_ID instead of <id>)";
+    return null;
+}

package/dist/context.d.ts

@@ -0,0 +1,74 @@
+/** Suggested agent names; anything else is kept as given. */
+export declare const AGENT_TYPES: readonly ["Claude Code", "Codex", "Cursor", "Grok", "Hermes", "OpenClaw", "Other", "Unknown"];
+/** 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, …). */
+export declare const CONTEXT_FIELD = "agent_context";
+/** Query parameters (GET and other requests without a body), prefixed so they don't collide with the merchant's. */
+export declare const CONTEXT_QUERY: {
+    readonly agent_type: "agent_type";
+    readonly agent_type_other: "agent_type_other";
+    readonly client: "agent_client";
+    readonly search_query: "agent_search_query";
+};
+export interface AgentContext {
+    agent_type?: string;
+    agent_type_other?: string;
+    client?: string;
+    search_query?: string;
+}
+/** Lenient: bad or unknown values are dropped or kept as plain text, never rejected. Known names get their canonical case. */
+export declare function parseAgentContext(input: unknown, { searchQuery }?: {
+    searchQuery?: boolean;
+}): AgentContext | undefined;
+/** Split `agent_context` off a parsed JSON body. The body is returned as a new object; the input is untouched. */
+export declare function takeFromBody(body: unknown): {
+    body: unknown;
+    raw?: unknown;
+};
+/** Split the agent_* query parameters off a URL (path + query). Other parameters stay byte-for-byte as they were. */
+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 }?: {
+    searchQuery?: boolean;
+}): {
+    type: string;
+    description: string;
+    properties: {
+        search_query?: {
+            type: string;
+            maxLength: number;
+            description: string;
+        } | undefined;
+        agent_type: {
+            type: string;
+            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok" | "Hermes" | "OpenClaw" | "Other" | "Unknown")[];
+            description: string;
+        };
+        agent_type_other: {
+            type: string;
+            maxLength: number;
+            description: string;
+        };
+        client: {
+            type: string;
+            enum: ("agentcash" | "awal" | "pay.sh" | "other" | "unknown")[];
+            description: string;
+        };
+    };
+};
+/** The optional query parameters, for operations without a request body. */
+export declare function agentContextParameters({ searchQuery }?: {
+    searchQuery?: boolean;
+}): {
+    name: string;
+    description: string;
+    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, client, search_query} to your paid request's JSON body (without a body: agent_type, agent_client, agent_search_query query parameters). Self-reported; omit what you don't know. search_query is what you searched to find this service, never your user's request." | "Please add agent_context {agent_type, client} to your paid request's JSON body (without a body: agent_type and agent_client query parameters). Self-reported; omit what you don't know.";

package/dist/context.js

@@ -0,0 +1,117 @@
+// 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.
+/** Suggested agent names; anything else is kept as given. */
+export const AGENT_TYPES = ["Claude Code", "Codex", "Cursor", "Grok", "Hermes", "OpenClaw", "Other", "Unknown"];
+/** Suggested x402 clients; anything else is kept as given. */
+export const CLIENTS = ["agentcash", "awal", "pay.sh", "other", "unknown"];
+/** JSON body field (POST, PUT, …). */
+export const CONTEXT_FIELD = "agent_context";
+/** Query parameters (GET and other requests without a body), prefixed so they don't collide with the merchant's. */
+export const CONTEXT_QUERY = {
+    agent_type: "agent_type",
+    agent_type_other: "agent_type_other",
+    client: "agent_client",
+    search_query: "agent_search_query",
+};
+const LIMITS = { agent_type: 80, agent_type_other: 80, client: 80, search_query: 200 };
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** Lenient: bad or unknown values are dropped or kept as plain text, never rejected. Known names get their canonical case. */
+export function parseAgentContext(input, { searchQuery = true } = {}) {
+    if (!isObj(input))
+        return undefined;
+    const context = {};
+    for (const key of Object.keys(LIMITS)) {
+        if (key === "search_query" && !searchQuery)
+            continue;
+        const raw = Array.isArray(input[key]) ? input[key][0] : input[key];
+        if (typeof raw !== "string")
+            continue;
+        const text = raw.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, LIMITS[key]);
+        if (!text)
+            continue;
+        const known = key === "agent_type" ? AGENT_TYPES : key === "client" ? CLIENTS : null;
+        context[key] = known?.find((v) => v.toLowerCase() === text.toLowerCase()) ?? text;
+    }
+    return Object.keys(context).length ? context : undefined;
+}
+/** Split `agent_context` off a parsed JSON body. The body is returned as a new object; the input is untouched. */
+export function takeFromBody(body) {
+    if (!isObj(body) || Object.getPrototypeOf(body) !== Object.prototype || !Object.hasOwn(body, CONTEXT_FIELD))
+        return { body };
+    const { [CONTEXT_FIELD]: raw, ...rest } = body;
+    return { body: rest, raw };
+}
+/** Split the agent_* query parameters off a URL (path + query). Other parameters stay byte-for-byte as they were. */
+export function takeFromUrl(url) {
+    const q = url.indexOf("?");
+    if (q < 0)
+        return { url };
+    const hash = url.indexOf("#", q);
+    const query = url.slice(q + 1, hash < 0 ? undefined : hash);
+    const names = new Map(Object.entries(CONTEXT_QUERY).map(([k, v]) => [v, k]));
+    const raw = {};
+    const kept = [];
+    for (const segment of query.split("&")) {
+        const eq = segment.indexOf("=");
+        let key;
+        let value;
+        try {
+            key = decodeURIComponent((eq < 0 ? segment : segment.slice(0, eq)).replace(/\+/g, " "));
+            value = eq < 0 ? "" : decodeURIComponent(segment.slice(eq + 1).replace(/\+/g, " "));
+        }
+        catch {
+            kept.push(segment); // not ours if we can't even decode it
+            continue;
+        }
+        const field = names.get(key);
+        if (field) {
+            if (!(field in raw))
+                raw[field] = value;
+        }
+        else
+            kept.push(segment);
+    }
+    if (!Object.keys(raw).length)
+        return { url };
+    const rest = kept.filter(Boolean).join("&");
+    return { url: `${url.slice(0, q)}${rest ? `?${rest}` : ""}${hash < 0 ? "" : url.slice(hash)}`, raw };
+}
+const DESCRIPTIONS = {
+    object: "Self-reported context about the calling agent, so the merchant can see which agents use this service. Not needed for the result; omit anything you don't know.",
+    agent_type: "Which agent are you? Use Other (with agent_type_other) if yours isn't listed, or Unknown.",
+    agent_type_other: "Your agent's name, when agent_type is Other.",
+    client: "Which x402 client or wallet paid for this call?",
+    search_query: "The search terms you used to find this service, for example in a marketplace or search tool. Omit if you didn't search; don't invent one, and never include your user's request.",
+};
+/** JSON Schema for the optional `agent_context` body property. */
+export function agentContextSchema({ searchQuery = true } = {}) {
+    return {
+        type: "object",
+        description: DESCRIPTIONS.object,
+        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 },
+            client: { type: "string", enum: [...CLIENTS], description: DESCRIPTIONS.client },
+            ...(searchQuery ? { search_query: { type: "string", maxLength: LIMITS.search_query, description: DESCRIPTIONS.search_query } } : {}),
+        },
+    };
+}
+/** The optional 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.client, description: DESCRIPTIONS.client, schema: { type: "string", enum: [...CLIENTS] } },
+    ];
+    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. */
+export function agentContextAsk({ searchQuery = true } = {}) {
+    return searchQuery
+        ? "Please add agent_context {agent_type, client, search_query} to your paid request's JSON body (without a body: agent_type, agent_client, agent_search_query query parameters). Self-reported; omit what you don't know. search_query is what you searched to find this service, never your user's request."
+        : "Please add agent_context {agent_type, client} to your paid request's JSON body (without a body: agent_type and agent_client query parameters). Self-reported; omit what you don't know.";
+}

package/dist/core.d.ts

@@ -1,4 +1,5 @@
 import { type EnrichReport } from "./openapi.js";
+import { type Tone } from "./ask.js";
 export interface OpenApiOptions {
     /** Paths where your OpenAPI JSON is served. Default ["/openapi.json"]. */
     paths?: string[];
@@ -20,15 +21,39 @@ export interface ForgeOptions {
     publicUrl: string;
     /** Path for the feedback routes. Default "/feedback" (quick rating at "/feedback/rate"). */
     basePath?: string;
+    /**
+     * How the rating is asked for: "soft" (default, "please rate this service for other agents") or "lifecycle"
+     * (describes this service's flow as four steps: 402, pay, response, rate). Both stay soft asks.
+     */
+    tone?: Tone;
     /** Append the rating sentence to x402 challenges (v2 header, v1 JSON body). Default true. */
     describeChallenges?: boolean;
-    /** Override the appended sentence, for wording experiments. "{rate_url}" and "{summary_url}" are substituted. */
+    /**
+     * Override the appended sentence, for wording experiments. "{rate_url}" and "{summary_url}" are substituted.
+     * Text that presents the rating as required, makes anything depend on it, or asks for user data is refused
+     * (with a warning) and the tone's default is used.
+     */
     challengeSentence?: string;
     /**
      * Add a structured `forge-feedback` extension to x402 v2 challenges (next to e.g. `bazaar`), which clients
      * that inspect the 402 print as its own block. Default true; `false` turns it off. v1 challenges have no extensions.
      */
     challengeExtension?: boolean;
+    /**
+     * Add the `forge-feedback` extension, with the real feedback_id, to the x402 v2 payment receipt
+     * (the PAYMENT-RESPONSE settlement header), so the rating follows the payment on the wire. Default true.
+     */
+    receiptExtension?: boolean;
+    /**
+     * Agent context: optional, self-reported `agent_context` {agent_type, client, search_query} on the paid request
+     * (JSON body, or agent_type / agent_client / 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).
+     */
+    agentContext?: boolean | {
+        searchQuery?: boolean;
+    };
     /** Add feedback_id and feedback_url to JSON object bodies of paid responses. Default true. */
     injectBody?: boolean;
     /**
@@ -80,8 +105,18 @@ export interface ForgeCall {
     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. */
     text(status: number, contentType: string, body: string): string;
-    /** Headers to set once the final status is known: a rewritten PAYMENT-REQUIRED on 402, Forge-Feedback-Id on paid 2xx. */
-    headers(status: number, paymentRequired: string | undefined): Record<string, string>;
+    /**
+     * Headers to set once the final status is known: a rewritten PAYMENT-REQUIRED on 402; on a paid 2xx,
+     * Forge-Feedback-Id and (when you pass the settlement header) a PAYMENT-RESPONSE with the receipt extension.
+     */
+    headers(status: number, paymentRequired: string | undefined, paymentResponse?: string): Record<string, string>;
+    /**
+     * A parsed JSON request body, before your validators and handlers see it: reads `agent_context` and returns
+     * the body without it (a new object; other fields untouched). Anything else is returned as is.
+     */
+    requestBody(body: unknown): unknown;
+    /** A request URL (path + query): reads the agent_* query parameters and returns the URL without them. */
+    requestUrl(url: string): string;
     /**
      * Report the challenge / interaction events after the response is sent. A 402 counts as a challenge when
      * headers() saw a PAYMENT-REQUIRED value or json() saw a challenge body; pass true if you know of one otherwise.

package/dist/core.js

@@ -2,15 +2,16 @@
 // objects to the small interfaces below and write out what the core returns.
 import { DEFAULT_TTL_MS, 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 { EventReporter } from "./reporter.js";
 import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL, parseSubmission } from "./values.js";
-import { describeChallenge, describeChallengeBody, feedbackExtension, readPaymentHeader } from "./x402.js";
+import { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, readPaymentHeader, receiptExtension } from "./x402.js";
 export const FEEDBACK_HEADERS = { "Cache-Control": "no-store", "X-Robots-Tag": "noindex" };
 /** Max JSON body for POST {basePath}. */
 export const BODY_LIMIT = 8 * 1024;
 /** Max OpenAPI document an adapter should buffer for enrichment. */
 export const SPEC_LIMIT = 10 * 1024 * 1024;
-const DEFAULT_RATE_HINT = "Please rate this service for other agents: GET {feedback_url} with fully, partially or no appended (e.g. {feedback_url}fully). Free, one request.";
 /**
  * Check options without throwing. Invalid required options are errors (Forge runs disabled);
  * invalid optional values are warnings and fall back to their defaults.
@@ -55,10 +56,21 @@ export function checkOptions(input) {
     fallback("flushIntervalMs", positive(raw.flushIntervalMs), "must be a positive number of milliseconds");
     fallback("fetch", typeof raw.fetch === "function", "must be a fetch function");
     fallback("onError", typeof raw.onError === "function", "must be a function");
+    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");
-    for (const key of ["describeChallenges", "challengeExtension", "injectBody", "injectText", "strict"])
+    fallback("agentContext", boolean(raw.agentContext) || (!!raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)), "must be true, false or { searchQuery }");
+    for (const key of ["describeChallenges", "challengeExtension", "receiptExtension", "injectBody", "injectText", "strict"])
         fallback(key, boolean(raw[key]), "must be true or false");
+    // The lines no wording may cross, whatever the merchant configures (see ask.ts).
+    for (const key of ["challengeSentence", "rateHint"]) {
+        const text = options[key];
+        const problem = typeof text === "string" ? checkAskText(text) : null;
+        if (problem) {
+            warnings.push(`${key} ${problem}; Forge never presents the rating as required or conditional, or asks for user data. Using the default`);
+            delete options[key];
+        }
+    }
     if (raw.openapi !== undefined && raw.openapi !== false) {
         const openapi = raw.openapi;
         if (!openapi || typeof openapi !== "object")
@@ -81,7 +93,15 @@ export function checkOptions(input) {
 }
 /** Everything passes through untouched. Used when invalid options turned Forge off. */
 function disabledCore(errors, warnings) {
-    const passThrough = { feedbackId: undefined, json: (_status, body) => body, text: (_status, _type, body) => body, headers: () => ({}), finish: () => { } };
+    const passThrough = {
+        feedbackId: undefined,
+        json: (_status, body) => body,
+        text: (_status, _type, body) => body,
+        headers: () => ({}),
+        requestBody: (body) => body,
+        requestUrl: (url) => url,
+        finish: () => { },
+    };
     return {
         enabled: false,
         challengeSentence: "",
@@ -134,11 +154,16 @@ function enabledCore(options, configWarnings) {
     const describe = options.describeChallenges ?? true;
     const injectBody = options.injectBody ?? true;
     const injectText = options.injectText ?? false;
+    const tone = options.tone ?? "soft";
+    const contextOption = options.agentContext ?? true;
+    const collectContext = contextOption !== false;
+    const searchQuery = collectContext && (typeof contextOption !== "object" || contextOption.searchQuery !== false);
+    const receipts = options.receiptExtension ?? true;
     const rateHint = options.rateHint === false
         ? null
         : typeof options.rateHint === "string" && options.rateHint.trim()
             ? options.rateHint
-            : DEFAULT_RATE_HINT;
+            : ASK[tone].rateHint;
     const openapi = options.openapi === false ? null : (options.openapi ?? {});
     const specPaths = new Set(openapi?.paths ?? ["/openapi.json"]);
     const stats = {
@@ -157,13 +182,12 @@ function enabledCore(options, configWarnings) {
             lastLogged = message;
         });
     const reporter = new EventReporter(new URL("/v1/events", backendUrl).href, apiKey, fetchImpl, onError, options.flushIntervalMs ?? 2000);
-    const challengeSentence = options.challengeSentence?.replaceAll("{rate_url}", rateUrl).replaceAll("{summary_url}", summaryUrl) ??
-        `After your call, please rate this service for other agents: GET ${rateUrl}?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no), using the feedback_id from the response. Free, one request.`;
+    const challengeSentence = (options.challengeSentence ?? ASK[tone].challengeSentence).replaceAll("{rate_url}", rateUrl).replaceAll("{summary_url}", summaryUrl);
     // Idempotency marker: the rate URL when the sentence contains it, otherwise the sentence itself.
     const challengeMarker = challengeSentence.includes(rateUrl) ? rateUrl : challengeSentence;
     const challengeAdditions = {
         ...(describe ? { sentence: challengeSentence, marker: challengeMarker } : {}),
-        ...(options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl) }),
+        ...(options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery }) : undefined) }),
     };
     const touchChallenges = Boolean(challengeAdditions.sentence || challengeAdditions.extension);
     // Set once a document has been enriched; lets body injection respect strict response schemas.
@@ -178,6 +202,7 @@ function enabledCore(options, configWarnings) {
             isPaidOperation: openapi?.isPaidOperation,
             describeOperations: openapi?.describeOperations,
             hintField: Boolean(rateHint),
+            agentContext: collectContext ? { searchQuery } : undefined,
         });
         stats.openapi = result.report;
         if (result.report.enriched)
@@ -301,7 +326,15 @@ function enabledCore(options, configWarnings) {
         }
         return null;
     }
-    const passThrough = { feedbackId: undefined, json: (_status, body) => body, text: (_status, _type, body) => body, headers: () => ({}), finish: () => { } };
+    const passThrough = {
+        feedbackId: undefined,
+        json: (_status, body) => body,
+        text: (_status, _type, body) => body,
+        headers: () => ({}),
+        requestBody: (body) => body,
+        requestUrl: (url) => url,
+        finish: () => { },
+    };
     function call(request) {
         try {
             return startCall(request);
@@ -322,6 +355,14 @@ function enabledCore(options, configWarnings) {
         const feedbackUrl = feedbackId ? `${rateUrl}?feedback_id=${feedbackId}&outcome=` : "";
         let bodyChallenge = false;
         let headerChallenge = false;
+        let context;
+        const remember = (raw) => {
+            if (!collectContext)
+                return;
+            const parsed = parseAgentContext(raw, { searchQuery });
+            if (parsed)
+                context = { ...context, ...parsed };
+        };
         const ok = (status) => status >= 200 && status < 300;
         const handle = {
             feedbackId,
@@ -366,7 +407,7 @@ function enabledCore(options, configWarnings) {
                     return body;
                 return `${body}${body.endsWith("\n") ? "" : "\n"}\nfeedback_id: ${feedbackId}\nfeedback_url: ${feedbackUrl}\n`;
             },
-            headers(status, paymentRequired) {
+            headers(status, paymentRequired, paymentResponse) {
                 const set = {};
                 try {
                     if (status === 402 && paymentRequired)
@@ -378,14 +419,42 @@ function enabledCore(options, configWarnings) {
                             stats.challengesDescribed++;
                         }
                     }
-                    if (feedbackId && ok(status))
+                    if (feedbackId && ok(status)) {
                         set["Forge-Feedback-Id"] = feedbackId;
+                        const receipt = receipts && paymentResponse ? describeReceipt(paymentResponse, receiptExtension(rateUrl, feedbackId, tone)) : undefined;
+                        if (receipt)
+                            set["PAYMENT-RESPONSE"] = receipt;
+                    }
                 }
                 catch (error) {
                     onError(error);
                 }
                 return set;
             },
+            requestBody(body) {
+                try {
+                    const taken = takeFromBody(body);
+                    if ("raw" in taken)
+                        remember(taken.raw);
+                    return taken.body;
+                }
+                catch (error) {
+                    onError(error);
+                    return body;
+                }
+            },
+            requestUrl(url) {
+                try {
+                    const taken = takeFromUrl(url);
+                    if (taken.raw)
+                        remember(taken.raw);
+                    return taken.url;
+                }
+                catch (error) {
+                    onError(error);
+                    return url;
+                }
+            },
             finish(status, hadChallengeHeader = false) {
                 try {
                     report(status, hadChallengeHeader);
@@ -399,7 +468,7 @@ function enabledCore(options, configWarnings) {
             const ts = Date.now();
             if (status === 402 && (hadChallengeHeader || headerChallenge || bodyChallenge)) {
                 // v2 carries the challenge in a header; v1 in the body. Both count as a challenge.
-                reporter.push({ type: "challenge", route, ts, user_agent: userAgent });
+                reporter.push({ type: "challenge", route, ts, user_agent: userAgent, ...(context ? { agent_context: context } : {}) });
             }
             if (feedbackId) {
                 const facts = readPaymentHeader(paymentHeader);
@@ -412,6 +481,7 @@ function enabledCore(options, configWarnings) {
                     // Only report the payer once the call succeeded (i.e. settlement went through).
                     ...(ok(status) ? facts : { network: facts.network, amount: facts.amount }),
                     user_agent: userAgent,
+                    ...(context ? { agent_context: context } : {}),
                     ts,
                 });
             }