@agent-cards/commerce-sdk 0.10.0 → 0.13.0

package/dist/browser.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `@agent-cards/commerce-sdk/browser`: the part of the package that runs in the shopper's browser.
+ * It imports no Node module, so any bundler takes it.
+ *
+ * `actionWindows` opens each step the shopper takes outside the chat (adding a card, signing in to a
+ * store, approving a payment) in a pop-up window over the chat, and closes it the moment the shopper
+ * message that ends the step arrives. On a phone, where a browser opens the pop-up as a tab, it
+ * closes that tab the same way.
+ */
+import { type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome } from './action-links.js';
+export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, type ActionLinkKind, type ActionLinkMessage, type ActionLinkOutcome, } from './action-links.js';
+/** The part of a window `window.open` returns that `actionWindows` uses. */
+export interface PopupLike {
+    readonly closed: boolean;
+    close(): void;
+    focus(): void;
+}
+/** The part of the page's `window` that `actionWindows` uses. */
+export interface WindowLike {
+    open(url: string, target: string, features: string): PopupLike | null;
+    readonly screenX?: number;
+    readonly screenY?: number;
+    readonly outerWidth?: number;
+    readonly outerHeight?: number;
+    readonly screen?: {
+        readonly availWidth?: number;
+        readonly availHeight?: number;
+    };
+    setInterval(handler: () => void, ms: number): unknown;
+    clearInterval(id: unknown): void;
+}
+/** A step's link, as the buy tool hands it over (`BuyToolLink`) or as an app passes it on: its kind and its page. */
+export interface ActionLinkLike {
+    kind: string;
+    url?: string | null;
+    /** The store a store login or an approval is for, as the buy tool names it, so a message about another store leaves it open. */
+    store?: string | null;
+    /** The link's `actionLinkId`, when the buy tool put one on it. Read from the link when absent. */
+    id?: string;
+}
+/** A step open in a pop-up. */
+export interface ActionWindow {
+    /** The link's `actionLinkId`. */
+    readonly id: string;
+    readonly kind: ActionLinkKind;
+    readonly url: string;
+    /** The store the step is for, when the link named one. */
+    readonly store: string | null;
+    /** False once the window closed, by the shopper or by `actionWindows`. */
+    readonly open: boolean;
+}
+export interface ActionWindowsOptions {
+    /** The page's window. Defaults to `globalThis.window`; pass one to test with a fake. */
+    window?: WindowLike;
+    /** The pop-up's size in CSS pixels, kept inside the screen. Defaults to 480 by 760. */
+    width?: number;
+    height?: number;
+    /** How often to check whether the shopper closed a pop-up, in milliseconds. Defaults to 500. */
+    pollMs?: number;
+    /**
+     * Hears a step that ended while its pop-up was open, after `settle` closed the pop-up. Show the step
+     * as done here.
+     */
+    onEnded?: (step: ActionWindow, outcome: ActionLinkOutcome) => void;
+    /**
+     * Hears a pop-up the shopper closed before the step ended. The step is still open: keep offering
+     * its link, so the shopper can open it again.
+     */
+    onClosed?: (step: ActionWindow) => void;
+}
+export interface ActionWindows {
+    /**
+     * Opens the step's page in a pop-up centered over the chat, or brings its pop-up to the front when
+     * one is open already. Returns null when the link is not a step with a page, or when the browser
+     * blocked the pop-up: then let the link open the way it would have, as a new tab. Call it from the
+     * tap's click handler, so the browser counts the tap as the reason for the pop-up:
+     *
+     * ```js
+     * a.addEventListener('click', (event) => { if (windows.open(link)) event.preventDefault(); });
+     * ```
+     */
+    open(link: ActionLinkLike): ActionWindow | null;
+    /**
+     * Hands over a shopper message (`ShopperMessage`, or any object with its `kind` and `facts`, whose
+     * `merchantName` keeps one store's message from closing another store's step).
+     * Each open pop-up whose step the message ends closes, and `onEnded` hears it. Returns the steps it
+     * ended, with how each ended; an empty list when the message ends none.
+     */
+    settle(message: ActionLinkMessage): {
+        step: ActionWindow;
+        outcome: ActionLinkOutcome;
+    }[];
+    /** The open pop-up for the link, or null. */
+    get(link: ActionLinkLike): ActionWindow | null;
+    /**
+     * Stops watching every pop-up, and leaves each one as it is: a chat that reloads or remounts never
+     * shuts the page a shopper is typing a card into. Call it when the chat goes away.
+     */
+    dispose(): void;
+}
+/**
+ * Opens each step outside the chat in a pop-up and closes it when the step ends. One per chat page.
+ * The pop-up keeps its opener, deliberately: a window opened with `noopener` hands back no handle,
+ * so the chat could neither close it nor tell when the shopper closed it.
+ */
+export declare function actionWindows(options?: ActionWindowsOptions): ActionWindows;

