Explain

Who talks to whom

Text to order is a third caller into the same engine.

Counter vs classic POS

For readers comparing to a traditional POS. Counter is an agent-facing store of record, not a skin on OSPOS. Buyer agents never call a classic POS API.

Today: no live link to a classic POS. No item sync, no shared register screen.

Future hook: after Counter pays, optionally push lines and totals into the merchant POS via PosPort.postSale—without marking paid again. Dev stand-in: text to order and the pos_sales fixture.

Flow: buyer agent → Counter (session, policy, pay) → optional post-sale → classic POS as downstream ledger.

Facts (wire level)

Wire-level rules the store already enforces.

• Discovery + every session echo policy (cap, hours, timezone).
• 86 = append event. out_of_stock carries since.
• Over buyer_auto_cap_cents → pending_approval. Complete → 422 until manager.
• Chat: request_comp / request_refund. No decide_approval tool.
• paid_after_86 on board. No auto-refund in v1.
• Close memo: code from SQL. Not LLM.

Demos

Six walks against the live sandbox. Start with oat 86 on the glass.

Plan · on the floor

Scenarios

Thirteen fixtures. The list is the definition of done.

For agents

Fake pay · loc_main · API-Version: 2026-04-17. Paths, headers, MCP, and a curl happy path.

Fake pay boundary

Sandbox uses PAYMENT_PORT=fake. Completing with fake_success does not move real money. Tickets still go paid/fired only through applyPaymentSucceeded.

Not a certified ACP merchant on ChatGPT: no request signatures, no delegated payment tokens, no platform outbound webhooks (Stage 2).

Paths

• Discovery: GET /.well-known/acp.json
• Create: POST /locations/loc_main/checkout_sessions
• Update: POST /locations/loc_main/checkout_sessions/{id}
• Get: GET /locations/loc_main/checkout_sessions/{id}
• Complete: POST /locations/loc_main/checkout_sessions/{id}/complete
• Cancel: POST /locations/loc_main/checkout_sessions/{id}/cancel
• Buyer MCP: POST /mcp (same bearer)

Replace loc_main with ?loc= / path id when multi-location is enabled.

Required headers (every POST)

• Authorization: Bearer <BUYER_BEARER>
• API-Version: 2026-04-17
• Idempotency-Key: <unique>
• content-type: application/json when body present

Responses echo Idempotency-Key and Request-Id. Same key + different body → HTTP 409.

Session statuses

• incomplete — no lines
• not_ready_for_payment — 86, closed, bad qty, unknown item
• ready_for_payment — clean quote, under cap (or approved)
• pending_approval — over buyer_auto_cap_cents
• complete_in_progress — PaymentIntent processing
• completed — webhook/sync applied
• canceled · expired

Message codes

unknown_item out_of_stock (+ since) store_closed invalid_quantity over_line_limit total_mismatch session_expired payment_declined already_completed approval_required

Create/update return 201/200 with bad lines kept on the session. Complete while not ready or pending approval → HTTP 422, no charge.

Buyer MCP tools

POST /mcp with the same buyer bearer. Staff tools are not registered.

• get_menu
• get_store_status
• create_checkout
• update_checkout
• get_checkout
• complete_checkout
• cancel_checkout

Happy path (drip + fake pay)

BASE=http://localhost:5173
BUYER=buyer_dev_token
LOC=loc_main
VER="API-Version: 2026-04-17"
AUTH="Authorization: Bearer $BUYER"

# 1. discovery
curl -sS "$BASE/.well-known/acp.json"

# 2. create
RESP=$(curl -sS -X POST "$BASE/locations/$LOC/checkout_sessions" \
  -H "$AUTH" -H "$VER" -H "Idempotency-Key: demo-$(date +%s%N)" \
  -H "content-type: application/json" \
  -d '{"line_items":[{"id":"drip","quantity":1}]}')
echo "$RESP"
SID=$(python3 -c "import json,sys; print(json.load(sys.stdin)['id'])" <<<"$RESP")

# 3. complete (fake — no real money)
curl -sS -X POST "$BASE/locations/$LOC/checkout_sessions/$SID/complete" \
  -H "$AUTH" -H "$VER" -H "Idempotency-Key: demo-c-$(date +%s%N)" \
  -H "content-type: application/json" \
  -d '{"payment_data":{"instrument":{"type":"fake","fake_code":"fake_success"}}}'

Cert harness: npm run agent-harness (server must be up). See README.

Example SKUs

• drip — always available in seed
• latte.12oz.whole / latte.12oz.oat — oat starts 86’d (seed event)
• burrito — 3× exceeds default 2500¢ cap

Not in v1

• 3DS · ACP request signatures · platform webhooks to ChatGPT / UCP certification
• Card-present · tips · split tender · multi-location · inventory counts · live price edits
• Model marks paid · model picks SKUs or writes memo · auto-approve · x402 as lunch tender
• OSPOS live link · Twilio SMS · photo vision · public /inbox without auth