@agent-cards/commerce-sdk 0.5.0 → 0.9.0

package/dist/buy-tool.d.ts

@@ -22,7 +22,7 @@
  * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
  * to a minute, until the turn ends.
  */
-import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type FetchLike } from './client.js';
+import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type BuyToolModelView } from './model-view.js';
 /**
@@ -40,10 +40,12 @@ export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'pl
  * card. `approval`: the page where they approve this purchase. `store_login`:
  * the page where they sign in to the store named in `store`, before Agentcard
  * can buy there. `product`: a product's page at its store, with its `title`,
- * `price`, `productId` and `imageUrl`.
+ * `price`, `productId` and `imageUrl`. The page is `url`; `productId` holds no link.
+ * `store`: a store's page at the merchant, for a store the shopper can pick, with
+ * its name in `title`, `storeId` and `etaMinutes`.
  */
 export interface BuyToolLink {
-    kind: 'vault' | 'approval' | 'store_login' | 'product';
+    kind: 'vault' | 'approval' | 'store_login' | 'product' | 'store';
     url: string;
     /** When the link stops working, as an ISO 8601 timestamp, or null when Agentcard did not say. Always null on a product link. */
     expiresAt: string | null;
@@ -53,10 +55,34 @@ export interface BuyToolLink {
     title?: string;
     /** On a product link: the price as the shopper reads it, such as `$12.99`, or null when Agentcard named none. */
     price?: string | null;
-    /** On a product link: Agentcard's id for the product. */
+    /**
+     * On a product link: Agentcard's id for the product, with no link in it. It is the `product_id` the
+     * model reads for the same product, and the tool takes it as `product_id`, so a "Buy this" button
+     * can hand it back as the shopper's pick. Absent when Agentcard sent no such id, as an older API does.
+     */
     productId?: string;
     /** On a product link: the product's picture, or null when Agentcard sent none. Show it beside the title. */
     imageUrl?: string | null;
+    /**
+     * On a store link: Agentcard's id for the store, with no link in it. It is the `store_id` the model
+     * reads for the same store, and the tool takes it as `store_id`, so a "Order here" button can hand it
+     * back as the shopper's pick.
+     */
+    storeId?: string;
+    /** On a store link: the store's delivery estimate in minutes, or null when the store showed none. */
+    etaMinutes?: number | null;
+}
+/** A store the answer's reply presents to choose from. */
+export interface BuyToolStore {
+    /** Agentcard's id for the store, with no link in it: the model passes it as `store_id` when the shopper picks this store. */
+    id: string;
+    name: string;
+    /** The store's page at the merchant, or null when Agentcard sent none. */
+    url: string | null;
+    /** The delivery estimate in minutes, or null when the store showed none. */
+    etaMinutes: number | null;
+    /** True when the shopper holds this store's page: `sendLink` took it in this call or an earlier call of the same model turn. */
+    linkSent: boolean;
 }
 /** A product the last search found. */
 export interface BuyToolProduct {
@@ -104,6 +130,11 @@ export interface BuyToolResult {
     approval_expires_at: string | null;
     /** True when Agentcard tells the shopper how the order went, so the shopper need not reply. */
     shopper_need_not_reply: boolean;
+    /**
+     * True when `onWorking` delivered this turn's instant reply, such as `got it, finding a taco`, so the
+     * shopper already heard that the request is being worked on. Absent or false when none went out.
+     */
+    shopper_already_told_looking?: boolean;
     conversation_id: string | null;
     order_id: string | null;
     decline_code: string | null;
@@ -112,6 +143,10 @@ export interface BuyToolResult {
     next_action: BuyNextAction | null;
     /** The product the model's `product_id` picked, by its catalog id, and whether the cart now holds it; null when the call picked none. */
     pick: BuyPick | null;
+    /** The stores the reply presents to choose from, at most three, in the order the reply names them; empty when it presents none. */
+    stores: BuyToolStore[];
+    /** The store the model's `store_id` picked, or the shopper's `the second one` did, and whether Agentcard selected it; null when none was picked. */
+    store_pick: BuyStorePick | null;
     /** Every cart hash in this answer. */
     hashes: string[];
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
@@ -148,10 +183,36 @@ export interface BuyToolOptions {
      * it before any link or the model's answer. One that throws costs nothing but the instant reply.
      */
     onWorking?: (message: string) => void | Promise<void>;
-    /** `false` sends no instant reply. A function writes it from the shopper's words instead, and an empty answer sends none. */
+    /** `false` sends no instant reply. A function writes it from the shopper's words instead, and an empty answer sends none. A turn whose message `instantAck` sent nothing for gets the built-in reply that names nothing. */
     ack?: false | ((ask: string) => string | null | undefined);
     /** How long Agentcard has to answer before the instant reply goes out. Default 1500. */
     ackDelayMs?: number;
+    /**
+     * Called with the whole answer once per call, after its links went out and before the model reads
+     * it, so your app can show the carts, the status, `next_action` or the order id without wrapping the
+     * tool. A refusal the tool turns into an answer, such as a Vault link for a shopper with no card,
+     * counts; a call that throws calls nothing. One that throws costs nothing but the call to it.
+     */
+    onResult?: (result: BuyToolResult) => void | Promise<void>;
+    /**
+     * Called while Agentcard works on a call, with the stage it reached: `searching`, `building_cart`,
+     * `checking_out` or `working`. Show it as a status line. One that throws costs nothing but the call to it.
+     */
+    onProgress?: (progress: BuyProgress) => void;
+    /**
+     * `false` waits for each whole answer. With `onProgress`, or with `earlyCards` and `sendLink`, the
+     * tool asks Agentcard to stream the call, and each stage goes to `onProgress` as it happens.
+     */
+    stream?: false;
+    /**
+     * `true` sends the store pages of a search's first three products to `sendLink` the moment the search
+     * answers, before Agentcard writes its reply, and the answer then sends only the pages it adds. Off by
+     * default: the reply often recommends other products than the search's first three, so a shopper
+     * would hold cards the reply never names. Measured on five live searches on 2026-10-20, the early
+     * pages arrived 2.2 to 3.3 seconds before the answer, and in four of them the reply named a product
+     * outside the first three.
+     */
+    earlyCards?: boolean;
 }
 /**
  * The buy tool, in the shape every agent framework takes, because their field
@@ -193,7 +254,20 @@ export interface BuyTool {
     answer(input: BuyToolInput): Promise<BuyToolResult>;
     /** The answer as the model may read it, with every link taken out. */
     forModel(result: BuyToolResult): BuyToolModelView;
+    /**
+     * The instant reply for a shopper's message, such as `on it, looking for usb-c cables under $20`, or
+     * null for a message that starts no search: `yes`, `1`, `ok`, a code, `hi`, or the shopper's own
+     * details, such as a name, a phone number or an address, and any message that answers a request for
+     * shipping or guest details or a code, and a pick of a product the shopper saw. Call it the moment the
+     * message arrives, before your model runs, and send the text it returns. When it returns a reply, the
+     * tool sends none of its own through `onWorking` for that turn, and the model reads
+     * `shopper_already_told_looking`, so the shopper never hears it twice. When it returns null for a
+     * message that picks nothing, such as `yes`, a slow call still sends `onWorking` a reply that names nothing.
+     */
+    instantAck(shopperText: string): string | null;
 }
+/** Shared with the merchant monitor so link eligibility uses the tool's product mapping. */
+export declare function productsOf(turn: BuyTurn): BuyToolProduct[];
 /**
  * A buy tool for one shopper. With a company client, name the shopper with
  * `externalUserId`; with a shopper's own `accessToken`, the token names them.

package/dist/buy-tool.js

@@ -24,9 +24,9 @@
  */
 import { AgentcardApiError, AgentcardClient, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
-import { forModel, forModelError, money, shownProducts } from './model-view.js';
+import { forModel, forModelError, money, pickId, shownProducts, shownStores } from './model-view.js';
 import { toMessages } from './messages.js';
-import { ackAt, isNewRequest, nextTemplate } from './ack.js';
+import { ackAt, instantAck as instantAckOf, isNewRequest, isPickText, nextTemplate } from './ack.js';
 /** 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. */
@@ -46,6 +46,14 @@ const AFTER_PLACEMENT = new Set(['nothing_to_confirm', 'conversation_closed', 't
 const ACK_DELAY_MS = 1_500;
 /** A call that starts this soon after the last one ended belongs to the same model turn, which gets one instant reply. */
 const SAME_TURN_MS = 15_000;
+/** A product name shorter than this, such as `AA`, is too short to tell a pick from a search. */
+const MIN_NAME_LENGTH = 12;
+/** Text as lowercase words with single spaces, so a product's name is found in a message that quotes it. */
+function productWords(text) {
+    return String(text ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+}
+/** How long after `instantAck` the model's first call still belongs to the turn it acknowledged. */
+const APP_TURN_MS = 120_000;
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
 const CARD_NEEDED = 'The shopper adds a card from a Vault link before Agentcard can buy for them.';
 const STILL_PLACING = 'The shopper approved, and the order is still going through.';
@@ -57,6 +65,7 @@ const ANSWER_LATE = "Agentcard's answer took too long to come back. Call this to
 const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shopper the cart as it stands now.';
 const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper what they want.';
 const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
+const STORE_PICK_GONE = "The store the shopper picked is no longer among the stores Agentcard found, so no store was chosen. Call this tool again with the shopper's words and store_id null, and Agentcard searches again.";
 const PICK_GONE = "The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.";
 /**
  * The pick as a later read of the conversation shows it: a pick the early answer found missing is in
@@ -72,8 +81,13 @@ function pickAfter(pick, carts) {
 function hashesOf(cart, carts) {
     return [...new Set([cart?.hash, ...carts.map((c) => c.hash)].filter((h) => typeof h === 'string' && h !== ''))];
 }
-function productsOf(turn) {
-    return (turn.catalog?.items ?? [])
+/** Shared with the merchant monitor so link eligibility uses the tool's product mapping. */
+export function productsOf(turn) {
+    return turn.catalog ? productsOfCatalog(turn.catalog) : [];
+}
+/** The products of a search, as the tool reads them. */
+function productsOfCatalog(catalog) {
+    return (catalog.items ?? [])
         .filter((item) => item.name)
         .map((item) => ({
         id: item.id,
@@ -83,11 +97,15 @@ function productsOf(turn) {
         currency: item.currency,
         imageUrl: item.image_url,
         ...(item.flight ? { flight: item.flight } : {}),
-        store: item.store?.name ?? item.store?.id ?? turn.catalog?.merchant_name ?? null,
+        store: item.store?.name ?? item.store?.id ?? catalog.merchant_name ?? null,
         url: item.url ?? null,
         linkSent: false,
     }));
 }
+/** 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 }));
+}
 /** The store login link an answer carries, read from its own fields: a link in `reply` is never pulled out. */
 function storeLoginOf(turn) {
     if (!turn.store_login_url)
@@ -113,6 +131,8 @@ function answerOf(turn) {
         error_code: turn.error_code,
         next_action: turn.next_action,
         pick: turn.pick,
+        stores: storesOf(turn.stores),
+        store_pick: turn.store_pick,
         hashes: hashesOf(turn.cart, turn.carts),
         envelope: turn.raw,
     };
@@ -211,6 +231,8 @@ function resultOfRefusal(error) {
         error_code: error.code,
         next_action: null,
         pick: null,
+        stores: [],
+        store_pick: null,
         hashes: hashesOf(null, carts),
         envelope: error.body,
     });
@@ -224,6 +246,8 @@ function resultOfRefusal(error) {
         return answer(STILL_WORKING, []);
     if (error.code === 'pick_not_found')
         return answer(PICK_GONE, []);
+    if (error.code === 'store_pick_not_found')
+        return answer(STORE_PICK_GONE, []);
     return null;
 }
 /** A shopper Agentcard has not connected to this company yet: the Vault link where they connect and add a card. */
@@ -245,6 +269,8 @@ function needsCard(link, body) {
         error_code: 'user_not_connected',
         next_action: 'add_card',
         pick: null,
+        stores: [],
+        store_pick: null,
         hashes: [],
         envelope: body,
     };
@@ -318,6 +344,19 @@ export function buyTool(options) {
         throw new TypeError('Pass sendLink as a function that delivers a link to the shopper.');
     }
     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.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;
+    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);
+    if (o.onResult !== undefined && typeof o.onResult !== 'function') {
+        throw new TypeError('Pass onResult as a function that takes each answer.');
+    }
+    const onResult = o.onResult;
     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.');
@@ -336,21 +375,55 @@ export function buyTool(options) {
     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;
+    /**
+     * 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
+     * message keeps its own turn's state.
+     */
+    let appAck = null;
+    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) => {
+        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;
+        // 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;
+    };
     /**
      * 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) => {
-        if (!onWorking || turnAcked || !isNewRequest(ask))
+    const holdAck = (ask, neutral) => {
+        if (!onWorking || turnAcked || (!neutral && (!isNewRequest(ask) || namesShownProduct(ask))))
             return null;
         turnAcked = true;
         let held = true;
         const timer = setTimeout(() => {
             held = false;
             let text;
-            if (writeAck) {
+            // A neutral turn's message held no request safe to read back, so no writer sees it.
+            if (writeAck && !neutral) {
                 try {
                     text = writeAck(ask);
                 }
@@ -360,14 +433,17 @@ export function buyTool(options) {
             }
             else {
                 lastTemplate = nextTemplate(lastTemplate);
-                text = ackAt(lastTemplate, ask);
+                // A neutral reply names nothing: the shopper's message held no request safe to read back.
+                text = ackAt(lastTemplate, neutral ? '' : ask);
             }
             if (typeof text !== 'string' || text.trim() === '') {
                 turnAcked = false;
                 return;
             }
             const message = text.trim();
-            ackOut = Promise.resolve().then(() => onWorking(message)).catch(() => { });
+            ackOut = Promise.resolve()
+                .then(() => onWorking(message))
+                .then(() => { ackDelivered = true; }, () => { });
         }, ackDelayMs);
         return {
             cancel: () => {
@@ -594,15 +670,21 @@ export function buyTool(options) {
         // A running turn that placed nothing may be a search rather than a placement, so the shopper hears it is still working.
         return settled.status === 'placing' && !placing ? refused : settled;
     };
-    /** The store pages this tool sent last, with their conversation. */
+    /** 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. A page whose `sendLink` throws
+     * 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
+     * page once. An answer that lists fewer of the same search's products, such
+     * as a pick's, keeps the pages that search already sent, so a later answer
+     * 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) => {
+    const deliverPages = async (result, call) => {
         if (!sendLink)
             return result;
         const pages = new Map();
@@ -613,12 +695,21 @@ export function buyTool(options) {
         // An answer with no store page leaves the last batch as it was.
         if (pages.size === 0)
             return result;
-        const before = lastPages?.conversationId === result.conversation_id ? lastPages.urls : new Set();
-        const held = new Set();
+        const kept = lastPages?.conversationId === result.conversation_id && (!call.presented || lastPages.turn === call.turn);
+        const before = kept && lastPages ? lastPages.urls : 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
+        // 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 held = new Set(sameSearch ? before : []);
         for (const [url, product] of pages) {
             if (!before.has(url)) {
                 try {
-                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, imageUrl: product.imageUrl, expiresAt: null });
+                    // 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 });
                 }
                 catch {
                     continue;
@@ -626,25 +717,57 @@ export function buyTool(options) {
             }
             held.add(url);
         }
-        lastPages = { conversationId: result.conversation_id, urls: held };
+        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)) };
     };
+    /** 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 });
+    /** The store pages this tool sent last, with their conversation and the model turn that sent them. */
+    let lastStorePages = null;
+    /**
+     * The page of each store the reply presents, sent once per page in a model turn. Agentcard lists
+     * stores only on an answer whose reply presents them, so a later model turn that presents them
+     * again sends their pages again, and the calls of one model turn send each page once. A store
+     * 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)
+            return result;
+        const kept = lastStorePages?.conversationId === result.conversation_id && lastStorePages.turn === call.turn;
+        const held = new Set(kept && lastStorePages ? lastStorePages.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 });
+                }
+                catch {
+                    continue;
+                }
+            }
+            held.add(store.url);
+        }
+        lastStorePages = { conversationId: result.conversation_id, turn: call.turn, urls: held };
+        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) => {
-        const batch = pagesInTurn.then(() => deliverPages(result));
+    const deliverPagesInTurn = (result, call) => {
+        const batch = pagesInTurn.then(() => deliverPages(result, call)).then((delivered) => deliverStorePages(delivered, call));
         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) => {
+    const deliver = async (result, call) => {
         let delivered = result;
         if (result.links.length > 0 && sendLink) {
             for (const link of result.links)
                 await sendLink({ ...link });
             delivered = { ...result, link_sent: true };
         }
-        return deliverPagesInTurn(delivered);
+        return deliverPagesInTurn(delivered, call);
     };
     const answer = async (raw) => {
         const startedAt = Date.now();
@@ -654,8 +777,9 @@ export function buyTool(options) {
         const ask = input.ask.trim();
         if (!confirm && ask === '')
             throw new TypeError("Put the shopper's words in ask.");
-        // A pick chooses from the products this conversation showed: never on a confirm, and never on a new order, which shows none yet.
-        const pick = !confirm && !input.new_order && input.product_id ? { product_id: input.product_id } : null;
+        // A pick chooses from the products or stores this conversation showed: never on a confirm, and never on a new order, which shows none yet.
+        const picks = !confirm && !input.new_order;
+        const pick = picks && input.product_id ? { product_id: input.product_id } : picks && input.store_id ? { store_id: input.store_id } : null;
         const body = {
             resume: true,
             ...(confirm ? { confirm: true, payment_source: 'vault' } : { ask }),
@@ -664,19 +788,56 @@ export function buyTool(options) {
             ...(o.deliveryAddress ? { delivery_address: o.deliveryAddress } : {}),
             ...(client.company ? { external_user_id: externalUserId } : {}),
         };
-        // A call that starts while another runs, or right after one ended, is the model working through the same turn.
-        if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
+        // 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;
         }
+        const callTurn = modelTurn;
         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);
+        const ack = confirm || pick ? null : holdAck(ask, neutralTurn);
         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);
+                        }
+                        catch { /* the app's display failing never fails the call */ } } } : {}),
+                    ...(earlyCards && sendLink && !confirm
+                        ? {
+                            onCatalog: async (update) => {
+                                // Products arrived before the instant reply was due: they are the reply.
+                                ack?.cancel();
+                                await 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 });
+                            },
+                        }
+                        : {}),
+                }
+                : undefined;
             try {
-                turn = await client.buy(body);
+                turn = await client.buy(body, handlers);
             }
             catch (error) {
                 refusal = error;
@@ -684,7 +845,23 @@ export function buyTool(options) {
             ack?.cancel();
             const settled = turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt);
             await ackOut;
-            return await deliver(withMessages(settled, turn));
+            const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true });
+            const result = 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) {
+                try {
+                    await onResult(result);
+                }
+                catch {
+                    // The app's display failing never fails the purchase call.
+                }
+            }
+            return result;
         }
         finally {
             ack?.cancel();
@@ -711,7 +888,7 @@ export function buyTool(options) {
         }
     };
     const { name, description, input_schema } = buyToolDefinition();
-    const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer, forModel };
+    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.
     const unsent = (value) => ({ value, enumerable: false, writable: true, configurable: true });
     return Object.defineProperties(tool, {