@agent-cards/commerce-sdk 0.18.4 → 0.18.6

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/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/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/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/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.4",
+  "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",