@agent-cards/commerce-sdk 0.10.0 → 0.13.0

package/dist/buy-tool.js

@@ -31,11 +31,19 @@
  * messages and links as one sequence, in the order they happened, and spaces
  * the messages like someone texting.
  */
-import { AgentcardApiError, AgentcardClient, } from './client.js';
+import { AgentcardApiError, AgentcardClient, cartBuildingOf, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
-import { forModel, forModelError, money, pickId, productCardKey, shownProducts, shownStores, stripLinks } from './model-view.js';
+import { forModel, forModelError, pickId, productPrice, productCardKey, replyAsWritten, shownProducts, shownStores, stripLinks } from './model-view.js';
 import { messageStream, paceOf, sleep, toMessages, typingHook } from './messages.js';
-import { ackAt, answersQuestion, instantAck as instantAckOf, isNewRequest, isPickText, namesStore, nextTemplate, slowStepLine, waitAt } from './ack.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';
+/** The action a product of `merchant` takes (BuyToolProductAction). */
+export function productAction(merchant) {
+    if (merchant === 'reservations')
+        return 'reserve';
+    return merchant === 'flights' || merchant === 'hotels' || merchant === 'tickets' || merchant === 'classes' ? 'book' : 'buy';
+}
 const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * The model's messages for a turn: the history, what Agentcard told the shopper, then the shopper's
@@ -112,7 +120,18 @@ function productWords(text) {
 }
 /** How long after `instantAck` the model's first call still belongs to the turn it acknowledged. */
 const APP_TURN_MS = 120_000;
+/** The links that ask the shopper to take a step: they go out after the message that asks for it. */
+const STEP_LINK_KINDS = new Set(['vault', 'approval', 'store_login']);
+/** The longest a step link waits for its message: an app that never writes one still sends the link. */
+const STEP_LINK_HOLD_MS = 20_000;
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
+const STILL_BUILDING = "The store is still building the cart for the shopper's last request. Its cart and total reach the shopper in a message from Agentcard: once that message has arrived, call this tool again with the shopper's words.";
+const CART_NOT_READY = 'The store is still building the cart, so it has no total yet, and nothing was confirmed. Its cart and total reach the shopper in a message from Agentcard: confirm it only after the shopper says yes to that total.';
+/** What the shopper hears while their message waits for the cart the store is still building. */
+const stillBuildingLine = (store) => `still building your cart at ${store}, i'll get to this as soon as it's in`;
+/** How often, and how many times, a message held for a cart being built reads whether the cart is in. */
+const CART_HOLD_EVERY_MS = 2_000;
+const CART_HOLD_READS = 45;
 const CARD_NEEDED = 'The shopper adds a card from a Vault link before Agentcard can buy for them.';
 const STILL_PLACING = 'The shopper approved, and the order is still going through.';
 const NOT_PLACED = 'The order did not go through.';
@@ -125,6 +144,40 @@ 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.";
+/** 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.';
+const CARD_AFTER_SIGN_IN = 'The shopper is signed in to the store. A card is the next step: ask them to add one from the link.';
+const NO_CART_WAITING = 'No cart is waiting. Carry on with what the shopper last asked for, in one short message.';
+const STEP_APPROVAL_WAITING = 'The shopper already has the link to approve this payment, and nothing was charged yet. Ask for nothing else: in one short line, remind them to approve it from the link they have.';
+const STEP_PLACEMENT_RUNNING = 'The order is going through now. Ask for nothing: say in one short line that it is being placed and that you will tell them once it is.';
+/** What the shopper just did outside the chat, for the line that opens a `nextStep` turn. */
+function stepDone(message) {
+    const store = message.facts.merchantName;
+    switch (message.kind) {
+        case 'card_added':
+            return 'The shopper just saved a card outside the chat.';
+        case 'store_connected':
+            return `The shopper just signed in to ${store ?? 'the store'} outside the chat.`;
+        case 'approval_declined':
+            return `The shopper just declined the approval${store ? ` for the ${store} order` : ''} outside the chat. Nothing was charged and no order was placed.`;
+        default:
+            return 'The shopper just finished a step outside the chat.';
+    }
+}
+/**
+ * The words a `nextStep` turn hands the model as the user's message: the event, marked as no one's
+ * typing, and the instruction to take the next step now in one short message, without the filler of
+ * a step announced and a question about what comes next.
+ */
+export function nextStepPrompt(message) {
+    const note = String(message.note ?? '').trim();
+    return [
+        note || `[event: ${stepDone(message)} This note was generated by the system, not typed by the user.]`,
+        `${stepDone(message)} The shopper has not written anything since: this turn starts on its own. Take the next step now, as your next message to them. Call the buy tool once, with ask "next step", and do what its answer says, in one short message.`,
+        "Don't tell them they're all set or ready, and don't ask what's next. Never say an order is placed or a card charged unless the buy tool's answer says so.",
+    ].join('\n\n');
+}
 /**
  * The pick as a later read of the conversation shows it: a pick the early answer found missing is in
  * the cart once a line carries its catalog id, as its product id or, for a retail product whose id is
@@ -152,11 +205,14 @@ function productsOfCatalog(catalog) {
         ref: item.ref,
         name: item.name,
         priceCents: item.priceCents,
+        ...(item.price_from ? { priceFrom: true } : {}),
         currency: item.currency,
         imageUrl: item.image_url,
+        images: item.image_urls ?? (item.image_url ? [item.image_url] : []),
         ...(item.flight ? { flight: item.flight } : {}),
         store: item.store?.name ?? item.store?.id ?? catalog.merchant_name ?? null,
         url: item.url ?? null,
+        action: productAction(catalog.merchant),
         linkSent: false,
     }));
 }
@@ -170,6 +226,14 @@ function storeLoginOf(turn) {
         return [];
     return [{ kind: 'store_login', url: turn.store_login_url, expiresAt: turn.store_login_expires_at, store: turn.store_login_merchant_name }];
 }
+/**
+ * The approval link for a cart, naming the cart's store in `store` when the answer names one, so a
+ * message about another store's cart never ends this approval (`actionLinkOutcome`).
+ */
+function approvalLink(url, expiresAt, cart) {
+    const store = cart?.merchant_name;
+    return { kind: 'approval', url, expiresAt, ...(store ? { store } : {}) };
+}
 /** The answer before its status is read: every field the purchase answer carries. */
 function answerOf(turn) {
     return {
@@ -192,6 +256,7 @@ function answerOf(turn) {
         stores: storesOf(turn.stores),
         store_pick: turn.store_pick,
         hashes: hashesOf(turn.cart, turn.carts),
+        cart_building: turn.cart_building,
         envelope: turn.raw,
     };
 }
@@ -259,7 +324,7 @@ function resultOfStatus(turn) {
                 return {
                     ...answer,
                     status: 'approval_sent',
-                    links: [...answer.links, ...(turn.approval_url ? [{ kind: 'approval', url: turn.approval_url, expiresAt: turn.approval_expires_at }] : [])],
+                    links: [...answer.links, ...(turn.approval_url ? [approvalLink(turn.approval_url, turn.approval_expires_at, turn.cart)] : [])],
                     shopper_need_not_reply: turn.placement_announced === true,
                 };
             }
@@ -292,16 +357,19 @@ function resultOfRefusal(error) {
         stores: [],
         store_pick: null,
         hashes: hashesOf(null, carts),
+        cart_building: cartBuildingOf(error.body.cart_building),
         envelope: error.body,
     });
     if (error.code.startsWith('delivery_address'))
         return answer(ADDRESS_CHANGED, []);
+    if (error.code === 'cart_not_ready')
+        return answer(CART_NOT_READY, []);
     if (error.code === 'cart_changed')
         return answer(CART_CHANGED, error.carts);
     if (error.code === 'nothing_to_confirm' || error.code === 'conversation_closed')
         return answer(NOTHING_TO_CONFIRM, []);
     if (error.code === 'turn_in_progress')
-        return answer(STILL_WORKING, []);
+        return answer(cartBuildingOf(error.body.cart_building) ? STILL_BUILDING : STILL_WORKING, []);
     if (error.code === 'pick_not_found')
         return answer(PICK_GONE, []);
     if (error.code === 'store_pick_not_found')
@@ -435,15 +503,29 @@ function feedReply(text) {
     };
     return { add, settled };
 }
