@agent-cards/commerce-sdk 0.8.0 → 0.10.0

package/dist/ack.js

@@ -7,8 +7,12 @@
  *
  * 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. 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 = [
@@ -19,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('^(?:' +
     [
@@ -30,6 +47,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 +82,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 +104,101 @@ 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+/;
+/** 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}$)`);
+/** 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, '');
+    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) {
+    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. */
@@ -77,7 +214,10 @@ 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. */
 function plain(text) {
     return text.toLowerCase().replace(/[‘’]/g, "'").replace(/["“”`]/g, '').replace(/\s+[-–—]+\s+|[–—]/g, ' ').replace(/\s+/g, ' ').trim();
@@ -92,30 +232,50 @@ 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;
+    const bare = words.replace(FILLER, '');
+    if (bare === '' || ACKNOWLEDGED.test(bare) || CHECKOUT.test(bare))
         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;
         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);
-    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. */
@@ -124,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));
@@ -136,6 +307,42 @@ 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)));
+}
+/** 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']);
 /**
@@ -156,7 +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 (!isNewRequest(shopperText))
+    if (asksForDetails(options?.asked) || answersQuestion(shopperText, options?.asked))
+        return null;
+    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') {
@@ -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

@@ -21,10 +21,21 @@
  * still finishing gets one 12-second pause and one read of the conversation.
  * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
  * to a minute, until the turn ends.
+ *
+ * `turn` binds the tool to one shopper message: the calls the model makes
+ * through it hand their links, answers and instant reply to that turn's own
+ * callbacks and lists, so a shopper who sends a second message before the
+ * first is answered never gets one message's cards beside the other's reply.
+ * Every turn of one tool still shares the shopper's conversation state, such
+ * as the store pages already sent. A turn with `onItem` hands the app its
+ * messages and links as one sequence, in the order they happened, and spaces
+ * the messages like someone texting.
  */
