@agent-cards/commerce-sdk 0.11.0 → 0.14.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,12 @@
  * 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 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';
+import { type ShopperMessage } from './shopper-message.js';
 /**
  * Where the purchase stands:
  * - `needs_input`: Agentcard asks the shopper something, or shows a cart.
@@ -51,13 +52,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 +74,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 +99,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 +128,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;
@@ -157,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;
@@ -165,12 +202,17 @@ 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>;
 }
@@ -182,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;
@@ -252,19 +306,75 @@ 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;
+    /**
+     * `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;
+    /**
+     * `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
@@ -338,6 +448,26 @@ export interface BuyTool {
      * 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
@@ -356,21 +486,34 @@ 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`, `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.
      */
     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`, `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
+     * `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
@@ -385,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,
@@ -392,7 +549,15 @@ 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' | 'instantReaction' | 'turn'> {
+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. */
@@ -422,19 +587,40 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
     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;
+    /**
+     * 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[];
     /**
      * 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. */
@@ -452,6 +638,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[];
 /**