@agent-cards/commerce-sdk 0.16.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
 
@@ -409,7 +410,7 @@ A reaction is the default acknowledgement. It names nothing the shopper said, so
 
 - A message that starts a search gets it the moment `buy.turn` opens, before your model runs.
 - A pick of a product or a store the shopper saw, an address or other details, an answer to a question such as `yes`, `2` or a code, a step toward checkout such as `ok lets checkout`, and an acknowledgement such as `its ok` get none when the turn opens, because Agentcard answers them fast.
-- A call that Agentcard has not answered within 1.5 seconds puts the 👀 on a message that has none yet: a slow `yes`, a pick, or a confirm that is still placing the order. It sends no text.
+- A call that Agentcard has not answered within 1 second puts the 👀 on a message that has none yet: a slow `yes`, a pick, or a confirm that is still placing the order. It sends no text.
 - A turn that runs long, even past a minute, still gets no text line. A search often takes 10 to 40 seconds, so a line at any wait short enough to help would land on most searches and bring back the chatter the reaction replaces. To show a long wait, pass `onProgress` and show its stage, such as `checking_out`, as a status line or a typing indicator.
 
 With `onItem` on `buy.turn`, the 👀 still goes to `onReaction` and never joins the turn's items, because it sits on the shopper's bubble rather than in the agent's sequence. Without an `onReaction`, the text instant reply is the turn's first `text` item, as before.
