@agent-cards/commerce-sdk 0.9.0 → 0.10.0

package/README.md

@@ -39,6 +39,8 @@ agentcard.listen({
 });
 ```
 
+Once `onMessage` returns, the client keeps the message for that shopper's next `buy.turn`, and `turn.messages(history)` hands it to your model before the shopper's words, so the model knows the shopper saved a card or got an order. "Tell the model what Agentcard told the shopper" shows it.
+
 `listen` returns `{ ready, close }`: `ready` resolves once the listener reaches Agentcard, and `close()` stops it after the callback that is running returns. Run one listener per company and mode. Two listeners each hear every event, so with two, skip a `message.eventId` you already stored. Sandbox credentials hear sandbox events, live credentials live ones, and a shopper message is always live.
 
 `listen` needs a process that keeps running, such as a Node server, a worker or a container. On a host that ends each request after a few seconds, such as a serverless function, take the events at a webhook endpoint instead, as "Hear from Agentcard at a webhook endpoint" shows.
@@ -134,12 +136,97 @@ console.log(await result.getText());
 
 A purchase needs a link at three moments: the shopper approves the purchase on an approval page, a new shopper adds a card on a Vault page, and a shopper signs in to a store's own account on its login page before Agentcard can buy there. Each link's `kind` says which: `approval`, `vault` or `store_login`, and a `store_login` link names the store in `store`. The tool hands each link to `sendLink` and waits for it, so the shopper holds the link before the model answers. The model reads `link_sent: true` and never the link itself, because a tool runner puts each answer straight into the model's context, and a model that holds a link writes it into the chat.
 
-The tool also hands `sendLink` a `product` link for each product a search finds, up to three per answer. The link carries the product's page at its store in `url`, the product's name in `title`, its price in `price`, such as `$12.99`, Agentcard's id for it in `productId`, and its picture in `imageUrl`, or null when the store sent none. Every price the tool writes, in a link or in the model's view, uses the currency Agentcard names for the cart or the product, in that currency's own minor units: `1331` is `$13.31` in USD, `CA$13.31` in CAD and `¥1,331` in JPY. A price whose currency Agentcard does not name shows with no symbol. The link arrives beside the reply, and you decide how to show it: as a card, in a list, or as a text with the URL. The model reads `product_links_sent` and never a URL, so a shopper who asks for links hears that the links are there. When a later answer in the conversation only stands beside the same products, as a cart answer does, the tool sends none of their links again. When a later turn's reply presents them again, as the answer to a repeated ask does, the tool sends their links again, so every product the reply names arrives with its link. A product link your `sendLink` throws on counts as not sent, and the call goes on.
+The tool also hands `sendLink` a `product` link for each product a search finds, up to three per answer. The link carries the product's page at its store in `url`, the product's name in `title`, its price in `price`, such as `$12.99`, Agentcard's id for it in `productId`, and its picture in `imageUrl`, or null when the store sent none. Every price the tool writes, in a link or in the model's view, uses the currency Agentcard names for the cart or the product, in that currency's own minor units: `1331` is `$13.31` in USD, `CA$13.31` in CAD and `¥1,331` in JPY. A price whose currency Agentcard does not name shows with no symbol. The link arrives beside the reply, and you decide how to show it: as a card, in a list, or as a text with the URL. Each product gets its own link, so the three dishes a restaurant's reply offers are three cards, though they share the store's one page. A flight has no page at a store, so each flight a search finds is a `product` link whose `url` is null, with the airline, the route and its times in `title`: show it as a card with no link to open, and hand its `productId` back as the shopper's pick. The model reads `product_links_sent` and never a URL. The tool's description tells it that the shopper already sees those products as cards, so its reply never lists them again by name or price: it writes one short line, such as which one they want, and a shopper who asks for links hears that the links are there. When a later answer in the conversation only stands beside the same products, as a cart answer does, the tool sends none of their links again. When a later turn's reply presents them again, as the answer to a repeated ask does, the tool sends their links again, so every product the reply names arrives with its link. A product link your `sendLink` throws on counts as not sent, and the call goes on.
 
 `productId` holds no link: it is the same `product_id` the model reads for that product, and the page is `url`. An answer that only adds a product the shopper picked lists that product alone, so it sends no card for a product nobody offered on that turn, and the pages the search already sent still count as sent on the answers after it.
 
 Without `sendLink`, `result.links` still carries each Vault, approval and store login link for your code, each product in `result.products` carries its `url`, and the model still never reads one.
 
+## Answer each shopper message in its own turn
+
+A shopper can send a second message before the first is answered. The `sendLink`, `onWorking` and `onResult` you pass to `buyTool` hear every call, whichever message the call answers, so a callback that hands each link to "the message running now" gives the first message's cards to the second. Open a turn for each message instead, and pass the turn to your model in place of the tool:
+
+```ts
+const buy = buyTool({ agentcard, externalUserId: shopper.id }); // one per shopper, kept
+
+async function onShopperMessage(message: string) {
+  const turn = buy.turn(message, { onWorking: (text) => textShopper(shopper.id, text) });
+  const runner = new Anthropic().beta.messages.toolRunner({
+    model: 'claude-opus-5-5',
+    max_tokens: 16000,
+    tools: [turn],
+    messages: turn.messages(history),
+  });
+  const answer = await runner;
+  history = runner.params.messages;
+  return { answer, links: turn.links, carts: turn.results.at(-1)?.carts ?? [] };
+}
+```
+
+`history` stands for the shopper's earlier messages. `turn.messages(history)` is the history, then what Agentcard told the shopper that the history doesn't hold yet, then `message`. Every call the model makes through `turn` belongs to that message alone:
+
+- `turn.links` holds each link the turn's calls handed over, in order: the Vault, approval and store login links, each product's store page, and each store card's page. The model reads that each one went out, so send them with the reply. Pass `sendLink` to `buy.turn` as well to send each one the moment the tool hands it over, such as down a server-sent event stream. A link your `sendLink` throws on stays out of `turn.links`.
+- `turn.results` holds the whole answer of each call, and an `onResult` passed to `buy.turn` hears each one as it arrives.
+- With `onWorking`, `buy.turn` sends the instant reply at once, before your model runs: the one `buy.instantAck` would return, or the one your `ack` function writes. You never call `instantAck` yourself. A slow call of the turn sends its reply to that `onWorking` too, and `turn.ack` holds the text the turn sent when it opened.
+- An `onProgress` passed to `buy.turn` hears only that turn's stages.
+- `turn.agentcardMessages` holds each message `agentcard.listen` or `agentcardWebhook` posted into this shopper's chat that the model has not read yet, and `turn.messages(history)` hands them to the model.
+
+A callback you leave out of `buy.turn` falls back to the one the tool was built with, so a tool whose `sendLink` texts the shopper keeps texting, and `turn.links` lists the same links. The turn is the tool, with the same name, schema and methods, so pass it to every framework the way you pass `buy`: `tools: [turn]`, `tools: { buy: turn }`, `tools: [turn.openai]` with `turn.handle`, or `toOpenRouterTool(turn, { tool, z })`. `turn.ack`, `turn.links` and `turn.results` stay out of the tool's JSON, so a tool runner sends the API the same fields. Build the tool once per shopper and open a turn from it for each message: the turns share the shopper's conversation, so a card a shopper already holds from an earlier turn is not sent again.
+
+A call made on `buy` itself still works as before: it belongs to the turn the tool reads from its timing, and its links go to the tool's `sendLink`.
+
+### Hand the app the turn in order
+
+A turn reaches the shopper as messages and links that interleave: the instant reply, the cards a search found, then your model's words about them. Pass `onItem` to `buy.turn`, and the turn hands your app all of them as one sequence, one item at a time, in the order they happened. Show each item below the one before it:
+
+```ts
+const turn = buy.turn(message, {
+  onItem: (item) => (item.kind === 'text' ? sendText(shopper.id, item.text) : sendCard(shopper.id, item.link)),
+  onTyping: (typing) => showTyping(shopper.id, typing),
+});
+const runner = new Anthropic().beta.messages.toolRunner({ model: 'claude-opus-5-5', max_tokens: 16000, tools: [turn], messages: turn.messages(history), stream: true });
+for await (const stream of runner) {
+  const paragraphs = turn.messageStream();
+  stream.on('text', (delta) => paragraphs.push(delta));
+  await stream.done();
+  await paragraphs.end();
+}
+```
+
+- A `text` item is the instant reply, or a message your model wrote through `turn.messageStream()` or `turn.say(text)`. A `link` item is each link the tool hands over, with the fields `sendLink` would get.
+- Messages arrive one at a time, like someone texting. Each one waits until `typingDelay` of it has passed since the item before it went out: 300 ms, plus 12 ms a character, at most 1.5 seconds. Time your model spent writing counts toward the pause, so a slow model gets no added wait, and links never wait. `onTyping` hears `true` when a pause starts and `false` when its message goes out. Pass `pace: false` to send each message the moment it is ready, or a function that returns the pause in milliseconds.
+- With `onItem`, the turn sends no link to a `sendLink` and no instant reply to an `onWorking`, so a tool built with those for other turns sends nothing twice. Passing `onItem` beside `sendLink` or `onWorking` to the same turn throws.
+- `turn.items` holds every item that went out, in order, so an app that answers the whole turn at once returns it as is. A turn without `onItem` keeps `turn.items` as well, unpaced.
+
+## 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.
+
+Build the listener and every buy tool on the same `AgentcardClient`. Then pass `turn.messages(history)` as the model's messages, and save what the run ends with as the next history:
+
+```ts
+const agentcard = new AgentcardClient({ clientId, clientSecret });
+agentcard.listen({ onMessage: (shopperId, message) => postToChat(shopperId, message.text) });
+
+const turn = buyTool({ agentcard, externalUserId: shopperId }).turn(message);
+const runner = anthropic.beta.messages.toolRunner({ model: 'claude-opus-5-5', max_tokens: 16000, tools: [turn], messages: turn.messages(history) });
+await runner;
+history = runner.params.messages;
+```
+
+How it works:
+
+- Once your `onMessage` returns, the client keeps the message for that shopper. A message whose `onMessage` threw every time never reached the chat, so the client does not keep it.
+- `buy.turn` reads the messages kept for its shopper when it opens. `turn.agentcardMessages` holds them, oldest first.
+- `turn.messages(history)` returns a new array: `history`, then Agentcard's `text` as the assistant's words, then the shopper's message as `{ role: 'user', content: message }`. The chat showed Agentcard's message in your agent's voice, so the model reads it as its own. Every link is taken out of the model's copy, as `forModel` takes them out of an answer, and the message `onMessage` got keeps them.
+- A message stays kept until a history you pass to `turn.messages` holds it, and then the client forgets it. So when a turn fails and you keep the history you had, the next turn hands the message to the model again. Once you saved a history that holds it, no turn hands it over a second time.
+- When the last message in `history` is the assistant's plain text, Agentcard's words join that message, so no provider reads two assistant messages in a row. That covers a string, or `text` parts as the Anthropic API, the Vercel AI SDK and OpenAI's chat completions write them. After anything else, such as a tool result, a tool call or an OpenAI Responses item, they come as an assistant message of their own. `history` itself is never changed.
+- The Anthropic SDK's `messages`, the Vercel AI SDK's `messages`, OpenAI's chat completions `messages` and the Responses API's `input` all take what it returns.
+
+With a webhook, pass the client to the handler: `agentcardWebhook({ secret, agentcard, onMessage })`. For a message you deliver some other way, call `agentcard.delivered(shopperId, message)` once it reaches the chat. The client keeps each message once per `eventId`, so a message both the listener and the webhook carry reaches the model once.
+
+The messages live in the client's memory, at most 20 per shopper. So the listener, or the webhook, and the turn have to run in one process on one client. When your listener runs in one process and your model in another, such as a serverless chat route, keep each message where your chat history lives as `onMessage` delivers it, as an assistant message, and the model reads it from the history.
+
 ## Add the exact product the shopper picks
 
 Each product in the model's view carries a `product_id`, Agentcard's id for it with no link in it. When the shopper picks one of those products, by its name, its place in the list or a tap on its card that sends its title, the model passes that `product_id`, and Agentcard adds exactly that product from the products it showed, with no new search. Your app sends no id of its own: a "Buy this" button that sends the shopper's words, such as `I'll take the KODAK AA Alkaline Batteries (24 Pack) ($13.49)`, is enough, because the model reads the `product_id` beside that name in its last result. Keep each tool result in the model's history, as a tool runner does, so the model still holds those ids on the shopper's next message. Your own code can pick too: a card's button can call `buy.answer` with the link's `productId` as `product_id`, and Agentcard adds that product.
