@agent-cards/commerce-sdk 0.18.4 → 0.18.6

package/dist/client.d.ts

@@ -1,5 +1,16 @@
+/**
+ * The client the buy tool calls Agentcard with. A company builds one from its
+ * client credentials, and every shopper's tool shares the one access token it
+ * exchanges them for; or a tool runs on one shopper's own access token. The
+ * global fetch is the only transport, so the package keeps no dependencies.
+ *
+ * The answer fields and the error codes follow the buy module of
+ * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
+ * token cache follows its client (packages/checkout/src/client.ts accessToken).
+ */
+import { type BuyPlan } from './plan.js';
 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 +155,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 +246,22 @@ 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;
+    /**
+     * How long, in milliseconds, the reply waits for store searches before Agentcard writes it. Left out, Agentcard keeps
+     * its own wait. `buyTool({ storeWaitMs })` sends it on every request.
+     */
+    store_wait_ms?: number;
+    /**
+     * What happens to a store that answers after the reply: `stream` sends its cards after the reply in the same streamed
+     * turn, before the answer; `hold` keeps them out of the turn. Left out, Agentcard does as it does today.
+     */
+    late_results?: 'stream' | 'hold';
     /** Drop the cart on the table and start a new order. */
     new_order?: true;
     /**
@@ -529,6 +563,8 @@ export interface BuyTurn {
     cart_building: BuyCartBuilding | null;
     /** The choice the reply asks the shopper to make, each group with every value; null when it asks none, and on an older API. */
     choice: BuyChoice | null;
+    /** The checkout plan this answer's yes started or moved, with each item's state; null when none, and on an older API. */
+    plan: BuyPlan | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -568,8 +604,22 @@ export interface BuyConversation {
     last_checkout: BuyLastCheckout | null;
     orders: BuyOrder[];
     carts: BuyCart[];
+    /**
+     * The reply Agentcard wrote since the shopper's last message, once no turn runs: the answer a call that ended with
+     * `turn_timeout` never got. Null while a turn runs, when no reply was written since, and on an older API.
+     */
+    latest_reply: BuyLatestReply | null;
     raw: Record<string, unknown>;
 }
+/** A reply a conversation read hands back: its text, its messages, and the products it showed. */
+export interface BuyLatestReply {
+    message_id: string;
+    text: string;
+    messages: string[];
+    /** The products the reply showed, when the call that asked ended before it was written; null otherwise. */
+    catalog: BuyCatalog | null;
+    created_at: string | null;
+}
 /** A Vault link: the page where a shopper connects and adds a card. */
 export interface VaultLink {
     id: string;
@@ -615,6 +665,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);
@@ -659,22 +713,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

@@ -8,10 +8,12 @@
  * @agent-cards/sdk (packages/checkout/src/buy.ts: turnOf, buyError), and the
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
+import { planOf } from './plan.js';
 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. */
@@ -301,6 +303,7 @@ export function turnOf(body) {
         store_pick: isRecord(body.store_pick) && str(body.store_pick.store_id) ? { store_id: body.store_pick.store_id, name: str(body.store_pick.name), selected: body.store_pick.selected === true } : null,
         cart_building: cartBuildingOf(body.cart_building),
         choice: choiceOf(body.choice),
+        plan: planOf(body.plan),
         raw: body,
     };
 }
@@ -357,9 +360,23 @@ function conversationOf(body) {
             placed_at: str(o.placed_at),
         })) : [],
         carts: cartsOf(body.carts),
+        latest_reply: latestReplyOf(body.latest_reply),
         raw: body,
     };
 }
