@agent-cards/commerce-sdk 0.15.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.';
@@ -264,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,
     };
 }
@@ -689,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;
@@ -749,6 +818,7 @@ export function buyTool(options) {
         onAvailability: o.onAvailability,
         onProducts: o.onProducts,
         onText: o.onText,
+        texting: textingByDefault,
         onCart: o.onCart,
         links: null,
         results: null,
@@ -781,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. */
@@ -834,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;
@@ -1322,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')
@@ -1330,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: [],
@@ -1371,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) {
@@ -1384,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).
@@ -1443,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.
@@ -1490,6 +1649,14 @@ 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. */
@@ -1631,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.
@@ -1695,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.
@@ -1705,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.
@@ -1715,7 +1879,20 @@ 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)));
+            // 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.
@@ -1733,10 +1910,19 @@ export function buyTool(options) {
             // 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;
@@ -1749,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)
@@ -1867,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);
@@ -1936,6 +2132,7 @@ export function buyTool(options) {
             // 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: [],
@@ -2004,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.
@@ -2067,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.

package/dist/client.d.ts

@@ -373,6 +373,32 @@ export interface BuyStorePick {
     name: string | null;
     selected: boolean;
 }
+/** One value the shopper picks from. `id` is the option id the cart takes, null when the shopper's words answer it. */
+export interface BuyChoiceOption {
+    id: string | null;
+    label: string;
+    /** What choosing it adds to the price, in cents: 0 when free, null when the store does not say. */
+    price_delta_cents: number | null;
+}
+/** One group of values, such as a sandwich's bread or a shirt's size. `min` and `max` count the values picked; `max` null for no limit. */
+export interface BuyChoiceGroup {
+    name: string;
+    required: boolean;
+    min: number;
+    max: number | null;
+    options: BuyChoiceOption[];
+}
+/**
+ * The choice an answer's reply asks the shopper to make, as data: the question, the item it is about, where the values come
+ * from (`menu_item`: a restaurant item's options, `store_checkout`: a store's own size or colour question, `catalog_variant`:
+ * a product's sizes or colours in stock), and every group with its values.
+ */
+export interface BuyChoice {
+    question: string | null;
+    item: string | null;
+    source: string;
+    groups: BuyChoiceGroup[];
+}
 export interface BuyPaymentSource {
     source: string;
     brand: string | null;
@@ -435,6 +461,8 @@ export interface BuyTurn {
     store_pick: BuyStorePick | null;
     /** The cart the store's checkout is still building after this answer; null when none is, and on an older API. */
     cart_building: BuyCartBuilding | null;
+    /** The choice the reply asks the shopper to make, each group with every value; null when it asks none, and on an older API. */
+    choice: BuyChoice | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -506,6 +534,8 @@ export declare class AgentcardApiError extends Error {
 }
 /** A turn as Agentcard answers it. */
 export declare function turnOf(body: Record<string, unknown>): BuyTurn;
+/** An answer's `choice`, its groups with at least one value each, or null when it carries none. */
+export declare function choiceOf(value: unknown): BuyChoice | null;
 /** A cart being built, as an answer, a refusal or the conversation read names it. */
 export declare function cartBuildingOf(value: unknown): BuyCartBuilding | null;
 /** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */

package/dist/client.js

@@ -299,9 +299,20 @@ export function turnOf(body) {
         stores: storesOf(body.stores),
         store_pick: isRecord(body.store_pick) && str(body.store_pick.store_id) ? { store_id: body.store_pick.store_id, name: str(body.store_pick.name), selected: body.store_pick.selected === true } : null,
         cart_building: cartBuildingOf(body.cart_building),
+        choice: choiceOf(body.choice),
         raw: body,
     };
 }
+/** An answer's `choice`, its groups with at least one value each, or null when it carries none. */
+export function choiceOf(value) {
+    if (!isRecord(value) || !Array.isArray(value.groups))
+        return null;
+    const groups = value.groups.filter(isRecord).flatMap((g) => {
+        const options = (Array.isArray(g.options) ? g.options : []).filter(isRecord).flatMap((o) => str(o.label) ? [{ id: str(o.id), label: o.label.trim(), price_delta_cents: num(o.price_delta_cents) }] : []);
+        return options.length ? [{ name: str(g.name) ?? '', required: g.required === true, min: num(g.min) ?? 0, max: num(g.max), options }] : [];
+    });
+    return groups.length ? { question: str(value.question), item: str(value.item), source: str(value.source) ?? '', groups } : null;
+}
 /** A cart being built, as an answer, a refusal or the conversation read names it. */
 export function cartBuildingOf(value) {
     return isRecord(value) && str(value.store) ? { store: value.store, started_at: str(value.started_at) ?? '' } : null;

package/dist/definition.js

@@ -42,6 +42,7 @@ export const BUY_TOOL_DESCRIPTION = [
     "Talk to the shopper only about their order, in their terms: what is in the cart, what was found and what they can do next. Leave out how it was done, even when `reply` says it: never mention this tool, `reply`, a field, a system, \"my end\" or what you can or can't see, the searches run, the stores checked or not, a timeout, account setup, or a link that did not go out. When parts of the result disagree, say what you are sure of and ask, never which part said what.",
     'Never tell the shopper what has not happened yet or where things stand inside, such as "nothing\'s been charged yet", "your order isn\'t placed yet" or "the address isn\'t locked in", even when `reply` says it: ask for what is needed instead, such as "should it ship to 1 ferry plz?".',
     'When `next_action` is `store_login`, `add_card` or `approve`, the message that asks for it is one short line and nothing else, even when `reply` says more, such as "sign in to doordash to place your order", "add your card to place the order" or "approve the payment to place your order (up to $19.02)": no recap of the cart, the address or the price, nothing about tax, delivery, shipping, a hold or what was charged, no word on when the link runs out, and never a request to tell you once it is done. On `approve`, put the cart\'s `max_charge` in the parentheses when it is set, and no other amount. Only when the shopper\'s last message picked what went in the cart does a line about the cart come first, as its own message; after an address, a phone number, a yes or a saved card, the ask is the whole reply.',
+    'When `yes_carried` is set, the shopper already said yes to this cart, or picked it (`yes_carried.picked`), and Agentcard went ahead on it once they finished the step outside the chat, so never ask for their yes again: ask only for the step `next_action` names. When `yes_carried.total_changed` is true, that one short line opens with the new total, the one price it names beside `max_charge`, such as "it\'s $17.89 with fees and tax now. approve the payment to place your order (up to $19.02)".',
     'When `next_action` is `confirm`, ask in one short message: the items, one total, and to say yes to place it, such as "1 carolina black socks pack from walmart, about $9.57. say yes to place it". Leave out the fees one by one, the hold, and the address unless the shopper just changed it.',
     'Every line you write reaches the shopper, a line before you call this tool too: write to them as "you", never about "the shopper" or "the user", and never say what you are about to do with this tool, such as "I\'ll add them now".',
     'Say as fact only what the result shows: never promise what a store will do later, such as confirm a size when the order goes through.',
@@ -52,6 +53,7 @@ export const BUY_TOOL_DESCRIPTION = [
     "When the shopper asks what you can do or which stores you shop at, answer without calling this tool and with no line saying you are looking: one message that names at most four stores plus the kinds of things you can do, such as food delivery and restaurant reservations, then one that asks what they need. Every shopper can buy from Amazon, Walmart, Target and Best Buy, so name those, and no other store unless a result showed it.",
     'Each paragraph you write reaches the shopper as its own message: give each one job and keep it under about 20 words. On a cart turn, write the confirmation and the one next step, such as "added a little cheeseburger from five guys, about $12.17 before delivery and tax" and then "next, sign in to doordash with the link so i can place it": one total, never a price breakdown your app\'s cart already shows (an app that shows no cart lists each line with its price) and never a fee by its name, rate or formula, such as an order fee, card processing or 2.9% + $0.30, even when `reply` or `fee_lines` names it, unless the shopper asks what the fees are, no promise to show the final total later, and nothing about passkeys, master passwords or Agentcard not seeing the card number unless the shopper asks.',
     'Never listing products again is for offering choices: when you confirm what is in the cart, name each line by its item, such as "1 Dawn Ultra dish soap, 38 oz", never "the one you picked, shown in the card".',
+    'When you list options or choices for the shopper, such as sizes, breads, times, or stores no card shows, write one per line, each starting with "• ", in the same paragraph as the line that asks which one, so the question and its choices reach the shopper as one message. When the result has `choice`, list every value it holds that way, with its extra price, such as "• Gluten-free bread (+$2.46)", even when `reply` names them inside a sentence. The products and stores the cards show are still never listed again.',
     'Say how long a link works only when the shopper asks, with `link_expires_in`, such as "it works for about 24 hours", never as a raw date and time or in UTC, such as `approval_expires_at` holds; when `link_expires_in` is null, say nothing about when it runs out.',
     'Never call a product the shopper was sent "the card", in any language ("la tarjeta", "o cartão"): to the shopper a card is how they pay. Call it by its name, or "the one i sent".',
     'When the cart has `total_leaves_out`, its `total` is before those: say so, such as "about $18.41 before tax and shipping", and never say it is with or includes tax, shipping or delivery.',

package/dist/direct.d.ts

@@ -1,7 +1,10 @@
 import type { BuyNextAction } from './client.js';
 import type { BuyToolInput } from './definition.js';
-/** Why a message goes straight to Agentcard. */
-export type DirectReason = 'product_ask' | 'pick' | 'answer' | 'confirm';
+/**
+ * Why a message goes straight to Agentcard. `next_step` is a turn `buy.nextStep` opened: its call reads where the
+ * purchase stands and goes on from there whatever the model would write, so it never needs the model to decide it.
+ */
+export type DirectReason = 'product_ask' | 'pick' | 'answer' | 'confirm' | 'next_step';
 /** The buy call for a message that goes straight to Agentcard, and why it does. */
 export interface DirectCall {
     input: BuyToolInput;

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatureReason, type AgentcardEvent, type VerifyOptions, } from './verify.js';
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
+export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.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 BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, } 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 BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyChoiceGroup, 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, forModelError, replyAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
+export { forModel, forModelError, stepAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
+export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice, type ReplyAsWrittenOptions } from './texting.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, } from './verify.js';
 export { readPurchaseMessage, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, } from './shopper-message.js';
+export { ORDER_STEPS, updateOrder, arrivalText, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
@@ -8,7 +9,8 @@ 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, forModelError, replyAsWritten, withoutCardList, stripLinks, } from './model-view.js';
+export { forModel, forModelError, stepAsWritten, withoutCardList, stripLinks, } from './model-view.js';
+export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice } from './texting.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';

package/dist/messages.js

@@ -6,14 +6,14 @@
  */
 /** A line holding nothing but spaces or tabs. */
 const BLANK = /^[ \t]*$/;
-/** A list item: `-`, `*` or `+`, or a number followed by `.` or `)`, then a space or the line's end. */
-const LIST_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)])(?:[ \t]|$)/;
+/** A list item: `-`, `*`, `+` or the bullet `•`, or a number followed by `.` or `)`, then a space or the line's end. */
+const LIST_ITEM = /^ {0,3}(?:[-*+•]|\d{1,9}[.)])(?:[ \t]|$)/;
 /** A list item whose marker a space already follows, the only kind a line still being written is sure to stay. */
-const LIST_ITEM_SPACED = /^ {0,3}(?:[-*+]|\d{1,9}[.)])[ \t]/;
+const LIST_ITEM_SPACED = /^ {0,3}(?:[-*+•]|\d{1,9}[.)])[ \t]/;
 /** A line indented under a list item: two spaces or a tab, then text. */
 const INDENTED = /^(?: {2,}|\t)\S/;
 /** The start of a line that can still grow into a list item or an indented line once more text arrives. */
-const MAYBE_ITEM = /^ {0,3}(?:[-*+]|\d{1,9}[.)]?)?$|^[ \t]*$/;
+const MAYBE_ITEM = /^ {0,3}(?:[-*+•]|\d{1,9}[.)]?)?$|^[ \t]*$/;
 /** A code fence: three or more backticks or tildes, indented by at most three spaces. */
 const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 /** How the line after a blank line inside a list reads: it continues the list, it ends it, or it is too short to tell. */