@agent-cards/commerce-sdk 0.18.5 → 0.18.6

package/README.md

@@ -51,7 +51,7 @@ Build one client with your company's credentials and one buy tool per shopper, t
 
 ```ts
 import Anthropic from '@anthropic-ai/sdk';
-import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';
+import { AgentcardClient, appInstructions, buyTool } from '@agent-cards/commerce-sdk';
 
 const agentcard = new AgentcardClient({
   clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
@@ -67,6 +67,7 @@ const buy = buyTool({
 const answer = await new Anthropic().beta.messages.toolRunner({
   model: 'claude-opus-5-5',
   max_tokens: 16000,
+  system: appInstructions({ markdown: true }),
   tools: [buy],
   messages: [{ role: 'user', content: 'two packs of AA batteries from Amazon' }],
 });
@@ -78,6 +79,16 @@ Build the client once and keep it. Every shopper's tool shares the client's acce
 
 The model sends `ask`, `confirm`, `new_order`, `product_id` and `store_id`, and nothing else. A product link the shopper sends, such as a `buy.trychannel3.com` link, goes in `ask` exactly as sent, and Agentcard buys that exact product from it. Pass `deliveryAddress` when you already hold the shopper's address: the order goes there, and Agentcard never asks the shopper for it. The model can change neither the address nor the shopper.
 
+## Give your model Agentcard's instructions
+
+`appInstructions()` returns the system prompt Agentcard recommends for your model: what Agentcard can do for the shopper, in the words Agentcard's own buy agent uses, how to hand a request to the buy tool, and how to write for your app. Put it first in your system prompt, and add only what is about your app, such as its name:
+
+```ts
+const system = [appInstructions({ markdown: true, textingStyle: true }), 'You are the shopping chat in Acme.'].join('\n\n');
+```
+
+Pass `markdown: true` when your app shows the model's words as Markdown, so a shopper who asks for a table gets one; leave it out and the model writes plain text, with lists as `• ` lines. Pass `textingStyle: true` when your app is a chat that writes in lowercase, as you pass it to `buyTool`. The text ships inside the package and changes with each release; `APP_INSTRUCTIONS_VERSION` names the version you run.
+
 ## Use the tool in any framework
 
 Pass `buy` as it is. Each framework reads its own fields from the same object, so you pick no adapter:
@@ -152,7 +163,7 @@ Each step ends with a shopper message: `actionLinkOutcome(link, message)` says h
 | --- | --- | --- | --- | --- |
 | `vault` | `card_added` | | | `card_link_expired` |
 | `store_login` | `store_connected` | | `store_connect_failed` | `store_connect_expired` |
-| `approval` | `order_placed`, `order_not_placed_yet`, `order_unconfirmed`, `order_confirmed`, `order_failed`, `payment_declined` | `approval_declined` | | `approval_expired` |
+| `approval` | `order_placing`, `order_placed`, `order_not_placed_yet`, `order_unconfirmed`, `order_confirmed`, `order_failed`, `payment_declined` | `approval_declined` | | `approval_expired` |
 
 A reminder, such as `card_link_unfinished` or `approval_expiring`, leaves the step open. An approval is `completed` once the shopper approved, even when the order then failed or the payment was refused: the approval page has nothing more to do, and the message tells the shopper what happened. A message whose facts name another link of the same kind (`facts.approvalUrl`, `facts.cardLinkUrl`) leaves this one open, and so does one about another store: a store login link names its store in `store`, and so does an approval link when the answer names the cart's store, so DoorDash's `store_connected` (`facts.merchantName: 'DoorDash'`) never ends a Locale sign-in the shopper has open beside it.
 
@@ -338,6 +349,24 @@ const buy = buyTool({ agentcard, externalUserId: shopper.id, threadId: chat.id }
 
 A message about one chat's purchase carries that chat as `threadId`, so post it into that chat. One about the shopper alone, such as a saved card, carries `threadId: null`. A chat's tool takes a next step only for its own chat's messages and the shopper's own, and a tool built without `threadId` only for purchases opened under no thread and the shopper's own.
 
+## Choose how long a reply waits for stores
+
+A search that asks several stores writes its reply once the stores answered or a wait ran out. Choose that wait with `storeWaitMs`, and choose with `lateResults` what happens to a store that answers after the reply:
+
+```ts
+// A streaming chat: cards show as each store answers, the reply waits up to 25 s (99.7% of stores' first products), and a later store's cards stream below it.
+const buy = buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: 25000, lateResults: 'stream' });
+// A texting app: the reply waits up to 20 s (96% of stores' first products) and is the turn's last word.
+const sms = buyTool({ agentcard, externalUserId: shopper.id, storeWaitMs: 20000, lateResults: 'hold' });
+```
+
+Agentcard ends every store search at 30 s, so a `storeWaitMs` above `30000` waits no longer than `30000` does.
+
+- `lateResults: 'stream'` sends a late store's cards after the reply, in the same turn, the way a slower hotel supplier's cards come: to `sendLink`, `onProducts` and `onItem`, with the one message that says what they added. The turn's `onResult` lists them in `result.products` after the answer's own.
+- `lateResults: 'hold'` keeps a late store's cards out of the turn, so a texting app never sends a card after the reply.
+- `buy.turn(message, { storeWaitMs, lateResults })` sets them for one turn, and each one left out keeps the tool's. An app that calls `client.buy` itself sends `store_wait_ms` and `late_results`.
+- Left out, the tool sends neither, and Agentcard keeps its own wait. A wait that is not a whole number of milliseconds, 0 or more, throws a TypeError before any call.
+
 ## Tell the model what Agentcard told the shopper
 
 Agentcard posts messages into the shopper's chat between turns, through `listen` or the webhook: `Your Visa ending 3132 is saved, so you're ready to check out.`, an order placed, an approval about to expire. The shopper reads them, so your model has to know them too. A model that never saw `card_added` answers "ok lets checkout" with "did you save your card?" and never calls the tool.