@@ -148,9 +235,9 @@ Each product in the model's view carries a `product_id`, Agentcard's id for it w
 
 ## Show the stores the shopper picks from
 
-A delivery order often starts with a choice of store: the shopper asks for a taco, and Agentcard answers with the taquerias near them that deliver. Each store the reply names reaches `sendLink` as a `store` link, up to three per answer, in the order the reply names them. The link carries the store's page at the merchant in `url`, its name in `title`, Agentcard's id for it in `storeId`, and the delivery estimate in minutes in `etaMinutes`, or null when the store showed none. Show it as a card with an "Order here" button. `result.stores` carries the same stores for your code, each with its `url` and `linkSent`.
+A delivery order often starts with a choice of store: the shopper asks for a taco, and Agentcard answers with the taquerias near them that deliver. Each store the reply names reaches `sendLink` as a `store` link, up to three per answer, in the order the reply names them. The link carries the store's page at the merchant in `url`, its name in `title`, Agentcard's id for it in `storeId`, the delivery estimate in minutes in `etaMinutes`, or null when the store showed none, and the picture the store's card shows at the merchant in `imageUrl`, or null when it shows none. Show it as a card with the picture and an "Order here" button. `result.stores` carries the same stores for your code, each with its `url` and `linkSent`.
 
-The model reads each store in `stores` by its `store_id`, name and `eta_minutes`, never its page, and `store_links_sent` says how many store pages the shopper holds. When the shopper picks a store, by its name, its place in the list or a tap on its card, the model passes that `store_id`, and Agentcard selects exactly that store before its agent answers, so the products it finds next are from that store. A card's button can call `buy.answer` with the link's `storeId` as `store_id`. A shopper who answers only with a place in the list, such as `the second one` or `2`, picks the store at that place in the last answer's list, whether or not the model passed the id.
+The model reads each store in `stores` by its `store_id`, name and `eta_minutes`, never its page, and `store_links_sent` says how many store pages the shopper holds. When the shopper picks a store, by its name, its place in the list or a tap on its card, the model passes that `store_id`, and Agentcard selects exactly that store before its agent answers, so the products it finds next are from that store. A card's button can call `buy.answer` with the link's `storeId` as `store_id`. A shopper who answers only with a place in the list, such as `the second one` or `2`, picks the store at that place in the last answer's list, whether or not the model passed the id. A store pick starts no search, so it gets no instant reply: a card tap that sends `Order from Tacos El Grullense`, the store's name alone or with `please`, and `order here` or `this place` all read as a pick of a store the last answer listed. A dish beside the store's name, as in `order tacos from el farolito`, is a search.
 
 `result.store_pick` says what happened: the store's id and name, and `selected`, whether the merchant took the selection; when it did not, Agentcard's agent selects the store itself. The model reads `store_pick` by the `store_id` it sent. A store Agentcard no longer holds, because the stores are more than 15 minutes old or a newer search replaced them, selects nothing, and the model reads that it should search again with the shopper's words.
 
