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

package/dist/express.js

@@ -1,3 +1,4 @@
+import { CONTEXT_QUERY } from "./context.js";
 import { BODY_LIMIT, SPEC_LIMIT, createForgeCore } from "./core.js";
 /** Never throws (unless `strict`): with invalid options it warns and returns a middleware that only calls next(). */
 export function createForge(options) {
@@ -97,8 +98,40 @@ export function createForge(options) {
             return end.call(res, body, done);
         };
     }
+    /**
+     * Agent context is read and removed before the merchant's validators and handlers run, so their API contract
+     * never changes. Query parameters: rewrite req.url (Express 5 re-reads req.query from it; Express 4 parsed
+     * req.query already, so delete them there too). Body: intercept the parser's `req.body = …` assignment,
+     * which leaves the request stream untouched for raw-body routes.
+     */
+    function takeAgentContext(req, call) {
+        const url = call.requestUrl(req.url);
+        if (url !== req.url) {
+            req.url = url;
+            const query = Object.getOwnPropertyDescriptor(req, "query");
+            if (query && "value" in query && query.value && typeof query.value === "object") {
+                for (const name of Object.values(CONTEXT_QUERY))
+                    delete query.value[name];
+            }
+        }
+        let body = call.requestBody(req.body);
+        Object.defineProperty(req, "body", {
+            configurable: true,
+            enumerable: true,
+            get: () => body,
+            set: (value) => {
+                body = call.requestBody(value);
+            },
+        });
+    }
     function observe(req, res) {
         const call = core.call({ method: req.method, path: req.originalUrl.split("?")[0], header: (name) => req.get(name) });
+        try {
+            takeAgentContext(req, call);
+        }
+        catch (error) {
+            core.onError(error);
+        }
         const originalJson = res.json.bind(res);
         res.json = ((body) => originalJson(call.json(res.statusCode, body)));
         if (call.feedbackId) {
@@ -120,11 +153,16 @@ export function createForge(options) {
             try {
                 // Headers may be set via setHeader (Express) or passed straight to writeHead.
                 const inline = rest.find((a) => !!a && typeof a === "object" && !Array.isArray(a));
-                const inlineKey = inline && Object.keys(inline).find((k) => k.toLowerCase() === "payment-required");
-                const current = inlineKey ? inline[inlineKey] : res.getHeader("payment-required");
-                for (const [name, value] of Object.entries(call.headers(statusCode, typeof current === "string" ? current : undefined))) {
-                    if (name === "PAYMENT-REQUIRED" && inlineKey)
-                        inline[inlineKey] = value;
+                const inlineKey = (name) => inline && Object.keys(inline).find((k) => k.toLowerCase() === name.toLowerCase());
+                const current = (name) => {
+                    const key = inlineKey(name);
+                    const value = key ? inline[key] : res.getHeader(name);
+                    return typeof value === "string" ? value : undefined;
+                };
+                for (const [name, value] of Object.entries(call.headers(statusCode, current("payment-required"), current("payment-response")))) {
+                    const key = inlineKey(name);
+                    if (key)
+                        inline[key] = value;
                     else
                         res.setHeader(name, value);
                 }

package/dist/fetch.d.ts

@@ -0,0 +1,17 @@
+import { type ForgeCore, type ForgeOptions, type ForgeResponse } from "./core.js";
+export type { ForgeOptions, OpenApiOptions } from "./core.js";
+type Next = (request: Request) => Response | Promise<Response>;
+export interface ForgeFetch extends Pick<ForgeCore, "enabled" | "challengeSentence" | "enrichOpenApi" | "diagnostics" | "shutdown"> {
+    /**
+     * Run one request through Forge around `next` (your handler, including your x402 payment middleware).
+     * Answers Forge's own routes, removes agent context from the request, and decorates the 402 and the paid response.
+     * Fails open: on any internal error the request reaches `next` unchanged, or its response is returned unchanged.
+     */
+    handle(request: Request, next: Next): Promise<Response>;
+    /** Wrap a fetch handler, e.g. `export default { fetch: forge.wrap(app.fetch) }`. Extra arguments (env, ctx) pass through. */
+    wrap<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>): (request: Request, ...rest: A) => Promise<Response>;
+    /** Forge's own routes only (/feedback, /feedback/rate, /feedback/summary, a static openapi.document); null for anything else. */
+    route(request: Request): Promise<Response | null>;
+}
+export declare function toResponse(response: ForgeResponse): Response;
+export declare function createForge(options: ForgeOptions): ForgeFetch;

package/dist/fetch.js

@@ -0,0 +1,171 @@
+// 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. */
+const JSON_LIMIT = 1024 * 1024;
+const isJson = (type) => /^application\/(?:[\w.+-]+\+)?json\b/i.test(type ?? "");
+export function toResponse(response) {
+    if (response.body === undefined)
+        return new Response(null, { status: response.status, headers: response.headers });
+    return new Response(JSON.stringify(response.body), { status: response.status, headers: { ...response.headers, "Content-Type": "application/json; charset=utf-8" } });
+}
+async function readJson(request) {
+    const text = (await request.clone().text()).trim();
+    if (text.length > BODY_LIMIT)
+        throw new Error("body_too_large");
+    return text ? JSON.parse(text) : {};
+}
+/** Read a body only when it's declared small enough. Chunked bodies without a length are left alone. */
+const smallEnough = (headers, limit) => {
+    const length = Number(headers.get("content-length"));
+    return Number.isFinite(length) && length > 0 && length <= limit;
+};
+export function createForge(options) {
+    const core = createForgeCore(options);
+    const forgeRequest = (request, url) => ({
+        method: request.method,
+        path: url.pathname,
+        header: (name) => request.headers.get(name) ?? undefined,
+        query: (name) => url.searchParams.get(name) ?? undefined,
+        json: () => readJson(request),
+    });
+    async function route(request) {
+        if (!core.enabled)
+            return null;
+        const own = await core.route(forgeRequest(request, new URL(request.url)));
+        return own ? toResponse(own) : null;
+    }
+    /** 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);
+        for (const name of ["if-none-match", "if-modified-since", "accept-encoding"])
+            headers.delete(name);
+        const response = await next(new Request(request, { headers }));
+        try {
+            if (response.status !== 200 || response.headers.get("content-encoding") || !isJson(response.headers.get("content-type")))
+                return response;
+            const text = await response.clone().text();
+            if (text.length > SPEC_LIMIT)
+                return response;
+            const result = core.enrichOpenApi(JSON.parse(text));
+            if (!result.report.enriched)
+                return response;
+            const out = new Headers(response.headers);
+            for (const name of ["content-length", "etag", "last-modified"])
+                out.delete(name);
+            return new Response(JSON.stringify(result.document), { status: 200, statusText: response.statusText, headers: out });
+        }
+        catch (error) {
+            core.onError(error);
+            return response;
+        }
+    }
+    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.
+        let call;
+        let forwarded = request;
+        try {
+            const url = new URL(request.url);
+            const own = await core.route(forgeRequest(request, url));
+            if (own)
+                return toResponse(own);
+            if (core.isSpecRequest(request.method, url.pathname))
+                return spec(request, next);
+            call = core.call({ method: request.method, path: url.pathname, header: (name) => request.headers.get(name) ?? undefined });
+            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);
+                    const without = call.requestBody(parsed);
+                    if (without !== parsed)
+                        body = JSON.stringify(without);
+                }
+            }
+            if (nextUrl !== request.url || body !== undefined) {
+                const headers = new Headers(request.headers);
+                if (body !== undefined)
+                    headers.delete("content-length");
+                forwarded = new Request(nextUrl, { method: request.method, headers, body: body ?? request.body, redirect: request.redirect, signal: request.signal, ...(body === undefined && request.body ? { duplex: "half" } : {}) });
+                // Cloudflare Workers attach request metadata as `cf`; keep it.
+                const cf = request.cf;
+                if (cf !== undefined)
+                    Object.defineProperty(forwarded, "cf", { value: cf, enumerable: true });
+            }
+        }
+        catch (error) {
+            core.onError(error);
+            return next(request);
+        }
+        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).
+        let added;
+        let read;
+        try {
+            added = call.headers(response.status, response.headers.get("payment-required") ?? undefined, response.headers.get("payment-response") ?? undefined);
+            const status = response.status;
+            const type = response.headers.get("content-type") ?? "";
+            const decorate = status === 402 || (call.feedbackId !== undefined && status >= 200 && status < 300);
+            const kind = isJson(type) || /^text\/plain\b/i.test(type);
+            // Only buffer JSON or plain text that is declared small, or has no declared length (never streams like SSE).
+            if (decorate && kind && response.body && (smallEnough(response.headers, JSON_LIMIT) || !response.headers.has("content-length"))) {
+                read = { text: await response.text(), type };
+            }
+        }
+        catch (error) {
+            core.onError(error);
+            call.finish(response.status);
+            return response;
+        }
+        let body = read?.text;
+        if (read) {
+            try {
+                if (isJson(read.type)) {
+                    const parsed = JSON.parse(read.text);
+                    const next = call.json(response.status, parsed);
+                    if (next !== parsed)
+                        body = JSON.stringify(next);
+                }
+                else
+                    body = call.text(response.status, read.type, read.text);
+            }
+            catch (error) {
+                core.onError(error); // not JSON after all: send it as it was
+            }
+        }
+        call.finish(response.status);
+        if (read === undefined) {
+            if (!Object.keys(added).length)
+                return response;
+            try {
+                for (const [name, value] of Object.entries(added))
+                    response.headers.set(name, value);
+                return response;
+            }
+            catch {
+                // Immutable headers (e.g. a fetch() response): rebuild around the same body stream.
+            }
+        }
+        const headers = new Headers(response.headers);
+        for (const [name, value] of Object.entries(added))
+            headers.set(name, value);
+        if (read !== undefined)
+            headers.delete("content-length");
+        return new Response(read === undefined ? response.body : body, { status: response.status, statusText: response.statusText, headers });
+    }
+    return {
+        enabled: core.enabled,
+        challengeSentence: core.challengeSentence,
+        enrichOpenApi: core.enrichOpenApi,
+        diagnostics: core.diagnostics,
+        shutdown: core.shutdown,
+        handle,
+        route,
+        wrap: (handler) => (request, ...rest) => handle(request, (r) => handler(r, ...rest)),
+    };
+}

package/dist/hono.d.ts

@@ -0,0 +1,10 @@
+import type { MiddlewareHandler } from "hono";
+import type { ForgeOptions } from "./core.js";
+import { type ForgeFetch } from "./fetch.js";
+export type { ForgeOptions, OpenApiOptions } from "./core.js";
+export interface Forge extends Omit<ForgeFetch, "handle" | "wrap" | "route"> {
+    /** Mount once, before your x402 payment middleware (`@x402/hono`) and before your OpenAPI route. */
+    middleware(): MiddlewareHandler;
+}
+/** Never throws (unless `strict`): with invalid options it warns and returns a middleware that only calls next(). */
+export declare function createForge(options: ForgeOptions): Forge;

package/dist/hono.js

@@ -0,0 +1,35 @@
+import { createForge as createForgeFetch } from "./fetch.js";
+/** Never throws (unless `strict`): with invalid options it warns and returns a middleware that only calls next(). */
+export function createForge(options) {
+    const forge = createForgeFetch(options);
+    return {
+        enabled: forge.enabled,
+        challengeSentence: forge.challengeSentence,
+        enrichOpenApi: forge.enrichOpenApi,
+        diagnostics: forge.diagnostics,
+        shutdown: forge.shutdown,
+        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) => {
+                    // Hono reads url, headers and body from c.req.raw on demand, so handlers see the request without agent context.
+                    if (request !== c.req.raw)
+                        c.req.raw = request;
+                    ranNext = true;
+                    await next();
+                    return c.res;
+                });
+                if (!ranNext)
+                    return response; // one of Forge's own routes
+                if (response !== c.res) {
+                    // Hono's c.res setter copies the previous response's headers onto the new one, which would undo
+                    // Forge's rewritten PAYMENT-REQUIRED / PAYMENT-RESPONSE. Clear it first.
+                    c.res = undefined;
+                    c.res = response;
+                }
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -8,6 +8,10 @@ export { mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS }
 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, feedbackExtension, FEEDBACK_EXTENSION, readPaymentHeader } from "./x402.js";
+export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader } 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";

package/dist/index.js

@@ -3,4 +3,6 @@ export { createForgeCore, checkOptions, BODY_LIMIT, SPEC_LIMIT } from "./core.js
 export { enrichOpenApi, detectVersion } from "./openapi.js";
 export { 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, feedbackExtension, FEEDBACK_EXTENSION, readPaymentHeader } from "./x402.js";
+export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader } 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.d.ts

@@ -0,0 +1,25 @@
+import type { ForgeOptions } from "./core.js";
+import { type ForgeFetch } from "./fetch.js";
+export type { ForgeOptions, OpenApiOptions } from "./core.js";
+export interface Forge extends Omit<ForgeFetch, "wrap" | "route"> {
+    /**
+     * Wrap a route handler, outermost: `export const GET = forge.withForge(withX402(handler, route, server))`.
+     * The handler receives the request Forge forwarded (without agent context); the 402 and the paid response are decorated.
+     */
+    withForge<R extends Request, C = unknown>(handler: (request: R, context: C) => Response | Promise<Response>): (request: R, context: C) => Promise<Response>;
+    /**
+     * Handlers for Forge's own routes. In app/feedback/[[...path]]/route.ts: `export const { GET, POST } = forge.routes;`
+     * (and in app/openapi.json/route.ts when you pass `openapi.document`). Anything else answers 404.
+     */
+    routes: {
+        GET: (request: Request) => Promise<Response>;
+        POST: (request: Request) => Promise<Response>;
+        HEAD: (request: Request) => Promise<Response>;
+    };
+    /**
+     * Wrap an x402 proxy (`paymentProxy`) so its 402 challenges carry the rating ask. Paid responses still need
+     * withForge on the route: the proxy never sees the route's body.
+     */
+    proxy<R extends Request>(proxy: (request: R) => Response | Promise<Response>): (request: R) => Promise<Response>;
+}
+export declare function createForge(options: ForgeOptions): Forge;

package/dist/next.js

@@ -0,0 +1,30 @@
+import { createForge as createForgeFetch } from "./fetch.js";
+/**
+ * Rebuild a forwarded Request as the original's class (NextRequest), so handlers and withX402 still get
+ * `nextUrl` and friends. Next isn't imported: the constructor comes from the request itself.
+ */
+function sameKind(original, forwarded) {
+    const Kind = original.constructor;
+    return Kind === Request ? forwarded : new Kind(forwarded);
+}
+export function createForge(options) {
+    const forge = createForgeFetch(options);
+    const own = async (request) => (await forge.route(request)) ?? new Response(JSON.stringify({ error: "not_found" }), { status: 404, headers: { "Content-Type": "application/json" } });
+    return {
+        enabled: forge.enabled,
+        challengeSentence: forge.challengeSentence,
+        enrichOpenApi: forge.enrichOpenApi,
+        diagnostics: forge.diagnostics,
+        shutdown: forge.shutdown,
+        handle: forge.handle,
+        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 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)
+                return response;
+            return forge.handle(request, () => response);
+        },
+    };
+}

