@agent-cards/commerce-sdk 0.13.0 → 0.14.0

package/README.md

@@ -236,6 +236,28 @@ history = written !== null ? [...runner.params.messages, { role: 'assistant', co
 
 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.
 
+### Send a clear shopping message straight to Agentcard
+
+Your model's first call on most messages only decides to call the buy tool. Pass `direct: true` to `buyTool`, and each turn reads its message by rule, with no model, and sets `turn.direct` when the message goes straight to Agentcard: a request to buy or book something (`find me usb-c cables under $20`, `aa batteries on amazon`), a pick of what Agentcard just showed (a card's tap, `the first one`, `1 and 3`), or the answer to the question Agentcard just asked (the address, a code, `medium`, or a plain yes to the total it asked the shopper to confirm). Send the call yourself, and with `replyAsWritten` the turn makes no model call at all:
+
+```ts
+const turn = buy.turn(message, { onMessage: (text) => sendText(shopper.id, text) });
+let messages = turn.messages(history);
+if (turn.direct) {
+  const id = `toolu_direct_${crypto.randomUUID().replace(/-/g, '')}`;
+  const content = await turn.run(turn.direct.input);
+  messages = [...messages, { role: 'assistant', content: [{ type: 'tool_use', id, name: turn.name, input: turn.direct.input }] }, { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, content }] }];
+  if (turn.replyAsWritten !== null) {
+    await turn.say(turn.replyAsWritten);
+    history = [...messages, { role: 'assistant', content: turn.replyAsWritten }];
+    return;
+  }
+}
+// Otherwise run your model on `messages` as before: it words the answer to the call already made, or decides the call itself.
+```
+
+Everything else leaves `turn.direct` null for your model: a question, small talk, a change of mind such as `no` or `wait`, a command to the cart, and anything about the account or an order. A pick or an answer goes straight only when the shopper's last turn ended on Agentcard's answer, so a reply to something your model said reaches your model. `directCall(text, context)` applies the same rule to one message, for an app that keeps its own state. The option is off by default, because it moves the decision of when to call Agentcard from your model into the tool.
+
 ### 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:
@@ -254,7 +276,7 @@ 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.
+- 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. A message of Agentcard's that `onText` takes holds its place in `turn.items` as a `text` item too, and reaches `onText` alone.
 - 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.
@@ -418,18 +440,35 @@ Without a buy tool, `instantReaction(message, { nextAction, asked, stores })` an
 
 ## Show what Agentcard is doing
 
-Pass `onProgress`, and the tool asks Agentcard to stream each call. Each stage the call reaches goes to `onProgress` as it happens, `searching`, `building_cart`, `checking_out` or `working`, for a status line such as "searching amazon":
+The tool streams every call, so each part of an answer reaches your app the moment Agentcard produces it: the stage the call reached, the products a search found, each message Agentcard writes and the cart it builds. Pass a callback for each part you show:
 
 ```ts
 const buy = buyTool({
   agentcard,
   externalUserId: shopper.id,
   sendLink: (link) => textShopper(shopper.id, link.url),
-  onProgress: ({ stage }) => showStatus(shopper.id, stage),
+  onStatus: ({ text }) => showStatus(shopper.id, text),
+  onFound: ({ shown, found, more }) => showCount(shopper.id, `${shown} of ${found} shown`, more),
+  onProducts: (products, { merchantName }) => showProducts(shopper.id, merchantName, products),
+  onText: (text) => textShopper(shopper.id, text),
+  onCart: (cart, { carts }) => showCart(shopper.id, cart, carts),
 });
 ```
 
-The product cards still go out with the answer, so each card is a product the reply names. `earlyCards: true` sends the search's first three cards the moment the search answers instead, a few seconds sooner, and the answer then sends only the cards it adds. The reply often recommends other products than the search's first three, so with `earlyCards` a shopper can hold cards the reply never names. A stream that breaks after the call started reads the conversation for what the turn left, as a turn past Agentcard's budget does. Pass `stream: false` to wait for each whole answer.
+- `onStatus` hears each step the moment Agentcard starts it, as a line to show in place of loading dots: `searching Target and Walmart`, `adding it to your cart`, `working through the store's checkout`. `step` names the step, such as `searching` or `adding_to_cart`, for an app that writes its own words. A call that only writes its reply sends none, so keep your dots until the first line comes.
+- `onFound` hears how many products the searches found, after the cards it counts: `shown` cards of `found` products, such as "8 of 23 shown", each time the count grows. `more` holds the products past the cards as product links, in the order they were found, for a "show more" that runs no new search. The model never reads them.
+- `onProgress` still hears the stage, `searching`, `building_cart`, `checking_out` or `working`.
+- `onProducts` hears the products a search found the moment it answers, before Agentcard writes its reply, with the conversation, when the search ran (`asOf`) and the store's name. With `sendLink`, each product's card goes out then too, a few seconds before the answer, and the answer sends only the cards it adds. Pass `earlyCards: false` to send only the cards the answer names, with the answer: the reply often names only some of a search's products.
+- `onText` hears each message Agentcard writes, links included, the moment it is written, and after the cards of the search it is about.
+- `onCart` hears the cart a confirm would place, or null, and every cart on the table, each time a call builds or changes one, before the message that announces it.
+
+`buy.turn` takes the same callbacks, and each one left out falls back to the tool's. A turn's `onText` hears each message in its place in the turn, after the instant reply and the cards, paced by `pace`, and `turn.items` lists it; `onItem` does not hear it, so an app that passes both hears each message once.
+
+When your app shows Agentcard's messages through `onText`, the model reads `shopper_already_read_reply: true` in that call's answer and adds nothing to them, as it reads `shopper_already_told_looking` after an instant reply: end the turn without a second model call, as with `replyAsWritten`, or let the model add one short line for what the reply left out. `turn.replyAsWritten` stays null for that answer, so the reply never reaches the shopper twice, and a step link the turn holds for your model's next message goes out right after Agentcard's ask instead.
+
+A stream that breaks after the call started reads the conversation for what the turn left, as a turn past Agentcard's budget does. Pass `stream: false` to wait for each whole answer, with its cards sent beside it.
+
+Code that calls the client itself streams with `agentcard.buy(body, handlers)`: `onCatalog`, `onSegment`, `onCart` and `onDelta` hear their events in the order Agentcard sent them, each once the one before it settled, and the answer waits for the last of them. `onDelta` asks Agentcard for the pieces of each message as it writes them, a draft that each `onSegment` message replaces.
 
 ## Send each paragraph as its own message
 
@@ -492,6 +531,7 @@ The model reads one object per call:
   "approval_expires_at": null,
   "shopper_need_not_reply": false,
   "shopper_already_told_looking": false,
+  "shopper_already_read_reply": false,
   "link_sent": false,
   "product_links_sent": 0,
   "pick": null,

package/dist/ack.d.ts

@@ -14,6 +14,28 @@
  * instant reply at all, because it starts no search and Agentcard answers it fast. So does a pick of a
  * store the shopper saw, such as `order here`, or `Order from Tacos El Grullense` as a store card sends it.
  */
+/** Words a reply opens with before it says what it means, such as `ok` in `ok lets checkout` or `yes,` in `yes, sounds good`. */
+export declare const FILLER: RegExp;
+/** A bare acknowledgement, such as `its ok`, `thats fine`, `sounds good` or `works for me`, after the filler comes off. */
+export declare const ACKNOWLEDGED: RegExp;
+/** A step toward paying for the cart already on the table, such as `lets checkout`, `place the order` or `pay`, after the filler comes off. */
+export declare const CHECKOUT: RegExp;
+/**
+ * A question about the conversation, an order or how things work, such as `how did it know to msg that
+ * number?`, `is it booked?` or `where is my order`: the model answers it straight away, with no search.
+ */
+export declare const ABOUT: RegExp;
+/** A command to the cart or the order, such as `lets clear the cart`, `remove the taco` or `change the quantity to 2`. */
+export declare const CART_COMMAND: RegExp;
+/** Small talk that asks for nothing to be bought, after `please` and `thanks` come off. */
+export declare const CHITCHAT: RegExp;
+/**
+ * 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.
+ */
+export declare const CAPABILITY: RegExp;
 /**
  * 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
@@ -23,6 +45,8 @@
 export declare function namesStore(text: string, storeNames: readonly string[] | null | undefined): boolean;
 /** True when the shopper's words pick a product they already saw, such as `the first one`, `2` or a card's title with its price. */
 export declare function isPickText(text: string): boolean;
+/** The text as one plain line: lowercase, no quotes, and no dash between words. */
+export declare function plain(text: string): string;
 /**
  * True when the shopper's words start a request, and false for an answer to a question, a pick, a
  * code, small talk, or a message that carries the shopper's own details, such as a phone number or a

package/dist/ack.js

@@ -31,11 +31,11 @@ const TEMPLATES = [
  */
 const WAITS = ['one moment', 'just a sec', 'working on it', 'on it, one sec', 'hang tight', 'one sec, working on it'];
 /** Words a reply opens with before it says what it means, such as `ok` in `ok lets checkout` or `yes,` in `yes, sounds good`. */
-const FILLER = /^(?:(?:ok|okay|k|kk|yes|yeah|yea|yep|yup|ya|sure|alright|all right|cool|great|perfect|nice|so|then|and|um|uh|oh|well|hmm|now)[\s,]+)+/;
+export const FILLER = /^(?:(?:ok|okay|k|kk|yes|yeah|yea|yep|yup|ya|sure|alright|all right|cool|great|perfect|nice|so|then|and|um|uh|oh|well|hmm|now)[\s,]+)+/;
 /** A bare acknowledgement, such as `its ok`, `thats fine`, `sounds good` or `works for me`, after the filler comes off. */
-const ACKNOWLEDGED = /^(?:ok|okay|k|kk|fine|alright|all right|cool|great|perfect|good|nice|sure|yes|yeah|yep|yup|right|correct|exactly|agreed|works|(?:that|this|it) works|(?:it|that|this)(?:'?s| is) (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|all right|all good|it)|its (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|all good)|thats (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|it|all)|sounds (?:good|great|fine|perfect|right|ok|okay)|looks (?:good|great|fine|perfect|right|ok|okay)|all good|all set|no worries|no problem|np|got it|gotcha|understood|makes sense|(?:works|fine|ok|okay|good) (?:for|by|with) me|i'?m good|im good|we'?re good)(?: (?:then|now|with me|for me|to me))?$/;
+export const ACKNOWLEDGED = /^(?:ok|okay|k|kk|fine|alright|all right|cool|great|perfect|good|nice|sure|yes|yeah|yep|yup|right|correct|exactly|agreed|works|(?:that|this|it) works|(?:it|that|this)(?:'?s| is) (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|all right|all good|it)|its (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|all good)|thats (?:ok|okay|fine|good|great|perfect|cool|right|correct|alright|it|all)|sounds (?:good|great|fine|perfect|right|ok|okay)|looks (?:good|great|fine|perfect|right|ok|okay)|all good|all set|no worries|no problem|np|got it|gotcha|understood|makes sense|(?:works|fine|ok|okay|good) (?:for|by|with) me|i'?m good|im good|we'?re good)(?: (?:then|now|with me|for me|to me))?$/;
 /** A step toward paying for the cart already on the table, such as `lets checkout`, `place the order` or `pay`, after the filler comes off. */
-const CHECKOUT = /^(?:(?:let'?s|lets|i want to|we want to|i'?d like to|id like to|i'?m ready to|im ready to|ready to|can you|could you|can we|go ahead and|just|please)\s+)*(?:check ?out|pay|pay now|pay for (?:it|this|that|them|the order|my order|everything)|place (?:the |my |this |that |our )?order|place it|confirm(?: (?:the|my) (?:order|purchase|cart)| it)?|complete (?:the |my )?(?:order|purchase|checkout)|finish (?:the |my )?(?:order|purchase|checkout)|proceed(?: to (?:checkout|payment|pay))?|go ahead|go for it|buy (?:it|them|this|that|these|those)(?: now)?|order it|book it|submit (?:the |my )?order|send (?:the |my )?order|do it|go|ready|i'?m ready|im ready)(?: now| then| already)?$/;
+export const CHECKOUT = /^(?:(?:let'?s|lets|i want to|we want to|i'?d like to|id like to|i'?m ready to|im ready to|ready to|can you|could you|can we|go ahead and|just|please)\s+)*(?:check ?out|pay|pay now|pay for (?:it|this|that|them|the order|my order|everything)|place (?:the |my |this |that |our )?order|place it|confirm(?: (?:the|my) (?:order|purchase|cart)| it)?|complete (?:the |my )?(?:order|purchase|checkout)|finish (?:the |my )?(?:order|purchase|checkout)|proceed(?: to (?:checkout|payment|pay))?|go ahead|go for it|buy (?:it|them|this|that|these|those)(?: now)?|order it|book it|submit (?:the |my )?order|send (?:the |my )?order|do it|go|ready|i'?m ready|im ready)(?: now| then| already)?$/;
 /** Whole replies that answer a question the shopper was asked, after `please` and `thanks` come off. */
 const ANSWERS = new RegExp('^(?:' +
     [
@@ -53,9 +53,9 @@ const STATUS = /^(?:(?:ok|okay|yes|yep|yeah|alright|cool|great|so|done|there)[\s
  * A question about the conversation, an order or how things work, such as `how did it know to msg that
  * number?`, `is it booked?` or `where is my order`: the model answers it straight away, with no search.
  */
-const ABOUT = /^(?:(?:ok|okay|so|wait|hmm|um|uh|and|but)[\s,]+)*(?:how (?:did|does|do|come|is|was|were|are)|why (?:did|does|do|is|was|are|were|would|didn'?t|isn'?t|won'?t)|what(?:'s| is| was) (?:my|the status|happening|going on|that|this)|what happened|where(?:'s| is| are) (?:my|the order|it)|(?:is|was|has|did|will) (?:it|my|this|that|the order|the booking|the reservation)|did (?:it|that|you) (?:go|work|book|place|send|get|cancel|charge|order|change|add|remove)|will you (?:let|tell|text|notify|email|update|remind|ping|keep (?:me|us) (?:updated|posted|informed|in the loop))|when (?:will|does|do|is|did) (?:it|my|the order|they)|how long (?:will|does|until|till))\b/;
+export const ABOUT = /^(?:(?:ok|okay|so|wait|hmm|um|uh|and|but)[\s,]+)*(?:how (?:did|does|do|come|is|was|were|are)|why (?:did|does|do|is|was|are|were|would|didn'?t|isn'?t|won'?t)|what(?:'s| is| was) (?:my|the status|happening|going on|that|this)|what happened|where(?:'s| is| are) (?:my|the order|it)|(?:is|was|has|did|will) (?:it|my|this|that|the order|the booking|the reservation)|did (?:it|that|you) (?:go|work|book|place|send|get|cancel|charge|order|change|add|remove)|will you (?:let|tell|text|notify|email|update|remind|ping|keep (?:me|us) (?:updated|posted|informed|in the loop))|when (?:will|does|do|is|did) (?:it|my|the order|they)|how long (?:will|does|until|till))\b/;
 /** A command to the cart or the order, such as `lets clear the cart`, `remove the taco` or `change the quantity to 2`. */
-const CART_COMMAND = new RegExp('^(?:(?:ok|okay|so|actually|wait|and|um|uh)[\\s,]+)*(?:let\'?s |lets |can you |could you |pls |i want to |i\'?d like to |id like to |i need to |go ahead and |just )*(?:' +
+export const CART_COMMAND = new RegExp('^(?:(?:ok|okay|so|actually|wait|and|um|uh)[\\s,]+)*(?:let\'?s |lets |can you |could you |pls |i want to |i\'?d like to |id like to |i need to |go ahead and |just )*(?:' +
     [
         // Verbs that never open a search: `remove fries`, `cancel order`.
         'remove|delete|cancel|undo|start over|take off|get rid of',
@@ -66,14 +66,14 @@ const CART_COMMAND = new RegExp('^(?:(?:ok|okay|so|actually|wait|and|um|uh)[\\s,
     ].join('|') +
     ')\\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)$/;
+export 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))?$/;
+export 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)';
 /**
@@ -226,7 +226,7 @@ const LEADING_PREPOSITION = /^(?:from|at|in|on|to|for|of|with|by|near|into|onto|
 const MAX_WORDS = 8;
 const MAX_WORD_LENGTH = 24;
 /** The text as one plain line: lowercase, no quotes, and no dash between words. */
-function plain(text) {
+export function plain(text) {
     return text.toLowerCase().replace(/[‘’]/g, "'").replace(/["“”`]/g, '').replace(/\s+[-–—]+\s+|[–—]/g, ' ').replace(/\s+/g, ' ').trim();
 }
 /**

package/dist/buy-tool.d.ts

@@ -31,8 +31,9 @@
  * messages and links as one sequence, in the order they happened, and spaces
  * the messages like someone texting.
  */
-import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
+import { AgentcardClient, type BuyCart, type BuyCartBuilding, type BuyFlightItinerary, type BuyDeliveryAddress, type BuyNextAction, type BuyPick, type BuyProgress, type BuyTurnStatus, type BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
+import { type DirectCall } from './direct.js';
 import { type BuyToolModelView } from './model-view.js';
 import { type MessagePace, type MessageStream } from './messages.js';
 import { type ShopperMessage } from './shopper-message.js';
@@ -188,6 +189,11 @@ export interface BuyToolResult {
      * the request is being worked on. Absent or false when none went out.
      */
     shopper_already_told_looking?: boolean;
+    /**
+     * True when every message of Agentcard's answer reached the shopper through `onText` as it was written, so the shopper
+     * already read `reply`. Absent or false when any message did not go out that way, and when the tool wrote the reply.
+     */
+    shopper_already_read_reply?: boolean;
     conversation_id: string | null;
     order_id: string | null;
     decline_code: string | null;
@@ -218,6 +224,18 @@ export interface BuyToolResult {
  * - `none`: nothing.
  */
 export type BuyAckMode = 'reaction' | 'text' | 'none';
+/**
+ * How many products a turn's searches found, sent each time the count grows, after the cards it counts: `shown` cards of
+ * `found` products, "8 of 23 shown". `more` holds the products found past the cards, in the order they were found, as
+ * product links the app reveals on "show more" with no new search; the model never reads them. Find mode sends a count
+ * with no `more`.
+ */
+export interface BuyToolFound {
+    conversationId: string;
+    shown: number;
+    found: number;
+    more: BuyToolLink[];
+}
 export interface BuyToolOptions {
     /** A client built with your company's credentials. Build it once and share it across every shopper's tool. */
     agentcard?: AgentcardClient;
@@ -288,17 +306,58 @@ export interface BuyToolOptions {
      */
     onProgress?: (progress: BuyProgress) => void;
     /**
-     * `false` waits for each whole answer. With `onProgress`, or with `earlyCards` and `sendLink`, the
-     * tool asks Agentcard to stream the call, and each stage goes to `onProgress` as it happens.
+     * Called the moment Agentcard starts a step of a call, with a short line to show in place of loading dots, such as
+     * `searching Target and Walmart` or `adding it to your cart`. No status comes for a call that only writes its reply, so
+     * keep the dots until the first one. One that throws costs nothing but the call to it.
+     */
+    onStatus?: (status: BuyTurnStatus) => void;
+    /**
+     * Hears how many products a call's searches found, each time the count grows (`BuyToolFound`), right after the cards it
+     * counts went out through `sendLink`. It needs `earlyCards`, the default: with the cards held for the answer, no count
+     * comes. One that throws costs nothing but the call to it.
+     */
+    onFound?: (found: BuyToolFound) => void | Promise<void>;
+    /**
+     * Hears the products a call's search found, the moment the search answers and before Agentcard writes its reply,
+     * with the conversation, when the search ran (`asOf`, as the answer's `catalog.as_of` names it) and the store's name.
+     * Show them as the answer's cards. Like `sendLink`, it hears every call; pass it to `buy.turn` to hear only the calls
+     * of one turn. One that throws costs nothing but the call to it.
+     */
+    onProducts?: (products: BuyToolProduct[], search: {
+        conversationId: string;
+        asOf: string | null;
+        merchantName: string;
+    }) => void | Promise<void>;
+    /**
+     * Hears each message Agentcard writes for the shopper, the moment it is written, links included, as `result.reply`
+     * and `result.messages` hold them. A message that lands before the instant reply was due quiets it, and one after it
+     * follows it. When every message of an answer went out through it, the model reads `shopper_already_read_reply` and
+     * adds nothing to them. One that throws leaves that flag false, so the model words the answer.
+     */
+    onText?: (text: string, info: {
+        conversationId: string | null;
+    }) => void | Promise<void>;
+    /**
+     * Hears the carts each time a call builds or changes one, before the message that announces it: the cart a confirm
+     * would place, or null, and every cart on the table. One that throws costs nothing but the call to it.
+     */
+    onCart?: (cart: BuyCart | null, info: {
+        carts: BuyCart[];
+        conversationId: string;
+    }) => void | Promise<void>;
+    /**
+     * `false` waits for each whole answer, and a search's cards go out with the answer that names them. Left out, the
+     * tool streams each call: the stages reach `onProgress`, the products `onProducts` and their cards `sendLink` the
+     * moment the search answers, each message `onText`, and the carts `onCart`, as Agentcard produces them. A call with
+     * none of these to hear it asks for the whole answer.
      */
     stream?: false;
     /**
-     * `true` sends the store pages of a search's first three products to `sendLink` the moment the search
-     * answers, before Agentcard writes its reply, and the answer then sends only the pages it adds. Off by
-     * default: the reply often recommends other products than the search's first three, so a shopper
-     * would hold cards the reply never names. Measured on five live searches on 2026-10-20, the early
-     * pages arrived 2.2 to 3.3 seconds before the answer, and in four of them the reply named a product
-     * outside the first three.
+     * Default `true`: the store page of every product a search found, at most eight, goes to `sendLink` the moment the
+     * search answers, before Agentcard writes its reply, and the answer then sends only the pages it adds. Measured on
+     * five live searches on 2026-10-20, the early pages arrived 2.2 to 3.3 seconds before the answer. `false` waits for
+     * the answer and sends only the cards it names: the reply often names only some of the search's products, so early
+     * cards can include ones the reply never names.
      */
     earlyCards?: boolean;
     /**
@@ -308,6 +367,14 @@ export interface BuyToolOptions {
      * writes every answer.
      */
     replyAsWritten?: boolean;
+    /**
+     * `true` reads each shopper message `buy.turn` opens by rule, with no model, and sets `turn.direct` to the call
+     * it makes straight to Agentcard when the message is a request to buy, a pick of what Agentcard just showed, or
+     * the answer to the question Agentcard just asked (`directCall`). Send it with `turn.run(turn.direct.input)` and
+     * skip your model's first call; every other message, small talk and questions among them, leaves `turn.direct`
+     * null for your model to decide. Off by default, so your model decides every call.
+     */
+    direct?: boolean;
 }
 /**
  * The buy tool, in the shape every agent framework takes, because their field
@@ -427,7 +494,7 @@ export interface BuyToolTurnOptions {
      */
     onItem?: (item: BuyToolTurnItem) => void | Promise<void>;
     /**
-     * With `onItem` or `onMessage`: how the turn's messages are spaced. Default `false`: each message goes
+     * With `onItem`, `onMessage` or `onText`: how the turn's messages are spaced. Default `false`: each message goes
      * out the moment it is ready. `true` spaces them like someone texting: a message waits until
      * `typingDelay` of it has passed since the item before it went out, and time the model spent writing
      * counts toward the pause. A function returns the pause in milliseconds for a message. Links never wait.
@@ -438,7 +505,7 @@ export interface BuyToolTurnOptions {
      * null, so your model rewords every answer. Default: the tool's `replyAsWritten`.
      */
     replyAsWritten?: boolean;
-    /** With `onItem` or `onMessage`: hears `true` when the pause before a message starts and `false` the moment that message goes out, for a typing indicator. */
+    /** With `onItem`, `onMessage` or `onText`: hears `true` when the pause before a message starts and `false` the moment that message goes out, for a typing indicator. */
     onTyping?: (typing: boolean) => void;
     /**
      * Without `onItem`: hears each message your model writes through `turn.messageStream()` or
@@ -461,6 +528,20 @@ export interface BuyToolTurnOptions {
     onResult?: (result: BuyToolResult) => void | Promise<void>;
     /** Called with each stage Agentcard reaches on a call this turn makes. */
     onProgress?: (progress: BuyProgress) => void;
+    /** Called with each step Agentcard starts on a call this turn makes, as the tool's `onStatus` is. */
+    onStatus?: BuyToolOptions['onStatus'];
+    /** Hears how many products this turn's calls found, as the tool's `onFound` does. */
+    onFound?: BuyToolOptions['onFound'];
+    /** Hears the products each search of this turn's calls found, the moment it answers, as the tool's `onProducts` does. */
+    onProducts?: BuyToolOptions['onProducts'];
+    /**
+     * Hears each message Agentcard writes for this turn's calls, as the tool's `onText` does, in its place in the turn:
+     * after the instant reply and every card handed over before it, paced by `pace`. `turn.items` lists each one as a
+     * `text` item, and `onItem` does not hear it.
+     */
+    onText?: BuyToolOptions['onText'];
+    /** Hears the carts each time a call of this turn builds or changes one, as the tool's `onCart` does. */
+    onCart?: BuyToolOptions['onCart'];
 }
 /**
  * The buy tool for one shopper message, from `buy.turn`. It is the same tool, with the same name,
@@ -515,10 +596,18 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
      * itself for your model, such as the note that the cart changed or a `nextStep` turn's ask for the yes.
      */
     readonly replyAsWritten: string | null;
+    /**
+     * With `direct` on: the call this turn's message makes straight to Agentcard, with no model deciding it, and why,
+     * or null when your model decides. It is set when the turn opens, from what Agentcard last asked the shopper.
+     * Send it with `run(direct.input)`, which returns what your model would read, then show `replyAsWritten` when it
+     * is set; when it is null, hand your model the call and its result, and its words answer the shopper.
+     */
+    readonly direct: DirectCall | null;
     /**
      * Every message and link the turn handed over, in the order they went out: the instant reply, each
-     * link, and each message written through `messageStream()` or `say()`. An item its send threw on is
-     * left out. Return it as the turn's answer, and an app renders it in order. Each read returns a new array.
+     * link, each message of Agentcard's that `onText` took, and each message written through `messageStream()`
+     * or `say()`. An item its send threw on is left out. Return it as the turn's answer, and an app renders it
+     * in order. Each read returns a new array.
      */
     readonly items: BuyToolTurnItem[];
     /**