@agent-cards/commerce-sdk 0.11.0 → 0.14.0

package/dist/buy-tool.js

@@ -31,11 +31,20 @@
  * 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 { directCall } from './direct.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 { ACK_REACTION, 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 +121,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 +145,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
@@ -144,6 +198,11 @@ export function productsOf(turn) {
     return turn.catalog ? productsOfCatalog(turn.catalog) : [];
 }
 /** The products of a search, as the tool reads them. */
+/** A product's card as `sendLink` hears it: the id the model reads and a pick takes, never the store page, which is `url`. A flight option has no page at a store: its card carries no url, and its productId picks it. */
+function productLink(product) {
+    const productId = pickId(product);
+    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), expiresAt: null };
+}
 function productsOfCatalog(catalog) {
     return (catalog.items ?? [])
         .filter((item) => item.name)
@@ -152,11 +211,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 +232,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 +262,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,
     };
 }
@@ -234,9 +305,67 @@ function withMessages(result, turn) {
     const sent = turn && result.reply === turn.reply && turn.messages.length > 0 ? turn.messages : [result.reply];
     return { ...result, messages: sent.flatMap(toMessages) };
 }
+/** True when the app showed every message of an answer that has one, each as written and in order. */
+function readEvery(told, messages) {
+    const written = messages.map((message) => message.trim()).filter((message) => message !== '');
+    return written.length > 0 && written.length === told.length && written.every((message, i) => message === told[i].trim());
+}
+/**
+ * The steps the shopper answers in the chat, none of which has a link, and the line that asks the shopper for one when
+ * a reply asks for something else instead. Each is written for the shopper, as Agentcard's messages are: an app that
+ * shows Agentcard's messages as they stream shows it in place of the ask it replaces.
+ */
+const CHAT_STEP_ASKS = {
+    shipping_details: "What's the shipping address for this order?",
+    guest_details: 'What name, email and phone should it go under?',
+    verification_code: "What's the verification code the store just sent you?",
+};
+/** Every web address in a text, with or without its scheme. */
+const URL_IN_TEXT = /\b(?:https?:\/\/|www\.)[^\s<>"'`)\]]+/gi;
+/** An ask for a payment card: "add your card", "save a card", "add a payment card". "Added the gift card" is a cart line. */
+const CARD_ASK = /\b(?:add|save|link|enter|attach)\s+(?:a|your|the)\s+(?:(?:payment|credit|debit)\s+)?card\b/i;
+/**
+ * Whether a streamed message waits for the answer before the shopper reads it: it asks for a card or points at a link,
+ * which `askingForNamedStep` replaces when Agentcard names a step that comes first. Every message after it waits behind
+ * it, so the shopper reads them in order; a message before it goes out at once.
+ */
+function waitsForAnswer(message) {
+    return CARD_ASK.test(message) || new RegExp(URL_IN_TEXT.source, 'i').test(message);
+}
+/**
+ * The answer with its reply asking for the step Agentcard named, when that step is answered in the chat (an address, a
+ * guest's details, a code) and a paragraph of the reply asks for a card, or sends the shopper to a link the answer does
+ * not hand over. Agentcard holds the add-card link back while the address comes first, yet its reply can still ask for
+ * the card, with the link pasted in or with none: every link is taken out of a reply, so the shopper read "add your card
+ * to place the order:" and no link came (2026-10-26, Commerce SDK playground, a Walmart cart with no shipping address).
+ * The paragraph gives way to a line that asks the shopper for the named step, so the reply is no longer Agentcard's as
+ * written and the model words it. A streamed message that asks for a card or points at a link waits for the answer
+ * (`waitsForAnswer`), so an app showing Agentcard's messages as they stream shows that line in its place. A link to a product, store or cart line the answer lists is not held back, and leaves the reply
+ * as it is, as does a cart line about a card that is a product ("added the gift card").
+ */
+function askingForNamedStep(result, next) {
+    const ask = next ? CHAT_STEP_ASKS[next] : undefined;
+    if (!ask || typeof result.reply !== 'string')
+        return result;
+    const known = [
+        ...result.links.map((link) => link.url),
+        ...result.products.map((product) => product.url),
+        ...result.stores.map((store) => store.url),
+        ...result.carts.flatMap((c) => c.items.map((line) => line.url)),
+        ...(result.cart?.items.map((line) => line.url) ?? []),
+    ].filter((url) => typeof url === 'string' && url !== '');
+    // The answer hands over no add-card link beside a step that comes first (onlyNextStepLinks), so a card ask is a dead end.
+    const held = (paragraph) => CARD_ASK.test(paragraph) ||
+        (paragraph.match(URL_IN_TEXT) ?? []).some((url) => !known.some((page) => page === url || page.startsWith(url) || url.startsWith(page)));
+    const paragraphs = result.reply.split(/\n\s*\n/);
+    if (!paragraphs.some(held))
+        return result;
+    const kept = paragraphs.filter((paragraph) => !held(paragraph) && paragraph.trim() !== '');
+    return { ...result, reply: [...kept, ask].join('\n\n') };
+}
 /** A purchase answer, read for its status. A status Agentcard adds later reads as `needs_input`. */
 function resultOfTurn(turn) {
-    return onlyNextStepLinks(resultOfStatus(turn), turn.next_action);
+    return askingForNamedStep(onlyNextStepLinks(resultOfStatus(turn), turn.next_action), turn.next_action);
 }
 /** A purchase answer, read for its status, with every link the answer carries. */
 function resultOfStatus(turn) {
@@ -259,7 +388,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 +421,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 +567,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;
         },
     };
 }
