@atrib/agent 0.1.0

package/dist/policy.d.ts

@@ -0,0 +1,28 @@
+import type { CreatorPolicyEntry, SessionPolicyRecord } from '@atrib/verify';
+export type { CreatorPolicyEntry, SessionPolicyRecord };
+/** A fetched policy document shape for the fetch/parse layer (§4.2). */
+export interface PolicyDocument {
+    spec_version: string;
+    edge_weights?: Record<string, number>;
+    modifiers?: unknown[];
+    constraints?: {
+        minimum_share?: number;
+        maximum_share?: number;
+        minimum_own_share?: number;
+        maximum_total_share?: number;
+    };
+    [key: string]: unknown;
+}
+/** Options for session initialization. */
+export interface PolicyInitOptions {
+    contextId: string;
+    merchantDomain?: string | undefined;
+    /** Server URLs for all tools the agent intends to call. */
+    serverUrls?: string[] | undefined;
+}
+/**
+ * Run session initialization: fetch policies and negotiate (§5.4.2).
+ * Must complete within 3 seconds.
+ */
+export declare function initializeSessionPolicy(options: PolicyInitOptions): Promise<SessionPolicyRecord>;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAI5E,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAA;AAMvD,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAA;IACrB,WAAW,CAAC,EAAE;QACZ,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,iBAAiB,CAAC,EAAE,MAAM,CAAA;QAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAC7B,CAAA;IACD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAgDD,0CAA0C;AAC1C,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;CAClC;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CA4D9B"}

