@agent-cards/commerce-sdk 0.8.0 → 0.9.0

package/README.md

@@ -74,7 +74,7 @@ const answer = await new Anthropic().beta.messages.toolRunner({
 
 Build the client once and keep it. Every shopper's tool shares the client's access token, and the client renews the token a minute before it expires. Keep each shopper's tool as well. Agentcard keeps each purchase between calls, so a tool built for every message buys the same way, but it sends the same product links again each time Agentcard shows the same products.
 
-The model sends `ask`, `confirm`, `new_order` and `product_id`, and nothing else. 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.
+The model sends `ask`, `confirm`, `new_order`, `product_id` and `store_id`, and nothing else. 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.
 
 ## Use the tool in any framework
 
@@ -146,6 +146,16 @@ Each product in the model's view carries a `product_id`, Agentcard's id for it w
 
 `result.pick` says what happened: the product's id, and `in_cart`, whether the cart now holds it. The model reads the same `pick` in its view, by the `product_id` it sent. A pick the cart does not hold names no next step, so the model tells the shopper what Agentcard said rather than asking for a card or a yes for an older cart. A product Agentcard no longer holds, because the products are more than 15 minutes old or a newer search replaced them, adds nothing, and the model reads that it should search again with the shopper's words.
 
+## 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`.
+
+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.
+
+`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.
+
+The tool sends each store page once for the calls the model makes in one turn. A later turn whose reply presents the stores again gets their pages again, so every store the reply names arrives with its card. A store link your `sendLink` throws on counts as not sent. Agentcard lists stores only for an answer whose reply presents them as a choice: a turn that searched stores on its way to a menu, or one that shows a cart, lists none.
+
 ## Tell the shopper you are on it
 
 A first search can take Agentcard most of a minute. Pass `onWorking`, and the shopper reads an instant reply while Agentcard looks, such as `on it, looking for usb-c cables under $20` or `give me a sec, checking for a table for 2 in north beach`:
@@ -172,9 +182,9 @@ 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 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 or a zip code, and any message that answers the last answer's request for shipping or guest details or a code. The reply never reads those details back. Once you call it, the tool sends no reply of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true` when your reply went out, so the shopper hears one acknowledgement.
+`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`.
 
-Without a buy tool, `instantAck(message, { previous, nextAction })` from the package root decides the same way: `previous` is the reply you sent last, so the next one comes from another template, and `nextAction` is the last answer's `next_action`. Pass `ack: false` to the tool when you send it yourself. `ackFor` is the earlier name of the same function.
+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.
 
 ## Show what Agentcard is doing
 
@@ -251,7 +261,11 @@ The model reads one object per call:
   "shopper_need_not_reply": false,
   "shopper_already_told_looking": false,
   "link_sent": false,
-  "product_links_sent": 0
+  "product_links_sent": 0,
+  "pick": null,
+  "stores": [],
+  "store_links_sent": 0,
+  "store_pick": null
 }
 ```
 

package/dist/ack.d.ts

@@ -7,9 +7,14 @@
  *
  * The paraphrase never carries a link, an email address, a phone number, a street address or a long
  * number: the text stops before the first one, and a request that starts with one gets the template
- * without a paraphrase. A reply to a question, such as `yes`, `2`, `the first one` or a code, gets no
- * instant reply at all, because it starts no search.
+ * without a paraphrase. It never reads back the shopper's own first-person words, such as `i'll take` or
+ * `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.
  */
+/** 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;
 /**
  * True when the shopper's words start a request, and false for an answer to a question, a pick, a
  * code, small talk, or a message that carries the shopper's own details, such as a phone number or a
@@ -30,7 +35,14 @@ export interface AckForOptions {
      * shipping or guest details or a code, the next message answers it, so it gets no instant reply.
      */
     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.
+     */
+    asked?: 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;
 /**
  * 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

@@ -7,8 +7,11 @@
  *
  * The paraphrase never carries a link, an email address, a phone number, a street address or a long
  * number: the text stops before the first one, and a request that starts with one gets the template
- * without a paraphrase. A reply to a question, such as `yes`, `2`, `the first one` or a code, gets no
- * instant reply at all, because it starts no search.
+ * without a paraphrase. It never reads back the shopper's own first-person words, such as `i'll take` or
+ * `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.
  */
 /** Each template twice: with the paraphrase in place of `{x}`, and without one. */
 const TEMPLATES = [
@@ -30,6 +33,24 @@ const ANSWERS = new RegExp('^(?:' +
         '(?:option|number|no|#) ?\\d{1,2}',
     ].join('|') +
     ')$');
+/** A status report after a step the shopper was asked to take, such as `connected`, `logged in` or `ok i did it`. */
+const STATUS = /^(?:(?:ok|okay|yes|yep|yeah|alright|cool|great|so|done|there)[\s,]+)*(?:i(?:'ve| have)? |we(?:'ve| have)? )?(?:just |already |finally )?(?:connected|linked|logged in|signed in|signed up|saved|finished|added|done|did it|did that|completed|verified|approved|paid|submitted|set (?:it )?up|all set|all good|good to go|i'?m in|we'?re in|it'?s (?:done|connected|linked|added|saved|in))(?: (?:it|that|them|this|my (?:account|card|address)|the (?:account|card|address)|now|already|too|just now|on my end))*$/;
+/**
+ * A question about the conversation, an order or how things work, such as `how did it know to msg that
+ * number?`, `is it booked?` or `where is my order`: the model answers it straight away, with no search.
+ */
+const ABOUT = /^(?:(?:ok|okay|so|wait|hmm|um|uh|and|but)[\s,]+)*(?:how (?:did|does|do|come|is|was|were|are)|why (?:did|does|do|is|was|are|were|would|didn'?t|isn'?t|won'?t)|what(?:'s| is| was) (?:my|the status|happening|going on|that|this)|what happened|where(?:'s| is| are) (?:my|the order|it)|(?:is|was|has|did|will) (?:it|my|this|that|the order|the booking|the reservation)|did (?:it|that|you) (?:go|work|book|place|send|get|cancel|charge|order|change|add|remove)|will you (?:let|tell|text|notify|email|update|remind|ping|keep (?:me|us) (?:updated|posted|informed|in the loop))|when (?:will|does|do|is|did) (?:it|my|the order|they)|how long (?:will|does|until|till))\b/;
+/** A command to the cart or the order, such as `lets clear the cart`, `remove the taco` or `change the quantity to 2`. */
+const CART_COMMAND = new RegExp('^(?:(?:ok|okay|so|actually|wait|and|um|uh)[\\s,]+)*(?:let\'?s |lets |can you |could you |pls |i want to |i\'?d like to |id like to |i need to |go ahead and |just )*(?:' +
+    [
+        // Verbs that never open a search: `remove fries`, `cancel order`.
+        'remove|delete|cancel|undo|start over|take off|get rid of',
+        // Verbs that also open product names, such as `clear phone case`, `drop earrings` or `take out pizza`, count only before the cart or a reference.
+        '(?:clear|empty|reset) (?:out )?(?:the |my |our )?(?:cart|basket|order|everything|it|all)',
+        '(?:drop|swap|take out) (?:the|that|this|those|these|it|them|my|our|item|#|\\d|one|both|all|everything)',
+        '(?:change|update|edit|reduce|increase|lower|raise|move) (?:the |my |our )?(?:quantity|qty|amount|number|size|order|cart|address|delivery|pickup|time|date|tip|item|reservation|booking|it|that|this|to|the|my|our)',
+    ].join('|') +
+    ')\\b');
 /** Small talk that asks for nothing to be bought, after `please` and `thanks` come off. */
 const CHITCHAT = /^(?:(?:hi|hey|hello|yo|hiya|howdy|sup)(?: there| again)?|good (?:morning|afternoon|evening|night)|g(?:oo)?d ?night|how are (?:you|u)(?: doing)?(?: today)?|how'?s it going|what'?s up|whats up|wassup|who are (?:you|u)|what (?:can|do) (?:you|u) do|are (?:you|u) (?:a )?(?:bot|real|human|there)|you there|test(?:ing)?|bye|see (?:you|ya)|later|love (?:it|you|u)|awesome|amazing|wow|omg|ha(?:ha)+|lmao|:\)|ok cool|cool thanks|so much|very much|a lot)$/;
 /** Unit words a number names a product by, such as `10000 mah`, so it is never read as a zip code. */
@@ -47,6 +68,17 @@ const PERSONAL = [
     /\b(?:my name is|my name'?s|name is|i'?m called|my (?:address|number|phone|email|zip)|address is|phone is|email is|zip is|deliver(?:ed)? (?:it )?to|ship(?:ped)? (?:it )?to|send (?:it )?to|bring (?:it )?to|call me|text me)\b/,
     new RegExp(`(?<![\\w/.$-])\\d{5}(?:-\\d{4})?(?![\\w.,]\\d)(?!\\w)(?!\\s*${UNIT}\\b)`),
 ];
+/**
+ * A message that is only a place, as a shopper answers `what address?`: a house number and a street
+ * with no kind, such as `1801 wedemeyer`, a room number, or a named building, such as `the ferry building`.
+ * A number before a unit or a plural, such as `100 envelopes` or `100 w projector`, and a year, such as
+ * `2024 macbook air`, name a product.
+ */
+const PLACE_ONLY = [
+    new RegExp(`^(?!(?:19|20)\\d{2}\\b)\\d{2,6}\\s+(?!${UNIT}\\b)[a-z][a-z'.-]*(?:\\s+[a-z][a-z'.-]*){0,2}(?<!s)$`),
+    /^(?:room|rm)\s*#?\s*\d{1,5}[a-z]?$/,
+    /^the [a-z']+(?: [a-z']+){0,2} (?:building|tower|plaza|station|terminal|airport|center|centre|hall|campus)$/,
+];
 /** True when the text holds a phone number (10 to 15 digits, with or without separators) or a run of 12 digits or more, such as a card number. */
 function hasPersonalNumber(line) {
     if (/\d{12,}/.test(line))
@@ -58,10 +90,55 @@ function hasPersonalNumber(line) {
     }
     return false;
 }
+/** Words a reply opens with before it names its pick, such as `yes,` in `yes, the first one`. */
+const OPENER = /^(?:(?:yes|yeah|yep|yup|ya|ok|okay|sure|great|perfect|cool|nice|alright|hmm|um|uh|so|then|actually|and)[\s,]+)+/;
+/** A frame that picks from what the shopper saw: `i'll take`, `go with`, `i want the`, `add the`. */
+const PICK_FRAME = new RegExp([
+    "^(?:i'?ll|i will|ill|we'?ll|we will|i'?d|id|let'?s|lets|let me) (?:take|go with|go for|pick|choose)\\b",
+    "^(?:go|going) (?:with|for) (?:the|that|this|those|these|it|both|option|number)\\b",
+    '^(?:i|we) (?:choose|chose|pick|picked)\\b',
+    "^(?:i'?ll|i will|ill|i'?d|we'?ll) (?:get|have|buy|order|do|grab) (?:the|that|this|those|these|it|both|one|option|number)\\b",
+    "^(?:i want|i'?d like|id like|i'?d prefer|i prefer|we want|we'?d like|i'?ll have|we'?ll have) (?:the|that|this|those|these|it|both)\\b",
+    '^add (?:the|that|this|those|these|it|both|one|option|number)\\b',
+    '^add #',
+].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+/;
+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}$)`);
+/** A budget word in front of a price, so `under $13.49` stays a search. */
+const BUDGET = /(?:under|below|than|max|maximum|around|about|to|budget|within|over|above|for|most)\s*$/;
+/**
+ * True for a pick of a product the shopper already saw: a frame such as `i'll take` or `i want the`, a
+ * reference such as `that one`, `the second` or `#2`, or a product title with its price, as a product
+ * card sends it: `KODAK AA Alkaline Batteries (24 Pack) ($13.49)`. Agentcard answers a pick fast, so it
+ * gets no instant reply.
+ */
+function isPick(line, words) {
+    if (/\(\s*\$\s*\d[\d,]*(?:\.\d{2})?\s*\)/.test(line))
+        return true;
+    const price = line.match(/\$\s*\d[\d,]*\.\d{2}\s*$/);
+    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, ''));
+}
+/** 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) {
+    const line = plain(String(text ?? ''));
+    return isPick(line, line.replace(/[!?.,;:]+/g, ' ').replace(/\b(?:please|pls|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim());
+}
 /** A code or a number on its own, such as `111111` or `4 2 1 9`. */
 const CODE = /^[a-z]{0,3}\d[\d ]*$/;
 /** Words that start a request and say nothing about what the shopper wants, taken off the front. */
