@agent-cards/commerce-sdk 0.13.0 → 0.15.0

package/dist/client.d.ts

@@ -44,20 +44,144 @@ export interface BuyCatalogUpdate {
     catalog: BuyCatalog;
     /** When the search ran, as the answer's `catalog.as_of` names it: the same search in the answer has the same value. */
     asOf: string | null;
+    /** How many of the products found are in `catalog.items`, the cards to show. Null when Agentcard sent no count. */
+    shown: number | null;
+    /** How many distinct products the turn's searches found so far. Null when Agentcard sent no count. */
+    found: number | null;
+    /** The products found past the cards, in the order they were found, to show on "show more" with no new search. */
+    more: BuyCatalog['items'];
 }
-/** Called while a purchase turn runs. Passing either one asks Agentcard to stream the turn. */
+/**
+ * Whether a place a card shows has room at the time the shopper asked for: `checking` while Agentcard's live search runs,
+ * `available` once it found the place open, with the open times it named in `slots` (empty when it named none),
+ * `unavailable` when it found the place full then, and `unknown` when the search ended without saying either way. Only
+ * `available` is a place to offer as a choice. A product with no such question, such as a retail product, carries none.
+ */
+export type BuyAvailability = {
+    status: 'checking';
+} | {
+    status: 'available';
+    slots: string[];
+} | {
+    status: 'unavailable';
+} | {
+    status: 'unknown';
+};
+/** What Agentcard's live search said of the places a running turn's cards show, matched to each card by its catalog `id`. */
+export interface BuyAvailabilityUpdate {
+    conversationId: string;
+    items: Array<{
+        id: string;
+        availability: BuyAvailability;
+    }>;
+}
+/** How many products a running turn found so far, and how many of them it shows: "8 of 23 shown". */
+export interface BuyFoundUpdate {
+    conversationId: string;
+    shown: number;
+    found: number;
+}
+/**
+ * What a running turn is doing, the moment a step starts: `text` is a short line to show in place of loading dots, such as
+ * `searching Target and Walmart` or `adding it to your cart`, and `step` names the step for an app that writes its own,
+ * such as `searching`, `adding_to_cart` or `store_checkout`. No status comes for a turn that only writes its reply.
+ */
+export interface BuyTurnStatus {
+    conversationId: string | null;
+    step: string;
+    text: string;
+}
+/** One message Agentcard finished writing while the turn runs, links included, as the answer's `messages` then holds it. */
+export interface BuySegmentUpdate {
+    conversationId: string | null;
+    text: string;
+}
+/** The carts on the table the moment a running turn builds or changes one, before the message that announces it. */
+export interface BuyCartUpdate {
+    conversationId: string;
+    /** The cart a confirm would place, as the answer's `cart` names it, or null when none would be. */
+    cart: BuyCart | null;
+    /** Every cart on the table, oldest first, as the answer's `carts`. */
+    carts: BuyCart[];
+}
+/**
+ * A piece of a message while Agentcard writes it. A piece can hold words Agentcard drops before the message is done, such
+ * as a line that only says it is looking, so show the pieces as a draft and replace them with each `onSegment` message.
+ */
+export interface BuyDeltaUpdate {
+    conversationId: string | null;
+    text: string;
+}
+/**
+ * Called while a purchase turn runs. Passing any one asks Agentcard to stream the turn. `onCatalog`, `onSegment`,
+ * `onCart` and `onDelta` hear their events one at a time, in the order Agentcard sent them, each once the one before it
+ * settled, so a piece of the next message never reaches the app before the message ahead of it. The client waits for
+ * the last of them before it hands back the turn's answer.
+ */
 export interface BuyStreamHandlers {
     onProgress?: (progress: BuyProgress) => void;
-    /** The client waits for what this returns before it hands back the turn's answer. */
+    /** Each step the turn starts, as a line to show while the shopper waits. */
+    onStatus?: (status: BuyTurnStatus) => void;
+    /** How many products the turn found, each time the count grows. */
+    onFound?: (update: BuyFoundUpdate) => void | Promise<void>;
     onCatalog?: (update: BuyCatalogUpdate) => void | Promise<void>;
+    /** Each message Agentcard writes, the moment it is written. */
+    onSegment?: (update: BuySegmentUpdate) => void | Promise<void>;
+    /** The carts, each time the turn builds or changes one. */
+    onCart?: (update: BuyCartUpdate) => void | Promise<void>;
+    /** Each piece of a message as Agentcard writes it. Passing it asks Agentcard for the pieces (`?stream=deltas`). */
+    onDelta?: (update: BuyDeltaUpdate) => void | Promise<void>;
+    /** Whether the places the turn's cards show have room, once Agentcard's live search says, after the cards it changes. */
+    onAvailability?: (update: BuyAvailabilityUpdate) => void | Promise<void>;
 }
 export declare const DEFAULT_BASE_URL = "https://api.agentcard.sh";
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
 export declare const BUY_TURN_TIMEOUT_MS = 130000;