package/dist/browser.js

@@ -0,0 +1,118 @@
+/**
+ * `@agent-cards/commerce-sdk/browser`: the part of the package that runs in the shopper's browser.
+ * It imports no Node module, so any bundler takes it.
+ *
+ * `actionWindows` opens each step the shopper takes outside the chat (adding a card, signing in to a
+ * store, approving a payment) in a pop-up window over the chat, and closes it the moment the shopper
+ * message that ends the step arrives. On a phone, where a browser opens the pop-up as a tab, it
+ * closes that tab the same way.
+ */
+import { actionLinkId, actionLinkOutcome, isActionLink } from './action-links.js';
+export { ACTION_LINK_ENDINGS, ACTION_LINK_KINDS, actionLinkId, actionLinkOutcome, isActionLink, } from './action-links.js';
+const DEFAULT_WIDTH = 480;
+const DEFAULT_HEIGHT = 760;
+const DEFAULT_POLL_MS = 500;
+/** `width=…,height=…,left=…,top=…` for a pop-up centered over the opener, kept on its screen. */
+function featuresFor(win, width, height) {
+    const availWidth = win.screen?.availWidth ?? width;
+    const availHeight = win.screen?.availHeight ?? height;
+    const w = Math.max(320, Math.min(width, availWidth));
+    const h = Math.max(400, Math.min(height, availHeight));
+    const left = Math.max(0, Math.round((win.screenX ?? 0) + ((win.outerWidth ?? w) - w) / 2));
+    const top = Math.max(0, Math.round((win.screenY ?? 0) + ((win.outerHeight ?? h) - h) / 2));
+    return `popup=yes,width=${w},height=${h},left=${left},top=${top}`;
+}
+const view = (t) => t.step;
+/**
+ * Opens each step outside the chat in a pop-up and closes it when the step ends. One per chat page.
+ * The pop-up keeps its opener, deliberately: a window opened with `noopener` hands back no handle,
+ * so the chat could neither close it nor tell when the shopper closed it.
+ */
+export function actionWindows(options = {}) {
+    const open = new Map();
+    let timer = null;
+    const win = () => options.window ?? (globalThis.window ?? null);
+    const stopIfIdle = () => {
+        if (open.size === 0 && timer !== null) {
+            win()?.clearInterval(timer);
+            timer = null;
+        }
+    };
+    const poll = () => {
+        for (const [id, tracked] of open) {
+            if (!tracked.popup.closed)
+                continue;
+            open.delete(id);
+            tracked.step.open = false;
+            options.onClosed?.(view(tracked));
+        }
+        stopIfIdle();
+    };
+    const idOf = (link) => link.id ?? actionLinkId(link);
+    return {
+        open(link) {
+            if (!isActionLink(link))
+                return null;
+            const w = win();
+            if (!w)
+                return null;
+            const id = idOf(link);
+            const known = open.get(id);
+            if (known && !known.popup.closed) {
+                known.popup.focus();
+                return view(known);
+            }
+            let popup = null;
+            try {
+                // A window named for the step: tapping the link again reaches the same window, never a second one.
+                popup = w.open(link.url, `agentcard_${id}`, featuresFor(w, options.width ?? DEFAULT_WIDTH, options.height ?? DEFAULT_HEIGHT));
+            }
+            catch {
+                popup = null;
+            }
+            if (!popup)
+                return null;
+            const tracked = { step: { id, kind: link.kind, url: link.url, store: link.store ?? null, open: true }, popup };
+            open.set(id, tracked);
+            try {
+                popup.focus();
+            }
+            catch {
+                /* a browser that refuses focus still shows the window */
+            }
+            timer ??= w.setInterval(poll, options.pollMs ?? DEFAULT_POLL_MS);
+            return view(tracked);
+        },
+        settle(message) {
+            const ended = [];
+            for (const [id, tracked] of open) {
+                const outcome = actionLinkOutcome(tracked.step, message);
+                if (!outcome)
+                    continue;
+                open.delete(id);
+                tracked.step.open = false;
+                try {
+                    tracked.popup.close();
+                }
+                catch {
+                    /* already gone */
+                }
+                ended.push({ step: view(tracked), outcome });
+            }
+            stopIfIdle();
+            for (const { step, outcome } of ended)
+                options.onEnded?.(step, outcome);
+            return ended;
+        },
+        get(link) {
+            if (!isActionLink(link))
+                return null;
+            const tracked = open.get(idOf(link));
+            return tracked && !tracked.popup.closed ? view(tracked) : null;
+        },
+        dispose() {
+            open.clear();
+            stopIfIdle();
+        },
+    };
+}

