@agent-cards/commerce-sdk 0.1.0 → 0.5.0

package/LICENSE

@@ -35,4 +35,4 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED. IN NO EVENT SHALL AGENTCARD CORPORATION BE LIABLE FOR ANY CLAIM,
 DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.
 
-Questions: legal@agentcard.sh
+Questions: legal@agentcard.com

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
 
@@ -101,10 +101,67 @@ 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 twenty 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`, and its id in `productId`. 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`, 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.
 
 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:
+
+```ts
+import { toMessages } from '@agent-cards/commerce-sdk';
+
+for (const text of toMessages(reply)) await textShopper(shopper.id, text);
+```
+
+`result.messages` from `buy.answer` holds Agentcard's own answer cut the same way, links included, so your code sends it without cutting it again.
+
+For a reply your model streams, `messageStream` hands over each paragraph the moment the blank line that ends it arrives, however the stream cuts the text. Push each piece of text, then call `end` for the last paragraph:
+
+```ts
+import { messageStream } from '@agent-cards/commerce-sdk';
+
+const paragraphs = messageStream({ onMessage: (text) => textShopper(shopper.id, text) });
+stream.on('text', (delta) => paragraphs.push(delta));
+await stream.done();
+await paragraphs.end();
+```
+
+`stream` stands for your model's streamed answer. When `onMessage` returns a promise, the stream waits for it before it sends the next paragraph, so the shopper reads them in order, and `end` resolves once every paragraph went out. After a send fails, no later paragraph goes out, and `end` rejects with that error. A paragraph inside a list waits for the first characters of the next line, which say whether the list goes on. Start a new `messageStream` for each model message, so one message never runs into the next.
+
 ## Sign up a new shopper
 
 A shopper who has not connected to your company yet gets a Vault link on their first call. The tool asks Agentcard for the link and hands it to `sendLink`, and the model reads `needs_card`. The shopper connects and adds a card on the Vault page, and the next call buys. Agentcard returns the same link while it has time left, so a shopper who asks twice gets one link.
@@ -206,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`:
 
@@ -279,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 BuyDeliveryAddress, 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';
 /**
@@ -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` and `productId`.
+ * `price`, `productId` and `imageUrl`.
  */
 export interface BuyToolLink {
     kind: 'vault' | 'approval' | 'store_login' | 'product';
@@ -55,10 +55,15 @@ export interface BuyToolLink {
     price?: string | null;
     /** On a product link: Agentcard's id for the product. */
     productId?: string;
+    /** On a product link: the product's picture, or null when Agentcard sent none. Show it beside the title. */
+    imageUrl?: string | null;
 }
 /** A product the last search found. */
 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;
@@ -80,6 +85,12 @@ export interface BuyToolResult {
     status: BuyToolStatus;
     /** Agentcard's answer for the shopper, links included. */
     reply: string;
+    /**
+     * The same answer as the separate messages a shopper reads one at a time, links included: each
+     * message Agentcard sent (the purchase answer's `messages`), cut at its blank lines by `toMessages`.
+     * An answer the tool wrote itself, such as `placing`, is `reply` cut the same way.
+     */
+    messages: string[];
     /** The cart on the table, or null. */
     cart: BuyCart | null;
     /** Every cart on the table, oldest first. */
@@ -97,6 +108,10 @@ export interface BuyToolResult {
     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. */
@@ -125,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