@agent-cards/commerce-sdk 0.19.1 → 0.20.0

package/dist/buy-tool.d.ts

@@ -604,6 +604,15 @@ export interface BuyTool {
      * call's answer tells the model where the purchase stands. Post `message.text` then, as before.
      */
     nextStep(message: ShopperMessage, options?: BuyToolTurnOptions): BuyToolTurn | null;
+    /**
+     * The carts this tool last showed, with the cart an `order_placed` message is about marked placed: its `totalStatus`
+     * reads `placed` and its total is the total the order placed at. A store that sets its final amount later names only an
+     * estimate, and the cart keeps `totalIsEstimate` true at that estimate. The tool's `onCart` hears the carts before the
+     * promise settles, so await it in your webhook's `onMessage`. Pass every message `onMessage` got. Answers null for any
+     * other message, a message about another conversation or shopper, or one whose cart this tool cannot tell: the message
+     * names a store none of the carts is at, and more than one cart is on the table.
+     */
+    placedCarts(message: ShopperMessage): Promise<BuyCart[] | null>;
 }
 /**
  * One thing a turn hands the shopper: a message, such as the instant reply or a paragraph your model

package/dist/buy-tool.js

@@ -769,7 +769,7 @@ function endTurn(state) {
  * The hash alone is not enough, since a store pricing a cart again changes `pricing` and its total under one hash.
  */
 function cartsKey(carts) {
-    return JSON.stringify(carts.map((c) => [c.hash, c.totalCents, c.pricing === true, c.totalIsEstimate, c.items.map((i) => [i.line_id, i.qty, i.lineTotalCents])]));
+    return JSON.stringify(carts.map((c) => [c.hash, c.totalCents, c.pricing === true, c.totalIsEstimate, c.totalStatus, c.items.map((i) => [i.line_id, i.qty, i.lineTotalCents])]));
 }
 export function buyTool(options) {
     const o = options ?? {};
@@ -934,6 +934,24 @@ export function buyTool(options) {
     let callsStarted = 0;
     let cartsFromCall = 0;
     let lastCarts = [];
+    /**
+     * The carts an order placed marked (`placedCarts`), by hash, with their conversation: an answer in that conversation that
+     * still lists one, such as a call that began before the order placed, shows it placed. The first answer that no longer
+     * lists it forgets it, so the same items carted again later are a new purchase.
+     */
+    const placedByHash = new Map();
+    const placedIn = (hash, conversationId) => {
+        const kept = placedByHash.get(hash);
+        return kept && (!kept.conversationId || !conversationId || kept.conversationId === conversationId) ? kept.cart : undefined;
+    };
+    const withPlaced = (carts, conversationId) => carts.map((c) => placedIn(c.hash, conversationId) ?? c);
+    /** The conversation the carts that left the table were in. */
+    let leftCartsIn = null;
+    /** The newest call whose answer set the carts the tool keeps. */
+    let cartsKeptFromCall = 0;
+    const cartKey = (c) => `${c.merchant}|${c.store?.id ?? ''}`;
+    /** The carts an answer took off the table, newest first, at most five: an order placed before its message arrived leaves its cart here. */
+    let leftCarts = [];
     /** The cart the last answer showed: the cart a confirm sent now confirms. */
     let lastShownCart = null;
     /**
@@ -2144,10 +2162,11 @@ export function buyTool(options) {
                         : {}),
                     ...(t.onCart
                         ? {
-                            onCart: async ({ cart, carts, conversationId }) => {
+                            onCart: async ({ cart: sent, carts: sentCarts, conversationId }) => {
                                 // A newer call already handed on its carts: this older stream's are stale, however late they come.
                                 if (callNo < cartsFromCall)
                                     return;
+                                const [cart, carts] = [sent ? placedIn(sent.hash, conversationId) ?? sent : sent, withPlaced(sentCarts, conversationId)];
                                 t.cartsHeard = cartsKey(carts);
                                 cartsFromCall = callNo;
                                 try {
@@ -2329,7 +2348,26 @@ export function buyTool(options) {
             // A refusal reports no carts, so only a turn's answer says how many wait, and whether a checkout just ended with none.
             if (turn) {
                 lastCartCount = result.carts.length;
-                lastCarts = result.carts;
+                // A cart an order placed reads placed in every answer that still lists it.
+                const answeredIn = result.conversation_id ?? lastConversationId;
+                result.carts = withPlaced(result.carts, answeredIn);
+                if (result.cart)
+                    result.cart = placedIn(result.cart.hash, answeredIn) ?? result.cart;
+                // Only the newest call's answer moves what the tool keeps: an older call's answer is no word on the carts as they stand.
+                if (callNo >= cartsKeptFromCall) {
+                    cartsKeptFromCall = callNo;
+                    for (const hash of [...placedByHash.keys()])
+                        if (!result.error_code && !result.carts.some((c) => c.hash === hash))
+                            placedByHash.delete(hash);
+                    // The carts that left the table, newest first, one per store. A cart the answer still holds at the same store, edited
+                    // or priced again, is the same purchase in a new version, so its older version never counts as one that left.
+                    const left = lastCarts.filter((c) => !result.carts.some((n) => n.hash === c.hash || cartKey(n) === cartKey(c)));
+                    // A new conversation is a new purchase: the carts that left the one before it are no longer its carts.
+                    const sameConversation = !answeredIn || !leftCartsIn || answeredIn === leftCartsIn;
+                    leftCarts = [...(sameConversation ? left : []), ...(sameConversation ? leftCarts : []).filter((c) => !left.some((n) => cartKey(n) === cartKey(c)))].slice(0, 5);
+                    leftCartsIn = answeredIn ?? leftCartsIn;
+                    lastCarts = result.carts;
+                }
                 // The answer's carts are the conversation's as they stand, an empty list included: onCart hears them when the stream
                 // sent none or older ones, so an app never keeps showing a cart Agentcard no longer holds (a stream sends a cart only
                 // when a tool changed it, and a call with stream: false sends none).
@@ -2391,8 +2429,8 @@ export function buyTool(options) {
                 held.add(id);
                 tappable.push(product);
             }
-            lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name }));
-            lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name }));
+            lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name, store: product.store }));
+            lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name, store: product.store }));
             // A new conversation starts the cards shown before afresh; each card keeps its newest showing, up to SHOWN_BEFORE_MAX.
             if (result.conversation_id && result.conversation_id !== shownIn)
                 shownBefore = [];
@@ -2489,6 +2527,45 @@ export function buyTool(options) {
             client.answered(externalUserId, message, threadId);
         return openTurn(nextStepPrompt(message), options, message);
     };
+    /** The carts with the one an order_placed message is about marked placed at its total (`BuyTool.placedCarts`). */
+    const placedCarts = async (message) => {
+        if (!message || typeof message !== 'object' || message.kind !== 'order_placed')
+            return null;
+        if (client.company && message.externalUserId !== externalUserId)
+            return null;
+        if (message.conversationId && lastConversationId && message.conversationId !== lastConversationId)
+            return null;
+        const store = message.facts?.merchantName?.trim().toLowerCase();
+        const named = (pool) => (store ? pool.filter((c) => [c.merchant_name, c.store?.name, c.store?.id, c.merchant].some((n) => n?.trim().toLowerCase() === store)) : []);
+        const [open, left] = [named(lastCarts), named(leftCarts)];
+        // The one cart the message names, on the table or one an answer took off it once the order placed, else the only cart.
+        // A name that fits more than one cart, an open one and one that left included, tells none apart: the order may be either.
+        const cart = open.length + left.length > 1 ? null
+            : open[0] ?? left[0] ?? (lastCarts.length === 1 ? lastCarts[0] : lastCarts.length === 0 && leftCarts.length === 1 ? leftCarts[0] : null);
+        if (!cart)
+            return null;
+        const [total, estimate] = [message.facts?.totalCents, message.facts?.estimatedTotalCents];
+        const final = typeof total === 'number' && total >= 0;
+        const placed = {
+            ...cart,
+            totalStatus: 'placed',
+            ...(final ? { totalCents: total, totalIsEstimate: false } : typeof estimate === 'number' && estimate >= 0 ? { totalCents: estimate, totalIsEstimate: true } : {}),
+        };
+        // A cart an answer took off the table is shown again, placed, beside the carts still open.
+        const carts = lastCarts.includes(cart) ? lastCarts.map((c) => (c === cart ? placed : c)) : [...lastCarts, placed];
+        leftCarts = leftCarts.filter((c) => c !== cart);
+        lastCarts = carts;
+        placedByHash.set(cart.hash, { cart: placed, conversationId: lastConversationId });
+        if (o.onCart && lastConversationId) {
+            try {
+                await o.onCart(placed, { carts, conversationId: lastConversationId });
+            }
+            catch {
+                // The app's display failing never fails the message.
+            }
+        }
+        return carts;
+    };
     const openTurn = (shopperText, options, event) => {
         const own = options ?? {};
         if (typeof own !== 'object')
@@ -2919,5 +2996,5 @@ export function buyTool(options) {
             say: { value: sayWhole, enumerable: false },
         });
     };
-    return toolOf(answer, { instantAck, instantReaction, turn, nextStep }, {});
+    return toolOf(answer, { instantAck, instantReaction, turn, nextStep, placedCarts }, {});
 }

