@agent-cards/commerce-sdk 0.2.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @agent-cards/commerce-sdk
 
-Give your agent one tool that buys for your shoppers at real stores, and tell each shopper what happened to their purchase in your agent's voice. The buy tool sends what the shopper says to Agentcard, and Agentcard finds the products, builds the cart and places the order once the shopper approves it. Agentcard then sends your webhook endpoint a signed `purchase.message` event at each moment a shopper should hear about, such as an order going through or an approval link about to expire. The package checks the signature and hands you the message.
+Give your agent one tool that buys for your shoppers at real stores, and tell each shopper what happened to their purchase in your agent's voice. The buy tool sends what the shopper says to Agentcard, and Agentcard finds the products, builds the cart and places the order once the shopper approves it. Agentcard then sends your webhook endpoint a signed event at each moment a shopper should hear about, such as a card saved, an order going through or an approval link about to expire. The package checks the signature and hands you a message ready to post into that shopper's chat.
 
 ## Install
 
@@ -41,7 +41,7 @@ const answer = await new Anthropic().beta.messages.toolRunner({
 
 Build the client once and keep it. Every shopper's tool shares the client's access token, and the client renews the token a minute before it expires. Keep each shopper's tool as well. Agentcard keeps each purchase between calls, so a tool built for every message buys the same way, but it sends the same product links again each time Agentcard shows the same products.
 
-The model sends `ask`, `confirm` and `new_order`, and nothing else. Pass `deliveryAddress` when you already hold the shopper's address: the order goes there, and Agentcard never asks the shopper for it. The model can change neither the address nor the shopper.
+The model sends `ask`, `confirm`, `new_order` and `product_id`, and nothing else. Pass `deliveryAddress` when you already hold the shopper's address: the order goes there, and Agentcard never asks the shopper for it. The model can change neither the address nor the shopper.
 
 ## Use the tool in any framework
 
@@ -105,6 +105,38 @@ The tool also hands `sendLink` a `product` link for each product a search finds,
 
 Without `sendLink`, `result.links` still carries each Vault, approval and store login link for your code, each product in `result.products` carries its `url`, and the model still never reads one.
 
+## Add the exact product the shopper picks
+
+Each product in the model's view carries a `product_id`, Agentcard's id for it with no link in it. When the shopper picks one of those products, by its name, its place in the list or a tap on its card that sends its title, the model passes that `product_id`, and Agentcard adds exactly that product from the products it showed, with no new search. Your app sends no id of its own: a "Buy this" button that sends the shopper's words, such as `I'll take the KODAK AA Alkaline Batteries (24 Pack) ($13.49)`, is enough, because the model reads the `product_id` beside that name in its last result. Keep each tool result in the model's history, as a tool runner does, so the model still holds those ids on the shopper's next message.
+
+`result.pick` says what happened: the product's id, and `in_cart`, whether the cart now holds it. The model reads the same `pick` in its view, by the `product_id` it sent. A pick the cart does not hold names no next step, so the model tells the shopper what Agentcard said rather than asking for a card or a yes for an older cart. A product Agentcard no longer holds, because the products are more than 15 minutes old or a newer search replaced them, adds nothing, and the model reads that it should search again with the shopper's words.
+
+## Tell the shopper you are on it
+
+A first search can take Agentcard most of a minute. Pass `onWorking`, and the shopper reads an instant reply while Agentcard looks, such as `on it, looking for usb-c cables under $20` or `give me a sec, checking for a table for 2 in north beach`:
+
+```ts
+const buy = buyTool({
+  agentcard,
+  externalUserId: shopper.id,
+  sendLink: (link) => textShopper(shopper.id, link.url),
+  onWorking: (text) => textShopper(shopper.id, text),
+});
+```
+
+The tool sends the reply when Agentcard has not answered a new request within 1.5 seconds, so a quick answer arrives alone. It sends one for the calls the model makes in one turn, where a call that starts within 15 seconds of the last one ending counts as the same turn, and none on a confirm, on a pick of a product the shopper saw, or on an answer such as `yes`, `2`, `the first one` or a code. The words rotate through six templates, and one tool never sends the same template twice in a row. A short paraphrase of the request goes in when the tool can read one: it stops before any link, email address, phone number, street address or long number, and a request that starts with one gets a reply that names nothing, such as `looking for that now`. The call waits for `onWorking`, so the shopper reads the reply before any link and before the model answers. An `onWorking` that throws costs only the instant reply.
+
+Pass `ack: false` to send none, `ack: (ask) => text` to write your own from the shopper's words, where an empty answer sends none, and `ackDelayMs` to change the 1.5 seconds.
+
+The model takes about two seconds to call the tool after the shopper's message arrives. To answer sooner, send `ackFor(message)` the moment the message arrives, before your model runs, and pass `ack: false` to the tool so the shopper reads one reply. `ackFor` returns null for a message that starts no search, and takes the reply you sent last as `{ previous }`, so the next one comes from another template:
+
+```ts
+import { ackFor } from '@agent-cards/commerce-sdk';
+
+const ack = ackFor(message, { previous: lastAck });
+if (ack) await textShopper(shopper.id, ack);
+```
+
 ## Send each paragraph as its own message
 
 A chat app reads best when each paragraph arrives as its own message. `toMessages` cuts text at its blank lines, trims each message and leaves out the empty ones. A list whose items blank lines separate stays one message, and so does a fenced code block:
@@ -231,7 +263,55 @@ The tool sends each purchase request once, because a purchase turn runs against
 
 `buy.answer` throws the `AgentcardApiError` itself. `buy.run`, `buy.execute` and `buy.handle` throw the same message with every link taken out, and keep the original error on `error.cause` for your logs.
 
-## Mount the handler
+## Hear from Agentcard
+
+Agentcard tells your webhook endpoint about each moment a shopper should hear about, even when the shopper is not chatting: a card saved, an approval about to expire, an order placed, a delivery on its way. `agentcardWebhook` checks each delivery's signature, skips an event it already handled, and calls `onMessage` with your own id for the shopper and a message ready to post into that shopper's chat:
+
+```ts
+import express from 'express';
+import { agentcardWebhook } from '@agent-cards/commerce-sdk';
+
+const app = express();
+app.post('/agentcard/webhooks', express.raw({ type: 'application/json' }), agentcardWebhook({
+  secret: process.env.AGENTCARD_WEBHOOK_SECRET ?? '', // returned once, when you created the endpoint
+  onMessage: (shopperId, message) => postToChat(shopperId, message.text),
+}));
+```
+
+`postToChat` stands for your own code. `shopperId` is the `externalUserId` you gave the buy tool, so the message lands in the chat the purchase started in. In a Next.js route handler, export the same handler's `fetch`:
+
+```ts
+const webhook = agentcardWebhook({ secret: process.env.AGENTCARD_WEBHOOK_SECRET ?? '', onMessage: (shopperId, message) => postToChat(shopperId, message.text) });
+export const POST = webhook.fetch;
+```
+
+Subscribe your endpoint to each event below by name. A catch-all `*` alone does not turn `purchase.message` on. `SHOPPER_EVENT_TYPES` holds the three names:
+
+| Event | `kind` | When it arrives | Who wrote `text` |
+|---|---|---|---|
+| `purchase.message` | `card_added` | The shopper saved a card from the card link your app sent, or picked one they keep. | Agentcard |
+| `purchase.message` | `order_placed` | The shopper approved, and Agentcard placed the order. | Agentcard |
+| `purchase.message` | `order_failed` | The order failed after the shopper approved. | Agentcard |
+| `purchase.message` | `order_not_placed_yet` | The shopper approved, and the order is not placed yet. | Agentcard |
+| `purchase.message` | `order_unconfirmed` | The store's reply to the order was lost, so the order may exist, and Agentcard is confirming it. | Agentcard |
+| `purchase.message` | `approval_expiring` | The approval link expires soon. `text` carries the link. | Agentcard |
+| `purchase.message` | `approval_expired` | The approval expired before the shopper answered, and no charge went through. | Agentcard |
+| `purchase.message` | `card_link_unfinished` | The shopper has not added a card from their card link. `text` carries the link again. | Agentcard |
+| `purchase.message` | `card_link_expired` | The card link expired before the shopper added a card. | Agentcard |
+| `purchase.message` | `cart_idle` | A cart sat, and nobody sent it for approval. | Agentcard |
+| `order.confirmed` | `order_confirmed` | The retailer accepted the order on its side, with its own order number and delivery window. | The package |
+| `order.updated` | `order_updated` | The order reached a new delivery stage, named in `facts.orderStatus`: `confirmed`, `courier_assigned`, `courier_at_store`, `ready_for_pickup`, `picked_up`, `arriving`, `delivered` or `canceled`. | The package |
+
+Every message carries `text`, ready to send as is, `note` for your agent, `facts` with the values one by one, `externalUserId`, `userId`, `conversationId` when Agentcard names the buy conversation, and `eventId`. A kind Agentcard adds later still carries `text`.
+
+The handler answers when `onMessage` is done: `200` when it returns, `500` when it throws, and Agentcard then delivers the event again, so a failed post is not lost. It remembers the last 10,000 events it finished, so a redelivery of one runs nothing, and a second delivery that lands while the first still runs waits for its answer. That memory belongs to one process: when more than one server takes deliveries, also skip a `message.eventId` you already stored. A message whose link or window closed before it arrived (`isStale`) reaches no callback. A message for a shopper you gave Agentcard no id for, and every other event, such as `vault.card_stored` or `order.placed`, goes to `onEvent`. Agentcard waits 10 seconds for the answer, so keep `onMessage` short: post the text, or queue the agent turn, then return.
+
+To read an event without the handler, `readShopperMessage(event)` returns the same message, or null for an event that carries none.
+
+## Mount the purchase message handler
+
+`purchaseAgentWebhook` is the handler from earlier versions. It hands you `purchase.message` events only, and leaves deduplication to you. New code takes `agentcardWebhook`.
+
 
 Subscribe your webhook endpoint to `purchase.message`, then mount the handler on its route with `express.raw`:
 
@@ -304,6 +384,8 @@ The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`
 | `card_link_unfinished` | The shopper has not added a card from their card link. `text` carries the link again. |
 | `card_link_expired` | The card link expired before the shopper added a card. |
 | `cart_idle` | A cart sat, and nobody sent it for approval. |
+| `order_unconfirmed` | The store's reply to the order was lost, and Agentcard is confirming it. |
+| `card_added` | The shopper saved a card from the card link your app sent. |
 
 Agentcard can add a kind later. A kind your code does not know still carries `text`, ready to send as is.
 

package/dist/ack.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The instant reply a shopper reads while Agentcard works on their request, such as `on it, looking
+ * for usb-c cables under $20`. A search can take Agentcard most of a minute, and a shopper who hears
+ * nothing in that time asks again. The words come from fixed templates, rotated so one shopper never
+ * reads the same one twice in a row, with a short paraphrase of the request when one can be read
+ * safely from it. No model writes them, so they cost nothing and arrive at once.
+ *
+ * The paraphrase never carries a link, an email address, a phone number, a street address or a long
+ * number: the text stops before the first one, and a request that starts with one gets the template
+ * without a paraphrase. A reply to a question, such as `yes`, `2`, `the first one` or a code, gets no
+ * instant reply at all, because it starts no search.
+ */
+/** True when the shopper's words start a request, and false for an answer to a question, a pick or a code. */
+export declare function isNewRequest(text: string): boolean;
+/** A short paraphrase of what the shopper asks for, safe to read back to them, or null when none is. */
+export declare function paraphrase(text: string): string | null;
+/** The template at `index` for these words, with the paraphrase when one is safe. */
+export declare function ackAt(index: number, text: string): string;
+/** A template other than `avoid`, picked at random. */
+export declare function nextTemplate(avoid: number, random?: () => number): number;
+export interface AckForOptions {
+    /** The instant reply this shopper read last, so the next one comes from another template. */
+    previous?: string;
+}
+/**
+ * The instant reply for a shopper's message, to send the moment it arrives and before your model
+ * runs, or null for a message that starts no search, such as `yes`, `2` or a code. The buy tool
+ * sends one on its own through `onWorking`, so pass `ack: false` to the tool when you send this one.
+ *
+ * ```ts
+ * ackFor('can you find me usb-c cables under $20'); // 'on it, looking for usb-c cables under $20', or another template
+ * ackFor('yes'); // null
+ * ```
+ */
+export declare function ackFor(text: string, options?: AckForOptions): string | null;

package/dist/ack.js

@@ -0,0 +1,118 @@
+/**
+ * The instant reply a shopper reads while Agentcard works on their request, such as `on it, looking
+ * for usb-c cables under $20`. A search can take Agentcard most of a minute, and a shopper who hears
+ * nothing in that time asks again. The words come from fixed templates, rotated so one shopper never
+ * reads the same one twice in a row, with a short paraphrase of the request when one can be read
+ * safely from it. No model writes them, so they cost nothing and arrive at once.
+ *
+ * The paraphrase never carries a link, an email address, a phone number, a street address or a long
+ * number: the text stops before the first one, and a request that starts with one gets the template
+ * without a paraphrase. A reply to a question, such as `yes`, `2`, `the first one` or a code, gets no
+ * instant reply at all, because it starts no search.
+ */
+/** Each template twice: with the paraphrase in place of `{x}`, and without one. */
+const TEMPLATES = [
+    ['on it, looking for {x}', 'on it, looking for that now'],
+    ['give me a sec, checking for {x}', 'give me a sec, checking'],
+    ['looking for {x} now', 'looking for that now'],
+    ['got it, finding {x}', 'got it, one moment while i look'],
+    ['searching for {x}, one moment', 'checking on that for you now'],
+    ['checking what i can find for {x}', 'on it, give me a moment'],
+];
+/** Whole replies that answer a question the shopper was asked, after `please` and `thanks` come off. */
+const ANSWERS = new RegExp('^(?:' +
+    [
+        'hi', 'hey', 'hello', 'yo', 'sup', 'lol', 'haha', 'hmm', 'y', 'ya', 'yes', 'yeah', 'yea', 'yep', 'yup', 'sure', 'ok', 'okay', 'k', 'kk', 'no', 'nope', 'nah',
+        'confirm(?:ed)?', 'approve[ds]?(?: it)?', 'i approved(?: it)?', 'done', 'added(?: it)?', 'i added(?: it| the card| a card)?',
+        'go', 'go ahead', 'do it', '(?:buy|order|place|book) it', 'sounds good', 'perfect', 'great', 'cool', 'nice',
+        'cancel', 'stop', 'never ?mind', 'nvm', 'wait', 'hold on', 'same', 'either', 'any', 'whatever',
+        '(?:the )?(?:first|second|third|fourth|fifth|last|other|\\d{1,2}(?:st|nd|rd|th)?)(?: one)?', '(?:that|this) one',
+        '(?:option|number|no|#) ?\\d{1,2}',
+    ].join('|') +
+    ')$');
+/** A code or a number on its own, such as `111111` or `4 2 1 9`. */
+const CODE = /^[a-z]{0,3}\d[\d ]*$/;
+/** Words that start a request and say nothing about what the shopper wants, taken off the front. */
+const LEAD = /^(?:hey|hi|hello|yo|ok|okay|so|also|and|um|uh|actually|just|please|pls|can you|could you|would you|will you|can i (?:get|have)|could i (?:get|have)|i want to|i want|i need to|i need|i would like|i'?d like|id like|i'?m looking for|im looking for|looking for|get|find|order|buy|book|grab|reserve|search for|look for|look up|show|me|us)\b[\s,]*/;
+/** A request that reads as a question or a change to the purchase: the template goes out without a paraphrase. */
+const NO_PARAPHRASE = /^(?:what|where|when|why|how|who|which|is|are|was|were|do|does|did|can|could|will|would|should|has|have|change|make|swap|switch|add|remove|drop|cancel|update|use|try|send|deliver|ship|pay|charge|check|tell|give|put|set|move|keep|skip|replace|return|refund|track|reorder|pick|choose|select|go|let|help|see|compare)\b/;
+/** Where the text stops: before the first link, contact detail, address, long number or delivery clause. */
+const PRIVATE = [
+    /https?:\/\/|www\./,
+    /\S+@\S+/,
+    /[\w-]+\.[a-z]{2,}\b/,
+    /\+?\d[\d\s().-]{6,}\d/,
+    /\d{5,}/,
+    /(?:^|\s)\d{3,}\s+(?!(?:packs?|count|ct|pcs?|pieces?|oz|ml|l|g|kg|gb|tb|mah|w|watts?|inch(?:es)?|in|ft|feet|mm|cm|lbs?|dollars?|bucks|thread)\b)[a-z]/,
+    /\b\d+\s+(?:[a-z]+\s+){1,2}(?:st|street|ave|avenue|rd|road|blvd|boulevard|dr|drive|ln|lane|way|ct|court|pl|place|ter|terrace|hwy|highway)\b/,
+    /\b(?:deliver(?:ed)? (?:it )?to|ship(?:ped)? (?:it )?to|send (?:it )?to|bring (?:it )?to|to my (?:place|house|home|apartment|apt|office|work)|my (?:address|number|phone|email|name|card)|address is|call me|text me|named|called|apt|apartment|unit|suite)\b/,
+];
+/** Words a cut paraphrase never ends on. */
+const TAIL = /\s+(?:for|with|and|or|but|the|a|an|to|of|in|at|on|from|under|over|below|above|near|by|who|that|which|my|some|around|about)$/;
+const MAX_WORDS = 8;
+/** The text as one plain line: lowercase, no quotes, and no dash between words. */
+function plain(text) {
+    return text.toLowerCase().replace(/[‘’]/g, "'").replace(/["“”`]/g, '').replace(/\s+[-–—]+\s+|[–—]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+/** True when the shopper's words start a request, and false for an answer to a question, a pick or a code. */
+export function isNewRequest(text) {
+    const words = plain(String(text ?? '')).replace(/[!?.,;:]+/g, ' ').replace(/\b(?:please|pls|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim();
+    if (!/[\p{L}\p{N}]/u.test(words))
+        return false;
+    return !ANSWERS.test(words) && !CODE.test(words);
+}
+/** A short paraphrase of what the shopper asks for, safe to read back to them, or null when none is. */
+export function paraphrase(text) {
+    let rest = plain(String(text ?? '')).split(/[.!?;\n](?:\s|$)/)[0] ?? '';
+    for (const pattern of PRIVATE) {
+        const at = rest.search(pattern);
+        if (at >= 0)
+            rest = rest.slice(0, at);
+    }
+    for (let before = ''; before !== rest;) {
+        before = rest;
+        rest = rest.replace(LEAD, '');
+    }
+    rest = rest.replace(/[\s,.:!?]+$/, '');
+    if (NO_PARAPHRASE.test(rest))
+        return null;
+    const words = rest.split(' ').filter(Boolean);
+    let short = words.slice(0, MAX_WORDS).join(' ');
+    while (TAIL.test(short))
+        short = short.replace(TAIL, '');
+    short = short.replace(/[\s,]+$/, '');
+    return /[a-z]{2}/.test(short) && isNewRequest(short) ? short : null;
+}
+/** The template at `index` for these words, with the paraphrase when one is safe. */
+export function ackAt(index, text) {
+    const [withWhat, without] = TEMPLATES[index % TEMPLATES.length];
+    const what = paraphrase(text);
+    return what ? withWhat.replace('{x}', what) : without;
+}
+/** A template other than `avoid`, picked at random. */
+export function nextTemplate(avoid, random = Math.random) {
+    const pick = Math.floor(random() * (TEMPLATES.length - 1));
+    return avoid < 0 || pick < avoid ? pick : pick + 1;
+}
+/** The template an earlier instant reply came from, or -1. */
+function templateOf(reply) {
+    if (!reply)
+        return -1;
+    const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return TEMPLATES.findIndex(([withWhat, without]) => reply === without || new RegExp(`^${escape(withWhat).replace('\\{x\\}', '.+')}$`).test(reply));
+}
+/**
+ * The instant reply for a shopper's message, to send the moment it arrives and before your model
+ * runs, or null for a message that starts no search, such as `yes`, `2` or a code. The buy tool
+ * sends one on its own through `onWorking`, so pass `ack: false` to the tool when you send this one.
+ *
+ * ```ts
+ * ackFor('can you find me usb-c cables under $20'); // 'on it, looking for usb-c cables under $20', or another template
+ * ackFor('yes'); // null
+ * ```
+ */
+export function ackFor(text, options = {}) {
+    if (!isNewRequest(text))
+        return null;
+    return ackAt(nextTemplate(templateOf(options?.previous)), text);
+}

package/dist/adapters.d.ts

@@ -14,13 +14,16 @@ import type { BuyTool } from './buy-tool.js';
 export type AnthropicBuyTool = BuyTool;
 /** @deprecated Pass the buy tool itself: `toolRunner({ tools: [buy] })`. Returns the same object, for one release. */
 export declare function toAnthropicTool(tool: BuyTool): BuyTool;
-/** The three zod builders the OpenRouter adapter calls; `z` from zod 3 or 4 has them. */
+/** The zod builders the OpenRouter adapter calls; `z` from zod 3 or 4 has them. */
 export interface ZodLike {
     object(shape: Record<string, unknown>): {
         strict(): unknown;
     };
     string(): {
         describe(description: string): unknown;
+        nullable(): {
+            describe(description: string): unknown;
+        };
     };
     boolean(): {
         describe(description: string): unknown;

package/dist/adapters.js

@@ -16,6 +16,7 @@ export function toOpenRouterTool(buy, toolkit) {
             ask: z.string().describe(properties.ask.description),
             confirm: z.boolean().describe(properties.confirm.description),
             new_order: z.boolean().describe(properties.new_order.description),
+            product_id: z.string().nullable().describe(properties.product_id.description),
         }).strict(),
         // OpenRouter's SDK encodes what execute returns as JSON, so the view goes back as an object and reaches the model as the same text.
         execute: async (input) => JSON.parse(await buy.execute(input)),

package/dist/buy-tool.d.ts

@@ -22,7 +22,7 @@
  * A turn that outlived Agentcard's budget gets a read every 5 seconds for up
  * to a minute, until the turn ends.
  */
-import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type FetchLike } from './client.js';
+import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type BuyToolModelView } from './model-view.js';
 /**
@@ -62,6 +62,8 @@ export interface BuyToolLink {
 export interface BuyToolProduct {
     flight?: BuyFlightItinerary;
     id: string;
+    /** Agentcard's link-free id for the product, which the model passes as `product_id` when the shopper picks it; null from an older API. */
+    ref: string | null;
     name: string;
     /** The price in the minor unit of `currency`. */
     priceCents: number | null;
@@ -108,6 +110,8 @@ export interface BuyToolResult {
     error_code: string | null;
     /** The one step the shopper takes next, as Agentcard named it, or null. Only that step's link is in `links`. */
     next_action: BuyNextAction | null;
+    /** The product the model's `product_id` picked, by its catalog id, and whether the cart now holds it; null when the call picked none. */
+    pick: BuyPick | null;
     /** Every cart hash in this answer. */
     hashes: string[];
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
@@ -136,6 +140,18 @@ export interface BuyToolOptions {
     fetch?: FetchLike;
     /** The pause between two reads of the conversation. Default: a timer. */
     wait?: (ms: number) => Promise<void>;
+    /**
+     * Sends the shopper an instant reply, such as `on it, looking for usb-c cables under $20`, while
+     * Agentcard works on a new request. It goes out when Agentcard has not answered within
+     * `ackDelayMs`, once for the calls the model makes in one turn, and never on a confirm, a pick or a
+     * reply such as `yes`, `2` or a code. The call waits for it before it returns, so the shopper reads
+     * it before any link or the model's answer. One that throws costs nothing but the instant reply.
+     */
+    onWorking?: (message: string) => void | Promise<void>;
+    /** `false` sends no instant reply. A function writes it from the shopper's words instead, and an empty answer sends none. */
+    ack?: false | ((ask: string) => string | null | undefined);
+    /** How long Agentcard has to answer before the instant reply goes out. Default 1500. */
+    ackDelayMs?: number;
 }
 /**
  * The buy tool, in the shape every agent framework takes, because their field

package/dist/buy-tool.js

@@ -26,6 +26,7 @@ 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. */
@@ -41,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.';
@@ -52,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 !== ''))];
 }
@@ -60,6 +77,7 @@ function productsOf(turn) {
         .filter((item) => item.name)
         .map((item) => ({
         id: item.id,
+        ref: item.ref,
         name: item.name,
         priceCents: item.priceCents,
         currency: item.currency,
@@ -94,6 +112,7 @@ function answerOf(turn) {
         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,
     };
@@ -191,6 +210,7 @@ function resultOfRefusal(error) {
         decline_code: null,
         error_code: error.code,
         next_action: null,
+        pick: null,
         hashes: hashesOf(null, carts),
         envelope: error.body,
     });
@@ -202,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. */
@@ -222,6 +244,7 @@ function needsCard(link, body) {
         decline_code: null,
         error_code: 'user_not_connected',
         next_action: 'add_card',
+        pick: null,
         hashes: [],
         envelope: body,
     };
@@ -299,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 {
@@ -456,6 +536,8 @@ export function buyTool(options) {
                     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)
@@ -572,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(withMessages(turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt), turn));
     };
     /** 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;
@@ -101,6 +108,8 @@ export interface BuyFlightItinerary {
 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. */
@@ -116,6 +125,12 @@ 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;
@@ -160,6 +175,8 @@ export interface BuyTurn {
     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>;
 }
@@ -211,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

@@ -20,7 +20,7 @@ const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'add_card', '
 /**
  * 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
@@ -118,6 +118,7 @@ function catalogOf(v) {
         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),
@@ -161,6 +162,7 @@ export function turnOf(body) {
         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,
     };
 }