-/** A message stream for a turn's feed: the messages it cuts are one reply, `feedReply`'s. */
-function feedStream(text) {
+/**
+ * A message stream for a turn's feed: the messages it cuts are one reply, `feedReply`'s. `ended` runs
+ * once the last message is cut and has its place in the feed, before it went out, so what it adds
+ * follows the reply. `end` settles once the reply and what `ended` added went out, and rejects with
+ * the first failure.
+ */
+function feedStream(text, ended) {
     const reply = feedReply(text);
     const inner = messageStream({ onMessage: reply.add, pace: false });
     return {
         push: (delta) => inner.push(delta),
         end: async () => {
-            await inner.end();
+            let added = Promise.resolve();
+            try {
+                await inner.end();
+            }
+            finally {
+                added = ended();
+                // Read below, after the reply: a failure here is never left unhandled while the reply settles.
+                added.catch(() => { });
+            }
             await reply.settled();
+            await added;
         },
     };
 }
@@ -529,19 +611,40 @@ export function buyTool(options) {
         throw new TypeError('Pass onResult as a function that takes each answer.');
     }
     const onResult = o.onResult;
+    if (o.replyAsWritten !== undefined && typeof o.replyAsWritten !== 'boolean')
+        throw new TypeError('Pass replyAsWritten as true or false.');
+    const writtenByDefault = o.replyAsWritten === true;
     const wait = o.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     if (typeof wait !== 'function')
         throw new TypeError('Pass wait as a function of milliseconds that resolves after the pause.');
     const who = client.company ? { externalUserId } : {};
     if (o.onWorking !== undefined && typeof o.onWorking !== 'function')
         throw new TypeError('Pass onWorking as a function that sends the shopper a message.');
-    if (o.ack !== undefined && o.ack !== false && typeof o.ack !== 'function')
-        throw new TypeError('Pass ack as false, or as a function that writes the instant reply from the ask.');
+    if (o.onReaction !== undefined && typeof o.onReaction !== 'function')
+        throw new TypeError('Pass onReaction as a function that puts the emoji on the shopper\'s message.');
+    if (o.ack !== undefined && o.ack !== false && o.ack !== 'reaction' && o.ack !== 'text' && o.ack !== 'none' && typeof o.ack !== 'function') {
+        throw new TypeError("Pass ack as 'reaction', 'text' or 'none', as false, or as a function that writes the instant reply from the ask.");
+    }
     const ackDelayMs = o.ackDelayMs ?? ACK_DELAY_MS;
     if (typeof ackDelayMs !== 'number' || !Number.isFinite(ackDelayMs) || ackDelayMs < 0)
         throw new TypeError('Pass ackDelayMs as a number of milliseconds, 0 or more.');
-    const onWorking = o.ack === false ? undefined : o.onWorking;
     const writeAck = typeof o.ack === 'function' ? o.ack : null;
+    /** The mode `ack` names, or null when it names none and the callbacks a turn holds decide. */
+    const ackMode = o.ack === undefined ? null : o.ack === false || o.ack === 'none' ? 'none' : o.ack === 'reaction' ? 'reaction' : 'text';
+    /**
+     * Where a turn acknowledges, from the callbacks it holds: a reaction when it can react and `ack` asks
+     * for no text, else text. At most one of the two comes back, so a shopper never gets a 👀 and a line.
+     */
+    const ackRoutes = (working, reacting) => {
+        if (ackMode === 'none')
+            return { onWorking: undefined, onReaction: undefined };
+        if (ackMode === 'text')
+            return { onWorking: working, onReaction: undefined };
+        if (ackMode === 'reaction' || reacting)
+            return { onWorking: undefined, onReaction: reacting };
+        return { onWorking: working, onReaction: undefined };
+    };
+    const { onWorking, onReaction } = ackRoutes(o.onWorking, o.onReaction);
     /** Calls running now, when the last one ended, and the template the instant reply used last. */
     let running = 0;
     let lastEndedAt = Number.NEGATIVE_INFINITY;
@@ -556,14 +659,18 @@ export function buyTool(options) {
         picked: null,
         ackOut: null,
         ackDelivered: false,
+        reaction: null,
         sendLink,
         onWorking,
+        onReaction,
+        tell: o.onWorking,
         onResult,
         onProgress,
         links: null,
         results: null,
         pages: null,
         storePages: null,
+        event: null,
     });
     /**
      * The turn the calls made straight on the tool belong to, which the tool tells apart by timing. A call
@@ -580,6 +687,31 @@ export function buyTool(options) {
     let lastNextAction = null;
     /** The last reply Agentcard wrote: a message that answers its question for an address or a code gets no instant reply. */
     let lastReply = null;
