@agent-cards/commerce-sdk 0.16.0 → 0.18.0

package/dist/client.d.ts

@@ -127,6 +127,12 @@ export interface BuyStreamHandlers {
     onCatalog?: (update: BuyCatalogUpdate) => void | Promise<void>;
     /** Each message Agentcard writes, the moment it is written. */
     onSegment?: (update: BuySegmentUpdate) => void | Promise<void>;
+    /**
+     * The line that says what Agentcard is looking for, such as `one sec, checking target for la croix`, written while the
+     * search runs on an ask for something new. It comes before the turn's cards and messages, or not at all, and the
+     * answer's `messages` never hold it.
+     */
+    onAck?: (update: BuySegmentUpdate) => void | Promise<void>;
     /** The carts, each time the turn builds or changes one. */
     onCart?: (update: BuyCartUpdate) => void | Promise<void>;
     /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
@@ -234,6 +240,31 @@ export interface BuyRequest {
     delivery_address?: BuyDeliveryAddress;
     external_user_id?: string;
     user_id?: string;
+    /** `false` asks for no line that says what Agentcard is looking for (`onAck`): the shopper already read one. */
+    ack?: false;
+    /**
+     * `true` asks Agentcard to answer at once, with `handed_back` and no turn run, when the ask is not shopping: a request to
+     * buy, a pick of what it showed, an answer to its question or a yes to a total runs as any ask, and every other message
+     * is your model's. `buy.turn`'s `handled()` sends it. An older API ignores it and runs the ask.
+     */
+    hand_back?: true;
+    /** With `hand_back`: what Agentcard's last answer showed and asked, which decides whether a pick or an answer is shopping. */
+    last_answer?: BuyLastAnswer;
+}
+/** What the shopper's last answer from Agentcard showed and asked, sent with `hand_back`. */
+export interface BuyLastAnswer {
+    /** True when the shopper's last turn ended on Agentcard's answer, with no turn your model answered alone since. */
+    answered: boolean;
+    next_action: string | null;
+    asked: string | null;
+    products: Array<{
+        product_id: string | null;
+        name: string;
+    }>;
+    stores: Array<{
+        store_id: string;
+        name: string;
+    }>;
 }
 export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
 export interface BuyStore {
@@ -427,6 +458,8 @@ export interface BuyTurn {
     conversation_id: string;
     /** A status Agentcard adds later reads as `needs_input`. */
     status: BuyStatus;
+    /** True when Agentcard answered a `hand_back` ask as your model's to answer: no turn ran, and the other fields are empty. */
+    handed_back?: true;
     reply: string;
     messages: string[];
     cart: BuyCart | null;

package/dist/client.js

@@ -11,7 +11,7 @@
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta', 'onAvailability'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -272,6 +272,7 @@ export function turnOf(body) {
     return {
         conversation_id: str(body.conversation_id) ?? '',
         status: typeof body.status === 'string' && STATUSES.has(body.status) ? body.status : 'needs_input',
+        ...(body.handed_back === true ? { handed_back: true } : {}),
         reply: typeof body.reply === 'string' ? body.reply : '',
         messages: Array.isArray(body.messages) ? body.messages.filter((m) => typeof m === 'string') : [],
         cart: cartOf(body.cart),
@@ -535,6 +536,9 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             else if (event === 'segment' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onSegment) {
                 deliver(() => stream.onSegment({ conversationId: named, text: data.text }));
             }
+            else if (event === 'ack' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onAck) {
+                deliver(() => stream.onAck({ conversationId: named, text: data.text }));
+            }
             else if (event === 'venue_availability' && stream.onAvailability && str(data.conversation_id) && Array.isArray(data.items)) {
                 const items = data.items.filter(isRecord).flatMap((i) => {
                     const id = str(i.id);

package/dist/definition.js

@@ -13,6 +13,7 @@ export const BUY_TOOL_DESCRIPTION = [
     '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 the shopper asks you to find, buy, book or order something new, such as a product, a gift idea, a meal, a table, a flight or a store page they pasted a link to, first write one short line that says what you are about to look for, then call this tool in the same reply: only what they asked for, and the store or place they named, in their own words, such as "on it, looking for la croix at target", "one sec, checking nopa for a table for 2 at 7pm" or, for a pasted link, "one sec, checking that link", never a price, a total, stock, a result, a question or that anything was found, added or ordered. A store named by its site, such as "the polishing cloth from myrqvist.com", is a store, not a link. For a yes, a pick, a size, an address, a code, a change to a cart or a question about an order, write no line first, and after this tool answers, never say again that you are looking.',
     '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.',

package/dist/direct.d.ts

@@ -21,11 +21,21 @@ export interface DirectContext {
     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. */
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. A place (`the second one`) reads these. */
     products?: ReadonlyArray<{
         productId: string | null;
         name: string;
     }>;
+    /**
+     * Every product card the shopper can tap by its name, each once: the answer's and the ones its searches sent as they answered,
+     * which an answer about one item can leave out (a menu turn that answered with the Burrito beside eight menu cards). A pick by
+     * name (a card's tap, a product's whole name, a word only one name holds) reads these; a place never does, so `the last one` is
+     * the last of `products`. Left out, `products` stands for both.
+     */
+    tappable?: ReadonlyArray<{
+        productId: string | null;
+        name: string;
+    }>;
     /** The stores Agentcard's last answer showed, with the `store_id` a pick sends. */
     stores?: ReadonlyArray<{
         storeId: string;

package/dist/direct.js

@@ -9,7 +9,10 @@
  * - 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.
+ *   answer such as `medium` or `size 9`, or a plain yes to the total it asked the shopper to confirm;
+ * - a price limit for the products Agentcard just showed: `only options under $20`, `under 20`, `cheaper ones`.
+ *   Agentcard holds its cards to the limit and shows the ones inside it again as cards; your model, answering
+ *   from the list it saw, named two products with no card to tap (2026-10-27).
  *
  * 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
@@ -21,6 +24,11 @@
  * 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';
+/**
+ * A price limit put on what was just shown: `under $20`, `under 20`, `less than 15 bucks`, `between 10 and 20`, `$20 or
+ * less`, `over $50`, `cheaper ones`, `menos de 20`. Only whether the message states one: Agentcard reads the limit itself.
+ */
+const PRICE_REFINE = /(?:\b(?:under|below|less than|cheaper than|up to|at most|no more than|max(?:imum)?|between|over|above|more than|at least|menos de|hasta|entre)\s+\$?\s?\d)|\$\s?\d+(?:\.\d{1,2})?\s*(?:or (?:less|under|below|more)|and (?:under|below|up)|max|tops|\+)|\b\d+\s*(?:dollars|bucks)\b|\b(?:cheaper|less expensive|more affordable|lower[- ]priced)\b(?!\s+than\b)|\bm[aá]s barat/;
 /** 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. */
@@ -143,9 +151,17 @@ function placesOf(bare, count) {
 function nameWords(text) {
     return String(text ?? '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
 }
+/** A card's tap as an app writes it, `I'll take the <name> (<price>)`: the name in it, or null for any other message. */
+const TAP = /^(?:i'?ll (?:take|have|get)|i want|add)\s+(?:the\s+)?(.+?)\s*\(\s*(?:[$€£]\s?\d[\d,]*(?:\.\d{1,2})?|from [$€£]\s?\d[\d,]*(?:\.\d{1,2})?)\s*\)\s*[.!]?$/i;
+function tappedName(raw) {
+    const name = TAP.exec(raw.trim())?.[1]?.trim();
+    return name ? name : null;
+}
 /** 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 ?? [];
+    // A pick by name reads every card the shopper can tap; a place reads `products`, in the order the answer showed them.
+    const byName = context.tappable?.length ? context.tappable : 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) {
@@ -159,18 +175,26 @@ function pickOf(raw, bare, context) {
         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)`.
+    if (byName.length > 0) {
+        // A card's tap names the product whole, `I'll take the Burrito Bowl ($15.15)`: the product of exactly that name is the pick,
+        // never the Burrito whose one word it shares, and a tap that names no product here (a card this list does not hold), or two
+        // alike, sends none, so Agentcard reads the words against every card it showed.
+        const tap = tappedName(raw);
+        if (tap !== null) {
+            const exact = byName.filter((product) => [nameWords(tap), nameWords(`the ${tap}`)].includes(nameWords(product.name)));
+            return call(exact.length === 1 ? { product_id: exact[0].productId } : {});
+        }
+        // A product's whole name inside the message: `I want the KODAK AA Alkaline Batteries (24 Pack)`.
         const said = nameWords(raw);
-        const named = products.filter((product) => nameWords(product.name).length >= 12 && said.includes(nameWords(product.name)));
+        const named = byName.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));
+        const owners = (word) => byName.filter((product) => nameWords(product.name).split(' ').includes(word));
+        const marked = byName.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);
@@ -182,7 +206,7 @@ function pickOf(raw, bare, context) {
         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))
+    if ((byName.length > 0 || stores.length > 0) && isPickText(raw))
         return call({});
     return null;
 }
@@ -220,6 +244,9 @@ export function directCall(shopperText, context = {}) {
                 return null;
             if (pick)
                 return pick;
+            // A price limit on the products just shown: Agentcard shows the ones inside it again, as cards.
+            if ((ctx.products ?? []).length > 0 && PRICE_REFINE.test(words) && words.split(' ').length <= 15)
+                return plainCall('product_ask');
             // 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)

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, ty
 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 { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.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 AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, 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, type BuyChoice, type BuyChoiceGroup, type BuyChoiceOption, } 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 BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, 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, type BuyChoice, type BuyChoiceGroup, type BuyChoiceOption, } 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, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';

package/dist/messages.d.ts

@@ -1,19 +1,39 @@
 /**
- * Text cut into the messages a shopper reads one at a time. A chat app sends each paragraph as its
- * own message, so a reply written as three paragraphs arrives as three texts. A blank line ends a
- * paragraph, with two exceptions that keep a block whole: a fenced code block, and a list whose
- * items a blank line separates.
+ * Joins each message that leads in with a colon (`two options came in under $20:`) to the message after it, so a shopper
+ * never reads a bubble that ends on a colon: the lead-in and its first item or list arrive as one message, a line apart.
+ * `add` returns the message to send, or null while it holds a lead-in for the next one. `end` returns what a held lead-in
+ * leaves once nothing followed it, such as when every item it led into went because the cards show them: the text less
+ * its colon sentence (withoutLeadIn), or null when nothing is left. On 2026-10-27 a chat showed "two options came in
+ * under $20:" as a bubble of its own, above the item it led into.
  */
+export declare function leadInJoiner(): {
+    add(message: string): string | null;
+    end(): string | null;
+};
 /**
  * The text as separate messages, in order: one per paragraph, each trimmed, with empty ones left
  * out. One or more blank lines end a paragraph. A fenced code block stays one message whatever blank
- * lines it holds, and so does a list whose items blank lines separate.
+ * lines it holds, and so does a list whose items blank lines separate. A paragraph that ends with a
+ * colon goes with the paragraph after it, one line apart, and loses its colon sentence when nothing
+ * follows it, so no message ends on a colon.
  *
  * ```ts
  * toMessages('Found two.\n\nWant the first one?'); // ['Found two.', 'Want the first one?']
+ * toMessages('two came in under $20:\n\n• Everydaze, $8.99'); // ['two came in under $20:\n• Everydaze, $8.99']
  * ```
  */
 export declare function toMessages(text: string): string[];
+/**
+ * The text's paragraphs as `toMessages` cuts them, before any lead-in joins the paragraph after it: the units Agentcard
+ * and a model write, and what a count of the messages a shopper read is checked against, paragraph for paragraph.
+ */
+export declare function paragraphsOf(text: string): string[];
+/**
+ * Messages in order, each one that leads in with a colon joined to the ones after it by one joiner across them all
+ * (leadInJoiner), so a lead-in that is a whole message of its own, as one of Agentcard's `messages` can be, still goes
+ * with the message after it, and a lead-in nothing follows at the very end loses its colon sentences.
+ */
+export declare function joinLeadIns(messages: readonly string[]): string[];
 /**
  * How long someone texting takes to type `message`, in milliseconds: 300, plus 12 a character, at most
  * 1,500. With `pace: true`, `messageStream` and `buy.turn` wait this long between two messages, so a
@@ -67,7 +87,8 @@ export interface MessageStreamOptions {
  * moment the blank line that ends it arrives, whatever the pieces split it into, and goes to
  * `onMessage` then, or, after the first, once its typing pause since the last one passed (`pace`). A
  * paragraph inside a list waits for the first characters of the line after the blank, which say
- * whether the list goes on. `end` hands over the last message and waits for every send.
+ * whether the list goes on, and a paragraph that ends with a colon waits for the paragraph after it,
+ * so the two go out as one message. `end` hands over the last message and waits for every send.
  *
  * ```ts
  * const paragraphs = messageStream({ onMessage: (text) => sendToShopper(text) });

package/dist/messages.js

@@ -2,8 +2,10 @@
  * Text cut into the messages a shopper reads one at a time. A chat app sends each paragraph as its
  * own message, so a reply written as three paragraphs arrives as three texts. A blank line ends a
  * paragraph, with two exceptions that keep a block whole: a fenced code block, and a list whose
- * items a blank line separates.
+ * items a blank line separates. A paragraph that leads in with a colon never stands alone: it goes out
+ * with the one after it (leadInJoiner).
  */
+import { leadsIn, withoutLeadIn } from './sentences.js';
 /** A line holding nothing but spaces or tabs. */
 const BLANK = /^[ \t]*$/;
 /** A list item: `-`, `*`, `+` or the bullet `•`, or a number followed by `.` or `)`, then a space or the line's end. */
@@ -30,6 +32,29 @@ function closesFence(line, open) {
     const match = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
     return !!match && match[1][0] === open[0] && match[1].length >= open.length;
 }
+/**
+ * Joins each message that leads in with a colon (`two options came in under $20:`) to the message after it, so a shopper
+ * never reads a bubble that ends on a colon: the lead-in and its first item or list arrive as one message, a line apart.
+ * `add` returns the message to send, or null while it holds a lead-in for the next one. `end` returns what a held lead-in
+ * leaves once nothing followed it, such as when every item it led into went because the cards show them: the text less
+ * its colon sentence (withoutLeadIn), or null when nothing is left. On 2026-10-27 a chat showed "two options came in
+ * under $20:" as a bubble of its own, above the item it led into.
+ */
+export function leadInJoiner() {
+    let held = null;
+    return {
+        add(message) {
+            const whole = held === null ? message : `${held}\n${message}`;
+            held = leadsIn(whole) ? whole : null;
+            return held === null ? whole : null;
+        },
+        end() {
+            const rest = held === null ? '' : withoutLeadIn(held);
+            held = null;
+            return rest || null;
+        },
+    };
+}
 /**
  * Reads text line by line and closes each message once nothing later can change it. It keeps only
  * the message being built, so text fed in pieces costs what the text costs once.
@@ -102,19 +127,47 @@ class Scanner {
 /**
  * The text as separate messages, in order: one per paragraph, each trimmed, with empty ones left
  * out. One or more blank lines end a paragraph. A fenced code block stays one message whatever blank
- * lines it holds, and so does a list whose items blank lines separate.
+ * lines it holds, and so does a list whose items blank lines separate. A paragraph that ends with a
+ * colon goes with the paragraph after it, one line apart, and loses its colon sentence when nothing
+ * follows it, so no message ends on a colon.
  *
  * ```ts
  * toMessages('Found two.\n\nWant the first one?'); // ['Found two.', 'Want the first one?']
+ * toMessages('two came in under $20:\n\n• Everydaze, $8.99'); // ['two came in under $20:\n• Everydaze, $8.99']
  * ```
  */
 export function toMessages(text) {
-    const messages = [];
-    const scanner = new Scanner((message) => messages.push(message));
+    return joinLeadIns(paragraphsOf(text));
+}
+/**
+ * The text's paragraphs as `toMessages` cuts them, before any lead-in joins the paragraph after it: the units Agentcard
+ * and a model write, and what a count of the messages a shopper read is checked against, paragraph for paragraph.
+ */
+export function paragraphsOf(text) {
+    const paragraphs = [];
+    const scanner = new Scanner((paragraph) => paragraphs.push(paragraph));
     for (const line of String(text ?? '').replace(/\r\n?/g, '\n').split('\n'))
         scanner.line(line);
     scanner.end();
-    return messages;
+    return paragraphs;
+}
+/**
+ * Messages in order, each one that leads in with a colon joined to the ones after it by one joiner across them all
+ * (leadInJoiner), so a lead-in that is a whole message of its own, as one of Agentcard's `messages` can be, still goes
+ * with the message after it, and a lead-in nothing follows at the very end loses its colon sentences.
+ */
+export function joinLeadIns(messages) {
+    const leads = leadInJoiner();
+    const out = [];
+    for (const message of messages) {
+        const ready = leads.add(message);
+        if (ready)
+            out.push(ready);
+    }
+    const rest = leads.end();
+    if (rest)
+        out.push(rest);
+    return out;
 }
 /** The pause before a message, as someone texting takes it: 300 ms, plus 12 ms a character, at most 1.5 seconds. */
 const TYPING_BASE_MS = 300;
@@ -171,7 +224,8 @@ export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * moment the blank line that ends it arrives, whatever the pieces split it into, and goes to
  * `onMessage` then, or, after the first, once its typing pause since the last one passed (`pace`). A
  * paragraph inside a list waits for the first characters of the line after the blank, which say
- * whether the list goes on. `end` hands over the last message and waits for every send.
+ * whether the list goes on, and a paragraph that ends with a colon waits for the paragraph after it,
+ * so the two go out as one message. `end` hands over the last message and waits for every send.
  *
  * ```ts
  * const paragraphs = messageStream({ onMessage: (text) => sendToShopper(text) });
@@ -247,10 +301,15 @@ export function messageStream(options) {
             });
         }
     };
-    const scanner = new Scanner((message) => {
+    // A paragraph that leads in with a colon waits for the one after it, so the two go out as one message.
+    const leads = leadInJoiner();
+    const send = (message) => {
+        if (!message)
+            return;
         queue.push(message);
         kick();
-    });
+    };
+    const scanner = new Scanner((paragraph) => send(leads.add(paragraph)));
     return {
         push(delta) {
             if (ended)
@@ -273,6 +332,7 @@ export function messageStream(options) {
                     scanner.line(line);
                 open = '';
                 scanner.end();
+                send(leads.end());
             }
             while (running)
                 await running;

package/dist/model-view.d.ts

@@ -242,8 +242,11 @@ export interface ShownCard {
  * store whose card went out, the line that led into that list (`here are a few:`, `other choices:`), a sentence that
  * points at a number the list gave (`the dishwand in #8`), a sentence that goes on to more of the list (`other 6-packs
  * are ...`, `there's also ...`) and names a card, and, past the one or two products a reply recommends in words, each
- * further sentence that names another card. What is left is the reply around the list, such as `found these at
- * amazon.` and `which one do you want?`. A reply whose cards went out names none of them twice over.
+ * further sentence that names another card. A list written on one line goes the same way, item by item (inlineList),
+ * and so does a list line written without a bullet, whole, up to the question on it. What is left is the reply around
+ * the list, such as `found these at amazon.` and `which one do you want?`. A reply whose cards went out names none of
+ * them twice over. A list that keeps an item for a product no card shows keeps its lead-in, and the two read as one
+ * message (toMessages), so the shopper never reads `two options came in under $20:` on its own.
  *
  * Each card is its name, or its name and its price as the model reads it (`{ name, price: '$22.89' }`): with the price,
  * a reply's short name for the product, such as `Planet Oat Extra Creamy ($22.89)`, reads as its card (cardsNamed).