@@ -431,9 +432,9 @@ const buy = buyTool({
 
 `ack` takes `'reaction'`, `'text'` or `'none'`. Left out, the tool reacts when the tool or the turn has an `onReaction`, and sends text through `onWorking` otherwise, so an app built on 0.9 with only `onWorking` keeps its text replies. With both callbacks, the shopper gets the 👀 and never the text too. `'none'`, or `false`, sends nothing.
 
-In text mode, the tool sends the reply when Agentcard has not answered a new request within 1.5 seconds, so a quick answer arrives alone. It sends one for the calls the model makes in one turn, where a call that starts within 15 seconds of the last one ending counts as the same turn. A slow confirm or pick never hears `looking for`: a pick of a product the shopper saw hears `adding it now`, a pick of a store or a place in a list, such as `the first one`, hears `got it, one moment`, and a confirm hears `on it, one moment`. None of them names anything the shopper said, and a code hears nothing. The words rotate through six templates, and one tool never sends the same template twice in a row. A short paraphrase of the request goes in when the tool can read one: it stops before any link, email address, phone number, street address or long number, and a request that starts with one gets a reply that names nothing, such as `looking for that now`. The call waits for `onWorking`, so the shopper reads the reply before any link and before the model answers. An `onWorking` that throws costs only the instant reply.
+In text mode, a streamed search's reply is Agentcard's own line, written from the conversation while it searches, such as `one sec, checking target for la croix`, and it reaches `onWorking` before the cards or not at all. A search `buy.turn` sends straight that has shown the shopper nothing by twice `ackDelayMs`, because Agentcard wrote no line or its line was dropped, sends `one moment` once, and a line of Agentcard's that comes after it is dropped. When your model's run fails before it wrote or called anything, call `turn.end()` before you show your error, so no wait line follows it. With `stream: false`, the tool sends its own reply when Agentcard has not answered a new request within `ackDelayMs`, 1 second by default, so a quick answer arrives alone. It sends one for the calls the model makes in one turn, where a call that starts within 15 seconds of the last one ending counts as the same turn. A slow confirm or pick never hears `looking for`: a pick, of a product, a store or a place in a list such as `the first one`, hears `got it, one moment`, a confirm hears `on it, one moment`, and any other answer hears `one moment`. A turn opened with `buy.turn` that has shown the shopper nothing, no line and no card, after the delay sends that line once. None of them names anything the shopper said, and a code hears nothing. The words rotate through six templates, and one tool never sends the same template twice in a row. A short paraphrase of the request goes in when the tool can read one: it stops before any link, email address, phone number, street address or long number, and a request that starts with one gets a reply that names nothing, such as `looking for that now`. The call waits for `onWorking`, so the shopper reads the reply before any link and before the model answers. An `onWorking` that throws costs only the instant reply.
 
-Pass `ack: (ask) => text` to write your own text from the shopper's words, where an empty answer sends none, and `ackDelayMs` to change the 1.5 seconds for either mode.
+Pass `ack: (ask) => text` to write your own text from the shopper's words, where an empty answer sends none, and `ackDelayMs` to change the 1 second for either mode.
 
 The model takes several seconds to call the tool after the shopper's message arrives. Without `buy.turn`, react sooner by calling `buy.instantReaction(message)` the moment the message arrives, before your model runs, and put the emoji it returns on the message. In text mode, call `buy.instantAck(message)` and send the text it returns:
 
@@ -447,7 +448,7 @@ if (ack) await textShopper(shopper.id, ack);
 
 With `buy.turn`, pass `onReaction` or `onWorking` to the turn instead: it acknowledges the moment the turn opens, and calls `instantReaction` or `instantAck` for you. When either returns a 👀 or a reply, the tool sends none of its own for that turn.
 
-`instantReaction` and `instantAck` return null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a step toward paying for the cart such as `ok lets checkout`, `place the order` or `pay`, an acknowledgement such as `its ok`, `thats fine` or `sounds good`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a pick of a store, such as `order here` or a store card's `Order from Tacos El Grullense`, a code, small talk such as `hi` or `how are you`, a message that carries the shopper's own details, such as a name with a phone number, an email address, a street address, a bare house number and street such as `1801 wedemeyer`, or a zip code, any message that answers the last answer's request for an address, shipping or guest details or a code, and a short reply right after any other question the last answer asked, such as `im a 37` after `what size do you want?`, or `carne asada` after `which meat?`. A reply that opens a new request, such as `find me black running shoes`, or that runs past four words is still a search. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed, or names one of the stores its last answer listed and nothing else to buy, as a pick of it. A request for a store the shopper did not see, such as `order from chipotle`, reads back as `looking for chipotle`, never `looking for from chipotle`. When it returns a reply, the tool sends none of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still acknowledges: with a 👀 in reaction mode, and in text mode with an `onWorking` reply that names nothing and never says it is looking for anything, such as `working on it` or `one moment`, and when it returns null for a pick, such a call sends `adding it now` or `got it, one moment`.
+`instantReaction` and `instantAck` return null for a message that starts no search: a confirmation or a short answer such as `yes`, `1` or `ok`, a step toward paying for the cart such as `ok lets checkout`, `place the order` or `pay`, an acknowledgement such as `its ok`, `thats fine` or `sounds good`, a pick of a product the shopper already saw, such as `the first one`, `#2`, `I want the blue one` or a card's title with its price, a pick of a store, such as `order here` or a store card's `Order from Tacos El Grullense`, a code, small talk such as `hi` or `how are you`, a message that carries the shopper's own details, such as a name with a phone number, an email address, a street address, a bare house number and street such as `1801 wedemeyer`, or a zip code, any message that answers the last answer's request for an address, shipping or guest details or a code, and a short reply right after any other question the last answer asked, such as `im a 37` after `what size do you want?`, or `carne asada` after `which meat?`. A reply that opens a new request, such as `find me black running shoes`, or that runs past four words is still a search. The reply never reads those details back, never repeats the shopper's own first-person words, and names the request only when it reads as a short, whole phrase; otherwise it says `on it, give me a moment` or another reply that names nothing. The tool also reads a message that quotes the name of a product its last answer showed, or names one of the stores its last answer listed and nothing else to buy, as a pick of it. A request for a store the shopper did not see, such as `order from chipotle`, reads back as `looking for chipotle`, never `looking for from chipotle`. When it returns a reply, the tool sends none of its own through `onWorking` for that turn, and the model reads `shopper_already_told_looking: true`, so the shopper hears one acknowledgement. When it returns null for a message that picks nothing, such as `yes`, a call that runs past `ackDelayMs` still acknowledges: with a 👀 in reaction mode, and in text mode with an `onWorking` reply that names nothing and never says it is looking for anything, such as `one moment`, and when it returns null for a pick, such a call sends `got it, one moment`.
 
 Without a buy tool, `instantReaction(message, { nextAction, asked, stores })` and `instantAck(message, { previous, nextAction, asked, stores })` from the package root decide the same way, and `ACK_REACTION` is the `👀` `instantReaction` returns: `previous` is the reply you sent last, so the next one comes from another template, `nextAction` is the last answer's `next_action`, `asked` is the last message the shopper read, so an answer to its question for an address, a name or a code, or a short answer to any other question it asked, gets none, and `stores` holds the names of the stores the last answer listed, so a message that picks one gets none. Pass `ack: 'none'` to the tool when you acknowledge yourself. `ackFor` is the earlier name of the same function.
 

package/dist/ack.d.ts

@@ -43,13 +43,23 @@ export declare function paraphrase(text: string): string | null;
 export declare function ackAt(index: number, text: string): string;
 /** The reply at `index` for a message that is no search: it says Agentcard is working, and never that it is looking for anything. */
 export declare function waitAt(index: number): string;
-/** What a slow call that is not a new request is doing: adding a product the shopper picked, choosing a store, or going through with a cart. */
-export type SlowStep = 'product' | 'pick' | 'confirm';
 /**
- * The reply a slow pick or confirm sends once Agentcard takes longer than the delay: fixed words that
- * name nothing the shopper said and never say `looking for`, because the shopper already chose.
+ * What a slow call that is not a new request is doing: adding a product the shopper picked, choosing a store, going
+ * through with a cart, or answering anything else, such as `yes` or an address.
+ */
+export type SlowStep = 'product' | 'pick' | 'confirm' | 'wait';
+/**
+ * The reply a slow pick, confirm or answer sends once Agentcard takes longer than the delay: fixed words that
+ * name nothing the shopper said and never say `looking for`, because the shopper already chose. A pick never
+ * says it is adding anything: a sandwich's bread can still hold the cart line up.
  */
 export declare function slowStepLine(step: SlowStep): string;
+/**
+ * Whether a model's message reads as an acknowledgement, such as `on it, looking for a dryer under $20`: one short line
+ * that opens with acknowledging words, says the turn is working, asks nothing and says nothing of what a search or a
+ * cart came to. A question, an answer such as `i can only help with shopping.`, or anything longer is not.
+ */
+export declare function readsAsAckLine(message: string): boolean;
 /** A template other than `avoid`, picked at random. */
 export declare function nextTemplate(avoid: number, random?: () => number): number;
 export interface AckForOptions {

package/dist/ack.js

@@ -298,11 +298,37 @@ export function waitAt(index) {
     return WAITS[((index % WAITS.length) + WAITS.length) % WAITS.length];
 }
 /**
- * The reply a slow pick or confirm sends once Agentcard takes longer than the delay: fixed words that
- * name nothing the shopper said and never say `looking for`, because the shopper already chose.
+ * The reply a slow pick, confirm or answer sends once Agentcard takes longer than the delay: fixed words that
+ * name nothing the shopper said and never say `looking for`, because the shopper already chose. A pick never
+ * says it is adding anything: a sandwich's bread can still hold the cart line up.
  */
 export function slowStepLine(step) {
-    return step === 'product' ? 'adding it now' : step === 'confirm' ? 'on it, one moment' : 'got it, one moment';
+    return step === 'confirm' ? 'on it, one moment' : step === 'wait' ? 'one moment' : 'got it, one moment';
+}
+/** Words that say what a search or a cart came to, which no acknowledgement can know yet. */
+const RESULT_CLAIM = /\b(found|finds?|added|adding|placed|total|totals|price[sd]?|pricing|in stock|out of stock|sold out|ordered|paid|charged|cart|costs?|here (?:are|is|'s))\b/i;
+/** The most characters a model's acknowledgement line runs to, such as `on it, looking for a dryer under $20`. */
+const ACK_LINE_MAX = 90;
+/** Words an acknowledgement opens with, such as `on it,` in `on it, looking for a dryer under $20`. */
+const ACK_OPENER = /^(?:(?:ok|okay|sure(?: thing)?|alright|all right|yes|yeah|yep|got it|on it|will do|of course|no problem|happy to help|absolutely)\b[\s,.!-]*)+/;
+/** What is left of an acknowledgement after its opening words: it says the turn is working, and nothing else. */
+const ACK_WORK = /^(?:(?:i'?ll|i'?m going to|i'?m gonna|i'?m|i am|let me|lemme|let'?s|just|now|gonna|going to)\s+)*(?:look|looking|check|checking|search|searching|finding|see what|seeing what|pull(?:ing)? up|work(?:ing)? on|dig(?:ging)?|hunt(?:ing)?|browse|browsing|start(?:ing)?)\b|^(?:one (?:moment|sec|second|minute)|a (?:moment|sec|second)|just a (?:moment|sec|second|minute)|give me a (?:moment|sec|second|minute)|hang tight|hold (?:on|tight)|two secs?|moment)\b/;
+/**
+ * Whether a model's message reads as an acknowledgement, such as `on it, looking for a dryer under $20`: one short line
+ * that opens with acknowledging words, says the turn is working, asks nothing and says nothing of what a search or a
+ * cart came to. A question, an answer such as `i can only help with shopping.`, or anything longer is not.
+ */
+export function readsAsAckLine(message) {
+    const line = String(message ?? '').trim();
+    if (line === '' || line.length > ACK_LINE_MAX || /[\r\n]/.test(line))
+        return false;
+    if (line.includes('?'))
+        return false;
+    if (RESULT_CLAIM.test(line))
+        return false;
+    // `on it` or `got it` is the whole acknowledgement; whatever follows those words has to say the turn is working.
+    const rest = line.toLowerCase().replace(ACK_OPENER, '').replace(/[\s,.!-]+$/, '');
+    return rest === '' ? ACK_OPENER.test(line.toLowerCase()) : ACK_WORK.test(rest);
 }
 /** A template other than `avoid`, picked at random. */
 export function nextTemplate(avoid, random = Math.random) {

package/dist/buy-tool.d.ts

@@ -315,12 +315,14 @@ export interface BuyToolOptions {
      */
     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, 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.
+     * Sends the shopper an instant reply, when the tool acknowledges in text: with `ack: 'text'`, or with
+     * no `onReaction`. A streamed search's reply is Agentcard's own line, such as `one sec, checking target
+     * for la croix`, written while it searches and sent before the cards or not at all; a search `buy.turn` sends
+     * straight that has shown nothing by twice `ackDelayMs` gets `one moment` instead; with `stream: false`
+     * it is the tool's template, once Agentcard has not answered within `ackDelayMs`. A pick, a confirm or
+     * any other answer that has shown nothing for `ackDelayMs` gets `got it, one moment`, `on it, one
+     * moment` or `one moment`, once for the calls the model makes in one turn. These replies name nothing
+     * the shopper said. A code gets no reply.
      * The call waits for it before it returns, so the shopper reads it before any link or the model's
      * answer. One that throws costs nothing but the instant reply.
      */
@@ -334,7 +336,7 @@ export interface BuyToolOptions {
      * 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. */
+    /** How long a turn shows the shopper nothing before the instant reply or the reaction goes out. Default 1000. */
     ackDelayMs?: number;
     /**
      * Called with the whole answer once per call, after its links went out and before the model reads
@@ -620,6 +622,13 @@ export interface BuyToolTurn extends Omit<BuyTool, 'instantAck' | 'instantReacti
      * `buy.nextStep` for the same event opens a turn again, as on a webhook's redelivery. Does nothing on another turn.
      */
     release(): void;
+    /**
+     * Ends the turn: call it once your agent is done with the message, and above all when your model's run failed before
+     * it wrote or called anything. No wait line, such as `one moment`, and no 👀 goes out after it, not even for a call
+     * still running, so the shopper never reads that the turn is still working after your app showed its error. Calling it
+     * again does nothing.
+     */
+    end(): 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. */
@@ -668,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()`
@@ -703,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