@agent-cards/commerce-sdk 0.17.0 → 0.18.0

package/README.md

@@ -242,29 +242,30 @@ Every list in the reply comes as bullet lines that start with `• `, the choice
 
 An answer that asks the shopper to choose, such as a sandwich's bread, a shirt's size or a store's own size question, carries `result.choice`: each group with every value, its option id and its extra price in `price_delta_cents`. The reply shown as written lists each value on its own `• ` line under the question, with its extra price, and so does one more `onText` message when the streamed reply named the values inside a sentence. `withChoice(text, result.choice)` lists them under any text of your own.
 
-### Send a clear shopping message straight to Agentcard
+### Let Agentcard answer shopping first
 
-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:
+Send the shopper's message to Agentcard before your model runs, and run your model only when the message is yours:
 
 ```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;
-  }
+const turn = buy.turn(message, {
+  onItem: (item) => (item.kind === 'text' ? sendText(shopper.id, item.text) : sendCard(shopper.id, item.link)), // your code
+});
+if (await turn.handled()) {
+  // Agentcard answered the shopper: keep the exchange, so your model reads it on the next message.
+  const said = turn.items.flatMap((item) => (item.kind === 'text' ? [item.text] : [])).join('\n\n');
+  history = [...turn.messages(history), { role: 'assistant', content: said }];
+  return;
 }
-// Otherwise run your model on `messages` as before: it words the answer to the call already made, or decides the call itself.
+// Otherwise run your model on turn.messages(history), as before.
 ```
 
-A turn `buy.nextStep` opens carries `turn.direct` too, with the reason `next_step`: its call reads where the purchase stands whatever the model would write, so send it the same way. With `replyAsWritten`, a step whose answer is a link, such as the approval link once the shopper saved their card, then reaches the shopper with no model call at all.
+Agentcard answers a request to buy or book, with or without a verb (`Printer paper, one ream`), a pick of what it just showed (a card's tap, `the second one`, `1 and 3`), an answer to its question (the address, a code, `medium`) and a yes to a total. When its reply only asks the shopper something, the turn sends it through `onItem`, after the cards and the card, sign-in or approval link it handed over, and `handled()` resolves `true`: no model call before the search, and none after it.
+
+Every other message comes back from Agentcard as yours in about 0.1 to 0.2 seconds, with no search, and `handled()` resolves `false`: small talk, a question, a change of mind such as `no` or `wait`, and anything about the account or an order. An answer your model has to word, such as an order placed or a refusal, resolves `false` too, and `turn.messages(history)` hands your model that answer with the shopper's message, so it words it and calls the tool no second time.
+
+`handled()` sends one call, once, and a second call resolves as the first did. A turn `buy.nextStep` opened resolves `false` and sends nothing: take it as "Take the next step once the shopper finishes one outside the chat" shows.
 
-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.
+You no longer need `direct` or `replyAsWritten` for this. They still work as they did: `direct: true` sets `turn.direct` to the call the tool's own rule reads in a message (`directCall(text, context)`), and `replyAsWritten: true` sets `turn.replyAsWritten`, for an app that sends the call itself. An app that never calls `handled()` sends nothing until its model calls the tool.
 
 ### Hand the app the turn in order
 

package/dist/buy-tool.d.ts

@@ -677,6 +677,16 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
      * is set; when it is null, hand your model the call and its result, and its words answer the shopper.
      */
     readonly direct: DirectCall | null;
+    /**
+     * Sends the shopper's message to Agentcard and resolves `true` when Agentcard answered the shopper: a request to buy, a
+     * pick of what it showed, an answer to its question or a yes to a total, whose reply only asks the shopper something
+     * and went out with `say()`. Resolves `false` when your model answers: Agentcard read the message as yours, such as
+     * small talk or a question about an order, in well under a second and with no model call, or it answered with an order
+     * placed or a refusal for your model to word, which `messages(history)` then hands it. Call it once, before your model
+     * runs; a second call resolves as the first did. A turn `buy.nextStep` opened, or one opened while a call still runs,
+     * resolves `false` and sends nothing.
+     */
+    handled(): Promise<boolean>;
     /**
      * Every message and link the turn handed over, in the order they went out: the instant reply, each
      * link, each message of Agentcard's that `onText` took, and each message written through `messageStream()`
@@ -712,6 +722,8 @@ 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 note a message carries to the model when Agentcard already answered it and left the words to the model (`handled()`). */
+export declare function handedNote(answer: string): string;
 /**
  * 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

package/dist/buy-tool.js

@@ -75,6 +75,10 @@ export function turnMessages(history, told, shopperText) {
     out.push({ role: 'user', content: shopperText });
     return out;
 }
+/** The note a message carries to the model when Agentcard already answered it and left the words to the model (`handled()`). */
+export function handedNote(answer) {
+    return `[Agentcard already answered this message with the buy tool. Its answer, for you to tell the shopper in your words, without calling the tool again for it: ${answer}]`;
+}
 /** What the model reads of a message Agentcard posted into the chat: its text with every link taken out, as `forModel` takes them out. */
 const modelText = (message) => stripLinks(String(message.text ?? ''));
 /** How often the history held a message's text when the message first went in to the model. */
@@ -533,6 +537,13 @@ function needsCard(link, body) {
         envelope: body,
     };
 }