-const LEAD = /^(?:hey|hi|hello|yo|ok|okay|so|also|and|um|uh|actually|just|please|pls|can you|could you|would you|will you|can i (?:get|have)|could i (?:get|have)|i want to|i want|i need to|i need|i would like|i'?d like|id like|i'?m looking for|im looking for|looking for|get|find|order|buy|book|grab|reserve|search for|look for|look up|show|me|us)\b[\s,]*/;
+const LEAD = /^(?:hey|hi|hello|yo|ok|okay|so|also|and|um|uh|actually|just|please|pls|can you|could you|would you|will you|can i (?:get|have)|could i (?:get|have)|i want to|i want|i need to|i need|we want|we need|i would like|i'?d like|id like|we'?d like|i'?m looking for|im looking for|we'?re looking for|looking for|i'?m after|im after|i'?m trying to find|im trying to find|trying to find|i'?m searching for|searching for|hunting for|help me find|help me get|help me|need to|want to|need|want|get|find|order|buy|book|grab|reserve|search for|look for|look up|show|me|us)\b[\s,]*/;
+/** The shopper's own first-person words, which an instant reply never reads back: `i'll take`, `my mom`. */
+const FIRST_PERSON = /\b(?:i|i'm|i'll|i'd|i've|im|ive|me|my|mine|myself|we|we're|we'll|we'd|our|ours|us)\b/;
+/** Words a subject that names a thing to buy never opens with: a verb of a command, or a pronoun. */
+const NOT_A_THING = /^(?:let|lets|let's|clear|empty|remove|delete|cancel|change|update|edit|undo|reset|start|stop|try|use|make|do|put|take|keep|it|its|it's|this|that|these|those|they|them|you|your|he|she|his|her|to|is|are|be|not|no)\b/;
+/** Characters that make a subject read as cut or as a product title rather than a request: brackets, bars and the like. */
+const MESSY = /[()[\]{}<>|\\*_=~^@#]/;
 /** A request that reads as a question or a change to the purchase: the template goes out without a paraphrase. */
 const NO_PARAPHRASE = /^(?:what|where|when|why|how|who|which|is|are|was|were|do|does|did|can|could|will|would|should|has|have|change|make|swap|switch|add|remove|drop|cancel|update|use|try|send|deliver|ship|pay|charge|check|tell|give|put|set|move|keep|skip|replace|return|refund|track|reorder|pick|choose|select|go|let|help|see|compare)\b/;
 /** Where the text stops: before the first link, contact detail, address, long number or delivery clause. */
@@ -78,6 +155,7 @@ 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)$/;
 const MAX_WORDS = 8;
+const MAX_WORD_LENGTH = 24;
 /** The text as one plain line: lowercase, no quotes, and no dash between words. */
 function plain(text) {
     return text.toLowerCase().replace(/[‘’]/g, "'").replace(/["“”`]/g, '').replace(/\s+[-–—]+\s+|[–—]/g, ' ').replace(/\s+/g, ' ').trim();
@@ -92,17 +170,18 @@ export function isNewRequest(text) {
     const words = line.replace(/[!?.,;:]+/g, ' ').replace(/\b(?:please|pls|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim();
     if (!/[\p{L}\p{N}]/u.test(words))
         return false;
-    if (hasPersonalNumber(line) || PERSONAL.some((pattern) => pattern.test(line)))
+    if (hasPersonalNumber(line) || PERSONAL.some((pattern) => pattern.test(line)) || PLACE_ONLY.some((pattern) => pattern.test(words)))
         return false;
-    return !ANSWERS.test(words) && !CODE.test(words) && !CHITCHAT.test(words);
+    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. */
 export function paraphrase(text) {
     let rest = plain(String(text ?? '')).split(/[.!?;\n](?:\s|$)/)[0] ?? '';
     for (const pattern of PRIVATE) {
         const at = rest.search(pattern);
+        // A cut inside a word takes the rest of that word too, so no word is left half read.
         if (at >= 0)
-            rest = rest.slice(0, at);
+            rest = /\S/.test(rest[at - 1] ?? '') ? rest.slice(0, at).replace(/\S+$/, '') : rest.slice(0, at);
     }
     for (let before = ''; before !== rest;) {
         before = rest;
@@ -112,10 +191,25 @@ export function paraphrase(text) {
     if (NO_PARAPHRASE.test(rest))
         return null;
     const words = rest.split(' ').filter(Boolean);
-    let short = words.slice(0, MAX_WORDS).join(' ');
+    // A long or messy subject is never cut to fit: the template goes out without one.
+    if (words.length > MAX_WORDS || words.some((word) => word.length > MAX_WORD_LENGTH))
+        return null;
+    let short = words.join(' ');
     while (TAIL.test(short))
         short = short.replace(TAIL, '');
     short = short.replace(/[\s,]+$/, '');
+    if (MESSY.test(short) || FIRST_PERSON.test(short))
+        return null;
+    // A house number and a direction, such as `1515 w pacific`, may be an address: the reply names nothing.
+    if (/^\d{3,6} [nsew]\.? /.test(short))
+        return null;
+    // The subject reads back only as a thing to buy or book: never one that opens with a verb or a
+    // pronoun, or that names the cart or the order.
+    if (NOT_A_THING.test(short) || /\b(?:cart|basket|order|orders|checkout|quantity|qty|items?)\b/.test(short))
+        return null;
+    // One word that reads as a step or a state, such as `connected` or `linked`, names nothing to buy.
+    if (!short.includes(' ') && /(?:ed|ing)$/.test(short))
+        return null;
     return /[a-z]{2}/.test(short) && isNewRequest(short) ? short : null;
 }
 /** The template at `index` for these words, with the paraphrase when one is safe. */
@@ -136,6 +230,25 @@ function templateOf(reply) {
     const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return TEMPLATES.findIndex(([withWhat, without]) => reply === without || new RegExp(`^${escape(withWhat).replace('\\{x\\}', '.+')}$`).test(reply));
 }
+/** What a question asks the shopper for when its answer is their own details or a code. */
+const DETAILS = new RegExp([
+    "\\byour (?:full |first |last |delivery |shipping |street |home |work |email |e-mail )?(?:address|name|phone(?: number)?|number|email|e-mail|zip(?: code)?|postal code|apartment|apt|unit|suite)\\b",
+    '\\b(?:delivery|shipping|street|home|drop-?off) address\\b',
+    "\\b(?:what|which) (?:is the |is your |'s the |'s your )?(?:address|name|zip|email)\\b",
+    '\\baddress (?:should|do|to|for)\\b',
+    '\\bname (?:for|on|under) the (?:order|table|booking|reservation|room|delivery)\\b',
+    '\\b(?:phone|mobile|cell|room|apartment|unit|suite|gate|flight) number\\b',
+    '\\b(?:email address|zip code|postal code)\\b',
+    '\\bwhere (?:should|do|can|would) (?:i|we)\\b.*\\b(?:send|deliver|ship|bring|drop)\\b',
+    '\\b(?:verification|confirmation|security|one-time|6-digit|six-digit) code\\b',
+    '\\b(?:enter|type|send me|share) the code\\b',
+    '\\bthe code (?:we|i|you|they)\\b',
+].join('|'));
+/** 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 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)));
+}
 /** 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']);
 /**
@@ -156,6 +269,8 @@ 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))
+        return null;
     if (!isNewRequest(shopperText))
         return null;
     return ackAt(nextTemplate(templateOf(options?.previous)), shopperText);

package/dist/adapters.js

@@ -17,6 +17,7 @@ export function toOpenRouterTool(buy, toolkit) {
             confirm: z.boolean().describe(properties.confirm.description),
             new_order: z.boolean().describe(properties.new_order.description),
             product_id: z.string().nullable().describe(properties.product_id.description),
+            store_id: z.string().nullable().describe(properties.store_id.description),
         }).strict(),
         // OpenRouter's SDK encodes what execute returns as JSON, so the view goes back as an object and reaches the model as the same text.
         execute: async (input) => JSON.parse(await buy.execute(input)),

package/dist/buy-tool.d.ts

@@ -22,7 +22,7 @@
  * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
  * to a minute, until the turn ends.
  */
-import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type FetchLike } from './client.js';
+import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type BuyToolModelView } from './model-view.js';
 /**
@@ -41,9 +41,11 @@ export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'pl
  * the page where they sign in to the store named in `store`, before Agentcard
  * can buy there. `product`: a product's page at its store, with its `title`,
  * `price`, `productId` and `imageUrl`. The page is `url`; `productId` holds no link.
+ * `store`: a store's page at the merchant, for a store the shopper can pick, with
+ * its name in `title`, `storeId` and `etaMinutes`.
  */
 export interface BuyToolLink {
-    kind: 'vault' | 'approval' | 'store_login' | 'product';
+    kind: 'vault' | 'approval' | 'store_login' | 'product' | 'store';
     url: string;
     /** When the link stops working, as an ISO 8601 timestamp, or null when Agentcard did not say. Always null on a product link. */
     expiresAt: string | null;
@@ -61,6 +63,26 @@ export interface BuyToolLink {
     productId?: string;
     /** On a product link: the product's picture, or null when Agentcard sent none. Show it beside the title. */
     imageUrl?: string | null;
+    /**
+     * On a store link: Agentcard's id for the store, with no link in it. It is the `store_id` the model
+     * reads for the same store, and the tool takes it as `store_id`, so a "Order here" button can hand it
+     * back as the shopper's pick.
+     */
+    storeId?: string;
+    /** On a store link: the store's delivery estimate in minutes, or null when the store showed none. */
+    etaMinutes?: number | null;
+}
+/** A store the answer's reply presents to choose from. */
+export interface BuyToolStore {
+    /** Agentcard's id for the store, with no link in it: the model passes it as `store_id` when the shopper picks this store. */
+    id: string;
+    name: string;
+    /** The store's page at the merchant, or null when Agentcard sent none. */
+    url: string | null;
+    /** The delivery estimate in minutes, or null when the store showed none. */
+    etaMinutes: number | null;
+    /** True when the shopper holds this store's page: `sendLink` took it in this call or an earlier call of the same model turn. */
+    linkSent: boolean;
 }
 /** A product the last search found. */
 export interface BuyToolProduct {
@@ -121,6 +143,10 @@ export interface BuyToolResult {
     next_action: BuyNextAction | null;
     /** The product the model's `product_id` picked, by its catalog id, and whether the cart now holds it; null when the call picked none. */
     pick: BuyPick | null;
+    /** The stores the reply presents to choose from, at most three, in the order the reply names them; empty when it presents none. */
+    stores: BuyToolStore[];
+    /** The store the model's `store_id` picked, or the shopper's `the second one` did, and whether Agentcard selected it; null when none was picked. */
+    store_pick: BuyStorePick | null;
     /** Every cart hash in this answer. */
     hashes: string[];
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
@@ -157,7 +183,7 @@ export interface BuyToolOptions {
      * it before any link or the model's answer. One that throws costs nothing but the instant reply.
      */
     onWorking?: (message: string) => void | Promise<void>;
-    /** `false` sends no instant reply. A function writes it from the shopper's words instead, and an empty answer sends none. */
+    /** `false` sends no instant reply. A function writes it from the shopper's words instead, and an empty answer sends none. A turn whose message `instantAck` sent nothing for gets the built-in reply that names nothing. */
     ack?: false | ((ask: string) => string | null | undefined);
     /** How long Agentcard has to answer before the instant reply goes out. Default 1500. */
     ackDelayMs?: number;
@@ -232,12 +258,16 @@ export interface BuyTool {
      * The instant reply for a shopper's message, such as `on it, looking for usb-c cables under $20`, or
      * null for a message that starts no search: `yes`, `1`, `ok`, a code, `hi`, or the shopper's own
      * details, such as a name, a phone number or an address, and any message that answers a request for
-     * shipping or guest details or a code. Call it the moment the message arrives, before your model runs,
-     * and send the text it returns. The tool then sends no reply of its own through `onWorking` for that
-     * turn, and the model reads `shopper_already_told_looking`, so the shopper never hears it twice.
+     * shipping or guest details or a code, and a pick of a product the shopper saw. Call it the moment the
+     * message arrives, before your model runs, and send the text it returns. When it returns a reply, the
+     * tool sends none of its own through `onWorking` for that turn, and the model reads
+     * `shopper_already_told_looking`, so the shopper never hears it twice. When it returns null for a
+     * message that picks nothing, such as `yes`, a slow call still sends `onWorking` a reply that names nothing.
      */
     instantAck(shopperText: string): string | null;
 }
+/** Shared with the merchant monitor so link eligibility uses the tool's product mapping. */
+export declare function productsOf(turn: BuyTurn): BuyToolProduct[];
 /**
  * A buy tool for one shopper. With a company client, name the shopper with
  * `externalUserId`; with a shopper's own `accessToken`, the token names them.

package/dist/buy-tool.js

@@ -24,9 +24,9 @@
  */
 import { AgentcardApiError, AgentcardClient, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
-import { forModel, forModelError, money, pickId, shownProducts } from './model-view.js';
+import { forModel, forModelError, money, pickId, shownProducts, shownStores } from './model-view.js';
 import { toMessages } from './messages.js';
-import { ackAt, instantAck as instantAckOf, isNewRequest, nextTemplate } from './ack.js';
+import { ackAt, instantAck as instantAckOf, isNewRequest, isPickText, nextTemplate } from './ack.js';
 /** The pause before the one read that follows a placement Agentcard is still finishing. */
 const PLACEMENT_WAIT_MS = 12_000;
 /** After a turn that outlived Agentcard's budget: one read every 5 seconds, for at most a minute. */
@@ -46,6 +46,12 @@ const AFTER_PLACEMENT = new Set(['nothing_to_confirm', 'conversation_closed', 't
 const ACK_DELAY_MS = 1_500;
 /** A call that starts this soon after the last one ended belongs to the same model turn, which gets one instant reply. */
 const SAME_TURN_MS = 15_000;
+/** A product name shorter than this, such as `AA`, is too short to tell a pick from a search. */
+const MIN_NAME_LENGTH = 12;
+/** Text as lowercase words with single spaces, so a product's name is found in a message that quotes it. */
+function productWords(text) {
+    return String(text ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+}
 /** How long after `instantAck` the model's first call still belongs to the turn it acknowledged. */
 const APP_TURN_MS = 120_000;
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
@@ -59,6 +65,7 @@ const ANSWER_LATE = "Agentcard's answer took too long to come back. Call this to
 const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shopper the cart as it stands now.';
 const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper what they want.';
 const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
+const STORE_PICK_GONE = "The store the shopper picked is no longer among the stores Agentcard found, so no store was chosen. Call this tool again with the shopper's words and store_id null, and Agentcard searches again.";
 const PICK_GONE = "The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.";
 /**
  * The pick as a later read of the conversation shows it: a pick the early answer found missing is in
@@ -74,7 +81,8 @@ function pickAfter(pick, carts) {
 function hashesOf(cart, carts) {
     return [...new Set([cart?.hash, ...carts.map((c) => c.hash)].filter((h) => typeof h === 'string' && h !== ''))];
 }
-function productsOf(turn) {
+/** Shared with the merchant monitor so link eligibility uses the tool's product mapping. */
+export function productsOf(turn) {
     return turn.catalog ? productsOfCatalog(turn.catalog) : [];
 }
 /** The products of a search, as the tool reads them. */
@@ -94,6 +102,10 @@ function productsOfCatalog(catalog) {
         linkSent: false,
     }));
 }
+/** The stores an answer presents, as the tool reads them. */
+function storesOf(stores) {
+    return (stores?.items ?? []).map((store) => ({ id: store.id, name: store.name, url: store.store_page_url, etaMinutes: store.eta_minutes, linkSent: false }));
+}
 /** The store login link an answer carries, read from its own fields: a link in `reply` is never pulled out. */
 function storeLoginOf(turn) {
     if (!turn.store_login_url)
@@ -119,6 +131,8 @@ function answerOf(turn) {
         error_code: turn.error_code,
         next_action: turn.next_action,
         pick: turn.pick,
+        stores: storesOf(turn.stores),
+        store_pick: turn.store_pick,
         hashes: hashesOf(turn.cart, turn.carts),
         envelope: turn.raw,
     };
@@ -217,6 +231,8 @@ function resultOfRefusal(error) {
         error_code: error.code,
         next_action: null,
         pick: null,
+        stores: [],
+        store_pick: null,
         hashes: hashesOf(null, carts),
         envelope: error.body,
     });
@@ -230,6 +246,8 @@ function resultOfRefusal(error) {
         return answer(STILL_WORKING, []);
     if (error.code === 'pick_not_found')
         return answer(PICK_GONE, []);
+    if (error.code === 'store_pick_not_found')
+        return answer(STORE_PICK_GONE, []);
     return null;
 }
 /** A shopper Agentcard has not connected to this company yet: the Vault link where they connect and add a card. */
@@ -251,6 +269,8 @@ function needsCard(link, body) {
         error_code: 'user_not_connected',
         next_action: 'add_card',
         pick: null,
+        stores: [],
+        store_pick: null,
         hashes: [],
         envelope: body,
     };
@@ -368,29 +388,42 @@ export function buyTool(options) {
      */
     let appAck = null;
     let lastNextAction = null;
+    /** The last reply Agentcard wrote: a message that answers its question for an address or a code gets no instant reply. */
+    let lastReply = null;
+    /** True for a turn whose message `instantAck` sent no reply for and that picks nothing: a slow call still tells the shopper, in words that name nothing. */
+    let neutralTurn = false;
+    /** The names of the products the last answer showed, which a pick takes by `product_id`: a message that names one picks it. */
+    let shownNames = [];
+    const namesShownProduct = (text) => {
+        const said = productWords(text);
+        return said !== '' && shownNames.some((name) => said.includes(name));
+    };
     /** The app's own instant reply: the turn its message opens sends no `onWorking` reply. */
     const instantAck = (shopperText) => {
         const text = String(shopperText ?? '');
-        const said = instantAckOf(text, { nextAction: lastNextAction }) !== null;
+        // A shopper who sends a product's name, as a tap on its card does, picks it: no "looking for" reply.
+        const pick = namesShownProduct(text) || isPickText(text);
+        const said = !pick && instantAckOf(text, { nextAction: lastNextAction, asked: lastReply }) !== null;
         // The same rotation onWorking uses, so the next reply comes from another template.
         if (said)
             lastTemplate = nextTemplate(lastTemplate);
-        appAck = { at: Date.now(), said };
+        appAck = { at: Date.now(), said, pick };
         return said ? ackAt(lastTemplate, text) : null;
     };
     /**
      * Holds the instant reply for a new request until `ackDelayMs` passes. `cancel` stops one that has
      * not gone out, and frees the turn's reply for a later call.
      */
-    const holdAck = (ask) => {
-        if (!onWorking || turnAcked || !isNewRequest(ask))
+    const holdAck = (ask, neutral) => {
+        if (!onWorking || turnAcked || (!neutral && (!isNewRequest(ask) || namesShownProduct(ask))))
             return null;
         turnAcked = true;
         let held = true;
         const timer = setTimeout(() => {
             held = false;
             let text;
-            if (writeAck) {
+            // A neutral turn's message held no request safe to read back, so no writer sees it.
+            if (writeAck && !neutral) {
                 try {
                     text = writeAck(ask);
                 }
@@ -400,7 +433,8 @@ export function buyTool(options) {
             }
             else {
                 lastTemplate = nextTemplate(lastTemplate);
-                text = ackAt(lastTemplate, ask);
+                // A neutral reply names nothing: the shopper's message held no request safe to read back.
+                text = ackAt(lastTemplate, neutral ? '' : ask);
             }
             if (typeof text !== 'string' || text.trim() === '') {
                 turnAcked = false;
@@ -688,10 +722,40 @@ export function buyTool(options) {
     };
     /** The products a streamed search found, as an answer the page delivery reads: its conversation, its search and its products. */
     const earlyPages = (conversationId, asOf, products) => ({ conversation_id: conversationId, envelope: { catalog: { as_of: asOf } }, products });
+    /** The store pages this tool sent last, with their conversation and the model turn that sent them. */
+    let lastStorePages = null;
+    /**
+     * The page of each store the reply presents, sent once per page in a model turn. Agentcard lists
+     * stores only on an answer whose reply presents them, so a later model turn that presents them
+     * again sends their pages again, and the calls of one model turn send each page once. A store
+     * whose id holds a link is left out, as the model view leaves it out. A page whose `sendLink`
+     * throws stays unsent, and the call goes on.
+     */
+    const deliverStorePages = async (result, call) => {
+        if (!sendLink || !result.stores?.length)
+            return result;
+        const kept = lastStorePages?.conversationId === result.conversation_id && lastStorePages.turn === call.turn;
+        const held = new Set(kept && lastStorePages ? lastStorePages.urls : []);
+        for (const store of shownStores(result.stores)) {
+            if (!store.url)
+                continue;
+            if (!held.has(store.url)) {
+                try {
+                    await sendLink({ kind: 'store', url: store.url, title: store.name, storeId: store.id, etaMinutes: store.etaMinutes, expiresAt: null });
+                }
+                catch {
+                    continue;
+                }
+            }
+            held.add(store.url);
+        }
+        lastStorePages = { conversationId: result.conversation_id, turn: call.turn, urls: held };
+        return { ...result, stores: result.stores.map((store) => (store.url && held.has(store.url) ? { ...store, linkSent: true } : store)) };
+    };
     /** One batch of pages at a time: a call that overlaps another reads the pages that one sent. */
     let pagesInTurn = Promise.resolve();
     const deliverPagesInTurn = (result, call) => {
-        const batch = pagesInTurn.then(() => deliverPages(result, call));
+        const batch = pagesInTurn.then(() => deliverPages(result, call)).then((delivered) => deliverStorePages(delivered, call));
         pagesInTurn = batch.catch(() => { });
         return batch;
     };
@@ -713,8 +777,9 @@ export function buyTool(options) {
         const ask = input.ask.trim();
         if (!confirm && ask === '')
             throw new TypeError("Put the shopper's words in ask.");
-        // A pick chooses from the products this conversation showed: never on a confirm, and never on a new order, which shows none yet.
-        const pick = !confirm && !input.new_order && input.product_id ? { product_id: input.product_id } : null;
+        // A pick chooses from the products or stores this conversation showed: never on a confirm, and never on a new order, which shows none yet.
+        const picks = !confirm && !input.new_order;
+        const pick = picks && input.product_id ? { product_id: input.product_id } : picks && input.store_id ? { store_id: input.store_id } : null;
         const body = {
             resume: true,
             ...(confirm ? { confirm: true, payment_source: 'vault' } : { ask }),
@@ -729,13 +794,17 @@ export function buyTool(options) {
         const opened = appAck && Date.now() - appAck.at < APP_TURN_MS ? appAck : null;
         appAck = null;
         if (opened) {
-            turnAcked = true;
+            // Only a reply the app sent, or a pick, quiets onWorking: a message such as `yes` that starts a
+            // slow search still gets a reply that names nothing.
+            turnAcked = opened.said || opened.pick;
+            neutralTurn = !turnAcked;
             ackOut = null;
             ackDelivered = opened.said;
             modelTurn += 1;
         }
         else if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
             turnAcked = false;
+            neutralTurn = false;
             ackOut = null;
             ackDelivered = false;
             modelTurn += 1;
@@ -743,7 +812,7 @@ export function buyTool(options) {
         const callTurn = modelTurn;
         running += 1;
         // A pick adds a product the shopper already saw, so no "looking for" reply goes out, as for "the first one".
-        const ack = confirm || pick ? null : holdAck(ask);
+        const ack = confirm || pick ? null : holdAck(ask, neutralTurn);
         try {
             let turn = null;
             let refusal;
@@ -779,6 +848,11 @@ export function buyTool(options) {
             const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true });
             const result = ackDelivered ? { ...delivered, shopper_already_told_looking: true } : delivered;
             lastNextAction = result.next_action;
+            lastReply = result.reply;
+            // An answer that lists products replaces the names, even when every one is too short to keep.
+            const shown = shownProducts(result.products);
+            if (shown.length > 0)
+                shownNames = shown.map((product) => productWords(product.name)).filter((name) => name.length >= MIN_NAME_LENGTH);
             if (onResult) {
                 try {
                     await onResult(result);

package/dist/client.d.ts

@@ -94,10 +94,14 @@ export interface BuyRequest {
     new_order?: true;
     /**
      * The product the shopper picked from the last search's `catalog.items`, by its `id` or its `ref`:
-     * Agentcard adds exactly that item, with no new search. Goes with an `ask`, never with `confirm` or `new_order`.
+     * Agentcard adds exactly that item, with no new search. Or the store the shopper picked from the last
+     * answer's `stores.items`, by its `id`: Agentcard selects exactly that store before the turn runs.
+     * Goes with an `ask`, never with `confirm` or `new_order`.
      */
     pick?: {
         product_id: string;
+    } | {
+        store_id: string;
     };
     payment_source?: 'vault';
     delivery_address?: BuyDeliveryAddress;
@@ -177,6 +181,30 @@ export interface BuyPick {
     ref: string | null;
     in_cart: boolean;
 }
+/**
+ * One store a delivery store search found that the answer's reply names. `id` holds no link and is what
+ * `pick.store_id` takes; `store_page_url` is the store's page at the merchant. `eta_minutes` is the
+ * merchant's delivery estimate, or null when it showed none.
+ */
+export interface BuyStoreChoice {
+    id: string;
+    name: string;
+    store_page_url: string | null;
+    eta_minutes: number | null;
+}
+/** The stores an answer's reply presents to choose from, at most three, in the order the reply names them. */
+export interface BuyStores {
+    merchant: string;
+    merchant_name: string;
+    items: BuyStoreChoice[];
+    as_of: string | null;
+}
+/** The store a store pick named, and whether Agentcard selected it before the turn ran. */
+export interface BuyStorePick {
+    store_id: string;
+    name: string | null;
+    selected: boolean;
+}
 export interface BuyPaymentSource {
     source: string;
     brand: string | null;
@@ -223,6 +251,10 @@ export interface BuyTurn {
     store_login_merchant_name: string | null;
     /** The product this turn's `pick` named, and whether the cart holds it; null for a turn without one. */
     pick: BuyPick | null;
+    /** The stores this answer's reply presents to choose from; null when it presents none, and on an older API. */
+    stores: BuyStores | null;
+    /** The store this turn's `pick.store_id` named, or an answer such as `the second one` picked; null without one. */
+    store_pick: BuyStorePick | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }

package/dist/client.js

@@ -132,6 +132,18 @@ function catalogOf(v) {
     }) : [];
     return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
 }
+/** The stores an answer presents: each one with an id and a name, and no block when none has both. */
+function storesOf(v) {
+    if (!isRecord(v) || !Array.isArray(v.items))
+        return null;
+    const items = v.items.filter(isRecord).flatMap((i) => {
+        const id = str(i.id);
+        const name = str(i.name);
+        const eta = num(i.eta_minutes);
+        return id && name ? [{ id, name, store_page_url: pageUrl(i.store_page_url), eta_minutes: eta }] : [];
+    });
+    return items.length ? { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, as_of: str(v.as_of) } : null;
+}
 function paymentSourceOf(v) {
     return isRecord(v) && str(v.source) ? { source: v.source, brand: str(v.brand), last4: str(v.last4) } : null;
 }
@@ -165,6 +177,8 @@ export function turnOf(body) {
         store_login_merchant_name: str(body.store_login_merchant_name),
         next_action: typeof body.next_action === 'string' && NEXT_ACTIONS.has(body.next_action) ? body.next_action : null,
         pick: isRecord(body.pick) && str(body.pick.product_id) ? { product_id: body.pick.product_id, ref: str(body.pick.ref), in_cart: body.pick.in_cart === true } : null,
+        stores: storesOf(body.stores),
+        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,
         raw: body,
     };
 }

package/dist/definition.d.ts

@@ -1,7 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with four required fields, `product_id` null unless the shopper
- * picks a product they were shown. The delivery address and the
+ * JSON Schema with five required fields, `product_id` null unless the shopper
+ * picks a product they were shown and `store_id` null unless they pick a store. The delivery address and the
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
@@ -9,8 +9,9 @@ export declare const BUY_TOOL_NAME = "buy";
 /** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
 export declare const BUY_TOOL_DESCRIPTION: string;
 /**
- * What the model sends: `ask`, `confirm` and `new_order` every time, and `product_id`, null unless the
- * shopper picks a product from the last result. Your own code may leave `product_id` out.
+ * What the model sends: `ask`, `confirm` and `new_order` every time, `product_id`, null unless the
+ * shopper picks a product from the last result, and `store_id`, null unless they pick a store from it.
+ * Your own code may leave `product_id` and `store_id` out.
  */
 export interface BuyToolInput {
     ask: string;
@@ -18,6 +19,8 @@ export interface BuyToolInput {
     new_order: boolean;
     /** The `product_id` of the product the shopper picked from the last result's `products`, or null. */
     product_id?: string | null;
+    /** The `store_id` of the store the shopper picked from the last result's `stores`, or null. */
+    store_id?: string | null;
 }
 /** A type, not an interface, so it fits the SDKs' own input schema types, which take any key. */
 export type BuyToolInputSchema = {
@@ -39,6 +42,10 @@ export type BuyToolInputSchema = {
             type: ['string', 'null'];
             description: string;
         };
+        store_id: {
+            type: ['string', 'null'];
+            description: string;
+        };
     };
     required: Array<keyof BuyToolInput>;
     additionalProperties: false;
@@ -52,8 +59,9 @@ export interface BuyToolDefinition {
 export declare function buyToolDefinition(): BuyToolDefinition;
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
- * string, null or left out, and nothing else. Throws a TypeError whose message
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` and
+ * `store_id` each a string, null or left out, at most one of them set, and
+ * nothing else. Throws a TypeError whose message
  * tells the model what to send.
  */
 export declare function parseBuyToolInput(value: unknown): BuyToolInput;

package/dist/definition.js

@@ -1,7 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with four required fields, `product_id` null unless the shopper
- * picks a product they were shown. The delivery address and the
+ * JSON Schema with five required fields, `product_id` null unless the shopper
+ * picks a product they were shown and `store_id` null unless they pick a store. The delivery address and the
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
@@ -25,6 +25,8 @@ export const BUY_TOOL_DESCRIPTION = [
     "After `needs_card` with no cart, call this tool again with the shopper's request once they say they added a card.",
     'Set `new_order` to true only when the shopper drops the cart.',
     "When the shopper picks one of the `products` in your last result, by its name, its place in the list or a tap that names it, set `product_id` to that product's `product_id`, so Agentcard adds exactly that product; otherwise set it to null.",
+    "When the shopper picks one of the `stores` in your last result, by its name, its place in the list or a tap that names it, set `store_id` to that store's `store_id`, so Agentcard orders from exactly that store; otherwise set it to null. Never set both `product_id` and `store_id`.",
+    'Store links reach the shopper on their own, beside your reply, as product links do: `store_links_sent` says how many.',
     'When `pick.in_cart` is false, the product the shopper picked is not in the cart: tell the shopper what `reply` says, and never ask them to confirm the cart.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
@@ -45,17 +47,22 @@ export function buyToolDefinition() {
                     type: ['string', 'null'],
                     description: "The `product_id` of the product the shopper picked from the `products` in your last result. Null when they picked none.",
                 },
+                store_id: {
+                    type: ['string', 'null'],
+                    description: 'The `store_id` of the store the shopper picked from the `stores` in your last result. Null when they picked none.',
+                },
             },
-            required: ['ask', 'confirm', 'new_order', 'product_id'],
+            required: ['ask', 'confirm', 'new_order', 'product_id', 'store_id'],
             additionalProperties: false,
         },
     };
 }
-const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id']);
+const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id', 'store_id']);
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
- * string, null or left out, and nothing else. Throws a TypeError whose message
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` and
+ * `store_id` each a string, null or left out, at most one of them set, and
+ * nothing else. Throws a TypeError whose message
  * tells the model what to send.
  */
 export function parseBuyToolInput(value) {
@@ -74,7 +81,7 @@ export function parseBuyToolInput(value) {
     const fields = input;
     const extra = Object.keys(fields).find((key) => !FIELDS.has(key));
     if (extra !== undefined)
-        throw new TypeError(`The buy tool takes only ask, confirm, new_order and product_id, and ${extra} is not one of them.`);
+        throw new TypeError(`The buy tool takes only ask, confirm, new_order, product_id and store_id, and ${extra} is not one of them.`);
     if (typeof fields.ask !== 'string')
         throw new TypeError("Set ask to the shopper's words, as a string.");
     if (typeof fields.confirm !== 'boolean')
@@ -85,7 +92,15 @@ export function parseBuyToolInput(value) {
     if (productId !== undefined && productId !== null && typeof productId !== 'string') {
         throw new TypeError("Set product_id to the picked product's product_id, as a string, or to null.");
     }
-    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order, product_id: typeof productId === 'string' && productId.trim() !== '' ? productId.trim() : null };
+    const storeId = fields.store_id;
+    if (storeId !== undefined && storeId !== null && typeof storeId !== 'string') {
+        throw new TypeError("Set store_id to the picked store's store_id, as a string, or to null.");
+    }
+    const product = typeof productId === 'string' && productId.trim() !== '' ? productId.trim() : null;
+    const store = typeof storeId === 'string' && storeId.trim() !== '' ? storeId.trim() : null;
+    if (product && store)
+        throw new TypeError('Set product_id or store_id for the one thing the shopper picked, and the other to null.');
+    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order, product_id: product, store_id: store };
 }
 /** A fresh copy of the tool in OpenAI's function-calling format: plain JSON, so an SDK that sends it as is sends exactly this. */
 export function openAIBuyTool() {

package/dist/index.d.ts

@@ -2,12 +2,12 @@ export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatur
 export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, type PurchaseFacts, } from './message.js';
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, } from './client.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, type MessageStream, type MessageStreamOptions, } from './messages.js';
-export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, } from './buy-tool.js';
+export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolStore, } from './buy-tool.js';
 export { instantAck, ackFor, type AckForOptions } from './ack.js';
-export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, } from './model-view.js';
+export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRouterToolkit, type ZodLike, } from './adapters.js';
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
 export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';

package/dist/model-view.d.ts

@@ -4,10 +4,11 @@
  * model that holds a link writes it into the chat. So a link never enters
  * this view: `sendLink` delivers it, and the model reads `link_sent` for the
  * Vault and approval links, and `link_sent` on each product and
- * `product_links_sent` for the products' store pages.
+ * `product_links_sent` for the products' store pages, and `link_sent` on each
+ * store and `store_links_sent` for the pages of the stores to pick from.
  */
 import type { BuyNextAction } from './client.js';
-import type { BuyToolProduct, BuyToolResult, BuyToolStatus } from './buy-tool.js';
+import type { BuyToolProduct, BuyToolResult, BuyToolStatus, BuyToolStore } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
     items: Array<{
@@ -29,6 +30,15 @@ export interface BuyToolModelProduct {
     /** True when the shopper holds this product's store page, which `sendLink` delivered beside the reply. */
     link_sent: boolean;
 }
+export interface BuyToolModelStore {
+    /** What the model passes as `store_id` when the shopper picks this store: Agentcard's id, never a link. */
+    store_id: string;
+    name: string;
+    /** The delivery estimate in minutes, or null when the store showed none. */
+    eta_minutes: number | null;
+    /** True when the shopper holds this store's page, which `sendLink` delivered beside the reply. */
+    link_sent: boolean;
+}
 /** The buy tool's answer as the model reads it. */
 export interface BuyToolModelView {
     status: BuyToolStatus;
@@ -54,6 +64,15 @@ export interface BuyToolModelView {
         product_id: string | null;
         in_cart: boolean;
     } | null;
+    /** The stores the reply presents to choose from, in the order it names them. */
+    stores: BuyToolModelStore[];
+    /** How many store pages of the stores above the shopper holds, 0 when none went out. */
+    store_links_sent: number;
+    /** The store this call's `store_id` (or an answer such as `the second one`) picked, and whether Agentcard selected it; null when none was picked. */
+    store_pick: {
+        store_id: string;
+        selected: boolean;
+    } | null;
 }
 /**
  * The text with every link taken out: a Markdown link keeps its label, an address with a path or a scheme goes
@@ -73,6 +92,11 @@ export declare function money(minor: number | null | undefined, currency: string
  * shopper never holds a product link the model cannot name.
  */
 export declare function shownProducts(products: readonly BuyToolProduct[] | null | undefined): BuyToolProduct[];
+/**
+ * The stores the model reads: each one whose id and name hold no link, so the model never reads a
+ * link and never offers a store without its name. The tool sends pages for these same stores.
+ */
+export declare function shownStores(stores: readonly BuyToolStore[] | null | undefined): BuyToolStore[];
 /**
  * The id the model passes back for a product: Agentcard's link-free ref, else the product's own id when
  * it holds no link, else null. A retail product's id is its store page, and a link never reaches the model.

package/dist/model-view.js

@@ -93,6 +93,13 @@ export function money(minor, currency) {
 export function shownProducts(products) {
     return (products ?? []).filter((product) => stripLinks(product.name) !== '' && stripLinks(product.store ?? '') !== '').slice(0, MAX_PRODUCTS);
 }
+/**
+ * The stores the model reads: each one whose id and name hold no link, so the model never reads a
+ * link and never offers a store without its name. The tool sends pages for these same stores.
+ */
+export function shownStores(stores) {
+    return (stores ?? []).filter((store) => store.id !== '' && stripLinks(store.id) === store.id && stripLinks(store.name) !== '');
+}
 /**
  * The id the model passes back for a product: Agentcard's link-free ref, else the product's own id when
  * it holds no link, else null. A retail product's id is its store page, and a link never reaches the model.
@@ -121,6 +128,8 @@ export function forModel(result) {
     const status = typeof result.status === 'string' && MODEL_STATUSES.has(result.status) ? result.status : 'needs_input';
     const products = shownProducts(result.products);
     const held = (product) => product.linkSent === true && typeof product.url === 'string' && product.url !== '';
+    const stores = shownStores(result.stores);
+    const heldStore = (store) => store.linkSent === true && typeof store.url === 'string' && store.url !== '';
     return {
         status,
         next_action: result.next_action ?? null,
@@ -136,6 +145,12 @@ export function forModel(result) {
         product_links_sent: new Set(products.filter(held).map((product) => product.url)).size,
         // The id the model sent, never the catalog id, which is a store page for a retail product.
         pick: result.pick ? { product_id: pickId({ id: result.pick.product_id, ref: result.pick.ref }), in_cart: result.pick.in_cart === true } : null,
+        stores: stores.map((store) => ({ store_id: store.id, name: stripLinks(store.name), eta_minutes: store.etaMinutes, link_sent: heldStore(store) })),
+        store_links_sent: new Set(stores.filter(heldStore).map((store) => store.url)).size,
+        // A store id with a link in it is never read back to the model.
+        store_pick: result.store_pick && stripLinks(result.store_pick.store_id) === result.store_pick.store_id
+            ? { store_id: result.store_pick.store_id, selected: result.store_pick.selected === true }
+            : null,
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
   "type": "module",
   "main": "dist/index.js",