@agent-cards/commerce-sdk 0.5.0 → 0.8.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 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.
+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 tells your server about each moment a shopper should hear about, such as a card saved, an order going through or an approval link about to expire, and the package hands you a message ready to post into that shopper's chat. Your server opens the connection to Agentcard, so you host no webhook endpoint.
 
 ## Install
 
@@ -10,6 +10,39 @@ npm install @agent-cards/commerce-sdk
 
 The package runs on Node 18 or later and has no dependencies.
 
+## Hear from Agentcard without webhooks
+
+Call `listen` once when your server starts. Your server opens one connection to Agentcard with your company credentials, and Agentcard sends every event for your company down it, so you need no public URL, no webhook secret and no signature check:
+
+```ts
+import { AgentcardClient } from '@agent-cards/commerce-sdk';
+
+const agentcard = new AgentcardClient({ clientId: process.env.AGENTCARD_CLIENT_ID ?? '', clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '' });
+agentcard.listen({
+  onMessage: (shopperId, message) => postToChat(shopperId, message.text),
+  onEvent: (event) => console.log(event.type, event.data),
+});
+```
+
+`postToChat` stands for your own code. `onMessage` gets each message for one of your shoppers under your own id for them, the `externalUserId` you gave the buy tool, with the same ready-to-send `text` as `agentcardWebhook`: a card saved (`card_added`), an order placed, an approval about to expire, a delivery on its way. `onEvent` gets every other event Agentcard sends your company, such as `vault.card_stored`, `checkout_authorization.approved` or `transfer.completed`, as the same envelope a webhook endpoint would receive, with the same `id`. Without `onMessage`, `onEvent` gets every event. `AGENTCARD_EVENT_TYPES` lists every type, and `events: ['order.*', 'purchase.message']` keeps only the ones you name.
+
+The listener keeps itself connected. It reconnects after a dropped connection, waiting longer after each failure up to 30 seconds, and reconnects when Agentcard sends no heartbeat for 45 seconds. Each reconnect resumes after the last event it handled, so nothing that happened while it was away is lost, and it skips an event it already handled. Agentcard keeps each event for the stream for 72 hours. Where the stream does not get through, the listener reads the same events every two seconds instead.
+
+Events run one at a time, in the order Agentcard recorded them. The listener waits for your callback before it hands over the next event, and a callback that throws runs again, up to five times, before the listener passes the error to `onError` and moves on.
+
+A new process starts from the moment it connects. To resume where the last process stopped, pass a `cursor` store. After a resume, Agentcard hands over the last ten seconds of events again, in case one of them arrived late. The listener saves the cursor with the id of each event it handled in that window, so a new process skips the ones it already handled:
+
+```ts
+agentcard.listen({
+  onMessage: (shopperId, message) => postToChat(shopperId, message.text),
+  cursor: { load: () => redis.get('agentcard:cursor'), save: (cursor) => redis.set('agentcard:cursor', cursor) },
+});
+```
+
+`listen` returns `{ ready, close }`: `ready` resolves once the listener reaches Agentcard, and `close()` stops it after the callback that is running returns. Run one listener per company and mode. Two listeners each hear every event, so with two, skip a `message.eventId` you already stored. Sandbox credentials hear sandbox events, live credentials live ones, and a shopper message is always live.
+
+`listen` needs a process that keeps running, such as a Node server, a worker or a container. On a host that ends each request after a few seconds, such as a serverless function, take the events at a webhook endpoint instead, as "Hear from Agentcard at a webhook endpoint" shows.
+
 ## Give your agent the buy tool
 
 Build one client with your company's credentials and one buy tool per shopper, then pass the tool to your agent as it is:
@@ -101,13 +134,15 @@ console.log(await result.getText());
 
 A purchase needs a link at three moments: the shopper approves the purchase on an approval page, a new shopper adds a card on a Vault page, and a shopper signs in to a store's own account on its login page before Agentcard can buy there. Each link's `kind` says which: `approval`, `vault` or `store_login`, and a `store_login` link names the store in `store`. The tool hands each link to `sendLink` and waits for it, so the shopper holds the link before the model answers. The model reads `link_sent: true` and never the link itself, because a tool runner puts each answer straight into the model's context, and a model that holds a link writes it into the chat.
 