package/dist/buy-tool.d.ts

@@ -31,11 +31,11 @@
  * messages and links as one sequence, in the order they happened, and spaces
  * the messages like someone texting.
  */
-import { AgentcardClient, type BuyCart, 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 BuyStorePick, type BuyTurn, type FetchLike } from './client.js';
 import { type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolStandardSchema, type OpenAIBuyTool } from './definition.js';
 import { type BuyToolModelView } from './model-view.js';
 import { type MessagePace, type MessageStream } from './messages.js';
-import type { ShopperMessage } from './shopper-message.js';
+import { type ShopperMessage } from './shopper-message.js';
 /**
  * Where the purchase stands:
  * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
@@ -51,13 +51,21 @@ export type BuyToolStatus = 'needs_input' | 'needs_card' | 'approval_sent' | 'pl
  * card. `approval`: the page where they approve this purchase. `store_login`:
  * the page where they sign in to the store named in `store`, before Agentcard
  * can buy there. `product`: a product's page at its store, with its `title`,
- * `price`, `productId` and `imageUrl`. The page is `url`; `productId` holds no link.
+ * `price`, `productId`, `imageUrl` and `images`. The page is `url`; `productId` holds no link.
  * A flight option is a `product` link too, with a null `url`, since a flight has no page.
  * `store`: a store's page at the merchant, for a store the shopper can pick, with
  * its name in `title`, `storeId`, `etaMinutes` and `imageUrl`.
  */
 export interface BuyToolLink {
     kind: 'vault' | 'approval' | 'store_login' | 'product' | 'store';
+    /**
+     * On a `vault`, `approval` or `store_login` link, a step the shopper takes outside the chat: a stable
+     * id for the link (`actionLinkId`), the same each time the same link is handed over, with no part of
+     * the URL in it. `actionLinkOutcome(link, message)` says whether a shopper message ended the step,
+     * and `actionWindows` from `@agent-cards/commerce-sdk/browser` opens it in a pop-up that closes then.
+     * Absent on product and store links.
+     */
+    id?: string;
     /**
      * The page the link opens. Null only on a product link for a product with no page at a store, a
      * flight option: show its card with no link to open, and let `productId` pick it.
@@ -65,11 +73,19 @@ export interface BuyToolLink {
     url: string | null;
     /** When the link stops working, as an ISO 8601 timestamp, or null when Agentcard did not say. Always null on a product link. */
     expiresAt: string | null;
-    /** On a store login link: the store's name, or null when Agentcard named none. */
+    /**
+     * 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.
+     */
     store?: string | null;
     /** On a product link: the product's name. */
     title?: string;
-    /** On a product link: the price as the shopper reads it, such as `$12.99`, or null when Agentcard named none. */
+    /**
+     * On a product link: what taking the product does, so a button can say it. `reserve` is a table the
+     * shopper reserves, `book` a flight, room, class or ticket they book, and `buy` anything they buy.
+     */
+    action?: BuyToolProductAction;
+    /** On a product link: the price as the shopper reads it, such as `$12.99`, or `from $10.69` for a product priced by a size or another required choice, or null when Agentcard named none. */
     price?: string | null;
     /**
      * On a product link: Agentcard's id for the product, with no link in it. It is the `product_id` the
@@ -82,6 +98,11 @@ export interface BuyToolLink {
      * the merchant. Null when Agentcard sent none. Show it beside the title.
      */
     imageUrl?: string | null;
+    /**
+     * On a product link: every photo of the product, `imageUrl` first, at most eight; one entry for a product
+     * with one photo and none for a product with none. Show the others as thumbnails that swap the main picture.
+     */
+    images?: string[];
     /**
      * On a store link: Agentcard's id for the store, with no link in it. It is the `store_id` the model
      * reads for the same store, and the tool takes it as `store_id`, so a "Order here" button can hand it
@@ -106,17 +127,27 @@ export interface BuyToolStore {
     linkSent: boolean;
 }
 /** A product the last search found. */
+/** What taking a product does: `reserve` a table, `book` a flight, room, class or ticket, `buy` anything else. */
+export type BuyToolProductAction = 'buy' | 'reserve' | 'book';
+/** The action a product of `merchant` takes (BuyToolProductAction). */
+export declare function productAction(merchant: string | null | undefined): BuyToolProductAction;
 export interface BuyToolProduct {
     flight?: BuyFlightItinerary;
+    /** What taking it does: `reserve` a table, `book` a flight, room, class or ticket, `buy` anything else. */
+    action: BuyToolProductAction;
     id: string;
     /** Agentcard's link-free id for the product, which the model passes as `product_id` when the shopper picks it; null from an older API. */
     ref: string | null;
     name: string;
     /** The price in the minor unit of `currency`. */
     priceCents: number | null;
+    /** True when `priceCents` is the lowest price of a product priced by a required choice, which reads `from $10.69`. */
+    priceFrom?: true;
     /** The ISO 4217 code the store prices the product in, or null when Agentcard sent none. */
     currency: string | null;
     imageUrl: string | null;
+    /** Every photo of the product, `imageUrl` first, at most eight; empty when it has none. */
+    images: string[];
     store: string | null;
     /** The product's page at its store, or null when Agentcard sent none. */
     url: string | null;
@@ -152,8 +183,9 @@ export interface BuyToolResult {
     /** True when Agentcard tells the shopper how the order went, so the shopper need not reply. */
     shopper_need_not_reply: boolean;
     /**
-     * True when `onWorking` delivered this turn's instant reply, such as `got it, finding a taco`, so the
-     * shopper already heard that the request is being worked on. Absent or false when none went out.
+     * True when this turn's acknowledgement reached the shopper: the 👀 `onReaction` put on their message,
+     * or the instant reply `onWorking` sent, such as `got it, finding a taco`. The shopper already knows
+     * the request is being worked on. Absent or false when none went out.
      */
     shopper_already_told_looking?: boolean;
     conversation_id: string | null;
@@ -164,15 +196,28 @@ export interface BuyToolResult {
     next_action: BuyNextAction | null;
     /** The product the model's `product_id` picked, by its catalog id, and whether the cart now holds it; null when the call picked none. */
     pick: BuyPick | null;
-    /** The stores the reply presents to choose from, at most three, in the order the reply names them; empty when it presents none. */
+    /** The stores the reply presents to choose from, at most eight, in the order the reply names them; empty when it presents none. */
     stores: BuyToolStore[];
     /** The store the model's `store_id` picked, or the shopper's `the second one` did, and whether Agentcard selected it; null when none was picked. */
     store_pick: BuyStorePick | null;
     /** Every cart hash in this answer. */
     hashes: string[];
+    /**
+     * The cart the store's checkout is still building after this answer, or null: its cart and total reach the shopper as a
+     * message from Agentcard, and only the shopper's yes to that total confirms it.
+     */
+    cart_building?: BuyCartBuilding | null;
     /** Agentcard's answer as it came: the purchase answer, or the body of the refusal. */
     envelope: Record<string, unknown>;
 }
+/**
+ * How the tool acknowledges a shopper's message while Agentcard works on it:
+ * - `reaction`, the default: a 👀 on the shopper's own message, through `onReaction`. No text goes out.
+ * - `text`: an instant reply, such as `on it, looking for usb-c cables under $20`, through `onWorking`,
+ *   for SMS, or any chat that shows no reactions.
+ * - `none`: nothing.
+ */
+export type BuyAckMode = 'reaction' | 'text' | 'none';
 export interface BuyToolOptions {
     /** A client built with your company's credentials. Build it once and share it across every shopper's tool. */
     agentcard?: AgentcardClient;
@@ -198,9 +243,19 @@ export interface BuyToolOptions {
     fetch?: FetchLike;
     /** The pause between two reads of the conversation. Default: a timer. */
     wait?: (ms: number) => Promise<void>;
+    /**
+     * Reacts to the shopper's message with `emoji`, always `👀`, to say the tool is on it: show it on the
+     * shopper's own bubble, as a tapback. It fires once per message: the moment `buy.turn` opens on a
+     * search, or, for a message that got none, such as `yes`, once a call passes `ackDelayMs`. Never on a
+     * pick, an address, an answer to a question or a step toward checkout when the turn opens. With it,
+     * the tool sends no text acknowledgement at all, unless `ack` is `'text'`. One that throws costs
+     * nothing but the reaction.
+     */
+    onReaction?: (emoji: string) => void | Promise<void>;
     /**
      * Sends the shopper an instant reply, such as `on it, looking for usb-c cables under $20`, while
-     * Agentcard works on a new request. It goes out when Agentcard has not answered within
+     * Agentcard works on a new request, when the tool acknowledges in text: with `ack: 'text'`, or with
+     * no `onReaction`. It goes out when Agentcard has not answered within
      * `ackDelayMs`, once for the calls the model makes in one turn. A slow pick gets `adding it now`
      * for a product or `got it, one moment` for a store or a place in a list. A slow confirm gets
      * `on it, one moment`. These replies name nothing the shopper said. A code gets no reply.
@@ -208,9 +263,16 @@ export interface BuyToolOptions {
      * answer. One that throws costs nothing but the instant reply.
      */
     onWorking?: (message: string) => void | Promise<void>;
-    /** `false` sends no instant reply. A function writes it from the shopper's words instead, and an empty answer sends none. A turn whose message `instantAck` sent nothing for gets the built-in reply that names nothing. */
-    ack?: false | ((ask: string) => string | null | undefined);
-    /** How long Agentcard has to answer before the instant reply goes out. Default 1500. */
+    /**
+     * How the tool acknowledges a message (`BuyAckMode`). Left out, it reacts through `onReaction` when
+     * the tool or the turn has one, and otherwise sends text through `onWorking`, as 0.9 did. `'text'`
+     * sends text even with an `onReaction`, and `'none'`, or `false`, sends nothing. A function is
+     * `'text'` with your own words: it writes the instant reply from the shopper's words, and an empty
+     * answer sends none. A turn whose message `instantAck` sent nothing for gets the built-in reply that
+     * names nothing.
+     */
+    ack?: BuyAckMode | false | ((ask: string) => string | null | undefined);
+    /** How long Agentcard has to answer before the instant reply or the reaction goes out. Default 1500. */
     ackDelayMs?: number;
     /**
      * Called with the whole answer once per call, after its links went out and before the model reads
@@ -239,6 +301,13 @@ export interface BuyToolOptions {
      * outside the first three.
      */
     earlyCards?: boolean;
+    /**
+     * `true` sets `turn.replyAsWritten` on every turn this tool opens, unless the turn says otherwise:
+     * Agentcard's reply, when an answer only asks the shopper something (`replyAsWritten`). Show it as
+     * the turn's answer and skip the model call that would reword it. Off by default, so your model
+     * writes every answer.
+     */
+    replyAsWritten?: boolean;
 }
 /**
  * The buy tool, in the shape every agent framework takes, because their field
@@ -292,6 +361,14 @@ export interface BuyTool {
      * message that picks nothing, such as `yes`, a slow call still sends `onWorking` a reply that names nothing.
      */
     instantAck(shopperText: string): string | null;
+    /**
+     * The reaction for a shopper's message, `👀`, or null for one that starts no search, read as
+     * `instantAck` reads it. Call it the moment the message arrives, before your model runs, and put the
+     * emoji it returns on the shopper's message. When it returns one, the tool sends no reaction or text of
+     * its own for that turn, and the model reads `shopper_already_told_looking`. With `buy.turn` and
+     * `onReaction`, the turn does this for you.
+     */
+    instantReaction(shopperText: string): string | null;
     /**
      * Opens the turn of one shopper message and returns the tool for that turn: pass it to your model in
      * place of the tool, as `tools: [turn]`. Each call the model makes through it hands its links to this
@@ -299,10 +376,31 @@ export interface BuyTool {
      * keeps it in `turn.results`, and sends this turn's instant reply to its `onWorking`. A shopper who
      * sends a second message while the first still runs gets a second turn, and no link, cart or reply
      * of one reaches the other. Call it the moment the message arrives, before your model runs: with an
-     * `onWorking`, the instant reply `instantAck` would return goes out at once. An option left out falls
-     * back to the one the tool was built with.
+     * `onReaction`, a search gets its 👀 at once, and with only an `onWorking`, the instant reply
+     * `instantAck` would return goes out at once. An option left out falls back to the one the tool was
+     * built with.
      */
     turn(shopperText: string, options?: BuyToolTurnOptions): BuyToolTurn;
+    /**
+     * Opens the turn your agent takes on its own once the shopper finished a step outside the chat, such
+     * as saving a card or signing in to the store: a message whose `advances` is true. Pass it to your
+     * model as you pass `buy.turn`, with `turn.messages(history)` as the messages, and the model's answer
+     * is the shopper's next message, the step after the one they took, so they never have to say "ok"
+     * or "done" first. Post that answer in place of `message.text`, which the shopper then never reads.
+     *
+     * The turn moves the purchase only up to the shopper's own decision. Its calls never reach Agentcard
+     * with an ask, so nothing in it can place an order, confirm a cart or charge a card for the shopper.
+     * Each call reads where the purchase stands and answers with the next step: the card link, or the
+     * cart and the ask for the shopper's yes. The one exception is the yes the shopper already gave in the
+     * chat for this exact cart, when that confirm stopped for the step they just finished: it goes in for
+     * that cart's hash alone, and Agentcard refuses it if the cart changed.
+     *
+     * Returns null when there is no next step to take: a message whose `advances` is false, a message
+     * for another shopper or one whose link closed, a message this tool already took a turn for, and a
+     * message that arrives while a call for the shopper's own message is still running, since that
+     * call's answer tells the model where the purchase stands. Post `message.text` then, as before.
+     */
+    nextStep(message: ShopperMessage, options?: BuyToolTurnOptions): BuyToolTurn | null;
 }
 /**
  * One thing a turn hands the shopper: a message, such as the instant reply or a paragraph your model
@@ -321,28 +419,43 @@ export interface BuyToolTurnOptions {
      * Hears everything the turn hands the shopper, one item at a time and in the order it happened: the
      * instant reply and each message your model writes through `turn.messageStream()` or `turn.say()` as
      * `text` items, and each link as a `link` item. Show each item below the one before it, and the chat
-     * reads in the order it happened: a search's cards, then the model's words about them. Each item
+     * reads in the order it happened: a search's cards, then the model's words about them. A step link
+     * (`vault`, `approval`, `store_login`) is the one exception: it waits for the message that asks for
+     * it, and goes out right after that message, so the shopper reads the ask, then taps. Each item
      * waits for the one before it to settle. With `onItem`, the turn hands no link to a `sendLink` and
      * no instant reply to an `onWorking`, the tool's included: pass `onItem`, or those, to the turn.
      */
     onItem?: (item: BuyToolTurnItem) => void | Promise<void>;
     /**
-     * With `onItem`: spaces the turn's messages like someone texting. A message waits until
-     * `typingDelay` of it has passed since the item before it went out, so the shopper reads one message
-     * at a time. Time the model spent writing counts toward the pause. Links never wait. Default `true`;
-     * `false` hands each message over the moment it is ready, and a function returns the pause in
-     * milliseconds for a message.
+     * With `onItem` or `onMessage`: 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.
      */
     pace?: MessagePace;
-    /** With `onItem`: hears `true` when the pause before a message starts and `false` the moment that message goes out, for a typing indicator. */
+    /**
+     * `true` sets `turn.replyAsWritten` when an answer only asks the shopper something; `false` leaves it
+     * 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. */
     onTyping?: (typing: boolean) => void;
+    /**
+     * Without `onItem`: hears each message your model writes through `turn.messageStream()` or
+     * `turn.say()`, paced by `pace`, in the same order as the links `sendLink` hears. Write the model's
+     * text through the turn, and a step link (`vault`, `approval`, `store_login`) reaches `sendLink`
+     * after the message that asks for it, never before.
+     */
+    onMessage?: (message: string) => void | Promise<void>;
     /**
      * Delivers a link of this turn to the shopper, as the tool's `sendLink` does. Each call waits for it.
      * Without one, `turn.links` still takes each link, and the model reads that it went out, so return
      * `turn.links` beside the turn's reply.
      */
     sendLink?: (link: BuyToolLink) => void | Promise<void>;
-    /** Sends this turn's instant reply: at once when `turn` opens on a new request, or once a slow call passes `ackDelayMs`. */
+    /** Reacts 👀 to this turn's message: at once when `turn` opens on a new request, or once a slow call passes `ackDelayMs`. */
+    onReaction?: (emoji: string) => void | Promise<void>;
+    /** Sends this turn's instant reply in text, when the tool acknowledges in text: at once when `turn` opens on a new request, or once a slow call passes `ackDelayMs`. */
     onWorking?: (message: string) => void | Promise<void>;
     /** Called with the whole answer of each call this turn makes, after its links went out and before the model reads it. */
     onResult?: (result: BuyToolResult) => void | Promise<void>;
@@ -355,9 +468,19 @@ export interface BuyToolTurnOptions {
  * belong to this turn alone. `ack`, `links` and `results` are read-only, and JSON leaves them out, so a
  * tool runner that sends the tool to its API sends the same fields as before.
  */
-export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'turn'> {
-    /** The instant reply this turn sent to `onWorking` when it opened, or null when it sent none. */
+export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReaction' | 'turn' | 'nextStep'> {
+    /** For a turn `buy.nextStep` opened, the message whose step the shopper finished; null for a turn of a shopper message. */
+    readonly event: ShopperMessage | null;
+    /**
+     * For a turn `buy.nextStep` opened that your agent could not finish: call it before you post `message.text` instead.
+     * The message's text then reaches later turns as words the shopper read (`agentcard.delivered`), and a later
+     * `buy.nextStep` for the same event opens a turn again, as on a webhook's redelivery. Does nothing on another turn.
+     */
+    release(): void;
+    /** 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. */
+    readonly reaction: string | null;
     /**
      * The messages Agentcard posted into this shopper's chat that the model has not read yet, oldest
      * first, such as `card_added` once they saved a card: each one `agentcard.listen`'s or
@@ -383,6 +506,15 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'turn'> {
     readonly links: BuyToolLink[];
     /** The whole answer of each call this turn made, in the order the calls returned. Each read returns a new array. */
     readonly results: BuyToolResult[];
+    /**
+     * With `replyAsWritten` on: Agentcard's reply when the turn's last answer only asks the shopper
+     * something, such as a product list, a size or a cart's total and the ask for their yes, with every
+     * link taken out. Read it after the tool runs. When it is set, show it with `say()` and end the turn
+     * without calling your model again: the reply already says what the model would. Null when the option
+     * is off, before any call, after an answer your model has to word, and after a line the tool wrote
+     * 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;
     /**
      * 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
@@ -392,10 +524,14 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'turn'> {
     /**
      * A message stream whose messages become this turn's `text` items, after the items before them, as
      * `messageStream` cuts them: push your model's text as it streams, then `end` it. Start one for each
-     * model message. With `onItem`, the turn spaces them by its `pace`.
+     * model message. With `onItem`, the turn spaces them by its `pace`. `end` resolves once the messages and the step links
+     * held for them went out, and rejects with the first that failed to send.
      */
     messageStream(): MessageStream;
-    /** Cuts a whole text into messages, as `toMessages` does, and hands each one over as a `text` item. Resolves once every one went out. */
+    /**
+     * Cuts a whole text into messages, as `toMessages` does, and hands each one over as a `text` item. Resolves once every
+     * one, and every step link held for it, went out, and rejects with the first that failed to send.
+     */
     say(text: string): Promise<void>;
 }
 /** A message in the one shape the Anthropic, OpenAI and Vercel AI SDK message lists all take. */
@@ -413,6 +549,12 @@ export type BuyToolTurnMessage = {
  * or an OpenAI Responses item, they come as an assistant message of their own.
  */
 export declare function turnMessages<M extends object>(history: readonly M[] | null | undefined, told: readonly string[], shopperText: string): Array<M | BuyToolTurnMessage>;
+/**
+ * The words a `nextStep` turn hands the model as the user's message: the event, marked as no one's
+ * typing, and the instruction to take the next step now in one short message, without the filler of
+ * a step announced and a question about what comes next.
+ */
+export declare function nextStepPrompt(message: ShopperMessage): string;
 /** Shared with the merchant monitor so link eligibility uses the tool's product mapping. */
 export declare function productsOf(turn: BuyTurn): BuyToolProduct[];
 /**