@@ -169,7 +256,7 @@ const buy = buyTool({
 });
 ```
 
-The tool sends the reply when Agentcard has not answered a new request within 1.5 seconds, so a quick answer arrives alone. It sends one for the calls the model makes in one turn, where a call that starts within 15 seconds of the last one ending counts as the same turn, and none on a confirm, on a pick of a product the shopper saw, or on an answer such as `yes`, `2`, `the first one` or a code. The words rotate through six templates, and one tool never sends the same template twice in a row. A short paraphrase of the request goes in when the tool can read one: it stops before any link, email address, phone number, street address or long number, and a request that starts with one gets a reply that names nothing, such as `looking for that now`. The call waits for `onWorking`, so the shopper reads the reply before any link and before the model answers. An `onWorking` that throws costs only the instant reply.
+The tool sends the reply when Agentcard has not answered a new request within 1.5 seconds, so a quick answer arrives alone. It sends one for the calls the model makes in one turn, where a call that starts within 15 seconds of the last one ending counts as the same turn. A slow confirm or pick never hears `looking for`: a pick of a product the shopper saw hears `adding it now`, a pick of a store or a place in a list, such as `the first one`, hears `got it, one moment`, and a confirm hears `on it, one moment`. None of them names anything the shopper said, and a code hears nothing. The words rotate through six templates, and one tool never sends the same template twice in a row. A short paraphrase of the request goes in when the tool can read one: it stops before any link, email address, phone number, street address or long number, and a request that starts with one gets a reply that names nothing, such as `looking for that now`. The call waits for `onWorking`, so the shopper reads the reply before any link and before the model answers. An `onWorking` that throws costs only the instant reply.
 
 When the instant reply went out, the model reads `shopper_already_told_looking: true` in that turn's answers, and the tool's description tells it not to acknowledge the request again, so its own reply opens with the answer or the question rather than a second `on it`. It reads false on a turn that sent none, and when `onWorking` threw.
 
@@ -182,9 +269,11 @@ const ack = buy.instantAck(message);
 if (ack) await textShopper(shopper.id, ack);
 ```
 
