Taking the next step once the shopper finishes outside the chat

​

Open a turn for the message

import type { BuyToolTurn } from '@agent-cards/commerce-sdk';
import { agentcard, buyFor } from './agentcard';

// Each shopper's model runs go in order, so the chat's own turns wait on them too.
const runs = new Map<string, Promise<void>>();

agentcard.listen({
  onMessage: (shopperId, message) => {
    const step = buyFor(shopperId).nextStep(message);
    if (!step) return postToChat(shopperId, message.text); // nothing to take: post the text as it is

    // Run the model without awaiting, so the listener moves on to the next event.
    // One shopper's runs go in order, so an older run never writes its history over a newer one.
    const run = (runs.get(shopperId) ?? Promise.resolve())
      .then(() => runModel(shopperId, step))
      .catch(async () => {
        // The turn failed: release it so its text reaches later turns, and post the text instead.
        step.release();
        await postToChat(shopperId, message.text);
        agentcard.delivered(shopperId, message); // only once the post went out
      })
      // The fallback post failed as well, so nothing is recorded and a redelivery opens the turn again.
      .catch(() => {});
    runs.set(shopperId, run);
  },
});

async function runModel(shopperId: string, turn: BuyToolTurn) {
  const runner = anthropic.beta.messages.toolRunner({
    model: 'claude-opus-5-5',
    max_tokens: 16000,
    tools: [turn],
    messages: turn.messages(histories.get(shopperId)),
  });
  const answer = await runner;
  histories.set(shopperId, runner.params.messages);
  await postToChat(shopperId, textOf(answer), turn.links);
}

​

Know what the shopper reads next

​

Keep the shopper’s decision theirs

• No call of the turn sends an ask to Agentcard, because Agentcard could read the model’s words as the shopper’s go-ahead. Each call reads where the purchase stands and answers with the next step: the card link the sign-in held back, or the cart and the ask for the shopper’s yes.
• A confirm goes in only for the yes the shopper already gave in the chat, such as “lets place it”, when that confirm stopped for the card or the sign-in they finished. It goes in once, for that cart’s hash, so Agentcard refuses it if the cart changed. A shopper message after the yes that is not a plain go-ahead, such as “wait, make it two”, takes the yes back.
• Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard.
• The approval in the Vault is still the shopper’s. The confirm sends the approval link, and Agentcard places the order only once the shopper approves it.
• A shopper who was not connected yet when they asked gets their own first ask run, in their words, once their card is saved.

​

Handle the cases with no step

• The message’s advances is false, such as order_placed, whose text is already the whole message.
• The message is for another shopper, or its link closed.
• The tool already took a turn for the message.
• The message arrives while a call for the shopper’s own message is still running. That call’s answer tells the model where the purchase stands.

​

Run the listener and the model in one process

​

Check it in the sandbox

1. Send “two packs of AA batteries from Amazon” as a test shopper nobody connected, and open the Vault link.
2. Save a card with the code 111111. Do not type anything in the chat.
3. Check that the chat posts one message that does the next thing, such as the ask for your yes or the approval link, with nothing typed after the card saved.
4. Check that the agent ran your first ask, “two packs of AA batteries from Amazon”, in your words once your card was saved, without you asking again.
5. Make your model throw during runModel. Check that the shopper still reads message.text.