@@ -518,17 +664,33 @@ export function buyTool(options) {
     const sendLink = o.sendLink;
     if (o.onProgress !== undefined && typeof o.onProgress !== 'function')
         throw new TypeError('Pass onProgress as a function that takes each stage of a call.');
+    if (o.onProducts !== undefined && typeof o.onProducts !== 'function')
+        throw new TypeError('Pass onProducts as a function that takes the products a search found.');
+    if (o.onText !== undefined && typeof o.onText !== 'function')
+        throw new TypeError('Pass onText as a function that takes each message Agentcard writes.');
+    if (o.onCart !== undefined && typeof o.onCart !== 'function')
+        throw new TypeError('Pass onCart as a function that takes the carts each time a call builds or changes one.');
     if (o.stream !== undefined && o.stream !== false)
         throw new TypeError('Pass stream as false to wait for each whole answer, or leave it out.');
     const onProgress = o.onProgress;
+    for (const key of ['onStatus', 'onFound']) {
+        if (o[key] !== undefined && typeof o[key] !== 'function')
+            throw new TypeError(`Pass ${key} as a function, or leave it out.`);
+    }
     if (o.earlyCards !== undefined && typeof o.earlyCards !== 'boolean')
         throw new TypeError('Pass earlyCards as true or false.');
-    // A call streams when it has someone to tell: a stage for onProgress, or early cards for the links of its turn.
-    const earlyCards = o.earlyCards === true;
+    // A search's cards go out the moment it answers, unless the app waits for the answer that names them.
+    const earlyCards = o.earlyCards !== false;
     if (o.onResult !== undefined && typeof o.onResult !== 'function') {
         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;
+    if (o.direct !== undefined && typeof o.direct !== 'boolean')
+        throw new TypeError('Pass direct as true or false.');
+    const directOn = o.direct === 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.');
@@ -578,12 +740,19 @@ export function buyTool(options) {
         sendLink,
         onWorking,
         onReaction,
+        tell: o.onWorking,
         onResult,
         onProgress,
+        onStatus: o.onStatus,
+        onFound: o.onFound,
+        onProducts: o.onProducts,
+        onText: o.onText,
+        onCart: o.onCart,
         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
@@ -600,12 +769,46 @@ 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;
+    /**
+     * True when the last answer was a checkout that ended with no order and no cart waiting (`declined`): a new order then
+     * has no cart to drop, so it goes to the same purchase too (answerIn).
+     */
+    let declinedNoCart = false;
+    /** 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) => {
         const said = productWords(text);
         return said !== '' && shownNames.some((name) => said.includes(name));
     };
+    /** What the last answer showed, products and stores with the ids a pick sends, and the turn the shopper opened last. */
+    let lastAnswerProducts = [];
+    let lastAnswerStores = [];
+    let previousTurn = null;
     /** The names of the stores the last answer that listed stores showed: a message that names one, as a tap on its card does, picks it. */
     let shownStoreNames = [];
     /** True for a pick of a product or a store the shopper saw, by its name. */
@@ -623,8 +826,21 @@ 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;
@@ -714,6 +930,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 {
@@ -723,6 +973,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;
@@ -809,7 +1070,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,
@@ -973,9 +1234,7 @@ export function buyTool(options) {
             if (!before.has(key)) {
                 try {
                     // 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(productLink(product));
                 }
                 catch {
                     continue;
@@ -1037,37 +1296,152 @@ 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.
+        // After a checkout that ended with no order and no cart, a new order has no cart to drop: the shopper's yes to
+        // trying again went out as one, and the new conversation searched again and asked for the delivery address a
+        // second time (Commerce SDK playground, duralexusa.com, 2026-10-27). The ask stays in the purchase that holds
+        // the product, the size and the address, until the next answer.
+        const newOrder = input.new_order && lastCartCount < 2 && !declinedNoCart;
+        // 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.
@@ -1085,52 +1459,234 @@ 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;
+        // Every call streams unless the app waits for whole answers, so each part reaches the app as Agentcard produces it. A
+        // confirm streams as a search does, and only a search's products go out early. A call with no callback to hear any part
+        // has no handler, and the client asks for the whole answer.
+        const streams = o.stream !== false;
+        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;
-            // Streamed: the stages go to onProgress, and a search's store pages go out the moment it answers.
+            /** Each message of Agentcard's answer the app showed through onText, in the order the shopper read them: every one means the shopper read the reply. */
+            const told = [];
+            /**
+             * The streamed messages that wait for the answer: the first that asks for a card or points at a link (waitsForAnswer),
+             * and every message after it, so the shopper reads them in the order Agentcard wrote them.
+             */
+            const waiting = [];
+            /** The products past the cards of the catalog this call heard last, for the count that follows it. */
+            let moreFound = null;
+            /** Whether this call's cards went out, and a count that came before them. */
+            let cardsOut = false;
+            let heldCount = null;
+            /** Hands the app one count with the products past the cards of the catalog it counts. */
+            const tellCount = async ({ conversationId, shown, found }) => {
+                const more = moreFound?.conversationId === conversationId ? moreFound.links : [];
+                moreFound = null;
+                try {
+                    await t.onFound({ conversationId, shown, found, more });
+                }
+                catch {
+                    // The app's display failing never fails the call.
+                }
+            };
+            // Streamed: the stages go to onProgress, a search's products to onProducts and its store pages out the moment it
+            // answers, and each message and cart to the app as Agentcard writes it.
             const handlers = streams
                 ? {
                     ...(progressOf ? { onProgress: (progress) => { try {
                             progressOf(progress);
                         }
                         catch { /* the app's display failing never fails the call */ } } } : {}),
-                    ...(early
+                    ...(t.onStatus ? { onStatus: (status) => { try {
+                            t.onStatus(status);
+                        }
+                        catch { /* the app's display failing never fails the call */ } } } : {}),
+                    // A count counts the cards the shopper already holds, so it comes only where the cards go out early (earlyCards):
+                    // with the cards held for the answer, the answer can list fewer than the count would say.
+                    ...(t.onFound && early
+                        ? {
+                            onFound: async ({ conversationId, shown, found }) => {
+                                // A count that comes before any card of this call (find mode's) waits for the cards it counts.
+                                if (!cardsOut) {
+                                    heldCount = { conversationId, shown, found };
+                                    return;
+                                }
+                                await tellCount({ conversationId, shown, found });
+                            },
+                        }
+                        : {}),
+                    ...(early || t.onProducts
                         ? {
                             onCatalog: async (update) => {
+                                try {
+                                    await t.onProducts?.(productsOfCatalog(update.catalog), { conversationId: update.conversationId, asOf: update.asOf, merchantName: update.catalog.merchant_name });
+                                }
+                                catch {
+                                    // The app's display failing never fails the call.
+                                }
+                                // The products past the cards are read after the cards went out, so the first card never waits for them.
+                                const keepMore = () => { if (t.onFound && early)
+                                    moreFound = { conversationId: update.conversationId, links: productsOfCatalog({ ...update.catalog, items: update.more }).map(productLink) }; };
+                                if (!early)
+                                    return;
                                 // Products arrived before the instant reply was due: they are the reply.
                                 ack?.cancel();
                                 await t.ackOut;
                                 // The turn's own search presents its products, as a reply that lists them does.
                                 await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, productsOfCatalog(update.catalog)), { turn: callTurn, presented: true, owner: t }, send);
+                                keepMore();
+                                cardsOut = true;
+                                // A count held for these cards goes out now, unless the catalog carries its own, which follows it.
+                                const held = heldCount;
+                                heldCount = null;
+                                if (held && update.found === null)
+                                    await tellCount(held);
+                            },
+                        }
+                        : {}),
+                    ...(t.onText
+                        ? {
+                            onSegment: async ({ text, conversationId }) => {
+                                // A message that lands before the instant reply was due is the reply; one after it follows it.
+                                ack?.cancel();
+                                await t.ackOut;
+                                // A card ask or a link waits for the answer, which may name a step that comes first, and every message after it waits behind it.
+                                if (waiting.length > 0 || waitsForAnswer(text)) {
+                                    waiting.push({ text, conversationId });
+                                    return;
+                                }
+                                try {
+                                    await t.onText(text, { conversationId });
+                                    told.push(text);
+                                }
+                                catch {
+                                    // A message the app failed to show was never read, so the model words the answer.
+                                }
+                            },
+                        }
+                        : {}),
+                    ...(t.onCart
+                        ? {
+                            onCart: async ({ cart, carts, conversationId }) => {
+                                try {
+                                    await t.onCart(cart, { carts, conversationId });
+                                }
+                                catch {
+                                    // The app's display failing never fails the call.
+                                }
                             },
                         }
                         : {}),
                 }
                 : undefined;
-            try {
-                turn = await client.buy(body, handlers);
+            if (plan && 'local' in plan) {
+                // Nothing went to Agentcard: the answer is where the purchase stands.
             }
-            catch (error) {
-                refusal = error;
+            else {
+                try {
+                    turn = await client.buy(sent, handlers);
+                }
+                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()))) {
+                // Only the answer of the request sent again counts toward what the shopper read.
+                told.length = 0;
+                waiting.length = 0;
+                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;
+            // The streamed messages that waited for the answer go out in order: each the answer kept as written, and a card ask or
+            // a link the answer replaced gives way to its ask for the step Agentcard named, once, after them. All of them go out
+            // before any link of the answer.
+            let replaced = false;
+            if (waiting.length > 0 && t.onText) {
+                const rewritten = !!turn && settled.reply !== turn.reply;
+                const kept = new Set((rewritten ? toMessages(settled.reply) : []).map((message) => message.trim()));
+                for (const message of waiting.splice(0)) {
+                    if (rewritten && waitsForAnswer(message.text) && !kept.has(message.text.trim())) {
+                        replaced = true;
+                        continue;
+                    }
+                    try {
+                        await t.onText(message.text, { conversationId: message.conversationId });
+                        told.push(message.text);
+                    }
+                    catch {
+                        // A message the app failed to show was never read, so the model words the answer.
+                    }
+                }
+                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);
+                    }
+                    catch {
+                        // Not shown, so the model asks for the step.
+                    }
+                }
+            }
+            // Every message of Agentcard's own answer reached the shopper through onText, so the model adds nothing to it. An answer
+            // whose card ask gave way to the named step was read the same way once every message of it, that ask last, went out.
+            const read = !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, toMessages(settled.reply)));
             const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
-            const result = t.ackDelivered ? { ...delivered, shopper_already_told_looking: true } : delivered;
+            // A count that came before any card (find mode puts its cards in the answer) goes out once the answer's cards did.
+            if (heldCount && (delivered.products?.length ?? 0) > 0) {
+                const held = heldCount;
+                heldCount = null;
+                await tellCount(held);
+            }
+            // The message that asks for a step link already went out, so the link follows it now instead of waiting for the model's.
+            // The call waits for it, and one that fails to send fails the call, as a step link the turn does not hold does.
+            if (read)
+                await t.releaseNow?.();
+            const result = {
+                ...delivered,
+                ...(t.ackDelivered ? { shopper_already_told_looking: true } : {}),
+                ...(read ? { shopper_already_read_reply: true } : {}),
+            };
             lastNextAction = result.next_action;
             lastReply = result.reply;
+            // A refusal reports no carts, so only a turn's answer says how many wait, and whether a checkout just ended with none.
+            if (turn) {
+                lastCartCount = result.carts.length;
+                lastCarts = result.carts;
+                declinedNoCart = result.status === 'declined' && result.carts.length === 0;
+            }
+            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)
@@ -1139,6 +1695,8 @@ export function buyTool(options) {
             const storesShown = shownStores(result.stores);
             if (storesShown.length > 0)
                 shownStoreNames = storesShown.map((store) => store.name);
+            lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name }));
+            lastAnswerStores = storesShown.map((store) => ({ storeId: store.id, name: store.name }));
             t.results?.push(result);
             if (t.onResult) {
                 try {
@@ -1194,10 +1752,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', 'onReaction', 'onResult', 'onProgress', 'onItem']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -1205,30 +1790,106 @@ 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;
+        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);
-        const feed = itemFeed(onItem ? pauseOf : null, typingHook(own.onTyping));
+        const feed = itemFeed(onItem || onMessage || hearText ? 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))),
             // 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,
+            onStatus: own.onStatus ?? o.onStatus,
+            onFound: own.onFound ?? o.onFound,
+            onProducts: own.onProducts ?? o.onProducts,
+            // Agentcard's message takes its place in the turn's sequence, after the items before it, and goes to onText alone, so
+            // an app that passes onItem too hears it once.
+            onText: hearText ? (text, info) => feed.push({ kind: 'text', text }, () => hearText(text, info)) : undefined,
+            onCart: own.onCart ?? o.onCart,
+            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.releaseNow = releaseForReply;
+        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;
         const reacting = state.onReaction;
-        if (working || reacting) {
+        // 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;
@@ -1270,6 +1931,13 @@ export function buyTool(options) {
         }
         const links = state.links;
         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;
+        if (!event)
+            previousTurn = state;
         // What Agentcard told the shopper that no history the model ran with holds yet.
         const kept = client.company ? client.keptMessages(externalUserId) : [];
         let handed = null;
@@ -1310,24 +1978,48 @@ 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 },
+            direct: { value: direct, 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, instantReaction, turn }, {});
+    return toolOf(answer, { instantAck, instantReaction, turn, nextStep }, {});
 }