package/dist/openapi.d.ts

@@ -16,6 +16,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. */
+    agentContext?: {
+        searchQuery: boolean;
+    };
 }
 export interface OperationReport {
     method: string;
@@ -23,6 +27,8 @@ 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. */
+    agentContext?: "body" | "query" | "not_added";
     reasons: string[];
 }
 export interface EnrichReport {

package/dist/openapi.js

@@ -1,6 +1,7 @@
 // Additive, idempotent OpenAPI enrichment for Swagger 2.0 and OpenAPI 3.0 / 3.1 / 3.2.
 // Rules: never mutate the input, never modify a shared $ref target, never override merchant paths,
 // 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 { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL } from "./values.js";
 const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
@@ -98,6 +99,58 @@ function extendSchema(doc, schema, props) {
     copy.properties = { ...(isObj(copy.properties) ? copy.properties : {}), ...clone(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. */
+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);
+    const props = { [CONTEXT_FIELD]: agentContextSchema(opts) };
+    const notAdded = (reason) => {
+        report.agentContext = "not_added";
+        report.reasons.push(`request: ${reason}`);
+    };
+    if (BODYLESS.has(method)) {
+        const taken = new Set(listed.filter((p) => p.in === "query").map((p) => p.name));
+        const params = agentContextParameters(opts).filter((p) => !taken.has(p.name));
+        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 });
+        op.parameters = [...(Array.isArray(op.parameters) ? op.parameters : []), ...documented];
+        report.agentContext = "query";
+        return;
+    }
+    if (version === "2.0") {
+        const params = Array.isArray(op.parameters) ? op.parameters : [];
+        const index = params.findIndex((p) => resolve(p)?.in === "body");
+        if (index < 0)
+            return notAdded("no_request_body");
+        const param = clone(resolve(params[index]));
+        const result = extendSchema(doc, param.schema, props);
+        if ("reason" in result)
+            return notAdded(result.reason);
+        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";
+        return;
+    }
+    const body = resolve(op.requestBody);
+    if (!isObj(body) || !isObj(body.content))
+        return notAdded("no_request_body");
+    const copy = clone(body);
+    const media = Object.entries(copy.content).filter(([type, entry]) => isJsonMedia(type) && isObj(entry) && "schema" in entry);
+    if (!media.length)
+        return notAdded("no_json_request_body");
+    for (const [, entry] of media) {
+        const result = extendSchema(doc, entry.schema, props);
+        if ("reason" in result)
+            return notAdded(result.reason);
+        entry.schema = result.schema;
+    }
+    op.requestBody = copy; // inline copy if it was a shared $ref
+    report.agentContext = "body";
+}
 const isJsonMedia = (type) => /^application\/(?:[\w.+-]+\+)?json\b/i.test(type);
 const is2xx = (code) => /^2(\d\d|XX)$/i.test(code);
 function appendSentence(text, sentence, marker) {
@@ -280,6 +333,8 @@ export function enrichOpenApi(input, options) {
                     op.responses[code] = response; // inline copy if it was a shared $ref
                     opReport.responses[code] = "extended";
                 }
+                if (options.agentContext)
+                    addAgentContext(doc, version, item, method, op, options.agentContext, opReport);
                 // agentcash-style payment metadata carries its own output schema.
                 const info = op["x-payment-info"];
                 if (isObj(info) && isObj(info.outputSchema)) {

package/dist/reporter.d.ts

@@ -1,8 +1,10 @@
+import type { AgentContext } from "./context.js";
 export type ForgeEvent = {
     type: "challenge";
     route: string;
     ts: number;
     user_agent?: string;
+    agent_context?: AgentContext;
 } | {
     type: "interaction";
     feedback_id: string;
@@ -13,6 +15,7 @@ export type ForgeEvent = {
     network?: string;
     amount?: string;
     user_agent?: string;
+    agent_context?: AgentContext;
     ts: number;
 };
 /** Batches events to the backend in the background. Drops the oldest events if the backend stays down. */

package/dist/x402.d.ts

@@ -1,19 +1,39 @@
-/** Key of the Forge extension in an x402 v2 challenge's `extensions`, next to e.g. `bazaar`. */
+import { type Tone } from "./ask.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.
  */
-export declare function feedbackExtension(rateUrl: string): {
+export declare function feedbackExtension(rateUrl: string, tone?: Tone, agentContext?: string): {
     info: {
+        agent_context?: string | undefined;
+        rate: string;
+        outcome: string[];
+        feedback_id: string;
+        payment: string;
         protocol: string;
         ask: string;
+    };
+};
+/** The receipt extension: the same ask, with the real feedback ID, in the settlement response after payment. */
+export declare function receiptExtension(rateUrl: string, feedbackId: string, tone?: Tone): {
+    info: {
+        protocol: string;
+        ask: string;
+        feedback_id: string;
         rate: string;
         outcome: string[];
-        feedback_id: string;
         payment: string;
     };
 };
+/**
+ * Add the receipt extension to a base64 PAYMENT-RESPONSE header (x402 v2 settlement response), only when
+ * settlement succeeded. The receipt is informational for the client: facilitator fields are untouched.
+ * 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;
 /** 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). */

package/dist/x402.js

@@ -1,22 +1,60 @@
+import { ASK } from "./ask.js";
 import { PROTOCOL } from "./values.js";
-/** Key of the Forge extension in an x402 v2 challenge's `extensions`, next to e.g. `bazaar`. */
+/** 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.
  */
-export function feedbackExtension(rateUrl) {
+export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
     return {
         info: {
             protocol: PROTOCOL,
-            ask: "After your call, please rate this service for other agents. Free, one request.",
+            ask: ASK[tone].extensionAsk,
+            ...ASK[tone].extensionExtras,
             rate: `GET ${rateUrl}?feedback_id=FEEDBACK_ID&outcome=fully`,
             outcome: ["fully", "partially", "no"],
             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 } : {}),
         },
     };
 }
+/** The receipt extension: the same ask, with the real feedback ID, in the settlement response after payment. */
+export function receiptExtension(rateUrl, feedbackId, tone = "soft") {
+    return {
+        info: {
+            protocol: PROTOCOL,
+            ask: ASK[tone].extensionAsk,
+            feedback_id: feedbackId,
+            rate: `GET ${rateUrl}?feedback_id=${feedbackId}&outcome=fully`,
+            outcome: ["fully", "partially", "no"],
+            payment: "None. Plain GET, not an x402 endpoint.",
+        },
+    };
+}
+/**
+ * Add the receipt extension to a base64 PAYMENT-RESPONSE header (x402 v2 settlement response), only when
+ * settlement succeeded. The receipt is informational for the client: facilitator fields are untouched.
+ * Returns undefined when the header can't be parsed, settlement failed, or the extension is already there.
+ */
+export function describeReceipt(headerValue, extension) {
+    let receipt;
+    try {
+        receipt = JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!receipt || typeof receipt !== "object" || receipt.success !== true)
+        return undefined;
+    const extensions = receipt.extensions;
+    if (extensions !== undefined && extensions !== null && (typeof extensions !== "object" || Array.isArray(extensions) || FEEDBACK_EXTENSION in extensions))
+        return undefined;
+    receipt.extensions = { ...extensions, [FEEDBACK_EXTENSION]: extension };
+    return Buffer.from(JSON.stringify(receipt), "utf8").toString("base64");
+}
 function appendSentence(description, sentence, marker) {
     const current = typeof description === "string" ? description.trim() : "";
     return current.includes(marker) ? current : current ? `${current} ${sentence}` : sentence;