@agent-cards/commerce-sdk 0.14.0 → 0.16.0

package/dist/buy-tool.js

@@ -33,12 +33,13 @@
  */
 import { AgentcardApiError, AgentcardClient, cartBuildingOf, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
-import { directCall } from './direct.js';
-import { forModel, forModelError, pickId, productPrice, productCardKey, replyAsWritten, shownProducts, shownStores, stripLinks } from './model-view.js';
+import { directCall, isProductAsk } from './direct.js';
+import { forModel, forModelError, pickId, productPrice, productCardKey, shownProducts, shownStores, stripLinks } from './model-view.js';
+import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, replyAsWritten, textingStyle } from './texting.js';
 import { messageStream, paceOf, sleep, toMessages, typingHook } from './messages.js';
 import { isStale } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
-import { ACK_REACTION, ackAt, answersQuestion, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, slowStepLine, waitAt } from './ack.js';
+import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, slowStepLine, waitAt } from './ack.js';
 /** The action a product of `merchant` takes (BuyToolProductAction). */
 export function productAction(merchant) {
     if (merchant === 'reservations')
@@ -145,6 +146,70 @@ const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper wha
 const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
 const STORE_PICK_GONE = "The store the shopper picked is no longer among the stores Agentcard found, so no store was chosen. Call this tool again with the shopper's words and store_id null, and Agentcard searches again.";
 const PICK_GONE = "The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.";
+/** One cart line as the order holds it: the product, its variant, its choices and its quantity. Prices are left out. */
+const lineKey = (line) => JSON.stringify([line.product_id ?? String(line.name ?? '').trim().toLowerCase(), line.variant ?? null, [...(line.options ?? [])].sort(), line.qty]);
+/**
+ * How two matched lines' prices stand: false when a price they both name moved, true when one they both name agrees, and
+ * null when they name none in common, so the lines say nothing about what they cost.
+ */
+function linePriceStands(a, b) {
+    const named = (x, y) => typeof x === 'number' && typeof y === 'number' ? x === y : null;
+    const read = [named(a.priceCents, b.priceCents), named(a.lineTotalCents, b.lineTotalCents)];
+    if (read.includes(false))
+        return false;
+    return read.includes(true) ? true : null;
+}
+/**
+ * True when two carts are the same order: the same store, the same items in the same quantities with the same choices,
+ * and the same price for those items. Only the total may differ, as when the store prices its fees, tax and delivery in
+ * once the shopper's account holds the cart (Mendocino Farms on DoorDash, 2026-10-27: about $15.90, then $17.89).
+ *
+ * What the items cost has to be shown to be the same: every matched line's prices agree, or both carts name a subtotal
+ * and it is equal. A line whose price moved, two lines whose prices swapped under one subtotal, and a cart nothing
+ * prices are each a different order, so the shopper is asked again (review of #11087).
+ */
+function sameOrder(a, b) {
+    if (a.merchant !== b.merchant || (a.store?.id ?? null) !== (b.store?.id ?? null))
+        return false;
+    if ((a.currency ?? null) !== (b.currency ?? null))
+        return false;
+    const subtotals = typeof a.subtotalCents === 'number' && typeof b.subtotalCents === 'number' ? a.subtotalCents === b.subtotalCents : null;
+    if (subtotals === false)
+        return false;
+    const lines = (cart) => [...(cart.items ?? [])].sort((p, q) => (lineKey(p) < lineKey(q) ? -1 : lineKey(p) > lineKey(q) ? 1 : 0));
+    const [x, y] = [lines(a), lines(b)];
+    if (x.length === 0 || x.length !== y.length || !x.every((line, i) => lineKey(line) === lineKey(y[i])))
+        return false;
+    const prices = x.map((line, i) => linePriceStands(line, y[i]));
+    if (prices.includes(false))
+        return false;
+    return subtotals === true || prices.every((stands) => stands === true);
+}
+/** True when `now` holds an item `before` did not: the call put something new in the cart. */
+function addsItem(now, before) {
+    if (!now || (now.items ?? []).length === 0)
+        return false;
+    const had = new Set((before && before.merchant === now.merchant ? before.items ?? [] : []).map((line) => lineKey({ ...line, qty: 0 })));
+    return (now.items ?? []).some((line) => !had.has(lineKey({ ...line, qty: 0 })));
+}
+/**
+ * The yes left standing when a confirm stopped for a step outside the chat, or null. The cart the confirm stopped on must
+ * be the same order as the one the yes covers; the total the shopper said yes to stays the one they saw.
+ */
+function yesAfter(result, yes) {
+    const stopped = result.cart ?? (result.carts.length === 1 ? result.carts[0] : null);
+    if ('carried' in yes) {
+        if (stopped && !sameOrder(stopped, yes.carried.cart))
+            return null;
+        return { ...yes.carried, cart: stopped ?? yes.carried.cart, conversationId: result.conversation_id ?? yes.carried.conversationId };
+    }
+    const seen = yes.shown ?? stopped;
+    if (!seen || (yes.shown && stopped && !sameOrder(yes.shown, stopped)))
+        return null;
+    return { conversationId: result.conversation_id, cart: stopped ?? seen, totalCents: seen.totalCents };
+}
+/** The words of the call a `nextStep` turn's `direct` makes. They never reach Agentcard: the turn's calls send no ask. */
+const NEXT_STEP_ASK = 'take the next step';
 /** What a call of a `nextStep` turn answers with when the shopper has not said yes to the cart on the table. */
 const ASK_FOR_YES = "The cart is ready, and the shopper has not said yes to it in the chat, so nothing was confirmed. Say the cart's total in one short line and ask for their yes.";
 const STEP_AFTER_DECLINE = 'The shopper declined the approval, so nothing was charged and no order was placed. The cart is still here. Say so in one short line and offer the way forward: their yes sends a new approval link, or they can change the order.';
@@ -201,7 +266,7 @@ export function productsOf(turn) {
 /** A product's card as `sendLink` hears it: the id the model reads and a pick takes, never the store page, which is `url`. A flight option has no page at a store: its card carries no url, and its productId picks it. */
 function productLink(product) {
     const productId = pickId(product);
-    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), expiresAt: null };
+    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
 }
 function productsOfCatalog(catalog) {
     return (catalog.items ?? [])
@@ -220,6 +285,7 @@ function productsOfCatalog(catalog) {
         url: item.url ?? null,
         action: productAction(catalog.merchant),
         linkSent: false,
+        ...(item.availability ? { availability: item.availability } : {}),
     }));
 }
 /** The stores an answer presents, as the tool reads them. */