package/dist/client.d.ts

@@ -472,6 +472,8 @@ export interface BuyCartHold {
     amountCents: number;
     reason: 'flight' | 'hotel' | 'checkout_estimate';
 }
+/** Where a cart's total stands: an estimate, the store's confirmed total, or the total of the order placed. */
+export type BuyCartTotalStatus = 'estimate' | 'confirmed' | 'placed';
 export interface BuyCart {
     merchant: string;
     merchant_name: string;
@@ -494,6 +496,13 @@ export interface BuyCart {
      * known fees only: show it as an estimate. DoorDash prices a cart once the shopper's own account holds it.
      */
     totalIsEstimate: boolean;
+    /**
+     * Where `totalCents` stands: `estimate` before the store priced the cart, `confirmed` once the store priced it, such
+     * as when the approval asks for the store's total, and `placed` once the order is placed (`buy.placedCarts`). A placed
+     * order whose store has not set its final amount yet keeps `totalIsEstimate` true. An older API sends none, and the
+     * cart reads `estimate` when `totalIsEstimate` is true, else `confirmed`.
+     */
+    totalStatus: BuyCartTotalStatus;
     /** The ISO 4217 code the store prices the cart in, or null when Agentcard sent none. */
     currency: string | null;
     approvedCeilingCents: number | null;

package/dist/client.js

@@ -232,6 +232,11 @@ function feesOf(v) {
             && amount !== null && Number.isSafeInteger(amount) && amount >= 0 ? 'known' : 'unknown';
     return { serviceFeesCents: status === 'known' ? amount : null, serviceFeesStatus: status };
 }
+function totalStatusOf(v) {
+    if (v.totalStatus === 'estimate' || v.totalStatus === 'confirmed' || v.totalStatus === 'placed')
+        return v.totalStatus;
+    return v.totalIsEstimate === true ? 'estimate' : 'confirmed';
+}
 function cartOf(v) {
     if (!isRecord(v) || !str(v.hash) || !str(v.merchant))
         return null;
@@ -265,6 +270,7 @@ function cartOf(v) {
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
         totalIsEstimate: v.totalIsEstimate === true,
+        totalStatus: totalStatusOf(v),
         currency: str(v.currency),
         approvedCeilingCents: num(v.approvedCeilingCents),
         hold: holdOf(v.hold),

package/dist/direct.d.ts

@@ -21,10 +21,11 @@ export interface DirectContext {
     nextAction?: BuyNextAction | null;
     /** Agentcard's last reply, the question a short answer answers. */
     asked?: string | null;
-    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. A place (`the second one`) reads these. */
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends and the store that sells each. A place (`the second one`) reads these. */
     products?: ReadonlyArray<{
         productId: string | null;
         name: string;
+        store?: string | null;
     }>;
     /**
      * Every product card the shopper can tap by its name, each once: the answer's and the ones its searches sent as they answered,
@@ -35,6 +36,7 @@ export interface DirectContext {
     tappable?: ReadonlyArray<{
         productId: string | null;
         name: string;
+        store?: string | null;
     }>;
     /**
      * Every product card an earlier answer of this conversation showed, each once, newest first. A card's tap whose name no card

package/dist/direct.js

@@ -164,6 +164,33 @@ function tappedName(raw) {
     const name = TAP.exec(raw.trim())?.[1]?.trim();
     return name ? name : null;
 }
+/**
+ * The words a pick by one word of a product's name says around that word, as `nameWords` spells them: `lets do the X ones`,
+ * `I'll take the X`, `go with X`, `X please`, `X, 2 of them`, `X is fine`. A yes, a no or any other word is not among them.
+ */
+const PICK_FRAME = new Set('the a an one ones that this lets let s do go with i ll take get want give me is fine good works uh uhh um umm please pls plz of them those it x pack packs'.split(' '));
+/** The stores a message names by brand, `home depot` and `barnes & noble` whole, as the words `nameWords` spells them. */
+const STORE_NAMED = new RegExp(`(?<![\\p{L}\\p{N}])(?:${STORES})(?![\\p{L}\\p{N}])`, 'gu');
+function storesNamed(raw) {
+    return [...String(raw ?? '').toLowerCase().matchAll(STORE_NAMED)].map((match) => nameWords(match[0]));
+}
+/**
+ * True when a message picks this product by a word only its name holds, such as its brand. Every other word of the message is the
+ * product's own or a pick frame's (`PICK_FRAME`), and the word is no part of a store's name the message holds (`home depot`), or of
+ * the product's own store, unless the product's name opens with that store's name, as Amazon Basics does. On 2026-11-05
+ * (conv_64712285dd09f5bbab6fc737) the agent showed eight books and offered to look at eBay, the shopper answered "yes ebay
+ * specifically", and "ebay", held by "The Expert Guide To Cashing In On eBay" alone, went as a tap on that card.
+ */
+function marksProduct(raw, said, product, cards) {
+    const own = nameWords(product.name).split(' ');
+    const title = ` ${own.join(' ')} `;
+    // Each store the message names, and the product's own store, unless the product's name opens with it (a store's own brand).
+    const stores = [...storesNamed(raw), nameWords(product.store ?? '')].filter((store) => store !== '' && !title.startsWith(` ${store} `));
+    const isStore = (word) => stores.some((store) => store.split(' ').includes(word));
+    const words = said.split(' ');
+    const marks = words.filter((word) => word.length >= 4 && !/^\d/.test(word) && own.includes(word) && !isStore(word) && cards.filter((card) => nameWords(card.name).split(' ').includes(word)).length === 1);
+    return marks.length > 0 && words.every((word) => own.includes(word) || PICK_FRAME.has(word) || /^\d+$/.test(word));
+}
 /** The pick a message makes of what Agentcard just showed, null when it picks nothing, or false when it counts past the list. */
 function pickOf(raw, bare, context) {
     const products = context.products ?? [];
@@ -213,9 +240,7 @@ function pickOf(raw, bare, context) {
         if (named.length > 1)
             return call({});
         // A word only one product's name holds, such as its brand: `lets do the coppertop ones`, `duracell 24 count is fine`.
-        const words = new Set(said.split(' '));
-        const owners = (word) => byName.filter((product) => nameWords(product.name).split(' ').includes(word));
-        const marked = byName.filter((product) => nameWords(product.name).split(' ').some((word) => word.length >= 4 && !/^\d/.test(word) && words.has(word) && owners(word).length === 1));
+        const marked = byName.filter((product) => marksProduct(raw, said, product, byName));
         if (marked.length === 1 && said.split(' ').length <= 10 && !QUESTION_START.test(bare) && !DOUBT.test(said))
             return call({ product_id: marked[0].productId });
         const places = placesOf(bare, products.length);

package/dist/index.d.ts

@@ -6,13 +6,13 @@ export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderSte
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
 export { searchAt, isMerchantStatusAt, merchantStatusLine, searchStatusLines, type BuySearchStatus, type BuyMerchantStatus, type BuyMerchantSearchStatus, type BuyMerchantStatusUpdate, } from './search-status.js';
 export { groupsOf, type BuyGroup, type BuyGroupKind, type BuyGroupStatus, type BuyGroupWithProducts, type BuyGroupsSource, type BuyGroupsUpdate, } from './search-groups.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyStoreCheckUpdate, type BuyFoundUpdate, type BuyTurnStatus, STATUS_WORDING, type BuySegmentUpdate, type BuyRecheck, type BuyFreshness, type BuyFreshnessState, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyCartDiscount, type BuyCartHold, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyFlightParty, type BuyPaymentSource, type BuyConversation, type BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyCodeRequest, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } from './client.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyStoreCheckUpdate, type BuyFoundUpdate, type BuyTurnStatus, STATUS_WORDING, type BuySegmentUpdate, type BuyRecheck, type BuyFreshness, type BuyFreshnessState, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyCartDiscount, type BuyCartHold, type BuyCartTotalStatus, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyFlightParty, type BuyPaymentSource, type BuyConversation, type BuyLatestReply, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyCodeRequest, type BuyChoiceGroup, type BuyChoiceDelivery, type BuyChoiceOption, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION, type AckForOptions } from './ack.js';
 export { directCall, isProductAsk, type DirectCall, type DirectContext, type DirectReason } from './direct.js';
-export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, type BuyToolModelView, type BuyToolModelCart, type BuyToolGrandTotal, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
+export { forModel, cartsForModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, type BuyToolModelView, type BuyToolModelCart, type BuyToolGrandTotal, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice, type ReplyAsWrittenOptions } from './texting.js';
 export { appInstructions, APP_INSTRUCTIONS_VERSION, type AppInstructionsOptions } from './app-instructions.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';

package/dist/index.js

@@ -12,7 +12,7 @@ export { toMessages, messageStream, typingDelay, } from './messages.js';
 export { buyTool, nextStepPrompt, productAction, } from './buy-tool.js';
 export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION } from './ack.js';
 export { directCall, isProductAsk } from './direct.js';
-export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, } from './model-view.js';
+export { forModel, cartsForModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, flightPartyWords, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice } from './texting.js';
 export { appInstructions, APP_INSTRUCTIONS_VERSION } from './app-instructions.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';

package/dist/model-view.d.ts

@@ -51,6 +51,11 @@ export interface BuyToolModelCart {
     total: string;
     /** True when the store has not priced its fees and tax yet: `total` is an estimate, never the final amount. */
     total_is_estimate: boolean;
+    /**
+     * Where `total` stands: `estimate` before the store priced the cart, `confirmed` once the store priced it, and `placed`
+     * once the order is placed. `total` is the final amount unless `total_is_estimate` is true.
+     */
+    total_status: 'estimate' | 'confirmed' | 'placed';
     /** What an estimated `total` leaves out, in words the model can repeat; null when the store priced the cart. */
     total_leaves_out: string | null;
     /** The most the shopper's card can be held for this cart: above `total` at a store that prices its final at checkout, `total` itself for a flight, which holds exactly that; else null. */
@@ -266,6 +271,8 @@ export declare function expiresIn(iso: string | null | undefined, now?: number):
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */
+/** The carts and their grand totals as the model reads them, for carts a turn's answer did not bring, such as `buy.placedCarts`'. */
+export declare function cartsForModel(carts: readonly BuyCart[]): Pick<BuyToolModelView, 'carts' | 'grand_totals'>;
 export declare function forModel(result: BuyToolResult): BuyToolModelView;
 /**
  * The fixed short line for an answer whose next step is a link the shopper already holds: `add your card to place the

package/dist/model-view.js

@@ -230,6 +230,7 @@ function cartView(cart, building) {
         tip: cart.tipCents > 0 ? money(cart.tipCents, cart.currency) : null,
         total: money(cart.totalCents, cart.currency) ?? money(0, cart.currency),
         total_is_estimate: cart.totalIsEstimate === true,
+        total_status: cart.totalStatus,
         // 2026-10-21, swarm-bigbox-a10: an estimate read "about $18.41 total with tax and shipping" to the shopper. The words
         // ride beside the flag, so the model never has to guess which side of the total tax and shipping sit on.
         total_leaves_out: cart.totalIsEstimate === true ? leftOut(cart.merchantFeeLines ?? []) : null,
@@ -303,6 +304,10 @@ function linkExpiry(result) {
  * whether the shopper has each link. A status this version does not know
  * reads as `needs_input`.
  */
+/** The carts and their grand totals as the model reads them, for carts a turn's answer did not bring, such as `buy.placedCarts`'. */
+export function cartsForModel(carts) {
+    return { carts: carts.map((cart) => cartView(cart)), grand_totals: grandTotals(carts) };
+}
 export function forModel(result) {
     const status = typeof result.status === 'string' && MODEL_STATUSES.has(result.status) ? result.status : 'needs_input';
     const products = shownProducts(result.products);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
   "homepage": "https://opencommerce.sh",
   "type": "module",