-import { 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';
+import { type MessagePace, type MessageStream } from './messages.js';
+import type { ShopperMessage } from './shopper-message.js';
 /**
  * Where the purchase stands:
  * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
@@ -41,10 +52,17 @@ 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.
+ * A flight option is a `product` link too, with a null `url`, since a flight has no page.
+ * `store`: a store's page at the merchant, for a store the shopper can pick, with
+ * its name in `title`, `storeId`, `etaMinutes` and `imageUrl`.
  */
 export interface BuyToolLink {
-    kind: 'vault' | 'approval' | 'store_login' | 'product';
-    url: string;
+    kind: 'vault' | 'approval' | 'store_login' | 'product' | 'store';
+    /**
+     * The page the link opens. Null only on a product link for a product with no page at a store, a
+     * flight option: show its card with no link to open, and let `productId` pick it.
+     */
+    url: string | null;
     /** 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;
     /** On a store login link: the store's name, or null when Agentcard named none. */
@@ -59,8 +77,33 @@ export interface BuyToolLink {
      * can hand it back as the shopper's pick. Absent when Agentcard sent no such id, as an older API does.
      */
     productId?: string;
-    /** On a product link: the product's picture, or null when Agentcard sent none. Show it beside the title. */
+    /**
+     * On a product link: the product's picture. On a store link: the picture the store's card shows at
+     * the merchant. 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;
+    /** The picture the store's card shows at the merchant, or null when Agentcard sent none. */
+    imageUrl: string | 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 +164,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. */
@@ -138,7 +185,9 @@ export interface BuyToolOptions {
      * holds the link before the model answers. A `sendLink` that throws on a
      * Vault or approval link makes the call throw too, and the model never
      * reads that a link went out. One that throws on a product link leaves
-     * that product's `linkSent` false, and the call goes on.
+     * that product's `linkSent` false, and the call goes on. It hears the links of every call, whatever
+     * shopper message the call answers: a chat app where a shopper can send a second message before the
+     * first is answered passes `sendLink` to `buy.turn` instead, so each link reaches the turn it belongs to.
      */
     sendLink?: (link: BuyToolLink) => void | Promise<void>;
     /** Where the orders go, when you already hold the shopper's address. The model never sets it. */
@@ -152,12 +201,14 @@ export interface BuyToolOptions {
     /**
      * Sends the shopper an instant reply, such as `on it, looking for usb-c cables under $20`, while
      * Agentcard works on a new request. It goes out when Agentcard has not answered within
-     * `ackDelayMs`, once for the calls the model makes in one turn, and never on a confirm, a pick or a
-     * reply such as `yes`, `2` or a code. The call waits for it before it returns, so the shopper reads
-     * it before any link or the model's answer. One that throws costs nothing but the instant reply.
+     * `ackDelayMs`, once for the calls the model makes in one turn. A slow pick gets `adding it now`
+     * for a product or `got it, one moment` for a store or a place in a list. A slow confirm gets
+     * `on it, one moment`. These replies name nothing the shopper said. A code gets no reply.
+     * The call waits for it before it returns, so the shopper reads 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;
@@ -165,7 +216,8 @@ export interface BuyToolOptions {
      * Called with the whole answer once per call, after its links went out and before the model reads
      * it, so your app can show the carts, the status, `next_action` or the order id without wrapping the
      * tool. A refusal the tool turns into an answer, such as a Vault link for a shopper with no card,
-     * counts; a call that throws calls nothing. One that throws costs nothing but the call to it.
+     * counts; a call that throws calls nothing. One that throws costs nothing but the call to it. Like
+     * `sendLink`, it hears every call; pass it to `buy.turn` to hear only the answers of one turn.
      */
     onResult?: (result: BuyToolResult) => void | Promise<void>;
     /**
@@ -232,12 +284,137 @@ 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 or a store the shopper saw, such as
+     * `Order from Tacos El Grullense` as a store card sends it. 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;
+    /**
+     * Opens the turn of one shopper message and returns the tool for that turn: pass it to your model in
+     * place of the tool, as `tools: [turn]`. Each call the model makes through it hands its links to this
+     * turn's `sendLink` and keeps them in `turn.links`, hands its answer to this turn's `onResult` and
+     * keeps it in `turn.results`, and sends this turn's instant reply to its `onWorking`. A shopper who
+     * sends a second message while the first still runs gets a second turn, and no link, cart or reply
+     * of one reaches the other. Call it the moment the message arrives, before your model runs: with an
+     * `onWorking`, the instant reply `instantAck` would return goes out at once. An option left out falls
+     * back to the one the tool was built with.
+     */
+    turn(shopperText: string, options?: BuyToolTurnOptions): BuyToolTurn;
+}
+/**
+ * One thing a turn hands the shopper: a message, such as the instant reply or a paragraph your model
+ * wrote, or a link, such as a product card. `buy.turn`'s `onItem` hears them in the order they happened.
+ */
+export type BuyToolTurnItem = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'link';
+    link: BuyToolLink;
+};
+/** The callbacks of one turn. Each one left out falls back to the option of the same name the tool was built with, except with `onItem`. */
+export interface BuyToolTurnOptions {
+    /**
+     * Hears everything the turn hands the shopper, one item at a time and in the order it happened: the
+     * instant reply and each message your model writes through `turn.messageStream()` or `turn.say()` as
+     * `text` items, and each link as a `link` item. Show each item below the one before it, and the chat
+     * reads in the order it happened: a search's cards, then the model's words about them. Each item
+     * waits for the one before it to settle. With `onItem`, the turn hands no link to a `sendLink` and
+     * no instant reply to an `onWorking`, the tool's included: pass `onItem`, or those, to the turn.
+     */
+    onItem?: (item: BuyToolTurnItem) => void | Promise<void>;
+    /**
+     * With `onItem`: spaces the turn's messages like someone texting. A message waits until
+     * `typingDelay` of it has passed since the item before it went out, so the shopper reads one message
+     * at a time. Time the model spent writing counts toward the pause. Links never wait. Default `true`;
+     * `false` hands each message over the moment it is ready, and a function returns the pause in
+     * milliseconds for a message.
+     */
+    pace?: MessagePace;
+    /** With `onItem`: hears `true` when the pause before a message starts and `false` the moment that message goes out, for a typing indicator. */
+    onTyping?: (typing: boolean) => void;
+    /**
+     * Delivers a link of this turn to the shopper, as the tool's `sendLink` does. Each call waits for it.
+     * Without one, `turn.links` still takes each link, and the model reads that it went out, so return
+     * `turn.links` beside the turn's reply.
+     */
+    sendLink?: (link: BuyToolLink) => void | Promise<void>;
+    /** Sends this turn's instant reply: at once when `turn` opens on a new request, or once a slow call passes `ackDelayMs`. */
+    onWorking?: (message: string) => void | Promise<void>;
+    /** Called with the whole answer of each call this turn makes, after its links went out and before the model reads it. */
+    onResult?: (result: BuyToolResult) => void | Promise<void>;
+    /** Called with each stage Agentcard reaches on a call this turn makes. */
+    onProgress?: (progress: BuyProgress) => void;
+}
+/**
+ * The buy tool for one shopper message, from `buy.turn`. It is the same tool, with the same name,
+ * schema and methods, so a framework takes it as it takes the tool, and the calls made through it
+ * belong to this turn alone. `ack`, `links` and `results` are read-only, and JSON leaves them out, so a
+ * tool runner that sends the tool to its API sends the same fields as before.
+ */
+export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'turn'> {
+    /** The instant reply this turn sent to `onWorking` when it opened, or null when it sent none. */
+    readonly ack: string | null;
+    /**
+     * The messages Agentcard posted into this shopper's chat that the model has not read yet, oldest
+     * first, such as `card_added` once they saved a card: each one `agentcard.listen`'s or
+     * `agentcardWebhook`'s `onMessage` returned from, on the client this tool was built with. Once
+     * `messages` ran, the ones it handed the model.
+     */
+    readonly agentcardMessages: ShopperMessage[];
+    /**
+     * What to send your model for this turn: `history`, then what Agentcard told the shopper that the
+     * history does not hold yet, as the assistant's words with every link taken out, then the shopper's
+     * message as a user message. Pass it as the model's `messages` and save what the model's run ends
+     * with as the next history, so the model reads that the shopper saved a card, approved or got an
+     * order before it answers them. A message the history already holds goes in no second time, and one
+     * a failed turn never saved goes in again. The Anthropic, OpenAI and Vercel AI SDK message lists all
+     * take it. Agentcard's words join the history's last assistant message when it is plain text, and
+     * come as an assistant message of their own otherwise. `history` is never changed.
+     */
+    messages<M extends object = BuyToolTurnMessage>(history?: readonly M[] | null): Array<M | BuyToolTurnMessage>;
+    /**
+     * Every link this 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. A link `sendLink` threw on is left out. Each read returns a new array.
+     */
+    readonly links: BuyToolLink[];
+    /** The whole answer of each call this turn made, in the order the calls returned. Each read returns a new array. */
+    readonly results: BuyToolResult[];
+    /**
+     * Every message and link the turn handed over, in the order they went out: the instant reply, each
+     * link, and each message written through `messageStream()` or `say()`. An item its send threw on is
+     * left out. Return it as the turn's answer, and an app renders it in order. Each read returns a new array.
+     */
+    readonly items: BuyToolTurnItem[];
+    /**
+     * A message stream whose messages become this turn's `text` items, after the items before them, as
+     * `messageStream` cuts them: push your model's text as it streams, then `end` it. Start one for each
+     * model message. With `onItem`, the turn spaces them by its `pace`.
+     */
+    messageStream(): MessageStream;
+    /** Cuts a whole text into messages, as `toMessages` does, and hands each one over as a `text` item. Resolves once every one went out. */
+    say(text: string): Promise<void>;
 }
+/** A message in the one shape the Anthropic, OpenAI and Vercel AI SDK message lists all take. */
+export type BuyToolTurnMessage = {
+    role: 'assistant';
+    content: string;
+} | {
+    role: 'user';
+    content: string;
+};
+/**
+ * The model's messages for a turn: the history, what Agentcard told the shopper, then the shopper's
+ * words. Agentcard's words join a last assistant message of plain text, a string or text parts only,
+ * so no provider reads two assistant messages in a row. After anything else, such as a tool result
+ * or an OpenAI Responses item, they come as an assistant message of their own.
+ */
+export declare function turnMessages<M extends object>(history: readonly M[] | null | undefined, told: readonly string[], shopperText: string): Array<M | BuyToolTurnMessage>;
+/** 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.