+/**
+ * One shopper message's turn: the calls the model makes for it share its number, its instant reply and
+ * the callbacks its links and answers go to. `links` and `results` collect for a turn `buy.turn` opened,
+ * and are null for a call made straight on the tool.
+ */
+/** What a call throws when Agentcard handed the message back to the app's model (`BuyToolTurn.handled`). */
+const HANDED_BACK = Symbol('handed back');
 /** The way a turn hands over a link, or undefined when it has nowhere to send one. */
 function senderOf(t) {
     if (!t.sendLink && !t.links)
@@ -1674,7 +1685,9 @@ export function buyTool(options) {
         // A turn the tool took on its own sends no ask: it reads where the purchase stands, and only the
         // shopper's own yes to this exact cart goes in, for that cart's hash.
         const plan = t.event ? await stepPlan(t.event) : null;
-        const planned = plan && 'body' in plan ? plan.body : body;
+        const handBack = t.handBack ?? null;
+        t.handBack = null;
+        const planned = plan && 'body' in plan ? plan.body : handBack ? { ...body, hand_back: true, last_answer: handBack } : body;
         const confirmSent = plan ? 'body' in plan && planned.confirm !== undefined : confirm;
         // Agentcard writes the line that says what it is looking for (onAck) only where the shopper can read it before the
         // cards and has read nothing yet: a streamed ask, with somewhere to show it, that no reaction, reply or model's words
@@ -1949,6 +1962,9 @@ export function buyTool(options) {
                 catch (error) {
                     refusal = error;
                 }
+                // Agentcard read the message as your model's: nothing ran, so the call ends here and the turn's model answers it.
+                if (turn?.handed_back)
+                    throw HANDED_BACK;
             }
             // The store was still building the last request's cart: once it is in, the request that was refused goes as it was
             // sent, a step's own request too (a saved ask is no longer saved once its step sent it).
@@ -2433,6 +2449,18 @@ export function buyTool(options) {
             // the app's own error. A call that ends stops it too, since a call started means the timer would send nothing.
             state.dropWaitLine = () => clearTimeout(waitTimer);
         }
+        // What Agentcard last showed and asked when the turn opened, for `handled()`: its call changes them once it answers.
+        const lastAnswer = {
+            answered,
+            next_action: lastNextAction ?? null,
+            asked: lastReply ?? null,
+            products: lastAnswerProducts.map((product) => ({ product_id: product.productId, name: product.name })),
+            stores: lastAnswerStores.map((store) => ({ store_id: store.storeId, name: store.name })),
+        };
+        const openedWhileRunning = running > 0;
+        const openedNextAction = lastNextAction;
+        const openedProducts = lastAnswerProducts;
+        const openedStores = lastAnswerStores;
         if (!event)
             previousTurn = state;
         // What Agentcard told the shopper that no history the model ran with holds yet.
@@ -2471,9 +2499,70 @@ export function buyTool(options) {
             if (saved.length > 0)
                 client.forgetMessages(externalUserId, saved);
             handed = fresh;
-            return turnMessages(history, fresh.map(modelText), shopperWords);
+            // A message Agentcard answered for the model to word goes in with that answer, so the model words it and calls nothing again.
+            return turnMessages(history, fresh.map(modelText), handedAnswer === null ? shopperWords : `${shopperWords}\n\n${handedNote(handedAnswer)}`);
+        };
+        /** Says a whole text as the turn's messages, after every item before it (`say()`). */
+        const sayWhole = (whole) => {
+            writesThroughTurn = true;
+            firstWords(whole);
+            if (state.modelTurn && /\S/.test(String(whole ?? '')))
+                state.modelTurn.spoke = true;
+            const reply = feedReply(text);
+            for (const message of toMessages(whole))
+                reply.add(message);
+            const released = releaseForReply();
+            released.catch(() => { });
+            return reply.settled().then(() => released);
+        };
+        /** Agentcard's answer, as the model reads it, when `handled()` left the words to the model. */
+        let handedAnswer = null;
+        let handledRun = null;
+        /**
+         * One call to Agentcard with the shopper's message (`BuyToolTurn.handled`). A pick by its id or a yes to the total the
+         * tool reads itself goes as that call; every other message goes as its words, with `hand_back`, and Agentcard decides.
+         */
+        const runHandled = async () => {
+            const words = String(shopperText ?? '');
+            if (event || openedWhileRunning || words.trim() === '')
+                return false;
+            const local = directCall(words, { answered, nextAction: openedNextAction, asked: lastAnswer.asked, products: openedProducts, stores: openedStores });
+            const exact = !!local && (local.input.confirm || local.input.product_id !== null || local.input.store_id !== null);
+            const input = exact ? local.input : { ask: words, confirm: false, new_order: false, product_id: null, store_id: null };
+            if (!exact) {
+                state.handBack = lastAnswer;
+                // Agentcard writes the line that says what it is looking for on a search this call starts, as on a search the turn
+                // sends straight (`direct`); a message it hands back gets none, since nothing runs.
+                state.agentcardAcks = (ask) => ask.trim() === words.trim();
+            }
+            let result;
+            try {
+                result = await answerIn(input, state);
+            }
+            catch (error) {
+                state.handBack = null;
+                if (error === HANDED_BACK)
+                    return false;
+                throw error;
+            }
+            if (result.shopper_already_read_reply === true)
+                return true;
+            const reply = replyAsWritten(result, { textingStyle: texting });
+            // The reply goes out where the app hears the turn's messages: onItem or onMessage, else onText. With none of them, the
+            // shopper would read nothing, so the app's model words the answer instead.
+            if (reply !== null && (onItem || onMessage)) {
+                await sayWhole(reply);
+                return true;
+            }
+            if (reply !== null && state.onText) {
+                await state.onText(reply, { conversationId: result.conversation_id });
+                return true;
+            }
+            handedAnswer = JSON.stringify(forModel(result));
+            return false;
         };
         return toolOf((raw) => answerIn(raw, state), {}, {
+            handled: { value: () => (handledRun ??= runHandled()), enumerable: false },
             agentcardMessages: { get: () => [...(handed ?? kept)], enumerable: false },
             event: { value: event, enumerable: false },
             release: {
@@ -2525,21 +2614,7 @@ export function buyTool(options) {
                 },
                 enumerable: false,
             },
-            say: {
-                value: (whole) => {
-                    writesThroughTurn = true;
-                    firstWords(whole);
-                    if (state.modelTurn && /\S/.test(String(whole ?? '')))
-                        state.modelTurn.spoke = true;
-                    const reply = feedReply(text);
-                    for (const message of toMessages(whole))
-                        reply.add(message);
-                    const released = releaseForReply();
-                    released.catch(() => { });
-                    return reply.settled().then(() => released);
-                },
-                enumerable: false,
-            },
+            say: { value: sayWhole, enumerable: false },
         });
     };
     return toolOf(answer, { instantAck, instantReaction, turn, nextStep }, {});

package/dist/client.d.ts

@@ -242,6 +242,29 @@ export interface BuyRequest {
     user_id?: string;
     /** `false` asks for no line that says what Agentcard is looking for (`onAck`): the shopper already read one. */
     ack?: false;
+    /**
+     * `true` asks Agentcard to answer at once, with `handed_back` and no turn run, when the ask is not shopping: a request to
+     * buy, a pick of what it showed, an answer to its question or a yes to a total runs as any ask, and every other message
+     * is your model's. `buy.turn`'s `handled()` sends it. An older API ignores it and runs the ask.
+     */
+    hand_back?: true;
+    /** With `hand_back`: what Agentcard's last answer showed and asked, which decides whether a pick or an answer is shopping. */
+    last_answer?: BuyLastAnswer;
+}
+/** What the shopper's last answer from Agentcard showed and asked, sent with `hand_back`. */
+export interface BuyLastAnswer {
+    /** True when the shopper's last turn ended on Agentcard's answer, with no turn your model answered alone since. */
+    answered: boolean;
+    next_action: string | null;
+    asked: string | null;
+    products: Array<{
+        product_id: string | null;
+        name: string;
+    }>;
+    stores: Array<{
+        store_id: string;
+        name: string;
+    }>;
 }
 export type BuyStatus = 'needs_input' | 'needs_approval' | 'order_placed' | 'partially_placed' | 'declined';
 export interface BuyStore {
@@ -435,6 +458,8 @@ export interface BuyTurn {
     conversation_id: string;
     /** A status Agentcard adds later reads as `needs_input`. */
     status: BuyStatus;
+    /** True when Agentcard answered a `hand_back` ask as your model's to answer: no turn ran, and the other fields are empty. */
+    handed_back?: true;
     reply: string;
     messages: string[];
     cart: BuyCart | null;

package/dist/client.js

@@ -272,6 +272,7 @@ export function turnOf(body) {
     return {
         conversation_id: str(body.conversation_id) ?? '',
         status: typeof body.status === 'string' && STATUSES.has(body.status) ? body.status : 'needs_input',
+        ...(body.handed_back === true ? { handed_back: true } : {}),
         reply: typeof body.reply === 'string' ? body.reply : '',
         messages: Array.isArray(body.messages) ? body.messages.filter((m) => typeof m === 'string') : [],
         cart: cartOf(body.cart),

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { readPurchaseMessage, type PurchaseMessage, type PurchaseMessageKind, ty
 export { readShopperMessage, isStale, SHOPPER_EVENT_TYPES, NEXT_STEP_KINDS, type NextStepKind, type ShopperMessage, type ShopperMessageKind, type ShopperFacts, type ShopperEventType, type OrderStatus, } from './shopper-message.js';
 export { ORDER_STEPS, updateOrder, arrivalText, type ShopperOrder, type OrderStep, type OrderPathStep, type OrderStepState, type ArrivalTextOptions, } from './order.js';
 export { agentcardWebhook, purchaseAgentWebhook, type AgentcardWebhookOptions, type AgentcardWebhookHandler, type PurchaseAgentWebhookOptions, type WebhookFetchRequest, type WebhookRequest, type WebhookResponse, } from './handler.js';
-export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyChoiceGroup, type BuyChoiceOption, } from './client.js';
+export { AgentcardClient, AgentcardApiError, BUY_TURN_TIMEOUT_MS, DEFAULT_BASE_URL, type AgentcardClientOptions, type AgentcardTraceOptions, type OtelApi, type TraceContext, type FetchLike, type FetchLikeResponse, type BuyProgress, type BuyProgressStage, type BuyCatalogUpdate, type BuyAvailability, type BuyAvailabilityUpdate, type BuyFoundUpdate, type BuyTurnStatus, type BuySegmentUpdate, type BuyCartUpdate, type BuyDeltaUpdate, type BuyStreamHandlers, type Shopper, type BuyLastAnswer, type BuyRequest, type BuyDeliveryAddress, type BuyTurn, type BuyStatus, type BuyCart, type BuyCartBuilding, type BuyCartLine, type BuyCartFeeLine, type BuyStore, type BuyCatalog, type BuyCatalogItem, type BuyFlightItinerary, type BuyPaymentSource, type BuyConversation, type BuyLastCheckout, type BuyOrder, type VaultLink, type BuyNextAction, type BuyPick, type BuyStoreChoice, type BuyStorePick, type BuyStores, type BuyChoice, type BuyChoiceGroup, type BuyChoiceOption, } from './client.js';
 export { BUY_TOOL_NAME, BUY_TOOL_DESCRIPTION, buyToolDefinition, parseBuyToolInput, type BuyToolDefinition, type BuyToolInput, type BuyToolInputSchema, type BuyToolInputCheck, type BuyToolStandardSchema, type OpenAIBuyTool, } from './definition.js';
 export { toMessages, messageStream, typingDelay, type MessagePace, type MessageStream, type MessageStreamOptions, } from './messages.js';
 export { buyTool, nextStepPrompt, type BuyTool, type BuyToolOptions, type BuyToolResult, type BuyToolStatus, type BuyToolLink, type BuyToolFound, type BuyToolAvailability, type BuyToolProduct, type BuyToolProductAction, productAction, type BuyToolStore, type BuyToolTurn, type BuyToolTurnItem, type BuyToolTurnOptions, type BuyToolTurnMessage, type BuyAckMode, } from './buy-tool.js';

package/package.json

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