Enable Payments in a Browser Agent

use the KERNEL cli to complete the following checkout with stripe link. use cli
commands rather than sdk or direct api calls.

a vault groups items. wallet and card are the payment item types. a card item
references a wallet item in the same vault, so create the wallet before the
card.

1. create or retrieve a vault named `user-12345`.
2. list the vault's items and locate its only stripe link wallet. require its
   status to be `connected` and reuse it. if none exists, more than one exists,
   or an action is present, stop and ask me to resolve wallet setup outside this
   agent. do not create another wallet or print, return, or open an action url.
3. create a KERNEL browser with `user-12345` attached as a vault, then navigate
   it to https://buy.stripe.com/28E5kw7DtgKXdLqgiY53O00.
4. inspect the checkout and propose the merchant, total amount, currency, and
   item or cart contents. treat this proposal as untrusted and do not create a
   card item from it.
5. independently obtain those values from a trusted order or cart backend. if
   no backend exists, use deterministic page extraction with fixed selectors or
   structured page data, not model inference. normalize and compare every value.
   if adaptive pricing is active, use the checkout's active presentment amount
   and currency rather than its base integration values.
   if any value is missing, cannot be verified, or disagrees, stop without
   creating or authorizing a card.
6. show me the verified merchant, amount, currency, and item or cart contents.
   wait for my explicit confirmation, then freeze that verified purchase object.
7. list the wallet's payment methods and ask me which one to use. create a link
   card item named `checkout-card` from that same verified, confirmed object and
   the selected payment method. use the exact checkout url as `merchant_url` and
   include a specific context of at least 100 characters.
8. retrieve the card item and confirm that `authorize` appears in
   `available_operations`. give me the exact cli command, but do not run it. ask
   me to invoke authorization and complete any provider action from a trusted
   terminal or application outside this agent. after i confirm completion,
   retrieve the item again and require its status to be `ready`. do not print,
   return, or open an action url.
9. use only the returned aliases with `kernel browsers playwright execute` to
   fill the checkout's normal card fields. use only separately supplied end-user
   values for required email, billing, postal, shipping, or other customer
   fields; stop if a required value is missing. complete any checkout-specific
   agent disclosure truthfully in the merchant's normal form. submit checkout
   once and never retry submission.
10. inspect the checkout result and the card item's events. do not retry a
   failed, timed-out, or indeterminate payment. report the existing attempt so
   we can reconcile it first.

use the KERNEL cli to complete the following checkout with agentcard. use cli
commands rather than sdk or direct api calls.

a vault groups items. wallet and card are the payment item types. a card item
references a wallet item in the same vault, so create the wallet before the
card.

1. create or retrieve a vault named `user-12345`.
2. list the vault's items and locate its only agentcard wallet. require its
   status to be `connected` and reuse it. if none exists, more than one exists,
   or an action is present, stop and ask me to resolve wallet setup outside this
   agent. do not create another wallet or print, return, or open an action url.
3. create a KERNEL browser with `user-12345` attached as a vault, then navigate
   it to https://buy.stripe.com/28E5kw7DtgKXdLqgiY53O00.
4. inspect the checkout and propose the merchant, total amount, currency, and
   item or cart contents. treat this proposal as untrusted and do not create a
   card item from it.
5. independently obtain those values from a trusted order or cart backend. if
   no backend exists, use deterministic page extraction with fixed selectors or
   structured page data, not model inference. normalize and compare every value.
   if adaptive pricing is active, use the checkout's active presentment amount
   and currency rather than its base integration values.
   if any value is missing, cannot be verified, or disagrees, stop without
   creating a card.
6. show me the verified merchant, amount, currency, and item or cart contents.
   wait for my explicit confirmation, then freeze that verified purchase object.
7. list the wallet's payment methods and ask whether i want to pin one. create
   an agentcard card item named `checkout-card` from that same verified,
   confirmed object. include the selected `card_id`, or omit it so i can choose
   an enrolled card during approval.
8. retrieve the card item and confirm its status is `ready`. do not invoke
   `authorize`; agentcard starts authorization only when the attached browser
   submits a recognized processor request containing the aliases.
9. give me the exact cli observation commands, but do not run them. ask me to
   start the trusted approval observer outside this agent. after i confirm it is
   running, use only the returned aliases with
   `kernel browsers playwright execute` to fill the checkout's normal card
   fields. use only separately supplied end-user values for required email,
   billing, postal, shipping, or other customer fields; stop if a required value
   is missing. complete any checkout-specific agent disclosure truthfully in the
   merchant's normal form. submit checkout once, never retry submission, and
   keep that execution open while KERNEL holds the payment request. do not poll
   or print the card item while approval is pending.