-The tool also hands `sendLink` a `product` link for each product a search finds, up to three per answer. The link carries the product's page at its store in `url`, the product's name in `title`, its price in `price`, such as `$12.99`, its id in `productId`, and its picture in `imageUrl`, or null when the store sent none. Every price the tool writes, in a link or in the model's view, uses the currency Agentcard names for the cart or the product, in that currency's own minor units: `1331` is `$13.31` in USD, `CA$13.31` in CAD and `¥1,331` in JPY. A price whose currency Agentcard does not name shows with no symbol. The link arrives beside the reply, and you decide how to show it: as a card, in a list, or as a text with the URL. The model reads `product_links_sent` and never a URL, so a shopper who asks for links hears that the links are there. When the next answer in the conversation shows the same products, the tool sends none of their links again. A product link your `sendLink` throws on counts as not sent, and the call goes on.
+The tool also hands `sendLink` a `product` link for each product a search finds, up to three per answer. The link carries the product's page at its store in `url`, the product's name in `title`, its price in `price`, such as `$12.99`, Agentcard's id for it in `productId`, and its picture in `imageUrl`, or null when the store sent none. Every price the tool writes, in a link or in the model's view, uses the currency Agentcard names for the cart or the product, in that currency's own minor units: `1331` is `$13.31` in USD, `CA$13.31` in CAD and `¥1,331` in JPY. A price whose currency Agentcard does not name shows with no symbol. The link arrives beside the reply, and you decide how to show it: as a card, in a list, or as a text with the URL. The model reads `product_links_sent` and never a URL, so a shopper who asks for links hears that the links are there. When a later answer in the conversation only stands beside the same products, as a cart answer does, the tool sends none of their links again. When a later turn's reply presents them again, as the answer to a repeated ask does, the tool sends their links again, so every product the reply names arrives with its link. A product link your `sendLink` throws on counts as not sent, and the call goes on.
+
+`productId` holds no link: it is the same `product_id` the model reads for that product, and the page is `url`. An answer that only adds a product the shopper picked lists that product alone, so it sends no card for a product nobody offered on that turn, and the pages the search already sent still count as sent on the answers after it.
 
 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.
+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. Your own code can pick too: a card's button can call `buy.answer` with the link's `productId` as `product_id`, and Agentcard adds that product.
 
 `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.
 
@@ -126,17 +161,36 @@ const buy = buyTool({
 
 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.
 
+When the instant reply went out, the model reads `shopper_already_told_looking: true` in that turn's answers, and the tool's description tells it not to acknowledge the request again, so its own reply opens with the answer or the question rather than a second `on it`. It reads false on a turn that sent none, and when `onWorking` threw.
+
 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:
+The model takes several seconds to call the tool after the shopper's message arrives. To answer sooner, call `buy.instantAck(message)` the moment the message arrives, before your model runs, and send the text it returns:
 
 ```ts