-`instantAck` returns null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a code, small talk such as `hi` or `how are you`, a message that carries the shopper's own details, such as a name with a phone number, an email address, a street address, a bare house number and street such as `1801 wedemeyer`, or a zip code, and any message that answers the last answer's request for an address, shipping or guest details or a code. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed as a pick of it. 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: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still sends `onWorking` a reply that names nothing, such as `give me a sec, checking`.
+With `buy.turn`, pass `onWorking` to the turn instead: it sends the same reply the moment the turn opens, and calls `instantAck` for you.
 
-Without a buy tool, `instantAck(message, { previous, nextAction, asked })` from the package root decides the same way: `previous` is the reply you sent last, so the next one comes from another template, `nextAction` is the last answer's `next_action`, and `asked` is the last message the shopper read, so an answer to its question for an address, a name or a code gets none. Pass `ack: false` to the tool when you send it yourself. `ackFor` is the earlier name of the same function.
+`instantAck` returns null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a step toward paying for the cart such as `ok lets checkout`, `place the order` or `pay`, an acknowledgement such as `its ok`, `thats fine` or `sounds good`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a pick of a store, such as `order here` or a store card's `Order from Tacos El Grullense`, a code, small talk such as `hi` or `how are you`, a message that carries the shopper's own details, such as a name with a phone number, an email address, a street address, a bare house number and street such as `1801 wedemeyer`, or a zip code, any message that answers the last answer's request for an address, shipping or guest details or a code, and a short reply right after any other question the last answer asked, such as `im a 37` after `what size do you want?`, or `carne asada` after `which meat?`. A reply that opens a new request, such as `find me black running shoes`, or that runs past four words is still a search. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed, or names one of the stores its last answer listed and nothing else to buy, as a pick of it. A request for a store the shopper did not see, such as `order from chipotle`, reads back as `looking for chipotle`, never `looking for from chipotle`. 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: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still sends `onWorking` a reply that names nothing and never says it is looking for anything, such as `working on it` or `one moment`, and when it returns null for a pick, such a call sends `adding it now` or `got it, one moment`.
+
+Without a buy tool, `instantAck(message, { previous, nextAction, asked, stores })` from the package root decides the same way: `previous` is the reply you sent last, so the next one comes from another template, `nextAction` is the last answer's `next_action`, `asked` is the last message the shopper read, so an answer to its question for an address, a name or a code, or a short answer to any other question it asked, gets none, and `stores` holds the names of the stores the last answer listed, so a message that picks one gets none. Pass `ack: false` to the tool when you send it yourself. `ackFor` is the earlier name of the same function.
 
 ## Show what Agentcard is doing
 
@@ -213,7 +302,7 @@ for (const text of toMessages(reply)) await textShopper(shopper.id, text);
 
 `result.messages` from `buy.answer` holds Agentcard's own answer cut the same way, links included, so your code sends it without cutting it again.
 
-For a reply your model streams, `messageStream` hands over each paragraph the moment the blank line that ends it arrives, however the stream cuts the text. Push each piece of text, then call `end` for the last paragraph:
+For a reply your model streams, `messageStream` hands over each paragraph once the blank line that ends it arrives, however the stream cuts the text. Push each piece of text, then call `end` for the last paragraph:
 
 ```ts
 import { messageStream } from '@agent-cards/commerce-sdk';
@@ -224,7 +313,9 @@ await stream.done();
 await paragraphs.end();
 ```
 
-`stream` stands for your model's streamed answer. When `onMessage` returns a promise, the stream waits for it before it sends the next paragraph, so the shopper reads them in order, and `end` resolves once every paragraph went out. After a send fails, no later paragraph goes out, and `end` rejects with that error. A paragraph inside a list waits for the first characters of the next line, which say whether the list goes on. Start a new `messageStream` for each model message, so one message never runs into the next.
+`stream` stands for your model's streamed answer. `toMessages` and `messageStream` keep nothing between two texts, so a shopper's overlapping messages never mix in them: the paragraphs of one model message go to the `onMessage` of its own stream, and the links of that turn's tool calls are in its `turn.links`. When `onMessage` returns a promise, the stream waits for it before it sends the next paragraph, so the shopper reads them in order, and `end` resolves once every paragraph went out. After a send fails, no later paragraph goes out, and `end` rejects with that error. A paragraph inside a list waits for the first characters of the next line, which say whether the list goes on. Start a new `messageStream` for each model message, so one message never runs into the next.
+
+A model often writes three paragraphs within 200 ms, and a shopper who gets them at once reads a wall, not a conversation. So `messageStream` spaces them like someone texting: the first goes out at once, and each one after it waits until `typingDelay` of it has passed since the one before, at most 1.5 seconds. Time the model spent writing counts toward the pause, so a slow model gets no added wait. Pass `onTyping` to show a typing indicator during each pause, `pace: false` to hand each paragraph over the moment it is cut, or `pace: (text) => ms` for your own pause. With `buy.turn`'s `onItem`, use `turn.messageStream()` instead, which spaces the model's messages after the cards and the instant reply too.
 
 ## Sign up a new shopper
 
