@agent-cards/commerce-sdk 0.13.0 → 0.15.0

package/dist/buy-tool.js

@@ -33,6 +33,7 @@
  */
 import { AgentcardApiError, AgentcardClient, cartBuildingOf, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
+import { directCall } from './direct.js';
 import { forModel, forModelError, pickId, productPrice, productCardKey, replyAsWritten, shownProducts, shownStores, stripLinks } from './model-view.js';
 import { messageStream, paceOf, sleep, toMessages, typingHook } from './messages.js';
 import { isStale } from './shopper-message.js';
@@ -197,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, ...(product.availability ? { availability: product.availability } : {}) };
+}
 function productsOfCatalog(catalog) {
     return (catalog.items ?? [])
         .filter((item) => item.name)
@@ -214,6 +220,7 @@ function productsOfCatalog(catalog) {
         url: item.url ?? null,
         action: productAction(catalog.merchant),
         linkSent: false,
+        ...(item.availability ? { availability: item.availability } : {}),
     }));
 }
 /** The stores an answer presents, as the tool reads them. */
@@ -299,9 +306,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) {
@@ -600,13 +665,23 @@ 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', 'onAvailability']) {
+        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.');
     }
@@ -614,6 +689,9 @@ export function buyTool(options) {
     if (o.replyAsWritten !== undefined && typeof o.replyAsWritten !== 'boolean')
         throw new TypeError('Pass replyAsWritten as true or false.');
     const writtenByDefault = o.replyAsWritten === true;
+    if (o.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.');
@@ -666,6 +744,12 @@ export function buyTool(options) {
         tell: o.onWorking,
         onResult,
         onProgress,
+        onStatus: o.onStatus,
+        onFound: o.onFound,
+        onAvailability: o.onAvailability,
+        onProducts: o.onProducts,
+        onText: o.onText,
+        onCart: o.onCart,
         links: null,
         results: null,
         pages: null,
@@ -689,6 +773,11 @@ export function buyTool(options) {
     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 = [];
@@ -718,6 +807,10 @@ export function buyTool(options) {
         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. */
@@ -1143,9 +1236,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: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), expiresAt: null });
+                    await send(productLink(product));
                 }
                 catch {
                     continue;
@@ -1325,7 +1416,11 @@ export function buyTool(options) {
         // 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;
+        // 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;
@@ -1374,31 +1469,186 @@ export function buyTool(options) {
         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);
+        // 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 = t.event ? null : holdAck(ask, t, confirm ? 'confirm' : pick?.product_id ? 'product' : pick ? 'pick' : null);
+        /** Says `unknown` of every card the call left `checking`; it runs once the answer's cards went out, or when the call fails. */
+        let settleLeft = null;
         try {
             let turn = null;
             let refusal;
-            // 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;
+            /** The card each catalog id of this call went out as (its `productId`), and the cards still `checking`, by conversation. */
+            const cardOfId = new Map();
+            const checking = new Map();
+            /**
+             * What the live search answered for each card, so a later copy of the same place, such as a card whose first send
+             * failed and goes out again with the answer, carries that answer and never goes back to `checking`.
+             */
+            const answered = new Map();
+            const withAnswers = (products) => answered.size === 0 ? products : products.map((product) => {
+                const known = product.availability ? answered.get(pickId(product) ?? '') : undefined;
+                return known ? { ...product, availability: known } : product;
+            });
+            /**
+             * Notes the card each product goes out as, and each place still `checking`, whichever way the app got it: a card
+             * through `sendLink` now or on a later try, or a product past the cards that `onFound` hands over for "show more".
+             */
+            const noteCards = (products, conversationId) => {
+                for (const product of products) {
+                    const productId = pickId(product);
+                    if (!productId)
+                        continue;
+                    cardOfId.set(product.id, productId);
+                    if (product.availability?.status === 'checking' && !answered.has(productId))
+                        checking.set(productId, conversationId);
+                }
+            };
+            /** Hands the app what the live search said of the places, each by its card, and settles those cards. */
+            settleLeft = async () => {
+                if (!t.onAvailability || !early)
+                    return;
+                const left = [...checking];
+                for (const conversationId of new Set(left.map(([, c]) => c))) {
+                    await tellAvailability(conversationId, left.filter(([, c]) => c === conversationId).map(([productId]) => ({ productId, availability: { status: 'unknown' } })));
+                }
+            };
+            const tellAvailability = async (conversationId, items) => {
+                for (const item of items) {
+                    checking.delete(item.productId);
+                    answered.set(item.productId, item.availability);
+                }
+                if (!t.onAvailability || items.length === 0)
+                    return;
+                try {
+                    await t.onAvailability({ conversationId, items });
+                }
+                catch {
+                    // The app's display failing never fails the call.
+                }
+            };
+            /** Hands the app one count with the products past the cards of the catalog it counts. */
+            const tellCount = async ({ conversationId, shown, found }) => {
+                const more = moreFound?.conversationId === conversationId ? moreFound.links : [];
+                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);
+                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                // A place shown `checking`, on a card or behind "show more", waits for the live search's word on it.
+                                noteCards([...productsOfCatalog(update.catalog), ...productsOfCatalog({ ...update.catalog, items: update.more })], update.conversationId);
+                                keepMore();
+                                cardsOut = true;
+                                // A count held for these cards goes out now, unless the catalog carries its own, which follows it.
+                                const held = heldCount;
+                                heldCount = null;
+                                if (held && update.found === null)
+                                    await tellCount(held);
+                            },
+                        }
+                        : {}),
+                    ...(t.onAvailability && early
+                        ? {
+                            onAvailability: async ({ conversationId, items }) => {
+                                await tellAvailability(conversationId, items.map(({ id, availability }) => ({ productId: cardOfId.get(id) ?? id, availability })));
+                            },
+                        }
+                        : {}),
+                    ...(t.onText
+                        ? {
+                            onSegment: async ({ text, conversationId }) => {
+                                // 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.
+                                }
                             },
                         }
                         : {}),
