@agent-cards/commerce-sdk 0.18.0 → 0.18.3

package/README.md

@@ -136,7 +136,7 @@ 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 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.
+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. The link names the store that sells the product in `store`, such as `Walmart`, and the store's own website in `storeDomain`, such as `walmart.com` or `jadeyoga.com`, or null when Agentcard knows none, such as a restaurant's: show `storeDomain` on the card as where the product comes from, never the host of `url`, which can be a tracking link. 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.
 
@@ -178,6 +178,40 @@ 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.
 
+## Keep the answer when the shopper's connection drops
+
+A phone that loses its connection while a reply streams back would show the shopper an error, though the turn finished on your server. Serve the turn with `turnStream` and read it in the browser with `streamTurn`, and the shopper gets the answer anyway. On your server:
+
+```ts
+import { readTurn, turnStream, isTurnId } from '@agent-cards/commerce-sdk';
+
+// POST /chat: the browser names the turn in `x-turn-id`.
+const turnId = request.headers.get('x-turn-id');
+if (!isTurnId(turnId)) return Response.json({ error: 'Name the turn.' }, { status: 400 });
+const { stream, finished } = turnStream({ store, key: `${shopperId}:${turnId}`, run: (send) => runTurn(send) });
+waitUntil(finished);
+return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });
+
+// GET /chat/turn?id=...: the turn's record, for the browser to pick up where its stream stopped.
+return Response.json(await readTurn(store, `${shopperId}:${id}`));
+```
+
+`store` is yours, such as Redis: `load(key)` and `save(key, record, ttlSeconds)`. `runTurn` stands for your agent's turn, and `send(event, data)` takes each event the chat shows, the last one included, such as `done`. The turn runs to its end after the browser leaves, and `finished` resolves once its record is saved: hand it to your host's `waitUntil`. The record is kept for ten minutes (`ttlSeconds`). Put your shopper's id in the key, so no shopper reads another's turn. When one turn at a time runs per shopper, answer a message sent during a turn with a 409 whose body names that turn, `{ "error": "...", "turn_id": "..." }`.
+
+In the browser:
+
+```ts
+import { streamTurn, readTurnResponse } from '@agent-cards/commerce-sdk/browser';
+
+const { refused } = await streamTurn({
+  start: (turnId) => fetch('/chat', { method: 'POST', headers: { 'x-turn-id': turnId }, body }),
+  read: (turnId) => fetch(`/chat/turn?id=${turnId}`).then(readTurnResponse),
+  onEvent: (event, data) => show(event, data),
+});
+```
+
+`onEvent` hears each event once, in order. When the stream drops, before its first event or after it, `streamTurn` reads the turn's record every 1.5 seconds (`pollMs`) and hands over the events the stream did not carry, until the turn's last one. A 409 that names a running turn waits for that turn's answer the same way. Any other refusal comes back in `refused`, the response, for you to show its error. A record that never appears within 15 seconds (`startWaitMs`) means the message never reached your server, and `streamTurn` throws the connection's error.
+
 ## 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:
@@ -251,6 +285,8 @@ const turn = buy.turn(message, {
   onItem: (item) => (item.kind === 'text' ? sendText(shopper.id, item.text) : sendCard(shopper.id, item.link)), // your code
 });
 if (await turn.handled()) {
+  // A newer message from the shopper stopped this turn: that message's turn answers and keeps the exchange.
+  if (turn.stopped) return;
   // Agentcard answered the shopper: keep the exchange, so your model reads it on the next message.
   const said = turn.items.flatMap((item) => (item.kind === 'text' ? [item.text] : [])).join('\n\n');
   history = [...turn.messages(history), { role: 'assistant', content: said }];
@@ -362,7 +398,7 @@ async function runModel(shopperId: string, turn: BuyToolTurn) {
 | Saving a card, with no yes and no pick standing | 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 |
-| Signing in or saving a card, after a yes, when the store priced its fees and tax in since | The new total, then the next link: `it's $17.89 with fees and tax now. approve the payment to place your order (up to $17.89)` |
+| Signing in or saving a card, after a yes, when the store priced its fees and tax in since | The new total and the ask for the yes, with no link: `The cart changed after your yes: it comes to $17.89 with tax and shipping now. Nothing was paid. Say yes to pay $17.89.` |
 | 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` |
 
 With `direct` and `replyAsWritten` on the tool, a step needs no model when its answer is a link: send `step.run(step.direct.input)` first, and when `step.replyAsWritten` is set, post it, with `step.links`, in place of the model's answer. When it is null, as for the ask for a yes, run your model as above.
@@ -370,8 +406,8 @@ With `direct` and `replyAsWritten` on the tool, a step needs no model when its a
 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, and the shopper is never asked for that yes again. It goes on past each step, the sign-in and then the card, as long as the cart holds the same items, in the same quantities and at the same prices, at the same store: a total that moved only because the store priced its fees, tax or delivery in keeps the yes, and the next ask says the new total (`yes_carried` on the answer). Each confirm names the cart's hash as it stands, so Agentcard refuses it if the cart changed. A cart whose items, quantities or store changed, a shopper message after the yes that is not a plain go-ahead, such as "wait, make it two", and a declined approval each take the yes back, and the shopper is asked again. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard.
-- A shopper who picked what is in the cart, by tapping a product's card or asking to buy it, and since answered only the checkout's questions (an address, a phone number, a name, an email, a yes to an address read back to them) or said a plain go-ahead, gave the same go-ahead: saving the card or signing in to the store confirms that cart by its hash as it stands, with no ask for a yes (`yes_carried.picked`). A cart whose items, quantities, item prices or store changed since the pick, any other message, such as "actually wait" or a question, and a declined approval take it back.
+- 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, and the shopper is never asked for that yes again. It goes on past each step, the sign-in and then the card, as long as the cart holds the same items, in the same quantities and at the same prices, at the same store. Each confirm names the cart's hash as it stands, and in `carried` the hash of the cart the shopper said yes to: Agentcard pays only that cart, so a total that moved because the store priced its fees, tax or delivery in comes back with the new total and the ask for the shopper's yes, and nothing is paid. A cart whose items, quantities or store changed, a shopper message after the yes that is not a plain go-ahead, such as "wait, make it two", and a declined approval each take the yes back, and the shopper is asked again. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard.
+- A shopper who picked what is in the cart, by tapping a product's card or asking to buy it, and since answered only the checkout's questions (an address, a phone number, a name, an email, a yes to an address read back to them) or said a plain go-ahead, gave the same go-ahead: saving the card or signing in to the store confirms that cart by its hash as it stands, with no ask for a yes (`yes_carried.picked`). The confirm names in `carried` the cart the chat showed, and a cart the store priced again since comes back with its total and the ask for a yes. A cart whose items, quantities, item prices or store changed since the pick, any other message, such as "actually wait" or a question, and a declined approval take it back.
 - The approval in the Vault is still the shopper's: the confirm sends the approval link, which names the most they can be charged, 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.
 
@@ -432,7 +468,7 @@ const buy = buyTool({
 
 `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.
 
-In text mode, a streamed search's reply is Agentcard's own line, written from the conversation while it searches, such as `one sec, checking target for la croix`, and it reaches `onWorking` before the cards or not at all. A search `buy.turn` sends straight that has shown the shopper nothing by twice `ackDelayMs`, because Agentcard wrote no line or its line was dropped, sends `one moment` once, and a line of Agentcard's that comes after it is dropped. When your model's run fails before it wrote or called anything, call `turn.end()` before you show your error, so no wait line follows it. With `stream: false`, the tool sends its own reply when Agentcard has not answered a new request within `ackDelayMs`, 1 second by default, 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, a store or a place in a list such as `the first one`, hears `got it, one moment`, a confirm hears `on it, one moment`, and any other answer hears `one moment`. A turn opened with `buy.turn` that has shown the shopper nothing, no line and no card, after the delay sends that line once. 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.
+In text mode, a streamed search's reply is Agentcard's own line, written from the conversation while it searches, such as `one sec, checking target for la croix`, and it reaches `onWorking` before the cards or not at all. A search `buy.turn` sends straight that has shown the shopper nothing by twice `ackDelayMs`, because Agentcard wrote no line or its line was dropped, sends `one moment` once, and a line of Agentcard's that comes after it is dropped. When your model's run fails before it wrote or called anything, call `turn.end()` before you show your error, so no wait line follows it. When `turn.stopped` is true after a call, the shopper sent a new message while this turn ran and Agentcard stopped the turn for it: end the turn there, with no model call, no error and no saved history, because the new message's turn answers. With `stream: false`, the tool sends its own reply when Agentcard has not answered a new request within `ackDelayMs`, 1 second by default, 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, a store or a place in a list such as `the first one`, hears `got it, one moment`, a confirm hears `on it, one moment`, and any other answer hears `one moment`. A turn opened with `buy.turn` that has shown the shopper nothing, no line and no card, after the delay sends that line once. 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: (ask) => text` to write your own text from the shopper's words, where an empty answer sends none, and `ackDelayMs` to change the 1 second for either mode.
 

package/dist/ack.d.ts

@@ -20,6 +20,13 @@ export declare const CHITCHAT: RegExp;
  * can you buy aa batteries from`, is a search and keeps its reply.
  */
 export declare const CAPABILITY: RegExp;
+/**
+ * True when the shopper's words ask for other products like one they saw, such as `More like the KODAK AA Alkaline Batteries (60
+ * Pack)`, `something similar to the first one`, `alternatives to the Duracell` or `cheaper than the KODAK one`: a new search,
+ * never a pick of the product it names. `names` are the products the shopper saw: their words are read out first, so a product
+ * whose own name says `alternative` or `similar` is still picked by its tap.
+ */
+export declare function asksForSimilar(text: string, names?: readonly string[]): boolean;
 /**
  * True when the message names one of these stores and nothing else to buy: the store's whole name, or
  * two words of it in a row, such as `el grullense` for `Tacos El Grullense`, alone or after a frame such

package/dist/ack.js

@@ -15,6 +15,7 @@
  * store the shopper saw, such as `order here`, or `Order from Tacos El Grullense` as a store card sends it.
  */
 import { SENTENCE_END } from './sentences.js';
+import { withoutTripVerb } from './trip-ask.js';
 /** 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'],
@@ -140,6 +141,45 @@ const PLACE = '(?:first|second|third|fourth|fifth|sixth|last|other|\\d{1,2}(?:st
 const PICK_REF = new RegExp(`^(?:(?:the|that|this) (?:[\\w'$.-]+ ){0,3}one\\b|(?:that|this|those|these|both|it)(?: ones?)?$|the ${PLACE}(?: (?:one|option|item|product|choice|result))?$|${PLACE}(?: (?:one|option|item|product|choice|result)\\b|$)|(?:option|number|item|choice|#) ?#?\\d{1,2}\\b|\\d{1,2}$)`);
 /** A budget word in front of a price, so `under $13.49` stays a search. */
 const BUDGET = /(?:under|below|than|max|maximum|around|about|to|budget|within|over|above|for|most)\s*$/;
+/** What a request for other products opens with before `more like`: `show me more like the KODAK one`, `any more like it`. */
+const MORE_LIKE_LEAD = "(?:(?:ok|okay|hey|hi|so|um|uh|also|and|cool|great|nice|hmm|actually|yes|yeah|can you|could you|can i|could i|i'?d like to|i want to|please)\\s+)*(?:(?:show|find|get|give|send)(?: me| us)?\\s+|(?:i want|i'?d like|i would like|i need|i'?m looking for|im looking for|looking for|search for|look for|do you have|got|have you got|are there|is there|see)\\s+)?(?:some\\s+|any\\s+)?";
+/**
+ * Words that ask for other products like one the shopper saw, never for that product: `more like the KODAK AA (60 Pack)`,
+ * `something similar`, `alternatives to the Duracell`, `cheaper than the KODAK one`, `like the first one but in blue`, and in
+ * Spanish `algo parecido al KODAK`, `más como este`. A number or a price after the words is a correction (`more like $20`,
+ * `something like 2`), and stays out.
+ */
+const SIMILAR = [
+    new RegExp(`^${MORE_LIKE_LEAD}more (?:like|similar)\\b(?!\\s*(?:\\$|\\d))`),
+    /\bmore like (?:the|this|that|these|those|it|them|one|ones)\b/,
+    /\b(?:something|anything|stuff|things|ones|others|other ones|other options|options|products|items|other products|other items|more)(?: else)? (?:like|similar to)\b(?!\s*(?:\$|\d))/,
+    /\bsimilar (?:to|ones?|items?|products?|options?|stuff|things|styles?|kinds?|types?|brands?|models?)\b|\b(?:something|anything|more|some|any|show me|find|see|got|have|want|need|others?) similar\b|^similar\b/,
+    /\b(?:an?|some|any|other|cheaper|good|better|similar) alternatives?\b|\balternatives? (?:to|for|like)\b|^alternatives?\b/,
+    /\b(?:cheaper|less expensive|more affordable|lower[- ]priced|lower cost) than\b(?!\s*(?:\$|\d|(?:that|this|my|the) (?:price|budget)))/,
+    /\blike (?:the|this|that|these|those|it)\b.*\bbut\b|\bbut (?:cheaper|less expensive|more affordable)\b/,
+    /\b(?:anything|something|others?|options?|ones?|products?|items?)(?: else)? (?:other than|besides|apart from)\b/,
+    /\bparecid[oa]s?\b|\bsimilar(?:es)? a[ls]?\b|\balgo (?:como|parecido|similar|as[ií])\b(?!\s*(?:\$|\d))|\bm[aá]s (?:como|del estilo)\b|\botr[oa]s? (?:opciones |cosas |productos |marcas )?(?:como|parecid[oa]s?|similares)\b|\balternativas?\b|\bm[aá]s barat[oa]s? que\b|\bcomo (?:el|la|los|las|este|esta|estos|estas|ese|esa)\b.*\bpero\b/,
+];
+/** Text as lowercase words with single spaces, accents kept, as `asksForSimilar` reads it. */
+function similarWords(text) {
+    return plain(String(text ?? '')).replace(/[^\p{L}\p{N}\s$#'-]+/gu, ' ').replace(/\s+/g, ' ').trim();
+}
+/**
+ * True when the shopper's words ask for other products like one they saw, such as `More like the KODAK AA Alkaline Batteries (60
+ * Pack)`, `something similar to the first one`, `alternatives to the Duracell` or `cheaper than the KODAK one`: a new search,
+ * never a pick of the product it names. `names` are the products the shopper saw: their words are read out first, so a product
+ * whose own name says `alternative` or `similar` is still picked by its tap.
+ */
+export function asksForSimilar(text, names = []) {
+    let said = ` ${similarWords(text)} `;
+    for (const name of names) {
+        const own = similarWords(name);
+        if (own.length >= 3)
+            said = said.split(` ${own} `).join(' ');
+    }
+    said = said.replace(/\s+/g, ' ').trim();
+    return said !== '' && SIMILAR.some((pattern) => pattern.test(said));
+}
 /**
  * True for a pick of a product the shopper already saw: a frame such as `i'll take` or `i want the`, a
  * reference such as `that one`, `the second` or `#2`, or a product title with its price, as a product
@@ -147,6 +187,9 @@ const BUDGET = /(?:under|below|than|max|maximum|around|about|to|budget|within|ov
  * gets no instant reply.
  */
 function isPick(line, words) {
+    // `More like the KODAK AA (60 Pack) ($26.05)` names a card to search for others like it: a new search, with its instant reply.
+    if (asksForSimilar(line))
+        return false;
     if (/\(\s*\$\s*\d[\d,]*(?:\.\d{2})?\s*\)/.test(line))
         return true;
     const price = line.match(/\$\s*\d[\d,]*\.\d{2}\s*$/);
@@ -259,7 +302,7 @@ export function paraphrase(text) {
     }
     for (let before = ''; before !== rest;) {
         before = rest;
-        rest = rest.replace(LEAD, '');
+        rest = withoutTripVerb(rest.replace(LEAD, ''));
     }
     // `order from tacos el grullense` names the store, never `from tacos el grullense`.
     rest = rest.replace(/^(?:from|at)\s+/, '').replace(/[\s,]+(?:please|pls|thanks|thank you|thx|ty)$/, '').replace(/[\s,.:!?]+$/, '');

package/dist/browser.d.ts

@@ -105,3 +105,5 @@ export interface ActionWindows {
  * so the chat could neither close it nor tell when the shopper closed it.
  */
 export declare function actionWindows(options?: ActionWindowsOptions): ActionWindows;
+export { streamTurn, readTurnResponse, type StreamTurnOptions, type StreamTurnResult, type TurnResponseLike } from './turn-reader.js';
+export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord } from './turn-record.js';

package/dist/browser.js

@@ -118,3 +118,6 @@ export function actionWindows(options = {}) {
         },
     };
 }
+// A chat turn read in the browser: a dropped connection reads the turn's answer back by the turn's id.
+export { streamTurn, readTurnResponse } from './turn-reader.js';
+export { TURN_RECOVERY_ON, isTurnId } from './turn-record.js';

package/dist/buy-tool.d.ts

@@ -76,9 +76,16 @@ export interface BuyToolLink {
     expiresAt: string | null;
     /**
      * On a store login link: the store's name, or null when Agentcard named none. On an approval link:
-     * the store whose cart it approves, when the answer names the cart.
+     * the store whose cart it approves, when the answer names the cart. On a product link: the name of
+     * the store that sells it, such as `Walmart` or `jadeyoga.com`, or null when Agentcard named none.
      */
     store?: string | null;
+    /**
+     * On a product link: the website of the store that sells it, such as `walmart.com` or `jadeyoga.com`, to show on the card
+     * as where the product comes from. It is never the host of `url`, which can be a tracking link that names no store. Null
+     * when Agentcard knows no website for the store, such as a restaurant, a venue or an airline.
+     */
+    storeDomain?: string | null;
     /** On a product link: the product's name. */
     title?: string;
     /**
@@ -156,6 +163,8 @@ export interface BuyToolProduct {
     /** Every photo of the product, `imageUrl` first, at most eight; empty when it has none. */
     images: string[];
     store: string | null;
+    /** The website of the store that sells it, such as `walmart.com`, or null when Agentcard knows none. */
+    storeDomain?: string | null;
     /** The product's page at its store, or null when Agentcard sent none. */
     url: string | null;
     /**
@@ -629,6 +638,14 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
      * again does nothing.
      */
     end(): void;
+    /**
+     * True once a call of this turn answered `turn_stopped`: the shopper sent a newer message, and Agentcard stopped this
+     * turn for it. The newer message's turn answers the shopper, so this one is over. Do not call your model again, show
+     * no error and save no history for it: the cards it already showed stay with the shopper. The call returns to your
+     * model as any other, so check `stopped` after each call. The stopped answer goes to no `onResult` and changes nothing
+     * a later turn reads, and no wait line or 👀 follows it.
+     */
+    readonly stopped: boolean;
     /** The instant reply this turn sent to `onWorking` when it opened, or null when it sent none, as with a reaction. */
     readonly ack: string | null;
     /** The reaction this turn put on the shopper's message, `👀`, when it opened or once a call ran slow, or null while it put none or when `onReaction` threw. */

package/dist/buy-tool.js

@@ -39,7 +39,7 @@ import { choiceLines, leadsIntoList, messageForShopper, messagesListChoice, repl
 import { joinLeadIns, leadInJoiner, messageStream, paceOf, paragraphsOf, sleep, toMessages, typingHook } from './messages.js';
 import { isStale } from './shopper-message.js';
 import { actionLinkId, isActionLink } from './action-links.js';
-import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
+import { ACK_REACTION, ackAt, answersCheckout, answersQuestion, asksForSimilar, holdsBack, instantAck as instantAckOf, isNewRequest, isPickText, keepsYes, namesStore, nextTemplate, readsAsAckLine, slowStepLine } from './ack.js';
 /** The action a product of `merchant` takes (BuyToolProductAction). */
 export function productAction(merchant) {
     if (merchant === 'reservations')
@@ -130,6 +130,8 @@ const APP_TURN_MS = 120_000;
 const STEP_LINK_KINDS = new Set(['vault', 'approval', 'store_login']);
 /** The longest a step link waits for its message: an app that never writes one still sends the link. */
 const STEP_LINK_HOLD_MS = 20_000;
+/** The `error_code` of an answer whose turn a newer message from the same shopper stopped: that message's turn answers instead. */
+const TURN_STOPPED = 'turn_stopped';
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
 const STILL_BUILDING = "The store is still building the cart for the shopper's last request. Its cart and total reach the shopper in a message from Agentcard: once that message has arrived, call this tool again with the shopper's words.";
 const CART_NOT_READY = 'The store is still building the cart, so it has no total yet, and nothing was confirmed. Its cart and total reach the shopper in a message from Agentcard: confirm it only after the shopper says yes to that total.';
@@ -210,7 +212,7 @@ function yesAfter(result, yes) {
     const seen = yes.shown ?? stopped;
     if (!seen || (yes.shown && stopped && !sameOrder(yes.shown, stopped)))
         return null;
-    return { conversationId: result.conversation_id, cart: stopped ?? seen, totalCents: seen.totalCents };
+    return { conversationId: result.conversation_id, cart: stopped ?? seen, totalCents: seen.totalCents, consentedHash: seen.hash };
 }
 /** The words of the call a `nextStep` turn's `direct` makes. They never reach Agentcard: the turn's calls send no ask. */
 const NEXT_STEP_ASK = 'take the next step';
@@ -270,7 +272,22 @@ export function productsOf(turn) {
 /** A product's card as `sendLink` hears it: the id the model reads and a pick takes, never the store page, which is `url`. A flight option has no page at a store: its card carries no url, and its productId picks it. */
 function productLink(product) {
     const productId = pickId(product);
-    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
+    return { kind: 'product', url: product.url || null, title: product.name, price: productPrice(product), ...(productId ? { productId } : {}), action: product.action ?? 'buy', imageUrl: product.imageUrl, images: product.images ?? (product.imageUrl ? [product.imageUrl] : []), store: product.store ?? null, storeDomain: product.storeDomain ?? null, expiresAt: null, ...(product.availability ? { availability: product.availability } : {}) };
+}
+/** A host name: dot-separated labels of letters, digits and hyphens, ending in a letters-only top-level label. */
+const STORE_HOST = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+/**
+ * The website of the store a catalog item is at: the `domain` Agentcard sent, else, from an older API that sends none, the
+ * store's id when the id is itself a website (`jadeyoga.com`). Never Channel3's tracking host (buy.trychannel3.com). Null
+ * when neither names one: a store id such as `walmart` names no website by itself.
+ */
+function storeDomainOf(store) {
+    for (const raw of [store?.domain, store?.id]) {
+        const host = typeof raw === 'string' ? raw.trim().toLowerCase().replace(/^www\./, '').replace(/\.$/, '') : '';
+        if (STORE_HOST.test(host) && host !== 'trychannel3.com' && !host.endsWith('.trychannel3.com'))
+            return host;
+    }
+    return null;
 }
 function productsOfCatalog(catalog) {
     return (catalog.items ?? [])
@@ -286,6 +303,7 @@ function productsOfCatalog(catalog) {
         images: item.image_urls ?? (item.image_url ? [item.image_url] : []),
         ...(item.flight ? { flight: item.flight } : {}),
         store: item.store?.name ?? item.store?.id ?? catalog.merchant_name ?? null,
+        storeDomain: storeDomainOf(item.store),
         url: item.url ?? null,
         action: productAction(catalog.merchant),
         linkSent: false,
@@ -719,6 +737,15 @@ function checkoutRefusal(conversation) {
         return null;
     return { code, merchant: last.merchant_name, message: last.message };
 }
+/** Ends a turn (`turn.end()`, or a call it made that a newer message stopped): no wait line and no 👀 go out after it. */
+function endTurn(state) {
+    state.ended = true;
+    state.dropWaitLine?.();
+    // The acknowledgement a call still running holds, a 👀 or a line for a slow pick, confirm or answer, is cancelled too.
+    for (const cancel of state.holds ?? [])
+        cancel();
+    state.holds?.clear();
+}
 /**
  * A buy tool for one shopper. With a company client, name the shopper with
  * `externalUserId`; with a shopper's own `accessToken`, the token names them.
@@ -915,8 +942,10 @@ export function buyTool(options) {
     let shownStoreNames = [];
     /** True for a pick of a product or a store the shopper saw, by its name. */
     const namesShown = (text) => namesShownProduct(text) || namesStore(text, shownStoreNames);
+    /** Whether a message asks for other products like one shown (`More like the <card's name>`): a new search, never a pick. */
+    const asksLikeShown = (text) => asksForSimilar(text, [...lastTappable, ...lastAnswerProducts].map((product) => product.name));
     /** What a message picks: a product it names (`product`), a store or a place in a list (`pick`), or nothing (null). */
-    const pickOf = (text) => namesStore(text, shownStoreNames) ? 'pick' : namesShownProduct(text) ? 'product' : isPickText(text) ? 'pick' : null;
+    const pickOf = (text) => asksLikeShown(text) ? null : namesStore(text, shownStoreNames) ? 'pick' : namesShownProduct(text) ? 'product' : isPickText(text) ? 'pick' : null;
     /** How the shopper's message reads for the instant reply: what it picks, and the reply it gets, or null. */
     const ackOfMessage = (shopperText) => {
         const text = String(shopperText ?? '');
@@ -1020,7 +1049,7 @@ export function buyTool(options) {
             };
         }
         // A confirm, or a pick of what the shopper saw, gets fixed words that never say `looking for`.
-        const slow = step ?? t.picked ?? (!t.neutral && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
+        const slow = step ?? t.picked ?? (!t.neutral && !asksLikeShown(ask) && (namesShown(ask) || isPickText(ask)) ? 'pick' : null);
         // A short answer to the question the last reply asked, such as `medium` after `what size?`, is no
         // search: like `yes`, a slow call still tells the shopper, in words that look for nothing.
         const neutral = t.neutral || answersQuestion(ask, lastReply);
@@ -1585,7 +1614,7 @@ export function buyTool(options) {
         const inPurchase = (at) => at === null || at === conversationId;
         if (yes && one && conversationId && inPurchase(yes.conversationId) && sameOrder(one, yes.cart)) {
             carriedYes = null;
-            return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who }, yes: { ...yes, cart: one, conversationId } };
+            return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', carried: { from: yes.picked ? 'pick' : 'yes', cart_hash: yes.consentedHash }, ...who }, yes: { ...yes, cart: one, conversationId } };
         }
         // The shopper picked what is in the cart and finished the step outside the chat: finishing it is their go-ahead for the
         // same order, confirmed by the cart's hash as it stands now, and the approval link stays their consent to the payment
@@ -1597,7 +1626,7 @@ export function buyTool(options) {
         if (picked?.cart && one && conversationId && inPurchase(picked.conversationId) && (event.kind === 'card_added' || event.kind === 'store_connected')) {
             pickedOrder = null;
             if (sameOrder(one, picked.cart)) {
-                return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', ...who }, yes: { conversationId, cart: one, totalCents: picked.cart.totalCents, picked: true } };
+                return { body: { confirm: one.hash, conversation_id: conversationId, payment_source: 'vault', carried: { from: 'pick', cart_hash: picked.cart.hash }, ...who }, yes: { conversationId, cart: one, totalCents: picked.cart.totalCents, consentedHash: picked.cart.hash, picked: true } };
             }
         }
         // A checkout the shopper already moved past their yes (an approval link waiting, or the order going through) is reported as
@@ -1640,7 +1669,9 @@ export function buyTool(options) {
         if (!confirm && ask === '')
             throw new TypeError("Put the shopper's words in ask.");
         // A pick chooses from the products or stores this conversation showed: never on a confirm, and never on a new order, which shows none yet.
-        const picks = !confirm && !newOrder;
+        // A request for other products like one shown is a new search: a `product_id` or `store_id` the model sent beside it would
+        // put that product in the cart (2026-10-27, "More like <a card's whole title>" on 0.18.0), so none goes.
+        const picks = !confirm && !newOrder && !asksLikeShown(ask);
         const pick = picks && input.product_id ? { product_id: input.product_id } : picks && input.store_id ? { store_id: input.store_id } : null;
         const body = {
             resume: true,
@@ -1985,6 +2016,15 @@ export function buyTool(options) {
             ack?.cancel();
             const settled = plan && 'local' in plan ? plan.local : turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirmSent, startedAt);
             await t.ackOut;
+            // A newer message from the shopper stopped this turn, and its own turn answers: this one ends here and says nothing
+            // more. Its empty answer holds no cart and lists no product, so it leaves what the shopper last read, the carts and
+            // the last ask as they were, and the app's onResult never hears it, so no cart panel empties.
+            if (turn?.error_code === TURN_STOPPED) {
+                endTurn(t);
+                t.stopped = true;
+                t.results?.push(settled);
+                return settled;
+            }
             // The streamed messages that waited for the answer go out in order: each the answer kept as written, and a card ask or
             // a link the answer replaced gives way to its ask for the step Agentcard named, once, after them. All of them go out
             // before any link of the answer.
@@ -2545,7 +2585,8 @@ export function buyTool(options) {
                     return false;
                 throw error;
             }
-            if (result.shopper_already_read_reply === true)
+            // A newer message stopped this turn, and that message's turn answers the shopper: nothing is left for the app's model.
+            if (result.shopper_already_read_reply === true || state.stopped)
                 return true;
             const reply = replyAsWritten(result, { textingStyle: texting });
             // The reply goes out where the app hears the turn's messages: onItem or onMessage, else onText. With none of them, the
@@ -2577,14 +2618,7 @@ export function buyTool(options) {
                 enumerable: false,
             },
             end: {
-                value: () => {
-                    state.ended = true;
-                    state.dropWaitLine?.();
-                    // The acknowledgement a call still running holds, a 👀 or a line for a slow pick, confirm or answer, is cancelled too.
-                    for (const cancel of state.holds ?? [])
-                        cancel();
-                    state.holds?.clear();
-                },
+                value: () => endTurn(state),
                 enumerable: false,
             },
             messages: { value: messagesFor, enumerable: false },
@@ -2593,7 +2627,8 @@ export function buyTool(options) {
             links: { get: () => [...links], enumerable: false },
             results: { get: () => [...results], enumerable: false },
             direct: { value: direct, enumerable: false },
-            replyAsWritten: { get: () => (written && results.length > 0 ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
+            stopped: { get: () => state.stopped === true, enumerable: false },
+            replyAsWritten: { get: () => (written && results.length > 0 && !state.stopped ? replyAsWritten(results[results.length - 1], { textingStyle: texting }) : null), enumerable: false },
             items: { get: () => feed.items.map((item) => (item.kind === 'link' ? { kind: 'link', link: { ...item.link } } : { ...item })), enumerable: false },
             // Each message joins the feed the moment it is cut, so a link the tool hands over during a pause never overtakes text already written.
             // A step link held for this message goes out right after its last paragraph, once the stream ends.

package/dist/client.d.ts

@@ -50,6 +50,11 @@ export interface BuyCatalogUpdate {
     found: number | null;
     /** The products found past the cards, in the order they were found, to show on "show more" with no new search. */
     more: BuyCatalog['items'];
+    /**
+     * False while a search of the turn is still out, such as a second flight source: more cards may join these, and a card
+     * already shown may come again with a lower price under the same `id`. True once every source answered.
+     */
+    final: boolean;
 }
 /**
  * Whether a place a card shows has room at the time the shopper asked for: `checking` while Agentcard's live search runs,
@@ -250,6 +255,15 @@ export interface BuyRequest {
     hand_back?: true;
     /** With `hand_back`: what Agentcard's last answer showed and asked, which decides whether a pick or an answer is shopping. */
     last_answer?: BuyLastAnswer;
+    /**
+     * On a confirm the app sends on its own after a step outside the chat (a saved card, a store sign-in): the go-ahead it
+     * carries, a `yes` to a cart or the `pick` of what is in it, and `cart_hash`, the cart it was given for. Agentcard pays
+     * only that cart; a cart that changed since is answered with its total and `next_action: 'confirm'`, and nothing is paid.
+     */
+    carried?: {
+        from: 'yes' | 'pick';
+        cart_hash: string;
+    };
 }
 /** What the shopper's last answer from Agentcard showed and asked, sent with `hand_back`. */
 export interface BuyLastAnswer {
@@ -267,9 +281,14 @@ export interface BuyLastAnswer {
     }>;
 }
 export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
+/**
+ * The store a product or a cart is at. `domain` is the store's own website, such as `walmart.com` or `jadeyoga.com`: on a
+ * catalog item, null when Agentcard knows none (a restaurant, a venue, an airline), and absent from an older API and on a cart.
+ */
 export interface BuyStore {
     id: string;
     name?: string;
+    domain?: string | null;
 }
 export interface BuyCartLine {
     name: string;

package/dist/client.js

@@ -136,7 +136,7 @@ function imagesOf(main, list) {
 function storeOf(v) {
     if (!isRecord(v) || !str(v.id))
         return null;
-    return { id: v.id, ...(str(v.name) ? { name: v.name } : {}) };
+    return { id: v.id, ...(str(v.name) ? { name: v.name } : {}), ...(Object.hasOwn(v, 'domain') ? { domain: str(v.domain) } : {}) };
 }
 function feeLinesOf(v) {
     if (!Array.isArray(v))
@@ -512,7 +512,7 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                 const asOf = str(block.as_of);
                 const shown = countOf(block.shown);
                 const found = countOf(block.found);
-                const update = { conversationId: data.conversation_id, catalog, asOf, shown, found, more: catalogItemsOf(block.more) };
+                const update = { conversationId: data.conversation_id, catalog, asOf, shown, found, more: catalogItemsOf(block.more), final: block.final !== false };
                 // The count follows the cards it counts, so an app never shows "8 of 23" above no cards, and it settles before the
                 // next event, so a later count never lands before an earlier one. A card display that throws never costs the count.
                 deliver(async () => {

package/dist/definition.d.ts

@@ -7,6 +7,8 @@
  */
 export declare const BUY_TOOL_NAME = "buy";
 /** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
+export declare const BUY_TOOL_RULES: string;
+/** The rules as the model reads them, with travel named when src/trip-ask.ts says so. */
 export declare const BUY_TOOL_DESCRIPTION: string;
 /**
  * What the model sends: `ask`, `confirm` and `new_order` every time, `product_id`, null unless the

package/dist/definition.js

@@ -5,9 +5,10 @@
  * shopper's id are construction options, never model inputs, so a model can
  * neither change where an order goes nor buy for someone else.
  */
+import { withTravel } from './trip-ask.js';
 export const BUY_TOOL_NAME = 'buy';
 /** What the model reads before it calls the tool. Every sentence is a rule the model follows. */
-export const BUY_TOOL_DESCRIPTION = [
+export const BUY_TOOL_RULES = [
     'Buy what this shopper asks for at real stores.',
     "Put the shopper's own words in `ask`.",
     'When the shopper sends a link to a product, such as a buy.trychannel3.com link, put the whole link in `ask` exactly as they sent it, query string included, with their words beside it: Agentcard buys that exact product from the link, so never describe the link in words instead.',
@@ -65,6 +66,8 @@ export const BUY_TOOL_DESCRIPTION = [
     'Ask the shopper to "let me know", never "text me", unless your app is a text-message chat.',
     'Name only the stores and products that reach the shopper as cards in this result, never others in passing, such as "five guys and mcdonald\'s deliver there too", even when `reply` names them: to offer more, ask "want other options?". This is for what you suggest: when you show the cart or ask for a yes to it, name what is in it.',
 ].join(' ');
+/** The rules as the model reads them, with travel named when src/trip-ask.ts says so. */
+export const BUY_TOOL_DESCRIPTION = withTravel(BUY_TOOL_RULES);
 /** A fresh copy of the tool's definition, so a caller that edits one never changes another. */
 export function buyToolDefinition() {
     return {

package/dist/direct.js

@@ -12,7 +12,11 @@
  *   answer such as `medium` or `size 9`, or a plain yes to the total it asked the shopper to confirm;
  * - a price limit for the products Agentcard just showed: `only options under $20`, `under 20`, `cheaper ones`.
  *   Agentcard holds its cards to the limit and shows the ones inside it again as cards; your model, answering
- *   from the list it saw, named two products with no card to tap (2026-10-27).
+ *   from the list it saw, named two products with no card to tap (2026-10-27);
+ * - a request for other products like one Agentcard just showed: `More like the KODAK AA Alkaline Batteries (60 Pack)`,
+ *   `something similar to the first one`, `cheaper than the KODAK one`. It goes as a new search with no `product_id`:
+ *   on 2026-10-27 (the playground chat on 0.18.0, production /buy) "More like <a card's whole title>" went as a pick of
+ *   that card, and Agentcard put it in the cart and asked for the shipping address.
  *
  * Everything else goes to the model: a question, small talk, a change of mind (`no`, `wait`, `cancel`),
  * a command to the cart, and anything about the account, an order or how the chat works. A pick or an
@@ -23,7 +27,8 @@
  * purchase reply to small talk, while one the model reads by mistake costs only the model's call. On
  * the 188 labelled messages in `test/fixtures/direct-messages.json`, it sends none it should not.
  */
-import { ABOUT, ACKNOWLEDGED, CAPABILITY, CART_COMMAND, CHECKOUT, CHITCHAT, FILLER, asksForDetails, isNewRequest, isPickText, namesStore, plain } from './ack.js';
+import { ABOUT, ACKNOWLEDGED, CAPABILITY, CART_COMMAND, CHECKOUT, CHITCHAT, FILLER, asksForDetails, asksForSimilar, isNewRequest, isPickText, namesStore, plain } from './ack.js';
+import { tripAskGoesStraight } from './trip-ask.js';
 /**
  * A price limit put on what was just shown: `under $20`, `under 20`, `less than 15 bucks`, `between 10 and 20`, `$20 or
  * less`, `over $50`, `cheaper ones`, `menos de 20`. Only whether the message states one: Agentcard reads the limit itself.
@@ -103,6 +108,8 @@ export function isProductAsk(text) {
         return !QUESTION_START.test(bare) && !NOT_SHOPPING.test(words.replace(/\S*https?:\/\/\S+|\S*www\.\S+/g, ''));
     if (!isNewRequest(raw) || CAPABILITY.test(words) || NOT_SHOPPING.test(words) || PAST.test(words) || CORRECTION.test(words) || REFERS.test(words) || COMPLAINT.test(words))
         return false;
+    if (tripAskGoesStraight(raw, bare))
+        return true;
     // A question goes to the model, unless it asks Agentcard to get something: `can you find me usb-c cables?`.
     const framed = SHOP_FRAME.exec(bare);
     if (/\?/.test(raw) && !(framed && /^(?:can|could|would|will) (?:you|u)\b/.test(bare)))
@@ -164,6 +171,9 @@ function pickOf(raw, bare, context) {
     const byName = context.tappable?.length ? context.tappable : products;
     const stores = context.stores ?? [];
     const call = (fields) => ({ input: { ask: raw, confirm: false, new_order: false, product_id: null, store_id: null, ...fields }, reason: 'pick' });
+    // `More like the <card's whole name>` names a card to find others like it: it picks nothing.
+    if (asksForSimilar(raw, [...byName, ...products].map((product) => product.name)))
+        return null;
     if (stores.length > 0) {
         const said = ` ${nameWords(raw)} `;
         // A store's card names it whole; a store named with the dishes to order from it (`five guys, bacon cheeseburger`) picks it too.
@@ -236,6 +246,12 @@ export function directCall(shopperText, context = {}) {
         const told = CHITCHAT.test(words) || ABOUT.test(words) || CART_COMMAND.test(words) || CAPABILITY.test(words);
         if (ctx.nextAction === 'confirm' && isYes(words))
             return plainCall('confirm', true);
+        // A request for other products like one just shown is a new search, never a pick of the one it names: it goes with no
+        // `product_id`, and Agentcard searches for products like it and leaves it out.
+        const shown = [...(ctx.tappable ?? []), ...(ctx.products ?? [])];
+        if (!told && (shown.length > 0 || (ctx.stores ?? []).length > 0) && asksForSimilar(raw, shown.map((product) => product.name))) {
+            return NOT_SHOPPING.test(words) || TAKEBACK.test(words) ? null : plainCall('product_ask');
+        }
         // A question, a story of what happened, an objection or a change of mind is the model's to answer, whatever came before.
         const aside = QUESTION_START.test(bare) || REFERS.test(words) || COMPLAINT.test(words) || PAST.test(words) || NOT_SHOPPING.test(words) || OBJECTION.test(words) || CORRECTION.test(words);
         if (!told && !aside && !TAKEBACK.test(words)) {

package/dist/index.d.ts

@@ -15,3 +15,5 @@ export { toAnthropicTool, toOpenRouterTool, type AnthropicBuyTool, type OpenRout
 export { listenToAgentcard, type AgentcardListener, type ListenOptions, type ListenCursorStore, type StreamFetch, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, type AgentcardEventType, } from './events.js';
+export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS, type TurnStream, type TurnStreamOptions } from './turn-stream.js';
+export { TURN_RECOVERY_ON, isTurnId, type TurnEvent, type TurnRecord, type TurnRecordStore } from './turn-record.js';

package/dist/index.js

@@ -15,3 +15,5 @@ export { toAnthropicTool, toOpenRouterTool, } from './adapters.js';
 export { listenToAgentcard, } from './listen.js';
 export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';
 export { AGENTCARD_EVENT_TYPES, } from './events.js';
+export { turnStream, readTurn, TURN_RECORD_TTL_SECONDS } from './turn-stream.js';
+export { TURN_RECOVERY_ON, isTurnId } from './turn-record.js';

package/dist/trip-ask.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Trip asks and the tool's travel wording, kept out of direct.ts, ack.ts and definition.ts, which each call in here once.
+ *
+ * On 2026-10-28 on chat.opencommerce.sh, "help me plan a trip to Loreto" never reached Agentcard: `directCall` read no
+ * shopping verb, and the app's model, whose capability rule named stores and restaurants and no travel, answered "i can't
+ * plan itineraries" and offered no flight or hotel. Both switches below ship off and change nothing until a later change
+ * turns them on; a test turns them on by setting the field.
+ */
+/**
+ * `goStraight` on: a trip, flights or a hotel with the place they are for, `help me plan a trip to Loreto`, `flights to
+ * Loreto`, `flights and hotels in loreto` or `a hotel in Chicago next week`, goes straight to Agentcard, which asks for the
+ * airport and the dates it needs, and the instant reply reads the trip back without the verb (`a trip to loreto`). Off: such
+ * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
+ *
+ * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
+ * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * description is the text it was before, word for word.
+ */
+export declare const TRAVEL: {
+    goStraight: boolean;
+    inCapabilities: boolean;
+};
+/** True when the message's words, openings taken off, ask for a trip, flights or a hotel and name the place. */
+export declare function isTripAsk(bare: string): boolean;
+/**
+ * Whether a message that passed `isProductAsk`'s checks for small talk, the account and a story of what happened goes straight
+ * as a trip ask: a question goes only when it asks Agentcard to plan it (`can you help me plan a trip to italy?`).
+ */
+export declare function tripAskGoesStraight(raw: string, bare: string): boolean;
+/** The read-back without the verb that asked for the trip: `plan a trip to loreto` reads back `a trip to loreto`. Any other words, `plan b emergency contraception` too, read back as they are. */
+export declare function withoutTripVerb(text: string): string;
+/** The tool's description with travel named, when `inCapabilities` is on (or `on` says so); the description as given when off. */
+export declare function withTravel(description: string, on?: boolean): string;

package/dist/trip-ask.js

@@ -0,0 +1,63 @@
+/**
+ * Trip asks and the tool's travel wording, kept out of direct.ts, ack.ts and definition.ts, which each call in here once.
+ *
+ * On 2026-10-28 on chat.opencommerce.sh, "help me plan a trip to Loreto" never reached Agentcard: `directCall` read no
+ * shopping verb, and the app's model, whose capability rule named stores and restaurants and no travel, answered "i can't
+ * plan itineraries" and offered no flight or hotel. Both switches below ship off and change nothing until a later change
+ * turns them on; a test turns them on by setting the field.
+ */
+/**
+ * `goStraight` on: a trip, flights or a hotel with the place they are for, `help me plan a trip to Loreto`, `flights to
+ * Loreto`, `flights and hotels in loreto` or `a hotel in Chicago next week`, goes straight to Agentcard, which asks for the
+ * airport and the dates it needs, and the instant reply reads the trip back without the verb (`a trip to loreto`). Off: such
+ * an ask goes straight only with a shopping verb (`book a flight to Loreto`), as before.
+ *
+ * `inCapabilities` on: the tool's description says it plans and books trips, flights and hotels, tells the model to call it
+ * for a trip ask with no dates or airport, and names flights and hotels when the shopper asks what it can do. Off: the
+ * description is the text it was before, word for word.
+ */
+export const TRAVEL = { goStraight: true, inCapabilities: true };
+/** What a trip ask opens with before the trip: `can you help me plan`, `i want to book`, `let's plan`, `plan`. */
+const TRIP_LEAD = "(?:(?:(?:can|could|would|will) (?:you|u) |please |i'?d like (?:you )?to |i want to |i need to |we want to |we need to |let'?s |lets )?(?:help (?:me|us) )?(?:plan|book|organi[sz]e|arrange|find|search for|look for)(?: (?:me|us))? )?";
+/** The trip itself: a trip, a vacation, flights, a hotel, or flights and a hotel together. */
+const TRIP_THING = '(?:(?:a|an|some|the|cheap|cheapest|good) )?(?:(?:(?:weekend|family|beach|ski|honeymoon|birthday|anniversary|business|work|quick|short|long|girls|guys) )?(?:trip|vacation|getaway|holiday)|(?:flights?|hotels?|hotel rooms?|places? to stay)(?: (?:and|&|\\+) (?:a |some )?(?:flights?|hotels?|hotel rooms?|places? to stay))?)';
+/** When the trip is, after its place: `next week`, `this weekend`, `in december`, `on nov 3`, `for 5 days`. */
+const MONTH = '(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|june?|july?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)';
+const NUMBER = '(?:a|an|one|two|three|four|five|six|seven|eight|nine|ten|\\d{1,2})';
+const WHEN = `(?: (?:next|this) (?:week|weekend|month|year|summer|winter|spring|fall)| tomorrow| tonight| in ${MONTH}| in ${NUMBER} (?:days?|weeks?|months?)| on ${MONTH} \\d{1,2}(?:st|nd|rd|th)?| ${MONTH} \\d{1,2}(?:st|nd|rd|th)?(?: ?- ?\\d{1,2})?| for ${NUMBER} (?:days?|nights?|weeks?)| over (?:thanksgiving|christmas|new year'?s|the holidays|spring break))*`;
+/** A trip with where it goes: one to three words of place, then only words of when. */
+const TRIP_ASK = new RegExp(`^${TRIP_LEAD}${TRIP_THING} (?:to|in|at|near|for|around) (\\p{L}[\\p{L}'.-]*(?: \\p{L}[\\p{L}'.-]*){0,2}?)${WHEN}$`, 'u');
+/** Words that make the place a sentence about a trip already booked or a price: `my flight to jfk is delayed`, `flights to cancun cost a fortune`. */
+const TRIP_TOLD = /\b(?:is|are|was|were|be|been|got|gets|get|delayed|cancell?ed|booked|landed|left|leaves|leaving|late|cheaper|cheap|expensive|pricey|cost|costs|price|prices|worth|good|bad|ok|okay|fine|over|done|sucks?|suck|lol|sounds?|seems?|looks?)\b/;
+/** Places close to home that a trip word can name and no flight or hotel goes to: `a trip to the store`, `a trip to walmart`, `a trip to target.com`. */
+const NOT_A_TRIP_PLACE = /^(?:the (?:store|shop|mall|grocery store|supermarket|gym|doctor|dentist|bank|vet|post office|office|pharmacy|market)|work|school|bed|me|us|you|my|our|it|this|that|walmart|target|costco|best ?buy|home depot|lowe'?s|trader joe'?s|whole foods|safeway|kroger|cvs|walgreens|ikea|aldi|publix|sam'?s club|amazon)\b|\.(?:com|co|net|org|shop|store|us|uk|ca|io)\b/;
+/** The verb a trip ask opens with, read off before the trip reads back. */
+const TRIP_VERB = /^(?:plan|organi[sz]e|arrange)\b[\s,]*/;
+/** True when the message's words, openings taken off, ask for a trip, flights or a hotel and name the place. */
+export function isTripAsk(bare) {
+    const match = TRIP_ASK.exec(bare.replace(/\s*\?+$/, ''));
+    return match !== null && !TRIP_TOLD.test(match[1]) && !NOT_A_TRIP_PLACE.test(match[1]);
+}
+/**
+ * Whether a message that passed `isProductAsk`'s checks for small talk, the account and a story of what happened goes straight
+ * as a trip ask: a question goes only when it asks Agentcard to plan it (`can you help me plan a trip to italy?`).
+ */
+export function tripAskGoesStraight(raw, bare) {
+    if (!TRAVEL.goStraight || !isTripAsk(bare))
+        return false;
+    return !/\?/.test(raw) || /^(?:can|could|would|will) (?:you|u)\b/.test(bare);
+}
+/** The read-back without the verb that asked for the trip: `plan a trip to loreto` reads back `a trip to loreto`. Any other words, `plan b emergency contraception` too, read back as they are. */
+export function withoutTripVerb(text) {
+    return TRAVEL.goStraight && isTripAsk(text) ? text.replace(TRIP_VERB, '') : text;
+}
+const OPENING_LINE = 'Buy what this shopper asks for at real stores.';
+const TRAVEL_LINES = 'You also plan and book trips: flights and hotels. When the shopper asks to plan a trip, or for flights or a hotel, such as "help me plan a trip to Loreto" or "flights and hotels in loreto", call this tool with their words, even when they name no dates and no place they leave from: Agentcard asks them for what it needs.';
+const CAPABILITY_END = 'so name those, and no other store unless a result showed it.';
+const CAPABILITY_TRAVEL = 'Name flights and hotels for a trip among the kinds of things you can do.';
+/** The tool's description with travel named, when `inCapabilities` is on (or `on` says so); the description as given when off. */
+export function withTravel(description, on = TRAVEL.inCapabilities) {
+    if (!on)
+        return description;
+    return description.replace(OPENING_LINE, `${OPENING_LINE} ${TRAVEL_LINES}`).replace(CAPABILITY_END, `${CAPABILITY_END} ${CAPABILITY_TRAVEL}`);
+}

package/dist/turn-reader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `streamTurn` sends the shopper's message and reads the turn's server-sent events in the browser. When the connection
+ * drops before the turn's last event, or before the first one, it reads the turn's record by its id from your server
+ * (`readTurn` behind a route of yours) and hands over each event the stream did not, so the shopper gets the answer.
+ * A 409 that names the turn already running for this shopper (`turn_id`) waits for that turn's answer the same way.
+ */
+import { type TurnRecord } from './turn-record.js';
+/** The part of a fetch `Response` the reader uses. */
+export interface TurnResponseLike {
+    ok: boolean;
+    status: number;
+    body: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+export interface StreamTurnOptions {
+    /** Sends the shopper's message with the turn's id, such as in an `x-turn-id` header, and returns the response. */
+    start(turnId: string): Promise<TurnResponseLike>;
+    /** Reads the turn's record from your server, or null while it has none. `readTurn` answers it there. */
+    read(turnId: string): Promise<TurnRecord | null>;
+    /** Hears each event once, in the order the turn sent them, whether the stream or the record carried it. */
+    onEvent(event: string, data: unknown): void;
+    /** The turn's id. Defaults to a new random one. */
+    turnId?: string;
+    /** How often the record is read after a drop, in milliseconds. Defaults to 1,500. */
+    pollMs?: number;
+    /** How long a record that never appears is waited for before the drop counts as the error, in milliseconds. Defaults to 15,000. */
+    startWaitMs?: number;
+    /** How long a turn's record is read before giving up, in milliseconds. Defaults to 300,000. */
+    waitMs?: number;
+    /** Whether a drop reads the record. Defaults to `TURN_RECOVERY_ON`. */
+    recover?: boolean;
+    /** Stops reading the record once it aborts, as the abort of your own fetch stops the stream. */
+    signal?: AbortSignal;
+}
+export interface StreamTurnResult {
+    /** The id of the turn whose events were heard: the running turn's after a 409 that named one. */
+    turnId: string;
+    /** True when some of the events came from the record, after a drop or a 409. */
+    recovered: boolean;
+    /** The response, when the server refused the message and no turn's answer was waited for: read its error from it. */
+    refused?: TurnResponseLike;
+}
+export declare function streamTurn(options: StreamTurnOptions): Promise<StreamTurnResult>;
+/** The record your server's route answers, read back: a helper for `read`, such as `(id) => fetch(...).then(readTurnResponse)`. */
+export declare function readTurnResponse(response: TurnResponseLike): Promise<TurnRecord | null>;

package/dist/turn-reader.js

@@ -0,0 +1,148 @@
+/**
+ * `streamTurn` sends the shopper's message and reads the turn's server-sent events in the browser. When the connection
+ * drops before the turn's last event, or before the first one, it reads the turn's record by its id from your server
+ * (`readTurn` behind a route of yours) and hands over each event the stream did not, so the shopper gets the answer.
+ * A 409 that names the turn already running for this shopper (`turn_id`) waits for that turn's answer the same way.
+ */
+import { TURN_RECOVERY_ON, isTurnId, parseTurnRecord } from './turn-record.js';
+const TERMINAL = new Set(['done', 'error']);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function newTurnId() {
+    const c = globalThis.crypto;
+    return c?.randomUUID?.() ?? `turn_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 12)}`;
+}
+export async function streamTurn(options) {
+    const recover = options.recover ?? TURN_RECOVERY_ON;
+    let turnId = options.turnId ?? newTurnId();
+    let heard = 0;
+    let ended = false;
+    // An error your `onEvent` throws is yours: it ends the read, and the record is not read in its place.
+    let appFailed = null;
+    const hear = (event, data) => {
+        heard++;
+        if (TERMINAL.has(event))
+            ended = true;
+        try {
+            options.onEvent(event, data);
+        }
+        catch (error) {
+            appFailed = { error };
+            throw error;
+        }
+    };
+    // A drop reads the record unless recovery is off, the turn already ended, the app's own code threw or the app aborted.
+    const recovers = (error) => recover && !ended && !appFailed && !options.signal?.aborted && error?.name !== 'AbortError';
+    // Reads the record until it holds the turn's last event, handing over what the stream had not.
+    const fromRecord = async (cause) => {
+        const startWaitMs = options.startWaitMs ?? 15_000;
+        const waitMs = options.waitMs ?? 300_000;
+        const began = Date.now();
+        let seen = false;
+        const stopIfAborted = () => {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? cause;
+        };
+        for (;;) {
+            stopIfAborted();
+            // A read that hangs counts as no record once the limit it waits under passes.
+            const left = Math.max(0, (seen ? waitMs : Math.min(startWaitMs, waitMs)) - (Date.now() - began));
+            const record = await withDeadline(Promise.resolve().then(() => options.read(turnId)), left, options.signal);
+            stopIfAborted();
+            if (record) {
+                seen = true;
+                for (const { event, data } of record.events.slice(heard))
+                    hear(event, data);
+                if (record.done || ended)
+                    return { turnId, recovered: true };
+            }
+            const waited = Date.now() - began;
+            if ((!seen && waited >= startWaitMs) || waited >= waitMs)
+                throw cause;
+            await sleep(options.pollMs ?? 1_500);
+        }
+    };
+    let response;
+    try {
+        response = await options.start(turnId);
+    }
+    catch (error) {
+        if (!recovers(error))
+            throw error;
+        return fromRecord(error);
+    }
+    if (!response.ok || !response.body) {
+        if (recover && response.status === 409) {
+            const text = await response.text().catch(() => '');
+            const running = parseJson(text)?.turn_id;
+            if (isTurnId(running)) {
+                turnId = running;
+                return fromRecord(new Error(`The chat answered ${response.status}.`));
+            }
+            return { turnId, recovered: false, refused: { ok: response.ok, status: response.status, body: null, text: async () => text } };
+        }
+        return { turnId, recovered: false, refused: response };
+    }
+    try {
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let end;
+            while ((end = buffer.indexOf('\n\n')) !== -1) {
+                const frame = buffer.slice(0, end);
+                buffer = buffer.slice(end + 2);
+                const event = /^event: (.*)$/m.exec(frame)?.[1];
+                const data = /^data: (.*)$/m.exec(frame)?.[1];
+                if (event && data !== undefined)
+                    hear(event, JSON.parse(data));
+            }
+        }
+        if (ended || !recover)
+            return { turnId, recovered: false };
+        return fromRecord(new Error('The chat stream ended before the turn did.'));
+    }
+    catch (error) {
+        if (ended && !appFailed)
+            return { turnId, recovered: false };
+        if (!recovers(error))
+            throw error;
+        return fromRecord(error);
+    }
+}
+/** The read's record, or null when it fails, has not answered within `ms`, or the app aborts first. */
+function withDeadline(read, ms, signal) {
+    let timer;
+    let stop;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), ms);
+        stop = () => resolve(null);
+        if (signal?.aborted)
+            resolve(null);
+        else
+            signal?.addEventListener('abort', stop, { once: true });
+    });
+    return Promise.race([read.catch(() => null), late]).finally(() => {
+        clearTimeout(timer);
+        if (stop)
+            signal?.removeEventListener('abort', stop);
+    });
+}
+/** A JSON body read leniently: null when it is not JSON. */
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** The record your server's route answers, read back: a helper for `read`, such as `(id) => fetch(...).then(readTurnResponse)`. */
+export async function readTurnResponse(response) {
+    if (!response.ok)
+        return null;
+    return parseTurnRecord(await response.text());
+}

package/dist/turn-record.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A turn's record: every event a chat turn sent the shopper's browser, in order, kept under the turn's id in a store
+ * the app provides, so a browser whose connection dropped reads the turn's answer back instead of losing it.
+ * This file imports nothing, so the server helper (`turnStream`) and the browser reader (`streamTurn`) share it.
+ */
+/**
+ * Whether a turn keeps its record and a dropped stream reads it back. Off until the pull request that turns it on:
+ * while it is off, `turnStream` streams without saving and `streamTurn` reports a drop as the error it was.
+ */
+export declare const TURN_RECOVERY_ON: boolean;
+/** One event of a turn, as its server-sent frame carries it: `event: <event>` and `data: <JSON of data>`. */
+export interface TurnEvent {
+    event: string;
+    data: unknown;
+}
+/** What a turn sent so far, and whether it ended: `done` is true once the turn's last event is in `events`. */
+export interface TurnRecord {
+    events: TurnEvent[];
+    done: boolean;
+}
+/** Where a turn's record lives between instances, such as Redis: the same shape as the listener's cursor store. */
+export interface TurnRecordStore {
+    /** The record saved last under `key`, or null when none was saved or it expired. */
+    load(key: string): Promise<string | null> | string | null;
+    /** Saves the record under `key`, to be kept for `ttlSeconds`. */
+    save(key: string, record: string, ttlSeconds: number): Promise<void> | void;
+}
+/** A turn id the browser makes up front: 8 to 64 letters, digits, `-` or `_`. Check one before using it in a key. */
+export declare function isTurnId(value: unknown): value is string;
+/** A stored record read back, or null when the text is not one. */
+export declare function parseTurnRecord(text: string | null | undefined): TurnRecord | null;

package/dist/turn-record.js

@@ -0,0 +1,26 @@
+/**
+ * A turn's record: every event a chat turn sent the shopper's browser, in order, kept under the turn's id in a store
+ * the app provides, so a browser whose connection dropped reads the turn's answer back instead of losing it.
+ * This file imports nothing, so the server helper (`turnStream`) and the browser reader (`streamTurn`) share it.
+ */
+/**
+ * Whether a turn keeps its record and a dropped stream reads it back. Off until the pull request that turns it on:
+ * while it is off, `turnStream` streams without saving and `streamTurn` reports a drop as the error it was.
+ */
+export const TURN_RECOVERY_ON = false;
+/** A turn id the browser makes up front: 8 to 64 letters, digits, `-` or `_`. Check one before using it in a key. */
+export function isTurnId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(value);
+}
+/** A stored record read back, or null when the text is not one. */
+export function parseTurnRecord(text) {
+    if (typeof text !== 'string')
+        return null;
+    try {
+        const record = JSON.parse(text);
+        return Array.isArray(record.events) ? { events: record.events, done: record.done === true } : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/turn-stream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `turnStream` serves one chat turn to the shopper's browser as server-sent events and keeps every event it sends in the
+ * app's store under the turn's id. The turn runs to its end whether or not the browser is still there: an event the
+ * stream can no longer carry still goes in the record, and `finished` resolves once the record holds the turn's last
+ * event. Hand `finished` to your host's `waitUntil` so a serverless function is not stopped before then.
+ * `readTurn` hands the record back to the browser's reader (`streamTurn` in `@agent-cards/commerce-sdk/browser`).
+ */
+import { type TurnRecord, type TurnRecordStore } from './turn-record.js';
+/** How long a record is kept by default: ten minutes, past the longest turn a chat waits on. */
+export declare const TURN_RECORD_TTL_SECONDS = 600;
+export interface TurnStreamOptions {
+    /** Where the record lives. */
+    store: TurnRecordStore;
+    /** The record's key: the turn's id together with your shopper's id, so one shopper never reads another's turn. */
+    key: string;
+    /**
+     * Runs the turn. Call `send` for each event the browser shows, the last one included (such as `done` or `error`).
+     * A turn that throws ends with an `error` event carrying the message in `failedText`.
+     */
+    run(send: (event: string, data: unknown) => void): Promise<void>;
+    /** How long the record is kept, in seconds. Defaults to `TURN_RECORD_TTL_SECONDS`. */
+    ttlSeconds?: number;
+    /** The text of the `error` event a turn that throws ends with. */
+    failedText?: string;
+    /** Whether to keep the record. Defaults to `TURN_RECOVERY_ON`. */
+    recover?: boolean;
+    /** Hears each save the store refused: the record then misses events until a later save lands. Log it here. */
+    onSaveError?: (error: unknown) => void;
+}
+export interface TurnStream {
+    /** The body of the response: `text/event-stream`. */
+    stream: ReadableStream<Uint8Array>;
+    /** Resolves once the turn ended and its record is saved. It never rejects. */
+    finished: Promise<void>;
+}
+export declare function turnStream(options: TurnStreamOptions): TurnStream;
+/** The turn's record under `key`, or null when the store has none, for the browser's reader to pick up where its stream stopped. */
+export declare function readTurn(store: TurnRecordStore, key: string): Promise<TurnRecord | null>;

package/dist/turn-stream.js

@@ -0,0 +1,91 @@
+/**
+ * `turnStream` serves one chat turn to the shopper's browser as server-sent events and keeps every event it sends in the
+ * app's store under the turn's id. The turn runs to its end whether or not the browser is still there: an event the
+ * stream can no longer carry still goes in the record, and `finished` resolves once the record holds the turn's last
+ * event. Hand `finished` to your host's `waitUntil` so a serverless function is not stopped before then.
+ * `readTurn` hands the record back to the browser's reader (`streamTurn` in `@agent-cards/commerce-sdk/browser`).
+ */
+import { TURN_RECOVERY_ON, parseTurnRecord } from './turn-record.js';
+/** How long a record is kept by default: ten minutes, past the longest turn a chat waits on. */
+export const TURN_RECORD_TTL_SECONDS = 600;
+export function turnStream(options) {
+    const recover = options.recover ?? TURN_RECOVERY_ON;
+    const ttl = options.ttlSeconds ?? TURN_RECORD_TTL_SECONDS;
+    const encoder = new TextEncoder();
+    const record = { events: [], done: false };
+    let controller = null;
+    let gone = false;
+    // Saves run one after another, so a slow early save never lands over a later one.
+    let saving = Promise.resolve();
+    const save = () => {
+        if (!recover)
+            return;
+        const text = JSON.stringify(record);
+        saving = saving
+            .then(() => options.store.save(options.key, text, ttl))
+            .catch((error) => {
+            try {
+                options.onSaveError?.(error);
+            }
+            catch {
+                /* the app's logging failing never stops the turn */
+            }
+        });
+    };
+    // Each event is written to JSON once, before it is kept: a value JSON cannot hold throws here, to the turn, and the
+    // record keeps a copy, so a later change to the caller's object never rewrites what the shopper was sent.
+    const send = (event, data) => {
+        if (record.done)
+            return;
+        const json = JSON.stringify(data) ?? 'null';
+        const entry = { event, data: JSON.parse(json) };
+        record.events.push(entry);
+        save();
+        if (gone || !controller)
+            return;
+        try {
+            controller.enqueue(encoder.encode(`event: ${event}\ndata: ${json}\n\n`));
+        }
+        catch {
+            // The browser left: the record still takes every event.
+            gone = true;
+        }
+    };
+    let started;
+    const ready = new Promise((resolve) => (started = resolve));
+    const stream = new ReadableStream({
+        start(c) {
+            controller = c;
+            started();
+        },
+        cancel() {
+            gone = true;
+        },
+    });
+    const finished = (async () => {
+        await ready;
+        save();
+        try {
+            await options.run(send);
+        }
+        catch {
+            send('error', { error: options.failedText ?? 'The turn could not finish.' });
+        }
+        record.done = true;
+        save();
+        await saving;
+        if (!gone) {
+            try {
+                controller?.close();
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    })();
+    return { stream, finished };
+}
+/** The turn's record under `key`, or null when the store has none, for the browser's reader to pick up where its stream stopped. */
+export async function readTurn(store, key) {
+    return parseTurnRecord(await store.load(key));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/commerce-sdk",
-  "version": "0.18.0",
+  "version": "0.18.3",
   "description": "Give your agent one tool that buys for your shoppers at real stores, and post each purchase update Agentcard sends into the shopper's chat, over a connection your server opens or a webhook endpoint.",
   "type": "module",
   "main": "dist/index.js",