-import { ackFor } from '@agent-cards/commerce-sdk';
-
-const ack = ackFor(message, { previous: lastAck });
+const ack = buy.instantAck(message);
 if (ack) await textShopper(shopper.id, ack);
 ```
 
+`instantAck` returns null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a code, small talk such as `hi` or `how are you`, a message that carries the shopper's own details, such as a name with a phone number, an email address, a street address or a zip code, and any message that answers the last answer's request for shipping or guest details or a code. The reply never reads those details back. Once you call it, the tool sends no reply of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true` when your reply went out, so the shopper hears one acknowledgement.
+
+Without a buy tool, `instantAck(message, { previous, nextAction })` from the package root decides the same way: `previous` is the reply you sent last, so the next one comes from another template, and `nextAction` is the last answer's `next_action`. Pass `ack: false` to the tool when you send it yourself. `ackFor` is the earlier name of the same function.
+
+## Show what Agentcard is doing
+
+Pass `onProgress`, and the tool asks Agentcard to stream each call. Each stage the call reaches goes to `onProgress` as it happens, `searching`, `building_cart`, `checking_out` or `working`, for a status line such as "searching amazon":
+
+```ts
+const buy = buyTool({
+  agentcard,
+  externalUserId: shopper.id,
+  sendLink: (link) => textShopper(shopper.id, link.url),
+  onProgress: ({ stage }) => showStatus(shopper.id, stage),
+});
+```
+
+The product cards still go out with the answer, so each card is a product the reply names. `earlyCards: true` sends the search's first three cards the moment the search answers instead, a few seconds sooner, and the answer then sends only the cards it adds. The reply often recommends other products than the search's first three, so with `earlyCards` a shopper can hold cards the reply never names. A stream that breaks after the call started reads the conversation for what the turn left, as a turn past Agentcard's budget does. Pass `stream: false` to wait for each whole answer.
+
 ## 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:
@@ -195,6 +249,7 @@ The model reads one object per call:
   "products": [],
   "approval_expires_at": null,
   "shopper_need_not_reply": false,
+  "shopper_already_told_looking": false,
   "link_sent": false,
   "product_links_sent": 0
 }
@@ -202,6 +257,8 @@ The model reads one object per call:
 
 `cart` is the newest cart, and `carts` lists every cart on the table, the newest last, so a shopper buying from more than one store hears each one.
 
+Each product in `products` names its `store`, and a product Agentcard sends without a store is left out, so the model never offers a product without saying where it is sold. No link reaches the model: an address with a path or a scheme is taken out, and a bare one, such as `walmart.com` in `reply`, reads as the site's name, `Walmart`.
+
 `status` says where the purchase stands:
 
 | `status` | What happened |
@@ -226,6 +283,20 @@ const view = buy.forModel(result); // the tool result your model reads
 
 `buy.run`, `buy.execute` and `buy.handle` each return the same text, `JSON.stringify(buy.forModel(result))`: Anthropic's tool runner calls `buy.run`, the Vercel AI SDK calls `buy.execute`, and your own loop calls `buy.handle`.
 
+## Show the cart in your app
+
+Pass `onResult` to read every answer while your framework keeps calling `buy.run`, so you never wrap the tool or parse the model's JSON. It gets the whole answer once per call, after its links went out and before the model reads it: the carts, `status`, `next_action` and `order_id`. This one keeps the cart above the chat input:
+
+```ts
+const buy = buyTool({
+  agentcard,
+  externalUserId: shopper.id,
+  onResult: (result) => showCartAboveInput(shopper.id, result.carts, result.next_action),
+});
+```
+
+A refusal the tool turns into an answer, such as the Vault link for a shopper with no card, reaches `onResult` too. A call that throws calls nothing. An `onResult` that throws costs only that call to it, and the model still reads the answer. If you wrap `buy.answer` yourself, hand its errors to `forModelError` before a model reads them, and every link is taken out.
+
 ## Buy with a shopper's own token
 
 A tool that buys for one signed-in shopper takes that shopper's own Agentcard access token instead of a client, and names nobody:
@@ -263,9 +334,9 @@ 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.
 
-## Hear from Agentcard
+## Hear from Agentcard at a webhook endpoint
 
-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:
+A company that prefers webhooks, or runs on a host where no process keeps running, takes the same events at an endpoint of its own. 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';

package/dist/ack.d.ts

@@ -10,7 +10,11 @@
  * 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. */
+/**
+ * True when the shopper's words start a request, and false for an answer to a question, a pick, a
+ * code, small talk, or a message that carries the shopper's own details, such as a phone number or a
+ * street address.
+ */
 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;
