@agent-cards/commerce-sdk 0.18.5 → 0.18.6

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,

package/dist/model-view.js

@@ -196,12 +196,42 @@ function cartView(cart) {
 /** What an estimated total leaves out: tax, and shipping or delivery, less what the store's own fee lines already carry
  *  (a 1-800-Flowers estimate holds its Florist Delivery and Sales Tax). Null when the lines carry both. */
 function leftOut(lines) {
+    return leftOutWords(leftOutParts(lines), 1);
+}
+function leftOutParts(lines) {
     const parts = [];
     if (!lines.some((l) => /\btax\b/i.test(l.label)))
         parts.push('tax');
     if (!lines.some((l) => /\b(?:deliver(?:y|ies)?|shipping)\b/i.test(l.label)))
         parts.push('shipping or delivery');
-    return parts.length ? `${parts.join(' and ')}, which the store adds at checkout` : null;
+    return parts;
+}
+function leftOutWords(parts, stores) {
+    return parts.length ? `${parts.join(' and ')}, which the ${stores === 1 ? 'store adds' : 'stores add'} at checkout` : 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 function grandTotals(carts) {
+    const groups = new Map();
+    for (const cart of carts) {
+        const code = typeof cart.currency === 'string' && cart.currency.trim() !== '' ? cart.currency.trim().toUpperCase() : null;
+        groups.set(code, [...(groups.get(code) ?? []), cart]);
+    }
+    return [...groups].map(([currency, group]) => {
+        const cents = group.reduce((sum, cart) => sum + cart.totalCents, 0);
+        const estimates = group.filter((cart) => cart.totalIsEstimate === true);
+        const parts = new Set(estimates.flatMap((cart) => leftOutParts(cart.merchantFeeLines ?? [])));
+        return {
+            amount: money(cents, currency),
+            amount_cents: cents,
+            currency,
+            is_estimate: estimates.length > 0,
+            leaves_out: leftOutWords(['tax', 'shipping or delivery'].filter((part) => parts.has(part)), estimates.length),
+            stores: group.length,
+        };
+    });
 }
 /** How long until `iso`, from `now`, as the shopper reads it: `about 24 hours`, `about 15 minutes`, `no longer`, or null. */
 export function expiresIn(iso, now = Date.now()) {
@@ -267,6 +297,7 @@ export function forModel(result) {
         store_pick: result.store_pick && stripLinks(result.store_pick.store_id) === result.store_pick.store_id
             ? { store_id: result.store_pick.store_id, selected: result.store_pick.selected === true }
             : null,
+        grand_totals: grandTotals(result.carts ?? []),
         ...(yesCarriedView(result) ? { yes_carried: yesCarriedView(result) } : {}),
     };
 }
@@ -393,6 +424,17 @@ const LIST_NUMBER = /(?<!\ba )(?<!\ban )(?:#(\d{1,2})\b|\bnumber (\d{1,2})\b)/i;
  * `there's also ...`, `you could also ...`. One that names a card is the list, whatever the reply recommended before it.
  */
 const MORE_OF_LIST = /^[\s*_"'(]*(?:(?:and|plus|but|or)\s+)?(?:others?\b[^.!?:]{0,40}?\b(?:are|is|include|includes|would be)\b|there(?:'s|’s|\s+is|\s+are)\s+also\b|(?:you|we)\s+(?:could|can|might)\s+also\b)/i;
+/**
+ * A sentence whose subject is the list's items, named by nothing but a pointer back at them and followed by its verb:
+ * `both are ...`, `these ship ...`, `the two cost ...`, `all three come ...`, `they're ...`. A pointer that leads a
+ * noun, `Both Visa and Mastercard are accepted.`, `Both taste and price matter.` or `Either way, ...`, points at no item and never
+ * matches: a word read as the verb but joined to another by `and` or `or` is a noun.
+ */
+const POINTS_BACK = /^[\s*_"'(]*(?:(?:and|but|so|plus)\s+)?(?:both|these|those|either|neither|they|the (?:two|three|four|five)|all (?:two|three|four|five|of (?:them|these|those))|each of (?:them|these|those))(?:\s+of\s+(?:them|these|those))?(?:'re|’re|\s+(?:(?:also|all|only|each|usually|both)\s+)?(?:are|is|were|was|have|has|had|come|comes|ship|ships|cost|costs|run|runs|sell|sells|look|looks|work|works|seem|seems|can|could|will|would|should|might|do|does|offer|offers|include|includes|take|takes|use|uses|weigh|weighs|arrive|arrives|carry|carries|fit|fits|need|needs|sit|sits|taste|tastes|smell|smells|feel|feels|make|makes|go|goes|pair|pairs|brew|brews|roast|roasts|stay|stays|last|lasts|hold|holds|don['’]t|doesn['’]t|didn['’]t|aren['’]t|isn['’]t|won['’]t|can['’]t|wouldn['’]t)\b(?!\s+(?:and|or)\b))/i;
+/** How far a line is set in, a tab counting as four spaces, so a nested list line reads as deeper than its item. */
+function indentOf(line) {
+    return (/^[ \t]*/.exec(line)?.[0] ?? '').replace(/\t/g, '    ').length;
+}
 /** An amount a text gives after a currency sign, such as `$22.89` or `¥1,331`. */
 const AMOUNT = /[$£€¥]\s?(\d{1,3}(?:,\d{3})+|\d+)(\.\d+)?/g;
 /** Words that tell no product from another: a card's brand or its distinctive words are never one of these. */
@@ -629,9 +671,11 @@ function inlineList(line, cards) {
  * 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,
@@ -653,10 +697,14 @@ export function withoutCardList(reply, cardNames) {
     };
     // The numbers the dropped list gave, so a number of a product's own, `a #2 Phillips head`, keeps its sentence.
     const numbers = new Set();
+    // How many items of a list written inline went: with the list lines that went, the count a pointer such as `these` means.
+    let inlineGone = 0;
+    // The lines whose inline list went whole: the lines set in under one describe its items, and go with them.
+    const inlineEmptied = new Set();
     // A list a line writes inline goes the way a list of lines does: each item that names a card, and the sentence that
     // led into the list once every item went. An item for a product no card shows stays, with the lead, and so does a
     // list that opens the line, `1) a mug; 2) a candle; 3) a soap box`, item by item rather than as one list line.
-    const unlisted = (line) => {
+    const unlisted = (line, index) => {
         const list = inlineList(line, cards);
         const gone = list?.items.map((item) => cardsNamed(item.body, cards, true).length > 0) ?? [];
         if (!list || !gone.some(Boolean))
@@ -665,6 +713,9 @@ export function withoutCardList(reply, cardNames) {
             if (gone[k] && item.number !== null)
                 numbers.add(item.number);
         });
+        inlineGone += gone.filter(Boolean).length;
+        if (gone.every(Boolean))
+            inlineEmptied.add(index);
         const after = line.slice(list.end).trimStart();
         if (gone.every(Boolean))
             return `${line.slice(0, list.lead).trimEnd()} ${after}`.trim();
@@ -672,22 +723,37 @@ export function withoutCardList(reply, cardNames) {
         const close = /[.!?]$/.test(left[left.length - 1]) ? '' : '.';
         return [line.slice(0, list.items[0].start).trimEnd(), `${left.join('; ')}${close}`, after].filter((part) => part !== '').join(' ');
     };
-    const lines = reply.split('\n').map(unlisted);
-    const kind = lines.map((line) => {
-        if (LIST_ITEM.test(line))
-            return cardsNamed(line.replace(LIST_ITEM, ''), cards, true).length > 0 ? 'item' : 'kept';
-        return opensCard(line) ? 'named' : 'kept';
+    const written = reply.split('\n');
+    const lines = written.map(unlisted);
+    // A line set in deeper than a list line that names a card is that item's detail, such as `  - ships from London`
+    // under `- Square Mile Red Brick, £13.50`: it goes with its item (`under`), since what it describes is the card.
+    let item = null;
+    const kind = lines.map((line, i) => {
+        if (inlineEmptied.has(i)) {
+            // A list nested under an item already dropped keeps that item's depth, so the lines after it still go with their item.
+            const at = indentOf(written[i]);
+            if (item === null || at <= item)
+                item = at;
+            return 'kept';
+        }
+        if (line.trim() === '')
+            return 'kept';
+        if (item !== null && indentOf(line) > item)
+            return 'under';
+        const of = LIST_ITEM.test(line) ? (cardsNamed(line.replace(LIST_ITEM, ''), cards, true).length > 0 ? 'item' : 'kept') : opensCard(line) ? 'named' : 'kept';
+        item = of === 'kept' ? null : indentOf(line);
+        return of;
     });
     const dropped = kind.map((of) => of !== 'kept');
     lines.forEach((line, i) => {
-        const number = dropped[i] ? Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1]) : NaN;
+        const number = dropped[i] && kind[i] !== 'under' ? Number(/^\s*(\d{1,2})[.)]\s/.exec(line)?.[1]) : NaN;
         if (Number.isInteger(number))
             numbers.add(number);
     });
     // The list a line leads into: the lines from the next one with words on it to the first that is not a list line, so a
     // question on the line after the last item, `Which one?`, is no part of the list. A blank line between two list lines
     // is no end of it, as toMessages reads one, so a list that keeps an item past the blank keeps its lead.
-    const listLine = (j) => LIST_ITEM.test(lines[j]) || kind[j] === 'named';
+    const listLine = (j) => LIST_ITEM.test(lines[j]) || kind[j] === 'named' || kind[j] === 'under';
     const listAfter = (line) => {
         const start = lines.findIndex((after, j) => j > line && after.trim() !== '');
         if (start === -1)
@@ -709,8 +775,20 @@ export function withoutCardList(reply, cardNames) {
     };
     const named = new Set();
     const kept = [];
+    // Once a list went, a sentence that only points back at its items, `both are priced in foreign currency` or `these ship
+    // free`, reads against the cards. It stays when it counts what the cards show, `both` beside two cards, and goes when the
+    // cards show another number, as eight cards beside `both` do: the shopper cannot tell which two it means.
+    const listed = kind.filter((of) => of === 'item' || of === 'named').length + inlineGone;
+    const pointsElsewhere = (sentence) => {
+        const pointer = POINTS_BACK.exec(sentence);
+        if (!pointer || listed === 0)
+            return false;
+        const counted = /\b(both|either|neither|two|three|four|five)\b/i.exec(pointer[0])?.[1]?.toLowerCase();
+        const count = counted ? { both: 2, either: 2, neither: 2, two: 2, three: 3, four: 4, five: 5 }[counted] : listed;
+        return count !== cards.length;
+    };
     lines.forEach((line, i) => {
-        if (kind[i] === 'item')
+        if (kind[i] === 'item' || kind[i] === 'under')
             return;
         let text = line;
         // The line that leads into a list whose every line went loses the sentence that leads in: `Two I'd suggest:` or
@@ -727,6 +805,8 @@ export function withoutCardList(reply, cardNames) {
             if (place && numbers.has(Number(place[1] ?? place[2])))
                 return [];
             const found = cardsNamed(sentence, cards, false);
+            if (found.length === 0 && !ASKS.test(sentence) && !/:\s*$/.test(sentence) && pointsElsewhere(sentence))
+                return [];
             if (kind[i] === 'named') {
                 const card = found.length > 0 || opensCard(sentence);
                 asked ||= ASKS.test(sentence);

package/dist/plan.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A checkout plan on a purchase answer: the items a shopper chose to book together, booked in the order they depend on each
+ * other on one approval, such as a trip's flight first, then its hotel and car. The same object rides `plan.updated`, so a
+ * tracker redraws from either. Null on an answer with no plan, and on an older API.
+ */
+export type BuyPlanStatus = 'preparing' | 'running' | 'done' | 'partly_done' | 'stopped';
+export type BuyPlanItemState = 'draft' | 'quoted' | 'approved' | 'booking' | 'confirmed' | 'pending' | 'needs_input' | 'failed' | 'skipped' | 'cancelled';
+export interface BuyPlanItem {
+    /** The item's key in its plan: `flight`, `hotel`, `car`. */
+    key: string;
+    kind: string;
+    state: BuyPlanItemState;
+    name: string;
+    /** What the shopper pays for it: the confirmed price once booked, the quote before. */
+    price_cents: number | null;
+    /** A changed price waiting for the shopper's answer, or null. */
+    asked_cents: number | null;
+    /** The supplier's confirmation number once booked. */
+    confirmation: string | null;
+    /** The keys of the items it books after. */
+    depends_on: string[];
+    /** Why it waits or did not book, such as `price_changed` or `approval_required`, or null. */
+    reason: string | null;
+}
+export interface BuyPlan {
+    id: string;
+    status: BuyPlanStatus;
+    /** Moves on every change: keep the highest one seen. */
+    version: number;
+    currency: string;
+    total_cents: number;
+    charged_cents: number;
+    /** When the items waiting on a paused one are let go, or null. */
+    hold_until: string | null;
+    items: BuyPlanItem[];
+}
+/**
+ * The plan an answer carries, or null when it carries none or one this version cannot read: a status or an item state this
+ * version does not know, a missing total, or an item it cannot read. A tracker never shows a guessed state or a zero total.
+ */
+export declare function planOf(value: unknown): BuyPlan | null;

package/dist/plan.js

@@ -0,0 +1,34 @@
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const text = (v) => (typeof v === 'string' ? v : null);
+const STATUSES = new Set(['preparing', 'running', 'done', 'partly_done', 'stopped']);
+const STATES = new Set(['draft', 'quoted', 'approved', 'booking', 'confirmed', 'pending', 'needs_input', 'failed', 'skipped', 'cancelled']);
+function itemOf(i) {
+    if (!isRecord(i) || !text(i.key) || !text(i.state) || !STATES.has(i.state))
+        return null;
+    return {
+        key: i.key, kind: text(i.kind) ?? '', state: i.state, name: text(i.name) ?? '',
+        price_cents: num(i.price_cents), asked_cents: num(i.asked_cents), confirmation: text(i.confirmation),
+        depends_on: Array.isArray(i.depends_on) ? i.depends_on.filter((d) => typeof d === 'string') : [], reason: text(i.reason),
+    };
+}
+/**
+ * The plan an answer carries, or null when it carries none or one this version cannot read: a status or an item state this
+ * version does not know, a missing total, or an item it cannot read. A tracker never shows a guessed state or a zero total.
+ */
+export function planOf(value) {
+    if (!isRecord(value) || !text(value.id) || !Array.isArray(value.items) || !STATUSES.has(text(value.status) ?? ''))
+        return null;
+    const total = num(value.total_cents);
+    const charged = num(value.charged_cents);
+    const version = num(value.version);
+    if (total === null || charged === null || version === null)
+        return null;
+    const items = value.items.map(itemOf);
+    if (items.some((i) => i === null))
+        return null;
+    return {
+        id: value.id, status: value.status, version, currency: text(value.currency) ?? 'USD',
+        total_cents: total, charged_cents: charged, hold_until: text(value.hold_until), items: items,
+    };
+}

package/dist/store-wait.d.ts

@@ -0,0 +1,27 @@
+import type { BuyToolProduct } from './buy-tool.js';
+/**
+ * What happens to a store that answers after the reply: `stream` sends its cards after the reply, in the same turn, as
+ * the card events every streamed turn carries; `hold` keeps them out of the turn, so the reply is the turn's last word.
+ */
+export type BuyLateResults = 'stream' | 'hold';
+/** The store wait of a tool or a turn. */
+export interface BuyStoreWait {
+    /** How long, in milliseconds, the reply waits for store searches before Agentcard writes it. */
+    storeWaitMs?: number;
+    /** What happens to a store that answers after the reply. */
+    lateResults?: BuyLateResults;
+}
+/** The request fields a store wait sends, none when it names nothing. */
+export interface BuyStoreWaitFields {
+    store_wait_ms?: number;
+    late_results?: BuyLateResults;
+}
+/** Checks a store wait passed to `buyTool` (`where` is empty) or to a turn (`where` reads ' to the turn'), and throws a TypeError for one that cannot work. */
+export declare function checkStoreWait(wait: BuyStoreWait, where?: string): void;
+/** The fields a request carries for a turn's store wait: the turn's own, else the tool's. */
+export declare function storeWaitFields(turn: BuyStoreWait, tool: BuyStoreWait): BuyStoreWaitFields;
+/**
+ * The answer's products with the cards of a store that answered after the reply added at the end, each once: the answer
+ * can list them already, when the turn's last word came after them, and a late card it lists is left as the answer has it.
+ */
+export declare function withLateCards(products: readonly BuyToolProduct[], late: readonly BuyToolProduct[]): BuyToolProduct[];

package/dist/store-wait.js

@@ -0,0 +1,41 @@
+/**
+ * How long a reply waits for store searches, and what happens to a store that answers after it: the `storeWaitMs` and
+ * `lateResults` options of `buyTool` and `buy.turn`, sent on every request as `store_wait_ms` and `late_results`. Left
+ * out, nothing is sent and Agentcard keeps its own wait.
+ */
+import { pickId, productCardKey } from './model-view.js';
+/** Checks a store wait passed to `buyTool` (`where` is empty) or to a turn (`where` reads ' to the turn'), and throws a TypeError for one that cannot work. */
+export function checkStoreWait(wait, where = '') {
+    const ms = wait.storeWaitMs;
+    if (ms !== undefined && (typeof ms !== 'number' || !Number.isInteger(ms) || ms < 0)) {
+        throw new TypeError(`Pass storeWaitMs${where} as a whole number of milliseconds, 0 or more, or leave it out.`);
+    }
+    const late = wait.lateResults;
+    if (late !== undefined && late !== 'stream' && late !== 'hold') {
+        throw new TypeError(`Pass lateResults${where} as 'stream' or 'hold', or leave it out.`);
+    }
+}
+/** The fields a request carries for a turn's store wait: the turn's own, else the tool's. */
+export function storeWaitFields(turn, tool) {
+    const ms = turn.storeWaitMs ?? tool.storeWaitMs;
+    const late = turn.lateResults ?? tool.lateResults;
+    return { ...(ms !== undefined ? { store_wait_ms: ms } : {}), ...(late !== undefined ? { late_results: late } : {}) };
+}
+/**
+ * The answer's products with the cards of a store that answered after the reply added at the end, each once: the answer
+ * can list them already, when the turn's last word came after them, and a late card it lists is left as the answer has it.
+ */
+export function withLateCards(products, late) {
+    // A product with no link-free id is told apart by its page, so two stores' offers of one title stay two.
+    const keyOf = (product) => pickId(product) ?? productCardKey(product) ?? `name:${product.name}`;
+    const held = new Set(products.map(keyOf));
+    const added = [];
+    for (const product of late) {
+        const key = keyOf(product);
+        if (held.has(key))
+            continue;
+        held.add(key);
+        added.push(product);
+    }
+    return [...products, ...added];
+}

package/dist/trip-ask.d.ts

@@ -13,7 +13,7 @@
  * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
  *
  * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
- * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * for a trip ask with no dates or airport, and leads with a whole trip when the shopper asks what it can do for travel. Off: the
  * description is the text it was before, word for word.
  */
 export declare const TRAVEL: {

package/dist/trip-ask.js

@@ -13,7 +13,7 @@
  * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
  *
  * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
- * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * for a trip ask with no dates or airport, and leads with a whole trip when the shopper asks what it can do for travel. Off: the
  * description is the text it was before, word for word.
  */
 export const TRAVEL = { goStraight: true, inCapabilities: true };
@@ -52,9 +52,9 @@ export function withoutTripVerb(text) {
     return TRAVEL.goStraight && isTripAsk(text) ? text.replace(TRIP_VERB, '') : text;
 }
 const OPENING_LINE = 'Buy what this shopper asks for at real stores.';
-const TRAVEL_LINES = 'You also plan and book trips: flights and hotels. When the shopper asks to plan a trip, or for flights or a hotel, such as "help me plan a trip to Loreto" or "flights and hotels in loreto", call this tool with their words, even when they name no dates and no place they leave from: Agentcard asks them for what it needs.';
-const CAPABILITY_END = 'so name those, and no other store unless a result showed it.';
-const CAPABILITY_TRAVEL = 'Name flights and hotels for a trip among the kinds of things you can do.';
+const TRAVEL_LINES = 'You also plan and book trips: flights, hotels and rental cars. When the shopper asks to plan a trip, or for flights or a hotel, such as "help me plan a trip to Loreto" or "flights and hotels in loreto", call this tool with their words, even when they name no dates and no place they leave from: Agentcard asks them for what it needs.';
+const CAPABILITY_END = 'Name no other store unless a result showed it.';
+const CAPABILITY_TRAVEL = 'Name whole trips among the kinds of things you can do. When the shopper asks what you can do for travel, lead with planning a whole trip, the flights, a hotel and a rental car together, then name the parts they can book on their own: flights, hotels and rental cars.';
 /** The tool's description with travel named, when `inCapabilities` is on (or `on` says so); the description as given when off. */
 export function withTravel(description, on = TRAVEL.inCapabilities) {
     if (!on)

package/examples/anthropic.mjs

@@ -6,7 +6,7 @@
 // Sandbox credentials place no real order. SHOPPER_ID is your own id for the shopper you play.
 import readline from 'node:readline';
 import Anthropic from '@anthropic-ai/sdk';
-import { AgentcardClient, buyTool } from '@agent-cards/commerce-sdk';
+import { AgentcardClient, appInstructions, buyTool } from '@agent-cards/commerce-sdk';
 
 const agentcard = new AgentcardClient({
   clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
@@ -33,7 +33,8 @@ for await (const line of terminal) {
   const runner = anthropic.beta.messages.toolRunner({
     model: 'claude-opus-5-5',
     max_tokens: 16000,
-    system: 'You are a shopping assistant. Buy what the shopper asks for with the buy tool.',
+    // Agentcard's recommended instructions: what it can do and how to use the buy tool. A terminal shows plain text.
+    system: appInstructions({ markdown: false }),
     tools: [buy],
     messages: [...messages, { role: 'user', content: said }],
     // When a safety classifier declines a request, Anthropic answers it with a fallback model instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.5",
+  "version": "0.18.6",
   "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",
@@ -27,11 +27,12 @@
   },
   "scripts": {
     "_comment_build": "Zero runtime dependencies: node:crypto is the one import, and the buy tool calls the global fetch. TypeScript is pinned, not installed, as in @agent-cards/sdk. types/node.d.ts declares the two node:crypto functions the source calls, so the build needs no @types package and the published declarations name no Node type; FetchLike names AbortSignal, which every runtime with fetch declares.",
-    "build": "npx -y -p typescript@5.9.3 tsc",
+    "build": "node scripts/app-instructions.mjs && npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
     "test": "pnpm build && node --test test/*.test.mjs",
     "verify:pack": "node scripts/verify-pack.mjs",
-    "_comment_pack": "verify:pack lists what npm would publish (npm pack --dry-run) and fails on a missing manifest target, README or example, or on a test, source, shim or build-cache file; then it loads the built root and checks the names the README imports. The release workflow runs it after the build."
+    "_comment_pack": "verify:pack lists what npm would publish (npm pack --dry-run) and fails on a missing manifest target, README or example, or on a test, source, shim or build-cache file; then it loads the built root and checks the names the README imports. The release workflow runs it after the build.",
+    "_comment_instructions": "The build first copies the instructions for an app's own model (appInstructions) from apps/agent-voice/kb/app.md into src/app-instructions.generated.ts, which git ignores, so the published text always matches the voice package at the commit it was built from."
   },
   "keywords": [
     "agentcard",