@@ -309,6 +400,8 @@ const buy = buyTool({
 });
 ```
 
+This `onResult` hears every call the tool makes. To show each message's carts beside that message, pass `onResult` to `buy.turn`, or read `turn.results` once the turn ends.
+
 A refusal the tool turns into an answer, such as the Vault link for a shopper with no card, reaches `onResult` too. A call that throws calls nothing. An `onResult` that throws costs only that call to it, and the model still reads the answer. If you wrap `buy.answer` yourself, hand its errors to `forModelError` before a model reads them, and every link is taken out.
 
 ## Buy with a shopper's own token
@@ -370,6 +463,8 @@ const webhook = agentcardWebhook({ secret: process.env.AGENTCARD_WEBHOOK_SECRET
 export const POST = webhook.fetch;
 ```
 
+Pass `agentcard`, the client your buy tools share, and the handler keeps each message it delivered for that shopper's next turn, as `listen` does: `agentcardWebhook({ secret, agentcard, onMessage })`. "Tell the model what Agentcard told the shopper" shows how the model reads it.
+
 Subscribe your endpoint to each event below by name. A catch-all `*` alone does not turn `purchase.message` on. `SHOPPER_EVENT_TYPES` holds the three names:
 
 | Event | `kind` | When it arrives | Who wrote `text` |

package/dist/ack.d.ts

@@ -11,8 +11,16 @@
  * `my mom`, and it never cuts a phrase short: a subject that runs long or carries brackets gets the
  * template without one. A reply to a question, such as `yes`, `2` or a code, and a pick of a product the
  * shopper already saw, such as `the first one`, `I'll take the KODAK AA ($13.49)` or `#2`, gets no
- * instant reply at all, because it starts no search and Agentcard answers it fast.
+ * instant reply at all, because it starts no search and Agentcard answers it fast. So does a pick of a
+ * store the shopper saw, such as `order here`, or `Order from Tacos El Grullense` as a store card sends it.
  */
+/**
+ * True when the message names one of these stores and nothing else to buy: the store's whole name, or
+ * two words of it in a row, such as `el grullense` for `Tacos El Grullense`, alone or after a frame such
+ * as `order from` or `let's go with`. One word of a name, such as `tacos`, and a dish beside the name,
+ * such as `order tacos from el farolito`, name no store.
+ */
+export declare function namesStore(text: string, storeNames: readonly string[] | null | undefined): boolean;
 /** True when the shopper's words pick a product they already saw, such as `the first one`, `2` or a card's title with its price. */
 export declare function isPickText(text: string): boolean;
 /**
@@ -25,6 +33,15 @@ export declare function isNewRequest(text: string): boolean;
 export declare function paraphrase(text: string): string | null;
 /** The template at `index` for these words, with the paraphrase when one is safe. */
 export declare function ackAt(index: number, text: string): string;