@@ -263,6 +329,7 @@ function answerOf(turn) {
         store_pick: turn.store_pick,
         hashes: hashesOf(turn.cart, turn.carts),
         cart_building: turn.cart_building,
+        choice: turn.choice ?? null,
         envelope: turn.raw,
     };
 }
@@ -673,7 +740,7 @@ export function buyTool(options) {
     if (o.stream !== undefined && o.stream !== false)
         throw new TypeError('Pass stream as false to wait for each whole answer, or leave it out.');
     const onProgress = o.onProgress;
-    for (const key of ['onStatus', 'onFound']) {
+    for (const key of ['onStatus', 'onFound', 'onAvailability']) {
         if (o[key] !== undefined && typeof o[key] !== 'function')
             throw new TypeError(`Pass ${key} as a function, or leave it out.`);
     }
@@ -688,6 +755,9 @@ export function buyTool(options) {
     if (o.replyAsWritten !== undefined && typeof o.replyAsWritten !== 'boolean')
         throw new TypeError('Pass replyAsWritten as true or false.');
     const writtenByDefault = o.replyAsWritten === true;
+    if (o.textingStyle !== undefined && typeof o.textingStyle !== 'boolean')
+        throw new TypeError('Pass textingStyle as true or false.');
+    const textingByDefault = o.textingStyle === true;
     if (o.direct !== undefined && typeof o.direct !== 'boolean')
         throw new TypeError('Pass direct as true or false.');
     const directOn = o.direct === true;
@@ -745,8 +815,10 @@ export function buyTool(options) {
         onProgress,
         onStatus: o.onStatus,
         onFound: o.onFound,
+        onAvailability: o.onAvailability,
         onProducts: o.onProducts,
         onText: o.onText,
+        texting: textingByDefault,
         onCart: o.onCart,
         links: null,
         results: null,
@@ -779,14 +851,25 @@ export function buyTool(options) {
     /** The conversation and the carts of the last answer, for a `nextStep` call that cannot read the conversation. */
     let lastConversationId = null;
     let lastCarts = [];
-    /** The hash of the cart the last answer showed: the cart a confirm sent now confirms. */
-    let lastShownHash = null;
+    /** The cart the last answer showed: the cart a confirm sent now confirms. */
+    let lastShownCart = null;
     /**
-     * The yes the shopper gave in the chat to one cart, by its hash, when the confirm it sent stopped for a
-     * step outside the chat: a card to add or a store to sign in to. A `nextStep` turn confirms that cart
-     * once the step is done. Any shopper message that is not a plain go-ahead, `ok` or `done` takes it back.
+     * The yes the shopper gave in the chat to one cart, when the confirm it sent stopped for a step outside the chat: a card
+     * to add or a store to sign in to. A `nextStep` turn confirms the cart once the step is done, as long as it holds the
+     * same items at the same store (`sameOrder`): a total that moved because the store priced its fees and tax in keeps the
+     * yes, and the turn says the new total. Any shopper message that is not a plain go-ahead, `ok` or `done` takes it back,
+     * and so does a declined approval.
      */
     let carriedYes = null;
+    /**
+     * The go-ahead of the shopper's pick, when they picked what is in the cart and answered only the checkout's questions
+     * since (address, phone, name, email, a yes to an address read back). A `nextStep` turn after a saved card or a store
+     * sign-in confirms that cart as it stands, when it is the same order (`sameOrder`), whatever the Vault does: the approval
+     * link is the shopper's approval. Any other shopper message takes it back, and so do a cart that changed and a declined approval.
+     */
+    let pickedOrder = null;
+    /** How many shopper messages took a pick's go-ahead back: a call that started before one leaves no pick behind. */
+    let pickWithdrawals = 0;
     /** The add-card link an answer carried while it asked for the store sign-in first: the card is the step after it. */
     let cardAfterSignIn = null;
     /** The shopper's words that never ran because they were not connected yet: they run once their card is saved. */
@@ -832,7 +915,17 @@ export function buyTool(options) {
      * way a shopper message reaches the tool runs it: `turn`, `instantAck` and `instantReaction` (review of #9220).
      */
     const withdrawUnlessGoAhead = (shopperText) => {
-        if (keepsYes(String(shopperText ?? '')))
+        const text = String(shopperText ?? '');
+        const goAhead = keepsYes(text);
+        // A pick's go-ahead also stands through the answers the checkout asks for, and through the answer that lets the store
+        // cart the pick, such as a size, while no cart holds it yet.
+        // Counted with no pick standing too, so a pick still running when the shopper says "no wait" leaves none behind.
+        // A short `cancel`, `wait` or `no` answers the question's shape, so it never counts as the answer the pick waits on.
+        if (!goAhead && !answersCheckout(text, { nextAction: lastNextAction, asked: lastReply }) && !(pickedOrder?.cart === null && answersQuestion(text, lastReply) && !holdsBack(text))) {
+            pickedOrder = null;
+            pickWithdrawals++;
+        }
+        if (goAhead)
             return;
         carriedYes = null;
         unconnectedAsk = null;
@@ -1320,7 +1413,7 @@ export function buyTool(options) {
             return;
         const outside = result.status === 'needs_card' || result.next_action === 'add_card' || result.next_action === 'store_login';
         if (call.confirm)
-            carriedYes = outside && call.yesHash ? { hash: call.yesHash } : null;
+            carriedYes = outside ? yesAfter(result, call.yes) : null;
         if (result.next_action === 'store_login' && turn?.add_card_url)
             cardAfterSignIn = { url: turn.add_card_url, expiresAt: turn.add_card_expires_at };
         else if (result.next_action !== 'store_login')
@@ -1328,6 +1421,45 @@ export function buyTool(options) {
         if (!call.confirm && call.ask !== '')
             unconnectedAsk = result.error_code === 'user_not_connected' ? call.ask : null;
     };
+    /**
+     * What a shopper's own call leaves of a pick's go-ahead (`pickedOrder`). A pick, a tap on a product's card or a request
+     * to buy it, that leaves one cart and no list of products to choose from starts one, with that cart; one whose store still
+     * asks a question before it carts the pick starts one with no cart yet. A later answer keeps it while the cart stays the
+     * same order, and notes the cart as the chat shows it now; an answer whose cart changed, another purchase, more than one
+     * cart, or a confirm of the shopper's own ends it. `heard` is false for a call whose shopper message no turn read
+     * (`withdrawUnlessGoAhead`): its words must then answer the checkout too.
+     */
+    const notePick = (result, call) => {
+        if (call.pickWithdrawalsAtStart !== pickWithdrawals)
+            return;
+        const now = result.cart ?? (result.carts.length === 1 ? result.carts[0] : null);
+        if (call.picking) {
+            // A search that listed products beside a cart already there picked nothing in it; one that carted what it names did.
+            const listed = shownProducts(result.products).length > 0;
+            pickedOrder = result.carts.length > 1
+                ? null
+                : now && (!listed || call.added)
+                    ? { conversationId: result.conversation_id, cart: now }
+                    : !now && !listed && result.error_code === null
+                        ? { conversationId: result.conversation_id, cart: null }
+                        : null;
+            return;
+        }
+        const picked = pickedOrder;
+        if (!picked)
+            return;
+        if (call.confirm || result.carts.length > 1 || (picked.conversationId && result.conversation_id && result.conversation_id !== picked.conversationId)) {
+            pickedOrder = null;
+            return;
+        }
+        if (!call.heard && !keepsYes(call.ask) && !answersCheckout(call.ask, { nextAction: call.asked.nextAction, asked: call.asked.reply })) {
+            pickedOrder = null;
+            return;
+        }
+        if (!now)
+            return;
+        pickedOrder = picked.cart === null || sameOrder(now, picked.cart) ? { conversationId: picked.conversationId ?? result.conversation_id, cart: now } : null;
+    };
     /** An answer the tool writes itself, from where the purchase stands, with nothing sent to Agentcard. */
     const stepResult = (fields) => ({
         messages: [],
@@ -1369,6 +1501,7 @@ export function buyTool(options) {
         const standing = { cart: one ?? carts.at(-1) ?? null, carts, hashes: carts.map((c) => c.hash), conversation_id: conversationId };
         if (event.kind === 'approval_declined') {
             carriedYes = null;
+            pickedOrder = null;
             return { local: stepResult({ ...standing, status: 'needs_input', reply: carts.length > 0 ? STEP_AFTER_DECLINE : NO_CART_WAITING }) };
         }
         if (event.kind === 'card_added' && unconnectedAsk) {
@@ -1382,9 +1515,28 @@ export function buyTool(options) {
             cardAfterSignIn = null;
             return { local: stepResult({ ...standing, status: 'needs_card', reply: CARD_AFTER_SIGN_IN, links: [{ kind: 'vault', url: link.url, expiresAt: link.expiresAt }], next_action: 'add_card' }) };
         }
-        if (carriedYes && one && conversationId && one.hash === carriedYes.hash) {
+        // The shopper's yes goes on past the step they just finished: the same items at the same store, in the same purchase,
+        // confirmed by the cart's hash as it stands now. A total that moved because the store priced its fees and tax in keeps
+        // the yes, and the answer says the new total beside the next ask; the approval link is still the shopper's consent to
+        // the payment (Karen, 2026-10-27).
+        const yes = carriedYes;
+        const inPurchase = (at) => at === null || at === conversationId;
+        if (yes && one && conversationId && inPurchase(yes.conversationId) && sameOrder(one, yes.cart)) {
             carriedYes = null;
-            return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who } };
+            return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who }, yes: { ...yes, cart: one, conversationId } };
+        }
+        // The shopper picked what is in the cart and finished the step outside the chat: finishing it is their go-ahead for the
+        // same order, confirmed by the cart's hash as it stands now, and the approval link stays their consent to the payment
+        // (Karen, 2026-10-27: "we are again asking for confirmation after user adds a card. we should assume they want to move
+        // forward"). That holds whatever the shopper's Vault does: the approval link is the approval (Karen, 2026-10-27: "That
+        // is the goal of the approval link. You shouldn't be asking again. Take the approval from the approval link as the
+        // approval.").
+        const picked = pickedOrder;
+        if (picked?.cart && one && conversationId && inPurchase(picked.conversationId) && (event.kind === 'card_added' || event.kind === 'store_connected')) {
+            pickedOrder = null;
+            if (sameOrder(one, picked.cart)) {
+                return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who }, yes: { conversationId, cart: one, totalCents: picked.cart.totalCents, picked: true } };
+            }
         }
         // A checkout the shopper already moved past their yes (an approval link waiting, or the order going through) is reported as
         // it stands: the cart stays while it waits, and asking for another yes would contradict the link they have (review of #9220).
@@ -1441,13 +1593,22 @@ export function buyTool(options) {
             ...(client.company ? { external_user_id: externalUserId } : {}),
         };
         // The cart a confirm sent now confirms, for the yes it carries past a step outside the chat.
-        const yesHash = confirm ? lastShownHash : null;
+        const yesShown = confirm ? lastShownCart : null;
+        // A pick of what the shopper saw, by a product's id or its name, or a request to buy something: when its answer carts
+        // it, the shopper's go-ahead for that cart (`notePick`). Read before the answer replaces what the shopper saw.
+        const picksShown = !confirm && (!!pick?.product_id || pickOf(ask) !== null || isProductAsk(ask));
+        const cartBefore = lastShownCart;
+        const pickWithdrawalsAtStart = pickWithdrawals;
+        const askedBefore = { nextAction: lastNextAction, reply: lastReply };
         // The first call after `instantAck` opens the turn of the message it answered, whose reply is the
         // app's. Any other call that starts while another runs, or right after one ended, is the model
         // working through the same turn. A call made through `buy.turn` belongs to that turn alone.
+        // Whether a turn read the shopper's message (`withdrawUnlessGoAhead`): `buy.turn`, or the app's instant reply.
+        let heard = !!explicit;
         if (!explicit) {
             const opened = appAck && Date.now() - appAck.at < APP_TURN_MS ? appAck : null;
             appAck = null;
+            heard = !!opened;
             if (opened) {
                 // Only a reply the app sent quiets onWorking. A message such as `yes` that starts a slow search
                 // still gets a reply that names nothing, and a slow pick gets one that says it is on it.
@@ -1476,6 +1637,8 @@ export function buyTool(options) {
         // A confirm or a pick of what the shopper saw never hears "looking for": once the call is slow, it hears a
         // fixed line that names nothing they said (slowStepLine), so a 20-second checkout or menu read is never silent.
         const ack = t.event ? null : holdAck(ask, t, confirm ? 'confirm' : pick?.product_id ? 'product' : pick ? 'pick' : null);
+        /** Says `unknown` of every card the call left `checking`; it runs once the answer's cards went out, or when the call fails. */
+        let settleLeft = null;
         try {
             let turn = null;
             let refusal;
@@ -1486,11 +1649,68 @@ export function buyTool(options) {
              * and every message after it, so the shopper reads them in the order Agentcard wrote them.
              */
             const waiting = [];
+            /** True when the last message the shopper read ended in a colon or a question mark, so choices that open the next one are its list. */
+            let leadIn = false;
+            /** Shows one of Agentcard's messages through onText, its lists as bullets (messageForShopper); `told` keeps it as Agentcard wrote it. */
+            const showText = async (text, conversationId) => {
+                await t.onText(messageForShopper(text, leadIn, t.texting), { conversationId });
+                leadIn = leadsIntoList(text);
+                told.push(text);
+            };
             /** The products past the cards of the catalog this call heard last, for the count that follows it. */
             let moreFound = null;
             /** Whether this call's cards went out, and a count that came before them. */
             let cardsOut = false;
             let heldCount = null;
+            /** The card each catalog id of this call went out as (its `productId`), and the cards still `checking`, by conversation. */
+            const cardOfId = new Map();
+            const checking = new Map();
+            /**
+             * What the live search answered for each card, so a later copy of the same place, such as a card whose first send
+             * failed and goes out again with the answer, carries that answer and never goes back to `checking`.
+             */
+            const answered = new Map();
+            const withAnswers = (products) => answered.size === 0 ? products : products.map((product) => {
+                const known = product.availability ? answered.get(pickId(product) ?? '') : undefined;
+                return known ? { ...product, availability: known } : product;
+            });
+            /**
+             * Notes the card each product goes out as, and each place still `checking`, whichever way the app got it: a card
+             * through `sendLink` now or on a later try, or a product past the cards that `onFound` hands over for "show more".
+             */
+            const noteCards = (products, conversationId) => {
+                for (const product of products) {
+                    const productId = pickId(product);
+                    if (!productId)
+                        continue;
+                    cardOfId.set(product.id, productId);
+                    if (product.availability?.status === 'checking' && !answered.has(productId))
+                        checking.set(productId, conversationId);
+                }
+            };
+            /** Hands the app what the live search said of the places, each by its card, and settles those cards. */
+            settleLeft = async () => {
+                if (!t.onAvailability || !early)
+                    return;
+                const left = [...checking];
+                for (const conversationId of new Set(left.map(([, c]) => c))) {
+                    await tellAvailability(conversationId, left.filter(([, c]) => c === conversationId).map(([productId]) => ({ productId, availability: { status: 'unknown' } })));
+                }
+            };
+            const tellAvailability = async (conversationId, items) => {
+                for (const item of items) {
+                    checking.delete(item.productId);
+                    answered.set(item.productId, item.availability);
+                }
+                if (!t.onAvailability || items.length === 0)
+                    return;
+                try {
+                    await t.onAvailability({ conversationId, items });
+                }
+                catch {
+                    // The app's display failing never fails the call.
+                }
+            };
             /** Hands the app one count with the products past the cards of the catalog it counts. */
             const tellCount = async ({ conversationId, shown, found }) => {
                 const more = moreFound?.conversationId === conversationId ? moreFound.links : [];
@@ -1546,7 +1766,9 @@ export function buyTool(options) {
                                 ack?.cancel();
                                 await t.ackOut;
                                 // The turn's own search presents its products, as a reply that lists them does.
-                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, productsOfCatalog(update.catalog)), { turn: callTurn, presented: true, owner: t }, send);
+                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                // A place shown `checking`, on a card or behind "show more", waits for the live search's word on it.
+                                noteCards([...productsOfCatalog(update.catalog), ...productsOfCatalog({ ...update.catalog, items: update.more })], update.conversationId);
                                 keepMore();
                                 cardsOut = true;
                                 // A count held for these cards goes out now, unless the catalog carries its own, which follows it.
@@ -1557,6 +1779,13 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
+                    ...(t.onAvailability && early
+                        ? {
+                            onAvailability: async ({ conversationId, items }) => {
+                                await tellAvailability(conversationId, items.map(({ id, availability }) => ({ productId: cardOfId.get(id) ?? id, availability })));
+                            },
+                        }
+                        : {}),
                     ...(t.onText
                         ? {
                             onSegment: async ({ text, conversationId }) => {
@@ -1569,8 +1798,7 @@ export function buyTool(options) {
                                     return;
                                 }
                                 try {
-                                    await t.onText(text, { conversationId });
-                                    told.push(text);
+                                    await showText(text, conversationId);
                                 }
                                 catch {
                                     // A message the app failed to show was never read, so the model words the answer.
@@ -1633,8 +1861,7 @@ export function buyTool(options) {
                         continue;
                     }
                     try {
-                        await t.onText(message.text, { conversationId: message.conversationId });
-                        told.push(message.text);
+                        await showText(message.text, message.conversationId);
                     }
                     catch {
                         // A message the app failed to show was never read, so the model words the answer.
@@ -1643,8 +1870,7 @@ export function buyTool(options) {
                 const stepAsk = turn?.next_action ? CHAT_STEP_ASKS[turn.next_action] : undefined;
                 if (replaced && stepAsk && settled.reply.endsWith(stepAsk)) {
                     try {
-                        await t.onText(stepAsk, { conversationId: settled.conversation_id });
-                        told.push(stepAsk);
+                        await showText(stepAsk, settled.conversation_id);
                     }
                     catch {
                         // Not shown, so the model asks for the step.
@@ -1653,22 +1879,50 @@ export function buyTool(options) {
             }
             // Every message of Agentcard's own answer reached the shopper through onText, so the model adds nothing to it. An answer
             // whose card ask gave way to the named step was read the same way once every message of it, that ask last, went out.
-            const read = !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, toMessages(settled.reply)));
-            const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
+            // A reply the shopper read that asks them to choose, with the values named inside a sentence or not at all, is followed
+            // by one more message that lists every value on its own line (choiceLines), so no choice is read buried in prose.
+            let choiceShown = true;
+            if (t.onText && turn?.choice && told.length > 0 && !messagesListChoice(told, turn.choice)) {
+                const lines = choiceLines(turn.choice);
+                try {
+                    await t.onText(t.texting ? textingStyle(lines) : lines, { conversationId: turn.conversation_id || null });
+                }
+                catch {
+                    // Not shown, so the shopper has not read the whole answer: the model words it, with the choice it reads.
+                    choiceShown = false;
+                }
+            }
+            const read = choiceShown && !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, toMessages(settled.reply)));
+            const answer = withMessages(settled, turn);
+            const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
             // A count that came before any card (find mode puts its cards in the answer) goes out once the answer's cards did.
             if (heldCount && (delivered.products?.length ?? 0) > 0) {
                 const held = heldCount;
                 heldCount = null;
                 await tellCount(held);
             }
+            // A call that ends with cards still `checking`, the answer's own cards included, says `unknown` of each, so none waits
+            // for an answer that is not coming.
+            if (delivered.conversation_id)
+                noteCards(delivered.products ?? [], delivered.conversation_id);
+            await settleLeft();
             // The message that asks for a step link already went out, so the link follows it now instead of waiting for the model's.
             // The call waits for it, and one that fails to send fails the call, as a step link the turn does not hold does.
             if (read)
                 await t.releaseNow?.();
+            // A confirm the turn sent on the shopper's earlier yes names the total they said yes to beside the cart's total now. A
+            // confirm Agentcard refused, or one whose answer holds another order or asks for a yes, carried nothing: the model asks.
+            const carried = plan && 'body' in plan && plan.yes && turn && delivered.next_action !== 'confirm' ? plan.yes : null;
+            const nowCart = !carried ? null : !delivered.cart ? carried.cart : sameOrder(delivered.cart, carried.cart) ? delivered.cart : null;
+            const yesCarried = carried && nowCart
+                ? { said_yes_to_cents: carried.totalCents, total_cents: nowCart.totalCents, currency: nowCart.currency ?? null, ...(carried.picked ? { picked: true } : {}) }
+                : null;
             const result = {
                 ...delivered,
                 ...(t.ackDelivered ? { shopper_already_told_looking: true } : {}),
                 ...(read ? { shopper_already_read_reply: true } : {}),
+                ...(confirmSent ? { confirm_sent: true } : {}),
+                ...(yesCarried ? { yes_carried: yesCarried } : {}),
             };
             lastNextAction = result.next_action;
             lastReply = result.reply;
@@ -1681,12 +1935,19 @@ export function buyTool(options) {
             if (result.conversation_id)
                 lastConversationId = result.conversation_id;
             if (result.cart?.hash)
-                lastShownHash = result.cart.hash;
+                lastShownCart = result.cart;
             // A shopper's own call, or the shopper's yes or words a turn taken on its own sent, leaves what the next step needs.
             if (!t.event)
-                noteShopperStep(result, turn, { confirm: !!confirm, yesHash, ask, withdrawalsAtStart });
+                noteShopperStep(result, turn, { confirm: !!confirm, yes: { shown: yesShown }, ask, withdrawalsAtStart });
             else if (plan && 'body' in plan)
-                noteShopperStep(result, turn, { confirm: confirmSent, yesHash: typeof sent.confirm === 'string' ? sent.confirm : null, ask: sent.ask ?? '', withdrawalsAtStart });
+                noteShopperStep(result, turn, { confirm: confirmSent && !!plan.yes, yes: plan.yes ? { carried: plan.yes } : { shown: null }, ask: sent.ask ?? '', withdrawalsAtStart });
+            if (!t.event && turn) {
+                // Words that name something to buy and put a new item in the cart picked it too, as `the chicken pesto caprese from
+                // mendocino farms` carts the dish it names.
+                const added = result.pick?.in_cart === true || addsItem(result.cart, cartBefore);
+                const picking = !confirm && (picksShown || result.pick?.in_cart === true || (isNewRequest(ask) && added));
+                notePick(result, { picking, added, confirm: !!confirm, ask, heard, asked: askedBefore, pickWithdrawalsAtStart });
+            }
             // An answer that lists products replaces the names, even when every one is too short to keep.
             const shown = shownProducts(result.products);
             if (shown.length > 0)
@@ -1709,6 +1970,8 @@ export function buyTool(options) {
             return result;
         }
         finally {
+            // A call that fails, Agentcard's error or a thrown handler, still settles the cards it left `checking`.
+            await settleLeft?.().catch(() => { });
             ack?.cancel();
             running -= 1;
             lastEndedAt = Date.now();
@@ -1782,7 +2045,7 @@ export function buyTool(options) {
         const own = options ?? {};
         if (typeof own !== 'object')
             throw new TypeError('Pass the turn options as an object, or leave them out.');
-        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -1797,6 +2060,9 @@ export function buyTool(options) {
         if (own.replyAsWritten !== undefined && typeof own.replyAsWritten !== 'boolean')
             throw new TypeError('Pass replyAsWritten to the turn as true or false, or leave it out.');
         const written = own.replyAsWritten ?? writtenByDefault;
+        if (own.textingStyle !== undefined && typeof own.textingStyle !== 'boolean')
+            throw new TypeError('Pass textingStyle to the turn as true or false, or leave it out.');
+        const texting = own.textingStyle ?? textingByDefault;
         const hearText = own.onText ?? o.onText;
         // Messages are spaced only for an app that hears each one as it goes out.
         const pauseOf = paceOf(own.pace);
@@ -1861,10 +2127,12 @@ export function buyTool(options) {
             onProgress: own.onProgress ?? onProgress,
             onStatus: own.onStatus ?? o.onStatus,
             onFound: own.onFound ?? o.onFound,
+            onAvailability: own.onAvailability ?? o.onAvailability,
             onProducts: own.onProducts ?? o.onProducts,
             // Agentcard's message takes its place in the turn's sequence, after the items before it, and goes to onText alone, so
             // an app that passes onItem too hears it once.
             onText: hearText ? (text, info) => feed.push({ kind: 'text', text }, () => hearText(text, info)) : undefined,
+            texting,
             onCart: own.onCart ?? o.onCart,
             tell: onItem || baseOnWorking ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
             links: [],
@@ -1933,9 +2201,13 @@ export function buyTool(options) {
         const results = state.results;
         // A pick or an answer goes straight only after a turn that ended on Agentcard's answer, and never while a call still runs.
         const answered = previousTurn !== null && (previousTurn.results?.length ?? 0) > 0;
-        const direct = directOn && !event && running === 0
-            ? directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, stores: lastAnswerStores })
-            : null;
+        // A `nextStep` turn's call is the same whatever the model writes (`stepPlan` reads where the purchase stands), so it goes
+        // straight too: with `replyAsWritten`, a step whose answer is a link, such as the approval after a saved card, needs no model.
+        const direct = !directOn || running > 0
+            ? null
+            : event
+                ? { input: { ask: NEXT_STEP_ASK, confirm: false, new_order: false, product_id: null, store_id: null }, reason: 'next_step' }
+                : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, stores: lastAnswerStores });
         if (!event)
             previousTurn = state;
         // What Agentcard told the shopper that no history the model ran with holds yet.
@@ -1996,7 +2268,7 @@ export function buyTool(options) {
             links: { get: () => [...links], enumerable: false },
             results: { get: () => [...results], enumerable: false },
             direct: { value: direct, enumerable: false },
-            replyAsWritten: { get: () => (written && results.length > 0 ? replyAsWritten(results[results.length - 1]) : null), enumerable: false },
+            replyAsWritten: { get: () => (written && results.length > 0 ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
             items: { get: () => feed.items.map((item) => (item.kind === 'link' ? { kind: 'link', link: { ...item.link } } : { ...item })), enumerable: false },
             // Each message joins the feed the moment it is cut, so a link the tool hands over during a pause never overtakes text already written.
             // A step link held for this message goes out right after its last paragraph, once the stream ends.