@agent-cards/commerce-sdk 0.1.0 → 0.5.0

package/dist/buy-tool.js

@@ -25,6 +25,8 @@
 import { AgentcardApiError, AgentcardClient, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
 import { forModel, forModelError, money, shownProducts } from './model-view.js';
+import { toMessages } from './messages.js';
+import { ackAt, isNewRequest, nextTemplate } from './ack.js';
 /** The pause before the one read that follows a placement Agentcard is still finishing. */
 const PLACEMENT_WAIT_MS = 12_000;
 /** After a turn that outlived Agentcard's budget: one read every 5 seconds, for at most a minute. */
@@ -40,6 +42,10 @@ const RESUME_SKEW_MS = 2 * 60_000;
 const STOPPED_ORDER = new Set(['failed', 'cancelled']);
 /** The refusals a confirm gets once the order took the cart, or while the placement still runs. */
 const AFTER_PLACEMENT = new Set(['nothing_to_confirm', 'conversation_closed', 'turn_in_progress']);
+/** How long Agentcard has to answer before the instant reply goes out. */
+const ACK_DELAY_MS = 1_500;
+/** A call that starts this soon after the last one ended belongs to the same model turn, which gets one instant reply. */
+const SAME_TURN_MS = 15_000;
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
 const CARD_NEEDED = 'The shopper adds a card from a Vault link before Agentcard can buy for them.';
 const STILL_PLACING = 'The shopper approved, and the order is still going through.';
@@ -51,6 +57,18 @@ const ANSWER_LATE = "Agentcard's answer took too long to come back. Call this to
 const CART_CHANGED = 'The cart changed since the shopper saw it. Show the shopper the cart as it stands now.';
 const NOTHING_TO_CONFIRM = 'There is no cart to confirm yet. Ask the shopper what they want.';
 const ADDRESS_CHANGED = 'The delivery address changed since this cart was built. Ask for the cart again, and Agentcard prices it for the new address.';
+const PICK_GONE = "The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.";
+/**
+ * The pick as a later read of the conversation shows it: a pick the early answer found missing is in
+ * the cart once a line carries its catalog id, as its product id or, for a retail product whose id is
+ * its store page, as its page. A pick already in the cart, or none, stays as it was.
+ */
+function pickAfter(pick, carts) {
+    if (!pick || pick.in_cart)
+        return pick;
+    const held = carts.some((c) => c.items.some((line) => line.product_id === pick.product_id || line.url === pick.product_id));
+    return held ? { ...pick, in_cart: true } : pick;
+}
 function hashesOf(cart, carts) {
     return [...new Set([cart?.hash, ...carts.map((c) => c.hash)].filter((h) => typeof h === 'string' && h !== ''))];
 }
@@ -59,10 +77,12 @@ function productsOf(turn) {
         .filter((item) => item.name)
         .map((item) => ({
         id: item.id,
+        ref: item.ref,
         name: item.name,
         priceCents: item.priceCents,
         currency: item.currency,
         imageUrl: item.image_url,
+        ...(item.flight ? { flight: item.flight } : {}),
         store: item.store?.name ?? item.store?.id ?? turn.catalog?.merchant_name ?? null,
         url: item.url ?? null,
         linkSent: false,
@@ -79,6 +99,7 @@ function answerOf(turn) {
     return {
         status: 'needs_input',
         reply: turn.reply,
+        messages: [],
         cart: turn.cart,
         carts: turn.carts,
         products: productsOf(turn),
@@ -90,13 +111,61 @@ function answerOf(turn) {
         order_id: turn.order_id,
         decline_code: turn.decline_code,
         error_code: turn.error_code,
+        next_action: turn.next_action,
+        pick: turn.pick,
         hashes: hashesOf(turn.cart, turn.carts),
         envelope: turn.raw,
     };
 }
+/**
+ * The answer that waits on the shopper's card, when the turn carries Agentcard's add-card link: a
+ * checkout refused on an empty vault (`vault_unavailable`), or the agent made the link while it
+ * asked. The status beside it does not decide: the link is the one way forward either way, and the
+ * reply has every link taken out. Null when the turn carries no link, or placed an order.
+ */
+function needsCardOf(turn, answer) {
+    // Agentcard named another step first: the card waits until that one is done.
+    if (turn.next_action && turn.next_action !== 'add_card')
+        return null;
+    if (!turn.add_card_url || turn.status === 'order_placed' || turn.status === 'partially_placed' || turn.status === 'needs_approval')
+        return null;
+    const refused = turn.status === 'declined';
+    // A refusal with another code is about something other than a card, and keeps its own status.
+    if (refused && turn.decline_code !== 'vault_unavailable')
+        return null;
+    if (!refused && turn.decline_code && turn.decline_code !== 'vault_unavailable')
+        return null;
+    return { ...answer, status: 'needs_card', links: [...answer.links, { kind: 'vault', url: turn.add_card_url, expiresAt: turn.add_card_expires_at }] };
+}
+/**
+ * The answer with only the link of the step the shopper takes now, when Agentcard names one
+ * (`next_action`): the Vault link waits for `add_card`, the approval link for `approve`. A store login
+ * link and product pages are not steps, so they stay. An answer that names no step keeps every link.
+ */
+function onlyNextStepLinks(result, next) {
+    if (!next)
+        return result;
+    const links = result.links.filter((link) => (link.kind === 'vault' ? next === 'add_card' : link.kind === 'approval' ? next === 'approve' : true));
+    return links.length === result.links.length ? result : { ...result, links };
+}
+/**
+ * The answer's `messages`, read once its `reply` is final: the messages Agentcard sent while the reply
+ * is still Agentcard's own, else the reply the tool wrote, each cut at its blank lines.
+ */
+function withMessages(result, turn) {
+    const sent = turn && result.reply === turn.reply && turn.messages.length > 0 ? turn.messages : [result.reply];
+    return { ...result, messages: sent.flatMap(toMessages) };
+}
 /** A purchase answer, read for its status. A status Agentcard adds later reads as `needs_input`. */
 function resultOfTurn(turn) {
+    return onlyNextStepLinks(resultOfStatus(turn), turn.next_action);
+}
+/** A purchase answer, read for its status, with every link the answer carries. */
+function resultOfStatus(turn) {
     const answer = answerOf(turn);
+    const card = needsCardOf(turn, answer);
+    if (card)
+        return card;
     switch (turn.status) {
         case 'order_placed':
         case 'partially_placed':
@@ -116,10 +185,6 @@ function resultOfTurn(turn) {
                     shopper_need_not_reply: turn.placement_announced === true,
                 };
             }
-            // A shopper with no card gets the add-card link checkout made. Every other reason for this code is not about a card.
-            if (turn.decline_code === 'vault_unavailable' && turn.add_card_url) {
-                return { ...answer, status: 'needs_card', links: [...answer.links, { kind: 'vault', url: turn.add_card_url, expiresAt: turn.add_card_expires_at }] };
-            }
             return { ...answer, status: 'declined' };
         default:
             return answer;
@@ -132,6 +197,7 @@ function resultOfRefusal(error) {
     const answer = (reply, carts) => ({
         status: 'needs_input',
         reply,
+        messages: [],
         cart: carts.at(-1) ?? null,
         carts,
         products: [],
@@ -143,6 +209,8 @@ function resultOfRefusal(error) {
         order_id: null,
         decline_code: null,
         error_code: error.code,
+        next_action: null,
+        pick: null,
         hashes: hashesOf(null, carts),
         envelope: error.body,
     });
@@ -154,6 +222,8 @@ function resultOfRefusal(error) {
         return answer(NOTHING_TO_CONFIRM, []);
     if (error.code === 'turn_in_progress')
         return answer(STILL_WORKING, []);
+    if (error.code === 'pick_not_found')
+        return answer(PICK_GONE, []);
     return null;
 }
 /** A shopper Agentcard has not connected to this company yet: the Vault link where they connect and add a card. */
@@ -161,6 +231,7 @@ function needsCard(link, body) {
     return {
         status: 'needs_card',
         reply: CARD_NEEDED,
+        messages: [],
         cart: null,
         carts: [],
         products: [],
@@ -172,6 +243,8 @@ function needsCard(link, body) {
         order_id: null,
         decline_code: null,
         error_code: 'user_not_connected',
+        next_action: 'add_card',
+        pick: null,
         hashes: [],
         envelope: body,
     };
@@ -249,6 +322,63 @@ export function buyTool(options) {
     if (typeof wait !== 'function')
         throw new TypeError('Pass wait as a function of milliseconds that resolves after the pause.');
     const who = client.company ? { externalUserId } : {};
+    if (o.onWorking !== undefined && typeof o.onWorking !== 'function')
+        throw new TypeError('Pass onWorking as a function that sends the shopper a message.');
+    if (o.ack !== undefined && o.ack !== false && typeof o.ack !== 'function')
+        throw new TypeError('Pass ack as false, or as a function that writes the instant reply from the ask.');
+    const ackDelayMs = o.ackDelayMs ?? ACK_DELAY_MS;
+    if (typeof ackDelayMs !== 'number' || !Number.isFinite(ackDelayMs) || ackDelayMs < 0)
+        throw new TypeError('Pass ackDelayMs as a number of milliseconds, 0 or more.');
+    const onWorking = o.ack === false ? undefined : o.onWorking;
+    const writeAck = typeof o.ack === 'function' ? o.ack : null;
+    /** Calls running now, when the last one ended, whether this turn's instant reply is taken, and the template it used last. */
+    let running = 0;
+    let lastEndedAt = Number.NEGATIVE_INFINITY;
+    let turnAcked = false;
+    let lastTemplate = -1;
+    /** This turn's instant reply while it is being sent: every call of the turn waits for it before it hands over a link. */
+    let ackOut = null;
+    /**
+     * Holds the instant reply for a new request until `ackDelayMs` passes. `cancel` stops one that has
+     * not gone out, and frees the turn's reply for a later call.
+     */
+    const holdAck = (ask) => {
+        if (!onWorking || turnAcked || !isNewRequest(ask))
+            return null;
+        turnAcked = true;
+        let held = true;
+        const timer = setTimeout(() => {
+            held = false;
+            let text;
+            if (writeAck) {
+                try {
+                    text = writeAck(ask);
+                }
+                catch {
+                    text = null;
+                }
+            }
+            else {
+                lastTemplate = nextTemplate(lastTemplate);
+                text = ackAt(lastTemplate, ask);
+            }
+            if (typeof text !== 'string' || text.trim() === '') {
+                turnAcked = false;
+                return;
+            }
+            const message = text.trim();
+            ackOut = Promise.resolve().then(() => onWorking(message)).catch(() => { });
+        }, ackDelayMs);
+        return {
+            cancel: () => {
+                if (!held)
+                    return;
+                held = false;
+                clearTimeout(timer);
+                turnAcked = false;
+            },
+        };
+    };
     /** One read of the conversation, or null when it fails: a read only ever improves an answer the tool already has. */
     const read = async (conversationId) => {
         try {
@@ -267,6 +397,7 @@ export function buyTool(options) {
                 status: 'order_placed',
                 reply: `The ${order.merchant || 'store'} order went through, order number ${order.orderId}.`,
                 links: [],
+                next_action: null,
                 order_id: order.orderId,
                 conversation_id: conversationId,
             };
@@ -280,6 +411,7 @@ export function buyTool(options) {
             links: [],
             order_id: order.orderId,
             decline_code: `order_${order.status}`,
+            next_action: null,
             shopper_need_not_reply: false,
             conversation_id: conversationId,
         };
@@ -291,6 +423,7 @@ export function buyTool(options) {
         reply: refusal.message || `${NOT_PLACED} The ${refusal.merchant || 'store'} answered ${refusal.code}.`,
         links: [],
         decline_code: refusal.code,
+        next_action: null,
         shopper_need_not_reply: false,
     });
     /**
@@ -306,7 +439,7 @@ export function buyTool(options) {
         const refusal = conversation && checkoutRefusal(conversation);
         if (refusal)
             return refusedCheckout(base, refusal);
-        return { ...base, status: 'placing', reply: STILL_PLACING, links: [] };
+        return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null };
     };
     /**
      * What a finished turn's checkout left besides an order, which `placedOrderOf`
@@ -324,6 +457,7 @@ export function buyTool(options) {
                 reply: last.message || CARD_NEEDED,
                 links: [{ kind: 'vault', url: last.add_card_url, expiresAt: last.add_card_expires_at }],
                 decline_code: last.decline_code,
+                next_action: 'add_card',
                 shopper_need_not_reply: false,
                 envelope: conversation.raw,
             };
@@ -335,13 +469,14 @@ export function buyTool(options) {
         }
         const announced = last.placement_announced === true;
         if (last.approval_in_progress === true)
-            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], shopper_need_not_reply: announced };
+            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null, shopper_need_not_reply: announced };
         return {
             ...base,
             status: 'approval_sent',
             reply: APPROVAL_WAITING,
             links: [{ kind: 'approval', url: last.approval_url, expiresAt: last.approval_expires_at }],
             approval_expires_at: last.approval_expires_at,
+            next_action: 'approve',
             shopper_need_not_reply: announced,
             envelope: conversation.raw,
         };
@@ -399,6 +534,10 @@ export function buyTool(options) {
                     carts: conversation.carts,
                     hashes: conversation.carts.map((c) => c.hash),
                     error_code: newest ? null : base.error_code,
+                    // A read replaced the answer the step was named for, and names no step of its own: the reply asks.
+                    next_action: null,
+                    // The early answer judged the pick before the turn finished adding it.
+                    pick: pickAfter(base.pick, conversation.carts),
                     envelope: conversation.raw,
                 };
                 if (!conversation.turn_in_progress)
@@ -408,7 +547,7 @@ export function buyTool(options) {
             }
         }
         if (placing)
-            return { ...base, status: 'placing', reply: STILL_PLACING, links: [] };
+            return { ...base, status: 'placing', reply: STILL_PLACING, links: [], next_action: null };
         // A minute that ends with the turn still running returns what the last read showed, a new cart as
         // ready although no read handed it back: nothing better exists by then, and a confirm that misses it
         // is refused, never placed on another cart.
@@ -479,7 +618,7 @@ export function buyTool(options) {
         for (const [url, product] of pages) {
             if (!before.has(url)) {
                 try {
-                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, expiresAt: null });
+                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, imageUrl: product.imageUrl, expiresAt: null });
                 }
                 catch {
                     continue;
@@ -515,22 +654,43 @@ export function buyTool(options) {
         const ask = input.ask.trim();
         if (!confirm && ask === '')
             throw new TypeError("Put the shopper's words in ask.");
+        // A pick chooses from the products this conversation showed: never on a confirm, and never on a new order, which shows none yet.
+        const pick = !confirm && !input.new_order && input.product_id ? { product_id: input.product_id } : null;
         const body = {
             resume: true,
             ...(confirm ? { confirm: true, payment_source: 'vault' } : { ask }),
             ...(input.new_order ? { new_order: true } : {}),
+            ...(pick ? { pick } : {}),
             ...(o.deliveryAddress ? { delivery_address: o.deliveryAddress } : {}),
             ...(client.company ? { external_user_id: externalUserId } : {}),
         };
-        let turn = null;
-        let refusal;
+        // A call that starts while another runs, or right after one ended, is the model working through the same turn.
+        if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
+            turnAcked = false;
+            ackOut = null;
+        }
+        running += 1;
+        // A pick adds a product the shopper already saw, so no "looking for" reply goes out, as for "the first one".
+        const ack = confirm || pick ? null : holdAck(ask);
         try {
-            turn = await client.buy(body);
+            let turn = null;
+            let refusal;
+            try {
+                turn = await client.buy(body);
+            }
+            catch (error) {
+                refusal = error;
+            }
+            ack?.cancel();
+            const settled = turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt);
+            await ackOut;
+            return await deliver(withMessages(settled, turn));
         }
-        catch (error) {
-            refusal = error;
+        finally {
+            ack?.cancel();
+            running -= 1;
+            lastEndedAt = Date.now();
         }
-        return deliver(turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt));
     };
     /** Checks the model's input, with every link taken out of a refusal. */
     const parse = (input) => {

package/dist/client.d.ts

@@ -51,6 +51,13 @@ export interface BuyRequest {
     resume?: true;
     /** Drop the cart on the table and start a new order. */
     new_order?: true;
+    /**
+     * The product the shopper picked from the last search's `catalog.items`, by its `id` or its `ref`:
+     * Agentcard adds exactly that item, with no new search. Goes with an `ask`, never with `confirm` or `new_order`.
+     */
+    pick?: {
+        product_id: string;
+    };
     payment_source?: 'vault';
     delivery_address?: BuyDeliveryAddress;
     external_user_id?: string;
@@ -87,8 +94,22 @@ export interface BuyCart {
     hash: string;
 }
 /** A product a search found. `priceCents` is in the minor unit of `currency`, the store's ISO 4217 code. */
+/** Supplier facts only. Missing facts stay null; fare cabin does not establish segment cabins. */
+export interface BuyFlightItinerary {
+    fareCabinClass?: string | null;
+    legs: Array<{
+        origin: string | null;
+        destination: string | null;
+        departureAt: string | null;
+        arrivalAt: string | null;
+        cabinClasses: Array<string | null>;
+    }>;
+}
 export interface BuyCatalogItem {
+    flight?: BuyFlightItinerary;
     id: string;
+    /** The item's id with no link in it, which `pick.product_id` takes as it takes `id`; null from an older API. */
+    ref: string | null;
     name: string | null;
     priceCents: number | null;
     /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
@@ -104,11 +125,25 @@ export interface BuyCatalog {
     merchant_name: string;
     items: BuyCatalogItem[];
 }
+/** The product a `pick` named, by its catalog id and ref, and whether the cart now holds it. */
+export interface BuyPick {
+    product_id: string;
+    ref: string | null;
+    in_cart: boolean;
+}
 export interface BuyPaymentSource {
     source: string;
     brand: string | null;
     last4: string | null;
 }
+/**
+ * The one thing the shopper does next, as Agentcard names it, in the order a purchase asks for them:
+ * `shipping_details` (a shipping address and phone), `guest_details` (a name, email and phone for a
+ * booking), `add_card` (a card in their Vault), `confirm` (their yes to the cart), `verification_code`
+ * (the code a booking texted them), then `approve` (the approval link). A value this version does
+ * not know reads as null.
+ */
+export type BuyNextAction = 'shipping_details' | 'guest_details' | 'add_card' | 'confirm' | 'verification_code' | 'approve';
 /** One turn's answer, every field read for its type; a field an older API does not send reads as null. */
 export interface BuyTurn {
     conversation_id: string;
@@ -133,11 +168,15 @@ export interface BuyTurn {
     placement_announced: boolean | null;
     approval_expires_at: string | null;
     approval_in_progress: boolean | null;
+    /** The one step the shopper takes next, or null when nothing waits on them or Agentcard named none. */
+    next_action: BuyNextAction | null;
     /** The page where the shopper signs in to a store's own account before Agentcard can buy there. */
     store_login_url: string | null;
     store_login_expires_at: string | null;
     /** The store that page signs in to. */
     store_login_merchant_name: string | null;
+    /** The product this turn's `pick` named, and whether the cart holds it; null for a turn without one. */
+    pick: BuyPick | null;
     /** The answer as Agentcard sent it. */
     raw: Record<string, unknown>;
 }
@@ -189,7 +228,7 @@ export interface VaultLink {
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
  * (`user_not_connected`, `external_user_id_ambiguous`, `turn_in_progress`,
- * `user_id_mismatch`), one read from the shape of the answer
+ * `user_id_mismatch`, `pick_not_found`), one read from the shape of the answer
  * (`cart_changed`, `nothing_to_confirm`, `conversation_closed`,
  * `conversation_not_found`), or the client's (`unreachable`, `timeout`,
  * `oauth_failed`, `unauthorized`, `http_<status>`). `status` is 0 when

package/dist/client.js

@@ -16,10 +16,11 @@ export const BUY_TURN_TIMEOUT_MS = 130_000;
 const CALL_TIMEOUT_MS = 30_000;
 /** A token is renewed this long before it expires, so it never expires mid-call. */
 const RENEW_EARLY_MS = 60_000;
+const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'add_card', 'confirm', 'verification_code', 'approve']);
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
  * (`user_not_connected`, `external_user_id_ambiguous`, `turn_in_progress`,
- * `user_id_mismatch`), one read from the shape of the answer
+ * `user_id_mismatch`, `pick_not_found`), one read from the shape of the answer
  * (`cart_changed`, `nothing_to_confirm`, `conversation_closed`,
  * `conversation_not_found`), or the client's (`unreachable`, `timeout`,
  * `oauth_failed`, `unauthorized`, `http_<status>`). `status` is 0 when
@@ -97,18 +98,36 @@ function cartOf(v) {
 function cartsOf(v) {
     return Array.isArray(v) ? v.map(cartOf).filter((c) => c !== null) : [];
 }
+function flightOf(value) {
+    if (!isRecord(value) || !Array.isArray(value.legs))
+        return undefined;
+    return {
+        ...(Object.hasOwn(value, 'fareCabinClass') ? { fareCabinClass: str(value.fareCabinClass) } : {}),
+        legs: value.legs.map(value => {
+            const leg = isRecord(value) ? value : {};
+            return { origin: str(leg.origin), destination: str(leg.destination),
+                departureAt: str(leg.departureAt), arrivalAt: str(leg.arrivalAt),
+                cabinClasses: Array.isArray(leg.cabinClasses) ? leg.cabinClasses.map(str) : [] };
+        }),
+    };
+}
 function catalogOf(v) {
     if (!isRecord(v))
         return null;
-    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => ({
-        id: str(i.id) ?? '',
-        name: str(i.name),
-        priceCents: num(i.priceCents),
-        currency: str(i.currency),
-        image_url: str(i.image_url),
-        store: storeOf(i.store),
-        url: pageUrl(i.url),
-    })) : [];
+    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+        const flight = flightOf(i.flight);
+        return {
+            id: str(i.id) ?? '',
+            ref: str(i.ref),
+            name: str(i.name),
+            priceCents: num(i.priceCents),
+            currency: str(i.currency),
+            image_url: str(i.image_url),
+            ...(flight ? { flight } : {}),
+            store: storeOf(i.store),
+            url: pageUrl(i.url),
+        };
+    }) : [];
     return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items };
 }
 function paymentSourceOf(v) {
@@ -142,6 +161,8 @@ export function turnOf(body) {
         store_login_url: str(body.store_login_url),
         store_login_expires_at: str(body.store_login_expires_at),
         store_login_merchant_name: str(body.store_login_merchant_name),
+        next_action: typeof body.next_action === 'string' && NEXT_ACTIONS.has(body.next_action) ? body.next_action : null,
+        pick: isRecord(body.pick) && str(body.pick.product_id) ? { product_id: body.pick.product_id, ref: str(body.pick.ref), in_cart: body.pick.in_cart === true } : null,
         raw: body,
     };
 }

package/dist/definition.d.ts

@@ -1,17 +1,23 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with three required fields. The delivery address and the
+ * JSON Schema with four required fields, `product_id` null unless the shopper
+ * picks a product they were shown. The delivery address and the
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
 export declare const BUY_TOOL_NAME = "buy";
 /** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
 export declare const BUY_TOOL_DESCRIPTION: string;
-/** What the model sends: all three fields, every time. */
+/**
+ * What the model sends: `ask`, `confirm` and `new_order` every time, and `product_id`, null unless the
+ * shopper picks a product from the last result. Your own code may leave `product_id` out.
+ */
 export interface BuyToolInput {
     ask: string;
     confirm: boolean;
     new_order: boolean;
+    /** The `product_id` of the product the shopper picked from the last result's `products`, or null. */
+    product_id?: string | null;
 }
 /** A type, not an interface, so it fits the SDKs' own input schema types, which take any key. */
 export type BuyToolInputSchema = {
@@ -29,6 +35,10 @@ export type BuyToolInputSchema = {
             type: 'boolean';
             description: string;
         };
+        product_id: {
+            type: ['string', 'null'];
+            description: string;
+        };
     };
     required: Array<keyof BuyToolInput>;
     additionalProperties: false;
@@ -42,8 +52,9 @@ export interface BuyToolDefinition {
 export declare function buyToolDefinition(): BuyToolDefinition;
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * with `ask` a string and `confirm` and `new_order` booleans, and nothing
- * else. Throws a TypeError whose message tells the model what to send.
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
+ * string, null or left out, and nothing else. Throws a TypeError whose message
+ * tells the model what to send.
  */
 export declare function parseBuyToolInput(value: unknown): BuyToolInput;
 /** The buy tool in OpenAI's function-calling format, which the OpenAI SDK, OpenRouter's chat API and most other model APIs take. */

package/dist/definition.js

@@ -1,6 +1,7 @@
 /**
  * The buy tool as a model sees it: one name, one description, and a strict
- * JSON Schema with three required fields. The delivery address and the
+ * JSON Schema with four required fields, `product_id` null unless the shopper
+ * picks a product they were shown. The delivery address and the
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
@@ -11,6 +12,7 @@ export const BUY_TOOL_DESCRIPTION = [
     "Put the shopper's own words in `ask`.",
     'Tell the shopper what `reply` says, in your own voice.',
     'Show the shopper the cart before you confirm it.',
+    'Ask the shopper for exactly one thing per message: the step `next_action` names, even when `reply` lists more. Never mention a later step, and never ask for the next one until the shopper has done this one.',
     'Set `confirm` to true only when the shopper just said yes to the cart in your last result, says they added the card for a cart that waits, says they approved, or asks for the approval link again.',
     'Never write a link.',
     'Each link reaches the shopper on its own.',
@@ -21,6 +23,8 @@ export const BUY_TOOL_DESCRIPTION = [
     'After `needs_card` with a cart, Agentcard keeps the cart, so set `confirm` to true once the shopper says they added the card.',
     "After `needs_card` with no cart, call this tool again with the shopper's request once they say they added a card.",
     'Set `new_order` to true only when the shopper drops the cart.',
+    "When the shopper picks one of the `products` in your last result, by its name, its place in the list or a tap that names it, set `product_id` to that product's `product_id`, so Agentcard adds exactly that product; otherwise set it to null.",
+    'When `pick.in_cart` is false, the product the shopper picked is not in the cart: tell the shopper what `reply` says, and never ask them to confirm the cart.',
 ].join(' ');
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {
@@ -36,17 +40,22 @@ export function buyToolDefinition() {
                     description: 'True only when the shopper just said yes to the cart in your last result, says they added the card for a cart that waits, says they approved, or asks for the approval link again. False otherwise.',
                 },
                 new_order: { type: 'boolean', description: 'True only when the shopper drops the cart to start a new order. False otherwise.' },
+                product_id: {
+                    type: ['string', 'null'],
+                    description: "The `product_id` of the product the shopper picked from the `products` in your last result. Null when they picked none.",
+                },
             },
-            required: ['ask', 'confirm', 'new_order'],
+            required: ['ask', 'confirm', 'new_order', 'product_id'],
             additionalProperties: false,
         },
     };
 }
-const FIELDS = new Set(['ask', 'confirm', 'new_order']);
+const FIELDS = new Set(['ask', 'confirm', 'new_order', 'product_id']);
 /**
  * The model's input, checked against the schema: an object, or its JSON text,
- * with `ask` a string and `confirm` and `new_order` booleans, and nothing
- * else. Throws a TypeError whose message tells the model what to send.
+ * with `ask` a string, `confirm` and `new_order` booleans, `product_id` a
+ * string, null or left out, and nothing else. Throws a TypeError whose message
+ * tells the model what to send.
  */
 export function parseBuyToolInput(value) {
     let input = value;
@@ -64,14 +73,18 @@ export function parseBuyToolInput(value) {
     const fields = input;
     const extra = Object.keys(fields).find((key) => !FIELDS.has(key));
     if (extra !== undefined)
-        throw new TypeError(`The buy tool takes only ask, confirm and new_order, and ${extra} is not one of them.`);
+        throw new TypeError(`The buy tool takes only ask, confirm, new_order and product_id, and ${extra} is not one of them.`);
     if (typeof fields.ask !== 'string')
         throw new TypeError("Set ask to the shopper's words, as a string.");
     if (typeof fields.confirm !== 'boolean')
         throw new TypeError('Set confirm to true or false.');
     if (typeof fields.new_order !== 'boolean')
         throw new TypeError('Set new_order to true or false.');
-    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order };
+    const productId = fields.product_id;
+    if (productId !== undefined && productId !== null && typeof productId !== 'string') {
+        throw new TypeError("Set product_id to the picked product's product_id, as a string, or to null.");
+    }
+    return { ask: fields.ask, confirm: fields.confirm, new_order: fields.new_order, product_id: typeof productId === 'string' && productId.trim() !== '' ? productId.trim() : null };
 }
 /** A fresh copy of the tool in OpenAI's function-calling format: plain JSON, so an SDK that sends it as is sends exactly this. */
 export function openAIBuyTool() {