+/** The reply a conversation read hands back, or null when it names no text. */
+function latestReplyOf(value) {
+    if (!isRecord(value) || !str(value.text)?.trim())
+        return null;
+    const messages = Array.isArray(value.messages) ? value.messages.filter((m) => typeof m === 'string' && m.trim() !== '') : [];
+    return {
+        message_id: str(value.message_id) ?? '',
+        text: value.text,
+        messages: messages.length > 0 ? messages : [value.text],
+        catalog: catalogOf(value.catalog),
+        created_at: str(value.created_at),
+    };
+}
 /** An error code as the API spells one: lower-case words joined by underscores. */
 const CODE = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
 /**
@@ -463,7 +480,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.
@@ -542,6 +559,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 }));
             }
@@ -586,6 +606,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) {
@@ -730,6 +754,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));
@@ -738,14 +766,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)
@@ -753,31 +788,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/definition.js

@@ -52,7 +52,8 @@ export const BUY_TOOL_RULES = [
     '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.",
+    "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, Best Buy and thousands more stores, so name those four and say \"and thousands more stores\" every time you name the stores you shop, in a reply about one kind of thing too, such as \"travel gear from Amazon, Target and thousands more stores\": never let the four read as the whole list, never say \"plenty more\", \"many more\" or \"most online stores\", and never give a number of stores. Name no other store unless a result showed it.",
+    "Never tell the shopper you can't render or show Markdown, a table or other formatting, and never say you keep to plain text: how your words look is your app's to decide.",
     '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".',
     'When you list options or choices for the shopper, such as sizes, breads, times, or stores no card shows, write one per line, each starting with "• ", in the same paragraph as the line that asks which one, so the question and its choices reach the shopper as one message. When the result has `choice`, list every value it holds that way, with its extra price, such as "• Gluten-free bread (+$2.46)", even when `reply` names them inside a sentence. The products and stores the cards show are still never listed again.',

package/dist/direct.d.ts

@@ -36,6 +36,14 @@ export interface DirectContext {
         productId: string | null;
         name: string;
     }>;
+    /**
+     * Every product card an earlier answer of this conversation showed, each once, newest first. A card's tap whose name no card
+     * of `tappable` holds is read against these, so a tap on a card two answers back still sends its `product_id`.
+     */
+    shownBefore?: 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

@@ -185,14 +185,25 @@ function pickOf(raw, bare, context) {
         if (named.length > 1)
             return call({});
     }
+    // A tap on a card an earlier answer showed, after an answer that showed no cards: it is read against every card shown before.
+    const tapNow = byName.length === 0 ? tappedName(raw) : null;
+    if (tapNow !== null) {
+        const before = (context.shownBefore ?? []).filter((product) => product.productId && [nameWords(tapNow), nameWords(`the ${tapNow}`)].includes(nameWords(product.name)));
+        if (before.length > 0)
+            return call(new Set(before.map((product) => product.productId)).size === 1 ? { product_id: before[0].productId } : {});
+    }
     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 } : {});
+            const named = (cards) => cards.filter((product) => [nameWords(tap), nameWords(`the ${tap}`)].includes(nameWords(product.name)));
+            const exact = named(byName);
+            // A tap on a card an earlier answer showed names a card of no newer list: it is read against every card shown before.
+            const before = exact.length === 0 ? named(context.shownBefore ?? []).filter((product) => product.productId) : [];
+            const card = exact.length === 1 ? exact[0] : exact.length === 0 && new Set(before.map((product) => product.productId)).size === 1 ? before[0] : null;
+            return call(card ? { product_id: card.productId } : {});
         }
         // A product's whole name inside the message: `I want the KODAK AA Alkaline Batteries (24 Pack)`.
         const said = nameWords(raw);

package/dist/index.d.ts

@@ -3,17 +3,20 @@ 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 BuyChoiceDelivery, 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 BuyLatestReply, 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';
 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, stepAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
+export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, type BuyToolModelView, type BuyToolModelCart, type BuyToolGrandTotal, type BuyToolModelProduct, type BuyToolModelStore, type ShownCard, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice, type ReplyAsWrittenOptions } from './texting.js';
+export { appInstructions, APP_INSTRUCTIONS_VERSION, type AppInstructionsOptions } from './app-instructions.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';
 export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS, type TurnStream, type TurnStreamOptions } from './turn-stream.js';
 export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord, type TurnRecordStore } from './turn-record.js';
+export type { BuyLateResults, BuyStoreWait } from './store-wait.js';
+export { planOf, type BuyPlan, type BuyPlanItem, type BuyPlanItemState, type BuyPlanStatus } from './plan.js';

package/dist/index.js

@@ -9,11 +9,13 @@ export { toMessages, messageStream, typingDelay, } from './messages.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, stepAsWritten, withoutCardList, stripLinks, } from './model-view.js';
+export { forModel, grandTotals, forModelError, stepAsWritten, withoutCardList, stripLinks, } from './model-view.js';
 export { asBullets, choiceLines, replyAsWritten, textingStyle, withChoice } from './texting.js';
+export { appInstructions, APP_INSTRUCTIONS_VERSION } from './app-instructions.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';
 export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS } from './turn-stream.js';
 export { TURN_RECOVERY_ON, isTurnId } from './turn-record.js';