@@ -1418,6 +1668,9 @@ export function buyTool(options) {
             // 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;
@@ -1429,14 +1682,69 @@ export function buyTool(options) {
             ack?.cancel();
             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;
+            // 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 answer = withMessages(settled, turn);
+            const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
+            // A count that came before any card (find mode puts its cards in the answer) goes out once the answer's cards did.
+            if (heldCount && (delivered.products?.length ?? 0) > 0) {
+                const held = heldCount;
+                heldCount = null;
+                await tellCount(held);
+            }
+            // A call that ends with cards still `checking`, the answer's own cards included, says `unknown` of each, so none waits
+            // for an answer that is not coming.
+            if (delivered.conversation_id)
+                noteCards(delivered.products ?? [], delivered.conversation_id);
+            await settleLeft();
+            // The message that asks for a step link already went out, so the link follows it now instead of waiting for the model's.
+            // The call waits for it, and one that fails to send fails the call, as a step link the turn does not hold does.
+            if (read)
+                await t.releaseNow?.();
+            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.
+            // 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;
@@ -1455,6 +1763,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 {
@@ -1467,6 +1777,8 @@ export function buyTool(options) {
             return result;
         }
         finally {
+            // A call that fails, Agentcard's error or a thrown handler, still settles the cards it left `checking`.
+            await settleLeft?.().catch(() => { });
             ack?.cancel();
             running -= 1;
             lastEndedAt = Date.now();
@@ -1540,7 +1852,7 @@ export function buyTool(options) {
         const own = options ?? {};
         if (typeof own !== 'object')
             throw new TypeError('Pass the turn options as an object, or leave them out.');
-        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onItem', 'onMessage']) {
+        for (const key of ['sendLink', 'onWorking', 'onReaction', 'onResult', 'onProgress', 'onStatus', 'onFound', 'onAvailability', 'onItem', 'onMessage', 'onProducts', 'onText', 'onCart']) {
             if (own[key] !== undefined && typeof own[key] !== 'function')
                 throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
         }
@@ -1555,9 +1867,10 @@ export function buyTool(options) {
         if (own.replyAsWritten !== undefined && typeof own.replyAsWritten !== 'boolean')
             throw new TypeError('Pass replyAsWritten to the turn as true or false, or leave it out.');
         const written = own.replyAsWritten ?? writtenByDefault;
+        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 || onMessage ? 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;
@@ -1616,12 +1929,21 @@ export function buyTool(options) {
             ...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,
+            onAvailability: own.onAvailability ?? o.onAvailability,
+            onProducts: own.onProducts ?? o.onProducts,
+            // Agentcard's message takes its place in the turn's sequence, after the items before it, and goes to onText alone, so
+            // an app that passes onItem too hears it once.
+            onText: hearText ? (text, info) => feed.push({ kind: 'text', text }, () => hearText(text, info)) : undefined,
+            onCart: own.onCart ?? o.onCart,
             tell: onItem || baseOnWorking ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
             links: [],
             results: [],
         };
         linkNow = state.sendLink;
         state.release = releaseLate;
+        state.releaseNow = releaseForReply;
         state.sendLink = (link) => {
             if (!writesThroughTurn || !STEP_LINK_KINDS.has(link.kind))
                 return linkNow(link);
@@ -1680,6 +2002,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;
@@ -1737,6 +2066,7 @@ export function buyTool(options) {
             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.