+/** The W3C trace context a `POST /buy` carries, so the backend's spans join the caller's trace. */
+export interface TraceContext {
+    traceparent: string;
+    tracestate?: string;
+}
+/** The part of `@opentelemetry/api` the client calls: pass the module itself as `otel`. */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string): OtelTracer;
+    };
+    context: {
+        active(): unknown;
+    };
+    propagation: {
+        inject(context: unknown, carrier: Record<string, string>): void;
+    };
+}
+interface OtelTracer {
+    startActiveSpan<T>(name: string, options: {
+        kind?: number;
+        attributes?: Record<string, string | boolean>;
+    }, fn: (span: OtelSpan) => T): T;
+}
+interface OtelSpan {
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    end(): void;
+}
+/**
+ * How the client finds the trace a `POST /buy` belongs to. `otel` is `@opentelemetry/api`: by default the client
+ * loads it when the app installed it, and `false` turns that off. `traceContext` names the trace by hand, for an app
+ * without OpenTelemetry: return its `traceparent`, or nothing to send none. The active OpenTelemetry context wins.
+ */
+export interface AgentcardTraceOptions {
+    otel?: OtelApi | false;
+    traceContext?: () => TraceContext | string | null | undefined;
+}
 /** A company's client credentials, or one shopper's own access token. */
 export type AgentcardClientOptions = {
     baseUrl?: string;
     fetch?: FetchLike;
+    trace?: AgentcardTraceOptions;
 } & ({
     clientId: string;
     clientSecret: string;
@@ -155,7 +279,8 @@ export interface BuyCart {
     items: BuyCartLine[];
     /** The items alone, or null from an older API. */
     subtotalCents: number | null;
-    serviceFeesCents: number;
+    serviceFeesCents: number | null;
+    serviceFeesStatus?: 'known' | 'pending' | 'unknown';
     /** The store's own fee and tax lines inside `serviceFeesCents`, or null when the store itemized none. */
     merchantFeeLines: BuyCartFeeLine[] | null;
     tipCents: number;
@@ -202,6 +327,8 @@ export interface BuyCatalogItem {
     store: BuyStore | null;
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
+    /** Whether a place has room at the asked time (BuyAvailability). Absent on a product with no such question. */
+    availability?: BuyAvailability;
 }
 /**
  * The products the last search found. `presented` is true when this answer's reply presents them: the
@@ -393,6 +520,7 @@ export declare class AgentcardClient {
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     private readonly inbox;
     private readonly deliveredIds;
+    private readonly trace;
     constructor(options: AgentcardClientOptions);
     /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
     get company(): boolean;
@@ -459,3 +587,4 @@ export declare class AgentcardClient {
     private renewAfter;
     private exchange;
 }
+export {};

package/dist/client.js

@@ -10,6 +10,8 @@
  */
 import { isRecord } from './verify.js';
 import { listenToAgentcard } from './listen.js';
+/** The handlers that ask Agentcard to stream a turn. */
+const STREAM_HANDLERS = ['onProgress', 'onStatus', 'onFound', 'onCatalog', 'onSegment', 'onCart', 'onDelta', 'onAvailability'];
 const PROGRESS_STAGES = new Set(['searching', 'building_cart', 'checking_out', 'working']);
 export const DEFAULT_BASE_URL = 'https://api.agentcard.sh';
 /** The wait for one purchase turn: past Agentcard's own 110-second budget, so a slow turn answers `turn_timeout` rather than aborting here. */
@@ -24,6 +26,37 @@ const DELIVERED_PER_SHOPPER = 20;
 const DELIVERED_SHOPPERS = 10_000;
 /** The event ids the client remembers taking in, so a message delivered twice reaches the model once. */
 const DELIVERED_IDS_KEPT = 10_000;
+/** `@opentelemetry/api`, loaded once, only when the app installed it: the package depends on nothing. */
+const OTEL_API = '@opentelemetry/api';
+let otelLoaded = null;
+function loadOtel() {
+    otelLoaded ??= import(/* webpackIgnore: true */ /* @vite-ignore */ OTEL_API).then((m) => (m.trace && m.propagation && m.context ? m : m.default?.trace ? m.default : null), () => null);
+    return otelLoaded;
+}
+/** The `traceparent` and `tracestate` headers for one call: the active span's, else the app's own, else none. */
+function traceHeaders(otel, own) {
+    const carrier = {};
+    if (otel) {
+        try {
+            otel.propagation.inject(otel.context.active(), carrier);
+        }
+        catch { /* A broken propagator never stops a purchase. */ }
+        if (str(carrier.traceparent))
+            return pickTrace(carrier);
+    }
+    let given;
+    try {
+        given = own?.();
+    }
+    catch { /* An app's own trace lookup that throws sends no trace. */ }
+    const ctx = typeof given === 'string' ? { traceparent: given } : given;
+    // Only a well-formed W3C traceparent goes out: anything else would break the header or the backend's parse.
+    return isRecord(ctx) && TRACEPARENT.test(String(ctx.traceparent)) ? pickTrace(ctx) : {};
+}
+const TRACEPARENT = /^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$/;
+// A tracestate is printable ASCII of at most 512 characters (W3C); any other value is left off, so it can never stop a purchase.
+const TRACESTATE = /^[\x20-\x7e]{1,512}$/;
+const pickTrace = (c) => typeof c.tracestate === 'string' && TRACESTATE.test(c.tracestate) ? { traceparent: c.traceparent, tracestate: c.tracestate } : { traceparent: c.traceparent };
 const NEXT_ACTIONS = new Set(['shipping_details', 'guest_details', 'store_login', 'add_card', 'confirm', 'verification_code', 'approve']);
 /**
  * A refusal, or a failure to reach Agentcard. `code` is the API's own
@@ -111,6 +144,13 @@ function feeLinesOf(v) {
     const lines = v.filter(isRecord).flatMap((f) => (str(f.label) && num(f.amountCents) !== null ? [{ label: f.label, amountCents: f.amountCents }] : []));
     return lines.length ? lines : null;
 }
+function feesOf(v) {
+    const amount = num(v.serviceFeesCents);
+    const status = v.merchantFeesPending === true || v.serviceFeesStatus === 'pending' ? 'pending'
+        : (v.serviceFeesStatus === undefined || v.serviceFeesStatus === 'known')
+            && amount !== null && Number.isSafeInteger(amount) && amount >= 0 ? 'known' : 'unknown';
+    return { serviceFeesCents: status === 'known' ? amount : null, serviceFeesStatus: status };
+}
 function cartOf(v) {
     if (!isRecord(v) || !str(v.hash) || !str(v.merchant))
         return null;
@@ -135,7 +175,7 @@ function cartOf(v) {
             };
         }) : [],
         subtotalCents: num(v.subtotalCents),
-        serviceFeesCents: num(v.serviceFeesCents) ?? 0,
+        ...feesOf(v),
         merchantFeeLines: feeLinesOf(v.merchantFeeLines),
         tipCents: num(v.tipCents) ?? 0,
         totalCents: num(v.totalCents) ?? 0,
@@ -164,7 +204,12 @@ function flightOf(value) {
 function catalogOf(v) {
     if (!isRecord(v))
         return null;
-    const items = Array.isArray(v.items) ? v.items.filter(isRecord).map((i) => {
+    const items = catalogItemsOf(v.items);
+    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+}
+/** A catalog block's products, as `items` or `more` lists them. */
+function catalogItemsOf(v) {
+    return Array.isArray(v) ? v.filter(isRecord).map((i) => {
         const flight = flightOf(i.flight);
         return {
             id: str(i.id) ?? '',
@@ -178,9 +223,33 @@ function catalogOf(v) {
             ...(flight ? { flight } : {}),
             store: storeOf(i.store),
             url: pageUrl(i.url),
+            ...availabilityField(i),
         };
     }) : [];
-    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
+}
+/**
+ * A place's availability as Agentcard marks it: `checking`, `open` or `available` with the times in `slots`, `none` or
+ * `unavailable`, and `unknown`. A mark this version does not know reads as `unknown`, so no place is offered on a guess.
+ */
+function availabilityOf(v) {
+    const mark = v.availability;
+    if (mark === 'checking')
+        return { status: 'checking' };
+    if (mark === 'open' || mark === 'available') {
+        const slots = Array.isArray(v.slots) ? v.slots.filter((s) => typeof s === 'string' && s.trim() !== '') : [];
+        return { status: 'available', slots };
+    }
+    if (mark === 'none' || mark === 'unavailable')
+        return { status: 'unavailable' };
+    return typeof mark === 'string' ? { status: 'unknown' } : null;
+}
+function availabilityField(v) {
+    const availability = availabilityOf(v);
+    return availability ? { availability } : {};
+}
+/** A count Agentcard sent: a whole number, never negative. Null otherwise. */
+function countOf(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null;
 }
 /** The stores an answer presents: each one with an id and a name, and no block when none has both. */
 function storesOf(v) {
@@ -376,14 +445,21 @@ async function eachEvent(res, onEvent) {
 }
 /**
  * A streamed purchase turn, read to its `envelope`: the same answer a JSON turn returns, with its
- * status in `http_status`. Each `progress` and `catalog` goes to its handler on the way. A stream that
- * breaks or ends before its envelope, once it named the conversation, reads as a turn past its budget
+ * status in `http_status`. Each `progress`, `status`, `delta`, `catalog`, `find`, `segment`, `cart` and `venue_availability` goes to its handler
+ * on the way, and any other event, such as a `ping` or a `tool`, is read past. A stream that breaks or
+ * ends before its envelope, once it named the conversation, reads as a turn past its budget
  * (`turn_timeout`), so the tool reads the conversation for what the turn left instead of losing it.
  */
 async function readStreamedTurn(res, stream, timeoutMs) {
     let envelope = null;
     let conversationId = null;
-    const delivering = [];
+    // The catalog, segment, cart and delta handlers run one after another, in the order their events arrived, so an app
+    // never shows a message above the cards it names, nor a piece of the next message before the message ahead of it. The
+    // stream is read on meanwhile, and the answer waits for the last one. A handler that throws costs only itself.
+    let delivering = Promise.resolve();
+    const deliver = (hand) => {
+        delivering = delivering.then(() => hand()).catch(() => { });
+    };
     let failure = null;
     try {
         await eachEvent(res, (event, text) => {
@@ -391,6 +467,8 @@ async function readStreamedTurn(res, stream, timeoutMs) {
             if (!data)
                 return;
             conversationId = str(data.conversation_id) ?? conversationId;
+            // The conversation this event belongs to: its own, or the one an earlier event of the same turn named.
+            const named = conversationId;
             if (event === 'envelope') {
                 envelope = data;
                 return true;
@@ -403,19 +481,68 @@ async function readStreamedTurn(res, stream, timeoutMs) {
                     // The app's display failing never fails the turn.
                 }
             }
-            else if (event === 'catalog' && stream.onCatalog && str(data.conversation_id)) {
+            else if (event === 'status' && typeof data.text === 'string' && data.text.trim() !== '' && typeof data.step === 'string' && stream.onStatus) {
+                try {
+                    stream.onStatus({ conversationId: named, step: data.step, text: data.text });
+                }
+                catch {
+                    // The app's display failing never fails the turn.
+                }
+            }
+            else if (event === 'delta' && typeof data.text === 'string' && data.text !== '' && stream.onDelta) {
+                deliver(() => stream.onDelta({ conversationId: named, text: data.text }));
+            }
+            else if (event === 'catalog' && (stream.onCatalog || stream.onFound) && str(data.conversation_id)) {
                 const catalog = catalogOf(data.catalog);
                 if (!catalog || catalog.items.length === 0)
                     return;
-                const asOf = isRecord(data.catalog) ? str(data.catalog.as_of) : null;
-                delivering.push(Promise.resolve().then(() => stream.onCatalog({ conversationId: data.conversation_id, catalog, asOf })).catch(() => { }));
+                const block = data.catalog;
+                const asOf = str(block.as_of);
+                const shown = countOf(block.shown);
+                const found = countOf(block.found);
+                const update = { conversationId: data.conversation_id, catalog, asOf, shown, found, more: catalogItemsOf(block.more) };
+                // The count follows the cards it counts, so an app never shows "8 of 23" above no cards, and it settles before the
+                // next event, so a later count never lands before an earlier one. A card display that throws never costs the count.
+                deliver(async () => {
+                    try {
+                        await stream.onCatalog?.(update);
+                    }
+                    catch {
+                        // The app's display failing never fails the turn.
+                    }
+                    if (shown !== null && found !== null && found >= shown)
+                        await stream.onFound?.({ conversationId: update.conversationId, shown, found });
+                });
+            }
+            else if (event === 'find' && stream.onFound && str(data.conversation_id)) {
+                // Find mode's count from the product index: the cards it shows of the products it found.
+                const shown = countOf(data.shown);
+                const found = countOf(data.found);
+                if (shown !== null && found !== null && found >= shown)
+                    deliver(() => stream.onFound({ conversationId: data.conversation_id, shown, found }));
+            }
+            else if (event === 'segment' && typeof data.text === 'string' && data.text.trim() !== '' && stream.onSegment) {
+                deliver(() => stream.onSegment({ conversationId: named, text: data.text }));
+            }
+            else if (event === 'venue_availability' && stream.onAvailability && str(data.conversation_id) && Array.isArray(data.items)) {
+                const items = data.items.filter(isRecord).flatMap((i) => {
+                    const id = str(i.id);
+                    const availability = availabilityOf(i);
+                    return id && availability ? [{ id, availability }] : [];
+                });
+                if (items.length)
+                    deliver(() => stream.onAvailability({ conversationId: data.conversation_id, items }));
+            }
+            else if (event === 'cart' && stream.onCart && str(data.conversation_id)) {
+                const update = { conversationId: data.conversation_id, cart: cartOf(data.cart), carts: cartsOf(data.carts) };
+                deliver(() => stream.onCart(update));
             }
         });
     }
     catch (error) {
         failure = error;
     }
-    await Promise.all(delivering);
+    await delivering;
     const answered = envelope;
     if (answered) {
         const { http_status: httpStatus, ...body } = answered;
@@ -439,6 +566,7 @@ export class AgentcardClient {
     /** Each shopper's messages that no history the model ran with holds yet, under your own id for them. */
     inbox = new Map();
     deliveredIds = new Set();
+    trace;
     constructor(options) {
         const o = (options ?? {});
         const hasCredentials = o.clientId !== undefined || o.clientSecret !== undefined;
@@ -457,6 +585,7 @@ export class AgentcardClient {
         this.baseUrl = (str(o.baseUrl) ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.credentials = hasCredentials ? { clientId: o.clientId, clientSecret: o.clientSecret } : null;
         this.shopperToken = hasCredentials ? null : o.accessToken;
+        this.trace = isRecord(o.trace) ? o.trace : {};
     }
     /** True when the client buys for many shoppers with a company's credentials; false under one shopper's own token. */
     get company() {
@@ -491,10 +620,39 @@ export class AgentcardClient {
         if (!isRecord(body))
             throw new TypeError('Pass the purchase request as an object, such as { ask: "two AA battery packs" }.');
         this.checkShopper({ externalUserId: body.external_user_id, userId: body.user_id });
-        const streamed = !!stream && (typeof stream.onProgress === 'function' || typeof stream.onCatalog === 'function');
-        // A streamed turn keeps the soft budget a JSON turn has, so it answers within BUY_TURN_TIMEOUT_MS too.
-        const path = streamed ? '/buy?stream=1&soft_timeout=1' : '/buy';
-        return turnOf(await this.call('POST', path, body, BUY_TURN_TIMEOUT_MS, streamed ? stream : undefined));
+        const streamed = !!stream && STREAM_HANDLERS.some((name) => typeof stream[name] === 'function');
+        // A streamed turn keeps the soft budget a JSON turn has, so it answers within BUY_TURN_TIMEOUT_MS too. The pieces of
+        // each message go out only to a caller that asks for them.
+        const path = !streamed ? '/buy' : typeof stream.onDelta === 'function' ? '/buy?stream=deltas&soft_timeout=1' : '/buy?stream=1&soft_timeout=1';
+        const otel = this.trace.otel === false ? null : this.trace.otel ?? await loadOtel();
+        const run = async () => {
+            const headers = traceHeaders(otel, this.trace.traceContext);
+            return turnOf(await this.call('POST', path, body, BUY_TURN_TIMEOUT_MS, streamed ? stream : undefined, headers));
+        };
+        if (!otel)
+            return run();
+        // One `sdk.buy` span per call, a client span (kind 2) the backend's `buy.request` hangs under. It names the
+        // conversation and how the call ended, never what the shopper said.
+        const attributes = { 'agentcard.streamed': streamed };
+        const conversationId = str(body.conversation_id);
+        if (conversationId)
+            attributes['agentcard.conversation_id'] = conversationId;
+        return otel.trace.getTracer('commerce-sdk').startActiveSpan('sdk.buy', { kind: 2, attributes }, async (span) => {
+            try {
+                const turn = await run();
+                if (turn.conversation_id)
+                    span.setAttribute('agentcard.conversation_id', turn.conversation_id);
+                span.setAttribute('agentcard.buy_status', turn.status);
+                return turn;
+            }
+            catch (error) {
+                span.setStatus({ code: 2, message: error instanceof AgentcardApiError ? error.code : 'error' });
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
     async conversation(conversationId, who = {}) {
@@ -618,10 +776,10 @@ export class AgentcardClient {
             throw new TypeError('Name the shopper once: externalUserId, your own id for them, or userId, the Agentcard user id.');
         }
     }
-    async call(method, path, body, timeoutMs, stream) {
+    async call(method, path, body, timeoutMs, stream, extra = {}) {
         let token = await this.bearer();
         for (let attempt = 0;; attempt++) {
-            const answer = await this.send(method, path, token, body, timeoutMs, stream);
+            const answer = await this.send(method, path, token, body, timeoutMs, stream, extra);
             if (answer.status === 401 && attempt === 0 && this.credentials) {
                 token = await this.renewAfter(token);
                 continue;
@@ -639,12 +797,13 @@ export class AgentcardClient {
             throw errorOf(answer.status, answer.body);
         }
     }
-    async send(method, path, token, body, timeoutMs, stream) {
+    async send(method, path, token, body, timeoutMs, stream, extra = {}) {
         let res;
         try {
             res = await this.fetchFn(`${this.baseUrl}${path}`, {
                 method,
                 headers: {
+                    ...extra,
                     authorization: `Bearer ${token}`,
                     accept: stream ? 'text/event-stream, application/json' : 'application/json',
                     ...(body !== undefined ? { 'content-type': 'application/json' } : {}),

package/dist/definition.js

@@ -13,6 +13,7 @@ export const BUY_TOOL_DESCRIPTION = [
     'When the shopper sends a link to a product, such as a buy.trychannel3.com link, put the whole link in `ask` exactly as they sent it, query string included, with their words beside it: Agentcard buys that exact product from the link, so never describe the link in words instead.',
     'Tell the shopper what `reply` says, in your own voice, except the products and stores it lists that reach the shopper as cards.',
     "When `shopper_already_told_looking` is true, the shopper already knows you are working on their request, from a reply or a 👀 on their message, so never acknowledge it again: open with the answer or the question.",
+    'When `shopper_already_read_reply` is true, the shopper already read `reply` as Agentcard wrote it, so never say it again in any words: answer with only what `reply` leaves out, in one short line, or with nothing.',
     'Show the shopper the cart before you confirm it.',
     'When `cart_building` is set, the store is still building that cart: tell the shopper in one short line that its total is on its way, never ask them to confirm it, and confirm it only after they say yes to the total in the message Agentcard sends next.',
     'Ask the shopper for exactly one thing per message: the step `next_action` names, even when `reply` lists more. Never mention a later step, and never ask for the next one until the shopper has done this one.',

package/dist/direct.d.ts

@@ -0,0 +1,50 @@
+import type { BuyNextAction } from './client.js';
+import type { BuyToolInput } from './definition.js';
+/** Why a message goes straight to Agentcard. */
+export type DirectReason = 'product_ask' | 'pick' | 'answer' | 'confirm';
+/** The buy call for a message that goes straight to Agentcard, and why it does. */
+export interface DirectCall {
+    input: BuyToolInput;
+    reason: DirectReason;
+}
+/** What Agentcard last told the shopper, which decides whether a pick or an answer goes straight. */
+export interface DirectContext {
+    /**
+     * True when the shopper's last turn ended on an answer from Agentcard: its last call returned, and
+     * no turn since ran without one. False or left out, only a request to buy goes straight.
+     */
+    answered?: boolean;
+    /** The step Agentcard's last answer asked for, its `next_action`. */
+    nextAction?: BuyNextAction | null;
+    /** Agentcard's last reply, the question a short answer answers. */
+    asked?: string | null;
+    /** The products Agentcard's last answer showed, in order, with the `product_id` a pick sends. */
+    products?: ReadonlyArray<{
+        productId: string | null;
+        name: string;
+    }>;
+    /** The stores Agentcard's last answer showed, with the `store_id` a pick sends. */
+    stores?: ReadonlyArray<{
+        storeId: string;
+        name: string;
+    }>;
+}
+/**
+ * True when the message asks to buy or book something, read with no context: a shopping verb with what
+ * to get, a product link, a product at a named store, or a table. A question, small talk, a pick or an
+ * answer, a command to the cart, the shopper's own details and anything about the account read false.
+ */
+export declare function isProductAsk(text: string): boolean;
+/**
+ * The call a shopper's message makes straight to Agentcard, with no model deciding it, or null when
+ * your model decides: see the top of this file for what goes straight. `ask` carries the shopper's
+ * words as they sent them, a confirm goes in only for a plain yes to the total Agentcard asked them to
+ * confirm, and a pick names its `product_id` or `store_id` only when the message names one exactly.
+ *
+ * ```ts
+ * directCall('find me usb-c cables under $20'); // { input: { ask: 'find me usb-c cables under $20', confirm: false, ... }, reason: 'product_ask' }
+ * directCall('what time is it'); // null
+ * directCall('yes', { answered: true, nextAction: 'confirm' }); // { input: { ask: 'yes', confirm: true, ... }, reason: 'confirm' }
+ * ```
+ */
+export declare function directCall(shopperText: string, context?: DirectContext): DirectCall | null;