+export { planOf } from './plan.js';

package/dist/message.d.ts

@@ -10,6 +10,7 @@ import { type AgentcardEvent } from './verify.js';
  * - `order_failed`: the order failed after the approval, and nothing more happens for that approval.
  * - `order_not_placed_yet`: the shopper approved, and the order is not placed yet.
  * - `order_unconfirmed`: the store's reply to the order was lost, so the order may exist; Agentcard is confirming it.
+ * - `order_placing`: the shopper approved, and Agentcard is placing the order now; one of the order kinds above follows.
  * - `approval_expiring`: the approval link expires soon; `text` carries the link.
  * - `approval_expired`: the approval expired before the shopper answered, and nothing was charged.
  * - `approval_declined`: the shopper declined the approval, and nothing was charged.
@@ -25,7 +26,7 @@ import { type AgentcardEvent } from './verify.js';
  * - `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' | 'cart_ready' | 'cart_needs_input' | 'cart_failed';
+export type PurchaseMessageKind = 'order_placed' | 'order_failed' | 'order_not_placed_yet' | 'order_unconfirmed' | 'order_placing' | '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/model-view.d.ts

@@ -7,7 +7,7 @@
  * `product_links_sent` for the products' store pages, and `link_sent` on each
  * store and `store_links_sent` for the pages of the stores to pick from.
  */
-import type { BuyNextAction } from './client.js';
+import type { BuyCart, BuyNextAction } from './client.js';
 import type { BuyToolProduct, BuyToolResult, BuyToolStatus, BuyToolStore } from './buy-tool.js';
 export interface BuyToolModelCart {
     store: string;
@@ -60,6 +60,22 @@ export interface BuyToolModelStore {
     /** True when the shopper holds this store's page, which `sendLink` delivered beside the reply. */
     link_sent: boolean;
 }
+/**
+ * What every store cart on the table adds up to, in one currency: the stores' totals summed in minor units, each store's
+ * tip, fees and tax counted once as its `total` counts them. `is_estimate` is true when any store's total is an estimate,
+ * and `leaves_out` names what the estimated totals leave out together; null when every store priced its cart.
+ */
+export interface BuyToolGrandTotal {
+    amount: string;
+    /** The sum in the currency's minor unit, such as cents. */
+    amount_cents: number;
+    /** The ISO 4217 code, upper case, or null when Agentcard named none for these carts. */
+    currency: string | null;
+    is_estimate: boolean;
+    leaves_out: string | null;
+    /** How many store carts this total adds up. */
+    stores: number;
+}
 /** The buy tool's answer as the model reads it. */
 export interface BuyToolModelView {
     status: BuyToolStatus;
@@ -78,6 +94,8 @@ export interface BuyToolModelView {
     cart: BuyToolModelCart | null;
     /** Every cart on the table, the newest last, when the shopper is buying from more than one store. */
     carts: BuyToolModelCart[];
+    /** What the carts add up to, one entry per currency, in the order the carts first name it; empty when no cart is on the table. */
+    grand_totals: BuyToolGrandTotal[];
     products: BuyToolModelProduct[];
     approval_expires_at: string | null;
     /**
@@ -197,6 +215,11 @@ export declare function cardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'ur
  * and a place's card is where the shopper reads whether it has room.
  */
 export declare function productCardKey(product: Pick<BuyToolProduct, 'id' | 'ref' | 'url' | 'flight' | 'availability'>): string | null;
+/**
+ * The carts' grand totals, one per currency, summed from each cart's `totalCents`, which already holds its tip, fees and
+ * tax: a display string is never parsed. Carts in two currencies are never added together.
+ */
+export declare function grandTotals(carts: readonly BuyCart[]): BuyToolGrandTotal[];
 /** How long until `iso`, from `now`, as the shopper reads it: `about 24 hours`, `about 15 minutes`, `no longer`, or null. */
 export declare function expiresIn(iso: string | null | undefined, now?: number): string | null;
 /**
@@ -243,9 +266,11 @@ export interface ShownCard {
  * 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. 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
+ * and so does a list line written without a bullet, whole, up to the question on it. The lines set in under a list
+ * line that goes, its details such as `  - ships from London`, go with it, and once the list went, a sentence that only
+ * points back at it, `both are priced in foreign currency`, goes when the cards show another number than it counts.
+ * 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,