+/** The reply at `index` for a message that is no search: it says Agentcard is working, and never that it is looking for anything. */
+export declare function waitAt(index: number): string;
+/** What a slow call that is not a new request is doing: adding a product the shopper picked, choosing a store, or going through with a cart. */
+export type SlowStep = 'product' | 'pick' | 'confirm';
+/**
+ * The reply a slow pick or confirm sends once Agentcard takes longer than the delay: fixed words that
+ * name nothing the shopper said and never say `looking for`, because the shopper already chose.
+ */
+export declare function slowStepLine(step: SlowStep): string;
 /** A template other than `avoid`, picked at random. */
 export declare function nextTemplate(avoid: number, random?: () => number): number;
 export interface AckForOptions {
@@ -37,12 +54,25 @@ export interface AckForOptions {
     nextAction?: string | null;
     /**
      * The last message the shopper read from you or from Agentcard. When it asks for an address, a name,
-     * a phone number, an email or a code, the next message answers it, so it gets no instant reply.
+     * a phone number, an email or a code, the next message answers it, so it gets no instant reply. When
+     * it asks any other question, such as `what size do you want?`, a short reply that asks for nothing
+     * new, such as `im a 37`, `medium`, `2`, `black` or `carne asada`, answers it and gets none either.
      */
     asked?: string | null;
+    /**
+     * The names of the stores the last purchase answer showed the shopper, its `stores`. A message that
+     * names one of them and nothing else, such as `Order from Tacos El Grullense` as a store card sends
+     * it, picks that store, so it gets no instant reply.
+     */
+    stores?: readonly string[] | null;
 }
 /** True when a message asks the shopper for their own details or a code, in a question or a request such as `send me your address`. */
 export declare function asksForDetails(message: string | null | undefined): boolean;
+/**
+ * True when the shopper's words answer the question the last message asked, such as `what size do you
+ * want?` or `which meat?`: the message asked a question, and the reply is short and opens no new request.
+ */
+export declare function answersQuestion(text: string, asked: string | null | undefined): boolean;
 /**
  * The instant reply for a shopper's message, such as `on it, looking for usb-c cables under $20`, to
  * send the moment the message arrives and before your model runs; or null for a message that starts no

package/dist/ack.js

@@ -11,7 +11,8 @@
  * `my mom`, and it never cuts a phrase short: a subject that runs long or carries brackets gets the
  * template without one. A reply to a question, such as `yes`, `2` or a code, and a pick of a product the
  * shopper already saw, such as `the first one`, `I'll take the KODAK AA ($13.49)` or `#2`, gets no
- * instant reply at all, because it starts no search and Agentcard answers it fast.
+ * instant reply at all, because it starts no search and Agentcard answers it fast. So does a pick of a
+ * store the shopper saw, such as `order here`, or `Order from Tacos El Grullense` as a store card sends it.
  */
 /** Each template twice: with the paraphrase in place of `{x}`, and without one. */
 const TEMPLATES = [
@@ -22,6 +23,19 @@ const TEMPLATES = [
     ['searching for {x}, one moment', 'checking on that for you now'],
     ['checking what i can find for {x}', 'on it, give me a moment'],
 ];
+/**
+ * What a slow call sends for a message that is no search, such as `yes` or `ok lets checkout`: words
+ * that say Agentcard is working and never that it is looking for anything. As many as `TEMPLATES`, so
+ * the same rotation never repeats one twice in a row, and none the same as a template's, so a wait and
+ * the next search's reply never read alike.
+ */
+const WAITS = ['one moment', 'just a sec', 'working on it', 'on it, one sec', 'hang tight', 'one sec, working on it'];
+/** Words a reply opens with before it says what it means, such as `ok` in `ok lets checkout` or `yes,` in `yes, sounds good`. */
+const FILLER = /^(?:(?:ok|okay|k|kk|yes|yeah|yea|yep|yup|ya|sure|alright|all right|cool|great|perfect|nice|so|then|and|um|uh|oh|well|hmm|now)[\s,]+)+/;
+/** A bare acknowledgement, such as `its ok`, `thats fine`, `sounds good` or `works for me`, after the filler comes off. */
+const ACKNOWLEDGED = /^(?:ok|okay|k|kk|fine|alright|all right|cool|great|perfect|good|nice|sure|yes|yeah|yep|yup|right|correct|exactly|agreed|works|(?:that|this|it) works|(?:it|that|this)(?:'?s| is) (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|all right|all good|it)|its (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|all good)|thats (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|it|all)|sounds (?:good|great|fine|perfect|right|ok|okay)|looks (?:good|great|fine|perfect|right|ok|okay)|all good|all set|no worries|no problem|np|got it|gotcha|understood|makes sense|(?:works|fine|ok|okay|good) (?:for|by|with) me|i'?m good|im good|we'?re good)(?: (?:then|now|with me|for me|to me))?$/;
+/** A step toward paying for the cart already on the table, such as `lets checkout`, `place the order` or `pay`, after the filler comes off. */
+const CHECKOUT = /^(?:(?:let'?s|lets|i want to|we want to|i'?d like to|id like to|i'?m ready to|im ready to|ready to|can you|could you|can we|go ahead and|just|please)\s+)*(?:check ?out|pay|pay now|pay for (?:it|this|that|them|the order|my order|everything)|place (?:the |my |this |that |our )?order|place it|confirm(?: (?:the|my) (?:order|purchase|cart)| it)?|complete (?:the |my )?(?:order|purchase|checkout)|finish (?:the |my )?(?:order|purchase|checkout)|proceed(?: to (?:checkout|payment|pay))?|go ahead|go for it|buy (?:it|them|this|that|these|those)(?: now)?|order it|book it|submit (?:the |my )?order|send (?:the |my )?order|do it|go|ready|i'?m ready|im ready)(?: now| then| already)?$/;
 /** Whole replies that answer a question the shopper was asked, after `please` and `thanks` come off. */
 const ANSWERS = new RegExp('^(?:' +
     [
@@ -104,6 +118,15 @@ const PICK_FRAME = new RegExp([
 ].join('|'));
 /** A frame in front of a reference to a product, taken off before the reference is read: `can i get` in `can i get the second one`. */
 const ASK_FRAME = /^(?:can i (?:get|have)|could i (?:get|have)|can you (?:get|add|order|buy)|give me|get me|gimme|i need|let me (?:get|have)|buy|order|get)\s+/;
+/** A reference to a store the shopper already saw: `order here`, `let's order from here`, `this place`, `from that restaurant`. */
+const STORE_REF = /^(?:(?:let'?s|lets|i'?ll|ill|we'?ll|i want to|i'?d like to|id like to) )?(?:(?:order|get it|buy|go|eat|try) )?(?:from |at |with )?(?:here|there|this (?:store|place|restaurant|spot|shop|one)|that (?:store|place|restaurant|spot|shop|one)|the (?:first|second|third|last|other) (?:store|place|restaurant|spot|shop))$/;
+/**
+ * Words around a store's name that only pick it: `order from` in `Order from Tacos El Grullense`, as a
+ * store card sends it, or `let's go with` and `please`. A dish named next to the store, as in
+ * `order tacos from el farolito`, is a search and stays.
+ */
+const STORE_FRAME = /^(?:(?:i'?ll|ill|i will|we'?ll|we will|let'?s|lets|let me|i want to|i'?d like to|id like to|we want to|can i|can we|could i|could we|can you|could you|i'?d|id)\s+)?(?:(?:order|get|buy|grab|try|do|pick|choose|take|use|go with|go for|go)\s+)?(?:(?:food|something|some food)\s+)?(?:(?:from|at|with)\s+)?/;
+const STORE_TAIL = /\s+(?:one|place|store|restaurant|it is|then|instead|today|tonight|now)$/;
 const PLACE = '(?:first|second|third|fourth|fifth|sixth|last|other|\\d{1,2}(?:st|nd|rd|th))';
 /** A reference to a product the shopper already saw: `that one`, `the blue one`, `the second`, `2nd option`, `#2`, `option 3`. */
 const PICK_REF = new RegExp(`^(?:(?:the|that|this) (?:[\\w'$.-]+ ){0,3}one\\b|(?:that|this|those|these|both|it)(?: ones?)?$|the ${PLACE}(?: (?:one|option|item|product|choice|result))?$|${PLACE}(?: (?:one|option|item|product|choice|result)\\b|$)|(?:option|number|item|choice|#) ?#?\\d{1,2}\\b|\\d{1,2}$)`);
@@ -122,7 +145,44 @@ function isPick(line, words) {
     if (price && price.index !== undefined && !BUDGET.test(line.slice(0, price.index)))
         return true;
     const said = words.replace(OPENER, '');
-    return PICK_FRAME.test(said) || PICK_REF.test(said.replace(ASK_FRAME, ''));
+    const asked = said.replace(ASK_FRAME, '');
+    return PICK_FRAME.test(said) || PICK_REF.test(asked) || PICK_REF.test(asked.replace(/^(?:from|at) /, '')) || STORE_REF.test(said) || STORE_REF.test(asked);
+}
+/**
+ * The ways a message can read as a store's name: as said, with the frame that only picks a store off,
+ * and with a closing word such as `place` off too, so `tacos el grullense` for `Order from Tacos El
+ * Grullense, please`. Each comes before the next, so a store whose own name holds one of those words,
+ * such as `Go Fish` or `Ramen Place`, still matches whole.
+ */
+function storeReadings(text) {
+    const words = plain(String(text ?? '')).replace(/\b(?:please|pls|thanks|thank you|thx|ty)\b/g, ' ').replace(/[^\p{L}\p{N}']+/gu, ' ').trim().replace(OPENER, '');
+    const framed = words.replace(STORE_FRAME, '');
+    const tidy = (reading) => reading.replace(/'/g, ' ').replace(/\s+/g, ' ').trim();
+    // A `the` the shopper said stays in one reading, so `order from the melt` reads two words of `The Melt - Market St`.
+    const readings = [words, framed, framed.replace(/^the\s+/, '')].flatMap((reading) => [reading, reading.replace(STORE_TAIL, '')]);
+    return [...new Set(readings.map(tidy))].filter((reading) => reading.length >= 3);
+}
+/**
+ * True when the message names one of these stores and nothing else to buy: the store's whole name, or
+ * two words of it in a row, such as `el grullense` for `Tacos El Grullense`, alone or after a frame such
+ * as `order from` or `let's go with`. One word of a name, such as `tacos`, and a dish beside the name,
+ * such as `order tacos from el farolito`, name no store.
+ */
+export function namesStore(text, storeNames) {
+    const readings = storeReadings(text);
+    if (readings.length === 0)
+        return false;
+    return (storeNames ?? []).some((raw) => {
+        const name = String(raw ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+        if (name === '')
+            return false;
+        return readings.some((said) => {
+            if (said === name || said === name.replace(/^the /, ''))
+                return true;
+            // Part of a name counts only as two words or more the shopper said, so `burger` never picks `The Burger Joint`.
+            return said.includes(' ') && ` ${name} `.includes(` ${said} `);
+        });
+    });
 }
 /** True when the shopper's words pick a product they already saw, such as `the first one`, `2` or a card's title with its price. */
 export function isPickText(text) {
@@ -154,6 +214,8 @@ const PRIVATE = [
 ];
 /** Words a cut paraphrase never ends on. */
 const TAIL = /\s+(?:for|with|and|or|but|the|a|an|to|of|in|at|on|from|under|over|below|above|near|by|who|that|which|my|some|around|about)$/;
+/** Words a paraphrase never opens with, so a reply never reads `looking for from …`. */
+const LEADING_PREPOSITION = /^(?:from|at|in|on|to|for|of|with|by|near|into|onto|off|via)\b/;
 const MAX_WORDS = 8;
 const MAX_WORD_LENGTH = 24;
 /** The text as one plain line: lowercase, no quotes, and no dash between words. */
@@ -172,6 +234,9 @@ export function isNewRequest(text) {
         return false;
     if (hasPersonalNumber(line) || PERSONAL.some((pattern) => pattern.test(line)) || PLACE_ONLY.some((pattern) => pattern.test(words)))
         return false;
+    const bare = words.replace(FILLER, '');
+    if (bare === '' || ACKNOWLEDGED.test(bare) || CHECKOUT.test(bare))
+        return false;
     return !ANSWERS.test(words) && !STATUS.test(words) && !ABOUT.test(words) && !CART_COMMAND.test(words) && !CODE.test(words) && !CHITCHAT.test(words) && !isPick(line, words);
 }
 /** A short paraphrase of what the shopper asks for, safe to read back to them, or null when none is. */
@@ -187,8 +252,9 @@ export function paraphrase(text) {
         before = rest;
         rest = rest.replace(LEAD, '');
     }
-    rest = rest.replace(/[\s,.:!?]+$/, '');
-    if (NO_PARAPHRASE.test(rest))
+    // `order from tacos el grullense` names the store, never `from tacos el grullense`.
+    rest = rest.replace(/^(?:from|at)\s+/, '').replace(/[\s,]+(?:please|pls|thanks|thank you|thx|ty)$/, '').replace(/[\s,.:!?]+$/, '');
+    if (NO_PARAPHRASE.test(rest) || LEADING_PREPOSITION.test(rest))
         return null;
     const words = rest.split(' ').filter(Boolean);
     // A long or messy subject is never cut to fit: the template goes out without one.
@@ -218,6 +284,17 @@ export function ackAt(index, text) {
     const what = paraphrase(text);
     return what ? withWhat.replace('{x}', what) : without;
 }
+/** The reply at `index` for a message that is no search: it says Agentcard is working, and never that it is looking for anything. */
+export function waitAt(index) {
+    return WAITS[((index % WAITS.length) + WAITS.length) % WAITS.length];
+}
+/**
+ * The reply a slow pick or confirm sends once Agentcard takes longer than the delay: fixed words that
+ * name nothing the shopper said and never say `looking for`, because the shopper already chose.
+ */
+export function slowStepLine(step) {
+    return step === 'product' ? 'adding it now' : step === 'confirm' ? 'on it, one moment' : 'got it, one moment';
+}
 /** A template other than `avoid`, picked at random. */
 export function nextTemplate(avoid, random = Math.random) {
     const pick = Math.floor(random() * (TEMPLATES.length - 1));
@@ -249,6 +326,23 @@ export function asksForDetails(message) {
     const sentences = plain(String(message ?? '')).split(/(?<=[.!?\n])\s+/);
     return sentences.some((sentence) => DETAILS.test(sentence) && (/\?\s*$/.test(sentence) || /^(?:please |pls )?(?:send|tell|share|give|reply|type|enter|text|drop|let me know|i need|i'll need|what|which|where)\b/.test(sentence)));
 }
+/** Words that open a new request rather than an answer, such as `find`, `can you get` or `what about`. */
+const REQUEST_LEAD = /^(?:(?:ok|okay|so|actually|also|and|no|nah|wait|hmm|um|uh|instead|nevermind|never mind|nvm|hey|hi|hello|yo|just|now|then|pls|please)[\s,]+)*(?:find|search|look|looking|show|get me|get us|help me|help|i'?m looking|im looking|i'?m after|im after|can you|could you|would you|will you|can i|could i|i want|i need|i'?d like|id like|we want|we need|we'?d like|order|buy|book|reserve|grab|how about|what about|do you have|do they have|is there|are there|something|anything|another|different|also)\b/;
+/** The most words a reply runs to when it only answers a question, as `im a 37` or `extra large please` does. */
+const MAX_ANSWER_WORDS = 4;
+/**
+ * True when the shopper's words answer the question the last message asked, such as `what size do you
+ * want?` or `which meat?`: the message asked a question, and the reply is short and opens no new request.
+ */
+export function answersQuestion(text, asked) {
+    if (!/\?/.test(String(asked ?? '')))
+        return false;
+    // A decimal size, such as `9.5`, stays one word.
+    const words = plain(String(text ?? '')).replace(/[!?,;:]+|\.(?!\d)|(?<!\d)\./g, ' ').replace(/\b(?:please|pls|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim();
+    if (!/[\p{L}\p{N}]/u.test(words) || words.split(' ').length > MAX_ANSWER_WORDS)
+        return false;
+    return !REQUEST_LEAD.test(words);
+}
 /** The steps a shopper answers with their own details or a code, never with a new request. */
 const ANSWERED_STEPS = new Set(['shipping_details', 'guest_details', 'verification_code']);
 /**
@@ -269,9 +363,9 @@ const ANSWERED_STEPS = new Set(['shipping_details', 'guest_details', 'verificati
 export function instantAck(shopperText, options = {}) {
     if (typeof options?.nextAction === 'string' && ANSWERED_STEPS.has(options.nextAction))
         return null;
-    if (asksForDetails(options?.asked))
+    if (asksForDetails(options?.asked) || answersQuestion(shopperText, options?.asked))
         return null;
-    if (!isNewRequest(shopperText))
+    if (!isNewRequest(shopperText) || namesStore(shopperText, options?.stores))
         return null;
     return ackAt(nextTemplate(templateOf(options?.previous)), shopperText);
 }

package/dist/adapters.d.ts

@@ -9,7 +9,7 @@
  * Both hand the model the JSON text `buy.handle` returns, and a failed call
  * as the error's message with every link taken out.
  */
-import type { BuyTool } from './buy-tool.js';
+import type { BuyTool, BuyToolTurn } from './buy-tool.js';
 /** @deprecated The buy tool is Anthropic's runnable tool already. Kept for one release. */
 export type AnthropicBuyTool = BuyTool;
 /** @deprecated Pass the buy tool itself: `toolRunner({ tools: [buy] })`. Returns the same object, for one release. */
@@ -34,5 +34,5 @@ export interface OpenRouterToolkit<T> {
     tool: (config: any) => T;
     z: ZodLike;
 }
-/** The buy tool for OpenRouter's `callModel({ tools: [toOpenRouterTool(buy, { tool, z })] })`. */
-export declare function toOpenRouterTool<T>(buy: BuyTool, toolkit: OpenRouterToolkit<T>): T;
+/** The buy tool, or one turn of it from `buy.turn`, for OpenRouter's `callModel({ tools: [toOpenRouterTool(buy, { tool, z })] })`. */
+export declare function toOpenRouterTool<T>(buy: BuyTool | BuyToolTurn, toolkit: OpenRouterToolkit<T>): T;

package/dist/adapters.js

@@ -2,7 +2,7 @@
 export function toAnthropicTool(tool) {
     return tool;
 }
-/** The buy tool for OpenRouter's `callModel({ tools: [toOpenRouterTool(buy, { tool, z })] })`. */
+/** The buy tool, or one turn of it from `buy.turn`, for OpenRouter's `callModel({ tools: [toOpenRouterTool(buy, { tool, z })] })`. */
 export function toOpenRouterTool(buy, toolkit) {
     const { tool, z } = toolkit ?? {};
     if (typeof tool !== 'function' || !z || typeof z.object !== 'function') {