package/dist/policy.js

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Policy negotiation and session policy record (§4.5, §5.4.2, §5.4.6).
+ */
+import { sha256, hexEncode } from '@atrib/mcp';
+import canonicalize from 'canonicalize';
+const POLICY_FETCH_TIMEOUT_MS = 1000;
+const INIT_BUDGET_MS = 3000;
+const POLICY_PATH = '/.well-known/atrib-policy.json';
+/**
+ * Fetch a policy document from a URL with timeout.
+ * Returns null on any error (404, timeout, parse error).
+ */
+async function fetchPolicy(url) {
+    try {
+        // Validate URL scheme to prevent SSRF via crafted merchantDomain/serverUrls
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+            return null;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), POLICY_FETCH_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(url, { signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok)
+            return null;
+        const doc = (await response.json());
+        // §4.5.2 Rule 6: reject contradictory constraints
+        if (doc.constraints) {
+            const { minimum_share, maximum_share } = doc.constraints;
+            if (minimum_share !== undefined &&
+                maximum_share !== undefined &&
+                minimum_share > maximum_share) {
+                return null;
+            }
+            // Reject negative values
+            for (const val of Object.values(doc.constraints)) {
+                if (typeof val === 'number' && val < 0)
+                    return null;
+            }
+        }
+        return doc;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run session initialization: fetch policies and negotiate (§5.4.2).
+ * Must complete within 3 seconds.
+ */
+export async function initializeSessionPolicy(options) {
+    const warnings = [];
+    const startTime = Date.now();
+    // Step 1: Fetch merchant policy
+    let merchantPolicyDoc = null;
+    let merchantPolicyUrl = 'default';
+    if (options.merchantDomain) {
+        merchantPolicyUrl = `${options.merchantDomain}${POLICY_PATH}`;
+        merchantPolicyDoc = await fetchPolicy(merchantPolicyUrl);
+        if (!merchantPolicyDoc) {
+            merchantPolicyUrl = 'default';
+            warnings.push(`merchant policy not found at ${options.merchantDomain}${POLICY_PATH}`);
+        }
+    }
+    // Step 2: Fetch creator policies concurrently (§5.4.2 step 4)
+    const creatorEntries = [];
+    if (options.serverUrls && options.serverUrls.length > 0) {
+        const fetches = options.serverUrls.map(async (serverUrl) => {
+            const policyUrl = `${serverUrl}${POLICY_PATH}`;
+            const doc = await fetchPolicy(policyUrl);
+            return { serverUrl, policyUrl, doc };
+        });
+        const results = await Promise.allSettled(fetches);
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                const { serverUrl, policyUrl, doc } = result.value;
+                creatorEntries.push({
+                    server_url: serverUrl,
+                    policy_url: policyUrl,
+                    status: doc ? 'compatible' : 'not_found',
+                    ...(doc ? { policy: doc } : {}),
+                });
+            }
+        }
+    }
+    // Check init budget
+    if (Date.now() - startTime > INIT_BUDGET_MS) {
+        warnings.push('negotiation_skipped: session initialization exceeded 3-second budget');
+        return buildSessionPolicyRecord(options.contextId, 'default', creatorEntries, {}, warnings);
+    }
+    // Step 3: Conflict resolution (§4.5.2)
+    const { agreedPolicy, minimumFloors, negotiationWarnings } = negotiatePolicies(merchantPolicyDoc, merchantPolicyUrl, creatorEntries);
+    warnings.push(...negotiationWarnings);
+    return buildSessionPolicyRecord(options.contextId, agreedPolicy, creatorEntries, minimumFloors, warnings);
+}
+/** Run the 7-rule conflict resolution (§4.5.2). */
+function negotiatePolicies(merchantPolicy, merchantPolicyUrl, creatorEntries) {
+    const warnings = [];
+    const minimumFloors = {};
+    const merchantCap = merchantPolicy?.constraints?.maximum_total_share;
+    // Collect creator floors
+    let floorSum = 0;
+    for (const entry of creatorEntries) {
+        if (entry.policy?.constraints?.minimum_own_share !== undefined) {
+            const floor = entry.policy.constraints.minimum_own_share;
+            minimumFloors[entry.server_url] = floor;
+            floorSum += floor;
+        }
+    }
+    // Rule 5: Creator floors summing to >1.0 are irreconcilable
+    if (floorSum > 1.0) {
+        warnings.push(`creator minimum floors sum to ${floorSum} (>1.0), falling back to default policy. ` +
+            `Contributors: ${Object.keys(minimumFloors).join(', ')}`);
+        for (const entry of creatorEntries) {
+            if (entry.status === 'compatible' && entry.policy) {
+                entry.status = 'conflict_defaulted';
+            }
+        }
+        return { agreedPolicy: 'default', minimumFloors: {}, negotiationWarnings: warnings };
+    }
+    // Rule 3: Check if single creator floor exceeds merchant cap (BEFORE scaling)
+    // Must check before Rule 2 scaling. a single floor > cap is irreconcilable
+    if (merchantCap !== undefined) {
+        for (const entry of creatorEntries) {
+            const floor = entry.policy?.constraints?.minimum_own_share;
+            if (floor !== undefined && floor > merchantCap) {
+                warnings.push(`creator ${entry.server_url} minimum floor ${floor} exceeds merchant cap ${merchantCap}, ` +
+                    `falling back to default`);
+                // Only mark creators whose floor actually exceeds the cap as
+                // conflict_defaulted. creators with floors that fit are not at fault.
+                for (const e of creatorEntries) {
+                    const eFloor = e.policy?.constraints?.minimum_own_share;
+                    if (e.status !== 'not_found' && eFloor !== undefined && eFloor > merchantCap) {
+                        e.status = 'conflict_defaulted';
+                    }
+                }
+                return { agreedPolicy: 'default', minimumFloors: {}, negotiationWarnings: warnings };
+            }
+        }
+    }
+    // Rule 1 & 2: Merchant cap + creator floor scaling
+    // Multiple floors that individually fit the cap but sum > cap get scaled down proportionally
+    if (merchantCap !== undefined && floorSum > merchantCap) {
+        const scaleFactor = merchantCap / floorSum;
+        for (const [url, floor] of Object.entries(minimumFloors)) {
+            minimumFloors[url] = floor * scaleFactor;
+        }
+        warnings.push(`creator minimum floors scaled by ${scaleFactor.toFixed(4)} to fit merchant cap of ${merchantCap}`);
+        for (const entry of creatorEntries) {
+            if (entry.status === 'compatible' && minimumFloors[entry.server_url] !== undefined) {
+                entry.status = 'floor_scaled';
+            }
+        }
+    }
+    // Rule 4: Edge weight disagreements. merchant governs (advisory only for creators)
+    const agreedPolicy = merchantPolicyUrl !== 'default' ? merchantPolicyUrl : 'default';
+    return { agreedPolicy, minimumFloors, negotiationWarnings: warnings };
+}
+/** Build the session policy record (§4.5.3). */
+function buildSessionPolicyRecord(contextId, agreedPolicy, creatorEntries, minimumFloors, warnings) {
+    // Build the record without record_id first, then compute it
+    const record = {
+        spec_version: 'atrib/1.0',
+        record_id: '', // placeholder
+        context_id: contextId,
+        created_at: Date.now(),
+        merchant_policy: agreedPolicy === 'default' ? 'default' : agreedPolicy,
+        creator_policies: creatorEntries.map(({ server_url, policy_url, status }) => ({
+            server_url,
+            policy_url,
+            status,
+        })),
+        agreed_policy: agreedPolicy,
+        applied_constraints: {
+            minimum_floors: minimumFloors,
+        },
+        warnings,
+    };
+    // Compute record_id = sha256 of JCS canonical form, excluding record_id
+    // and warnings (warnings are mutable. runtime warnings are appended after
+    // negotiation, so including them would make record_id stale).
+    const { record_id: _, warnings: _w, ...forHashing } = record;
+    const canonical = canonicalize(forHashing);
+    if (canonical) {
+        const encoder = new TextEncoder();
+        const hash = sha256(encoder.encode(canonical));
+        record.record_id = `sha256:${hexEncode(hash)}`;
+    }
+    return record;
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,50 @@
+import type { GapNode } from '@atrib/verify';
+/** The latest attribution context from the most recent tool response. */
+export interface LatestContext {
+    recordHash: Uint8Array;
+    creatorKey: Uint8Array;
+}
+/** Mutable session state, evolved by each tool call/response. */
+export interface SessionState {
+    contextId: string;
+    sessionToken: string;
+    latestContext: LatestContext | null;
+    initialized: boolean;
+    /** The record_id from the session policy record, set after init. */
+    policyRecordId: string | null;
+    /** Task IDs from tasks/create responses (§5.7). */
+    taskIds: Set<string>;
+    /** Unsigned hops recorded during this session (§1.6). */
+    gapNodes: GapNode[];
+    warnings: string[];
+}
+/** Options for creating a session. */
+export interface SessionOptions {
+    /** Session token for cross-trace linking. Auto-generated if absent. */
+    sessionToken?: string | undefined;
+}
+/**
+ * Create a new session state.
+ */
+export declare function createSession(options: SessionOptions): SessionState;
+/**
+ * Build the outbound _meta for a tools/call request (§5.4.3).
+ * Attaches attribution context, traceparent, session_token, and policy record ID.
+ */
+/**
+ * Build the outbound _meta for a tools/call request (§5.4.3).
+ * Attaches attribution context, traceparent, session_token, and policy record ID.
+ *
+ * Merges with the caller's existing _meta:
+ * - `baggage` and `tracestate` are APPENDED (W3C semantics, multi-vendor safe)
+ * - `traceparent` is overwritten only if the caller has not supplied one
+ * - `atrib` and `X-Atrib-Chain` are set (atrib-owned keys)
+ */
+export declare function buildOutboundMeta(session: SessionState, existing?: Record<string, unknown>): Record<string, string>;
+/**
+ * Read inbound attribution context from a tool response (§5.4.4).
+ * Updates session state with the latest context.
+ * Returns true if an attribution token was found.
+ */
+export declare function accumulateInboundContext(session: SessionState, responseMeta: Record<string, unknown> | undefined): boolean;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE5C,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,aAAa,GAAG,IAAI,CAAA;IACnC,WAAW,EAAE,OAAO,CAAA;IACpB,oEAAoE;IACpE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,mDAAmD;IACnD,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACpB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAClC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CA0BnE;AAED;;;GAGG;AACH;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmDxB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,YAAY,EACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAChD,OAAO,CAwCT"}

package/dist/session.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Agent session state management (§5.4).
+ *
+ * Tracks the latest attribution context across sequential tool calls
+ * within a session. The session is initialized lazily on the first
+ * outbound tool call.
+ */
+import { base64urlEncode, hexEncode, decodeToken, mergeTracestate, mergeBaggageAtribSession, } from '@atrib/mcp';
+/**
+ * Create a new session state.
+ */
+export function createSession(options) {
+    // Generate context_id (random 16-byte hex if no OTel trace available)
+    const contextIdBytes = new Uint8Array(16);
+    crypto.getRandomValues(contextIdBytes);
+    const contextId = hexEncode(contextIdBytes);
+    // Generate or use provided session_token
+    let sessionToken;
+    if (options.sessionToken) {
+        sessionToken = options.sessionToken;
+    }
+    else {
+        const tokenBytes = new Uint8Array(16);
+        crypto.getRandomValues(tokenBytes);
+        sessionToken = base64urlEncode(tokenBytes);
+    }
+    return {
+        contextId,
+        sessionToken,
+        latestContext: null,
+        initialized: false,
+        policyRecordId: null,
+        taskIds: new Set(),
+        gapNodes: [],
+        warnings: [],
+    };
+}
+/**
+ * Build the outbound _meta for a tools/call request (§5.4.3).
+ * Attaches attribution context, traceparent, session_token, and policy record ID.
+ */
+/**
+ * Build the outbound _meta for a tools/call request (§5.4.3).
+ * Attaches attribution context, traceparent, session_token, and policy record ID.
+ *
+ * Merges with the caller's existing _meta:
+ * - `baggage` and `tracestate` are APPENDED (W3C semantics, multi-vendor safe)
+ * - `traceparent` is overwritten only if the caller has not supplied one
+ * - `atrib` and `X-Atrib-Chain` are set (atrib-owned keys)
+ */
+export function buildOutboundMeta(session, existing = {}) {
+    const meta = {};
+    // §1.5.3.1: Set X-atrib-Context on every outbound request.
+    // The value is the raw 32-char hex context_id (not the propagation token).
+    meta['X-atrib-Context'] = session.contextId;
+    // §1.5.4: traceparent. only set if caller has not provided one.
+    // If they have one, the trace-id should already match session.contextId
+    // (since the session adopted it), so we leave it untouched.
+    if (typeof existing.traceparent === 'string') {
+        meta.traceparent = existing.traceparent;
+    }
+    else {
+        const parentIdBytes = new Uint8Array(8);
+        crypto.getRandomValues(parentIdBytes);
+        const parentId = hexEncode(parentIdBytes);
+        meta.traceparent = `00-${session.contextId}-${parentId}-01`;
+    }
+    // §5.4.3: baggage gets atrib-session prepended (most-recent vendor first
+    // per W3C). mergeBaggageAtribSession dedupes prior atrib-session entries
+    // and enforces the W3C 64-list-member and 8192-byte limits, evicting
+    // entries from the rightmost end if needed.
+    //
+    // policy is added as a separate, non-evictable entry. We add it after the
+    // session merge to ensure both atrib entries are leftmost.
+    const existingBaggage = typeof existing.baggage === 'string' ? existing.baggage : '';
+    let baggage = mergeBaggageAtribSession(session.sessionToken, existingBaggage);
+    if (session.policyRecordId) {
+        baggage = `atrib-policy=${session.policyRecordId},${baggage}`;
+    }
+    meta.baggage = baggage;
+    // Attach latest attribution token if available
+    if (session.latestContext) {
+        const token = `${base64urlEncode(session.latestContext.recordHash)}.${base64urlEncode(session.latestContext.creatorKey)}`;
+        meta.atrib = token;
+        meta['X-Atrib-Chain'] = token;
+        // §5.4.3: tracestate gets `atrib=<token>` PREPENDED so atrib appears
+        // leftmost (W3C "most recent vendor first" convention). mergeTracestate
+        // dedupes any prior atrib entry and enforces the W3C 32-list-member
+        // maximum, evicting from the rightmost end if needed.
+        const existingTracestate = typeof existing.tracestate === 'string' ? existing.tracestate : '';
+        meta.tracestate = mergeTracestate(`atrib=${token}`, existingTracestate);
+    }
+    else if (typeof existing.tracestate === 'string') {
+        // Preserve caller's tracestate if no atrib token to add
+        meta.tracestate = existing.tracestate;
+    }
+    return meta;
+}
+/**
+ * Read inbound attribution context from a tool response (§5.4.4).
+ * Updates session state with the latest context.
+ * Returns true if an attribution token was found.
+ */
+export function accumulateInboundContext(session, responseMeta) {
+    if (!responseMeta)
+        return false;
+    // Priority: _meta.atrib > tracestate atrib= > X-Atrib-Chain
+    let decoded = null;
+    if (typeof responseMeta.atrib === 'string') {
+        decoded = decodeToken(responseMeta.atrib);
+    }
+    if (!decoded && typeof responseMeta.tracestate === 'string') {
+        // W3C Trace Context list-member grammar allows OWS around `=`. Be lenient
+        // about whitespace and accept the entry whether it's leftmost or not.
+        for (const entry of responseMeta.tracestate.split(',')) {
+            const trimmed = entry.trim();
+            const match = trimmed.match(/^atrib\s*=\s*(.*)$/);
+            if (match && match[1] !== undefined) {
+                decoded = decodeToken(match[1].trim());
+                break;
+            }
+        }
+    }
+    if (!decoded) {
+        const xAtribChain = responseMeta['X-Atrib-Chain'] ?? responseMeta['x-atrib-chain'];
+        if (typeof xAtribChain === 'string') {
+            decoded = decodeToken(xAtribChain);
+        }
+    }
+    if (decoded) {
+        session.latestContext = {
+            recordHash: decoded.recordHash,
+            creatorKey: decoded.creatorKey,
+        };
+        return true;
+    }
+    // No token → tool doesn't have @atrib/mcp. Gap node in graph. Session continues.
+    return false;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/transaction.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Transaction detection (§5.4.5).
+ *
+ * Detects transaction events from response shapes for ACP, UCP, x402, MPP,
+ * AP2, and heuristic tool name matching.
+ *
+ * Protocol shape sources (verified 2026-04-06):
+ * - ACP: github.com/agentic-commerce-protocol/agentic-commerce-protocol
+ *        rfcs/rfc.agentic_checkout.md
+ * - UCP: github.com/universal-commerce-protocol/ucp
+ *        docs/specification/checkout-rest.md (version 2026-01-11)
+ * - AP2: github.com/google-agentic-commerce/ap2 (v0.1). A2A Message with a
+ *        DataPart containing the key `ap2.mandates.PaymentMandate`. AP2 does
+ *        NOT currently use W3C Verifiable Credentials despite earlier drafts
+ *        of this code and the atrib spec assuming it would.
+ * - a2a-x402: github.com/google-agentic-commerce/a2a-x402. extension that
+ *        layers x402 crypto payments over A2A. Detection signal is
+ *        `status.message.metadata["x402.payment.status"] === "payment-completed"`
+ *        with at least one `success: true` entry in
+ *        `status.message.metadata["x402.payment.receipts"]`. Both shapes are
+ *        reported as `protocol: 'AP2'` since a2a-x402 IS the AP2 crypto path.
+ * - x402: github.com/coinbase/x402. response header `PAYMENT-RESPONSE` (v2)
+ *        or `X-PAYMENT-RESPONSE` (v1 legacy). Value is base64-encoded JSON
+ *        with shape { success: bool, transaction, network, payer, requirements }.
+ * - MPP: IETF draft-ryan-httpauth-payment-01 ("The 'Payment' HTTP Authentication
+ *        Scheme"), per Section 5.3. Response header is `Payment-Receipt` on a
+ *        200 success after the client retries with Authorization: Payment.
+ *        Value is base64url-nopad JSON with required field { status: "success",
+ *        method, timestamp, reference }.
+ *
+ * x402 and MPP are DIFFERENT protocols that use DIFFERENT headers. Earlier
+ * versions of this code conflated them on a fictitious shared `Payment-Receipt`
+ * header. see DECISIONS.md D016 for the verification trail.
+ */
+export type TransactionProtocol = 'ACP' | 'UCP' | 'x402' | 'MPP' | 'AP2' | 'heuristic';
+export interface TransactionDetection {
+    detected: boolean;
+    protocol: TransactionProtocol | null;
+    /**
+     * For Path 2 content_id derivation (§5.4.5):
+     * - ACP/UCP: the order permalink URL from the response (if present)
+     * - x402/MPP: not available here (caller must use HTTP endpoint URL)
+     * - AP2: not available here (caller uses MCP server URL)
+     * - Heuristic: not available here (caller uses MCP server URL)
+     */
+    checkoutUrl: string | null;
+}
+/**
+ * Detect whether a tool call response contains a transaction signal (§5.4.5).
+ */
+export declare function detectTransaction(toolName: string, response: unknown, headers?: Record<string, string | undefined>): TransactionDetection;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,WAAW,CAAA;AAEtF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACpC;;;;;;OAMG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAWD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAC3C,oBAAoB,CAkItB"}

package/dist/transaction.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+const HEURISTIC_KEYWORDS = [
+    'create_order',
+    'complete_checkout',
+    'process_payment',
+    'place_order',
+    'purchase',
+    'checkout',
+];
+/**
+ * Detect whether a tool call response contains a transaction signal (§5.4.5).
+ */
+export function detectTransaction(toolName, response, headers) {
+    const resp = response;
+    // ACP / UCP completion response shape:
+    //   { id: "...", status: "completed", order: { id, permalink_url? }, ... }
+    // UCP additionally has a top-level `ucp: { version, capabilities }` envelope.
+    // Both shapes are produced by POST /checkout_sessions/{id}/complete (ACP)
+    // or POST /checkout-sessions/{id}/complete (UCP).
+    if (resp) {
+        const status = resp['status'];
+        const order = resp['order'];
+        if (status === 'completed' && order && typeof order['id'] === 'string') {
+            const ucpEnvelope = resp['ucp'];
+            const isUcp = !!ucpEnvelope && typeof ucpEnvelope['version'] === 'string';
+            const checkoutUrl = typeof order['permalink_url'] === 'string' ? order['permalink_url'] : null;
+            return { detected: true, protocol: isUcp ? 'UCP' : 'ACP', checkoutUrl };
+        }
+        // ACP webhook event shapes (server → merchant): order_create / order_update.
+        //   { type: "order_create", data: { type: "order", checkout_session_id, permalink_url, status, refunds } }
+        if (resp['type'] === 'order_create' || resp['type'] === 'order_update') {
+            const data = resp['data'];
+            const checkoutUrl = typeof data?.['permalink_url'] === 'string' ? data['permalink_url'] : null;
+            return { detected: true, protocol: 'ACP', checkoutUrl };
+        }
+    }
+    // x402 and MPP: distinct protocols, distinct response headers.
+    //
+    //   x402 v2  →  PAYMENT-RESPONSE       (renamed from v1 X-PAYMENT-RESPONSE)
+    //   MPP      →  Payment-Receipt        (per draft-ryan-httpauth-payment-01 §5.3)
+    //
+    // HTTP header names are case-insensitive per RFC 7230, so we accept any
+    // letter casing. JS object keys are not case-insensitive, so we lower-case
+    // the lookup table once and probe by lowercase key.
+    if (headers) {
+        const lower = {};
+        for (const [k, v] of Object.entries(headers)) {
+            if (typeof v === 'string')
+                lower[k.toLowerCase()] = v;
+        }
+        // x402. accept v2 and v1 names
+        if (lower['payment-response'] || lower['x-payment-response']) {
+            return { detected: true, protocol: 'x402', checkoutUrl: null };
+        }
+        // MPP. IETF draft Payment-Receipt header
+        if (lower['payment-receipt']) {
+            return { detected: true, protocol: 'MPP', checkoutUrl: null };
+        }
+    }
+    // AP2 v0.1. PaymentMandate Message inside an A2A DataPart.
+    // Source: github.com/google-agentic-commerce/ap2 docs/specification.md
+    // Shape: { ..., parts: [{ kind: "data", data: { "ap2.mandates.PaymentMandate": {...} } }, ...] }
+    if (resp) {
+        const parts = resp['parts'];
+        if (Array.isArray(parts)) {
+            for (const part of parts) {
+                if (part && typeof part === 'object') {
+                    const data = part['data'];
+                    if (data &&
+                        typeof data === 'object' &&
+                        'ap2.mandates.PaymentMandate' in data) {
+                        return { detected: true, protocol: 'AP2', checkoutUrl: null };
+                    }
+                }
+            }
+        }
+        // a2a-x402 extension. payment-completed via A2A task status metadata.
+        // Source: github.com/google-agentic-commerce/a2a-x402 spec/v0.1/spec.md
+        // Shape: { kind: "task", status: { message: { metadata: { "x402.payment.status": "payment-completed", "x402.payment.receipts": [{success, transaction, ...}] } } } }
+        // Guard on kind === "task" to prevent false positives from responses
+        // that incidentally contain matching metadata keys.
+        if (resp['kind'] === 'task') {
+            const status = resp['status'];
+            const statusMessage = status?.['message'];
+            const metadata = statusMessage?.['metadata'];
+            if (metadata && metadata['x402.payment.status'] === 'payment-completed') {
+                const receipts = metadata['x402.payment.receipts'];
+                if (Array.isArray(receipts) &&
+                    receipts.some((r) => r !== null &&
+                        typeof r === 'object' &&
+                        r['success'] === true)) {
+                    return { detected: true, protocol: 'AP2', checkoutUrl: null };
+                }
+            }
+        }
+        // Legacy: W3C Verifiable Credential PaymentMandate. AP2 v0.1 does NOT use
+        // VCs, but research forks and earlier drafts may. Kept as a backward-
+        // compatible fallback. Accepts both VC v2 array form and v1 string form.
+        const respType = resp['type'];
+        const credentialSubject = resp['credentialSubject'];
+        const subjectType = credentialSubject?.['type'];
+        const isVcArray = Array.isArray(respType) &&
+            respType.includes('VerifiableCredential') &&
+            respType.some((t) => typeof t === 'string' && /paymentmandate/i.test(t));
+        const isVcStringLegacy = respType === 'VerifiableCredential';
+        const subjectIsPaymentMandate = (typeof subjectType === 'string' && /paymentmandate/i.test(subjectType)) ||
+            (Array.isArray(subjectType) &&
+                subjectType.some((t) => typeof t === 'string' && /paymentmandate/i.test(t)));
+        // For v2 array form: the PaymentMandate type is in the type array itself,
+        // so no credentialSubject check needed. For v1 string form: type is just
+        // "VerifiableCredential" so we need credentialSubject to confirm it's a PaymentMandate.
+        if (isVcArray || (isVcStringLegacy && subjectIsPaymentMandate)) {
+            return { detected: true, protocol: 'AP2', checkoutUrl: null };
+        }
+    }
+    // Heuristic: tool name keywords (last resort)
+    const lowerName = toolName.toLowerCase();
+    if (HEURISTIC_KEYWORDS.some((k) => lowerName.includes(k))) {
+        return { detected: true, protocol: 'heuristic', checkoutUrl: null };
+    }
+    return { detected: false, protocol: null, checkoutUrl: null };
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"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"}