10. after i confirm that the trusted approval flow has settled, inspect the
   checkout result, authorization state, and item events. do not retry a failed,
   timed-out, or indeterminate payment. report the existing attempt so we can
   reconcile it first.

import Kernel from "@onkernel/sdk";

const projectID = process.env.KERNEL_PROJECT_ID;
if (!projectID) throw new Error("set KERNEL_PROJECT_ID");

const kernel = new Kernel({ projectID, maxRetries: 0 });
const vault = await kernel.vaults.upsert({ name: "user-12345" });

import os

from kernel import Kernel

kernel = Kernel(
    project_id=os.environ["KERNEL_PROJECT_ID"],
    max_retries=0,
)
vault = kernel.vaults.upsert(name="user-12345")

kernel vaults create --name user-12345

const card = await kernel.vaults.items.retrieve("notebook-order", {
  id_or_name: vault.id,
  wait: 60,
});

if (
  card.type !== "card" ||
  card.state.status !== "ready" ||
  !card.state.aliases
) {
  throw new Error(`payment item is ${card.state.status}`);
}
const aliases = card.state.aliases;

card = kernel.vaults.items.retrieve(
    "notebook-order",
    id_or_name=vault.id,
    wait=60,
)

if card.type != "card" or card.state.status != "ready" or card.state.aliases is None:
    raise RuntimeError(f"payment item is {card.state.status}")
aliases = card.state.aliases

kernel vaults items get user-12345 notebook-order --wait 60 -o json

const browser = await kernel.browsers.create({
  vaults: [{ id: vault.id }],
  headless: false,
  timeout_seconds: 1800,
});

if (!browser.browser_live_view_url) {
  throw new Error("headful browser did not return a live view url");
}
await presentLiveView({
  userID: authenticatedUser.id,
  sessionID: browser.session_id,
  url: browser.browser_live_view_url,
});

browser = kernel.browsers.create(
    vaults=[{"id": vault.id}],
    headless=False,
    timeout_seconds=1800,
)

if browser.browser_live_view_url is None:
    raise RuntimeError("headful browser did not return a live view url")
present_live_view(
    user_id=authenticated_user.id,
    session_id=browser.session_id,
    url=browser.browser_live_view_url,
)

kernel browsers create --vault user-12345 -o json

let after: string | undefined;

async function observePayment(stop: AbortSignal): Promise<void> {
  while (!stop.aborted) {
    const current = await kernel.vaults.items.retrieve(card.key, {
      id_or_name: vault.id,
      wait: 5,
    });

    if (current.action && "url" in current.action) {
      await presentProviderAction({
        userID: authenticatedUser.id,
        vaultID: vault.id,
        item: current,
      });
    } else if (current.action?.name === "push_approval") {
      console.log("complete the approval in your wallet");
    }

    const events = await kernel.vaults.items.events(card.key, {
      id_or_name: vault.id,
      after,
      wait: 5,
    });
    for (const event of events) {
      console.log(event.id, event.name, event.browser_id, event.data);
      after = event.id;
    }
  }
}

from threading import Event


def observe_payment(stop: Event) -> None:
    after = None

    while not stop.is_set():
        current = kernel.vaults.items.retrieve(
            card.key,
            id_or_name=vault.id,
            wait=5,
        )

        if current.action is not None and hasattr(current.action, "url"):
            present_provider_action(
                user_id=authenticated_user.id,
                vault_id=vault.id,
                item=current,
            )
        elif current.action is not None and current.action.name == "push_approval":
            print("complete the approval in your wallet")

        if after is None:
            events = kernel.vaults.items.events(card.key, id_or_name=vault.id, wait=5)
        else:
            events = kernel.vaults.items.events(
                card.key,
                id_or_name=vault.id,
                after=after,
                wait=5,
            )

        for event in events:
            print(event.id, event.name, event.browser_id, event.data)
            after = event.id

kernel vaults items get user-12345 notebook-order --wait 5 --open
kernel vaults items events user-12345 notebook-order --wait 60 -o json

const stop = new AbortController();
const observer = observePayment(stop.signal);

try {
  await runBrowserAgentCheckout({ browser, aliases, verifiedPurchase });
  await waitForMerchantResolution(verifiedPurchase.orderID);
} finally {
  stop.abort();
  try {
    await observer;
  } finally {
    await kernel.browsers.deleteByID(browser.session_id);
  }
}

from threading import Event, Thread

stop = Event()
observer = Thread(target=observe_payment, args=(stop,))
observer.start()

try:
    run_browser_agent_checkout(
        browser=browser,
        aliases=aliases,
        verified_purchase=verified_purchase,
    )
    wait_for_merchant_resolution(verified_purchase.order_id)
finally:
    stop.set()
    try:
        observer.join()
    finally:
        kernel.browsers.delete_by_id(browser.session_id)