+    /** How many carts the last answer held: with two or more, a new order goes to the same purchase (answerIn). */
+    let lastCartCount = 0;
+    /** 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 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.
+     */
+    let carriedYes = null;
+    /** 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. */
+    let unconnectedAsk = null;
+    /** The events this tool already took a `nextStep` turn for. */
+    const stepped = new Set();
+    /**
+     * How many shopper messages took back what the shopper asked for before them (any message that is not a plain go-ahead).
+     * A call that started before one of them leaves no yes and no words for a later step: its answer can land after the
+     * shopper said no, and a yes it carried would be confirmed by the next card or sign-in (review of #9220).
+     */
+    let withdrawals = 0;
     /** The names of the products the last answer showed, which a pick takes by `product_id`: a message that names one picks it. */
     let shownNames = [];
     const namesShownProduct = (text) => {
@@ -603,31 +735,72 @@ export function buyTool(options) {
             lastTemplate = nextTemplate(lastTemplate);
         return { picked, text: said ? ackAt(lastTemplate, text) : null };
     };
+    /**
+     * A shopper message that is not a plain go-ahead takes back a yes the shopper gave before it, and words of theirs that
+     * never ran because they were not connected yet ("never mind" after them): a card saved later replays neither. Every
+     * way a shopper message reaches the tool runs it: `turn`, `instantAck` and `instantReaction` (review of #9220).
+     */
+    const withdrawUnlessGoAhead = (shopperText) => {
+        if (keepsYes(String(shopperText ?? '')))
+            return;
+        carriedYes = null;
+        unconnectedAsk = null;
+        withdrawals++;
+    };
     /** The app's own instant reply: the turn its message opens sends no `onWorking` reply. */
     const instantAck = (shopperText) => {
+        withdrawUnlessGoAhead(shopperText);
         const { picked, text } = ackOfMessage(shopperText);
         appAck = { at: Date.now(), said: text !== null, picked };
         return text;
     };
+    /** The app's own reaction: the turn its message opens sends no reaction or reply of its own. */
+    const instantReaction = (shopperText) => (instantAck(shopperText) === null ? null : ACK_REACTION);
+    /**
+     * Puts the 👀 on the turn's message. Every call of the turn waits for it before it hands over a link,
+     * and one that throws costs only the reaction: `turn.reaction` goes back to null, and the model reads
+     * that the shopper was not told.
+     */
+    const react = (t, reacting) => {
+        t.acked = true;
+        t.reaction = ACK_REACTION;
+        let sent;
+        try {
+            sent = reacting(ACK_REACTION);
+        }
+        catch (error) {
+            sent = Promise.reject(error);
+        }
+        t.ackOut = Promise.resolve(sent).then(() => { t.ackDelivered = true; }, () => { t.reaction = null; });
+    };
     /**
      * Holds the instant reply for a new request until `ackDelayMs` passes. `cancel` stops one that has
      * not gone out, and frees the turn's reply for a later call.
      */
     const holdAck = (ask, t, step = null) => {
         const onWorking = t.onWorking;
-        if (!onWorking || t.acked)
+        const reacting = t.onReaction;
+        if ((!onWorking && !reacting) || t.acked)
             return null;
         // A confirm, or a pick of what the shopper saw, gets fixed words that never say `looking for`.
         const slow = step ?? t.picked ?? (!t.neutral && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
         // A short answer to the question the last reply asked, such as `medium` after `what size?`, is no
         // search: like `yes`, a slow call still tells the shopper, in words that look for nothing.
         const neutral = t.neutral || answersQuestion(ask, lastReply);
-        if (!slow && !neutral && !isNewRequest(ask))
+        // A slow call of any message may get the 👀, which reads nothing back; only a text reply needs one of these.
+        if (!reacting && !slow && !neutral && !isNewRequest(ask))
             return null;
         t.acked = true;
         let held = true;
         const timer = setTimeout(() => {
             held = false;
+            // With reactions, a slow call puts the message's one 👀 on it, and never adds a line of text.
+            if (reacting) {
+                react(t, reacting);
+                return;
+            }
+            if (!onWorking)
+                return;
             let text;
             if (slow) {
                 text = slowStepLine(slow);
@@ -666,6 +839,40 @@ export function buyTool(options) {
             },
         };
     };
+    /**
+     * A message sent while the store builds the cart the last request asked for (`turn_in_progress` with `cart_building`) is
+     * never refused for it: the shopper hears the store is still building their cart, once, and the message waits until
+     * the cart is in, reading the conversation every two seconds for at most 90. True once the cart is in and the message
+     * can go; false for any other refusal, and when the wait gave up.
+     */
+    const holdForCart = async (error, t, quiet) => {
+        if (!(error instanceof AgentcardApiError) || error.status !== 409 || error.code !== 'turn_in_progress' || !error.conversationId)
+            return false;
+        const building = cartBuildingOf(error.body.cart_building);
+        if (!building)
+            return false;
+        // The acknowledgement this message was due goes nowhere: the shopper hears the cart is still building instead, and no
+        // search runs meanwhile for it to speak of (Greptile on #9652).
+        quiet?.();
+        try {
+            await t.tell?.(stillBuildingLine(building.store));
+        }
+        catch {
+            // The app's display failing never fails the purchase call.
+        }
+        // The 90 seconds hold however slow a read is: each read gets only the time left, so a read that hangs ends the wait.
+        const deadline = Date.now() + CART_HOLD_READS * CART_HOLD_EVERY_MS;
+        for (let i = 0; i < CART_HOLD_READS && Date.now() < deadline; i++) {
+            await wait(CART_HOLD_EVERY_MS);
+            const left = deadline - Date.now();
+            if (left <= 0)
+                break;
+            const conversation = await readWithin(error.conversationId, left);
+            if (conversation && !conversation.cart_building && !conversation.turn_in_progress)
+                return true;
+        }
+        return false;
+    };
     /** One read of the conversation, or null when it fails: a read only ever improves an answer the tool already has. */
     const read = async (conversationId) => {
         try {
@@ -675,6 +882,17 @@ export function buyTool(options) {
             return null;
         }
     };
+    /** One read that gives up after `ms`, as a failed read does: the read itself is no longer waited for. */
+    const readWithin = async (conversationId, ms) => {
+        let timer;
+        const late = new Promise((resolve) => { timer = setTimeout(() => resolve(null), ms); });
+        try {
+            return await Promise.race([read(conversationId), late]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
     /** The order this purchase placed, or the reason it stopped when the ledger says it did. */
     const placed = (base, order, conversation) => {
         const conversationId = conversation.conversation_id || base.conversation_id;
@@ -761,7 +979,7 @@ export function buyTool(options) {
             ...base,
             status: 'approval_sent',
             reply: APPROVAL_WAITING,
-            links: [{ kind: 'approval', url: last.approval_url, expiresAt: last.approval_expires_at }],
+            links: [approvalLink(last.approval_url, last.approval_expires_at, base.cart)],
             approval_expires_at: last.approval_expires_at,
             next_action: 'approve',
             shopper_need_not_reply: announced,
@@ -927,7 +1145,7 @@ export function buyTool(options) {
                     // The id the model reads and a pick takes, never the store page: the page is `url`.
                     const productId = pickId(product);
                     // A flight option has no page at a store: its card carries no url, and its productId picks it.
-                    await send({ kind: 'product', url: product.url || null, title: product.name, price: money(product.priceCents, product.currency), ...(productId ? { productId } : {}), imageUrl: product.imageUrl, expiresAt: null });
+                    await send({ 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 });
                 }
                 catch {
                     continue;
@@ -989,37 +1207,148 @@ export function buyTool(options) {
     };
     /** The Vault or approval link first, because the purchase waits on it, then the store pages, each to the call's own turn. */
     const deliver = async (result, call, send) => {
-        let delivered = result;
-        if (result.links.length > 0 && send) {
-            for (const link of result.links)
+        // Each step link carries its stable id, in what the shopper is sent and in what the call returns.
+        const stamped = result.links.some((link) => isActionLink(link) && !link.id)
+            ? { ...result, links: result.links.map((link) => (isActionLink(link) && !link.id ? { ...link, id: actionLinkId(link) } : link)) }
+            : result;
+        let delivered = stamped;
+        if (stamped.links.length > 0 && send) {
+            for (const link of stamped.links)
                 await send({ ...link });
-            delivered = { ...result, link_sent: true };
+            delivered = { ...stamped, link_sent: true };
         }
         return deliverPagesInTurn(delivered, call, send);
     };
+    /**
+     * What a shopper's own call leaves for a later `nextStep` turn: the yes a confirm gave, while the
+     * confirm stopped for a card or a store sign-in; the add-card link an answer held back while it asked
+     * for the sign-in first; and the words of a shopper who was not connected yet.
+     */
+    const noteShopperStep = (result, turn, call) => {
+        // A shopper message that took things back while this call ran wins over what the call carried, and a newer call's
+        // state stays as it is: an answer from before the withdrawal changes nothing here (review of #9220).
+        if (call.withdrawalsAtStart !== withdrawals)
+            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;
+        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')
+            cardAfterSignIn = null;
+        if (!call.confirm && call.ask !== '')
+            unconnectedAsk = result.error_code === 'user_not_connected' ? call.ask : null;
+    };
+    /** An answer the tool writes itself, from where the purchase stands, with nothing sent to Agentcard. */
+    const stepResult = (fields) => ({
+        messages: [],
+        cart: null,
+        carts: [],
+        products: [],
+        links: [],
+        link_sent: false,
+        approval_expires_at: null,
+        shopper_need_not_reply: false,
+        conversation_id: null,
+        order_id: null,
+        decline_code: null,
+        error_code: null,
+        next_action: null,
+        pick: null,
+        stores: [],
+        store_pick: null,
+        hashes: [],
+        envelope: {},
+        ...fields,
+    });
+    /**
+     * How a call of a `nextStep` turn goes. It never sends the model's ask, which Agentcard could read as
+     * the shopper's go-ahead. It sends the shopper's own words that never ran because they were not
+     * connected yet, once their card is saved, or a confirm of the one cart the shopper already said yes
+     * to, by that cart's hash. Every other call answers from a read of the conversation: the card link the
+     * sign-in held back, the cart and the ask for the shopper's yes, or the way forward after a decline.
+     */
+    const stepPlan = async (event) => {
+        const conversationId = event.conversationId ?? lastConversationId;
+        const conversation = conversationId ? await read(conversationId) : null;
+        const carts = conversation ? conversation.carts : lastCarts;
+        const one = carts.length === 1 ? carts[0] : null;
+        const who = {
+            ...(o.deliveryAddress ? { delivery_address: o.deliveryAddress } : {}),
+            ...(client.company ? { external_user_id: externalUserId } : {}),
+        };
+        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;
+            return { local: stepResult({ ...standing, status: 'needs_input', reply: carts.length > 0 ? STEP_AFTER_DECLINE : NO_CART_WAITING }) };
+        }
+        if (event.kind === 'card_added' && unconnectedAsk) {
+            const ask = unconnectedAsk;
+            unconnectedAsk = null;
+            // Every purchase through the tool pays from the Vault, so a replayed ask names it too and its carts are quoted that way.
+            return { body: { resume: true, ask, payment_source: 'vault', ...who } };
+        }
+        if (event.kind === 'store_connected' && cardAfterSignIn && !(Date.parse(cardAfterSignIn.expiresAt ?? '') <= Date.now())) {
+            const link = cardAfterSignIn;
+            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) {
+            carriedYes = null;
+            return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who } };
+        }
+        // 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).
+        const last = conversation?.last_checkout ?? null;
+        const approvalOpen = !!last?.approval_url && !(Date.parse(last.approval_expires_at ?? '') <= Date.now());
+        // A checkout whose order the store already took (`pending` while the charge settles, with its order id) is reported as
+        // placed, with that order id, as the recovery path does, never as still going through (review of #9220).
+        const order = conversation && last?.order_id ? placedOrderOf(conversation, 0) : null;
+        if (conversation && order)
+            return { local: placed(stepResult({ ...standing, status: 'needs_input', reply: '' }), order, conversation) };
+        if (conversation && placementRunning(conversation))
+            return { local: stepResult({ ...standing, status: 'needs_input', reply: STEP_PLACEMENT_RUNNING }) };
+        if (approvalOpen)
+            return { local: stepResult({ ...standing, status: 'needs_input', reply: STEP_APPROVAL_WAITING, next_action: 'approve' }) };
+        return { local: stepResult({ ...standing, status: 'needs_input', reply: carts.length > 0 ? ASK_FOR_YES : NO_CART_WAITING, next_action: carts.length > 0 ? 'confirm' : null }) };
+    };
     /**
      * One call, for the turn `explicit` names, or, made straight on the tool, for the turn the tool reads
      * from its timing. Every link, answer and instant reply of the call goes to the turn it started in.
      */
     const answerIn = async (raw, explicit) => {
         const startedAt = Date.now();
+        // A step link held for the message that introduces it goes out before this call hands over any of its own.
+        explicit?.release?.();
+        const withdrawalsAtStart = withdrawals;
         const input = parseBuyToolInput(raw);
-        // A new order is never a confirm: a model that sets both drops the cart and places nothing.
+        // With carts at more than one store waiting, a new order would drop every one of them: "cancel the
+        // reservation, keep the flowers" started a new conversation and lost the flowers cart (2026-10-20).
+        // The ask goes to the same purchase instead, and Agentcard drops only the cart it names.
+        const newOrder = input.new_order && lastCartCount < 2;
+        // A new order is never a confirm: a model that sets both drops the cart and places nothing, even
+        // when the ask stays in the same purchase ("cancel the reservation" never checks out a cart).
         const confirm = input.confirm && !input.new_order;
         const ask = input.ask.trim();
         if (!confirm && ask === '')
             throw new TypeError("Put the shopper's words in ask.");
         // A pick chooses from the products or stores this conversation showed: never on a confirm, and never on a new order, which shows none yet.
-        const picks = !confirm && !input.new_order;
+        const picks = !confirm && !newOrder;
         const pick = picks && input.product_id ? { product_id: input.product_id } : picks && input.store_id ? { store_id: input.store_id } : null;
         const body = {
             resume: true,
-            ...(confirm ? { confirm: true, payment_source: 'vault' } : { ask }),
-            ...(input.new_order ? { new_order: true } : {}),
+            ...(confirm ? { confirm: true } : { ask }),
+            // Every purchase through the tool pays from the shopper's Vault, so every call says so: an ask's carts are then
+            // quoted with the fees the Vault payment charges, and the estimate the shopper sees is the one the confirm pays
+            // (2026-10-21: a cart read $15.67 on its asks and $17.09 at its confirm).
+            payment_source: 'vault',
+            ...(newOrder ? { new_order: true } : {}),
             ...(pick ? { pick } : {}),
             ...(o.deliveryAddress ? { delivery_address: o.deliveryAddress } : {}),
             ...(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;
         // 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.
@@ -1037,16 +1366,21 @@ export function buyTool(options) {
         }
         // The call keeps the turn it started in, whichever turn opens while it runs.
         const t = explicit ?? implicit;
+        // A turn the tool took on its own sends no ask: it reads where the purchase stands, and only the
+        // shopper's own yes to this exact cart goes in, for that cart's hash.
+        const plan = t.event ? await stepPlan(t.event) : null;
+        const sent = plan && 'body' in plan ? plan.body : body;
+        const confirmSent = plan ? 'body' in plan && sent.confirm !== undefined : confirm;
         const callTurn = t.number;
         const send = senderOf(t);
         const progressOf = t.onProgress;
         // A confirm streams as a search does, and only a search's products go out early.
         const streams = o.stream !== false && ((earlyCards && !!send) || !!progressOf);
-        const early = earlyCards && !!send && !confirm;
+        const early = earlyCards && !!send && !confirmSent;
         running += 1;
         // 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 = holdAck(ask, t, confirm ? 'confirm' : pick?.product_id ? 'product' : pick ? 'pick' : null);
+        const ack = t.event ? null : holdAck(ask, t, confirm ? 'confirm' : pick?.product_id ? 'product' : pick ? 'pick' : null);
         try {
             let turn = null;
             let refusal;
@@ -1070,19 +1404,49 @@ export function buyTool(options) {
                         : {}),
                 }
                 : undefined;
-            try {
-                turn = await client.buy(body, handlers);
+            if (plan && 'local' in plan) {
+                // Nothing went to Agentcard: the answer is where the purchase stands.
+            }
+            else {
+                try {
+                    turn = await client.buy(sent, handlers);
+                }
+                catch (error) {
+                    refusal = error;
+                }
             }
-            catch (error) {
-                refusal = error;
+            // The store was still building the last request's cart: once it is in, the request that was refused goes as it was
+            // sent, a step's own request too (a saved ask is no longer saved once its step sent it).
+            if (!turn && !confirmSent && (await holdForCart(refusal, t, () => ack?.cancel()))) {
+                try {
+                    turn = await client.buy(sent, handlers);
+                    refusal = undefined;
+                }
+                catch (error) {
+                    refusal = error;
+                }
             }
             ack?.cancel();
-            const settled = turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt);
+            const settled = plan && 'local' in plan ? plan.local : turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirmSent, startedAt);
             await t.ackOut;
             const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
             const result = t.ackDelivered ? { ...delivered, shopper_already_told_looking: true } : delivered;
             lastNextAction = result.next_action;
             lastReply = result.reply;
+            // A refusal reports no carts, so only a turn's answer says how many wait.
+            if (turn) {
+                lastCartCount = result.carts.length;
+                lastCarts = result.carts;
+            }
+            if (result.conversation_id)
+                lastConversationId = result.conversation_id;
+            if (result.cart?.hash)
+                lastShownHash = result.cart.hash;
+            // 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 });
+            else if (plan && 'body' in plan)
+                noteShopperStep(result, turn, { confirm: confirmSent, yesHash: typeof sent.confirm === 'string' ? sent.confirm : null, ask: sent.ask ?? '', withdrawalsAtStart });
             // 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)
@@ -1146,10 +1510,37 @@ export function buyTool(options) {
      * with another message's, and it sends its instant reply at once, as `instantAck` would read it.
      */
     const turn = (shopperText, options) => {
+        withdrawUnlessGoAhead(String(shopperText ?? ''));
+        return openTurn(String(shopperText ?? ''), options, null);
+    };
+    /**
+     * The turn the agent takes on its own after a step the shopper finished outside the chat, or null
+     * when there is none to take (`BuyTool.nextStep`). The message is answered by the model's words, so
+     * the client never hands its text to a later turn as words the shopper read.
+     */
+    const nextStep = (message, options) => {
+        if (!message || typeof message !== 'object' || typeof message.kind !== 'string')
+            throw new TypeError('Pass the message onMessage got.');
+        if (message.advances !== true || isStale(message))
+            return null;
+        if (client.company && message.externalUserId !== externalUserId)
+            return null;
+        if (message.eventId && stepped.has(message.eventId))
+            return null;
+        // A call for the shopper's own message is still running: its answer tells the model where the purchase stands.
+        if (running > 0)
+            return null;
+        if (message.eventId)
+            stepped.add(message.eventId);
+        if (client.company)
+            client.answered(externalUserId, message);
+        return openTurn(nextStepPrompt(message), options, message);
+    };
+    const openTurn = (shopperText, options, event) => {
         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', 'onResult', 'onProgress', 'onItem']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onItem', 'onMessage']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -1157,32 +1548,101 @@ export function buyTool(options) {
         if (onItem && (own.sendLink !== undefined || own.onWorking !== undefined)) {
             throw new TypeError('Pass onItem, or sendLink and onWorking, to the turn, not both: onItem hears every link and message of the turn.');
         }
+        if (onItem && own.onMessage !== undefined) {
+            throw new TypeError('Pass onItem or onMessage to the turn, not both: onItem hears every message of the turn.');
+        }
+        const onMessage = onItem ? undefined : own.onMessage;
+        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;
         // Messages are spaced only for an app that hears each one as it goes out.
         const pauseOf = paceOf(own.pace);
-        const feed = itemFeed(onItem ? pauseOf : null, typingHook(own.onTyping));
+        const feed = itemFeed(onItem || onMessage ? pauseOf : null, typingHook(own.onTyping));
         // With onItem, every link and message goes to it alone, in order. Without, each goes where it went before, and the turn lists it.
         const baseSendLink = onItem ? undefined : own.sendLink ?? sendLink;
         const baseOnWorking = onItem ? undefined : own.onWorking ?? onWorking;
         // `ack: false` sends no instant reply, whoever would hear it.
         const acks = o.ack !== false && (!!onItem || !!baseOnWorking);
+        /**
+         * Step links held for the message that asks for them. A turn whose model writes through it
+         * (`onItem`, or `messageStream()`/`say()` once called) holds each step link a call hands over until
+         * that message went out: the tool answers before the model writes, so the link used to reach the
+         * chat above the words that explain it (2026-10-21). Product and store cards are what the message
+         * is about, and go out at once. A held link goes out once the turn's next message ends, when the
+         * next call starts, or after STEP_LINK_HOLD_MS, so no link is ever kept from the shopper.
+         */
+        const held = [];
+        // `onMessage` says the app writes the model through the turn, so its links wait for the message too (review of #9234).
+        let writesThroughTurn = !!onItem || !!onMessage;
+        let holdTimer = null;
+        let linkNow = () => { };
+        // A held link that failed to go out when no reply was ending (its timer ran out, or the next call started): the next
+        // reply that ends rejects with it, so the app learns the shopper is missing a link (review of #9234).
+        let lateFailure = null;
+        /** Every held link joins the feed now, in order: settled once each went out, rejected with the first failure. */
+        const release = () => {
+            if (holdTimer)
+                clearTimeout(holdTimer);
+            holdTimer = null;
+            const sends = held.splice(0).map((link) => {
+                try {
+                    return Promise.resolve(linkNow(link));
+                }
+                catch (error) {
+                    return Promise.reject(error);
+                }
+            });
+            return Promise.all(sends).then(() => undefined);
+        };
+        const releaseLate = () => {
+            release().catch((error) => {
+                lateFailure ??= { error };
+            });
+        };
+        /** The release a reply ends with: it waits for the held links, and fails with theirs or an earlier late failure. */
+        const releaseForReply = async () => {
+            await release();
+            if (lateFailure) {
+                const { error } = lateFailure;
+                lateFailure = null;
+                throw error;
+            }
+        };
         const state = {
             ...toolTurn(++modelTurn),
+            event,
             sendLink: (link) => feed.push({ kind: 'link', link }, () => (onItem ? onItem({ kind: 'link', link: { ...link } }) : baseSendLink?.(link))),
-            onWorking: acks ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
+            // A reaction goes to onReaction even with onItem: it sits on the shopper's bubble, not in the turn's sequence.
+            ...ackRoutes(acks ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined, own.onReaction ?? o.onReaction),
             onResult: own.onResult ?? onResult,
             onProgress: own.onProgress ?? onProgress,
+            tell: onItem || baseOnWorking ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
             links: [],
             results: [],
         };
-        /** A message the app's model wrote: it goes to onItem, after every item before it, and the turn lists it. */
-        const text = (message, skip) => feed.push({ kind: 'text', text: message }, () => onItem?.({ kind: 'text', text: message }), skip);
+        linkNow = state.sendLink;
+        state.release = releaseLate;
+        state.sendLink = (link) => {
+            if (!writesThroughTurn || !STEP_LINK_KINDS.has(link.kind))
+                return linkNow(link);
+            held.push({ ...link });
+            if (!holdTimer) {
+                holdTimer = setTimeout(releaseLate, STEP_LINK_HOLD_MS);
+                holdTimer.unref?.();
+            }
+            return Promise.resolve();
+        };
+        /** A message the app's model wrote: it goes to onItem, else onMessage, after every item before it, and the turn lists it. */
+        const text = (message, skip) => feed.push({ kind: 'text', text: message }, () => (onItem ? onItem({ kind: 'text', text: message }) : onMessage?.(message)), skip);
         let ack = null;
         const working = state.onWorking;
-        if (working) {
+        const reacting = state.onReaction;
+        // A turn the agent takes on its own answers no shopper message, so nothing gets a 👀 or an instant reply.
+        if (!event && (working || reacting)) {
             const message = String(shopperText ?? '');
             const read = ackOfMessage(message);
             let text = read.text;
-            if (text !== null && writeAck) {
+            if (text !== null && writeAck && working) {
                 try {
                     text = writeAck(message) ?? null;
                 }
@@ -1199,7 +1659,11 @@ export function buyTool(options) {
                 // A message that starts no search, such as `yes`: a slow call still tells the shopper, in words that name nothing.
                 state.neutral = true;
             }
-            else if (text !== null) {
+            else if (reacting) {
+                // A search gets its 👀 the moment the turn opens, and no text: the reaction reads nothing back.
+                react(state, reacting);
+            }
+            else if (text !== null && working) {
                 ack = text;
                 state.acked = true;
                 let sent;
@@ -1256,23 +1720,47 @@ export function buyTool(options) {
         };
         return toolOf((raw) => answerIn(raw, state), {}, {
             agentcardMessages: { get: () => [...(handed ?? kept)], enumerable: false },
+            event: { value: event, enumerable: false },
+            release: {
+                value: () => {
+                    if (!event)
+                        return;
+                    if (event.eventId)
+                        stepped.delete(event.eventId);
+                    if (client.company)
+                        client.unanswered(externalUserId, event);
+                },
+                enumerable: false,
+            },
             messages: { value: messagesFor, enumerable: false },
             ack: { value: ack, enumerable: false },
+            reaction: { get: () => state.reaction, enumerable: false },
             links: { get: () => [...links], enumerable: false },
             results: { get: () => [...results], enumerable: false },
+            replyAsWritten: { get: () => (written && results.length > 0 ? replyAsWritten(results[results.length - 1]) : 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.
-            messageStream: { value: () => feedStream(text), enumerable: false },
+            // A step link held for this message goes out right after its last paragraph, once the stream ends.
+            messageStream: {
+                value: () => {
+                    writesThroughTurn = true;
+                    return feedStream(text, releaseForReply);
+                },
+                enumerable: false,
+            },
             say: {
                 value: (whole) => {
+                    writesThroughTurn = true;
                     const reply = feedReply(text);
                     for (const message of toMessages(whole))
                         reply.add(message);
-                    return reply.settled();
+                    const released = releaseForReply();
+                    released.catch(() => { });
+                    return reply.settled().then(() => released);
                 },
                 enumerable: false,
             },
         });
     };
-    return toolOf(answer, { instantAck, turn }, {});
+    return toolOf(answer, { instantAck, instantReaction, turn, nextStep }, {});
 }