@agent-cards/commerce-sdk 0.5.0 → 0.8.0

package/dist/buy-tool.js

@@ -24,9 +24,9 @@
  */
 import { AgentcardApiError, AgentcardClient, } from './client.js';
 import { buyToolDefinition, buyToolStandardSchema, openAIBuyTool, parseBuyToolInput, } from './definition.js';
-import { forModel, forModelError, money, shownProducts } from './model-view.js';
+import { forModel, forModelError, money, pickId, shownProducts } from './model-view.js';
 import { toMessages } from './messages.js';
-import { ackAt, isNewRequest, nextTemplate } from './ack.js';
+import { ackAt, instantAck as instantAckOf, isNewRequest, nextTemplate } from './ack.js';
 /** The pause before the one read that follows a placement Agentcard is still finishing. */
 const PLACEMENT_WAIT_MS = 12_000;
 /** After a turn that outlived Agentcard's budget: one read every 5 seconds, for at most a minute. */
@@ -46,6 +46,8 @@ const AFTER_PLACEMENT = new Set(['nothing_to_confirm', 'conversation_closed', 't
 const ACK_DELAY_MS = 1_500;
 /** A call that starts this soon after the last one ended belongs to the same model turn, which gets one instant reply. */
 const SAME_TURN_MS = 15_000;
+/** How long after `instantAck` the model's first call still belongs to the turn it acknowledged. */
+const APP_TURN_MS = 120_000;
 const STILL_WORKING = "Agentcard is still working on the shopper's last request. Call this tool again in a moment.";
 const CARD_NEEDED = 'The shopper adds a card from a Vault link before Agentcard can buy for them.';
 const STILL_PLACING = 'The shopper approved, and the order is still going through.';
@@ -73,7 +75,11 @@ function hashesOf(cart, carts) {
     return [...new Set([cart?.hash, ...carts.map((c) => c.hash)].filter((h) => typeof h === 'string' && h !== ''))];
 }
 function productsOf(turn) {
-    return (turn.catalog?.items ?? [])
+    return turn.catalog ? productsOfCatalog(turn.catalog) : [];
+}
+/** The products of a search, as the tool reads them. */
+function productsOfCatalog(catalog) {
+    return (catalog.items ?? [])
         .filter((item) => item.name)
         .map((item) => ({
         id: item.id,
@@ -83,7 +89,7 @@ function productsOf(turn) {
         currency: item.currency,
         imageUrl: item.image_url,
         ...(item.flight ? { flight: item.flight } : {}),
-        store: item.store?.name ?? item.store?.id ?? turn.catalog?.merchant_name ?? null,
+        store: item.store?.name ?? item.store?.id ?? catalog.merchant_name ?? null,
         url: item.url ?? null,
         linkSent: false,
     }));
@@ -318,6 +324,19 @@ export function buyTool(options) {
         throw new TypeError('Pass sendLink as a function that delivers a link to the shopper.');
     }
     const sendLink = o.sendLink;
+    if (o.onProgress !== undefined && typeof o.onProgress !== 'function')
+        throw new TypeError('Pass onProgress as a function that takes each stage of a call.');
+    if (o.stream !== undefined && o.stream !== false)
+        throw new TypeError('Pass stream as false to wait for each whole answer, or leave it out.');
+    const onProgress = o.onProgress;
+    if (o.earlyCards !== undefined && typeof o.earlyCards !== 'boolean')
+        throw new TypeError('Pass earlyCards as true or false.');
+    const earlyCards = o.earlyCards === true && !!o.sendLink;
+    const streams = o.stream !== false && (earlyCards || !!onProgress);
+    if (o.onResult !== undefined && typeof o.onResult !== 'function') {
+        throw new TypeError('Pass onResult as a function that takes each answer.');
+    }
+    const onResult = o.onResult;
     const wait = o.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     if (typeof wait !== 'function')
         throw new TypeError('Pass wait as a function of milliseconds that resolves after the pause.');
@@ -336,8 +355,29 @@ export function buyTool(options) {
     let lastEndedAt = Number.NEGATIVE_INFINITY;
     let turnAcked = false;
     let lastTemplate = -1;
+    /** Counts the model's turns: the calls of one turn share its number. */
+    let modelTurn = 0;
     /** This turn's instant reply while it is being sent: every call of the turn waits for it before it hands over a link. */
     let ackOut = null;
+    /** True once `onWorking` delivered this turn's instant reply, so the model is told not to acknowledge again. */
+    let ackDelivered = false;
+    /**
+     * The app's instant reply for the shopper's newest message, waiting for the model's first call on that
+     * message, and the step the last answer asked the shopper for. A call still running for an earlier
+     * message keeps its own turn's state.
+     */
+    let appAck = null;
+    let lastNextAction = null;
+    /** The app's own instant reply: the turn its message opens sends no `onWorking` reply. */
+    const instantAck = (shopperText) => {
+        const text = String(shopperText ?? '');
+        const said = instantAckOf(text, { nextAction: lastNextAction }) !== null;
+        // The same rotation onWorking uses, so the next reply comes from another template.
+        if (said)
+            lastTemplate = nextTemplate(lastTemplate);
+        appAck = { at: Date.now(), said };
+        return said ? ackAt(lastTemplate, text) : null;
+    };
     /**
      * Holds the instant reply for a new request until `ackDelayMs` passes. `cancel` stops one that has
      * not gone out, and frees the turn's reply for a later call.
@@ -367,7 +407,9 @@ export function buyTool(options) {
                 return;
             }
             const message = text.trim();
-            ackOut = Promise.resolve().then(() => onWorking(message)).catch(() => { });
+            ackOut = Promise.resolve()
+                .then(() => onWorking(message))
+                .then(() => { ackDelivered = true; }, () => { });
         }, ackDelayMs);
         return {
             cancel: () => {
@@ -594,15 +636,21 @@ export function buyTool(options) {
         // A running turn that placed nothing may be a search rather than a placement, so the shopper hears it is still working.
         return settled.status === 'placing' && !placing ? refused : settled;
     };
-    /** The store pages this tool sent last, with their conversation. */
+    /** The store pages this tool sent last, with their conversation, the model turn that sent them, and the search they list. */
     let lastPages = null;
     /**
      * The store page of each product the model reads, sent once per page. A
      * page the last batch in this conversation already sent stays with the
-     * shopper and goes out no second time. A page whose `sendLink` throws
+     * shopper and goes out no second time, unless a later model turn's reply
+     * presents the products again (the catalog's `presented`): a repeated ask
+     * answered with the same products gets their pages beside it, so every
+     * product the reply names has a card. Calls of one model turn still send a
+     * page once. An answer that lists fewer of the same search's products, such
+     * as a pick's, keeps the pages that search already sent, so a later answer
+     * that lists them again sends none twice. A page whose `sendLink` throws
      * stays unsent, and the call goes on, so the next answer tries it again.
      */
-    const deliverPages = async (result) => {
+    const deliverPages = async (result, call) => {
         if (!sendLink)
             return result;
         const pages = new Map();
@@ -613,12 +661,21 @@ export function buyTool(options) {
         // An answer with no store page leaves the last batch as it was.
         if (pages.size === 0)
             return result;
-        const before = lastPages?.conversationId === result.conversation_id ? lastPages.urls : new Set();
-        const held = new Set();
+        const kept = lastPages?.conversationId === result.conversation_id && (!call.presented || lastPages.turn === call.turn);
+        const before = kept && lastPages ? lastPages.urls : new Set();
+        // Agentcard names the search an answer lists by when it ran. An answer that lists fewer of the same
+        // search's products, such as a pick's, keeps every page that search already sent, so a later answer
+        // that lists them again sends none twice.
+        const catalog = result.envelope?.catalog;
+        const search = typeof catalog?.as_of === 'string' ? catalog.as_of : null;
+        const sameSearch = kept && search !== null && lastPages?.search === search;
+        const held = new Set(sameSearch ? before : []);
         for (const [url, product] of pages) {
             if (!before.has(url)) {
                 try {
-                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), productId: product.id, imageUrl: product.imageUrl, expiresAt: null });
+                    // The id the model reads and a pick takes, never the store page: the page is `url`.
+                    const productId = pickId(product);
+                    await sendLink({ kind: 'product', url, title: product.name, price: money(product.priceCents, product.currency), ...(productId ? { productId } : {}), imageUrl: product.imageUrl, expiresAt: null });
                 }
                 catch {
                     continue;
@@ -626,25 +683,27 @@ export function buyTool(options) {
             }
             held.add(url);
         }
-        lastPages = { conversationId: result.conversation_id, urls: held };
+        lastPages = { conversationId: result.conversation_id, turn: call.turn, search, urls: held };
         return { ...result, products: result.products.map((product) => (product.url && held.has(product.url) ? { ...product, linkSent: true } : product)) };
     };
+    /** The products a streamed search found, as an answer the page delivery reads: its conversation, its search and its products. */
+    const earlyPages = (conversationId, asOf, products) => ({ conversation_id: conversationId, envelope: { catalog: { as_of: asOf } }, products });
     /** One batch of pages at a time: a call that overlaps another reads the pages that one sent. */
     let pagesInTurn = Promise.resolve();
-    const deliverPagesInTurn = (result) => {
-        const batch = pagesInTurn.then(() => deliverPages(result));
+    const deliverPagesInTurn = (result, call) => {
+        const batch = pagesInTurn.then(() => deliverPages(result, call));
         pagesInTurn = batch.catch(() => { });
         return batch;
     };
     /** The Vault or approval link first, because the purchase waits on it, then the store pages. */
-    const deliver = async (result) => {
+    const deliver = async (result, call) => {
         let delivered = result;
         if (result.links.length > 0 && sendLink) {
             for (const link of result.links)
                 await sendLink({ ...link });
             delivered = { ...result, link_sent: true };
         }
-        return deliverPagesInTurn(delivered);
+        return deliverPagesInTurn(delivered, call);
     };
     const answer = async (raw) => {
         const startedAt = Date.now();
@@ -664,19 +723,52 @@ export function buyTool(options) {
             ...(o.deliveryAddress ? { delivery_address: o.deliveryAddress } : {}),
             ...(client.company ? { external_user_id: externalUserId } : {}),
         };
-        // A call that starts while another runs, or right after one ended, is the model working through the same turn.
-        if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
+        // The first call after `instantAck` opens the turn of the message it answered, whose reply is the
+        // app's. Any other call that starts while another runs, or right after one ended, is the model
+        // working through the same turn.
+        const opened = appAck && Date.now() - appAck.at < APP_TURN_MS ? appAck : null;
+        appAck = null;
+        if (opened) {
+            turnAcked = true;
+            ackOut = null;
+            ackDelivered = opened.said;
+            modelTurn += 1;
+        }
+        else if (running === 0 && Date.now() - lastEndedAt >= SAME_TURN_MS) {
             turnAcked = false;
             ackOut = null;
+            ackDelivered = false;
+            modelTurn += 1;
         }
+        const callTurn = modelTurn;
         running += 1;
         // A pick adds a product the shopper already saw, so no "looking for" reply goes out, as for "the first one".
         const ack = confirm || pick ? null : holdAck(ask);
         try {
             let turn = null;
             let refusal;
+            // Streamed: the stages go to onProgress, and a search's store pages go out the moment it answers.
+            const handlers = streams
+                ? {
+                    ...(onProgress ? { onProgress: (progress) => { try {
+                            onProgress(progress);
+                        }
+                        catch { /* the app's display failing never fails the call */ } } } : {}),
+                    ...(earlyCards && sendLink && !confirm
+                        ? {
+                            onCatalog: async (update) => {
+                                // Products arrived before the instant reply was due: they are the reply.
+                                ack?.cancel();
+                                await ackOut;
+                                // The turn's own search presents its products, as a reply that lists them does.
+                                await deliverPagesInTurn(earlyPages(update.conversationId, update.asOf, productsOfCatalog(update.catalog)), { turn: callTurn, presented: true });
+                            },
+                        }
+                        : {}),
+                }
+                : undefined;
             try {
-                turn = await client.buy(body);
+                turn = await client.buy(body, handlers);
             }
             catch (error) {
                 refusal = error;
@@ -684,7 +776,18 @@ export function buyTool(options) {
             ack?.cancel();
             const settled = turn ? await settleTurn(turn, startedAt) : await settleRefusal(refusal, confirm, startedAt);
             await ackOut;
-            return await deliver(withMessages(settled, turn));
+            const delivered = await deliver(withMessages(settled, turn), { turn: callTurn, presented: turn?.catalog?.presented === true });
+            const result = ackDelivered ? { ...delivered, shopper_already_told_looking: true } : delivered;
+            lastNextAction = result.next_action;
+            if (onResult) {
+                try {
+                    await onResult(result);
+                }
+                catch {
+                    // The app's display failing never fails the purchase call.
+                }
+            }
+            return result;
         }
         finally {
             ack?.cancel();
@@ -711,7 +814,7 @@ export function buyTool(options) {
         }
     };
     const { name, description, input_schema } = buyToolDefinition();
-    const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer, forModel };
+    const tool = { name, description, input_schema, strict: true, parse, run: handle, execute: handle, handle, answer, forModel, instantAck };
     // JSON skips these three, so a runner that sends the tool to its API as is sends Anthropic's fields and nothing else.
     const unsent = (value) => ({ value, enumerable: false, writable: true, configurable: true });
     return Object.defineProperties(tool, {

package/dist/client.d.ts

@@ -1,14 +1,55 @@
+import { type AgentcardListener, type ListenOptions } from './listen.js';
 /** The fetch the client calls: Node 18 and later have one built in. */
 export type FetchLike = (url: string, init: {
     method: string;
     headers: Record<string, string>;
     body?: string;
     signal?: AbortSignal;
-}) => Promise<{
+}) => Promise<FetchLikeResponse>;
+/**
+ * The answer a fetch returns, as far as the client reads it. `headers` and `body` are optional: a
+ * fetch without them is read whole with `text()`, and a streamed purchase answer still arrives, at its end.
+ */
+export interface FetchLikeResponse {
     status: number;
     ok: boolean;
     text(): Promise<string>;
-}>;
+    headers?: {
+        get(name: string): string | null;
+    } | null;
+    body?: {
+        getReader(): {
+            read(): Promise<{
+                done: boolean;
+                value?: Uint8Array;
+            }>;
+            cancel?(): Promise<void>;
+        };
+    } | null;
+}
+/**
+ * What the purchase turn is doing while it runs: `searching` the stores, `building_cart`, `checking_out`,
+ * or `working` on anything else. Agentcard names only the stage, never what the shopper said.
+ */
+export type BuyProgressStage = 'searching' | 'building_cart' | 'checking_out' | 'working';
+/** One step of a running purchase turn. */
+export interface BuyProgress {
+    stage: BuyProgressStage;
+    conversationId: string | null;
+}
+/** The products a running turn's search found, sent the moment the search answers and before the reply is written. */
+export interface BuyCatalogUpdate {
+    conversationId: string;
+    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;
+}
+/** Called while a purchase turn runs. Passing either one asks Agentcard to stream the turn. */
+export interface BuyStreamHandlers {
+    onProgress?: (progress: BuyProgress) => void;
+    /** The client waits for what this returns before it hands back the turn's answer. */
+    onCatalog?: (update: BuyCatalogUpdate) => 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;
@@ -119,11 +160,16 @@ export interface BuyCatalogItem {
     /** The product's page at its store, as an http or https address, or null when Agentcard sent none. */
     url: string | null;
 }
-/** The products the last search found. */
+/**
+ * The products the last search found. `presented` is true when this answer's reply presents them: the
+ * turn searched, or answered a repeated ask from the results it already held. False when they only
+ * stand from an earlier answer, and on an older API.
+ */
 export interface BuyCatalog {
     merchant: string;
     merchant_name: string;
     items: BuyCatalogItem[];
+    presented: boolean;
 }
 /** The product a `pick` named, by its catalog id and ref, and whether the cart now holds it. */
 export interface BuyPick {
@@ -260,15 +306,18 @@ export declare class AgentcardClient {
     get company(): boolean;
     /** True for a sandbox client, as the token exchange said; null until the first exchange, and under a shopper's token. */
     get sandbox(): boolean | null;
-    /** The access token the client sends: the shopper's own, or the company's, exchanged once and renewed a minute before it expires. */
-    bearer(): Promise<string>;
+    /**
+     * The access token the client sends: the shopper's own, or the company's, exchanged once and
+     * renewed a minute before it expires. Pass a company token Agentcard refused to get a new one.
+     */
+    bearer(refused?: string): Promise<string>;
     /**
      * One purchase turn, sent once with a 130-second wait. A turn is a model run
      * against live stores, so a lost answer is never sent again: read the
      * conversation instead. Only a 401 is sent again, once, with a fresh token,
      * because Agentcard refused it before anything ran.
      */
-    buy(body: BuyRequest): Promise<BuyTurn>;
+    buy(body: BuyRequest, stream?: BuyStreamHandlers): Promise<BuyTurn>;
     /** One read of a conversation: whether a turn is running, the last checkout, the orders it placed, the carts on the table. */
     conversation(conversationId: string, who?: Shopper): Promise<BuyConversation>;
     /**
@@ -279,6 +328,11 @@ export declare class AgentcardClient {
     mintVaultLink(input: {
         externalUserId: string;
     }): Promise<VaultLink>;
+    /**
+     * Hear every event Agentcard sends your company over one connection your server opens, with no
+     * webhook endpoint: `listenToAgentcard(this, opts)`. Takes your company credentials.
+     */
+    listen(opts: ListenOptions): AgentcardListener;
     /** A company names the shopper exactly once; a shopper's own token already names them. */
     private checkShopper;
     private call;

package/dist/client.js

@@ -9,6 +9,8 @@
  * token cache follows its client (packages/checkout/src/client.ts accessToken).
  */
 import { isRecord } from './verify.js';
+import { listenToAgentcard } from './listen.js';
+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. */
 export const BUY_TURN_TIMEOUT_MS = 130_000;
@@ -128,7 +130,7 @@ function catalogOf(v) {
             url: pageUrl(i.url),
         };
     }) : [];
-    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items };
+    return { merchant: str(v.merchant) ?? '', merchant_name: str(v.merchant_name) ?? str(v.merchant) ?? '', items, presented: v.presented === true };
 }
 function paymentSourceOf(v) {
     return isRecord(v) && str(v.source) ? { source: v.source, brand: str(v.brand), last4: str(v.last4) } : null;
@@ -255,6 +257,106 @@ function parseJson(text) {
         return null;
     }
 }
+/** Each event of a server-sent stream, in order, read as it arrives, or from the whole text when the fetch hands no stream. */
+async function eachEvent(res, onEvent) {
+    let buffer = '';
+    // True once onEvent says the stream is over.
+    let over = false;
+    const drain = (final) => {
+        buffer = buffer.replace(/\r\n?/g, '\n');
+        for (let end = buffer.indexOf('\n\n'); end >= 0 || (final && buffer.trim() !== ''); end = buffer.indexOf('\n\n')) {
+            const block = end >= 0 ? buffer.slice(0, end) : buffer;
+            buffer = end >= 0 ? buffer.slice(end + 2) : '';
+            let event = 'message';
+            const data = [];
+            for (const line of block.split('\n')) {
+                if (line.startsWith('event:'))
+                    event = line.slice(6).trim();
+                else if (line.startsWith('data:'))
+                    data.push(line.slice(5).replace(/^ /, ''));
+            }
+            if (data.length > 0 && onEvent(event, data.join('\n')) === true) {
+                over = true;
+                return;
+            }
+        }
+    };
+    const reader = res.body?.getReader?.();
+    if (!reader) {
+        buffer = await res.text();
+        drain(true);
+        return;
+    }
+    const decoder = new TextDecoder();
+    try {
+        while (!over) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            buffer += decoder.decode(chunk.value, { stream: true });
+            drain(false);
+        }
+        if (!over)
+            drain(true);
+    }
+    finally {
+        if (over)
+            reader.cancel?.().catch(() => { });
+    }
+}
+/**
+ * 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
+ * (`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 = [];
+    let failure = null;
+    try {
+        await eachEvent(res, (event, text) => {
+            const data = parseJson(text);
+            if (!data)
+                return;
+            conversationId = str(data.conversation_id) ?? conversationId;
+            if (event === 'envelope') {
+                envelope = data;
+                return true;
+            }
+            if (event === 'progress' && typeof data.stage === 'string' && PROGRESS_STAGES.has(data.stage) && stream.onProgress) {
+                try {
+                    stream.onProgress({ stage: data.stage, conversationId: str(data.conversation_id) });
+                }
+                catch {
+                    // The app's display failing never fails the turn.
+                }
+            }
+            else if (event === 'catalog' && stream.onCatalog && 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(() => { }));
+            }
+        });
+    }
+    catch (error) {
+        failure = error;
+    }
+    await Promise.all(delivering);
+    const answered = envelope;
+    if (answered) {
+        const { http_status: httpStatus, ...body } = answered;
+        const status = typeof httpStatus === 'number' ? httpStatus : res.status;
+        return { status, ok: status >= 200 && status < 300, readable: true, body };
+    }
+    if (conversationId) {
+        return { status: 200, ok: true, readable: true, body: { conversation_id: conversationId, status: 'needs_input', reply: '', error_code: 'turn_timeout' } };
+    }
+    throw failure ? failureOf(failure, timeoutMs) : new AgentcardApiError(0, 'unreachable', 'Agentcard closed the purchase answer before it ended.');
+}
 /** The client every shopper's buy tool shares. Build one per set of credentials and keep it. */
 export class AgentcardClient {
     baseUrl;
@@ -291,10 +393,15 @@ export class AgentcardClient {
     get sandbox() {
         return this.learnedSandbox;
     }
-    /** The access token the client sends: the shopper's own, or the company's, exchanged once and renewed a minute before it expires. */
-    async bearer() {
+    /**
+     * The access token the client sends: the shopper's own, or the company's, exchanged once and
+     * renewed a minute before it expires. Pass a company token Agentcard refused to get a new one.
+     */
+    async bearer(refused) {
         if (this.shopperToken !== null)
             return this.shopperToken;
+        if (refused !== undefined)
+            return this.renewAfter(refused);
         if (this.token && Date.now() < this.token.expiresAt)
             return this.token.value;
         if (!this.inflight)
@@ -307,11 +414,14 @@ export class AgentcardClient {
      * conversation instead. Only a 401 is sent again, once, with a fresh token,
      * because Agentcard refused it before anything ran.
      */
-    async buy(body) {
+    async buy(body, stream) {
         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 });
-        return turnOf(await this.call('POST', '/buy', body, BUY_TURN_TIMEOUT_MS));
+        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));
     }
     /** 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 = {}) {
@@ -339,6 +449,13 @@ export class AgentcardClient {
             throw new AgentcardApiError(200, 'invalid_answer', 'Agentcard answered the Vault link request without a link.', answer);
         return { id: str(answer.id) ?? '', url, expiresAt: str(answer.expires_at), reused: answer.reused === true };
     }
+    /**
+     * Hear every event Agentcard sends your company over one connection your server opens, with no
+     * webhook endpoint: `listenToAgentcard(this, opts)`. Takes your company credentials.
+     */
+    listen(opts) {
+        return listenToAgentcard(this, opts);
+    }
     /** A company names the shopper exactly once; a shopper's own token already names them. */
     checkShopper(who) {
         const named = [who.externalUserId, who.userId].filter((v) => v !== undefined);
@@ -351,10 +468,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) {
+    async call(method, path, body, timeoutMs, stream) {
         let token = await this.bearer();
         for (let attempt = 0;; attempt++) {
-            const answer = await this.send(method, path, token, body, timeoutMs);
+            const answer = await this.send(method, path, token, body, timeoutMs, stream);
             if (answer.status === 401 && attempt === 0 && this.credentials) {
                 token = await this.renewAfter(token);
                 continue;
@@ -372,24 +489,39 @@ export class AgentcardClient {
             throw errorOf(answer.status, answer.body);
         }
     }
-    async send(method, path, token, body, timeoutMs) {
+    async send(method, path, token, body, timeoutMs, stream) {
+        let res;
         try {
-            const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+            res = await this.fetchFn(`${this.baseUrl}${path}`, {
                 method,
                 headers: {
                     authorization: `Bearer ${token}`,
-                    accept: 'application/json',
+                    accept: stream ? 'text/event-stream, application/json' : 'application/json',
                     ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
                 },
                 ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
                 signal: AbortSignal.timeout(timeoutMs),
             });
-            const parsed = parseJson(await res.text());
-            return { status: res.status, ok: res.ok, readable: parsed !== null, body: parsed ?? {} };
         }
         catch (error) {
             throw failureOf(error, timeoutMs);
         }
+        // Agentcard streams only once the turn starts: a refusal before it is plain JSON.
+        if (stream && /text\/event-stream/i.test(res.headers?.get?.('content-type') ?? ''))
+            return readStreamedTurn(res, stream, timeoutMs);
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (error) {
+            throw failureOf(error, timeoutMs);
+        }
+        const parsed = parseJson(text);
+        // A fetch that hands no headers still carries a streamed answer in its text: read it whole.
+        if (stream && parsed === null && /^(?:event|data):/m.test(text)) {
+            return readStreamedTurn({ status: res.status, ok: res.ok, text: async () => text }, stream, timeoutMs);
+        }
+        return { status: res.status, ok: res.ok, readable: parsed !== null, body: parsed ?? {} };
     }
     /** After a 401: the token another call already renewed, or one new exchange, however many calls were refused at once. */
     async renewAfter(refused) {

package/dist/definition.js

@@ -11,6 +11,7 @@ export const BUY_TOOL_DESCRIPTION = [
     'Buy what this shopper asks for at real stores.',
     "Put the shopper's own words in `ask`.",
     'Tell the shopper what `reply` says, in your own voice.',
+    "When `shopper_already_told_looking` is true, the shopper was already told you are working on their request, so never acknowledge it again: open with the answer or the question.",
     'Show the shopper the cart before you confirm it.',
     '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.',
     'Set `confirm` to true only when the shopper just said yes to the cart in your last result, says they added the card for a cart that waits, says they approved, or asks for the approval link again.',

package/dist/events.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every event type Agentcard sends a company, the same list a webhook endpoint subscribes to by
+ * name. The stream (`agentcard.listen`) and a webhook endpoint carry the same types, with the same
+ * envelope and the same ids. A test holds this list to the backend's catalog.
+ */
+export declare const AGENTCARD_EVENT_TYPES: readonly ["card.created", "card.updated", "card.closed", "cardholder.created", "cardholder.updated", "transaction.authorized", "transaction.declined", "transaction.cleared", "transaction.voided", "balance.low", "cardholder_onboarding_session.completed", "platform_connect_session.completed", "merchant.connected", "order.placed", "order.confirmed", "order.failed", "order.updated", "purchase.message", "connection.created", "connected_card.updated", "vault.card_stored", "vault.session_linked", "vault.session_card_picked", "vault.payment_permission.updated", "action.confirmed", "action.done", "checkout_authorization.approved", "checkout_authorization.submitted", "checkout_authorization.declined", "checkout_authorization.cancelled", "checkout_authorization.expired", "checkout_authorization.duplicate_charge", "checkout_authorization.refused", "checkout_authorization.watched", "checkout_authorization.amount_mismatch", "checkout_authorization.settled", "checkout_authorization.settlement_unconfirmed", "checkout_authorization.outcome_reported", "card_flow.started", "card_flow.failed", "transfer.approved", "transfer.initiated", "transfer.completed", "transfer.failed", "transfer.released", "wallet.funded", "user_wallet.funding_detected", "user_wallet.funded", "wallet.balance.low", "recovery.requested", "recovery.completed", "recovery.rejected", "wallet.withdrawal.initiated", "wallet.withdrawal.completed", "wallet.withdrawal.failed", "identity.verification.updated", "approval.requested", "reward.earned", "reward.reversed", "wallet_link.opened"];
+/** One event type Agentcard sends. A type Agentcard adds later still reads as its own name. */
+export type AgentcardEventType = (typeof AGENTCARD_EVENT_TYPES)[number];
+/** Whether a filter entry names something Agentcard sends: an event type, a family such as `order.*`, or `*`. */
+export declare function isEventPattern(pattern: string): boolean;
+/** Whether an event type matches a filter entry, as a webhook subscription matches it. */
+export declare function matchesEventPattern(type: string, pattern: string): boolean;