@agent-cards/commerce-sdk 0.13.0 → 0.14.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 };
+}
 function productsOfCatalog(catalog) {
     return (catalog.items ?? [])
         .filter((item) => item.name)
@@ -299,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) {
@@ -600,13 +664,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']) {
+        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 +688,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 +743,11 @@ export function buyTool(options) {
         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,
@@ -689,6 +771,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 +805,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 +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: 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 +1414,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,8 +1467,10 @@ 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
@@ -1384,21 +1479,114 @@ export function buyTool(options) {
         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.
+                                }
                             },
                         }
                         : {}),
@@ -1418,6 +1606,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 +1620,63 @@ 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;
+            // 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.
+            // 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 +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 {
@@ -1540,7 +1782,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', '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 +1797,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 +1859,20 @@ 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,
+            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 +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;
@@ -1737,6 +1995,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.

package/dist/client.d.ts

@@ -44,20 +44,118 @@ export interface BuyCatalogUpdate {
     catalog: BuyCatalog;
     /** When the search ran, as the answer's `catalog.as_of` names it: the same search in the answer has the same value. */
     asOf: string | null;
+    /** How many of the products found are in `catalog.items`, the cards to show. Null when Agentcard sent no count. */
+    shown: number | null;
+    /** How many distinct products the turn's searches found so far. Null when Agentcard sent no count. */
+    found: number | null;
+    /** The products found past the cards, in the order they were found, to show on "show more" with no new search. */
+    more: BuyCatalog['items'];
 }
-/** Called while a purchase turn runs. Passing either one asks Agentcard to stream the turn. */
+/** How many products a running turn found so far, and how many of them it shows: "8 of 23 shown". */
+export interface BuyFoundUpdate {
+    conversationId: string;
+    shown: number;
+    found: number;
+}
+/**
+ * What a running turn is doing, the moment a step starts: `text` is a short line to show in place of loading dots, such as
+ * `searching Target and Walmart` or `adding it to your cart`, and `step` names the step for an app that writes its own,
+ * such as `searching`, `adding_to_cart` or `store_checkout`. No status comes for a turn that only writes its reply.
+ */
+export interface BuyTurnStatus {
+    conversationId: string | null;
+    step: string;
+    text: string;
+}
+/** One message Agentcard finished writing while the turn runs, links included, as the answer's `messages` then holds it. */
+export interface BuySegmentUpdate {
+    conversationId: string | null;
+    text: string;
+}
+/** The carts on the table the moment a running turn builds or changes one, before the message that announces it. */
+export interface BuyCartUpdate {
+    conversationId: string;
+    /** The cart a confirm would place, as the answer's `cart` names it, or null when none would be. */
+    cart: BuyCart | null;
+    /** Every cart on the table, oldest first, as the answer's `carts`. */
+    carts: BuyCart[];
+}
+/**
+ * A piece of a message while Agentcard writes it. A piece can hold words Agentcard drops before the message is done, such
+ * as a line that only says it is looking, so show the pieces as a draft and replace them with each `onSegment` message.
+ */
+export interface BuyDeltaUpdate {
+    conversationId: string | null;
+    text: string;
+}
+/**
+ * Called while a purchase turn runs. Passing any one asks Agentcard to stream the turn. `onCatalog`, `onSegment`,
+ * `onCart` and `onDelta` hear their events one at a time, in the order Agentcard sent them, each once the one before it
+ * settled, so a piece of the next message never reaches the app before the message ahead of it. The client waits for
+ * the last of them before it hands back the turn's answer.
+ */
 export interface BuyStreamHandlers {
     onProgress?: (progress: BuyProgress) => void;
-    /** The client waits for what this returns before it hands back the turn's answer. */
+    /** Each step the turn starts, as a line to show while the shopper waits. */
+    onStatus?: (status: BuyTurnStatus) => void;
+    /** How many products the turn found, each time the count grows. */
+    onFound?: (update: BuyFoundUpdate) => void | Promise<void>;
     onCatalog?: (update: BuyCatalogUpdate) => void | Promise<void>;
+    /** Each message Agentcard writes, the moment it is written. */
+    onSegment?: (update: BuySegmentUpdate) => void | Promise<void>;
+    /** The carts, each time the turn builds or changes one. */
+    onCart?: (update: BuyCartUpdate) => void | Promise<void>;
+    /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
+    onDelta?: (update: BuyDeltaUpdate) => void | Promise<void>;
 }
 export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
 export declare const BUY_TURN_TIMEOUT_MS = 130000;
+/** The W3C trace context a `POST /buy` carries, so the backend's spans join the caller's trace. */
+export interface TraceContext {
+    traceparent: string;
+    tracestate?: string;
+}
+/** The part of `@opentelemetry/api` the client calls: pass the module itself as `otel`. */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string): OtelTracer;
+    };
+    context: {
+        active(): unknown;
+    };
+    propagation: {
+        inject(context: unknown, carrier: Record<string, string>): void;
+    };
+}
+interface OtelTracer {
+    startActiveSpan<T>(name: string, options: {
+        kind?: number;
+        attributes?: Record<string, string | boolean>;
+    }, fn: (span: OtelSpan) => T): T;
+}
+interface OtelSpan {
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(): void;
+}
+/**
+ * How the client finds the trace a `POST /buy` belongs to. `otel` is `@opentelemetry/api`: by default the client
+ * loads it when the app installed it, and `false` turns that off. `traceContext` names the trace by hand, for an app
+ * without OpenTelemetry: return its `traceparent`, or nothing to send none. The active OpenTelemetry context wins.
+ */
+export interface AgentcardTraceOptions {
+    otel?: OtelApi | false;
+    traceContext?: () => TraceContext | string | null | undefined;
+}
 /** A company's client credentials, or one shopper's own access token. */
 export type AgentcardClientOptions = {
     baseUrl?: string;
     fetch?: FetchLike;
+    trace?: AgentcardTraceOptions;
 } & ({
     clientId: string;
     clientSecret: string;
@@ -155,7 +253,8 @@ export interface BuyCart {
     items: BuyCartLine[];
     /** The items alone, or null from an older API. */
     subtotalCents: number | null;
-    serviceFeesCents: number;
+    serviceFeesCents: number | null;
+    serviceFeesStatus?: 'known' | 'pending' | 'unknown';
     /** The store's own fee and tax lines inside `serviceFeesCents`, or null when the store itemized none. */
     merchantFeeLines: BuyCartFeeLine[] | null;
     tipCents: number;
@@ -393,6 +492,7 @@ export declare class AgentcardClient {
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     private readonly inbox;
     private readonly deliveredIds;
+    private readonly trace;
     constructor(options: AgentcardClientOptions);
     /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
     get company(): boolean;
@@ -459,3 +559,4 @@ export declare class AgentcardClient {
     private renewAfter;
     private exchange;
 }
+export {};