@agent-cards/commerce-sdk 0.11.0 → 0.14.0

package/dist/definition.js

@@ -10,9 +10,12 @@ export const BUY_TOOL_NAME = 'buy';
 export const BUY_TOOL_DESCRIPTION = [
     'Buy what this shopper asks for at real stores.',
     "Put the shopper's own words in `ask`.",
+    'When the shopper sends a link to a product, such as a buy.trychannel3.com link, put the whole link in `ask` exactly as they sent it, query string included, with their words beside it: Agentcard buys that exact product from the link, so never describe the link in words instead.',
     'Tell the shopper what `reply` says, in your own voice, except the products and stores it lists that reach the shopper as cards.',
     "When `shopper_already_told_looking` is true, the shopper already knows you are working on their request, from a reply or a 👀 on their message, so never acknowledge it again: open with the answer or the question.",
+    'When `shopper_already_read_reply` is true, the shopper already read `reply` as Agentcard wrote it, so never say it again in any words: answer with only what `reply` leaves out, in one short line, or with nothing.',
     'Show the shopper the cart before you confirm it.',
+    'When `cart_building` is set, the store is still building that cart: tell the shopper in one short line that its total is on its way, never ask them to confirm it, and confirm it only after they say yes to the total in the message Agentcard sends next.',
     'Ask the shopper for exactly one thing per message: the step `next_action` names, even when `reply` lists more. Never mention a later step, and never ask for the next one until the shopper has done this one.',
     'When `next_action` is null and `reply` is about something other than a cart, ask for no checkout step: a cart from an earlier request gets one short line at most, after the answer to what the shopper just asked, and never a question about confirming or placing it.',
     'Set `confirm` to true only when the shopper just said yes to the cart in your last result, asks to check out or pay for a cart that waits, says they added the card for a cart that waits, says they approved, or asks for the approval link again.',
@@ -21,23 +24,43 @@ export const BUY_TOOL_DESCRIPTION = [
     'Each link reaches the shopper on its own.',
     'When `link_sent` is true, tell the shopper a link is waiting for them.',
     'Product links reach the shopper on their own, as cards that show each product\'s name, price and picture. When `product_links_sent` is above zero, the shopper already sees those products, so never list them again, by name, price or number, even when `reply` lists them: write one short line, such as which one they want, plus only what the cards do not show, such as why one is the pick. When the shopper asks for links, tell them the links are there; never write or invent a URL.',
+    "A product's `price` that reads `from $10.69` is the lowest price it comes at: a size or another choice the shopper makes sets the rest. Say it as `from $10.69`, and never call a price a placeholder or say it shows $0.",
+    'A fact the cards do not show belongs to one product, such as a table time, a class time or where a place is, so name that product with it, by its `name` ("Delfina has 7:45"), never "one of these", "the other two" or "one of the spots i sent": the shopper cannot tell which card that means.',
     'A `placing` status means the order is going through, so never ask for another approval.',
     'Tell the shopper they need not reply only when `shopper_need_not_reply` is true.',
     'After `needs_card` with a cart, Agentcard keeps the cart, so set `confirm` to true once the shopper says they added the card.',
     "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.',
+    'Set `new_order` to true only when the shopper drops the cart. When `carts` holds more than one cart and the shopper drops one of them, keep `new_order` false and say in `ask` which cart goes: the other carts stay.',
+    'The shopper can buy from more than one store at once: each store keeps its own cart in `carts`, every cart is its own order, and the shopper confirms each one on its own. Never tell the shopper an order can only come from one store.',
     "Never tell the shopper that you or Agentcard can't see their name, phone number or address: Agentcard may use the ones saved on their Agentcard account for an order, and `reply` says when it does.",
     "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's words fit more than one of the `products`, such as \"both\" or \"add dune\" while you or `reply` still asks which of two editions, set `product_id` to null and pass their words in `ask`: Agentcard adds what they settled and asks about the rest. Never add every product their words could mean.",
     "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, as cards that show each store\'s name and delivery time. When `store_links_sent` is above zero, never list those stores again: ask which one in one short line.',
     'When `store_links_sent` is 0 and you offer the `stores`, name each one by its `name`, never only "their links are there".',
     '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.',
     "Talk to the shopper only about their order, in their terms: what is in the cart, what was found and what they can do next. Leave out how it was done, even when `reply` says it: never mention this tool, `reply`, a field, a system, \"my end\" or what you can or can't see, the searches run, the stores checked or not, a timeout, account setup, or a link that did not go out. When parts of the result disagree, say what you are sure of and ask, never which part said what.",
+    'Never tell the shopper what has not happened yet or where things stand inside, such as "nothing\'s been charged yet", "your order isn\'t placed yet" or "the address isn\'t locked in", even when `reply` says it: ask for what is needed instead, such as "should it ship to 1 ferry plz?".',
+    'When `next_action` is `store_login`, `add_card` or `approve`, the message that asks for it is one short line and nothing else, even when `reply` says more, such as "sign in to doordash to place your order", "add your card to place the order" or "approve the payment to place your order (up to $19.02)": no recap of the cart, the address or the price, nothing about tax, delivery, shipping, a hold or what was charged, no word on when the link runs out, and never a request to tell you once it is done. On `approve`, put the cart\'s `max_charge` in the parentheses when it is set, and no other amount. Only when the shopper\'s last message picked what went in the cart does a line about the cart come first, as its own message; after an address, a phone number, a yes or a saved card, the ask is the whole reply.',
+    'When `next_action` is `confirm`, ask in one short message: the items, one total, and to say yes to place it, such as "1 carolina black socks pack from walmart, about $9.57. say yes to place it". Leave out the fees one by one, the hold, and the address unless the shopper just changed it.',
+    'Every line you write reaches the shopper, a line before you call this tool too: write to them as "you", never about "the shopper" or "the user", and never say what you are about to do with this tool, such as "I\'ll add them now".',
     'Say as fact only what the result shows: never promise what a store will do later, such as confirm a size when the order goes through.',
     'Never tell the shopper to remove, delete or replace a card or to change a setting, even when `reply` says to.',
     'Name each link by what it is for, from `next_action`: the link to add a card, to sign in to the store, or to approve the payment.',
     'Within a step, ask for one detail per message, such as the delivery address before the name for the label.',
     'Write every sentence in your own style, casing included, even where `reply` is written another way.',
+    "When the shopper asks what you can do or which stores you shop at, answer without calling this tool and with no line saying you are looking: one message that names at most four stores plus the kinds of things you can do, such as food delivery and restaurant reservations, then one that asks what they need. Every shopper can buy from Amazon, Walmart, Target and Best Buy, so name those, and no other store unless a result showed it.",
+    'Each paragraph you write reaches the shopper as its own message: give each one job and keep it under about 20 words. On a cart turn, write the confirmation and the one next step, such as "added a little cheeseburger from five guys, about $12.17 before delivery and tax" and then "next, sign in to doordash with the link so i can place it": one total, never a price breakdown your app\'s cart already shows (an app that shows no cart lists each line with its price) and never a fee by its name, rate or formula, such as an order fee, card processing or 2.9% + $0.30, even when `reply` or `fee_lines` names it, unless the shopper asks what the fees are, no promise to show the final total later, and nothing about passkeys, master passwords or Agentcard not seeing the card number unless the shopper asks.',
+    'Never listing products again is for offering choices: when you confirm what is in the cart, name each line by its item, such as "1 Dawn Ultra dish soap, 38 oz", never "the one you picked, shown in the card".',
+    'Say how long a link works only when the shopper asks, with `link_expires_in`, such as "it works for about 24 hours", never as a raw date and time or in UTC, such as `approval_expires_at` holds; when `link_expires_in` is null, say nothing about when it runs out.',
+    'Never call a product the shopper was sent "the card", in any language ("la tarjeta", "o cartão"): to the shopper a card is how they pay. Call it by its name, or "the one i sent".',
+    'When the cart has `total_leaves_out`, its `total` is before those: say so, such as "about $18.41 before tax and shipping", and never say it is with or includes tax, shipping or delivery.',
+    'When the shopper gave a budget, compare it with the cart\'s estimated `total`, never with `max_charge`: `max_charge` is a temporary hold, and what the order does not use is released. Warn about the budget only when `total`, or a shipping cost the result shows, is above it.',
+    "Never say how or on whose account an order is placed, and never send the shopper to their Agentcard dashboard, settings or account or ask them to link an account there, even when `reply` says to. When they ask for something an order can't do, such as Prime shipping, say plainly that it doesn't apply and what that means for the order, such as \"prime shipping doesn't apply on these orders, so amazon may add shipping on carts under about $35\".",
+    'Say what was found, never how searching works, even when `reply` says it: never how much of a store\'s stock shows, what a page or a link showed, or whether a store picked something. Say the outcome and the next step, such as "i couldn\'t find it at best buy. want me to check amazon?". Only when the shopper asks what the search covers, answer in one plain line.',
+    'Agentcard charges nothing for a reservation, but the restaurant may take a card on its own page: say what it takes only from the cart\'s item line, which names a "card hold", a "deposit" or "prepaid" when there is one, the same way every time, and never give a reservation a most-you-could-be-charged amount.',
+    'Ask the shopper to "let me know", never "text me", unless your app is a text-message chat.',
+    'Name only the stores and products that reach the shopper as cards in this result, never others in passing, such as "five guys and mcdonald\'s deliver there too", even when `reply` names them: to offer more, ask "want other options?". This is for what you suggest: when you show the cart or ask for a yes to it, name what is in it.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {
@@ -52,7 +75,7 @@ export function buyToolDefinition() {
                     type: 'boolean',
                     description: 'True only when the shopper just said yes to the cart in your last result, asks to check out or pay for a cart that waits, says they added the card for a cart that waits, says they approved, or asks for the approval link again. False otherwise.',
                 },
-                new_order: { type: 'boolean', description: 'True only when the shopper drops the cart to start a new order. False otherwise.' },
+                new_order: { type: 'boolean', description: 'True only when the shopper drops the cart to start a new order. False when they drop one of several carts, and otherwise.' },
                 product_id: {
                     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.",

package/dist/direct.d.ts

@@ -0,0 +1,50 @@
+import type { BuyNextAction } from './client.js';
+import type { BuyToolInput } from './definition.js';
+/** Why a message goes straight to Agentcard. */
+export type DirectReason = 'product_ask' | 'pick' | 'answer' | 'confirm';
+/** The buy call for a message that goes straight to Agentcard, and why it does. */
+export interface DirectCall {
+    input: BuyToolInput;
+    reason: DirectReason;
+}
+/** What Agentcard last told the shopper, which decides whether a pick or an answer goes straight. */
+export interface DirectContext {
+    /**
+     * True when the shopper's last turn ended on an answer from Agentcard: its last call returned, and
+     * no turn since ran without one. False or left out, only a request to buy goes straight.
+     */
+    answered?: boolean;
+    /** The step Agentcard's last answer asked for, its `next_action`. */
+    nextAction?: BuyNextAction | null;
+    /** Agentcard's last reply, the question a short answer answers. */
+    asked?: string | null;
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. */
+    products?: ReadonlyArray<{
+        productId: string | null;
+        name: string;
+    }>;
+    /** The stores Agentcard's last answer showed, with the `store_id` a pick sends. */
+    stores?: ReadonlyArray<{
+        storeId: string;
+        name: string;
+    }>;
+}
+/**
+ * True when the message asks to buy or book something, read with no context: a shopping verb with what
+ * to get, a product link, a product at a named store, or a table. A question, small talk, a pick or an
+ * answer, a command to the cart, the shopper's own details and anything about the account read false.
+ */
+export declare function isProductAsk(text: string): boolean;
+/**
+ * The call a shopper's message makes straight to Agentcard, with no model deciding it, or null when
+ * your model decides: see the top of this file for what goes straight. `ask` carries the shopper's
+ * words as they sent them, a confirm goes in only for a plain yes to the total Agentcard asked them to
+ * confirm, and a pick names its `product_id` or `store_id` only when the message names one exactly.
+ *
+ * ```ts
+ * directCall('find me usb-c cables under $20'); // { input: { ask: 'find me usb-c cables under $20', confirm: false, ... }, reason: 'product_ask' }
+ * directCall('what time is it'); // null
+ * directCall('yes', { answered: true, nextAction: 'confirm' }); // { input: { ask: 'yes', confirm: true, ... }, reason: 'confirm' }
+ * ```
+ */
+export declare function directCall(shopperText: string, context?: DirectContext): DirectCall | null;

package/dist/direct.js

@@ -0,0 +1,237 @@
+/**
+ * The buy call a shopper's message makes with no model deciding it: `directCall` reads the message, and
+ * what Agentcard last asked the shopper, and returns the call your app sends straight to Agentcard, or
+ * null when your model decides. Only three kinds of message go straight:
+ *
+ * - a request to buy or book something: a shopping verb with what to get (`find me usb-c cables under
+ *   $20`, `i need a gift for my dad`, `add a toothbrush from walmart to my cart`), a product link, a
+ *   product at a named store (`aa batteries on amazon`), or a table (`a table for 2 tonight at 7`);
+ * - a pick of what Agentcard just showed, by a card's tap (`I'll take the KODAK AA (24 Pack) ($13.49)`,
+ *   `Order from Shake Shack`), its place (`the first one`, `#2`, `1 and 3`) or a reference (`that one`);
+ * - the answer to the question Agentcard just asked: the address, name or code it asked for, a short
+ *   answer such as `medium` or `size 9`, or a plain yes to the total it asked the shopper to confirm.
+ *
+ * Everything else goes to the model: a question, small talk, a change of mind (`no`, `wait`, `cancel`),
+ * a command to the cart, and anything about the account, an order or how the chat works. A pick or an
+ * answer goes straight only while the shopper's last turn ended on Agentcard's answer, so a reply to
+ * something your model said reaches your model.
+ *
+ * The rule is tuned for precision over recall: a message that reaches Agentcard by mistake gets a
+ * purchase reply to small talk, while one the model reads by mistake costs only the model's call. On
+ * the 188 labelled messages in `test/fixtures/direct-messages.json`, it sends none it should not.
+ */
+import { ABOUT, ACKNOWLEDGED, CAPABILITY, CART_COMMAND, CHECKOUT, CHITCHAT, FILLER, asksForDetails, isNewRequest, isPickText, namesStore, plain } from './ack.js';
+/** The longest message that goes straight: a long one is read by the model. */
+const MAX_CHARS = 500;
+/** The steps a shopper answers with their own details or a code. */
+const DETAIL_STEPS = new Set(['shipping_details', 'guest_details', 'verification_code']);
+/** The words of a message: plain, with punctuation, `please` and `thanks` taken out. */
+function wordsOf(text) {
+    return plain(text).replace(/[^\p{L}\p{N}\s$'&+./#-]+/gu, ' ').replace(/[!?.,;:]+(?=\s|$)/g, ' ').replace(/[!?,;:]+/g, ' ').replace(/\b(?:please|pls|plz|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/** Words a message opens with before it says anything: a greeting or filler. */
+const OPENING = /^(?:(?:hey+|hi+|hello+|yo|hiya|howdy|good (?:morning|afternoon|evening)|ok|okay|so|um|uh|also|and|alright|cool|great)(?: there)?\s+)+/;
+/** A change of mind, a refusal or a stall: never an answer to send on. */
+const TAKEBACK = /^(?:i'?ll think|let me think|thinking|i'?m thinking|let me check|i'?ll check|i'?ll let you know|no|nope|nah|not (?:yet|now|really|sure)|cancel|stop|wait|hold on|hang on|never ?mind|nvm|forget (?:it|that|about it)|start over|nothing|none|neither|later|maybe|idk|i don'?t know|dunno|not sure|hmm+|um+|uh+|lol|lmao|haha+|ok|okay|k|kk|thanks?|ty|cool|nice|great|wow|oh|ah)\b/;
+/** Words that say the message is about something other than buying, wherever they sit. */
+const NOT_SHOPPING = new RegExp([
+    'joke', 'weather', 'forecast', 'news', 'poem', 'riddle', 'lyrics', 'translate', 'homework', 'essay', 'coding', 'python', 'javascript',
+    'bug', 'error', 'crash(?:ed|es)?', 'broken', 'not working', "doesn'?t work", 'refund', 'return policy', 'password', 'log ?in', 'sign ?in',
+    'account', 'api', 'support', 'customer service', 'agent ?card', 'what time', 'time is it', "today'?s date", 'human', 'real person',
+    'cancel', 'track(?:ing)?', "where'?s my", 'status', 'receipt', 'invoice', 'unsubscribe', 'privacy', 'kyc', 'identity', 'verify',
+    'promo', 'coupon', 'discount code', 'charged', 'charge me', 'balance', 'wallet', 'approve', 'approval', 'link',
+    '(?:my|a|the|new|your|payment|credit|debit|virtual|bank|visa|mastercard) card', 'card (?:number|details|on file)',
+]
+    .map((word) => `\\b${word}\\b`)
+    .join('|'));
+/** A message that opens as a question: the model reads it, unless it asks Agentcard to get something (`can you find me ...`). */
+const QUESTION_START = /^(?:what|whats|what'?s|where|wheres|where'?s|when|why|how|who|whose|which|is|are|was|were|do|does|did|should|shall|will|would|have|has|tell me|explain|any idea|wanna|you)\b/;
+/** A shopping verb and what follows it, after any opening such as `can you`. */
+const SHOP_FRAME = new RegExp('^(?:(?:can|could|would|will) (?:you|u) (?:please )?|please |i\'?d like (?:you )?to |help me )?' +
+    '(?:find(?: me| us)?|search(?: for)?|look(?:ing)? for|look up|show me|shop for|buy(?: me)?|order(?: me)?|purchase|get me|get us|grab(?: me)?|pick up|book(?: me)?|reserve|add|' +
+    "i want|i need|we need|we want|i'?d like|id like|i would like|i'?m looking for|im looking for|we'?re looking for|i'?m after|im after|" +
+    'need|want|can i get|could i get|can i have|could i have|i\'?ll have|send me|get)\\s+(.+)$');
+/** What a shopping verb takes that names nothing to buy: help, a person, a pronoun, the cart, a question. */
+const NOT_AN_ITEM = /^(?:(?:stuff|things|anything|items|products|everything)(?: (?:on|from|at|in|here|there|online)\b.*)?$|help|some help|assistance|someone|somebody|a human|a person|an agent|to (?!(?:buy|order|get|find|book|reserve|purchase|shop|grab|try)\b)\w+|info|information|advice|more info|you|u|me|it|this|that|these|those|them|nothing|out|lost|more|again|a (?:moment|minute|sec|second|break|nap|hug|vacation|friend)|how|what|where|why|when|who|(?:the |my |our )?(?:cart|basket|order|orders|total|purchases?|history|address)|my)\b/;
+/** A verb that needs an object word after it before it names a thing: `add` alone, or `get` with one word, says too little. */
+const MIN_ITEM_CHARS = 3;
+/** Stores a shopper names by brand, so `aa batteries amazon` reads as a product at a store. */
+const STORES = "amazon|walmart|target|best ?buy|costco|home depot|lowe'?s|ebay|etsy|doordash|door dash|uber ?eats|instacart|cvs|walgreens|nike|adidas|sephora|ulta|macy'?s|nordstrom|ikea|wayfair|chewy|whole foods|trader joe'?s|safeway|kroger|old navy|uniqlo|zara|h&m|rei|staples|office depot|barnes (?:&|and) noble|petco|petsmart|aldi|publix|sam'?s club|shein|temu|newegg|lululemon|patagonia|allbirds|glossier|shake shack|chipotle|starbucks|mcdonald'?s|taco bell|five guys|souvla|opentable|resy|1-800-flowers|zappos|kohl'?s|ace hardware|hollister|abercrombie|gap|apple store|dick'?s sporting goods";
+/** A store's own address, such as `livlyclothing.com`. */
+const DOMAIN = '[a-z0-9][a-z0-9-]*\\.(?:com|co|net|org|shop|store|us|uk|ca|io|co\\.uk)';
+/** A thing at a named store: `aa batteries from amazon`, `bows at livlyclothing.com`, `aa batteries amazon`, `tacos near me`. */
+const AT_STORE = new RegExp(`^(?:a |an |some |\\d+ )?[\\p{L}\\p{N}$'&+./-]+(?: [\\p{L}\\p{N}$'&+./-]+){0,9} (?:(?:(?:from|at|on|off) (?:the )?(?:${STORES}|${DOMAIN}))(?: [\\p{L}\\p{N}$'&+./-]+){0,6}|(?:${STORES})|near me)$`, 'u');
+/** Words a thing never opens with: a pronoun or a verb of the chat. */
+const NOT_A_THING = /^(?:i|i'?m|im|i'?ll|ill|i'?ve|ive|we|we'?re|you|u|your|it|its|it'?s|this|that|these|those|they|he|she|my|our|let|lets|let'?s|thank|thanks|just|still|so|not|no|yes|cool|nice|great|love|like|hate|wish|hope|think|guess|really|very|too)\b/;
+/** A table, or a reservation, for a number of people. */
+const TABLE = /^(?:(?:a |an |book (?:a |me a |us a )?)?(?:\w+ )?)?(?:table|reservation|res|booking) for (?:\d{1,2}|one|two|three|four|five|six|seven|eight|ten|twelve)\b/;
+/** A count or size a product is named by: `81 ct`, `30 rolls`, `160ct`, `6 pack`, `12 oz`. */
+const COUNTED = /\b\d+(?:\.\d+)? ?(?:ct|count|pk|pack|packs|rolls?|pcs|pieces|oz|fl oz|ml|lb|lbs|kg|g|gb|tb|mah|inch|in|ft|qt|quart|gallon|gal|capsules|tablets|caplets|gels|bars|cans|bottles)\b/;
+/** Words that tell of something that already happened, not something to get: `returned 3 bottles`, `the 12 pack never came`. */
+const HAPPENED = /\b(?:returned|bought|ordered|got|received|have|had|has|was|were|is|are|did|never|came|arrived|missing|broke|broken|delivered|shipped|yesterday|last)\b/;
+/** A purchase that already happened, which the shopper tells of rather than asks for: `returned my nike shoes yesterday`. */
+const PAST = /\b(?:returned|bought|ordered|received|arrived|came|never|yesterday|last (?:week|time|month|night)|already|refund(?:ed)?|expired)\b/;
+/** A correction of what came before, such as `actually i need AAA not AA`: the model reads it with what it corrects. */
+const CORRECTION = /^(?:actually|instead|no|nah|nope|wait|oh wait|hmm|oops|sorry|i meant|meant)\b|\bnot\b|\binstead\b/;
+/** Words that point at something only the shopper knows, such as `the usual` or `my home address`, or at a step to repeat. */
+const REFERS = /\b(?:whatever|anything|up to you|you pick|you choose|your call|surprise me|dealer'?s choice|usual|same as|as before|like before|like last time|my (?:home|work|office|regular|normal)\b|code|again)\b/;
+/** A complaint or a joke at a price or a store, which asks for nothing: `another $9.99 delivery fee on doordash`, `duracell is a ripoff`. */
+const COMPLAINT = /\b(?:fees?|ripoff|rip off|scam|overpriced|ugh|smh|annoying|terrible|worst|sucks|hate|love that|tbh|lol|lmao|wtf|seriously|bruh)\b/;
+const LINK = /\bhttps?:\/\/\S+|\bwww\.\S+/i;
+/**
+ * True when the message asks to buy or book something, read with no context: a shopping verb with what
+ * to get, a product link, a product at a named store, or a table. A question, small talk, a pick or an
+ * answer, a command to the cart, the shopper's own details and anything about the account read false.
+ */
+export function isProductAsk(text) {
+    const raw = String(text ?? '');
+    if (raw.length > MAX_CHARS)
+        return false;
+    const words = wordsOf(raw);
+    if (!/[\p{L}]/u.test(words))
+        return false;
+    const bare = words.replace(OPENING, '');
+    if (LINK.test(raw))
+        return !QUESTION_START.test(bare) && !NOT_SHOPPING.test(words.replace(/\S*https?:\/\/\S+|\S*www\.\S+/g, ''));
+    if (!isNewRequest(raw) || CAPABILITY.test(words) || NOT_SHOPPING.test(words) || PAST.test(words) || CORRECTION.test(words) || REFERS.test(words) || COMPLAINT.test(words))
+        return false;
+    // A question goes to the model, unless it asks Agentcard to get something: `can you find me usb-c cables?`.
+    const framed = SHOP_FRAME.exec(bare);
+    if (/\?/.test(raw) && !(framed && /^(?:can|could|would|will) (?:you|u)\b/.test(bare)))
+        return false;
+    if (QUESTION_START.test(bare))
+        return false;
+    if (framed) {
+        const item = framed[1].trim();
+        return item.length >= MIN_ITEM_CHARS && !NOT_AN_ITEM.test(item);
+    }
+    if (TABLE.test(bare))
+        return true;
+    // A product named with its count or size, such as `tide pods 81 ct` or `kirkland toilet paper 30 rolls`, with no verb.
+    if (COUNTED.test(bare) && !NOT_A_THING.test(bare) && !HAPPENED.test(bare) && bare.split(' ').length <= 10)
+        return true;
+    return AT_STORE.test(bare) && !NOT_A_THING.test(bare);
+}
+/** A plain yes: to a total, the go-ahead that confirms it. */
+const YES = /^(?:y|ya|yes+|yeah|yea|yep|yup|sure|confirm(?:ed)?|sounds good|looks good|perfect|yes (?:please|place it|go ahead|do it|confirm|that'?s right|correct))$/;
+function isYes(words) {
+    if (YES.test(words) || CHECKOUT.test(words))
+        return true;
+    // A yes, then the go-ahead in other words: `yep go ahead`, `ok do it`, `yes, place the order`, `sure, sounds good`.
+    const rest = words.replace(FILLER, '');
+    return rest !== words && (rest === '' || YES.test(rest) || CHECKOUT.test(rest));
+}
+/** Words that open a new request or a question rather than a short answer. */
+const REQUEST_START = /^(?:find|search|look|show|get|order|buy|book|can|could|would|will|what|which|how|is|are|do|does|did|i want|i need|please)\b/;
+/** Words that open an objection to giving details: the model answers it. */
+const OBJECTION = /\b(?:expired|wrong|invalid|another|new code|resend|lol|don'?t|do not|won'?t|didn'?t|did not|haven'?t|not|never|no|rather not|why|what|where|how|privacy|safe|secure|instead|different|change)\b/;
+/** Words that weigh a product rather than pick it: `duracell is too expensive`, `energizer instead of these`. */
+const DOUBT = /\b(?:far|close|closest|open|hours|distance|minutes|rating|reviews|not|no|too|expensive|cheaper|pricey|better|worse|than|instead|vs|versus|or|compare|difference|why|isn'?t|aren'?t|don'?t|doesn'?t|hate|meh)\b/;
+const ORDINALS = { first: 1, second: 2, third: 3, fourth: 4, fifth: 5, sixth: 6, seventh: 7, eighth: 8 };
+/** The places in a list a message names, such as `1 and 3` or `the second one`, in order: empty when it names none. */
+function placesOf(bare, count) {
+    const said = bare.replace(/^(?:i'?ll take|i'?ll do|i'?ll go with|go with|let'?s do|lets do|i want|give me|get me|add|the|both|option|options|number|numbers|item|#)\s*/g, ' ');
+    const tokens = said.match(/#?\d{1,2}(?:st|nd|rd|th)?|first|second|third|fourth|fifth|sixth|seventh|eighth|last/g) ?? [];
+    // The places stand alone, joined by `and` or a comma, with only `the`, `one`, `ones`, `option` or `#` around them.
+    const rest = said.replace(/#?\d{1,2}(?:st|nd|rd|th)?|first|second|third|fourth|fifth|sixth|seventh|eighth|last|\band\b|&|\+|,|\bthe\b|\bones?\b|\boptions?\b|\bnumbers?\b|\bitems?\b|#|\bplease\b/g, ' ').trim();
+    if (tokens.length === 0 || rest !== '')
+        return null;
+    const places = tokens.map((token) => (token === 'last' ? count : ORDINALS[token] ?? Number(token.replace(/\D/g, ''))));
+    return places.every((place) => place >= 1 && place <= count) ? places : null;
+}
+/** Text as lowercase words with single spaces, as the tool compares a product's name with a tap. */
+function nameWords(text) {
+    return String(text ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+}
+/** The pick a message makes of what Agentcard just showed, null when it picks nothing, or false when it counts past the list. */
+function pickOf(raw, bare, context) {
+    const products = context.products ?? [];
+    const stores = context.stores ?? [];
+    const call = (fields) => ({ input: { ask: raw, confirm: false, new_order: false, product_id: null, store_id: null, ...fields }, reason: 'pick' });
+    if (stores.length > 0) {
+        const said = ` ${nameWords(raw)} `;
+        // A store's card names it whole; a store named with the dishes to order from it (`five guys, bacon cheeseburger`) picks it too.
+        const named = stores.filter((store) => namesStore(raw, [store.name]) || (nameWords(store.name).length >= 5 && said.includes(` ${nameWords(store.name)} `)));
+        if (named.length === 1 && !QUESTION_START.test(bare) && !DOUBT.test(said))
+            return call({ store_id: named[0].storeId });
+        if (named.length > 0 && (QUESTION_START.test(bare) || DOUBT.test(said)))
+            return false;
+        if (named.length > 1)
+            return call({});
+    }
+    if (products.length > 0) {
+        // A card's tap names the product whole: `I'll take the KODAK AA Alkaline Batteries (24 Pack) ($13.49)`.
+        const said = nameWords(raw);
+        const named = products.filter((product) => nameWords(product.name).length >= 12 && said.includes(nameWords(product.name)));
+        if (named.length === 1)
+            return call({ product_id: named[0].productId });
+        if (named.length > 1)
+            return call({});
+        // A word only one product's name holds, such as its brand: `lets do the coppertop ones`, `duracell 24 count is fine`.
+        const words = new Set(said.split(' '));
+        const owners = (word) => products.filter((product) => nameWords(product.name).split(' ').includes(word));
+        const marked = products.filter((product) => nameWords(product.name).split(' ').some((word) => word.length >= 4 && !/^\d/.test(word) && words.has(word) && owners(word).length === 1));
+        if (marked.length === 1 && said.split(' ').length <= 10 && !QUESTION_START.test(bare) && !DOUBT.test(said))
+            return call({ product_id: marked[0].productId });
+        const places = placesOf(bare, products.length);
+        if (places)
+            return call(places.length === 1 ? { product_id: products[places[0] - 1].productId } : {});
+        // A place past the end of the list picks nothing the shopper saw.
+        if (placesOf(bare, Number.MAX_SAFE_INTEGER))
+            return false;
+        if (/^(?:both|all|all of them|both of them|all three|all 3)$/.test(bare))
+            return call({});
+    }
+    if ((products.length > 0 || stores.length > 0) && isPickText(raw))
+        return call({});
+    return null;
+}
+/**
+ * The call a shopper's message makes straight to Agentcard, with no model deciding it, or null when
+ * your model decides: see the top of this file for what goes straight. `ask` carries the shopper's
+ * words as they sent them, a confirm goes in only for a plain yes to the total Agentcard asked them to
+ * confirm, and a pick names its `product_id` or `store_id` only when the message names one exactly.
+ *
+ * ```ts
+ * directCall('find me usb-c cables under $20'); // { input: { ask: 'find me usb-c cables under $20', confirm: false, ... }, reason: 'product_ask' }
+ * directCall('what time is it'); // null
+ * directCall('yes', { answered: true, nextAction: 'confirm' }); // { input: { ask: 'yes', confirm: true, ... }, reason: 'confirm' }
+ * ```
+ */
+export function directCall(shopperText, context = {}) {
+    const raw = String(shopperText ?? '').trim();
+    if (raw === '' || raw.length > MAX_CHARS)
+        return null;
+    const ctx = context ?? {};
+    const words = wordsOf(raw);
+    if (!/[\p{L}\p{N}]/u.test(words))
+        return null;
+    const bare = words.replace(OPENING, '') || words;
+    const plainCall = (reason, confirm = false) => ({ input: { ask: raw, confirm, new_order: false, product_id: null, store_id: null }, reason });
+    if (ctx.answered === true && !/\?/.test(raw)) {
+        const told = CHITCHAT.test(words) || ABOUT.test(words) || CART_COMMAND.test(words) || CAPABILITY.test(words);
+        if (ctx.nextAction === 'confirm' && isYes(words))
+            return plainCall('confirm', true);
+        // A question, a story of what happened, an objection or a change of mind is the model's to answer, whatever came before.
+        const aside = QUESTION_START.test(bare) || REFERS.test(words) || COMPLAINT.test(words) || PAST.test(words) || NOT_SHOPPING.test(words) || OBJECTION.test(words) || CORRECTION.test(words);
+        if (!told && !aside && !TAKEBACK.test(words)) {
+            const pick = pickOf(raw, bare, ctx);
+            if (pick === false)
+                return null;
+            if (pick)
+                return pick;
+            // The address, name or code Agentcard asked for: what the shopper sends is the answer, unless it objects.
+            const details = (typeof ctx.nextAction === 'string' && DETAIL_STEPS.has(ctx.nextAction)) || asksForDetails(ctx.asked);
+            if (details && !OBJECTION.test(words) && !REQUEST_START.test(bare) && !QUESTION_START.test(bare) && !PAST.test(words) && !/\b(?:same as|on file|you have|the usual|ur|your)\b/.test(words) && !/^(?:resend|send|again|still)\b/.test(bare) && !NOT_SHOPPING.test(words) && words.split(' ').length <= 40)
+                return plainCall('answer');
+            // A short answer to Agentcard's question, such as `medium` after `what size?`, or a yes to `want me to check amazon?`.
+            if (/\?/.test(String(ctx.asked ?? '')) && ctx.nextAction !== 'confirm' && !NOT_SHOPPING.test(words)) {
+                if (isYes(words))
+                    return plainCall('answer');
+                if (!ACKNOWLEDGED.test(words) && words.split(' ').length <= 4 && !REQUEST_START.test(bare))
+                    return plainCall('answer');
+            }
+        }
+    }
+    return isProductAsk(raw) ? plainCall('product_ask') : null;
+}

package/dist/events.d.ts

@@ -3,7 +3,7 @@
  * name. The stream (`agentcard.listen`) and a webhook endpoint carry the same types, with the same
  * envelope and the same ids. A test holds this list to the backend's catalog.
  */
-export declare const AGENTCARD_EVENT_TYPES: readonly ["card.created", "card.updated", "card.closed", "cardholder.created", "cardholder.updated", "transaction.authorized", "transaction.declined", "transaction.cleared", "transaction.voided", "balance.low", "cardholder_onboarding_session.completed", "platform_connect_session.completed", "merchant.connected", "order.placed", "order.confirmed", "order.failed", "order.updated", "purchase.message", "connection.created", "connected_card.updated", "vault.card_stored", "vault.session_linked", "vault.session_card_picked", "vault.payment_permission.updated", "action.confirmed", "action.done", "checkout_authorization.approved", "checkout_authorization.submitted", "checkout_authorization.declined", "checkout_authorization.cancelled", "checkout_authorization.expired", "checkout_authorization.duplicate_charge", "checkout_authorization.refused", "checkout_authorization.watched", "checkout_authorization.amount_mismatch", "checkout_authorization.settled", "checkout_authorization.settlement_unconfirmed", "checkout_authorization.outcome_reported", "card_flow.started", "card_flow.failed", "transfer.approved", "transfer.initiated", "transfer.completed", "transfer.failed", "transfer.released", "wallet.funded", "user_wallet.funding_detected", "user_wallet.funded", "wallet.balance.low", "recovery.requested", "recovery.completed", "recovery.rejected", "wallet.withdrawal.initiated", "wallet.withdrawal.completed", "wallet.withdrawal.failed", "identity.verification.updated", "approval.requested", "reward.earned", "reward.reversed", "wallet_link.opened"];
+export declare const AGENTCARD_EVENT_TYPES: readonly ['card.created', 'card.updated', 'card.closed', 'cardholder.created', 'cardholder.updated', 'transaction.authorized', 'transaction.declined', 'transaction.cleared', 'transaction.voided', 'balance.low', 'cardholder_onboarding_session.completed', 'platform_connect_session.completed', 'merchant.connected', 'order.placed', 'order.confirmed', 'order.failed', 'order.updated', 'purchase.message', 'connection.created', 'connected_card.updated', 'vault.card_stored', 'vault.session_linked', 'vault.session_card_picked', 'vault.payment_permission.updated', 'action.confirmed', 'action.done', 'checkout_authorization.approved', 'checkout_authorization.submitted', 'checkout_authorization.declined', 'checkout_authorization.cancelled', 'checkout_authorization.expired', 'checkout_authorization.duplicate_charge', 'checkout_authorization.refused', 'checkout_authorization.watched', 'checkout_authorization.amount_mismatch', 'checkout_authorization.settled', 'checkout_authorization.settlement_unconfirmed', 'checkout_authorization.outcome_reported', 'card_flow.started', 'card_flow.failed', 'transfer.approved', 'transfer.initiated', 'transfer.completed', 'transfer.failed', 'transfer.released', 'wallet.funded', 'user_wallet.funding_detected', 'user_wallet.funded', 'wallet.balance.low', 'recovery.requested', 'recovery.completed', 'recovery.rejected', 'wallet.withdrawal.initiated', 'wallet.withdrawal.completed', 'wallet.withdrawal.failed', 'identity.verification.updated', 'approval.requested', 'reward.earned', 'reward.reversed', 'wallet_link.opened'];
 /** One event type Agentcard sends. A type Agentcard adds later still reads as its own name. */
 export type AgentcardEventType = (typeof AGENTCARD_EVENT_TYPES)[number];
 /** Whether a filter entry names something Agentcard sends: an event type, a family such as `order.*`, or `*`. */

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, type AgentcardSignatureReason, type AgentcardEvent, type VerifyOptions, } from './verify.js';
 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 { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, 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 BuyCartFeeLine, 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 { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, 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, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
-export { buyTool, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolProduct, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
-export { instantAck, instantReaction, ackFor, ACK_REACTION, type AckForOptions } from './ack.js';
-export { forModel, forModelError, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, } from './model-view.js';
+export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';
+export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION, type AckForOptions } from './ack.js';
+export { directCall, isProductAsk, type DirectCall, type DirectContext, type DirectReason } from './direct.js';
+export { forModel, forModelError, replyAsWritten, withoutCardList, 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 { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';

package/dist/index.js

@@ -1,13 +1,15 @@
 export { verifyAgentcardWebhook, AgentcardSignatureError, } from './verify.js';
 export { readPurchaseMessage, } from './message.js';
-export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, } from './shopper-message.js';
+export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, } from './shopper-message.js';
 export { agentcardWebhook, purchaseAgentWebhook, } from './handler.js';
 export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, } from './definition.js';
 export { toMessages, messageStream, typingDelay, } from './messages.js';
-export { buyTool, } from './buy-tool.js';
-export { instantAck, instantReaction, ackFor, ACK_REACTION } from './ack.js';
-export { forModel, forModelError, stripLinks, } from './model-view.js';
+export { buyTool, nextStepPrompt, productAction, } from './buy-tool.js';
+export { instantAck, instantReaction, ackFor, keepsYes, ACK_REACTION } from './ack.js';
+export { directCall, isProductAsk } from './direct.js';
+export { forModel, forModelError, replyAsWritten, withoutCardList, stripLinks, } from './model-view.js';
 export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.js';
+export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, } from './events.js';

package/dist/message.d.ts

@@ -21,8 +21,11 @@ import { type AgentcardEvent } from './verify.js';
  * - `store_connected`: the shopper signed in to their own account at the store from the sign-in link your app sent, so the order can go through on it.
  * - `store_connect_failed`: the shopper's sign-in to the store did not go through, and the link no longer works.
  * - `store_connect_expired`: the sign-in link expired before the shopper finished signing in.
+ * - `cart_ready`: the store's checkout built the cart an answer named as still being built (`cart_building`), at the store's own total. Nothing is paid until the shopper says yes to it.
+ * - `cart_needs_input`: that checkout asks the shopper something first, such as a size, a delivery address, a sign-in to the store or an approval of the most the order can cost.
+ * - `cart_failed`: that checkout built no cart, and nothing was ordered or charged.
  */
-export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'approval_declined' | 'payment_declined' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added' | 'store_connected' | 'store_connect_failed' | 'store_connect_expired';
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'approval_expiring' | 'approval_expired' | 'approval_declined' | 'payment_declined' | 'card_link_unfinished' | 'card_link_expired' | 'cart_idle' | 'card_added' | 'store_connected' | 'store_connect_failed' | 'store_connect_expired' | 'cart_ready' | 'cart_needs_input' | 'cart_failed';
 /** The message's values one by one, for a company that writes its own copy. A fact that does not apply is absent. */
 export interface PurchaseFacts {
     merchantName?: string;

package/dist/messages.d.ts

@@ -16,17 +16,17 @@
 export declare function toMessages(text: string): string[];
 /**
  * How long someone texting takes to type `message`, in milliseconds: 300, plus 12 a character, at most
- * 1,500. `messageStream` and `buy.turn` wait this long between two messages by default, so a model that
- * writes three paragraphs in 100 ms still delivers them one at a time.
+ * 1,500. With `pace: true`, `messageStream` and `buy.turn` wait this long between two messages, so a
+ * model that writes three paragraphs in 100 ms still delivers them one at a time.
  *
  * ```ts
  * typingDelay('which one do you want?'); // 564
  * ```
  */
 export declare function typingDelay(message: string): number;
-/** How messages are spaced: `true` by `typingDelay`, `false` not at all, or a function that returns the pause for a message. */
+/** How messages are spaced: `false` (the default) not at all, `true` by `typingDelay`, or a function that returns the pause for a message. */
 export type MessagePace = boolean | ((message: string) => number);
-/** The pause for each message `pace` asks for, or null for none. Throws a TypeError for a pace that cannot work. */
+/** The pause for each message `pace` asks for, or null for none, the default. Throws a TypeError for a pace that cannot work. */
 export declare function paceOf(pace: unknown): ((message: string) => number) | null;
 /** A typing hook that never throws: one that fails costs nothing but the indicator. */
 export declare function typingHook(onTyping: unknown): (typing: boolean) => void;
@@ -49,11 +49,11 @@ export interface MessageStreamOptions {
      */
     onMessage: (message: string) => void | Promise<void>;
     /**
-     * Spaces the messages like someone texting. Each message after the first waits until `typingDelay`
-     * of it has passed since the one before it went out, so a model that writes three paragraphs in
-     * 100 ms still delivers them one at a time. Time the model spent writing counts toward the pause, so
-     * a slow model gets no added wait. Default `true`. `false` hands each message over the moment it is
-     * written, and a function returns the pause in milliseconds for a message.
+     * How the messages are spaced. Default `false`: each message goes out the moment it is written.
+     * `true` spaces them like someone texting: each message after the first waits until `typingDelay` of
+     * it has passed since the one before it went out, so a model that writes three paragraphs in 100 ms
+     * still delivers them one at a time, and time the model spent writing counts toward the pause. A
+     * function returns the pause in milliseconds for a message.
      */
     pace?: MessagePace;
     /**

package/dist/messages.js

@@ -122,8 +122,8 @@ const TYPING_MS_PER_CHARACTER = 12;
 const TYPING_MAX_MS = 1_500;
 /**
  * How long someone texting takes to type `message`, in milliseconds: 300, plus 12 a character, at most
- * 1,500. `messageStream` and `buy.turn` wait this long between two messages by default, so a model that
- * writes three paragraphs in 100 ms still delivers them one at a time.
+ * 1,500. With `pace: true`, `messageStream` and `buy.turn` wait this long between two messages, so a
+ * model that writes three paragraphs in 100 ms still delivers them one at a time.
  *
  * ```ts
  * typingDelay('which one do you want?'); // 564
@@ -132,12 +132,12 @@ const TYPING_MAX_MS = 1_500;
 export function typingDelay(message) {
     return Math.min(TYPING_MAX_MS, TYPING_BASE_MS + TYPING_MS_PER_CHARACTER * [...String(message ?? '')].length);
 }
-/** The pause for each message `pace` asks for, or null for none. Throws a TypeError for a pace that cannot work. */
+/** The pause for each message `pace` asks for, or null for none, the default. Throws a TypeError for a pace that cannot work. */
 export function paceOf(pace) {
-    if (pace === undefined || pace === true)
-        return typingDelay;
-    if (pace === false)
+    if (pace === undefined || pace === false)
         return null;
+    if (pace === true)
+        return typingDelay;
     if (typeof pace !== 'function')
         throw new TypeError('Pass pace as true, false, or a function that returns the pause before a message in milliseconds.');
     return (message) => {