@agent-cards/commerce-sdk 0.10.0 → 0.13.0

package/README.md

@@ -39,7 +39,7 @@ agentcard.listen({
 });
 ```
 
-Once `onMessage` returns, the client keeps the message for that shopper's next `buy.turn`, and `turn.messages(history)` hands it to your model before the shopper's words, so the model knows the shopper saved a card or got an order. "Tell the model what Agentcard told the shopper" shows it.
+Once `onMessage` returns, the client keeps the message for that shopper's next `buy.turn`, and `turn.messages(history)` hands it to your model before the shopper's words, so the model knows the shopper saved a card or got an order. "Tell the model what Agentcard told the shopper" shows it. A message whose `advances` is true ends a step the shopper took outside the chat, such as saving a card: "Take the next step once the shopper finishes one outside the chat" shows how your agent moves on without waiting for their "ok".
 
 `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.
 
@@ -76,7 +76,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`, `new_order`, `product_id` and `store_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.
+The model sends `ask`, `confirm`, `new_order`, `product_id` and `store_id`, and nothing else. A product link the shopper sends, such as a `buy.trychannel3.com` link, goes in `ask` exactly as sent, and Agentcard buys that exact product from it. 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
 
@@ -136,12 +136,48 @@ 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`, 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. Each product gets its own link, so the three dishes a restaurant's reply offers are three cards, though they share the store's one page. A flight has no page at a store, so each flight a search finds is a `product` link whose `url` is null, with the airline, the route and its times in `title`: show it as a card with no link to open, and hand its `productId` back as the shopper's pick. The model reads `product_links_sent` and never a URL. The tool's description tells it that the shopper already sees those products as cards, so its reply never lists them again by name or price: it writes one short line, such as which one they want, and 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.
+The tool also hands `sendLink` a `product` link for each product a search finds, up to eight 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`, or `from $10.69` for a product priced by a size or another choice the shopper makes, such as a burger whose patty count sets its price, Agentcard's id for it in `productId`, what taking it does in `action` (`reserve` for a restaurant table, `book` for a flight, room, class or ticket, `buy` for anything else, so a button can say Reserve instead of Buy this), its picture in `imageUrl`, or null when the store sent none, and every photo of the product in `images`, `imageUrl` first and at most eight, so a card can show the others as thumbnails that swap the main picture. `images` holds one entry for a product with one photo and none for a product with 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. Each product gets its own link, so the three dishes a restaurant's reply offers are three cards, though they share the store's one page. A flight has no page at a store, so each flight a search finds is a `product` link whose `url` is null, with the airline, the route and its times in `title`: show it as a card with no link to open, and hand its `productId` back as the shopper's pick. The model reads `product_links_sent` and never a URL. The tool's description tells it that the shopper already sees those products as cards, so its reply never lists them again by name or price: it writes one short line, such as which one they want, and 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.
 
+## Open each step in a pop-up, and close it when it is done
+
+A Vault, approval or store login link is a step the shopper takes outside the chat. Each one carries a stable `id`, such as `vault_1x9k2qd`: the same every time the same link is handed over, on your server and in the browser, with no part of the URL in it, so it is safe as a DOM key or in a log. `actionLinkId(link)` reads it from a link that has none.
+
+Each step ends with a shopper message: `actionLinkOutcome(link, message)` says how a message ended the step, or null when it left it open. `ACTION_LINK_ENDINGS` is the whole table:
+
+| Link | `completed` | `declined` | `failed` | `expired` |
+| --- | --- | --- | --- | --- |
+| `vault` | `card_added` | | | `card_link_expired` |
+| `store_login` | `store_connected` | | `store_connect_failed` | `store_connect_expired` |
+| `approval` | `order_placed`, `order_not_placed_yet`, `order_unconfirmed`, `order_confirmed`, `order_failed`, `payment_declined` | `approval_declined` | | `approval_expired` |
+
+A reminder, such as `card_link_unfinished` or `approval_expiring`, leaves the step open. An approval is `completed` once the shopper approved, even when the order then failed or the payment was refused: the approval page has nothing more to do, and the message tells the shopper what happened. A message whose facts name another link of the same kind (`facts.approvalUrl`, `facts.cardLinkUrl`) leaves this one open, and so does one about another store: a store login link names its store in `store`, and so does an approval link when the answer names the cart's store, so DoorDash's `store_connected` (`facts.merchantName: 'DoorDash'`) never ends a Locale sign-in the shopper has open beside it.
+
+In the browser, `actionWindows` from `@agent-cards/commerce-sdk/browser` opens each step in a pop-up window centered over the chat, so the shopper never leaves it, and closes the pop-up the moment the message that ends the step arrives. The browser entry imports no Node module, so any bundler takes it:
+
+```ts
+import { actionWindows } from '@agent-cards/commerce-sdk/browser';
+
+const windows = actionWindows({
+  onEnded: (step, outcome) => markStepDone(step.id, outcome),
+  onClosed: (step) => keepOfferingStep(step.id),
+});
+
+// The link's own click handler, so the browser counts the tap as the reason for the pop-up. When the
+// browser blocks it, `open` returns null and the link opens the way it would have, as a new tab.
+stepLink.addEventListener('click', (event) => {
+  if (windows.open(link)) event.preventDefault();
+});
+
+// Each shopper message your server forwards from `listen` or the webhook, with its `kind` and `facts`.
+onShopperMessage((message) => windows.settle(message));
+```
+
+`markStepDone`, `keepOfferingStep` and `onShopperMessage` stand for your own code. `settle` closes each open pop-up whose step the message ends and returns `[{ step, outcome }]`. A pop-up the shopper closes before the step ends reaches `onClosed`, checked every 500 milliseconds (`pollMs`): the step is still open, so keep its link on screen, and a tap opens it again. Tapping a step whose pop-up is open brings that window to the front instead of opening a second one. A phone's browser opens the pop-up as a tab, and `settle` closes that tab the same way, since the chat opened it. The pop-up is 480 by 760 pixels by default (`width`, `height`), kept inside the screen. It keeps its opener on purpose: a window opened with `noopener` hands back no handle, so the chat could neither close it nor tell when the shopper closed it. `dispose()` stops watching and leaves every pop-up open, so a chat that remounts never shuts the page a shopper is typing a card into.
+
 ## Answer each shopper message in its own turn
 
 A shopper can send a second message before the first is answered. The `sendLink`, `onWorking` and `onResult` you pass to `buyTool` hear every call, whichever message the call answers, so a callback that hands each link to "the message running now" gives the first message's cards to the second. Open a turn for each message instead, and pass the turn to your model in place of the tool:
@@ -150,7 +186,7 @@ A shopper can send a second message before the first is answered. The `sendLink`
 const buy = buyTool({ agentcard, externalUserId: shopper.id }); // one per shopper, kept
 
 async function onShopperMessage(message: string) {
-  const turn = buy.turn(message, { onWorking: (text) => textShopper(shopper.id, text) });
+  const turn = buy.turn(message, { onReaction: (emoji) => reactToShopperMessage(shopper.id, emoji) });
   const runner = new Anthropic().beta.messages.toolRunner({
     model: 'claude-opus-5-5',
     max_tokens: 16000,
@@ -167,14 +203,39 @@ async function onShopperMessage(message: string) {
 
 - `turn.links` holds each link the turn's calls handed over, in order: the Vault, approval and store login links, each product's store page, and each store card's page. The model reads that each one went out, so send them with the reply. Pass `sendLink` to `buy.turn` as well to send each one the moment the tool hands it over, such as down a server-sent event stream. A link your `sendLink` throws on stays out of `turn.links`.
 - `turn.results` holds the whole answer of each call, and an `onResult` passed to `buy.turn` hears each one as it arrives.
-- With `onWorking`, `buy.turn` sends the instant reply at once, before your model runs: the one `buy.instantAck` would return, or the one your `ack` function writes. You never call `instantAck` yourself. A slow call of the turn sends its reply to that `onWorking` too, and `turn.ack` holds the text the turn sent when it opened.
+- With `onReaction`, `buy.turn` puts a 👀 on a message that starts a search at once, before your model runs, and `turn.reaction` holds it. With only `onWorking`, it sends the text reply `buy.instantAck` would return, or the one your `ack` function writes, and `turn.ack` holds that text. You never call `instantReaction` or `instantAck` yourself. A slow call of the turn acknowledges through the same callback.
 - An `onProgress` passed to `buy.turn` hears only that turn's stages.
 - `turn.agentcardMessages` holds each message `agentcard.listen` or `agentcardWebhook` posted into this shopper's chat that the model has not read yet, and `turn.messages(history)` hands them to the model.
 
-A callback you leave out of `buy.turn` falls back to the one the tool was built with, so a tool whose `sendLink` texts the shopper keeps texting, and `turn.links` lists the same links. The turn is the tool, with the same name, schema and methods, so pass it to every framework the way you pass `buy`: `tools: [turn]`, `tools: { buy: turn }`, `tools: [turn.openai]` with `turn.handle`, or `toOpenRouterTool(turn, { tool, z })`. `turn.ack`, `turn.links` and `turn.results` stay out of the tool's JSON, so a tool runner sends the API the same fields. Build the tool once per shopper and open a turn from it for each message: the turns share the shopper's conversation, so a card a shopper already holds from an earlier turn is not sent again.
+A callback you leave out of `buy.turn` falls back to the one the tool was built with, so a tool whose `sendLink` texts the shopper keeps texting, and `turn.links` lists the same links. The turn is the tool, with the same name, schema and methods, so pass it to every framework the way you pass `buy`: `tools: [turn]`, `tools: { buy: turn }`, `tools: [turn.openai]` with `turn.handle`, or `toOpenRouterTool(turn, { tool, z })`. `turn.ack`, `turn.reaction`, `turn.links` and `turn.results` stay out of the tool's JSON, so a tool runner sends the API the same fields. Build the tool once per shopper and open a turn from it for each message: the turns share the shopper's conversation, so a card a shopper already holds from an earlier turn is not sent again.
 
 A call made on `buy` itself still works as before: it belongs to the turn the tool reads from its timing, and its links go to the tool's `sendLink`.
 
+### Show Agentcard's reply as written
+
+Most answers only ask the shopper something: which product, which size, which store, or a yes to a cart's total. Agentcard's reply already says that, so a second model call that rewords it costs the shopper one more model round trip and changes nothing. Pass `replyAsWritten: true`, to `buyTool` for every turn or to `buy.turn` for one, and `turn.replyAsWritten` holds Agentcard's reply, with every link taken out, whenever the turn's last answer only asks. Show it and end the turn without calling your model again:
+
+```ts
+const turn = buy.turn(message, { replyAsWritten: true, onMessage: (text) => sendText(shopper.id, text) });
+const runner = new Anthropic().beta.messages.toolRunner({ model: 'claude-sonnet-5-5', max_tokens: 16000, tools: [turn], messages: turn.messages(history), stream: true });
+let written: string | null = null;
+for await (const stream of runner) {
+  written = turn.replyAsWritten;
+  if (written !== null) {
+    stream.abort(); // the reply says it already: no second model call
+    break;
+  }
+  const paragraphs = turn.messageStream();
+  stream.on('text', (delta) => paragraphs.push(delta));
+  await stream.done();
+  await paragraphs.end();
+}
+if (written !== null) await turn.say(written);
+history = written !== null ? [...runner.params.messages, { role: 'assistant', content: written }] : runner.params.messages;
+```
+
+Any other answer, such as an approval sent, an order placed or a refusal, leaves `turn.replyAsWritten` null, and your model words it. So does a line the tool writes itself for your model, such as the note that the cart changed or a `buy.nextStep` turn's ask for the shopper's yes: only a reply Agentcard sent goes out as written. `replyAsWritten(result)` applies the same rule to one answer, for a loop that reads `turn.results` itself. Leave the option off to have your model write every answer.
+
 ### Hand the app the turn in order
 
 A turn reaches the shopper as messages and links that interleave: the instant reply, the cards a search found, then your model's words about them. Pass `onItem` to `buy.turn`, and the turn hands your app all of them as one sequence, one item at a time, in the order they happened. Show each item below the one before it:
@@ -194,9 +255,11 @@ for await (const stream of runner) {
 ```
 
 - A `text` item is the instant reply, or a message your model wrote through `turn.messageStream()` or `turn.say(text)`. A `link` item is each link the tool hands over, with the fields `sendLink` would get.
-- Messages arrive one at a time, like someone texting. Each one waits until `typingDelay` of it has passed since the item before it went out: 300 ms, plus 12 ms a character, at most 1.5 seconds. Time your model spent writing counts toward the pause, so a slow model gets no added wait, and links never wait. `onTyping` hears `true` when a pause starts and `false` when its message goes out. Pass `pace: false` to send each message the moment it is ready, or a function that returns the pause in milliseconds.
+- Each message goes out the moment it is ready. Pass `pace: true` to space them like someone texting: each one then waits until `typingDelay` of it has passed since the item before it went out, 300 ms plus 12 ms a character, at most 1.5 seconds. Time your model spent writing counts toward the pause, so a slow model gets no added wait, and links never wait. `onTyping` hears `true` when a pause starts and `false` when its message goes out. A function returns your own pause in milliseconds.
 - With `onItem`, the turn sends no link to a `sendLink` and no instant reply to an `onWorking`, so a tool built with those for other turns sends nothing twice. Passing `onItem` beside `sendLink` or `onWorking` to the same turn throws.
 - `turn.items` holds every item that went out, in order, so an app that answers the whole turn at once returns it as is. A turn without `onItem` keeps `turn.items` as well, unpaced.
+- A step link, the `vault`, `approval` or `store_login` page the shopper opens to go on, comes after the message that asks for it: the turn holds it until your model's next message stream ends (or `turn.say` is called), then sends it right after that message, so the shopper reads "add your card to place the order" and then taps. Product and store cards go out the moment the tool hands them over. A held link also goes out when the turn's next call starts, or after 20 seconds, so a model that writes nothing still sends it. `turn.say` and the stream's `end` resolve once the held links went out too, and reject when one failed to send, so your app never answers without a link the shopper needs; a link that failed to go out at the next call or the 20 seconds rejects the next reply that ends.
+- Without `onItem`, pass `onMessage` beside `sendLink`, and write the model's text through `turn.messageStream()`: `onMessage` hears each message, paced, and `sendLink` hears each step link after the message that asks for it. An app that streams the model through the package's own `messageStream` gets each link the moment the tool hands it over, before the words about it.
 
 ## Tell the model what Agentcard told the shopper
 
@@ -227,6 +290,57 @@ With a webhook, pass the client to the handler: `agentcardWebhook({ secret, agen
 
 The messages live in the client's memory, at most 20 per shopper. So the listener, or the webhook, and the turn have to run in one process on one client. When your listener runs in one process and your model in another, such as a serverless chat route, keep each message where your chat history lives as `onMessage` delivers it, as an assistant message, and the model reads it from the history.
 
+## Take the next step once the shopper finishes one outside the chat
+
+Some steps happen outside the chat: the shopper saves a card from the Vault link, signs in to DoorDash from the sign-in link, or declines the approval. Agentcard tells your server the moment each one ends, and its message reads like `Your Visa ending 4242 is saved, so you're ready to check out.`. Posted as is, it leaves the shopper to say "ok" or "done" before anything moves. Take the next step for them instead: when `message.advances` is true, open `buy.nextStep(message)` and run your model on it, and post the model's answer in place of `message.text`:
+
+```ts
+/** Each shopper's model runs, in order: the chat's own turns should wait on it too. */
+const runs = new Map<string, Promise<void>>();
+
+agentcard.listen({
+  onMessage: (shopperId, message) => {
+    const step = buyFor(shopperId).nextStep(message);
+    if (!step) return postToChat(shopperId, message.text);
+    // Run it without awaiting, so the listener moves on to the next event. One shopper's runs go in order, after
+    // their last one, so an older run never writes its history over a newer one.
+    // A turn that fails is released, so its text reaches later turns and a redelivery can take the step again.
+    const run = (runs.get(shopperId) ?? Promise.resolve()).then(() => runModel(shopperId, step)).catch(() => {
+      step.release();
+      agentcard.delivered(shopperId, message);
+      postToChat(shopperId, message.text);
+    });
+    runs.set(shopperId, run);
+  },
+});
+
+async function runModel(shopperId: string, turn: BuyToolTurn) {
+  const runner = anthropic.beta.messages.toolRunner({ model: 'claude-opus-5-5', max_tokens: 16000, tools: [turn], messages: turn.messages(histories.get(shopperId)) });
+  const answer = await runner;
+  histories.set(shopperId, runner.params.messages);
+  postToChat(shopperId, textOf(answer), turn.links);
+}
+```
+
+`buyFor` stands for the buy tool you keep for each shopper, and `textOf` for the text of the model's answer. The turn is a `buy.turn` in every way but one: no shopper wrote anything, so `turn.messages(history)` ends with the event, marked as written by the system, and the instruction to take the next step now in one short message, never "you're all set, what's next?". The shopper reads one message that does the next thing:
+
+| The shopper finished | The next message |
+| --- | --- |
+| Saving a card, after their yes stopped for it | The approval link: `i sent you a link to approve the payment for your chicken salad. it works for about 15 minutes, and the most you'll be charged is $19.02.` |
+| Saving a card, with no yes yet | The total and the ask for the yes: `your Souvla chicken salad comes to $17.43 with fees. should i go ahead and place the order?` |
+| Signing in to the store, with a card still to add | The add-card link: `next, add a card with the link i sent. it works for about 24 hours.` |
+| Signing in to the store, with a card on file | The total and the ask for the yes, or the approval link after a yes that stopped for the sign-in |
+| Declining the approval | `you declined the payment, so you haven't been charged. your chicken salad is still in the cart, so just say yes if you want a new approval link, or tell me what to change` |
+
+The turn moves the purchase only up to the shopper's own decision, and the tool holds it there whatever the model calls:
+
+- No call of the turn sends an ask to Agentcard, which could read the model's words as the shopper's go-ahead. Each call reads where the purchase stands and answers with the next step: the card link the sign-in held back, or the cart and the ask for the shopper's yes.
+- A confirm goes in only for the yes the shopper already gave in the chat, such as "lets place it", when that confirm stopped for the card or the sign-in they just finished. It goes in once, for that cart's hash, so Agentcard refuses it if the cart changed. A shopper message after the yes that is not a plain go-ahead, such as "wait, make it two", takes it back. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard.
+- The approval in the Vault is still the shopper's: the confirm sends the approval link, and the order goes in only once they approve it.
+- A shopper who was not connected yet when they asked gets their own first ask run, in their words, once their card is saved.
+
+`buy.nextStep` returns null when there is no step to take: a message whose `advances` is false, such as `order_placed`, whose `text` is already the whole message; a message for another shopper, or one whose link closed; a message it already took a turn for; and one that arrives while a call for the shopper's own message is still running, since that call's answer tells the model where the purchase stands. Post `message.text` then. `NEXT_STEP_KINDS` lists the kinds that advance: `card_added`, `store_connected` and `approval_declined`. Once `buy.nextStep` opens a turn, the client never hands the message's text to a later turn as words the shopper read, since they never read it. When your agent cannot finish the turn, call `step.release()` before you post `message.text`: the text then reaches later turns once `agentcard.delivered` records it, and a redelivery of the event opens a turn again.
+
 ## 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.
@@ -235,7 +349,7 @@ Each product in the model's view carries a `product_id`, Agentcard's id for it w
 
 ## Show the stores the shopper picks from
 
-A delivery order often starts with a choice of store: the shopper asks for a taco, and Agentcard answers with the taquerias near them that deliver. Each store the reply names reaches `sendLink` as a `store` link, up to three per answer, in the order the reply names them. The link carries the store's page at the merchant in `url`, its name in `title`, Agentcard's id for it in `storeId`, the delivery estimate in minutes in `etaMinutes`, or null when the store showed none, and the picture the store's card shows at the merchant in `imageUrl`, or null when it shows none. Show it as a card with the picture and an "Order here" button. `result.stores` carries the same stores for your code, each with its `url` and `linkSent`.
+A delivery order often starts with a choice of store: the shopper asks for a taco, and Agentcard answers with the taquerias near them that deliver. Each store the reply names reaches `sendLink` as a `store` link, up to eight per answer, in the order the reply names them. The link carries the store's page at the merchant in `url`, its name in `title`, Agentcard's id for it in `storeId`, the delivery estimate in minutes in `etaMinutes`, or null when the store showed none, and the picture the store's card shows at the merchant in `imageUrl`, or null when it shows none. Show it as a card with the picture and an "Order here" button. `result.stores` carries the same stores for your code, each with its `url` and `linkSent`.
 
 The model reads each store in `stores` by its `store_id`, name and `eta_minutes`, never its page, and `store_links_sent` says how many store pages the shopper holds. When the shopper picks a store, by its name, its place in the list or a tap on its card, the model passes that `store_id`, and Agentcard selects exactly that store before its agent answers, so the products it finds next are from that store. A card's button can call `buy.answer` with the link's `storeId` as `store_id`. A shopper who answers only with a place in the list, such as `the second one` or `2`, picks the store at that place in the last answer's list, whether or not the model passed the id. A store pick starts no search, so it gets no instant reply: a card tap that sends `Order from Tacos El Grullense`, the store's name alone or with `please`, and `order here` or `this place` all read as a pick of a store the last answer listed. A dish beside the store's name, as in `order tacos from el farolito`, is a search.
 
@@ -245,35 +359,62 @@ The tool sends each store page once for the calls the model makes in one turn. A
 
 ## 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`:
+A first search can take Agentcard most of a minute. Pass `onReaction`, and the shopper sees a 👀 on their own message while Agentcard looks, the way a friend reacts to a text before answering it. Show it as a tapback on the shopper's bubble:
 
 ```ts
 const buy = buyTool({
   agentcard,
   externalUserId: shopper.id,
   sendLink: (link) => textShopper(shopper.id, link.url),
+  onReaction: (emoji) => reactToShopperMessage(shopper.id, emoji), // emoji is always '👀'
+});
+```
+
+A reaction is the default acknowledgement. It names nothing the shopper said, so it never reads a request back wrong, and the chat holds only real answers. Each message gets at most one 👀:
+
+- A message that starts a search gets it the moment `buy.turn` opens, before your model runs.
+- A pick of a product or a store the shopper saw, an address or other details, an answer to a question such as `yes`, `2` or a code, a step toward checkout such as `ok lets checkout`, and an acknowledgement such as `its ok` get none when the turn opens, because Agentcard answers them fast.
+- A call that Agentcard has not answered within 1.5 seconds puts the 👀 on a message that has none yet: a slow `yes`, a pick, or a confirm that is still placing the order. It sends no text.
+- A turn that runs long, even past a minute, still gets no text line. A search often takes 10 to 40 seconds, so a line at any wait short enough to help would land on most searches and bring back the chatter the reaction replaces. To show a long wait, pass `onProgress` and show its stage, such as `checking_out`, as a status line or a typing indicator.
+
+With `onItem` on `buy.turn`, the 👀 still goes to `onReaction` and never joins the turn's items, because it sits on the shopper's bubble rather than in the agent's sequence. Without an `onReaction`, the text instant reply is the turn's first `text` item, as before.
+
+When the 👀 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 reply opens with the answer or the question rather than `on it`. It reads false on a turn that reacted with nothing, and when `onReaction` threw. An `onReaction` that throws costs only the reaction.
+
+### Acknowledge in text, or not at all
+
+For SMS, or any chat that shows no reactions, acknowledge in text. Pass `onWorking` and no `onReaction`, or set `ack: 'text'`, and the shopper reads an instant reply instead, 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,
+  ack: 'text',
   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. A slow confirm or pick never hears `looking for`: a pick of a product the shopper saw hears `adding it now`, a pick of a store or a place in a list, such as `the first one`, hears `got it, one moment`, and a confirm hears `on it, one moment`. None of them names anything the shopper said, and a code hears nothing. 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.
+`ack` takes `'reaction'`, `'text'` or `'none'`. Left out, the tool reacts when the tool or the turn has an `onReaction`, and sends text through `onWorking` otherwise, so an app built on 0.9 with only `onWorking` keeps its text replies. With both callbacks, the shopper gets the 👀 and never the text too. `'none'`, or `false`, sends nothing.
 
-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.
+In text mode, 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. A slow confirm or pick never hears `looking for`: a pick of a product the shopper saw hears `adding it now`, a pick of a store or a place in a list, such as `the first one`, hears `got it, one moment`, and a confirm hears `on it, one moment`. None of them names anything the shopper said, and a code hears nothing. 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.
+Pass `ack: (ask) => text` to write your own text from the shopper's words, where an empty answer sends none, and `ackDelayMs` to change the 1.5 seconds for either mode.
 
-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:
+The model takes several seconds to call the tool after the shopper's message arrives. Without `buy.turn`, react sooner by calling `buy.instantReaction(message)` the moment the message arrives, before your model runs, and put the emoji it returns on the message. In text mode, call `buy.instantAck(message)` and send the text it returns:
 
 ```ts
+const reaction = buy.instantReaction(message); // '👀' or null
+if (reaction) await reactToShopperMessage(shopper.id, reaction);
+// In text mode instead:
 const ack = buy.instantAck(message);
 if (ack) await textShopper(shopper.id, ack);
 ```
 
-With `buy.turn`, pass `onWorking` to the turn instead: it sends the same reply the moment the turn opens, and calls `instantAck` for you.
+With `buy.turn`, pass `onReaction` or `onWorking` to the turn instead: it acknowledges the moment the turn opens, and calls `instantReaction` or `instantAck` for you. When either returns a 👀 or a reply, the tool sends none of its own for that turn.
 
-`instantAck` returns null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a step toward paying for the cart such as `ok lets checkout`, `place the order` or `pay`, an acknowledgement such as `its ok`, `thats fine` or `sounds good`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a pick of a store, such as `order here` or a store card's `Order from Tacos El Grullense`, 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, a bare house number and street such as `1801 wedemeyer`, or a zip code, any message that answers the last answer's request for an address, shipping or guest details or a code, and a short reply right after any other question the last answer asked, such as `im a 37` after `what size do you want?`, or `carne asada` after `which meat?`. A reply that opens a new request, such as `find me black running shoes`, or that runs past four words is still a search. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed, or names one of the stores its last answer listed and nothing else to buy, as a pick of it. A request for a store the shopper did not see, such as `order from chipotle`, reads back as `looking for chipotle`, never `looking for from chipotle`. When it returns a reply, the tool sends none of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still sends `onWorking` a reply that names nothing and never says it is looking for anything, such as `working on it` or `one moment`, and when it returns null for a pick, such a call sends `adding it now` or `got it, one moment`.
+`instantReaction` and `instantAck` return null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a step toward paying for the cart such as `ok lets checkout`, `place the order` or `pay`, an acknowledgement such as `its ok`, `thats fine` or `sounds good`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a pick of a store, such as `order here` or a store card's `Order from Tacos El Grullense`, 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, a bare house number and street such as `1801 wedemeyer`, or a zip code, any message that answers the last answer's request for an address, shipping or guest details or a code, and a short reply right after any other question the last answer asked, such as `im a 37` after `what size do you want?`, or `carne asada` after `which meat?`. A reply that opens a new request, such as `find me black running shoes`, or that runs past four words is still a search. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed, or names one of the stores its last answer listed and nothing else to buy, as a pick of it. A request for a store the shopper did not see, such as `order from chipotle`, reads back as `looking for chipotle`, never `looking for from chipotle`. When it returns a reply, the tool sends none of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still acknowledges: with a 👀 in reaction mode, and in text mode with an `onWorking` reply that names nothing and never says it is looking for anything, such as `working on it` or `one moment`, and when it returns null for a pick, such a call sends `adding it now` or `got it, one moment`.
 
-Without a buy tool, `instantAck(message, { previous, nextAction, asked, stores })` from the package root decides the same way: `previous` is the reply you sent last, so the next one comes from another template, `nextAction` is the last answer's `next_action`, `asked` is the last message the shopper read, so an answer to its question for an address, a name or a code, or a short answer to any other question it asked, gets none, and `stores` holds the names of the stores the last answer listed, so a message that picks one gets none. Pass `ack: false` to the tool when you send it yourself. `ackFor` is the earlier name of the same function.
+Without a buy tool, `instantReaction(message, { nextAction, asked, stores })` and `instantAck(message, { previous, nextAction, asked, stores })` from the package root decide the same way, and `ACK_REACTION` is the `👀` `instantReaction` returns: `previous` is the reply you sent last, so the next one comes from another template, `nextAction` is the last answer's `next_action`, `asked` is the last message the shopper read, so an answer to its question for an address, a name or a code, or a short answer to any other question it asked, gets none, and `stores` holds the names of the stores the last answer listed, so a message that picks one gets none. Pass `ack: 'none'` to the tool when you acknowledge yourself. `ackFor` is the earlier name of the same function.
 
 ## Show what Agentcard is doing
 
@@ -315,7 +456,7 @@ await paragraphs.end();
 
 `stream` stands for your model's streamed answer. `toMessages` and `messageStream` keep nothing between two texts, so a shopper's overlapping messages never mix in them: the paragraphs of one model message go to the `onMessage` of its own stream, and the links of that turn's tool calls are in its `turn.links`. 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.
 
-A model often writes three paragraphs within 200 ms, and a shopper who gets them at once reads a wall, not a conversation. So `messageStream` spaces them like someone texting: the first goes out at once, and each one after it waits until `typingDelay` of it has passed since the one before, at most 1.5 seconds. Time the model spent writing counts toward the pause, so a slow model gets no added wait. Pass `onTyping` to show a typing indicator during each pause, `pace: false` to hand each paragraph over the moment it is cut, or `pace: (text) => ms` for your own pause. With `buy.turn`'s `onItem`, use `turn.messageStream()` instead, which spaces the model's messages after the cards and the instant reply too.
+Each paragraph goes out the moment it is cut. To space them like someone texting, pass `pace: true`: the first goes out at once, and each one after it waits until `typingDelay` of it has passed since the one before, at most 1.5 seconds. Time the model spent writing counts toward the pause, so a slow model gets no added wait. Pass `onTyping` to show a typing indicator during each pause, or `pace: (text) => ms` for your own pause. With `buy.turn`'s `onItem`, use `turn.messageStream()` instead, which keeps the model's messages after the cards and the instant reply too.
 
 ## Sign up a new shopper
 
@@ -470,12 +611,15 @@ Subscribe your endpoint to each event below by name. A catch-all `*` alone does
 | 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` | `store_connected` | The shopper signed in to their own account at the store from the sign-in link your app sent. | 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` | `approval_declined` | The shopper declined the approval, and no charge went through. | Agentcard |
+| `purchase.message` | `payment_declined` | The shopper approved, and the payment was refused before the order went in, such as a declined card. `facts.reason` says why. 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 |
@@ -561,11 +705,19 @@ The facts are `merchantName`, `totalCents`, `currency`, `cardBrand`, `cardLast4`
 | `order_not_placed_yet` | The shopper approved, and the order is not placed yet. |
 | `approval_expiring` | The approval link expires soon. `text` carries the link. |
 | `approval_expired` | The approval expired before the shopper answered, and no charge went through. |
+| `approval_declined` | The shopper declined the approval, and no charge went through. |
+| `payment_declined` | The shopper approved, and the payment was refused before the order went in. `facts.reason` says why. |
 | `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. |
+| `store_connected` | The shopper signed in to their own account at the store from the sign-in link your app sent, such as DoorDash, so the order can go through on it. |
+| `store_connect_failed` | The shopper's sign-in to the store did not go through, and the link no longer works. `text` offers a new one. |
+| `store_connect_expired` | The sign-in link expired before the shopper finished signing in. `text` offers a new one. |
+| `cart_ready` | The store's checkout built the cart an answer named as still being built (`cart_building`). `text` gives the store's own total, and nothing is paid until the shopper says yes to it. |
+| `cart_needs_input` | That checkout asks the shopper something first, such as a size, a delivery address, a sign-in to the store or an approval of the most the order can cost. Their reply continues the cart. |
+| `cart_failed` | That checkout built no cart, and nothing was ordered or charged. |
 
 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

@@ -89,5 +89,34 @@ export declare function answersQuestion(text: string, asked: string | null | und
  * ```
  */
 export declare function instantAck(shopperText: string, options?: AckForOptions): string | null;
+/**
+ * The reaction the tool puts on a shopper's message to say it is on it: 👀, as a chat app shows a
+ * tapback on the shopper's own bubble. It names nothing the shopper said, so it can never read a
+ * request back wrong.
+ */
+export declare const ACK_REACTION = "\uD83D\uDC40";
+/**
+ * The reaction for a shopper's message, `👀`, or null for a message that starts no search. It reads the
+ * message exactly as `instantAck` does, so a pick, an address, an answer to a question, a step toward
+ * checkout or an acknowledgement such as `its ok` gets none.
+ *
+ * ```ts
+ * instantReaction('can you find me usb-c cables under $20'); // '👀'
+ * instantReaction('yes'); // null
+ * ```
+ */
+export declare function instantReaction(shopperText: string, options?: AckForOptions): string | null;
+/**
+ * True when the shopper's words leave a yes they already gave standing: an acknowledgement such as
+ * `ok` or `sounds good`, a go-ahead such as `lets place it`, or a report that they took the step they
+ * were sent, such as `done` or `signed in`. False for anything else, `wait`, `no`, `cancel`, a
+ * question or a new request among them, which a yes given before it does not cover.
+ *
+ * ```ts
+ * keepsYes('ok done'); // true
+ * keepsYes('wait, make it two'); // false
+ * ```
+ */
+export declare function keepsYes(shopperText: string): boolean;
 /** 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

@@ -67,6 +67,13 @@ const CART_COMMAND = new RegExp('^(?:(?:ok|okay|so|actually|wait|and|um|uh)[\\s,
     ')\\b');
 /** 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)$/;
+/**
+ * A question about what the agent can buy or where it shops, such as `what stores can you buy from`,
+ * `where can you shop` or `which stores do you support`: the model answers it in a line or two, with no
+ * search, so no instant reply says it is looking. A question that names a product, such as `which stores
+ * can you buy aa batteries from`, is a search and keeps its reply.
+ */
+const CAPABILITY = /^(?:(?:ok|okay|so|and|but|hey|hi|um|uh|also|wait)[\s,]+)*(?:(?:what|which|where)(?: (?:kinds?|types?|sorts?) of)?(?: (?:other|else|all|the))?(?: (?:stores?|shops?|places?|sites?|websites?|merchants?|retailers?|restaurants?|brands?|products?|items?|things?|stuff))?(?: else)? (?:can|do|could|will|are) (?:you|u)(?: (?:able to|even|actually|also))? (?:buy|shop|order|get|purchase|do|use|support|work with|deliver|cover|access|sell|carry|offer|stock)(?: (?:from|at|on|in|with|for me|for us|to))?(?: for me)?|(?:what|which) (?:stores?|shops?|merchants?|retailers?|sites?) (?:are )?(?:supported|available|connected|on here)|(?:what|which) (?:stores?|shops?|merchants?|retailers?) do (?:you|u) (?:have|know|use|support|work with)|what (?:else )?(?:do|can) (?:you|u) (?:offer|sell|carry|get (?:me|us)|buy (?:me|us)|order (?:me|us)|find (?:me|us)))(?: (?:right now|here|today))?$/;
 /** 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)';
 /**
@@ -237,7 +244,7 @@ export function isNewRequest(text) {
     const bare = words.replace(FILLER, '');
     if (bare === '' || ACKNOWLEDGED.test(bare) || CHECKOUT.test(bare))
         return false;
-    return !ANSWERS.test(words) && !STATUS.test(words) && !ABOUT.test(words) && !CART_COMMAND.test(words) && !CODE.test(words) && !CHITCHAT.test(words) && !isPick(line, words);
+    return !ANSWERS.test(words) && !STATUS.test(words) && !ABOUT.test(words) && !CART_COMMAND.test(words) && !CODE.test(words) && !CHITCHAT.test(words) && !CAPABILITY.test(words) && !isPick(line, 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) {
@@ -369,6 +376,46 @@ export function instantAck(shopperText, options = {}) {
         return null;
     return ackAt(nextTemplate(templateOf(options?.previous)), shopperText);
 }
+/**
+ * The reaction the tool puts on a shopper's message to say it is on it: 👀, as a chat app shows a
+ * tapback on the shopper's own bubble. It names nothing the shopper said, so it can never read a
+ * request back wrong.
+ */
+export const ACK_REACTION = '👀';
+/**
+ * The reaction for a shopper's message, `👀`, or null for a message that starts no search. It reads the
+ * message exactly as `instantAck` does, so a pick, an address, an answer to a question, a step toward
+ * checkout or an acknowledgement such as `its ok` gets none.
+ *
+ * ```ts
+ * instantReaction('can you find me usb-c cables under $20'); // '👀'
+ * instantReaction('yes'); // null
+ * ```
+ */
+export function instantReaction(shopperText, options = {}) {
+    return instantAck(shopperText, options) === null ? null : ACK_REACTION;
+}
+/**
+ * True when the shopper's words leave a yes they already gave standing: an acknowledgement such as
+ * `ok` or `sounds good`, a go-ahead such as `lets place it`, or a report that they took the step they
+ * were sent, such as `done` or `signed in`. False for anything else, `wait`, `no`, `cancel`, a
+ * question or a new request among them, which a yes given before it does not cover.
+ *
+ * ```ts
+ * keepsYes('ok done'); // true
+ * keepsYes('wait, make it two'); // false
+ * ```
+ */
+export function keepsYes(shopperText) {
+    const words = plain(String(shopperText ?? '')).replace(/[!?.,;:]+/g, ' ').replace(/\b(?:please|pls|thanks|thank you|thx|ty)\b/g, ' ').replace(/\s+/g, ' ').trim();
+    if (words === '')
+        return false;
+    const bare = words.replace(FILLER, '');
+    if (bare === '')
+        return true;
+    // A report after filler ("well signed in", "k connected") is read on its bare words too (review of #9220).
+    return ACKNOWLEDGED.test(bare) || CHECKOUT.test(bare) || STATUS.test(words) || STATUS.test(bare) || /^(?:done|added(?: it)?|i added(?: it| the card| a card)?)$/.test(bare);
+}
 /** The earlier name of `instantAck`, kept for apps that call it. */
 export function ackFor(text, options = {}) {
     return instantAck(text, options);

package/dist/action-links.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The steps a shopper takes outside the chat: adding a card (`vault`), signing in to a store
+ * (`store_login`) and approving a payment (`approval`). Each one is a link the buy tool hands over,
+ * and each one ends with a shopper message Agentcard sends: this file says which message ends which
+ * link, and how. It imports nothing, so a browser bundle can use it as well as a server.
+ */
+/** A link the shopper opens to do something outside the chat. */
+export type ActionLinkKind = 'vault' | 'store_login' | 'approval';
+/** The kinds of link that are a step outside the chat. */
+export declare const ACTION_LINK_KINDS: readonly ActionLinkKind[];
+/**
+ * How a step ended:
+ * - `completed`: the shopper finished it: a card saved, a store signed in to, a payment approved.
+ *   An approval stays `completed` when the order then failed or the payment was refused, since the
+ *   page has nothing more to do; the message itself tells the shopper what happened next.
+ * - `declined`: the shopper declined the payment on the approval page.
+ * - `failed`: the step did not go through, and its link no longer works (a store sign-in that failed).
+ * - `expired`: the link expired before the shopper finished.
+ */
+export type ActionLinkOutcome = 'completed' | 'declined' | 'failed' | 'expired';
+/**
+ * For each kind of step, the shopper message kinds that end it, and how. Every other message kind,
+ * such as `card_link_unfinished` or `approval_expiring`, leaves the step open.
+ */
+export declare const ACTION_LINK_ENDINGS: Readonly<Record<ActionLinkKind, Readonly<Record<string, ActionLinkOutcome>>>>;
+/** Whether a link is a step outside the chat: a `vault`, `store_login` or `approval` link with a page to open. */
+export declare function isActionLink<T extends {
+    kind: string;
+    url?: string | null;
+}>(link: T): link is T & {
+    kind: ActionLinkKind;
+    url: string;
+};
+/**
+ * A stable id for a step's link, such as `vault_1x9k2qd`: the same for the same link every time it is
+ * handed over, on the server and in the browser, and with no part of the URL in it, so it is safe in
+ * a log, a DOM key or a window name. The buy tool puts it on each step link as `id`.
+ */
+export declare function actionLinkId(link: {
+    kind: string;
+    url: string;
+}): string;
+/** What `actionLinkOutcome` reads of a shopper message: its kind, and the link URLs and the store its facts name, when they name them. */
+export interface ActionLinkMessage {
+    kind: string;
+    facts?: {
+        approvalUrl?: string;
+        cardLinkUrl?: string;
+        merchantName?: string;
+    } | null;
+}
+/**
+ * How `message` ends the step `link` is, or null when it leaves it open: a message about another
+ * kind of step, a reminder such as `card_link_unfinished`, a message whose facts name another link of
+ * the same kind (`facts.approvalUrl` or `facts.cardLinkUrl`), or one about another store: a store
+ * login or an approval link that names its `store` stays open when `facts.merchantName` names a
+ * different one, since a shopper can sign in to two stores, or approve two stores' carts, at once.
+ * A message whose facts name neither ends the shopper's open step of its kind.
+ */
+export declare function actionLinkOutcome(link: {
+    kind: string;
+    url?: string | null;
+    store?: string | null;
+}, message: ActionLinkMessage): ActionLinkOutcome | null;

package/dist/action-links.js

@@ -0,0 +1,77 @@
+/**
+ * The steps a shopper takes outside the chat: adding a card (`vault`), signing in to a store
+ * (`store_login`) and approving a payment (`approval`). Each one is a link the buy tool hands over,
+ * and each one ends with a shopper message Agentcard sends: this file says which message ends which
+ * link, and how. It imports nothing, so a browser bundle can use it as well as a server.
+ */
+/** The kinds of link that are a step outside the chat. */
+export const ACTION_LINK_KINDS = ['vault', 'store_login', 'approval'];
+/**
+ * For each kind of step, the shopper message kinds that end it, and how. Every other message kind,
+ * such as `card_link_unfinished` or `approval_expiring`, leaves the step open.
+ */
+export const ACTION_LINK_ENDINGS = {
+    vault: { card_added: 'completed', card_link_expired: 'expired' },
+    store_login: { store_connected: 'completed', store_connect_failed: 'failed', store_connect_expired: 'expired' },
+    approval: {
+        order_placed: 'completed',
+        order_not_placed_yet: 'completed',
+        order_unconfirmed: 'completed',
+        order_confirmed: 'completed',
+        order_failed: 'completed',
+        payment_declined: 'completed',
+        approval_declined: 'declined',
+        approval_expired: 'expired',
+    },
+};
+/** Whether a link is a step outside the chat: a `vault`, `store_login` or `approval` link with a page to open. */
+export function isActionLink(link) {
+    return ACTION_LINK_KINDS.includes(link.kind) && typeof link.url === 'string' && link.url !== '';
+}
+/** FNV-1a, 32 bits, written out so the id reads the same in every runtime, with no crypto import. */
+function fnv1a(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash;
+}
+/**
+ * A stable id for a step's link, such as `vault_1x9k2qd`: the same for the same link every time it is
+ * handed over, on the server and in the browser, and with no part of the URL in it, so it is safe in
+ * a log, a DOM key or a window name. The buy tool puts it on each step link as `id`.
+ */
+export function actionLinkId(link) {
+    return `${link.kind}_${fnv1a(`${link.kind} ${link.url}`).toString(36)}`;
+}
+/** A store's name reduced to its letters and digits, so "Walmart" and "walmart.com" read alike. */
+const storeKey = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '');
+/** Whether two names are the same store: one reduced name holds the other. */
+function sameStore(a, b) {
+    const x = storeKey(a);
+    const y = storeKey(b);
+    return x === '' || y === '' || x.includes(y) || y.includes(x);
+}
+/**
+ * How `message` ends the step `link` is, or null when it leaves it open: a message about another
+ * kind of step, a reminder such as `card_link_unfinished`, a message whose facts name another link of
+ * the same kind (`facts.approvalUrl` or `facts.cardLinkUrl`), or one about another store: a store
+ * login or an approval link that names its `store` stays open when `facts.merchantName` names a
+ * different one, since a shopper can sign in to two stores, or approve two stores' carts, at once.
+ * A message whose facts name neither ends the shopper's open step of its kind.
+ */
+export function actionLinkOutcome(link, message) {
+    if (!isActionLink(link))
+        return null;
+    const outcome = ACTION_LINK_ENDINGS[link.kind][message.kind];
+    if (!outcome)
+        return null;
+    const named = link.kind === 'approval' ? message.facts?.approvalUrl : link.kind === 'vault' ? message.facts?.cardLinkUrl : undefined;
+    if (named && named !== link.url)
+        return null;
+    const store = message.facts?.merchantName;
+    if (link.store && store && !sameStore(link.store, store))
+        return null;
+    return outcome;
+}