@agent-cards/commerce-sdk 0.18.3 → 0.18.5

package/README.md

@@ -328,6 +328,16 @@ for await (const stream of runner) {
 - A step link, the `vault`, `approval` or `store_login` page the shopper opens to go on, comes after the message that asks for it: the turn holds it until your model's next message stream ends (or `turn.say` is called), then sends it right after that message, so the shopper reads "add your card to place the order" and then taps. Product and store cards go out the moment the tool hands them over. A held link also goes out when the turn's next call starts, or after 20 seconds, so a model that writes nothing still sends it. `turn.say` and the stream's `end` resolve once the held links went out too, and reject when one failed to send, so your app never answers without a link the shopper needs; a link that failed to go out at the next call or the 20 seconds rejects the next reply that ends.
 - Without `onItem`, pass `onMessage` beside `sendLink`, and write the model's text through `turn.messageStream()`: `onMessage` hears each message, paced, and `sendLink` hears each step link after the message that asks for it. An app that streams the model through the package's own `messageStream` gets each link the moment the tool hands it over, before the words about it.
 
+## Keep one purchase per chat
+
+A shopper who writes to your agent in several chats at once, such as group chats or threads, would otherwise continue one purchase from all of them. Build one tool per shopper and chat, and name the chat with `threadId`, your own id for it. Agentcard then keeps a purchase per chat: each chat's carts, questions and approvals stay in that chat, while the shopper keeps one Vault card, one store sign-in and one address book.
+
+```ts
+const buy = buyTool({ agentcard, externalUserId: shopper.id, threadId: chat.id }); // one per shopper and chat
+```
+
+A message about one chat's purchase carries that chat as `threadId`, so post it into that chat. One about the shopper alone, such as a saved card, carries `threadId: null`. A chat's tool takes a next step only for its own chat's messages and the shopper's own, and a tool built without `threadId` only for purchases opened under no thread and the shopper's own.
+
 ## Tell the model what Agentcard told the shopper
 
 Agentcard posts messages into the shopper's chat between turns, through `listen` or the webhook: `Your Visa ending 3132 is saved, so you're ready to check out.`, an order placed, an approval about to expire. The shopper reads them, so your model has to know them too. A model that never saw `card_added` answers "ok lets checkout" with "did you save your card?" and never calls the tool.
@@ -517,6 +527,8 @@ const buy = buyTool({
 
 When your app shows Agentcard's messages through `onText`, the model reads `shopper_already_read_reply: true` in that call's answer and adds nothing to them, as it reads `shopper_already_told_looking` after an instant reply: end the turn without a second model call, as with `replyAsWritten`, or let the model add one short line for what the reply left out. `turn.replyAsWritten` stays null for that answer, so the reply never reaches the shopper twice, and a step link the turn holds for your model's next message goes out right after Agentcard's ask instead.
 
+A turn built with `replyAsWritten` and `earlyCards` that hears messages through `onMessage` or `onItem` and passes no `onText` gets the same once a reply is written while a slower source's cards are still coming, such as a second hotel supplier's: Agentcard's messages go out through that callback the moment Agentcard says the reply is written, the slower cards and their one message follow in the same call, and the answer reads `shopper_already_read_reply: true` with `turn.replyAsWritten` null.
+
 A stream that breaks after the call started reads the conversation for what the turn left, as a turn past Agentcard's budget does. Pass `stream: false` to wait for each whole answer, with its cards sent beside it.
 
 Code that calls the client itself streams with `agentcard.buy(body, handlers)`: `onCatalog`, `onSegment`, `onCart` and `onDelta` hear their events in the order Agentcard sent them, each once the one before it settled, and the answer waits for the last of them. `onDelta` asks Agentcard for the pieces of each message as it writes them, a draft that each `onSegment` message replaces.

package/dist/buy-tool.d.ts

@@ -296,6 +296,13 @@ export interface BuyToolOptions {
     accessToken?: string;
     /** Your own id for the shopper. Required with a company client, and left out with a shopper's own token. */
     externalUserId?: string;
+    /**
+     * Your own id for the chat or thread this tool answers in, such as a group chat's id. Agentcard keeps one open purchase
+     * per thread for the shopper, so two chats never share a cart, a question or an approval, and the tool reads only the
+     * messages about this thread's purchase and those about the shopper alone, such as a saved card. Build one tool per
+     * shopper and thread. Leave it out for an app with one chat per shopper.
+     */
+    threadId?: string;
     /**
      * Delivers a link to the shopper. Each call waits for it, so the shopper
      * holds the link before the model answers. A `sendLink` that throws on a

package/dist/buy-tool.js

@@ -37,7 +37,7 @@ import { directCall, isProductAsk } from './direct.js';
 import { forModel, forModelError, pickId, productPrice, productCardKey, shownProducts, shownStores, stripLinks } from './model-view.js';
 import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, replyAsWritten, textingStyle } from './texting.js';
 import { joinLeadIns, leadInJoiner, messageStream, paceOf, paragraphsOf, sleep, toMessages, typingHook } from './messages.js';
-import { isStale } from './shopper-message.js';
+import { isStale, messageInChat } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
 import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, asksForSimilar, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
 /** The action a product of `merchant` takes (BuyToolProductAction). */
@@ -81,7 +81,7 @@ export function handedNote(answer) {
 }
 /** What the model reads of a message Agentcard posted into the chat: its text with every link taken out, as `forModel` takes them out. */
 const modelText = (message) => stripLinks(String(message.text ?? ''));
-/** How often the history held a message's text when the message first went in to the model. */
+/** How often each chat's history held a message's text when the message first went in to its model, by `threadId` ('' for none). */
 const offeredAt = new WeakMap();
 /** How many times `needle` appears in `haystack`, none overlapping. */
 function occurrences(haystack, needle) {
@@ -767,6 +767,12 @@ export function buyTool(options) {
     if (!client.company && externalUserId !== undefined) {
         throw new TypeError("A shopper's own access token already names the shopper. Leave externalUserId out.");
     }
+    if (o.threadId !== undefined && (typeof o.threadId !== 'string' || o.threadId.trim() === '' || o.threadId.trim().length > 200)) {
+        throw new TypeError('Pass threadId as your own id for the chat or thread, 1 to 200 characters, or leave it out.');
+    }
+    const threadId = o.threadId?.trim();
+    /** Whether a message is this tool's to read (`messageInChat`): its chat's purchase, or news about the shopper alone. */
+    const inThisThread = (message) => messageInChat(message, threadId);
     if (o.sendLink !== undefined && typeof o.sendLink !== 'function') {
         throw new TypeError('Pass sendLink as a function that delivers a link to the shopper.');
     }
@@ -1750,6 +1756,16 @@ export function buyTool(options) {
             let refusal;
             /** Each message of Agentcard's answer the app showed through onText, in the order the shopper read them: every one means the shopper read the reply. */
             const told = [];
+            /**
+             * Where this call's messages from Agentcard go as they stream: the app's onText, or, for an app that shows the reply as
+             * written, its onMessage once Agentcard says the reply is written (`reply_written`). Until then such an app's
+             * messages are kept in `unsaid`, and a call whose stream never says so shows none of them: the app shows the answer.
+             */
+            let speak = t.onText;
+            // Only where the cards went out as they streamed (earlyCards): a reply shown earlier than its cards would ask the shopper
+            // to choose from hotels they cannot see yet.
+            const writtenText = early ? t.onWrittenText : undefined;
+            const unsaid = [];
             /**
              * The streamed messages that wait for the answer: the first that asks for a card or points at a link (waitsForAnswer),
              * and every message after it, so the shopper reads them in the order Agentcard wrote them.
@@ -1762,7 +1778,7 @@ export function buyTool(options) {
             let heldTexts = [];
             /** Shows a message through onText, its lists as bullets (messageForShopper); `told` keeps each of Agentcard's messages in it as written. */
             const showMessage = async (message, texts, conversationId) => {
-                await t.onText(messageForShopper(message, leadIn, t.texting), { conversationId });
+                await speak(messageForShopper(message, leadIn, t.texting), { conversationId });
                 leadIn = leadsIntoList(message);
                 told.push(...texts);
             };
@@ -1863,6 +1879,23 @@ export function buyTool(options) {
                     // The app's display failing never fails the call.
                 }
             };
+            /** One of Agentcard's messages as it streams, to the app through `speak`. */
+            const streamText = async (text, conversationId) => {
+                // A message that lands before the instant reply was due is the reply; one after it follows it.
+                ack?.cancel();
+                await t.ackOut;
+                // A card ask or a link waits for the answer, which may name a step that comes first, and every message after it waits behind it.
+                if (waiting.length > 0 || waitsForAnswer(text)) {
+                    waiting.push({ text, conversationId });
+                    return;
+                }
+                try {
+                    await showText(text, conversationId);
+                }
+                catch {
+                    // A message the app failed to show was never read, so the model words the answer.
+                }
+            };
             // Streamed: the stages go to onProgress, a search's products to onProducts and its store pages out the moment it
             // answers, and each message and cart to the app as Agentcard writes it.
             const handlers = streams
@@ -1928,23 +1961,25 @@ export function buyTool(options) {
                             },
                         }
                         : {}),
-                    ...(t.onText
+                    ...(t.onText || writtenText
                         ? {
                             onSegment: async ({ text, conversationId }) => {
-                                // A message that lands before the instant reply was due is the reply; one after it follows it.
-                                ack?.cancel();
-                                await t.ackOut;
-                                // A card ask or a link waits for the answer, which may name a step that comes first, and every message after it waits behind it.
-                                if (waiting.length > 0 || waitsForAnswer(text)) {
-                                    waiting.push({ text, conversationId });
+                                if (!speak) {
+                                    unsaid.push({ text, conversationId });
                                     return;
                                 }
-                                try {
-                                    await showText(text, conversationId);
-                                }
-                                catch {
-                                    // A message the app failed to show was never read, so the model words the answer.
-                                }
+                                await streamText(text, conversationId);
+                            },
+                        }
+                        : {}),
+                    ...(!t.onText && writtenText
+                        ? {
+                            onReplyWritten: async () => {
+                                if (speak)
+                                    return;
+                                speak = writtenText;
+                                for (const message of unsaid.splice(0))
+                                    await streamText(message.text, message.conversationId);
                             },
                         }
                         : {}),
@@ -1983,6 +2018,9 @@ export function buyTool(options) {
             // A streamed ask for something new that the tool shows no line of Agentcard's for says so. A pick never gets one.
             const streamed = !!handlers && Object.values(handlers).some((handler) => typeof handler === 'function');
             sent = planned.ask !== undefined && !planned.pick && streamed && !agentcardAcks ? { ...planned, ack: false } : planned;
+            // Every request names the tool's thread, so Agentcard continues this chat's purchase and no other.
+            if (threadId)
+                sent = { ...sent, thread_id: threadId };
             if (plan && 'local' in plan) {
                 // Nothing went to Agentcard: the answer is where the purchase stands.
             }
@@ -2003,6 +2041,8 @@ export function buyTool(options) {
                 // Only the answer of the request sent again counts toward what the shopper read.
                 told.length = 0;
                 waiting.length = 0;
+                unsaid.length = 0;
+                speak = t.onText;
                 leads = leadInJoiner();
                 heldTexts = [];
                 try {
@@ -2029,7 +2069,7 @@ export function buyTool(options) {
             // a link the answer replaced gives way to its ask for the step Agentcard named, once, after them. All of them go out
             // before any link of the answer.
             let replaced = false;
-            if (waiting.length > 0 && t.onText) {
+            if (waiting.length > 0 && speak) {
                 const rewritten = !!turn && settled.reply !== turn.reply;
                 // Paragraph for paragraph, as `told` keeps Agentcard's messages, before any lead-in joins the one after it.
                 const kept = new Set((rewritten ? paragraphsOf(settled.reply) : []).map((message) => message.trim()));
@@ -2055,7 +2095,7 @@ export function buyTool(options) {
                     }
                 }
             }
-            if (t.onText) {
+            if (speak) {
                 try {
                     await showLeftLead();
                 }
@@ -2068,10 +2108,10 @@ export function buyTool(options) {
             // A reply the shopper read that asks them to choose, with the values named inside a sentence or not at all, is followed
             // by one more message that lists every value on its own line (choiceLines), so no choice is read buried in prose.
             let choiceShown = true;
-            if (t.onText && turn?.choice && told.length > 0 && !messagesListChoice(told, turn.choice)) {
+            if (speak && turn?.choice && told.length > 0 && !messagesListChoice(told, turn.choice)) {
                 const lines = choiceLines(turn.choice);
                 try {
-                    await t.onText(t.texting ? textingStyle(lines) : lines, { conversationId: turn.conversation_id || null });
+                    await speak(t.texting ? textingStyle(lines) : lines, { conversationId: turn.conversation_id || null });
                 }
                 catch {
                     // Not shown, so the shopper has not read the whole answer: the model words it, with the choice it reads.
@@ -2235,6 +2275,8 @@ export function buyTool(options) {
             return null;
         if (client.company && message.externalUserId !== externalUserId)
             return null;
+        if (!inThisThread(message))
+            return null;
         if (message.eventId && stepped.has(message.eventId))
             return null;
         // A call for the shopper's own message is still running: its answer tells the model where the purchase stands.
@@ -2243,7 +2285,7 @@ export function buyTool(options) {
         if (message.eventId)
             stepped.add(message.eventId);
         if (client.company)
-            client.answered(externalUserId, message);
+            client.answered(externalUserId, message, threadId);
         return openTurn(nextStepPrompt(message), options, message);
     };
     const openTurn = (shopperText, options, event) => {
@@ -2337,6 +2379,12 @@ export function buyTool(options) {
             // Agentcard's message takes its place in the turn's sequence, after the items before it, and goes to onText alone, so
             // an app that passes onItem too hears it once.
             onText: hearText ? (text, info) => feed.push({ kind: 'text', text }, () => hearText(text, info)) : undefined,
+            // An app that shows the reply as written hears it the moment Agentcard says it is written, when the turn then waits for
+            // a slower source's cards: the reply no longer waits for them (chat.opencommerce.sh, 2026-10-29, a hotel reply written
+            // at about 21 s reached the shopper at 36.5 s, with the second supplier's hotels).
+            onWrittenText: !hearText && written && (onItem || onMessage)
+                ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : onMessage?.(text)))
+                : undefined,
             texting,
             onCart: own.onCart ?? o.onCart,
             tell: onItem || baseOnWorking ? (text) => feed.push({ kind: 'text', text }, () => (onItem ? onItem({ kind: 'text', text }) : baseOnWorking?.(text))) : undefined,
@@ -2504,7 +2552,7 @@ export function buyTool(options) {
         if (!event)
             previousTurn = state;
         // What Agentcard told the shopper that no history the model ran with holds yet.
-        const kept = client.company ? client.keptMessages(externalUserId) : [];
+        const kept = client.company ? client.keptMessages(externalUserId, threadId).filter(inThisThread) : [];
         let handed = null;
         const shopperWords = String(shopperText ?? '');
         /**
@@ -2526,18 +2574,20 @@ export function buyTool(options) {
                 // Another order's update can read the same, so only a history holding the text more often than
                 // when this message first went in holds this message.
                 const count = occurrences(held, JSON.stringify(text).slice(1, -1));
-                const before = offeredAt.get(message);
+                // Each chat counts its own history: a message about the shopper alone goes in to every chat's model.
+                const counts = offeredAt.get(message) ?? new Map();
+                const before = counts.get(threadId ?? '');
                 if (before !== undefined && count > before) {
                     saved.push(message);
                 }
                 else {
                     if (before === undefined)
-                        offeredAt.set(message, count);
+                        offeredAt.set(message, counts.set(threadId ?? '', count));
                     fresh.push(message);
                 }
             }
             if (saved.length > 0)
-                client.forgetMessages(externalUserId, saved);
+                client.forgetMessages(externalUserId, saved, threadId);
             handed = fresh;
             // A message Agentcard answered for the model to word goes in with that answer, so the model words it and calls nothing again.
             return turnMessages(history, fresh.map(modelText), handedAnswer === null ? shopperWords : `${shopperWords}\n\n${handedNote(handedAnswer)}`);
@@ -2613,7 +2663,7 @@ export function buyTool(options) {
                     if (event.eventId)
                         stepped.delete(event.eventId);
                     if (client.company)
-                        client.unanswered(externalUserId, event);
+                        client.unanswered(externalUserId, event, threadId);
                 },
                 enumerable: false,
             },

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { type AgentcardListener, type ListenOptions } from './listen.js';
-import type { ShopperMessage } from './shopper-message.js';
+import { type ShopperMessage } from './shopper-message.js';
 /** The fetch the client calls: Node 18 and later have one built in. */
 export type FetchLike = (url: string, init: {
     method: string;
@@ -144,6 +144,13 @@ export interface BuyStreamHandlers {
     onDelta?: (update: BuyDeltaUpdate) => void | Promise<void>;
     /** Whether the places the turn's cards show have room, once Agentcard's live search says, after the cards it changes. */
     onAvailability?: (update: BuyAvailabilityUpdate) => void | Promise<void>;
+    /**
+     * The reply is written, after its messages, and the turn stays open only for a slower source's cards, such as a second
+     * hotel supplier's, and the one message that says what they added. Comes once, or not at all when nothing is still out.
+     */
+    onReplyWritten?: (update: {
+        conversationId: string | null;
+    }) => void | Promise<void>;
 }
 export declare 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. */
@@ -228,6 +235,12 @@ export interface BuyRequest {
     resume?: true;
     /** The conversation a confirm of a cart hash belongs to, in place of `resume`. */
     conversation_id?: string;
+    /**
+     * Your own id for the chat or thread the shopper wrote in, such as a group chat's id (up to 200 characters). The shopper
+     * keeps one open purchase per thread: `resume` continues the newest one in this thread only, and a conversation_id from
+     * another thread is refused (409 `thread_mismatch`). Leave it out for an app with one chat per shopper.
+     */
+    thread_id?: string;
     /** Drop the cart on the table and start a new order. */
     new_order?: true;
     /**
@@ -429,6 +442,19 @@ export interface BuyChoiceOption {
     label: string;
     /** What choosing it adds to the price, in cents: 0 when free, null when the store does not say. */
     price_delta_cents: number | null;
+    /** On a `recipe_delivery` choice: the grocery store, when it arrives and what this way costs. Absent on every other choice. */
+    delivery?: BuyChoiceDelivery;
+}
+/**
+ * One way a recipe's groceries can come: the DoorDash grocery store, its street when DoorDash names one, its delivery estimate in
+ * minutes (null when DoorDash shows none), the total with DoorDash's fees, and the part of that total that ships from Walmart or Amazon.
+ */
+export interface BuyChoiceDelivery {
+    store: string;
+    store_address: string | null;
+    eta_minutes: number | null;
+    total_cents: number;
+    shipped_cents: number;
 }
 /** One group of values, such as a sandwich's bread or a shirt's size. `min` and `max` count the values picked; `max` null for no limit. */
 export interface BuyChoiceGroup {
@@ -441,7 +467,8 @@ export interface BuyChoiceGroup {
 /**
  * The choice an answer's reply asks the shopper to make, as data: the question, the item it is about, where the values come
  * from (`menu_item`: a restaurant item's options, `store_checkout`: a store's own size or colour question, `catalog_variant`:
- * a product's sizes or colours in stock), and every group with its values.
+ * a product's sizes or colours in stock, `recipe_delivery`: the ways a recipe's groceries can come, each option with its
+ * `delivery`), and every group with its values.
  */
 export interface BuyChoice {
     question: string | null;
@@ -601,6 +628,10 @@ export declare class AgentcardClient {
     private learnedSandbox;
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     private readonly inbox;
+    /** The chats (`threadId`, '' for a tool built without one) that need a kept message about the shopper alone no more: their history holds it, or their agent answered it (`forgetMessages`, `answered`). */
+    private readonly savedInChats;
+    /** The same marks by event id, for a copy of the message delivered later, such as a retried webhook's: `delivered` starts that copy with them. */
+    private readonly savedInChatsById;
     private readonly deliveredIds;
     private readonly trace;
     constructor(options: AgentcardClientOptions);
@@ -645,22 +676,41 @@ export declare class AgentcardClient {
     delivered(externalUserId: string, message: ShopperMessage): void;
     /**
      * Notes that your agent answers `message` with a turn of its own (`buy.nextStep`) instead of posting
-     * its `text`, so the shopper never reads that text: `delivered` skips it from now on, and no later
-     * `buy.turn` hands it to the model as words the shopper read. `buy.nextStep` calls it.
+     * its `text`, so the shopper never reads that text in that chat (`threadId`, or the tool built
+     * without one). A message about one purchase belongs to one chat, so it leaves the client:
+     * `delivered` skips it from now on, and no later `buy.turn` hands it to the model as words the
+     * shopper read. A message about the shopper alone, such as a saved card, is answered for that chat
+     * only: the shopper's other chats still keep it. `buy.nextStep` calls it.
      */
-    answered(externalUserId: string, message: ShopperMessage): void;
+    answered(externalUserId: string, message: ShopperMessage, threadId?: string): void;
     /**
      * Takes back `answered` for a message your agent's own turn could not answer (`BuyToolTurn.release` calls it): once you
-     * post its text after all, `delivered` keeps it, and a later `buy.turn` hands it to the model as words the shopper read.
+     * post its text after all, `delivered` keeps it, and a later `buy.turn` in that chat hands it to the model as words the
+     * shopper read.
+     */
+    unanswered(externalUserId: string, message: ShopperMessage, threadId?: string): void;
+    /**
+     * The messages kept for this shopper that this chat reads, oldest first: each one about a purchase
+     * opened in this chat or about the shopper alone, that reached their chat and that no history
+     * `turn.messages` read in this chat has held yet. The chat is `threadId`, or the tool built without
+     * one, which reads the purchases opened under no thread. `buy.turn` reads them when it opens.
+     */
+    keptMessages(externalUserId: string, threadId?: string): ShopperMessage[];
+    /**
+     * Forgets these messages for this shopper in this chat (`threadId`, or the tool built without one): `turn.messages`
+     * calls it once the history it reads holds them. A message about one purchase leaves the client, since one chat reads
+     * it. A message about the shopper alone, such as a saved card, stays kept for the shopper's other chats until their
+     * own histories hold it.
      */
-    unanswered(externalUserId: string, message: ShopperMessage): void;
+    forgetMessages(externalUserId: string, messages: readonly ShopperMessage[], threadId?: string): void;
     /**
-     * The messages kept for this shopper, oldest first: each one that reached their chat and that no
-     * history `turn.messages` read has held yet. `buy.turn` reads them when it opens.
+     * Marks a message about the shopper alone as one this chat needs no more, its history holding it or its agent having
+     * answered it, or takes the mark back. The kept copies with the same event id carry the mark too, and so does a copy
+     * delivered later (`delivered`), while the client still remembers the id.
      */
-    keptMessages(externalUserId: string): ShopperMessage[];
-    /** Forgets these messages for this shopper: `turn.messages` calls it once the history it reads holds them. */
-    forgetMessages(externalUserId: string, messages: readonly ShopperMessage[]): void;
+    private markChat;
+    /** Removes these messages from the shopper's kept messages, for every chat. */
+    private dropKept;
     /** A company names the shopper exactly once; a shopper's own token already names them. */
     private checkShopper;
     private call;

package/dist/client.js

@@ -10,8 +10,9 @@
  */
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
+import { messageInChat } from './shopper-message.js';
 /** The handlers that ask Agentcard to stream a turn. */
-const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability'];
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onAck', 'onCart', 'onDelta', 'onAvailability', 'onReplyWritten'];
 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. */
@@ -309,11 +310,17 @@ export function choiceOf(value) {
     if (!isRecord(value) || !Array.isArray(value.groups))
         return null;
     const groups = value.groups.filter(isRecord).flatMap((g) => {
-        const options = (Array.isArray(g.options) ? g.options : []).filter(isRecord).flatMap((o) => str(o.label) ? [{ id: str(o.id), label: o.label.trim(), price_delta_cents: num(o.price_delta_cents) }] : []);
+        const options = (Array.isArray(g.options) ? g.options : []).filter(isRecord).flatMap((o) => str(o.label) ? [{ id: str(o.id), label: o.label.trim(), price_delta_cents: num(o.price_delta_cents), ...deliveryOf(o.delivery) }] : []);
         return options.length ? [{ name: str(g.name) ?? '', required: g.required === true, min: num(g.min) ?? 0, max: num(g.max), options }] : [];
     });
     return groups.length ? { question: str(value.question), item: str(value.item), source: str(value.source) ?? '', groups } : null;
 }
+/** A recipe option's `delivery`, as `{ delivery }` when it names a store and a total, else nothing. */
+function deliveryOf(value) {
+    if (!isRecord(value) || !str(value.store) || num(value.total_cents) === null)
+        return {};
+    return { delivery: { store: value.store, store_address: str(value.store_address), eta_minutes: num(value.eta_minutes), total_cents: num(value.total_cents), shipped_cents: num(value.shipped_cents) ?? 0 } };
+}
 /** A cart being built, as an answer, a refusal or the conversation read names it. */
 export function cartBuildingOf(value) {
     return isRecord(value) && str(value.store) ? { store: value.store, started_at: str(value.started_at) ?? '' } : null;
@@ -457,7 +464,7 @@ async function eachEvent(res, onEvent) {
 }
 /**
  * A streamed purchase turn, read to its `envelope`: the same answer a JSON turn returns, with its
- * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `cart` and `venue_availability` goes to its handler
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `reply_written`, `cart` and `venue_availability` goes to its handler
  * on the way, and any other event, such as a `ping` or a `tool`, is read past. A stream that breaks or
  * ends before its envelope, once it named the conversation, reads as a turn past its budget
  * (`turn_timeout`), so the tool reads the conversation for what the turn left instead of losing it.
@@ -536,6 +543,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 === 'reply_written' && stream.onReplyWritten) {
+                deliver(() => stream.onReplyWritten({ conversationId: named }));
+            }
             else if (event === 'ack' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onAck) {
                 deliver(() => stream.onAck({ conversationId: named, text: data.text }));
             }
@@ -580,6 +590,10 @@ export class AgentcardClient {
     learnedSandbox = null;
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     inbox = new Map();
+    /** The chats (`threadId`, '' for a tool built without one) that need a kept message about the shopper alone no more: their history holds it, or their agent answered it (`forgetMessages`, `answered`). */
+    savedInChats = new WeakMap();
+    /** The same marks by event id, for a copy of the message delivered later, such as a retried webhook's: `delivered` starts that copy with them. */
+    savedInChatsById = new Map();
     deliveredIds = new Set();
     trace;
     constructor(options) {
@@ -724,6 +738,10 @@ export class AgentcardClient {
                 this.deliveredIds.delete(this.deliveredIds.values().next().value);
         }
         const kept = this.inbox.get(externalUserId) ?? [];
+        // A copy delivered again, such as a retried webhook's, keeps the chats that already answered it.
+        const marks = str(message.eventId) ? this.savedInChatsById.get(message.eventId) : undefined;
+        if (marks)
+            this.savedInChats.set(message, new Set(marks));
         // The shopper written to last moves to the end, so the one dropped first is the one written to longest ago.
         this.inbox.delete(externalUserId);
         this.inbox.set(externalUserId, [...kept, message].slice(-DELIVERED_PER_SHOPPER));
@@ -732,14 +750,21 @@ export class AgentcardClient {
     }
     /**
      * Notes that your agent answers `message` with a turn of its own (`buy.nextStep`) instead of posting
-     * its `text`, so the shopper never reads that text: `delivered` skips it from now on, and no later
-     * `buy.turn` hands it to the model as words the shopper read. `buy.nextStep` calls it.
+     * its `text`, so the shopper never reads that text in that chat (`threadId`, or the tool built
+     * without one). A message about one purchase belongs to one chat, so it leaves the client:
+     * `delivered` skips it from now on, and no later `buy.turn` hands it to the model as words the
+     * shopper read. A message about the shopper alone, such as a saved card, is answered for that chat
+     * only: the shopper's other chats still keep it. `buy.nextStep` calls it.
      */
-    answered(externalUserId, message) {
+    answered(externalUserId, message, threadId) {
         if (!str(externalUserId))
             throw new TypeError('Pass externalUserId: your own id for the shopper the message is for.');
         if (!isRecord(message))
             throw new TypeError('Pass the message onMessage got.');
+        if (!message.threadId && !message.conversationId) {
+            this.markChat(externalUserId, message, threadId ?? '', true);
+            return;
+        }
         if (str(message.eventId)) {
             this.deliveredIds.add(message.eventId);
             if (this.deliveredIds.size > DELIVERED_IDS_KEPT)
@@ -747,31 +772,82 @@ export class AgentcardClient {
         }
         const kept = this.inbox.get(externalUserId);
         if (kept)
-            this.forgetMessages(externalUserId, kept.filter((m) => m === message || (!!message.eventId && m.eventId === message.eventId)));
+            this.dropKept(externalUserId, kept.filter((m) => m === message || (!!message.eventId && m.eventId === message.eventId)));
     }
     /**
      * Takes back `answered` for a message your agent's own turn could not answer (`BuyToolTurn.release` calls it): once you
-     * post its text after all, `delivered` keeps it, and a later `buy.turn` hands it to the model as words the shopper read.
+     * post its text after all, `delivered` keeps it, and a later `buy.turn` in that chat hands it to the model as words the
+     * shopper read.
      */
-    unanswered(externalUserId, message) {
+    unanswered(externalUserId, message, threadId) {
         if (!str(externalUserId))
             throw new TypeError('Pass externalUserId: your own id for the shopper the message is for.');
         if (!isRecord(message))
             throw new TypeError('Pass the message onMessage got.');
+        if (!message.threadId && !message.conversationId) {
+            this.markChat(externalUserId, message, threadId ?? '', false);
+            return;
+        }
         if (str(message.eventId))
             this.deliveredIds.delete(message.eventId);
     }
     /**
-     * The messages kept for this shopper, oldest first: each one that reached their chat and that no
-     * history `turn.messages` read has held yet. `buy.turn` reads them when it opens.
+     * The messages kept for this shopper that this chat reads, oldest first: each one about a purchase
+     * opened in this chat or about the shopper alone, that reached their chat and that no history
+     * `turn.messages` read in this chat has held yet. The chat is `threadId`, or the tool built without
+     * one, which reads the purchases opened under no thread. `buy.turn` reads them when it opens.
      */
-    keptMessages(externalUserId) {
-        return [...(this.inbox.get(externalUserId) ?? [])];
+    keptMessages(externalUserId, threadId) {
+        const chat = threadId ?? '';
+        return (this.inbox.get(externalUserId) ?? []).filter((m) => messageInChat(m, threadId) && !this.savedInChats.get(m)?.has(chat));
     }
-    /** Forgets these messages for this shopper: `turn.messages` calls it once the history it reads holds them. */
-    forgetMessages(externalUserId, messages) {
+    /**
+     * Forgets these messages for this shopper in this chat (`threadId`, or the tool built without one): `turn.messages`
+     * calls it once the history it reads holds them. A message about one purchase leaves the client, since one chat reads
+     * it. A message about the shopper alone, such as a saved card, stays kept for the shopper's other chats until their
+     * own histories hold it.
+     */
+    forgetMessages(externalUserId, messages, threadId) {
+        const chat = threadId ?? '';
+        this.dropKept(externalUserId, messages.filter((m) => {
+            if (m.threadId || m.conversationId)
+                return true;
+            this.markChat(externalUserId, m, chat, true);
+            return false;
+        }));
+    }
+    /**
+     * Marks a message about the shopper alone as one this chat needs no more, its history holding it or its agent having
+     * answered it, or takes the mark back. The kept copies with the same event id carry the mark too, and so does a copy
+     * delivered later (`delivered`), while the client still remembers the id.
+     */
+    markChat(externalUserId, message, chat, done) {
+        const id = str(message.eventId);
+        const mark = (chats) => {
+            if (done)
+                chats.add(chat);
+            else
+                chats.delete(chat);
+            return chats;
+        };
+        const same = (m) => m === message || (!!id && m.eventId === id);
+        for (const m of new Set([message, ...(this.inbox.get(externalUserId) ?? []).filter(same)])) {
+            this.savedInChats.set(m, mark(this.savedInChats.get(m) ?? new Set()));
+        }
+        if (!id)
+            return;
+        // The id marked last moves to the end, so the one dropped first is the one marked longest ago. A kept copy keeps its
+        // own marks after its id is dropped.
+        const chats = mark(this.savedInChatsById.get(id) ?? new Set());
+        this.savedInChatsById.delete(id);
+        this.savedInChatsById.set(id, chats);
+        if (this.savedInChatsById.size > DELIVERED_IDS_KEPT)
+            this.savedInChatsById.delete(this.savedInChatsById.keys().next().value);
+    }
+    /** Removes these messages from the shopper's kept messages, for every chat. */
+    dropKept(externalUserId, messages) {
         const kept = this.inbox.get(externalUserId);
-        if (!kept)
+        if (!kept || messages.length === 0)
             return;
         const left = kept.filter((m) => !messages.includes(m));
         if (left.length > 0)

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 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 { 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 BuyChoiceDelivery, 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/shopper-message.d.ts

@@ -72,6 +72,12 @@ export interface ShopperMessage {
     externalUserId: string | null;
     /** The buy conversation the event belongs to, when Agentcard names one. */
     conversationId: string | null;
+    /**
+     * Your own id for the chat or thread that conversation opened under (the buy tool's `threadId`, POST /buy `thread_id`):
+     * the chat to post `text` into. Null for a purchase that opened under none, and for a message about the shopper alone,
+     * such as a saved card.
+     */
+    threadId: string | null;
     /** Ready to send to the shopper as is. */
     text: string;
     /** For your agent: the facts of what happened, marked as written by the system and not typed by the shopper. */
@@ -97,6 +103,12 @@ export interface ShopperMessage {
     /** Unix seconds. */
     created: number;
 }
+/**
+ * Whether a chat reads this message: one about a purchase opened under the chat's thread, matched both ways, so the chat
+ * of a tool built without `threadId` reads the purchases opened under none and never a chat's, or one about the shopper
+ * alone, which names neither a thread nor a conversation. Internal: `buyTool` and the client's kept messages share it.
+ */
+export declare function messageInChat(message: Pick<ShopperMessage, 'threadId' | 'conversationId'>, threadId?: string): boolean;
 /**
  * The message an event carries for a shopper, or null when it carries none: an event type that is
  * not a shopper event, an order event that names no shopper, or a delivery stage the package does

package/dist/shopper-message.js

@@ -89,6 +89,7 @@ function orderBase(event, type) {
             userId,
             externalUserId: id(data.external_user_id) ?? null,
             conversationId: id(data.conversation_id) ?? null,
+            threadId: id(data.thread_id) ?? null,
             clientId: id(connection.client_id) ?? null,
             livemode: event.livemode,
             created: event.created,
@@ -180,6 +181,14 @@ function readOrderUpdated(event) {
         order,
     };
 }
+/**
+ * Whether a chat reads this message: one about a purchase opened under the chat's thread, matched both ways, so the chat
+ * of a tool built without `threadId` reads the purchases opened under none and never a chat's, or one about the shopper
+ * alone, which names neither a thread nor a conversation. Internal: `buyTool` and the client's kept messages share it.
+ */
+export function messageInChat(message, threadId) {
+    return (message.threadId || undefined) === (threadId || undefined) || (!message.threadId && !message.conversationId);
+}
 /**
  * The message an event carries for a shopper, or null when it carries none: an event type that is
  * not a shopper event, an order event that names no shopper, or a delivery stage the package does
@@ -198,6 +207,7 @@ export function readShopperMessage(event) {
         ...message,
         type: 'purchase.message',
         conversationId: id(event.data.conversation_id) ?? null,
+        threadId: id(event.data.thread_id) ?? null,
         advances: NEXT_STEP.has(message.kind),
         order: purchaseOrder(message.kind, message.facts, event.created),
     };

package/dist/turn-record.d.ts

@@ -4,8 +4,8 @@
  * This file imports nothing, so the server helper (`turnStream`) and the browser reader (`streamTurn`) share it.
  */
 /**
- * Whether a turn keeps its record and a dropped stream reads it back. Off until the pull request that turns it on:
- * while it is off, `turnStream` streams without saving and `streamTurn` reports a drop as the error it was.
+ * Whether a turn keeps its record and a dropped stream reads it back. When it is off, `turnStream` streams without
+ * saving and `streamTurn` reports a drop as the error it was; `recover: false` does the same for the one call it is passed to.
  */
 export declare const TURN_RECOVERY_ON: boolean;
 /** One event of a turn, as its server-sent frame carries it: `event: <event>` and `data: <JSON of data>`. */

package/dist/turn-record.js

@@ -4,10 +4,10 @@
  * This file imports nothing, so the server helper (`turnStream`) and the browser reader (`streamTurn`) share it.
  */
 /**
- * Whether a turn keeps its record and a dropped stream reads it back. Off until the pull request that turns it on:
- * while it is off, `turnStream` streams without saving and `streamTurn` reports a drop as the error it was.
+ * Whether a turn keeps its record and a dropped stream reads it back. When it is off, `turnStream` streams without
+ * saving and `streamTurn` reports a drop as the error it was; `recover: false` does the same for the one call it is passed to.
  */
-export const TURN_RECOVERY_ON = false;
+export const TURN_RECOVERY_ON = true;
 /** A turn id the browser makes up front: 8 to 64 letters, digits, `-` or `_`. Check one before using it in a key. */
 export function isTurnId(value) {
     return typeof value === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(value);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.3",
+  "version": "0.18.5",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
+  "homepage": "https://opencommerce.sh",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",