@agent-cards/commerce-sdk 0.9.0 → 0.10.0

package/dist/buy-tool.js

@@ -21,12 +21,70 @@
  * still finishing gets one 12-second pause and one read of the conversation.
  * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
  * to a minute, until the turn ends.
+ *
+ * `turn` binds the tool to one shopper message: the calls the model makes
+ * through it hand their links, answers and instant reply to that turn's own
+ * callbacks and lists, so a shopper who sends a second message before the
+ * first is answered never gets one message's cards beside the other's reply.
+ * Every turn of one tool still shares the shopper's conversation state, such
+ * as the store pages already sent. A turn with `onItem` hands the app its
+ * 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 { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
-import { forModel, forModelError, money, pickId, shownProducts, shownStores } from './model-view.js';
-import { toMessages } from './messages.js';
-import { ackAt, instantAck as instantAckOf, isNewRequest, isPickText, nextTemplate } from './ack.js';
+import { forModel, forModelError, money, pickId, productCardKey, shownProducts, shownStores, stripLinks } from './model-view.js';
+import { messageStream, paceOf, sleep, toMessages, typingHook } from './messages.js';
+import { ackAt, answersQuestion, instantAck as instantAckOf, isNewRequest, isPickText, namesStore, nextTemplate, slowStepLine, waitAt } from './ack.js';
+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
+ * words. Agentcard's words join a last assistant message of plain text, a string or text parts only,
+ * so no provider reads two assistant messages in a row. After anything else, such as a tool result
+ * or an OpenAI Responses item, they come as an assistant message of their own.
+ */
+export function turnMessages(history, told, shopperText) {
+    if (history !== undefined && history !== null && !Array.isArray(history))
+        throw new TypeError("Pass the model's history as an array of messages, or leave it out.");
+    const out = [...(history ?? [])];
+    const said = told.map((text) => text.trim()).filter((text) => text !== '');
+    if (said.length > 0) {
+        const last = out.at(-1);
+        const content = isObject(last) && last.role === 'assistant' ? last.content : undefined;
+        if (typeof content === 'string') {
+            // The model's own words stay as it wrote them.
+            out[out.length - 1] = { ...last, content: content.trim() === '' ? said.join('\n\n') : [content, ...said].join('\n\n') };
+        }
+        else if (Array.isArray(content) && content.length > 0 && content.every((part) => isObject(part) && part.type === 'text' && typeof part.text === 'string')) {
+            out[out.length - 1] = { ...last, content: [...content, ...said.map((text) => ({ type: 'text', text }))] };
+        }
+        else {
+            out.push({ role: 'assistant', content: said.join('\n\n') });
+        }
+    }
+    out.push({ role: 'user', content: shopperText });
+    return out;
+}
+/** What the model reads of a message Agentcard posted into the chat: its text with every link taken out, as `forModel` takes them out. */
+const modelText = (message) => stripLinks(String(message.text ?? ''));
+/** How often the history held a message's text when the message first went in to the model. */
+const offeredAt = new WeakMap();
+/** How many times `needle` appears in `haystack`, none overlapping. */
+function occurrences(haystack, needle) {
+    let count = 0;
+    for (let at = haystack.indexOf(needle); needle !== '' && at !== -1; at = haystack.indexOf(needle, at + needle.length))
+        count++;
+    return count;
+}
+/** The history as JSON text, to find a message it already holds, or empty text for one JSON cannot write. */
+function historyText(history) {
+    try {
+        return JSON.stringify(history ?? []) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
 /** The pause before the one read that follows a placement Agentcard is still finishing. */
 const PLACEMENT_WAIT_MS = 12_000;
 /** After a turn that outlived Agentcard's budget: one read every 5 seconds, for at most a minute. */
@@ -104,7 +162,7 @@ function productsOfCatalog(catalog) {
 }
 /** The stores an answer presents, as the tool reads them. */
 function storesOf(stores) {
-    return (stores?.items ?? []).map((store) => ({ id: store.id, name: store.name, url: store.store_page_url, etaMinutes: store.eta_minutes, linkSent: false }));
+    return (stores?.items ?? []).map((store) => ({ id: store.id, name: store.name, url: store.store_page_url, etaMinutes: store.eta_minutes, imageUrl: store.image_url, linkSent: false }));
 }
 /** The store login link an answer carries, read from its own fields: a link in `reply` is never pulled out. */
 function storeLoginOf(turn) {
@@ -275,6 +333,120 @@ function needsCard(link, body) {
         envelope: body,
     };
 }
+/** The way a turn hands over a link, or undefined when it has nowhere to send one. */
+function senderOf(t) {
+    if (!t.sendLink && !t.links)
+        return undefined;
+    return async (link) => {
+        if (t.sendLink)
+            await t.sendLink(link);
+        // A link sendLink threw on never reached the shopper, so the turn does not list it.
+        t.links?.push({ ...link });
+    };
+}
+/**
+ * A turn's items, one at a time and in order: each one goes out once the one before it settled, and a
+ * `text` item first waits for its pause since the item before it (`pauseOf`). `items` lists each item
+ * that went out, in order. A failed item stays out of `items` and never stops the next one.
+ */
+function itemFeed(pauseOf, typing) {
+    const items = [];
+    // The item going out now, or null when none is: an item pushed while none is goes out at once.
+    let tail = null;
+    let lastAt = null;
+    const sent = (item) => {
+        items.push(item.kind === 'link' ? { kind: 'link', link: { ...item.link } } : { ...item });
+    };
+    /** Sends one item now: settled when its send settled, and listed once it succeeded. */
+    const sendNow = (item, send) => {
+        let out;
+        try {
+            out = send();
+        }
+        catch (error) {
+            lastAt = Date.now();
+            return Promise.reject(error);
+        }
+        if (out && typeof out.then === 'function') {
+            return Promise.resolve(out).then(() => {
+                lastAt = Date.now();
+                sent(item);
+            }, (error) => {
+                lastAt = Date.now();
+                throw error;
+            });
+        }
+        lastAt = Date.now();
+        sent(item);
+        return Promise.resolve();
+    };
+    /**
+     * Adds an item to the feed. `skip` is read when the item's turn comes: true leaves it unsent and
+     * unlisted, with no pause, as for the rest of a reply whose earlier message failed.
+     */
+    const push = (item, send, skip = () => false) => {
+        // Each message's pause is chosen once, when it joins the feed, so a pace that varies never makes it wait twice.
+        const pause = item.kind === 'text' && pauseOf ? pauseOf(item.text) : 0;
+        const waitFor = () => (pause > 0 && lastAt !== null ? lastAt + pause - Date.now() : 0);
+        let run;
+        if (tail === null && (skip() || waitFor() <= 0)) {
+            run = skip() ? Promise.resolve() : sendNow(item, send);
+        }
+        else {
+            run = (tail ?? Promise.resolve()).then(async () => {
+                if (skip())
+                    return;
+                const wait = waitFor();
+                if (wait > 0) {
+                    typing(true);
+                    await sleep(wait);
+                    typing(false);
+                }
+                await sendNow(item, send);
+            });
+        }
+        const settled = run.catch(() => { }).then(() => {
+            if (tail === settled)
+                tail = null;
+        });
+        tail = settled;
+        return run;
+    };
+    return { items, push };
+}
+/**
+ * One reply's messages in a turn's feed: each one takes its place in the feed the moment it is cut,
+ * so no link overtakes it, and once one fails to send, none after it goes out, as `messageStream`
+ * stops after a failed send. `settled` resolves once every one went out or was left out, and rejects
+ * with the first failure.
+ */
+function feedReply(text) {
+    const sends = [];
+    let failure = null;
+    const add = (message) => {
+        sends.push(text(message, () => failure !== null).catch((error) => {
+            failure ??= { error };
+        }));
+    };
+    const settled = async () => {
+        await Promise.all(sends);
+        if (failure)
+            throw failure.error;
+    };
+    return { add, settled };
+}
+/** A message stream for a turn's feed: the messages it cuts are one reply, `feedReply`'s. */
+function feedStream(text) {
+    const reply = feedReply(text);
+    const inner = messageStream({ onMessage: reply.add, pace: false });
+    return {
+        push: (delta) => inner.push(delta),
+        end: async () => {
+            await inner.end();
+            await reply.settled();
+        },
+    };
+}
 /**
  * The order this purchase's checkout produced: the last checkout's own order, or the newest order
  * placed since the last checkout, one that did not stop first. Agentcard clears the last checkout when
@@ -351,8 +523,8 @@ export function buyTool(options) {
     const onProgress = o.onProgress;
     if (o.earlyCards !== undefined && typeof o.earlyCards !== 'boolean')
         throw new TypeError('Pass earlyCards as true or false.');
-    const earlyCards = o.earlyCards === true && !!o.sendLink;
-    const streams = o.stream !== false && (earlyCards || !!onProgress);
+    // 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;
     if (o.onResult !== undefined && typeof o.onResult !== 'function') {
         throw new TypeError('Pass onResult as a function that takes each answer.');
     }
@@ -370,17 +542,35 @@ export function buyTool(options) {
         throw new TypeError('Pass ackDelayMs as a number of milliseconds, 0 or more.');
     const onWorking = o.ack === false ? undefined : o.onWorking;
     const writeAck = typeof o.ack === 'function' ? o.ack : null;
-    /** Calls running now, when the last one ended, whether this turn's instant reply is taken, and the template it used last. */
+    /** Calls running now, when the last one ended, and the template the instant reply used last. */
     let running = 0;
     let lastEndedAt = Number.NEGATIVE_INFINITY;
-    let turnAcked = false;
     let lastTemplate = -1;
     /** Counts the model's turns: the calls of one turn share its number. */
     let modelTurn = 0;
-    /** This turn's instant reply while it is being sent: every call of the turn waits for it before it hands over a link. */
-    let ackOut = null;
-    /** True once `onWorking` delivered this turn's instant reply, so the model is told not to acknowledge again. */
-    let ackDelivered = false;
+    /** A turn with the tool's own callbacks and nothing collected: the turn a call made straight on the tool belongs to. */
+    const toolTurn = (number) => ({
+        number,
+        acked: false,
+        neutral: false,
+        picked: null,
+        ackOut: null,
+        ackDelivered: false,
+        sendLink,
+        onWorking,
+        onResult,
+        onProgress,
+        links: null,
+        results: null,
+        pages: null,
+        storePages: null,
+    });
+    /**
+     * The turn the calls made straight on the tool belong to, which the tool tells apart by timing. A call
+     * captures its turn when it starts, so a later message opening the next one never changes what a call
+     * still running for an earlier message waits for or tells the model.
+     */
+    let implicit = toolTurn(0);
     /**
      * The app's instant reply for the shopper's newest message, waiting for the model's first call on that
      * message, and the step the last answer asked the shopper for. A call still running for an earlier
@@ -390,40 +580,60 @@ 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;
-    /** True for a turn whose message `instantAck` sent no reply for and that picks nothing: a slow call still tells the shopper, in words that name nothing. */
-    let neutralTurn = false;
     /** 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));
     };
-    /** The app's own instant reply: the turn its message opens sends no `onWorking` reply. */
-    const instantAck = (shopperText) => {
+    /** 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. */
+    const namesShown = (text) => namesShownProduct(text) || namesStore(text, shownStoreNames);
+    /** What a message picks: a product it names (`product`), a store or a place in a list (`pick`), or nothing (null). */
+    const pickOf = (text) => namesStore(text, shownStoreNames) ? 'pick' : namesShownProduct(text) ? 'product' : isPickText(text) ? 'pick' : null;
+    /** How the shopper's message reads for the instant reply: what it picks, and the reply it gets, or null. */
+    const ackOfMessage = (shopperText) => {
         const text = String(shopperText ?? '');
-        // A shopper who sends a product's name, as a tap on its card does, picks it: no "looking for" reply.
-        const pick = namesShownProduct(text) || isPickText(text);
-        const said = !pick && instantAckOf(text, { nextAction: lastNextAction, asked: lastReply }) !== null;
+        // A shopper who sends a product's or a store's name, as a tap on its card does, picks it: no "looking for" reply.
+        const picked = pickOf(text);
+        const said = !picked && instantAckOf(text, { nextAction: lastNextAction, asked: lastReply }) !== null;
         // The same rotation onWorking uses, so the next reply comes from another template.
         if (said)
             lastTemplate = nextTemplate(lastTemplate);
-        appAck = { at: Date.now(), said, pick };
-        return said ? ackAt(lastTemplate, text) : null;
+        return { picked, text: said ? ackAt(lastTemplate, text) : null };
+    };
+    /** The app's own instant reply: the turn its message opens sends no `onWorking` reply. */
+    const instantAck = (shopperText) => {
+        const { picked, text } = ackOfMessage(shopperText);
+        appAck = { at: Date.now(), said: text !== null, picked };
+        return text;
     };
     /**
      * Holds the instant reply for a new request until `ackDelayMs` passes. `cancel` stops one that has
      * not gone out, and frees the turn's reply for a later call.
      */
-    const holdAck = (ask, neutral) => {
-        if (!onWorking || turnAcked || (!neutral && (!isNewRequest(ask) || namesShownProduct(ask))))
+    const holdAck = (ask, t, step = null) => {
+        const onWorking = t.onWorking;
+        if (!onWorking || t.acked)
+            return null;
+        // A confirm, or a pick of what the shopper saw, gets fixed words that never say `looking for`.
+        const slow = step ?? t.picked ?? (!t.neutral && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
+        // A short answer to the question the last reply asked, such as `medium` after `what size?`, is no
+        // search: like `yes`, a slow call still tells the shopper, in words that look for nothing.
+        const neutral = t.neutral || answersQuestion(ask, lastReply);
+        if (!slow && !neutral && !isNewRequest(ask))
             return null;
-        turnAcked = true;
+        t.acked = true;
         let held = true;
         const timer = setTimeout(() => {
             held = false;
             let text;
-            // A neutral turn's message held no request safe to read back, so no writer sees it.
-            if (writeAck && !neutral) {
+            if (slow) {
+                text = slowStepLine(slow);
+            }
+            else if (writeAck && !neutral) {
+                // A neutral turn's message held no request safe to read back, so no writer sees it.
                 try {
                     text = writeAck(ask);
                 }
@@ -433,17 +643,18 @@ export function buyTool(options) {
             }
             else {
                 lastTemplate = nextTemplate(lastTemplate);
-                // A neutral reply names nothing: the shopper's message held no request safe to read back.
-                text = ackAt(lastTemplate, neutral ? '' : ask);
+                // A neutral turn's message, such as `yes` or `ok lets checkout`, is no search: its reply says the
+                // tool is working, and never that it is looking for anything.
+                text = neutral ? waitAt(lastTemplate) : ackAt(lastTemplate, ask);
             }
             if (typeof text !== 'string' || text.trim() === '') {
-                turnAcked = false;
+                t.acked = false;
                 return;
             }
             const message = text.trim();
-            ackOut = Promise.resolve()
+            t.ackOut = Promise.resolve()
                 .then(() => onWorking(message))
-                .then(() => { ackDelivered = true; }, () => { });
+                .then(() => { t.ackDelivered = true; }, () => { });
         }, ackDelayMs);
         return {
             cancel: () => {
@@ -451,7 +662,7 @@ export function buyTool(options) {
                     return;
                 held = false;
                 clearTimeout(timer);
-                turnAcked = false;
+                t.acked = false;
             },
         };
     };
@@ -673,9 +884,10 @@ export function buyTool(options) {
     /** The store pages this tool sent last, with their conversation, the model turn that sent them, and the search they list. */
     let lastPages = null;
     /**
-     * The store page of each product the model reads, sent once per page. A
-     * page the last batch in this conversation already sent stays with the
-     * shopper and goes out no second time, unless a later model turn's reply
+     * A card for each product the model reads, with its store page, sent once
+     * per product: two dishes on a restaurant's one page are two cards. A card
+     * the last batch in this conversation already sent stays with the shopper
+     * and goes out no second time, unless a later model turn's reply
      * presents the products again (the catalog's `presented`): a repeated ask
      * answered with the same products gets their pages beside it, so every
      * product the reply names has a card. Calls of one model turn still send a
@@ -684,41 +896,54 @@ export function buyTool(options) {
      * that lists them again sends none twice. A page whose `sendLink` throws
      * stays unsent, and the call goes on, so the next answer tries it again.
      */
-    const deliverPages = async (result, call) => {
-        if (!sendLink)
+    const deliverPages = async (result, call, send) => {
+        if (!send)
             return result;
-        const pages = new Map();
+        // One card per product the model reads, so a restaurant's dishes, which all carry the store's one page, are a card each.
+        const cards = new Map();
         for (const product of shownProducts(result.products)) {
-            if (product.url && !pages.has(product.url))
-                pages.set(product.url, product);
+            const key = productCardKey(product);
+            if (key && !cards.has(key))
+                cards.set(key, product);
         }
         // An answer with no store page leaves the last batch as it was.
-        if (pages.size === 0)
+        if (cards.size === 0)
             return result;
-        const kept = lastPages?.conversationId === result.conversation_id && (!call.presented || lastPages.turn === call.turn);
-        const before = kept && lastPages ? lastPages.urls : new Set();
+        // An answer that presents its products reads the last batch of its own turn: another turn's batch
+        // sent in between, as when the shopper's next message answers first, never makes it send its cards again.
+        const last = call.presented && lastPages?.turn !== call.turn && call.owner.pages ? call.owner.pages : lastPages;
+        const kept = last?.conversationId === result.conversation_id && (!call.presented || last.turn === call.turn);
+        const before = kept && last ? last.keys : new Set();
         // Agentcard names the search an answer lists by when it ran. An answer that lists fewer of the same
-        // search's products, such as a pick's, keeps every page that search already sent, so a later answer
+        // search's products, such as a pick's, keeps every card that search already sent, so a later answer
         // that lists them again sends none twice.
         const catalog = result.envelope?.catalog;
         const search = typeof catalog?.as_of === 'string' ? catalog.as_of : null;
-        const sameSearch = kept && search !== null && lastPages?.search === search;
+        const sameSearch = kept && search !== null && last?.search === search;
         const held = new Set(sameSearch ? before : []);
-        for (const [url, product] of pages) {
-            if (!before.has(url)) {
+        for (const [key, product] of cards) {
+            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);
-                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), ...(productId ? { productId } : {}), imageUrl: product.imageUrl, expiresAt: null });
+                    // 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 });
                 }
                 catch {
                     continue;
                 }
             }
-            held.add(url);
+            held.add(key);
         }
-        lastPages = { conversationId: result.conversation_id, turn: call.turn, search, urls: held };
-        return { ...result, products: result.products.map((product) => (product.url && held.has(product.url) ? { ...product, linkSent: true } : product)) };
+        lastPages = { conversationId: result.conversation_id, turn: call.turn, search, keys: held };
+        call.owner.pages = lastPages;
+        return {
+            ...result,
+            products: result.products.map((product) => {
+                const key = productCardKey(product);
+                return key && held.has(key) ? { ...product, linkSent: true } : product;
+            }),
+        };
     };
     /** The products a streamed search found, as an answer the page delivery reads: its conversation, its search and its products. */
     const earlyPages = (conversationId, asOf, products) => ({ conversation_id: conversationId, envelope: { catalog: { as_of: asOf } }, products });
@@ -731,17 +956,19 @@ export function buyTool(options) {
      * whose id holds a link is left out, as the model view leaves it out. A page whose `sendLink`
      * throws stays unsent, and the call goes on.
      */
-    const deliverStorePages = async (result, call) => {
-        if (!sendLink || !result.stores?.length)
+    const deliverStorePages = async (result, call, send) => {
+        if (!send || !result.stores?.length)
             return result;
-        const kept = lastStorePages?.conversationId === result.conversation_id && lastStorePages.turn === call.turn;
-        const held = new Set(kept && lastStorePages ? lastStorePages.urls : []);
+        // A turn reads its own last batch when another turn's replaced it in between, so it never sends a store's page twice.
+        const last = lastStorePages?.turn !== call.turn && call.owner.storePages ? call.owner.storePages : lastStorePages;
+        const kept = last?.conversationId === result.conversation_id && last.turn === call.turn;
+        const held = new Set(kept && last ? last.urls : []);
         for (const store of shownStores(result.stores)) {
             if (!store.url)
                 continue;
             if (!held.has(store.url)) {
                 try {
-                    await sendLink({ kind: 'store', url: store.url, title: store.name, storeId: store.id, etaMinutes: store.etaMinutes, expiresAt: null });
+                    await send({ kind: 'store', url: store.url, title: store.name, storeId: store.id, etaMinutes: store.etaMinutes, imageUrl: store.imageUrl, expiresAt: null });
                 }
                 catch {
                     continue;
@@ -750,26 +977,31 @@ export function buyTool(options) {
             held.add(store.url);
         }
         lastStorePages = { conversationId: result.conversation_id, turn: call.turn, urls: held };
+        call.owner.storePages = lastStorePages;
         return { ...result, stores: result.stores.map((store) => (store.url && held.has(store.url) ? { ...store, linkSent: true } : store)) };
     };
     /** One batch of pages at a time: a call that overlaps another reads the pages that one sent. */
     let pagesInTurn = Promise.resolve();
-    const deliverPagesInTurn = (result, call) => {
-        const batch = pagesInTurn.then(() => deliverPages(result, call)).then((delivered) => deliverStorePages(delivered, call));
+    const deliverPagesInTurn = (result, call, send) => {
+        const batch = pagesInTurn.then(() => deliverPages(result, call, send)).then((delivered) => deliverStorePages(delivered, call, send));
         pagesInTurn = batch.catch(() => { });
         return batch;
     };
-    /** The Vault or approval link first, because the purchase waits on it, then the store pages. */
-    const deliver = async (result, call) => {
+    /** 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 && sendLink) {
+        if (result.links.length > 0 && send) {
             for (const link of result.links)
-                await sendLink({ ...link });
+                await send({ ...link });
             delivered = { ...result, link_sent: true };
         }
-        return deliverPagesInTurn(delivered, call);
+        return deliverPagesInTurn(delivered, call, send);
     };
-    const answer = async (raw) => {
+    /**
+     * 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();
         const input = parseBuyToolInput(raw);
         // A new order is never a confirm: a model that sets both drops the cart and places nothing.
@@ -790,47 +1022,49 @@ export function buyTool(options) {
         };
         // 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.
-        const opened = appAck && Date.now() - appAck.at < APP_TURN_MS ? appAck : null;
-        appAck = null;
-        if (opened) {
-            // Only a reply the app sent, or a pick, quiets onWorking: a message such as `yes` that starts a
-            // slow search still gets a reply that names nothing.
-            turnAcked = opened.said || opened.pick;
-            neutralTurn = !turnAcked;
-            ackOut = null;
-            ackDelivered = opened.said;
-            modelTurn += 1;
-        }
-        else if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
-            turnAcked = false;
-            neutralTurn = false;
-            ackOut = null;
-            ackDelivered = false;
-            modelTurn += 1;
+        // working through the same turn. A call made through `buy.turn` belongs to that turn alone.
+        if (!explicit) {
+            const opened = appAck && Date.now() - appAck.at < APP_TURN_MS ? appAck : null;
+            appAck = null;
+            if (opened) {
+                // Only a reply the app sent quiets onWorking. A message such as `yes` that starts a slow search
+                // still gets a reply that names nothing, and a slow pick gets one that says it is on it.
+                implicit = { ...toolTurn(++modelTurn), acked: opened.said, neutral: !opened.said && !opened.picked, picked: opened.picked, ackDelivered: opened.said };
+            }
+            else if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
+                implicit = toolTurn(++modelTurn);
+            }
         }
-        const callTurn = modelTurn;
+        // The call keeps the turn it started in, whichever turn opens while it runs.
+        const t = explicit ?? implicit;
+        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;
         running += 1;
-        // A pick adds a product the shopper already saw, so no "looking for" reply goes out, as for "the first one".
-        const ack = confirm || pick ? null : holdAck(ask, neutralTurn);
+        // 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);
         try {
             let turn = null;
             let refusal;
             // Streamed: the stages go to onProgress, and a search's store pages go out the moment it answers.
             const handlers = streams
                 ? {
-                    ...(onProgress ? { onProgress: (progress) => { try {
-                            onProgress(progress);
+                    ...(progressOf ? { onProgress: (progress) => { try {
+                            progressOf(progress);
                         }
                         catch { /* the app's display failing never fails the call */ } } } : {}),
-                    ...(earlyCards && sendLink && !confirm
+                    ...(early
                         ? {
                             onCatalog: async (update) => {
                                 // Products arrived before the instant reply was due: they are the reply.
                                 ack?.cancel();
-                                await ackOut;
+                                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 });
+                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, productsOfCatalog(update.catalog)), { turn: callTurn, presented: true, owner: t }, send);
                             },
                         }
                         : {}),
@@ -844,18 +1078,23 @@ export function buyTool(options) {
             }
             ack?.cancel();
             const settled = turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt);
-            await ackOut;
-            const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true });
-            const result = ackDelivered ? { ...delivered, shopper_already_told_looking: true } : delivered;
+            await t.ackOut;
+            const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
+            const result = t.ackDelivered ? { ...delivered, shopper_already_told_looking: true } : delivered;
             lastNextAction = result.next_action;
             lastReply = result.reply;
             // 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)
                 shownNames = shown.map((product) => productWords(product.name)).filter((name) => name.length >= MIN_NAME_LENGTH);
-            if (onResult) {
+            // An answer that lists stores replaces their names, as one that lists products replaces the products'.
+            const storesShown = shownStores(result.stores);
+            if (storesShown.length > 0)
+                shownStoreNames = storesShown.map((store) => store.name);
+            t.results?.push(result);
+            if (t.onResult) {
                 try {
-                    await onResult(result);
+                    await t.onResult(result);
                 }
                 catch {
                     // The app's display failing never fails the purchase call.
@@ -869,6 +1108,7 @@ export function buyTool(options) {
             lastEndedAt = Date.now();
         }
     };
+    const answer = (raw) => answerIn(raw, null);
     /** Checks the model's input, with every link taken out of a refusal. */
     const parse = (input) => {
         try {
@@ -879,21 +1119,160 @@ export function buyTool(options) {
         }
     };
     /** Every call a framework makes: the model's input, checked, then the model's view of the answer as JSON text. */
-    const handle = async (args) => {
+    const handlerOf = (answerCall) => async (args) => {
         try {
-            return JSON.stringify(forModel(await answer(parseBuyToolInput(args))));
+            return JSON.stringify(forModel(await answerCall(parseBuyToolInput(args))));
         }
         catch (error) {
             throw forModelError(error);
         }
     };
     const { name, description, input_schema } = buyToolDefinition();
-    const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer, forModel, instantAck };
-    // JSON skips these three, so a runner that sends the tool to its API as is sends Anthropic's fields and nothing else.
+    // JSON skips these, so a runner that sends the tool to its API as is sends Anthropic's fields and nothing else.
     const unsent = (value) => ({ value, enumerable: false, writable: true, configurable: true });
-    return Object.defineProperties(tool, {
-        definition: unsent(buyToolDefinition()),
-        inputSchema: unsent(buyToolStandardSchema((error) => forModelError(error).message)),
-        openai: unsent(openAIBuyTool()),
-    });
+    /** The fields every framework reads and the methods it calls, around one way to answer a call. */
+    const toolOf = (answerCall, own, hidden) => {
+        const handle = handlerOf(answerCall);
+        const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer: answerCall, forModel, ...own };
+        return Object.defineProperties(tool, {
+            definition: unsent(buyToolDefinition()),
+            inputSchema: unsent(buyToolStandardSchema((error) => forModelError(error).message)),
+            openai: unsent(openAIBuyTool()),
+            ...hidden,
+        });
+    };
+    /**
+     * The turn of one shopper message. It takes the next turn number, so its calls never share a turn
+     * with another message's, and it sends its instant reply at once, as `instantAck` would read it.
+     */
+    const turn = (shopperText, 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', 'onResult', 'onProgress', 'onItem']) {
+            if (own[key] !== undefined && typeof own[key] !== 'function')
+                throw new TypeError(`Pass ${key} to the turn as a function, or leave it out.`);
+        }
+        const onItem = own.onItem;
+        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.');
+        }
+        // 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));
+        // 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);
+        const state = {
+            ...toolTurn(++modelTurn),
+            sendLink: (link) => feed.push({ kind: 'link', link }, () => (onItem ? onItem({ kind: 'link', link: { ...link } }) : baseSendLink?.(link))),
+            onWorking: acks ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
+            onResult: own.onResult ?? onResult,
+            onProgress: own.onProgress ?? onProgress,
+            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);
+        let ack = null;
+        const working = state.onWorking;
+        if (working) {
+            const message = String(shopperText ?? '');
+            const read = ackOfMessage(message);
+            let text = read.text;
+            if (text !== null && writeAck) {
+                try {
+                    text = writeAck(message) ?? null;
+                }
+                catch {
+                    text = null;
+                }
+                text = typeof text === 'string' && text.trim() !== '' ? text.trim() : null;
+            }
+            if (read.picked) {
+                // A pick of a product or a store the shopper saw gets no "looking for" reply; a slow call says it is on it.
+                state.picked = read.picked;
+            }
+            else if (read.text === null) {
+                // A message that starts no search, such as `yes`: a slow call still tells the shopper, in words that name nothing.
+                state.neutral = true;
+            }
+            else if (text !== null) {
+                ack = text;
+                state.acked = true;
+                let sent;
+                try {
+                    sent = working(text);
+                }
+                catch (error) {
+                    sent = Promise.reject(error);
+                }
+                // Every call of the turn waits for it before it hands over a link, and a failed send costs only the reply.
+                state.ackOut = Promise.resolve(sent).then(() => { state.ackDelivered = true; }, () => { });
+            }
+            // An ack writer that wrote nothing for a new request leaves the slow call to ask it again, with the model's words.
+        }
+        const links = state.links;
+        const results = state.results;
+        // What Agentcard told the shopper that no history the model ran with holds yet.
+        const kept = client.company ? client.keptMessages(externalUserId) : [];
+        let handed = null;
+        const shopperWords = String(shopperText ?? '');
+        /**
+         * The model's messages for this turn. A kept message whose text the history holds more often than
+         * when the message first went in reached the model on a turn whose history the app saved, so the
+         * client forgets it. One the history lacks, as after a turn that failed before its history was
+         * saved, goes in again.
+         */
+        const messagesFor = (history) => {
+            const held = historyText(history);
+            const saved = [];
+            const fresh = [];
+            for (const message of kept) {
+                const text = modelText(message);
+                if (text === '') {
+                    saved.push(message);
+                    continue;
+                }
+                // Another order's update can read the same, so only a history holding the text more often than
+                // when this message first went in holds this message.
+                const count = occurrences(held, JSON.stringify(text).slice(1, -1));
+                const before = offeredAt.get(message);
+                if (before !== undefined && count > before) {
+                    saved.push(message);
+                }
+                else {
+                    if (before === undefined)
+                        offeredAt.set(message, count);
+                    fresh.push(message);
+                }
+            }
+            if (saved.length > 0)
+                client.forgetMessages(externalUserId, saved);
+            handed = fresh;
+            return turnMessages(history, fresh.map(modelText), shopperWords);
+        };
+        return toolOf((raw) => answerIn(raw, state), {}, {
+            agentcardMessages: { get: () => [...(handed ?? kept)], enumerable: false },
+            messages: { value: messagesFor, enumerable: false },
+            ack: { value: ack, enumerable: false },
+            links: { get: () => [...links], enumerable: false },
+            results: { get: () => [...results], 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 },
+            say: {
+                value: (whole) => {
+                    const reply = feedReply(text);
+                    for (const message of toMessages(whole))
+                        reply.add(message);
+                    return reply.settled();
+                },
+                enumerable: false,
+            },
+        });
+    };
+    return toolOf(answer, { instantAck, turn }, {});
 }