@@ -21,15 +25,27 @@ export declare function nextTemplate(avoid: number, random?: () => number): numb
 export interface AckForOptions {
     /** The instant reply this shopper read last, so the next one comes from another template. */
     previous?: string;
+    /**
+     * The step the last purchase answer asked the shopper for, its `next_action`. After a question for
+     * shipping or guest details or a code, the next message answers it, so it gets no instant reply.
+     */
+    nextAction?: string | null;
 }
 /**
- * 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.
+ * The instant reply for a shopper's message, such as `on it, looking for usb-c cables under $20`, to
+ * send the moment the message arrives and before your model runs; or null for a message that starts no
+ * search: a confirmation or a short answer such as `yes`, `1` or `ok`, a code, small talk such as `hi`,
+ * and the shopper's own details, such as a name, a phone number or an address. The words come from
+ * fixed lowercase templates, rotated, and never repeat the shopper's personal details.
+ *
+ * With the buy tool, call `buy.instantAck(text)` instead: the tool then sends no reply of its own
+ * through `onWorking` for that turn, and tells the model the shopper already heard 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
+ * instantAck('can you find me usb-c cables under $20'); // 'on it, looking for usb-c cables under $20', or another template
+ * instantAck('karen, 628 208 4916, 1801 wedemeyer st'); // null
  * ```
  */
+export declare function instantAck(shopperText: string, options?: AckForOptions): string | null;
+/** The earlier name of `instantAck`, kept for apps that call it. */
 export declare function ackFor(text: string, options?: AckForOptions): string | null;

package/dist/ack.js

@@ -30,6 +30,34 @@ const ANSWERS = new RegExp('^(?:' +
         '(?:option|number|no|#) ?\\d{1,2}',
     ].join('|') +
     ')$');
+/** Small talk that asks for nothing to be bought, after `please` and `thanks` come off. */
+const CHITCHAT = /^(?:(?:hi|hey|hello|yo|hiya|howdy|sup)(?: there| again)?|good (?:morning|afternoon|evening|night)|g(?:oo)?d ?night|how are (?:you|u)(?: doing)?(?: today)?|how'?s it going|what'?s up|whats up|wassup|who are (?:you|u)|what (?:can|do) (?:you|u) do|are (?:you|u) (?:a )?(?:bot|real|human|there)|you there|test(?:ing)?|bye|see (?:you|ya)|later|love (?:it|you|u)|awesome|amazing|wow|omg|ha(?:ha)+|lmao|:\)|ok cool|cool thanks|so much|very much|a lot)$/;
+/** Unit words a number names a product by, such as `10000 mah`, so it is never read as a zip code. */
+const UNIT = '(?:packs?|count|ct|pcs?|pieces?|oz|ml|l|g|kg|gb|tb|mb|mah|w|watts?|v|volts?|lumens?|lm|inch(?:es)?|in|ft|feet|mm|cm|lbs?|dollars?|bucks|rpm|dpi|btu|cal|calories|thread)';
+/**
+ * Details a shopper sends about themselves rather than a request: an email address, a street address,
+ * an apartment number, or words that hand over a name, a number or a place. Phone numbers, zip codes
+ * and card numbers are read by `hasPersonalNumber`.
+ */
+const PERSONAL = [
+    /\S+@\S+\.\S+/,
+    // A house number, a direction, then a street name that is no unit (`16 gb flash drive` is a product), then the street's kind.
+    new RegExp(`(?:^|[\\s,])\\d{2,6}\\s+(?:[nsew]\\.?\\s+)?(?!${UNIT}\\b)[a-z][a-z'.-]+(?:\\s+[a-z][a-z'.-]+){0,2}\\s+(?:st|street|ave|avenue|rd|road|blvd|boulevard|dr|drive|ln|lane|way|ct|court|pl|place|ter|terrace|hwy|highway|pkwy|parkway)\\b`),
+    /\b(?:apt|apartment|unit|suite)\s*#?\s*\d/,
+    /\b(?:my name is|my name'?s|name is|i'?m called|my (?:address|number|phone|email|zip)|address is|phone is|email is|zip is|deliver(?:ed)? (?:it )?to|ship(?:ped)? (?:it )?to|send (?:it )?to|bring (?:it )?to|call me|text me)\b/,
+    new RegExp(`(?<![\\w/.$-])\\d{5}(?:-\\d{4})?(?![\\w.,]\\d)(?!\\w)(?!\\s*${UNIT}\\b)`),
+];
+/** True when the text holds a phone number (10 to 15 digits, with or without separators) or a run of 12 digits or more, such as a card number. */
+function hasPersonalNumber(line) {
+    if (/\d{12,}/.test(line))
+        return true;
+    for (const run of line.match(/\+?\d[\d\s().-]{6,}\d/g) ?? []) {
+        const digits = run.replace(/\D/g, '').length;
+        if (digits >= 10 && digits <= 15)
+            return true;
+    }
+    return false;
+}
 /** 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. */
