@forgeintel/sdk 0.4.0-beta.1 → 0.5.0-beta.1

package/README.md

@@ -86,13 +86,14 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `apiKey` | required | Merchant key. Also the HMAC key for IDs. |
 | `backendUrl` | required | Forge backend origin. |
 | `publicUrl` | required | This service's public origin. Used in rating URLs. |
+| `feedback` | `true` | Master switch for rating prompts, IDs, response additions and feedback routes. `false` leaves telemetry, client headers and independent agent context on. |
 | `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. 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. |
+| `agentContext` | `true` | Ask for self-reported `agent_context` (agent name, search query), record it, and remove it before your code runs. `{ searchQuery: false }` or `false` to limit. |
 | `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. |
@@ -105,3 +106,5 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 `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.
 
 Source, examples and design notes: [github.com/ClawCash/forge-feedback](https://github.com/ClawCash/forge-feedback).
+
+Client headers are captured automatically at discovery, challenge, payment, and rating stages, including unknown clients. Forge identifies awal, AgentCash, pay.sh and x402scan-mcp from known headers; other clients remain unknown. There is no client-signals switch. Legacy `agent_context.client` inputs remain accepted but are no longer requested.

package/dist/client-signals.d.ts

@@ -0,0 +1,4 @@
+declare const HEADERS: readonly ["user-agent", "x-client-id", "x-session-id", "x-wallet-address", "x-solana-wallet-address", "referer", "access-control-expose-headers", "payment-retry", "cf-worker", "signature-agent"];
+export type ClientHeaders = Partial<Record<(typeof HEADERS)[number] | "sentry-release", string>>;
+export declare function captureClientHeaders(header: (name: string) => string | undefined): ClientHeaders | undefined;
+export {};

package/dist/client-signals.js

@@ -0,0 +1,45 @@
+// Attribution hints only. Iterate named headers, never enumerate or serialize a request's headers.
+const HEADERS = [
+    "user-agent", "x-client-id", "x-session-id", "x-wallet-address", "x-solana-wallet-address",
+    "referer", "access-control-expose-headers", "payment-retry", "cf-worker", "signature-agent",
+];
+const VALUE_LIMIT = 512;
+const BAGGAGE_LIMIT = 8192;
+export function captureClientHeaders(header) {
+    const captured = {};
+    const read = (name) => {
+        try {
+            return header(name);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const clean = (value) => value.slice(0, VALUE_LIMIT).replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+    for (const name of HEADERS) {
+        const raw = read(name);
+        if (typeof raw !== "string")
+            continue;
+        const value = clean(raw);
+        if (value)
+            captured[name] = value;
+    }
+    // Baggage may contain unrelated tracing data. Keep only the exact Sentry release member,
+    // excluding its optional metadata. Oversized baggage is dropped, never partially parsed.
+    const baggage = read("baggage");
+    if (typeof baggage === "string" && baggage.length <= BAGGAGE_LIMIT) {
+        for (const member of baggage.split(",")) {
+            const eq = member.indexOf("=");
+            if (eq < 0 || member.slice(0, eq).trim() !== "sentry-release")
+                continue;
+            try {
+                const value = clean(decodeURIComponent(member.slice(eq + 1).split(";", 1)[0].trim()));
+                if (value)
+                    captured["sentry-release"] = value;
+            }
+            catch { /* Malformed encoding is not a usable release. */ }
+            break;
+        }
+    }
+    return Object.keys(captured).length ? captured : undefined;
+}

package/dist/context.d.ts

@@ -1,5 +1,5 @@
 /** Suggested agent names; anything else is kept as given. */
-export declare const AGENT_TYPES: readonly ["Claude Code", "Codex", "Cursor", "Grok", "Hermes", "Instinct", "OpenClaw", "Other", "Unknown"];
+export declare const AGENT_TYPES: readonly ["Claude Code", "Codex", "Cursor", "Grok Bot", "Muse", "Hermes", "Instinct", "OpenClaw", "Others"];
 /** 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,7 +45,7 @@ export declare function agentContextSchema({ searchQuery }?: {
         } | undefined;
         agent_type: {
             type: string;
-            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok" | "Hermes" | "Instinct" | "OpenClaw" | "Other" | "Unknown")[];
+            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok Bot" | "Muse" | "Hermes" | "Instinct" | "OpenClaw" | "Others")[];
             description: string;
         };
         agent_type_other: {
@@ -53,11 +53,6 @@ export declare function agentContextSchema({ searchQuery }?: {
             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. */
@@ -71,4 +66,4 @@ export declare function agentContextParameters({ searchQuery }?: {
 /** 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.";
+}): "Please add agent_context {agent_type, search_query} to your paid request's JSON body (without a body: agent_type, agent_search_query query parameters). search_query: share the query you used to find this service, or \"direct\" if you did not search." | "Please add agent_context {agent_type} to your paid request's JSON body (without a body: agent_type query parameter). Self-reported; omit what you don't know.";

package/dist/context.js

@@ -3,7 +3,7 @@
 // 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", "Instinct", "OpenClaw", "Other", "Unknown"];
+export const AGENT_TYPES = ["Claude Code", "Codex", "Cursor", "Grok Bot", "Muse", "Hermes", "Instinct", "OpenClaw", "Others"];
 /** Suggested x402 clients; anything else is kept as given. */
 export const CLIENTS = ["agentcash", "awal", "pay.sh", "other", "unknown"];
 /** JSON body field (POST, PUT, …). */
@@ -28,9 +28,17 @@ export function parseAgentContext(input, { searchQuery = true } = {}) {
         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]);
+        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 === "search_query" && /^direct$/i.test(text))
+            text = "direct";
         const known = key === "agent_type" ? AGENT_TYPES : key === "client" ? CLIENTS : null;
         context[key] = known?.find((v) => v.toLowerCase() === text.toLowerCase()) ?? text;
     }
@@ -80,10 +88,9 @@ export function takeFromUrl(url) {
 }
 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.",
+    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.",
+    search_query: "The search query you used to find this service, or \"direct\" if you did not search.",
 };
 /** JSON Schema for the optional `agent_context` body property. */
 export function agentContextSchema({ searchQuery = true } = {}) {
@@ -93,7 +100,6 @@ export function agentContextSchema({ searchQuery = true } = {}) {
         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 } } : {}),
         },
     };
@@ -103,7 +109,6 @@ 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 } });
@@ -112,6 +117,6 @@ export function agentContextParameters({ searchQuery = true } = {}) {
 /** 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.";
+        ? "Please add agent_context {agent_type, search_query} to your paid request's JSON body (without a body: agent_type, agent_search_query query parameters). search_query: share the query you used to find this service, or \"direct\" if you did not search."
+        : "Please add agent_context {agent_type} to your paid request's JSON body (without a body: agent_type query parameter). Self-reported; omit what you don't know.";
 }

package/dist/core.d.ts

@@ -22,6 +22,8 @@ export interface ForgeOptions {
     backendUrl: string;
     /** This service's public origin, e.g. https://pixels.gateway.clawca.sh. Never derived from the Host header. */
     publicUrl: string;
+    /** Enable rating prompts, feedback IDs and feedback routes. Default true. Telemetry and agent context are independent. */
+    feedback?: boolean;
     /** Path for the feedback routes. Default "/feedback" (quick rating at "/feedback/rate"). */
     basePath?: string;
     /**
@@ -48,8 +50,8 @@ export interface ForgeOptions {
      */
     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
+     * Agent context: optional, self-reported `agent_context` {agent_type, search_query} on the paid request
+     * (JSON body, or agent_type / agent_search_query query parameters). Forge documents it in the
      * extension and OpenAPI, reads it, reports it with the call, and removes it before your validators and handlers
      * run. Default true. `{ searchQuery: false }` stops asking for (and recording) the search query; `false` stops
      * asking and recording altogether (the fields are still removed if an agent sends them).
@@ -145,7 +147,7 @@ export interface ForgeCore {
     readonly enabled: boolean;
     /** The sentence appended to x402 challenges and OpenAPI guidance. */
     readonly challengeSentence: string;
-    /** Handle Forge's own routes ({basePath}, /rate, /summary, a static openapi.document). Null when not ours. */
+    /** Call once per request: records OpenAPI discovery and handles Forge's own routes. Null when not ours. */
     route(request: ForgeRequest): Promise<ForgeResponse | null>;
     /** Whether this is a GET for the merchant's own OpenAPI route, which the adapter should buffer and pass to enrichOpenApi. */
     isSpecRequest(method: string, path: string): boolean;

package/dist/core.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 // Framework-free Forge logic. Adapters (express.ts, later fetch.ts) translate their request/response
 // objects to the small interfaces below and write out what the core returns.
 import { DEFAULT_TTL_MS, deriveSigningKey, mintFeedbackId, verifyFeedbackId } from "./id.js";
@@ -5,6 +6,7 @@ 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 { captureClientHeaders } from "./client-signals.js";
 import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL, parseSubmission } from "./values.js";
 import { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, readPaymentHeader, readReceipt, receiptExtension } from "./x402.js";
 export const FEEDBACK_HEADERS = { "Cache-Control": "no-store", "X-Robots-Tag": "noindex" };
@@ -60,7 +62,7 @@ export function checkOptions(input) {
     fallback("challengeSentence", typeof raw.challengeSentence === "string" && raw.challengeSentence.trim() !== "", "must be a non-empty string");
     fallback("rateHint", boolean(raw.rateHint) || typeof raw.rateHint === "string", "must be a boolean or a string");
     fallback("agentContext", boolean(raw.agentContext) || (!!raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)), "must be true, false or { searchQuery }");
-    for (const key of ["describeChallenges", "challengeExtension", "receiptExtension", "injectBody", "injectText", "strict"])
+    for (const key of ["feedback", "describeChallenges", "challengeExtension", "receiptExtension", "injectBody", "injectText", "strict"])
         fallback(key, boolean(raw[key]), "must be true or false");
     // The lines no wording may cross, whatever the merchant configures (see ask.ts).
     for (const key of ["challengeSentence", "rateHint"]) {
@@ -155,7 +157,8 @@ function enabledCore(options, configWarnings) {
     const summaryUrl = new URL(summaryPath, publicUrl).href;
     const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
     const fetchImpl = options.fetch ?? fetch;
-    const describe = options.describeChallenges ?? true;
+    const feedback = options.feedback !== false;
+    const describe = feedback && (options.describeChallenges ?? true);
     const injectBody = options.injectBody ?? true;
     const injectText = options.injectText ?? false;
     const tone = options.tone ?? "soft";
@@ -186,20 +189,23 @@ function enabledCore(options, configWarnings) {
             lastLogged = message;
         });
     const reporter = new EventReporter(backend("events"), apiKey, fetchImpl, onError, options.flushIntervalMs ?? 2000);
-    const challengeSentence = (options.challengeSentence ?? ASK[tone].challengeSentence).replaceAll("{rate_url}", rateUrl).replaceAll("{summary_url}", summaryUrl);
+    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;
     const challengeAdditions = {
         ...(describe ? { sentence: challengeSentence, marker: challengeMarker } : {}),
-        ...(options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery }) : undefined) }),
+        ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery }) : undefined) }),
     };
-    const touchChallenges = Boolean(challengeAdditions.sentence || challengeAdditions.extension);
+    if (!feedback && collectContext)
+        challengeAdditions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery }), optional: true } };
+    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;
     let lastWarnings = "";
     function enrich(document) {
         const result = enrichOpenApi(document, {
             publicUrl,
+            feedback,
             basePath,
             sentence: challengeSentence,
             marker: challengeMarker,
@@ -258,7 +264,7 @@ function enabledCore(options, configWarnings) {
             const upstream = await fetchImpl(backend("feedback"), {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
-                body: JSON.stringify({ ...parsed.value, via, user_agent: request.header("user-agent") ?? null }),
+                body: JSON.stringify({ ...parsed.value, via, user_agent: request.header("user-agent") ?? null, request_headers: captureClientHeaders((name) => request.header(name)) }),
                 signal: AbortSignal.timeout(3000),
             });
             const body = await upstream.json().catch(() => ({ recorded: false, error: "feedback_unavailable" }));
@@ -299,7 +305,7 @@ function enabledCore(options, configWarnings) {
     }
     async function handleRoute(request) {
         const { method, path } = request;
-        if (path === basePath) {
+        if (feedback && path === basePath) {
             if (method === "GET" || method === "HEAD")
                 return reply(200, form);
             if (method === "POST") {
@@ -315,18 +321,22 @@ function enabledCore(options, configWarnings) {
                 return submit(request, body, "POST");
             }
         }
-        if (path === summaryPath && (method === "GET" || method === "HEAD"))
+        if (feedback && path === summaryPath && (method === "GET" || method === "HEAD"))
             return summary();
-        if (path === ratePath) {
+        if (feedback && path === ratePath) {
             // HEAD and other methods must never record a rating (link checkers send HEAD).
             if (method !== "GET")
                 return reply(405, undefined, { ...FEEDBACK_HEADERS, Allow: "GET" });
             const first = (v) => (Array.isArray(v) ? v[0] : v);
             return submit(request, { feedback_id: first(request.query("feedback_id")), outcome: first(request.query("outcome")), issue: first(request.query("issue")) }, "GET");
         }
-        if (openapi && openapi.document !== undefined && method === "GET" && specPaths.has(path)) {
-            const source = typeof openapi.document === "function" ? await openapi.document() : openapi.document;
-            return reply(200, enrich(source).document, { "Cache-Control": "no-store" });
+        if (openapi && method === "GET" && specPaths.has(path)) {
+            const requestHeaders = captureClientHeaders((name) => request.header(name));
+            reporter.push({ type: "discovery", route: `${method} ${path}`, ts: Date.now(), user_agent: requestHeaders?.["user-agent"], request_headers: requestHeaders });
+            if (openapi.document !== undefined) {
+                const source = typeof openapi.document === "function" ? await openapi.document() : openapi.document;
+                return reply(200, enrich(source).document, { "Cache-Control": "no-store" });
+            }
         }
         return null;
     }
@@ -352,8 +362,10 @@ function enabledCore(options, configWarnings) {
         const started = Date.now();
         const route = `${request.method} ${request.path}`;
         const userAgent = request.header("user-agent") ?? undefined;
+        const requestHeaders = captureClientHeaders((name) => request.header(name));
         const paymentHeader = request.header("payment-signature") ?? request.header("x-payment"); // x402 v2 / v1
-        const feedbackId = paymentHeader ? mintFeedbackId(signingKey) : undefined;
+        const feedbackId = feedback && paymentHeader ? mintFeedbackId(signingKey) : undefined;
+        const interactionId = paymentHeader && !feedback ? randomUUID() : undefined;
         if (feedbackId)
             stats.minted++;
         const feedbackUrl = feedbackId ? `${rateUrl}?feedback_id=${feedbackId}&outcome=` : "";
@@ -424,10 +436,10 @@ function enabledCore(options, configWarnings) {
                             stats.challengesDescribed++;
                         }
                     }
+                    if (paymentHeader && ok(status) && paymentResponse)
+                        receiptFacts = readReceipt(paymentResponse);
                     if (feedbackId && ok(status)) {
                         set["Forge-Feedback-Id"] = feedbackId;
-                        if (paymentResponse)
-                            receiptFacts = readReceipt(paymentResponse);
                         const receipt = receipts && paymentResponse ? describeReceipt(paymentResponse, receiptExtension(rateUrl, feedbackId, tone)) : undefined;
                         if (receipt)
                             set["PAYMENT-RESPONSE"] = receipt;
@@ -475,19 +487,20 @@ 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, ...(context ? { agent_context: context } : {}) });
+                reporter.push({ type: "challenge", route, ts, user_agent: userAgent, request_headers: requestHeaders, ...(context ? { agent_context: context } : {}) });
             }
-            if (feedbackId) {
+            if (feedbackId || interactionId) {
                 const facts = { ...readPaymentHeader(paymentHeader), ...receiptFacts };
                 reporter.push({
                     type: "interaction",
-                    feedback_id: feedbackId,
+                    ...(feedbackId ? { feedback_id: feedbackId } : { interaction_id: interactionId }),
                     route,
                     status,
                     latency_ms: ts - started,
                     // 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,
+                    request_headers: requestHeaders,
                     ...(context ? { agent_context: context } : {}),
                     ts,
                 });

package/dist/index.d.ts

@@ -15,3 +15,4 @@ export type { AgentContext } from "./context.js";
 export type { AskTexts, Tone } from "./ask.js";
 export type { ChallengeAdditions } from "./x402.js";
 export type { ForgeEvent } from "./reporter.js";
+export type { ClientHeaders } from "./client-signals.js";

package/dist/openapi.d.ts

@@ -2,6 +2,8 @@ type Json = Record<string, any>;
 export type SpecVersion = "2.0" | "3.0" | "3.1" | "3.2";
 export type ResponseSupport = "extended" | "incompatible" | "undocumented";
 export interface EnrichOptions {
+    /** Disable all feedback additions while retaining optional agent context. */
+    feedback?: boolean;
     /** Merchant public origin, e.g. https://api.example.com */
     publicUrl: string;
     /** Public path of the feedback routes, e.g. /feedback */

package/dist/openapi.js

@@ -287,6 +287,11 @@ export function enrichOpenApi(input, options) {
                     continue;
                 const opReport = { method: method.toUpperCase(), path, responses: {}, reasons: [] };
                 report.operations.push(opReport);
+                if (options.feedback === false) {
+                    if (options.agentContext)
+                        addAgentContext(doc, version, item, method, op, options.agentContext, opReport);
+                    continue;
+                }
                 if (options.describeOperations ?? true)
                     op.description = appendSentence(op.description, options.sentence, options.marker);
                 const produces = (op.produces ?? doc.produces);
@@ -344,6 +349,10 @@ export function enrichOpenApi(input, options) {
                 }
             }
         }
+        if (options.feedback === false) {
+            report.enriched = Boolean(options.agentContext);
+            return { document: doc, report };
+        }
         // Feedback routes. Paths are relative to the server prefix when it's this origin;
         // otherwise (3.x) the path items carry their own servers entry.
         const inPrefix = sameOrigin && (base === prefix || base.startsWith(`${prefix}/`));

package/dist/reporter.d.ts

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

package/dist/x402.d.ts

@@ -50,6 +50,8 @@ export interface ChallengeAdditions {
     marker?: string;
     /** Added as extensions["forge-feedback"] (v2 only; v1 challenges have no extensions). */
     extension?: unknown;
+    /** Independent context prompt when feedback is disabled. */
+    contextExtension?: unknown;
 }
 /**
  * Add the rating sentence and/or the forge-feedback extension to a base64 PAYMENT-REQUIRED header (x402 v2).

package/dist/x402.js

@@ -72,15 +72,17 @@ function addToV2(challenge, add) {
             changed = true;
         }
     }
-    if (add.extension) {
+    for (const [key, extension] of [[FEEDBACK_EXTENSION, add.extension], ["forge-agent-context", add.contextExtension]]) {
+        if (!extension)
+            continue;
         const extensions = challenge.extensions;
         if (extensions === undefined || extensions === null) {
-            challenge.extensions = { [FEEDBACK_EXTENSION]: add.extension };
+            challenge.extensions = { [key]: extension };
             changed = true;
         }
-        else if (typeof extensions === "object" && !Array.isArray(extensions) && !(FEEDBACK_EXTENSION in extensions)) {
+        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.
-            challenge.extensions = { ...extensions, [FEEDBACK_EXTENSION]: add.extension };
+            challenge.extensions = { ...extensions, [key]: extension };
             changed = true;
         }
     }

package/package.json

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