@agent-cards/commerce-sdk 0.2.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 `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 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:
@@ -41,7 +74,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
 
@@ -101,10 +134,63 @@ 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. 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.
+
+## 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.
+
+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 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
+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:
@@ -163,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
 }
@@ -170,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 |
@@ -194,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:
@@ -231,7 +334,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 at a webhook endpoint
+
+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';
+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 +455,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,51 @@
+/**
+ * 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, 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;
+/** 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 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, 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
+ * 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

@@ -0,0 +1,166 @@
+/**
+ * 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('|') +
+    ')$');
+/** 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. */
+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, 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 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;
+    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) {
+    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 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, 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
+ * 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 instantAck(shopperText, options = {}) {
+    if (typeof options?.nextAction === 'string' && ANSWERED_STEPS.has(options.nextAction))
+        return null;
+    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/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 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;
@@ -62,6 +66,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;
@@ -102,12 +108,19 @@ 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;
     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 +149,44 @@ 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;
+    /**
+     * 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
@@ -177,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