@@ -527,7 +556,7 @@ const buy = buyTool({
 
 When your app shows Agentcard's messages through `onText`, the model reads `shopper_already_read_reply: true` in that call's answer and adds nothing to them, as it reads `shopper_already_told_looking` after an instant reply: end the turn without a second model call, as with `replyAsWritten`, or let the model add one short line for what the reply left out. `turn.replyAsWritten` stays null for that answer, so the reply never reaches the shopper twice, and a step link the turn holds for your model's next message goes out right after Agentcard's ask instead.
 
-A turn built with `replyAsWritten` and `earlyCards` that hears messages through `onMessage` or `onItem` and passes no `onText` gets the same once a reply is written while a slower source's cards are still coming, such as a second hotel supplier's: Agentcard's messages go out through that callback the moment Agentcard says the reply is written, the slower cards and their one message follow in the same call, and the answer reads `shopper_already_read_reply: true` with `turn.replyAsWritten` null.
+A turn built with `replyAsWritten` and `earlyCards` that hears messages through `onMessage` or `onItem` and passes no `onText` gets the same once a reply is written while a slower source's cards are still coming, such as a second hotel supplier's: Agentcard's messages go out through that callback the moment Agentcard says the reply is written, the slower cards and their one message follow in the same call, and the answer reads `shopper_already_read_reply: true`. `turn.replyAsWritten` then holds the messages the shopper read, and `turn.say` of it sends nothing, so an app that shows the reply as written and skips its model shows no second reply.
 
 A stream that breaks after the call started reads the conversation for what the turn left, as a turn past Agentcard's budget does. Pass `stream: false` to wait for each whole answer, with its cards sent beside it.
 
@@ -719,6 +748,7 @@ Subscribe your endpoint to each event below by name. A catch-all `*` alone does
 | `purchase.message` | `order_failed` | The order failed after the shopper approved. | Agentcard |
 | `purchase.message` | `order_not_placed_yet` | The shopper approved, and the order is not placed yet. | Agentcard |
 | `purchase.message` | `order_unconfirmed` | The store's reply to the order was lost, so the order may exist, and Agentcard is confirming it. | Agentcard |
+| `purchase.message` | `order_placing` | The shopper approved, and Agentcard is placing the order now. One of the order kinds above follows. | Agentcard |
 | `purchase.message` | `approval_expiring` | The approval link expires soon. `text` carries the link. | Agentcard |
 | `purchase.message` | `approval_expired` | The approval expired before the shopper answered, and no charge went through. | Agentcard |
 | `purchase.message` | `approval_declined` | The shopper declined the approval, and no charge went through. | Agentcard |
@@ -848,6 +878,7 @@ The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`
 | `card_link_expired` | The card link expired before the shopper added a card. |
 | `cart_idle` | A cart sat, and nobody sent it for approval. |
 | `order_unconfirmed` | The store's reply to the order was lost, and Agentcard is confirming it. |
+| `order_placing` | The shopper approved, and Agentcard is placing the order now. The order's own message follows. |
 | `card_added` | The shopper saved a card from the card link your app sent. |
 | `store_connected` | The shopper signed in to their own account at the store from the sign-in link your app sent, such as DoorDash, so the order can go through on it. |
 | `store_connect_failed` | The shopper's sign-in to the store did not go through, and the link no longer works. `text` offers a new one. |

package/dist/action-links.js

@@ -14,6 +14,7 @@ export const ACTION_LINK_ENDINGS = {
     vault: { card_added: 'completed', card_link_expired: 'expired' },
     store_login: { store_connected: 'completed', store_connect_failed: 'failed', store_connect_expired: 'expired' },
     approval: {
+        order_placing: 'completed',
         order_placed: 'completed',
         order_not_placed_yet: 'completed',
         order_unconfirmed: 'completed',

package/dist/app-instructions.d.ts

@@ -0,0 +1,17 @@
+/** The version of the text `appInstructions` returns. It changes whenever the text does. */
+export declare const APP_INSTRUCTIONS_VERSION: string;
+export interface AppInstructionsOptions {
+    /** `true` when your app shows the model's words as Markdown: tables, lists and bold. Default `false`, plain text. */
+    markdown?: boolean;
+    /**
+     * `true` when your app is a chat that writes like a text message: all lowercase except names. Pass the same value
+     * you pass `buyTool` as `textingStyle`. Default `false`.
+     */
+    textingStyle?: boolean;
+}
+/**
+ * The lines to put in your model's system prompt, before your own. Add only what is about your app, such as its name
+ * or what a shopper sees on its screen; what Agentcard can do and how to use the buy tool come from here, so they
+ * change with each SDK release.
+ */
+export declare function appInstructions(options?: AppInstructionsOptions): string;

package/dist/app-instructions.generated.d.ts

@@ -0,0 +1,9 @@
+/** The version of the voice package the text was copied from. */
+export declare const VOICE_VERSION = "0.2.79";
+export declare const APP_TEXT: {
+    readonly core: "You help a shopper buy what they ask for, with the `buy` tool from Agentcard.\n\nWhen the shopper asks what you can do, answer from these lines without calling the tool:\n- You buy from Amazon, Walmart, Target, Best Buy and thousands more stores. Say \"and thousands more stores\" every time you name the stores you shop, in a reply about one kind of thing too, such as \"travel gear from Amazon, Target and thousands more stores\". Never let a few names read as the whole list, never say \"most online stores\", \"plenty more\" or \"many more\", and never give a number of stores.\n- You plan a whole trip: the flights, a hotel and a rental car together. When they ask what you can do for travel, lead with the whole trip, then name the parts they can book on their own.\n- You order food delivery and book restaurant tables.\n\nHow you use the buy tool:\n- Call it for anything the shopper wants to find, buy, book or order, a trip with no dates or airport yet included: the tool asks for what it still needs.\n- Never say whether you can buy at a store the shopper names, either way. Only the tool knows, so say you will look and call it.\n- Never write a link. Each link reaches the shopper on its own, so when `link_sent` is true, tell them a link is waiting for them.\n- Tell the shopper no reply is needed only when `shopper_need_not_reply` is true.\n- Ask for one thing per message, the step `next_action` names, and leave every later step for a later message.\n- Never tell the shopper you can't show Markdown, a table or other formatting, and never say you keep to plain text.";
+    readonly markdown: "The app shows your words as Markdown. When the shopper asks for a table, a list or bold, write it in Markdown. Use a list or a table where it reads better than a sentence, and keep each message short all the same.";
+    readonly plainText: "The app shows your words as plain text, so write no Markdown: asterisks, underscores, pound signs, backticks and table pipes show up as written. Write a list as lines that start with \"• \", and a table the shopper asks for as one line per row.";
+    readonly texting: "Write like a text message: all lowercase except names, short and plain, with no dashes.";
+    readonly standard: "Write short, plain sentences, the way a person writes in a chat.";
+};

package/dist/app-instructions.generated.js

@@ -0,0 +1,10 @@
+// GENERATED by scripts/app-instructions.mjs from apps/agent-voice/kb/app.md. Do not edit: edit kb/app.md.
+/** The version of the voice package the text was copied from. */
+export const VOICE_VERSION = "0.2.79";
+export const APP_TEXT = {
+    "core": "You help a shopper buy what they ask for, with the `buy` tool from Agentcard.\n\nWhen the shopper asks what you can do, answer from these lines without calling the tool:\n- You buy from Amazon, Walmart, Target, Best Buy and thousands more stores. Say \"and thousands more stores\" every time you name the stores you shop, in a reply about one kind of thing too, such as \"travel gear from Amazon, Target and thousands more stores\". Never let a few names read as the whole list, never say \"most online stores\", \"plenty more\" or \"many more\", and never give a number of stores.\n- You plan a whole trip: the flights, a hotel and a rental car together. When they ask what you can do for travel, lead with the whole trip, then name the parts they can book on their own.\n- You order food delivery and book restaurant tables.\n\nHow you use the buy tool:\n- Call it for anything the shopper wants to find, buy, book or order, a trip with no dates or airport yet included: the tool asks for what it still needs.\n- Never say whether you can buy at a store the shopper names, either way. Only the tool knows, so say you will look and call it.\n- Never write a link. Each link reaches the shopper on its own, so when `link_sent` is true, tell them a link is waiting for them.\n- Tell the shopper no reply is needed only when `shopper_need_not_reply` is true.\n- Ask for one thing per message, the step `next_action` names, and leave every later step for a later message.\n- Never tell the shopper you can't show Markdown, a table or other formatting, and never say you keep to plain text.",
+    "markdown": "The app shows your words as Markdown. When the shopper asks for a table, a list or bold, write it in Markdown. Use a list or a table where it reads better than a sentence, and keep each message short all the same.",
+    "plainText": "The app shows your words as plain text, so write no Markdown: asterisks, underscores, pound signs, backticks and table pipes show up as written. Write a list as lines that start with \"• \", and a table the shopper asks for as one line per row.",
+    "texting": "Write like a text message: all lowercase except names, short and plain, with no dashes.",
+    "standard": "Write short, plain sentences, the way a person writes in a chat."
+};

package/dist/app-instructions.js

@@ -0,0 +1,22 @@
+/**
+ * The system prompt Agentcard recommends for your own model, the one that holds the buy tool and talks to the
+ * shopper. The buy tool's description says how to call it; these lines say who the model is for the shopper: what
+ * Agentcard can do, in the same words Agentcard's buy agent uses, how the model hands a request to the tool, and
+ * how its words look in your app. The text is copied from the voice package (apps/agent-voice/kb/app.md) when the
+ * SDK is built, so it ships inside the package and costs no request.
+ */
+import { APP_TEXT, VOICE_VERSION } from './app-instructions.generated.js';
+/** The version of the text `appInstructions` returns. It changes whenever the text does. */
+export const APP_INSTRUCTIONS_VERSION = VOICE_VERSION;
+/**
+ * The lines to put in your model's system prompt, before your own. Add only what is about your app, such as its name
+ * or what a shopper sees on its screen; what Agentcard can do and how to use the buy tool come from here, so they
+ * change with each SDK release.
+ */
+export function appInstructions(options = {}) {
+    return [
+        APP_TEXT.core,
+        options.markdown ? APP_TEXT.markdown : APP_TEXT.plainText,
+        options.textingStyle ? APP_TEXT.texting : APP_TEXT.standard,
+    ].join('\n\n');
+}

package/dist/buy-tool.d.ts

@@ -31,12 +31,14 @@
  * messages and links as one sequence, in the order they happened, and spaces
  * the messages like someone texting.
  */
+import type { BuyPlan } from './plan.js';
 import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyChoice, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyTurnStatus, type BuyAvailability, 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 DirectCall } from './direct.js';
 import { type BuyToolModelView } from './model-view.js';
 import { type MessagePace, type MessageStream } from './messages.js';
 import { type ShopperMessage } from './shopper-message.js';
+import { type BuyStoreWait } from './store-wait.js';
 /**
  * Where the purchase stands:
  * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
@@ -230,6 +232,8 @@ export interface BuyToolResult {
      * message from Agentcard, and only the shopper's yes to that total confirms it.
      */
     cart_building?: BuyCartBuilding | null;
+    /** The checkout plan the answer started or moved, such as a trip's flight, hotel and car with each one's state; null when none. */
+    plan?: BuyPlan | null;
     /**
      * True when this call sent Agentcard a confirm: the shopper's yes, or the yes the tool carried past a step the shopper
      * finished outside the chat. Absent when the call sent the shopper's words or read the conversation.
@@ -289,7 +293,7 @@ export interface BuyToolFound {
     found: number;
     more: BuyToolLink[];
 }
-export interface BuyToolOptions {
+export interface BuyToolOptions extends BuyStoreWait {
     /** A client built with your company's credentials. Build it once and share it across every shopper's tool. */
     agentcard?: AgentcardClient;
     /** Or one shopper's own Agentcard access token, for a tool that buys only for them. */
@@ -557,7 +561,7 @@ export type BuyToolTurnItem = {
     link: BuyToolLink;
 };
 /** The callbacks of one turn. Each one left out falls back to the option of the same name the tool was built with, except with `onItem`. */
-export interface BuyToolTurnOptions {
+export interface BuyToolTurnOptions extends BuyStoreWait {
     /**
      * Hears everything the turn hands the shopper, one item at a time and in the order it happened: the
      * instant reply and each message your model writes through `turn.messageStream()` or `turn.say()` as
@@ -622,6 +626,14 @@ export interface BuyToolTurnOptions {
     onText?: BuyToolOptions['onText'];
     /** Hears the carts each time a call of this turn builds or changes one, as the tool's `onCart` does. */
     onCart?: BuyToolOptions['onCart'];
+    /**
+     * The card the shopper tapped to open this turn, by the `productId` its link carried, whatever answer showed it. With `direct`
+     * on, the turn's call goes straight to Agentcard as a pick of exactly that card (`turn.direct`, reason `pick`), and Agentcard
+     * carts it, so a tap on a card two answers back carts that card. Send the tap's words as the turn's message too.
+     */
+    tapped?: {
+        productId: string;
+    };
 }
 /**
  * The buy tool for one shopper message, from `buy.turn`. It is the same tool, with the same name,

package/dist/buy-tool.js

@@ -1,36 +1,3 @@
-/**
- * The buy tool: one call that buys for one shopper, in one object that every
- * agent framework takes. `answer` sends the model's input to Agentcard and
- * returns the whole answer for your code, with the status, Agentcard's
- * reply, the cart and its hash, the products and the links. `forModel` turns
- * that answer into what the model may read, with every link taken out, and
- * `run`, `execute` and `handle` return that view as JSON text. A link
- * reaches the shopper through `sendLink`, and each call waits for it before
- * it returns: the Vault and approval links, then the store page of each
- * product the model reads.
- *
- * Agentcard keeps the conversation: every call continues the shopper's open
- * purchase (`resume: true`), and a confirm places the cart Agentcard last
- * showed (`confirm: true`). The tool keeps one thing between calls: the store
- * pages it sent last. Agentcard repeats the last search in each answer for a
- * while, so a list it shows again in the same conversation does not reach
- * the shopper twice. A tool built for each message buys the same way, and
- * sends such a list again.
- *
- * Two answers make the tool wait before it returns. A placement Agentcard is
- * 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, cartBuildingOf, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
 import { directCall, isProductAsk } from './direct.js';
@@ -39,6 +6,7 @@ import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, repl
 import { joinLeadIns, leadInJoiner, messageStream, paceOf, paragraphsOf, sleep, toMessages, typingHook } from './messages.js';
 import { isStale, messageInChat } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
+import { checkStoreWait, storeWaitFields, withLateCards } from './store-wait.js';
 import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, asksForSimilar, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
 /** The action a product of `merchant` takes (BuyToolProductAction). */
 export function productAction(merchant) {
@@ -151,6 +119,8 @@ const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shoppe
 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.";
+/** The most product cards a tool keeps from earlier answers for a tap on an older card. */
+const SHOWN_BEFORE_MAX = 200;
 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.";
 /** One cart line as the order holds it: the product, its variant, its choices and its quantity. Prices are left out. */
 const lineKey = (line) => JSON.stringify([line.product_id ?? String(line.name ?? '').trim().toLowerCase(), line.variant ?? null, [...(line.options ?? [])].sort(), line.qty]);
@@ -352,6 +322,7 @@ function answerOf(turn) {
         hashes: hashesOf(turn.cart, turn.carts),
         cart_building: turn.cart_building,
         choice: turn.choice ?? null,
+        plan: turn.plan ?? null,
         envelope: turn.raw,
     };
 }
@@ -419,6 +390,13 @@ const CARD_ASK = /\b(?:add|save|link|enter|attach)\s+(?:a|your|the)\s+(?:(?:paym
  * 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.
  */
+/**
+ * Agentcard's messages of an answer, as written, that the shopper read in full through the early reply (onWrittenText)
+ * before the call ended, by the answer they belong to. `turn.replyAsWritten` hands them back for the turn's last answer and
+ * `turn.say` of them sends nothing, so the app shows no second reply and its model is not asked to word one
+ * (chat.opencommerce.sh, 2026-10-29: after "i found 16 more hotels" the model wrote a second recommendation of the same hotels).
+ */
+const readAsWritten = new WeakMap();
 function waitsForAnswer(message) {
     return CARD_ASK.test(message) || new RegExp(URL_IN_TEXT.source, 'i').test(message);
 }
@@ -771,6 +749,7 @@ export function buyTool(options) {
         throw new TypeError('Pass threadId as your own id for the chat or thread, 1 to 200 characters, or leave it out.');
     }
     const threadId = o.threadId?.trim();
+    checkStoreWait(o);
     /** Whether a message is this tool's to read (`messageInChat`): its chat's purchase, or news about the shopper alone. */
     const inThisThread = (message) => messageInChat(message, threadId);
     if (o.sendLink !== undefined && typeof o.sendLink !== 'function') {
@@ -844,6 +823,9 @@ export function buyTool(options) {
     const { onWorking, onReaction } = ackRoutes(o.onWorking, o.onReaction);
     /** Calls running now, when the last one ended, and the template the instant reply used last. */
     let running = 0;
+    // When the newest call of this tool started: a late reply on the conversation answers the newest shopper message, so a call
+    // that a newer one followed no longer owns it.
+    let newestCallAt = 0;
     let lastEndedAt = Number.NEGATIVE_INFINITY;
     let lastTemplate = -1;
     /** Counts the model's turns: the calls of one turn share its number. */
@@ -942,6 +924,9 @@ export function buyTool(options) {
     let lastAnswerProducts = [];
     /** Every product card of the last answer's call the shopper can tap by name, each once (the answer's and the streamed). */
     let lastTappable = [];
+    /** Every product card this conversation's answers showed, newest first, each once: a tap on an older card reads these. */
+    let shownBefore = [];
+    let shownIn = null;
     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. */
@@ -1278,7 +1263,8 @@ export function buyTool(options) {
      * picks one first. A placement another attempt is still finishing keeps the
      * reading going and ends as `placing`, never as the cart. A minute without
      * any of them returns Agentcard's own answer, or what the last read showed
-     * while the turn still ran.
+     * while the turn still ran. A turn that ended with a reply of its own
+     * (`latest_reply`) answers with that reply and the products it showed.
      */
     const awaitCart = async (base, conversationId, since) => {
         const shown = new Set(base.hashes);
@@ -1313,13 +1299,18 @@ export function buyTool(options) {
                 // conversation and it shows one cart. With carts at two stores `confirm: true` still names the
                 // cart an earlier answer showed, so none is offered: the shopper's pick goes out as an ask.
                 const one = conversation.carts.length === 1 ? newest : null;
+                // The reply the turn wrote after its early answer is what the shopper waited for: it goes out in place of the
+                // tool's own line, with the products it showed (conv_054988b998634b16ab4a91d9, 2026-10-30: a stop message
+                // written while the shopper read "one moment" was never shown, and the model was told to call again).
+                const late = conversation.turn_in_progress || newestCallAt > since ? null : conversation.latest_reply;
                 const answer = {
                     ...base,
-                    reply: one ? CART_READY : newest ? CHOOSE_CART : ANSWER_LATE,
+                    reply: late ? late.text : one ? CART_READY : newest ? CHOOSE_CART : ANSWER_LATE,
+                    ...(late?.catalog ? { products: productsOfCatalog(late.catalog) } : {}),
                     cart: one,
                     carts: conversation.carts,
                     hashes: conversation.carts.map((c) => c.hash),
-                    error_code: newest ? null : base.error_code,
+                    error_code: newest || late ? null : base.error_code,
                     // A read replaced the answer the step was named for, and names no step of its own: the reply asks.
                     next_action: null,
                     // The early answer judged the pick before the turn finished adding it.
@@ -1818,6 +1809,9 @@ export function buyTool(options) {
             let cardsOut = false;
             /** The product cards this call's searches sent out as they answered, which the shopper can tap whatever the answer lists. */
             const streamedCards = [];
+            /** Whether Agentcard said the reply is written (`reply_written`), and the cards that went out after it: a store that answered late. */
+            let replyWritten = false;
+            const lateCards = [];
             let heldCount = null;
             /** The card each catalog id of this call went out as (its `productId`), and the cards still `checking`, by conversation. */
             const cardOfId = new Map();
@@ -1934,13 +1928,19 @@ export function buyTool(options) {
                                 // 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)
+                                if (!early) {
+                                    // Without early cards nothing goes out here, but a store that answered after the reply still joins the result.
+                                    if (replyWritten)
+                                        lateCards.push(...productsOfCatalog(update.catalog));
                                     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, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                const out = await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, withAnswers(productsOfCatalog(update.catalog))), { turn: callTurn, presented: true, owner: t }, send);
+                                if (replyWritten)
+                                    lateCards.push(...out.products);
                                 // A place shown `checking`, on a card or behind "show more", waits for the live search's word on it.
                                 noteCards([...productsOfCatalog(update.catalog), ...productsOfCatalog({ ...update.catalog, items: update.more })], update.conversationId);
                                 streamedCards.push(...productsOfCatalog(update.catalog));
@@ -1972,10 +1972,11 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
-                    ...(!t.onText && writtenText
+                    ...(early || t.onProducts
                         ? {
                             onReplyWritten: async () => {
-                                if (speak)
+                                replyWritten = true;
+                                if (speak || !writtenText)
                                     return;
                                 speak = writtenText;
                                 for (const message of unsaid.splice(0))
@@ -2021,10 +2022,15 @@ export function buyTool(options) {
             // Every request names the tool's thread, so Agentcard continues this chat's purchase and no other.
             if (threadId)
                 sent = { ...sent, thread_id: threadId };
+            // Every request names how long the reply waits for stores, and what happens to a store that answers after it.
+            sent = { ...sent, ...storeWaitFields(t.storeWait ?? {}, o) };
             if (plan && 'local' in plan) {
                 // Nothing went to Agentcard: the answer is where the purchase stands.
             }
             else {
+                // This call now owns the conversation's newest reply: an earlier call still waiting for its late reply gives it up.
+                // A call that threw on its input, or answered from where the purchase stands, sent nothing and takes none.
+                newestCallAt = Math.max(newestCallAt, startedAt);
                 try {
                     turn = await client.buy(sent, handlers);
                 }
@@ -2119,8 +2125,14 @@ export function buyTool(options) {
                 }
             }
             const read = choiceShown && !!turn && (settled.reply === turn.reply ? readEvery(told, turn.messages) : replaced && readEvery(told, paragraphsOf(settled.reply)));
+            // The shopper read the whole answer before the call ended, the late source's message included: the turn's reply is what
+            // they read, and nothing is worded again (chat.opencommerce.sh, 2026-10-29: after "i found 16 more hotels" the model
+            // wrote a second recommendation of the same hotels).
             const answer = withMessages(settled, turn);
-            const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented: turn?.catalog?.presented === true, owner: t }, send);
+            // A late reply read from the conversation presents the products of its own catalog, which the early answer never held.
+            const late = settled.envelope?.latest_reply;
+            const presented = turn?.catalog?.presented === true || (late?.text === settled.reply && late?.catalog?.presented === true);
+            const delivered = await deliver(answered.size > 0 ? { ...answer, products: withAnswers(answer.products) } : answer, { turn: callTurn, presented, owner: t }, send);
             // A count that came before any card (find mode puts its cards in the answer) goes out once the answer's cards did.
             if (heldCount && (delivered.products?.length ?? 0) > 0) {
                 const held = heldCount;
@@ -2145,11 +2157,15 @@ export function buyTool(options) {
                 : null;
             const result = {
                 ...delivered,
+                // The cards of a store that answered after the reply join the answer's, when the answer does not list them already.
+                ...(lateCards.length > 0 ? { products: withLateCards(delivered.products, lateCards) } : {}),
                 ...(t.ackDelivered ? { shopper_already_told_looking: true } : {}),
                 ...(read ? { shopper_already_read_reply: true } : {}),
                 ...(confirmSent ? { confirm_sent: true } : {}),
                 ...(yesCarried ? { yes_carried: yesCarried } : {}),
             };
+            if (read && speak && speak === writtenText)
+                readAsWritten.set(result, told.join('\n\n'));
             lastNextAction = result.next_action;
             lastReply = result.reply;
             // A refusal reports no carts, so only a turn's answer says how many wait, and whether a checkout just ended with none.
@@ -2199,6 +2215,13 @@ export function buyTool(options) {
             }
             lastAnswerProducts = shown.map((product) => ({ productId: pickId(product), name: product.name }));
             lastTappable = tappable.map((product) => ({ productId: pickId(product), name: product.name }));
+            // A new conversation starts the cards shown before afresh; each card keeps its newest showing, up to SHOWN_BEFORE_MAX.
+            if (result.conversation_id && result.conversation_id !== shownIn)
+                shownBefore = [];
+            if (result.conversation_id)
+                shownIn = result.conversation_id;
+            const fresh = new Set(lastTappable.map((product) => product.productId ?? `name:${product.name}`));
+            shownBefore = [...lastTappable, ...shownBefore.filter((product) => !fresh.has(product.productId ?? `name:${product.name}`))].slice(0, SHOWN_BEFORE_MAX);
             lastAnswerStores = storesShown.map((store) => ({ storeId: store.id, name: store.name }));
             t.results?.push(result);
             if (t.onResult) {
@@ -2310,6 +2333,7 @@ export function buyTool(options) {
         if (own.textingStyle !== undefined && typeof own.textingStyle !== 'boolean')
             throw new TypeError('Pass textingStyle to the turn as true or false, or leave it out.');
         const texting = own.textingStyle ?? textingByDefault;
+        checkStoreWait(own, ' to the turn');
         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);
@@ -2386,6 +2410,7 @@ export function buyTool(options) {
                 ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : onMessage?.(text)))
                 : undefined,
             texting,
+            storeWait: { storeWaitMs: own.storeWaitMs, lateResults: own.lateResults },
             onCart: own.onCart ?? o.onCart,
             tell: onItem || baseOnWorking ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
             links: [],
@@ -2478,13 +2503,17 @@ export function buyTool(options) {
         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;
+        // A tap names its card by the id its link carried, whatever answer showed it: the pick goes straight with that id.
+        const tappedId = typeof options?.tapped?.productId === 'string' && options.tapped.productId.trim() ? options.tapped.productId.trim() : null;
         // A `nextStep` turn's call is the same whatever the model writes (`stepPlan` reads where the purchase stands), so it goes
         // straight too: with `replyAsWritten`, a step whose answer is a link, such as the approval after a saved card, needs no model.
         const direct = !directOn || running > 0
             ? null
             : event
                 ? { input: { ask: NEXT_STEP_ASK, confirm: false, new_order: false, product_id: null, store_id: null }, reason: 'next_step' }
-                : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, tappable: lastTappable, stores: lastAnswerStores });
+                : tappedId && String(shopperText ?? '').trim()
+                    ? { input: { ask: String(shopperText).trim(), confirm: false, new_order: false, product_id: tappedId, store_id: null }, reason: 'pick' }
+                    : directCall(String(shopperText ?? ''), { answered, nextAction: lastNextAction, asked: lastReply, products: lastAnswerProducts, tappable: lastTappable, shownBefore, stores: lastAnswerStores });
         // Agentcard writes the line for a search the turn sends straight. A turn the app's model runs gets the model's own line,
         // or the wait line below.
         state.agentcardAcks = (ask) => direct !== null && direct.reason === 'product_ask' && ask.trim() === direct.input.ask.trim();
@@ -2595,6 +2624,10 @@ export function buyTool(options) {
         /** Says a whole text as the turn's messages, after every item before it (`say()`). */
         const sayWhole = (whole) => {
             writesThroughTurn = true;
+            // The reply the shopper already read as Agentcard wrote it (`readAsWritten`), of the turn's last answer: saying it again sends nothing.
+            const read = results.length > 0 ? readAsWritten.get(results[results.length - 1]) : undefined;
+            if (read && whole === read)
+                return releaseForReply();
             firstWords(whole);
             if (state.modelTurn && /\S/.test(String(whole ?? '')))
                 state.modelTurn.spoke = true;
@@ -2678,7 +2711,7 @@ export function buyTool(options) {
             results: { get: () => [...results], enumerable: false },
             direct: { value: direct, enumerable: false },
             stopped: { get: () => state.stopped === true, enumerable: false },
-            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
+            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? readAsWritten.get(results[results.length - 1]) ?? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : 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.
             // A step link held for this message goes out right after its last paragraph, once the stream ends.

package/dist/client.d.ts

@@ -1,3 +1,14 @@
+/**
+ * The client the buy tool calls Agentcard with. A company builds one from its
+ * client credentials, and every shopper's tool shares the one access token it
+ * exchanges them for; or a tool runs on one shopper's own access token. The
+ * global fetch is the only transport, so the package keeps no dependencies.
+ *
+ * The answer fields and the error codes follow the buy module of
+ * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
+ * token cache follows its client (packages/checkout/src/client.ts accessToken).
+ */
+import { type BuyPlan } from './plan.js';
 import { type AgentcardListener, type ListenOptions } from './listen.js';
 import { type ShopperMessage } from './shopper-message.js';
 /** The fetch the client calls: Node 18 and later have one built in. */
@@ -241,6 +252,16 @@ export interface BuyRequest {
      * another thread is refused (409 `thread_mismatch`). Leave it out for an app with one chat per shopper.
      */
     thread_id?: string;
+    /**
+     * How long, in milliseconds, the reply waits for store searches before Agentcard writes it. Left out, Agentcard keeps
+     * its own wait. `buyTool({ storeWaitMs })` sends it on every request.
+     */
+    store_wait_ms?: number;
+    /**
+     * What happens to a store that answers after the reply: `stream` sends its cards after the reply in the same streamed
+     * turn, before the answer; `hold` keeps them out of the turn. Left out, Agentcard does as it does today.
+     */
+    late_results?: 'stream' | 'hold';
     /** Drop the cart on the table and start a new order. */
     new_order?: true;
     /**
@@ -542,6 +563,8 @@ export interface BuyTurn {
     cart_building: BuyCartBuilding | null;
     /** The choice the reply asks the shopper to make, each group with every value; null when it asks none, and on an older API. */
     choice: BuyChoice | null;
+    /** The checkout plan this answer's yes started or moved, with each item's state; null when none, and on an older API. */
+    plan: BuyPlan | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -581,8 +604,22 @@ export interface BuyConversation {
     last_checkout: BuyLastCheckout | null;
     orders: BuyOrder[];
     carts: BuyCart[];
+    /**
+     * The reply Agentcard wrote since the shopper's last message, once no turn runs: the answer a call that ended with
+     * `turn_timeout` never got. Null while a turn runs, when no reply was written since, and on an older API.
+     */
+    latest_reply: BuyLatestReply | null;
     raw: Record<string, unknown>;
 }
+/** A reply a conversation read hands back: its text, its messages, and the products it showed. */
+export interface BuyLatestReply {
+    message_id: string;
+    text: string;
+    messages: string[];
+    /** The products the reply showed, when the call that asked ended before it was written; null otherwise. */
+    catalog: BuyCatalog | null;
+    created_at: string | null;
+}
 /** A Vault link: the page where a shopper connects and adds a card. */
 export interface VaultLink {
     id: string;

package/dist/client.js

@@ -8,6 +8,7 @@
  * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
+import { planOf } from './plan.js';
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
 import { messageInChat } from './shopper-message.js';
@@ -302,6 +303,7 @@ export function turnOf(body) {
         store_pick: isRecord(body.store_pick) && str(body.store_pick.store_id) ? { store_id: body.store_pick.store_id, name: str(body.store_pick.name), selected: body.store_pick.selected === true } : null,
         cart_building: cartBuildingOf(body.cart_building),
         choice: choiceOf(body.choice),
+        plan: planOf(body.plan),
         raw: body,
     };
 }
@@ -358,9 +360,23 @@ function conversationOf(body) {
             placed_at: str(o.placed_at),
         })) : [],
         carts: cartsOf(body.carts),
+        latest_reply: latestReplyOf(body.latest_reply),
         raw: body,
     };
 }
+/** The reply a conversation read hands back, or null when it names no text. */
+function latestReplyOf(value) {
+    if (!isRecord(value) || !str(value.text)?.trim())
+        return null;
+    const messages = Array.isArray(value.messages) ? value.messages.filter((m) => typeof m === 'string' && m.trim() !== '') : [];
+    return {
+        message_id: str(value.message_id) ?? '',
+        text: value.text,
+        messages: messages.length > 0 ? messages : [value.text],
+        catalog: catalogOf(value.catalog),
+        created_at: str(value.created_at),
+    };
+}
 /** An error code as the API spells one: lower-case words joined by underscores. */
 const CODE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
 /**