@@ -54,12 +82,19 @@ const MAX_WORDS = 8;
 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. */
+/**
+ * True when the shopper's words start a request, and false for an answer to a question, a pick, a
+ * code, small talk, or a message that carries the shopper's own details, such as a phone number or a
+ * street address.
+ */
 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();
+    const line = plain(String(text ?? ''));
+    const words = line.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);
+    if (hasPersonalNumber(line) || PERSONAL.some((pattern) => pattern.test(line)))
+        return false;
+    return !ANSWERS.test(words) && !CODE.test(words) && !CHITCHAT.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) {
@@ -101,18 +136,31 @@ function templateOf(reply) {
     const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return TEMPLATES.findIndex(([withWhat, without]) => reply === without || new RegExp(`^${escape(withWhat).replace('\\{x\\}', '.+')}$`).test(reply));
 }
+/** The steps a shopper answers with their own details or a code, never with a new request. */
+const ANSWERED_STEPS = new Set(['shipping_details', 'guest_details', 'verification_code']);
 /**
- * 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.
+ * The instant reply for a shopper's message, such as `on it, looking for usb-c cables under $20`, to
+ * send the moment the message arrives and before your model runs; or null for a message that starts no
+ * search: a confirmation or a short answer such as `yes`, `1` or `ok`, a code, small talk such as `hi`,
+ * and the shopper's own details, such as a name, a phone number or an address. The words come from
+ * fixed lowercase templates, rotated, and never repeat the shopper's personal details.
+ *
+ * With the buy tool, call `buy.instantAck(text)` instead: the tool then sends no reply of its own
+ * through `onWorking` for that turn, and tells the model the shopper already heard 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
+ * instantAck('can you find me usb-c cables under $20'); // 'on it, looking for usb-c cables under $20', or another template
+ * instantAck('karen, 628 208 4916, 1801 wedemeyer st'); // null
  * ```
  */
-export function ackFor(text, options = {}) {
-    if (!isNewRequest(text))
+export function instantAck(shopperText, options = {}) {
+    if (typeof options?.nextAction === 'string' && ANSWERED_STEPS.has(options.nextAction))
         return null;
-    return ackAt(nextTemplate(templateOf(options?.previous)), text);
+    if (!isNewRequest(shopperText))
+        return null;
+    return ackAt(nextTemplate(templateOf(options?.previous)), shopperText);
+}
+/** The earlier name of `instantAck`, kept for apps that call it. */
+export function ackFor(text, options = {}) {
+    return instantAck(text, options);
 }

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 BuyPick, type FetchLike } from './client.js';
+import { AgentcardClient, type BuyCart, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, 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';
 /**
@@ -40,7 +40,7 @@ export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'pl
  * card. `approval`: the page where they approve this purchase. `store_login`:
  * the page where they sign in to the store named in `store`, before Agentcard
  * can buy there. `product`: a product's page at its store, with its `title`,
- * `price`, `productId` and `imageUrl`.
+ * `price`, `productId` and `imageUrl`. The page is `url`; `productId` holds no link.
  */
 export interface BuyToolLink {
     kind: 'vault' | 'approval' | 'store_login' | 'product';
@@ -53,7 +53,11 @@ export interface BuyToolLink {
     title?: string;
     /** On a product link: the price as the shopper reads it, such as `$12.99`, or null when Agentcard named none. */
     price?: string | null;
-    /** On a product link: Agentcard's id for the product. */
+    /**
+     * On a product link: Agentcard's id for the product, with no link in it. It is the `product_id` the
+     * model reads for the same product, and the tool takes it as `product_id`, so a "Buy this" button
+     * can hand it back as the shopper's pick. Absent when Agentcard sent no such id, as an older API does.
+     */
     productId?: string;
     /** On a product link: the product's picture, or null when Agentcard sent none. Show it beside the title. */
     imageUrl?: string | null;
@@ -104,6 +108,11 @@ export interface BuyToolResult {
     approval_expires_at: string | null;
     /** True when Agentcard tells the shopper how the order went, so the shopper need not reply. */
     shopper_need_not_reply: boolean;
+    /**
+     * True when `onWorking` delivered this turn's instant reply, such as `got it, finding a taco`, so the
+     * shopper already heard that the request is being worked on. Absent or false when none went out.
+     */
+    shopper_already_told_looking?: boolean;
     conversation_id: string | null;
     order_id: string | null;
     decline_code: string | null;
@@ -152,6 +161,32 @@ export interface BuyToolOptions {
     ack?: false | ((ask: string) => string | null | undefined);
     /** How long Agentcard has to answer before the instant reply goes out. Default 1500. */
     ackDelayMs?: number;
+    /**
+     * Called with the whole answer once per call, after its links went out and before the model reads
+     * it, so your app can show the carts, the status, `next_action` or the order id without wrapping the
+     * tool. A refusal the tool turns into an answer, such as a Vault link for a shopper with no card,
+     * counts; a call that throws calls nothing. One that throws costs nothing but the call to it.
+     */
+    onResult?: (result: BuyToolResult) => void | Promise<void>;
+    /**
+     * Called while Agentcard works on a call, with the stage it reached: `searching`, `building_cart`,
+     * `checking_out` or `working`. Show it as a status line. One that throws costs nothing but the call to it.
+     */
+    onProgress?: (progress: BuyProgress) => void;
+    /**
+     * `false` waits for each whole answer. With `onProgress`, or with `earlyCards` and `sendLink`, the
+     * tool asks Agentcard to stream the call, and each stage goes to `onProgress` as it happens.
+     */
+    stream?: false;
+    /**
+     * `true` sends the store pages of a search's first three products to `sendLink` the moment the search
+     * answers, before Agentcard writes its reply, and the answer then sends only the pages it adds. Off by
+     * default: the reply often recommends other products than the search's first three, so a shopper
+     * would hold cards the reply never names. Measured on five live searches on 2026-10-20, the early
+     * pages arrived 2.2 to 3.3 seconds before the answer, and in four of them the reply named a product
+     * outside the first three.
+     */
+    earlyCards?: boolean;
 }
 /**
  * The buy tool, in the shape every agent framework takes, because their field
@@ -193,6 +228,15 @@ export interface BuyTool {
     answer(input: BuyToolInput): Promise<BuyToolResult>;
     /** The answer as the model may read it, with every link taken out. */
     forModel(result: BuyToolResult): BuyToolModelView;
+    /**
+     * The instant reply for a shopper's message, such as `on it, looking for usb-c cables under $20`, or
+     * null for a message that starts no search: `yes`, `1`, `ok`, a code, `hi`, or the shopper's own
+     * details, such as a name, a phone number or an address, and any message that answers a request for
+     * shipping or guest details or a code. Call it the moment the message arrives, before your model runs,
+     * and send the text it returns. The tool then sends no reply of its own through `onWorking` for that
+     * turn, and the model reads `shopper_already_told_looking`, so the shopper never hears it twice.
+     */
+    instantAck(shopperText: string): string | null;
 }
 /**
  * A buy tool for one shopper. With a company client, name the shopper with