portage-ucp-client 0.3.3 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0cbf2202d4919b19b1a74189fdb31be0ead7ebe888d4bed829cef643493e694
-  data.tar.gz: 87f4581b5e880bda64986f54dad191ab3560ef838f2229e9a97f6c084f5b3ab2
+  metadata.gz: 8eeeb1c006e06155791f086b9dbfce78562ecb4281412c18dbdf5794a4189c08
+  data.tar.gz: 6be190c6cb00f34b0d0978b522da1e912f3a0b33973b6eb813db72859869b491
 SHA512:
-  metadata.gz: eff0ee7ebac57a7c3bb903a5a59793e39c47edf383573757ecdaa8940f2a3dc6f2fdce2a31c2a1fc0d264eafc1455ff9a0ced8e0d16bd5ddf5fbab139258a36b
-  data.tar.gz: 2293b310ae2d4185f92028b26b28b9449fc561fb5563788d9c598cb5b4802f80e9f9f81a38a6d05a7ad5ea89ce98ee25cbe9e458cc5564c0976eccce70a66aef
+  metadata.gz: c3ce4e8717a67bce1e3614677ec6b850ac58f6a598402debc78371b3a11fd3ebfde1d876375d6ed588d7ad9a7cde8a5a2806e982f2c5ab9ea8c14c72136b6651
+  data.tar.gz: a559406993fc8f3d9bb95f59df96e8fd70a6a45672675a9255e84857b1e36778993a1be498ca710ad8c60cb27cc27da3d48a4d2d8d3065550ee1254b141d2569

data/CHANGELOG.md

@@ -4,7 +4,88 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
-## [Unreleased]
+## [0.6.1] - 2026-09-22
+
+- `ServerError` carries the parsed error document on `#payload` when the
+  server's text content is JSON, with `#summary`, `#continue_url` and
+  `#server_messages` readers over it. A real UCP server answers an
+  out-of-stock `create_cart` with its whole `ucp` envelope — every
+  capability, every payment handler — wrapped around a two-word
+  `messages[].content` of "Sold out", so `#message` alone is several
+  kilobytes of JSON and unusable by anything that has to show it to a
+  person. `#message` is unchanged; the readers are additive, and return
+  nil/`[]` for a refusal whose text isn't JSON.
+
+## [0.6.0] - 2026-09-22
+
+- `Transports::Http` now builds `checkout.payment.instruments[]` for
+  `complete_checkout` against the card handler (`dev.shopify.card`) instead
+  of unconditionally raising `UnsupportedWireShapeError`. Top level carries
+  `id`/`checkout`; the instrument carries `id`/`handler_id`/`type`/
+  `credential: { token:, type: }`, per the schema pulled live from
+  `tools/list` 2026-09-22. `credential.type` (`dev.shopify.card_token`)
+  follows the payment-handler-guide's reverse-DNS-plus-`_token` convention
+  but is **not confirmed against a live response** — `complete_checkout` has
+  never actually been called (no grant to test against; see
+  `docs/ucp-tool-gating-investigation.md`). A `handler_id:` other than the
+  card handler still raises `UnsupportedWireShapeError`, now naming the
+  handler.
+- `Session#complete_checkout` takes optional `handler_id:`/`credential_type:`
+  to override the above; both are dropped by `Transports::{Loopback,Stdio}`
+  same as `context:`/`cart_id:`, since neither means anything to an Adapter
+  method signature.
+- New `Client::PaymentPermissionError`, distinct from `ServerError` (a
+  malformed/declined request) and `UnsupportedWireShapeError` (a handler
+  this client can't build a request for). `Transports::Http` raises it when
+  a `complete_checkout` refusal looks permission-shaped — going by the
+  *pattern* of Shopify's other confirmed permission error
+  (`get_order`'s `"You are forbidden to make tools/call requests"`) and the
+  community-thread description of what's gated on `complete_checkout`
+  (checkout-completion permission on the token, the merchant's channel
+  enabled). This pattern match is also unconfirmed live.
+
+## [0.5.0] - 2026-09-22
+
+- `Session#search_catalog`/`#get_product`/`#lookup_catalog`/`#create_cart`/
+  `#update_cart`/`#create_checkout`/`#update_checkout` take a `context:` — the
+  UCP `context` object (`address_country`, `address_region`, `postal_code`,
+  `currency`, `language`) — and `Transports::Http` nests it under the
+  capability key. This reads as optional and isn't: a store resolves which
+  market, and so which publication and inventory, a call is scoped to from it.
+  A cart built without one comes back with `line_items: []`, zeroed totals and
+  a `merchandise_out_of_stock` warning naming a product the same store's
+  `search_catalog` returned as `available` seconds earlier — confirmed live
+  2026-09-22. It failed open, with a plausible wrong answer instead of an
+  error.
+- `Session#create_checkout` takes a `cart_id:`, converting an existing cart
+  into a checkout. `line_items:` stays required: `checkout.cart_id`'s own
+  schema says a cart id alone is enough, and the live server rejects that with
+  `missing required properties: line_items`, so `Transports::Http` sends both.
+- `Transports::Loopback` and `Transports::Stdio` drop `context`/`cart_id`
+  before dispatch. Both hand arguments to this gem's own server, which splats
+  them into an Adapter method signature that has no such keywords.
+
+## [0.4.0] - 2026-09-17
+
+- Fixed `Transports::Http` sending every tool call in the flat, unwrapped
+  shape this gem's own Dispatcher/adapters speak — real UCP servers
+  (confirmed live against Shopify's 2026-08-25 rollout) reject it with a 422,
+  since they expect arguments nested under a capability key
+  (`catalog:`/`cart:`/`checkout:`) and a `meta.ucp-agent.profile` URL they
+  fetch themselves to verify the caller's identity. `Http` now builds that
+  real wire shape; `Loopback`/`Stdio` are unchanged, since the former talks
+  to this gem's own Dispatcher (still the flat shape by design) and the
+  latter has no confirmed real-world shape to fix. Callers must now pass
+  `meta: { agent_profile: <url> }`, or `MissingAgentProfileError` explains
+  what's missing instead of a bare 422.
+- Added `MissingAgentProfileError` and `UnsupportedWireShapeError`.
+  `complete_checkout` over HTTP raises the latter rather than guessing at
+  the real payment-instrument shape (Apple Pay/Shop Pay/card-token variants
+  each have distinct required credential fields) with no way to verify it
+  against a real payment flow.
+- Widens the `portage-ucp` dependency pin to `~> 0.8` so this gem installs
+  alongside `portage-ucp` 0.8.0 (the `~> 0.7` pin published with 0.3.3 is
+  pessimistic and excludes it).
 
 ## [0.3.3] - 2026-09-16
 

data/lib/portage/ucp/client/errors.rb

@@ -8,12 +8,94 @@ module Portage
       # `isError: true` — e.g. an AuthenticationError/RateLimitExceededError/
       # RawPanRejectedError the server side surfaced. `#message` is the text
       # content the server returned, not a generic string.
-      class ServerError < Error; end
+      #
+      # On a real UCP server that text is frequently the whole error document
+      # rather than a sentence — Shopify answers an out-of-stock `create_cart`
+      # with its entire `ucp` envelope (every capability, every payment
+      # handler) plus a two-word `messages[].content` of "Sold out" (confirmed
+      # live 2026-09-22). Raising that as a several-kilobyte `#message` is
+      # accurate and useless to anything that has to show it to a person, so
+      # `#payload` carries the parsed document when the text is JSON, and the
+      # readers below pull out the parts a caller actually wants. They return
+      # nil/[] rather than raising for a server whose text isn't JSON — this
+      # is an error path, and failing to parse an error is not worth a second
+      # error.
+      class ServerError < Error
+        attr_reader :payload
 
-      # Raised by .discover when the manifest can't be fetched/parsed, or has
-      # no `services` entry for the mcp transport to connect to (see
-      # Portage::Ucp::Manifest#services — the core-gem fix this depends on).
+        def initialize(message = nil, payload: nil)
+          super(message)
+          @payload = payload
+        end
+
+        # The server's own human-readable explanations, most specific first —
+        # `messages[]` entries carry `content`, `code` and `severity`.
+        def server_messages
+          Array(payload && payload["messages"]).filter_map do |m|
+            next unless m.is_a?(Hash)
+
+            { code: m["code"], content: m["content"], severity: m["severity"] }.compact
+          end
+        end
+
+        # One line fit to print: the server's message content joined, falling
+        # back to the raw text when there's no structured document to read.
+        def summary
+          contents = server_messages.filter_map { |m| m[:content] }
+          return message if contents.empty?
+
+          contents.join("; ")
+        end
+
+        # Where a shopper can finish by hand — present on Shopify's cart and
+        # checkout errors, which is exactly when a CLI wants to offer it.
+        def continue_url
+          payload && payload["continue_url"]
+        end
+      end
+
+      # Raised by .discover when the manifest can't be fetched at all: the URL
+      # 404s, the host refuses the connection, or the body isn't valid JSON.
+      # Indistinguishable from "this store doesn't run UCP" — callers that
+      # want to fall back silently for that case should rescue this.
       class DiscoveryError < Error; end
+
+      # Raised by .discover when the manifest *was* fetched and parsed as
+      # JSON, but this client couldn't make sense of its shape (no `services`
+      # entry advertising an `mcp` transport). Unlike DiscoveryError, this
+      # means the store *is* running UCP — the failure is on this client's
+      # side, not the store's — so callers shouldn't treat it the same as
+      # "no native UCP support" the way a 404 does.
+      class ManifestShapeError < DiscoveryError; end
+
+      # Raised by Transports::Http when a call is made without
+      # `meta: { agent_profile: <url> }` — real UCP servers (confirmed
+      # against Shopify's 2026-08-25 rollout) fetch and verify this URL
+      # themselves to identify the calling agent, so there's no sane default
+      # to fall back to; better to fail here than pass `meta: nil` through
+      # to a 422 the server explains as `profile_unreachable`.
+      class MissingAgentProfileError < Error; end
+
+      # Raised by Transports::Http for a mutating call this gem can't yet
+      # build the real wire shape for — currently only `complete_checkout`,
+      # whose `checkout.payment.instruments` shape (Apple Pay/Shop
+      # Pay/card-token variants, each with its own required credential
+      # fields) can't be safely guessed without a real payment flow to test
+      # against. Raised instead of sending a best-effort shape that might
+      # silently misbehave with real money on the line.
+      class UnsupportedWireShapeError < Error; end
+
+      # Raised by Transports::Http when a `complete_checkout` call is refused
+      # because this client's token lacks checkout-completion permission on
+      # the store, or the merchant hasn't enabled this agent's channel (see
+      # docs/ucp-tool-gating-investigation.md — that's the one thing genuinely
+      # gated in native UCP, granted case by case, no scope picker). Distinct
+      # from ServerError (a malformed/declined request the server understood
+      # and rejected on its own terms) and from UnsupportedWireShapeError (a
+      # handler this client can't build a request for at all) — callers that
+      # want to fall back to the checkout's own continue_url should rescue
+      # this specifically rather than pattern-matching ServerError#message.
+      class PaymentPermissionError < Error; end
     end
   end
 end

data/lib/portage/ucp/client/session.rb

@@ -38,22 +38,35 @@ module Portage
           capabilities&.include?(capability_name)
         end
 
-        def search_catalog(query:, limit: 20,
+        # `context:` is the UCP `context` object — buyer locale hints
+        # (`address_country`, `address_region`, `postal_code`, `currency`,
+        # `language`). Optional on paper, effectively required against a real
+        # store: see Transports::Http#with_context for what a store does with
+        # a cart built without one. Ignored by the loopback/stdio transports,
+        # which talk to this gem's own flat-argument server.
+        def search_catalog(query:, limit: 20, context: nil,
                            meta: nil)
-          call("search_catalog", meta: meta, query: query, limit: limit)
+          call("search_catalog", meta: meta, query: query, limit: limit, context: context)
         end
 
-        def get_product(product_id:, meta: nil) = call("get_product", meta: meta, product_id: product_id)
-        def lookup_catalog(product_ids:, meta: nil) = call("lookup_catalog", meta: meta, product_ids: product_ids)
+        def get_product(product_id:, context: nil, meta: nil)
+          call("get_product", meta: meta, product_id: product_id, context: context)
+        end
+
+        def lookup_catalog(product_ids:, context: nil, meta: nil)
+          call("lookup_catalog", meta: meta, product_ids: product_ids, context: context)
+        end
 
         def get_cart(cart_id:, meta: nil) = call("get_cart", meta: meta, cart_id: cart_id)
 
-        def create_cart(line_items:, idempotency_key: nil, meta: nil)
-          call("create_cart", meta: meta, line_items: line_items, idempotency_key: idempotency_key)
+        def create_cart(line_items:, idempotency_key: nil, context: nil, meta: nil)
+          call("create_cart", meta: meta, line_items: line_items, idempotency_key: idempotency_key,
+                              context: context)
         end
 
-        def update_cart(cart_id:, line_items:, idempotency_key: nil, meta: nil)
-          call("update_cart", meta: meta, cart_id: cart_id, line_items: line_items, idempotency_key: idempotency_key)
+        def update_cart(cart_id:, line_items:, idempotency_key: nil, context: nil, meta: nil)
+          call("update_cart", meta: meta, cart_id: cart_id, line_items: line_items,
+                              idempotency_key: idempotency_key, context: context)
         end
 
         def cancel_cart(cart_id:, idempotency_key: nil, meta: nil)
@@ -66,23 +79,39 @@ module Portage
         # (a Portage::Ucp::CheckoutFulfillment for loopback). Over stdio/HTTP
         # it would need a JSON wire shape this gem doesn't build yet, so
         # callers on those transports should leave it nil.
-        def create_checkout(line_items:, idempotency_key: nil, fulfillment: nil, meta: nil)
+        # `cart_id:` converts an existing cart into a checkout rather than
+        # re-listing its contents from scratch — HTTP only (see
+        # Transports::Http#wrap_line_items); `line_items:` stays required
+        # because the live server rejects a `cart_id`-only body.
+        def create_checkout(line_items:, idempotency_key: nil, fulfillment: nil, cart_id: nil, context: nil,
+                            meta: nil)
           call("create_checkout", meta: meta, line_items: line_items, idempotency_key: idempotency_key,
+                                  context: context, **(cart_id ? { cart_id: cart_id } : {}),
                                   **(fulfillment ? { fulfillment: fulfillment } : {}))
         end
 
         def get_checkout(checkout_id:, meta: nil) = call("get_checkout", meta: meta, checkout_id: checkout_id)
 
-        def update_checkout(checkout_id:, line_items:, idempotency_key: nil, fulfillment: nil, meta: nil)
+        def update_checkout(checkout_id:, line_items:, idempotency_key: nil, fulfillment: nil, context: nil,
+                            meta: nil)
           call("update_checkout", meta: meta, checkout_id: checkout_id, line_items: line_items,
-                                  idempotency_key: idempotency_key,
+                                  idempotency_key: idempotency_key, context: context,
                                   **(fulfillment ? { fulfillment: fulfillment } : {}))
         end
 
-        def complete_checkout(checkout_id:, payment_token:, idempotency_key: nil, meta: nil)
+        # `handler_id:`/`credential_type:` only matter to Transports::Http
+        # (see #complete_checkout_body there) — the loopback/stdio transports
+        # splat straight into an Adapter signature with no such keywords, so
+        # both are dropped there like `context:`/`cart_id:` (their own
+        # REMOTE_WIRE_ARGUMENTS). Left nil, Http assumes the one handler it
+        # knows how to build a request for (the card handler).
+        def complete_checkout(checkout_id:, payment_token:, idempotency_key: nil, handler_id: nil,
+                              credential_type: nil, meta: nil)
           Portage::Ucp::PaymentTokenGuard.validate!(payment_token)
           call("complete_checkout", meta: meta, checkout_id: checkout_id, payment_token: payment_token,
-                                    idempotency_key: idempotency_key)
+                                    idempotency_key: idempotency_key,
+                                    **(handler_id ? { handler_id: handler_id } : {}),
+                                    **(credential_type ? { credential_type: credential_type } : {}))
         end
 
         def cancel_checkout(checkout_id:, idempotency_key: nil, meta: nil)
@@ -106,6 +135,7 @@ module Portage
         private
 
         def call(action, meta: nil, **arguments)
+          arguments.delete(:context) if arguments[:context].nil?
           arguments[:idempotency_key] ||= SecureRandom.uuid if MUTATING_ACTIONS.include?(action)
           @transport.call_tool(name: action, arguments: arguments, meta: meta)
         end

data/lib/portage/ucp/client/tool_result.rb

@@ -1,3 +1,5 @@
+require "json"
+
 module Portage
   module Ucp
     module Client
@@ -10,7 +12,10 @@ module Portage
         def self.extract(response, symbol_keys:)
           result = fetch(response, "result", symbol_keys) || {}
           content = fetch(result, "content", symbol_keys)
-          raise ServerError, text(content, symbol_keys: symbol_keys) if fetch(result, "isError", symbol_keys)
+          if fetch(result, "isError", symbol_keys)
+            body = text(content, symbol_keys: symbol_keys)
+            raise ServerError.new(body, payload: parse(body))
+          end
 
           fetch(result, "structuredContent", symbol_keys)
         end
@@ -19,6 +24,18 @@ module Portage
           Array(content).filter_map { |block| fetch(block, "text", symbol_keys) }.join(" ")
         end
 
+        # A UCP server's error text is usually its whole JSON error document
+        # (see ServerError) — parsed here so callers get the `messages[]` and
+        # `continue_url` inside it without re-parsing a string. Anything that
+        # isn't a JSON object stays nil and callers fall back to the raw text.
+        def self.parse(body)
+          parsed = JSON.parse(body.to_s)
+          parsed.is_a?(Hash) ? parsed : nil
+        rescue JSON::ParserError
+          nil
+        end
+        private_class_method :parse
+
         def self.fetch(hash, key, symbol_keys)
           hash[symbol_keys ? key.to_sym : key]
         end

data/lib/portage/ucp/client/transports/http/complete_checkout_wire_shape.rb

@@ -0,0 +1,86 @@
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        class Http
+          # `complete_checkout`'s real-UCP wire shape — split out of Http
+          # itself only to keep that class under Metrics/ClassLength; these
+          # methods are private instance methods of Http, not a separate
+          # collaborator object, so they still read/raise the same
+          # Http-scoped constants and errors.
+          module CompleteCheckoutWireShape
+            # The one payment handler this transport can build a request for.
+            # Reverse-DNS handler id, confirmed live 2026-09-22 in the dev
+            # store's checkout `payment_handlers` (see docs handoff) — the key
+            # the store itself uses, not the `id`/`spec` fields nested under
+            # it (those name the handler's own config, e.g. "shopify.card").
+            CARD_HANDLER_ID = "dev.shopify.card".freeze
+
+            # `credential.type` per the payment-handler-guide's discriminated
+            # union (ucp.dev/specification/payment/guide, e.g.
+            # `tokenizer_card_token` for a `com.example.tokenizer` handler) —
+            # the reverse-DNS handler id plus a `_token` suffix. NOT confirmed
+            # against a live response (complete_checkout has never been
+            # called — see handoff doc); a caller that knows better can
+            # override via `credential_type:`.
+            CARD_CREDENTIAL_TYPE = "dev.shopify.card_token".freeze
+
+            # Substrings a permission refusal is expected to carry, going by
+            # the *shape* of Shopify's other permission error ("You are
+            # forbidden to make tools/call requests" on `get_order`,
+            # confirmed live — see docs/ucp-tool-gating-investigation.md) and
+            # the community-thread description of what's gated
+            # (checkout-completion permission / channel not enabled). NOT
+            # confirmed for `complete_checkout` itself — no live call has
+            # been made. A refusal that doesn't match falls through as a
+            # plain ServerError/RequestHandlerError instead of being
+            # misreported.
+            PERMISSION_REFUSAL_PATTERN = /forbidden|not enabled|not granted|checkout.?completion/i
+
+            # `checkout.payment.instruments[]` — schema pulled live from
+            # tools/list 2026-09-22 (see handoff doc): top level needs
+            # `id`/`checkout`, `checkout.payment.instruments[]` items need
+            # `id`/`handler_id`/`type`, and every handler but apple-pay needs
+            # `credential: { token:, type: }`. Only the card handler is
+            # wired; any other `handler_id:` the caller passes raises,
+            # naming it, rather than guessing a shape that's never been
+            # tested live.
+            def complete_checkout_body(arguments, idempotency_key)
+              handler_id = arguments[:handler_id] || CARD_HANDLER_ID
+              raise_unsupported_payment_shape(handler_id) unless handler_id == CARD_HANDLER_ID
+
+              instrument = {
+                "id" => "instrument-#{idempotency_key}",
+                "handler_id" => handler_id,
+                "type" => "card",
+                "credential" => { "token" => arguments.fetch(:payment_token),
+                                  "type" => arguments[:credential_type] || CARD_CREDENTIAL_TYPE }
+              }
+              { "id" => arguments.fetch(:checkout_id),
+                "checkout" => { "payment" => { "instruments" => [instrument] } } }
+            end
+
+            def permission_refusal?(message)
+              message.to_s.match?(PERMISSION_REFUSAL_PATTERN)
+            end
+
+            def permission_error(cause)
+              PaymentPermissionError.new(
+                "complete_checkout refused for lack of permission (#{cause.class}: #{cause.message}) — needs " \
+                "checkout-completion permission on this client's token and the merchant enabling this agent's " \
+                "channel on their shop"
+              )
+            end
+
+            def raise_unsupported_payment_shape(handler_id)
+              raise UnsupportedWireShapeError,
+                    "complete_checkout doesn't know how to build a payment instrument for handler " \
+                    "#{handler_id.inspect} — only #{CARD_HANDLER_ID.inspect} is wired; apple-pay/shop-pay each " \
+                    "need their own credential shape this client hasn't verified against a real payment flow"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/client/transports/http.rb

@@ -1,3 +1,6 @@
+require_relative "../errors"
+require_relative "http/complete_checkout_wire_shape"
+
 module Portage
   module Ucp
     module Client
@@ -6,15 +9,160 @@ module Portage
         # `mcp` gem's client half (MCP::Client + MCP::Client::HTTP). Performs
         # the `initialize` handshake eagerly so a caller's first real call
         # doesn't pay for it.
+        #
+        # Session's public API (query:/limit:, cart_id:/checkout_id:/
+        # order_id:, line_items: [{product_id:, quantity:}], ...) stays flat
+        # — it's shared with Loopback, which hands arguments straight to this
+        # gem's own Dispatcher/adapters, and those speak that flat shape by
+        # design (see portage-ucp/lib/portage/ucp/mcp/server.rb). Real UCP
+        # servers don't: confirmed live against Shopify's 2026-08-25 rollout,
+        # every tool nests its arguments under a capability key
+        # (catalog:/cart:/checkout:) and requires a `meta.ucp-agent.profile`
+        # URL the server itself fetches to verify the caller's identity. This
+        # transport is the one place that reshapes Session's flat arguments
+        # into that real wire format before the request goes out — Loopback
+        # and Stdio are untouched.
         class Http
+          include CompleteCheckoutWireShape
+
+          # Actions whose one identifying argument becomes a top-level `id`.
+          ID_ARG = {
+            "get_cart" => :cart_id, "cancel_cart" => :cart_id,
+            "get_checkout" => :checkout_id, "cancel_checkout" => :checkout_id,
+            "get_order" => :order_id
+          }.freeze
+
+          CATALOG_ACTIONS = %w[get_product lookup_catalog search_catalog].freeze
+          CART_ACTIONS = %w[create_cart update_cart].freeze
+          CHECKOUT_ACTIONS = %w[create_checkout update_checkout].freeze
+
           def initialize(url:, headers: {})
             @client = ::MCP::Client.new(transport: ::MCP::Client::HTTP.new(url: url, headers: headers))
             @client.connect
           end
 
+          # `meta` here is a *property of the tool's own `arguments` object*
+          # (confirmed live against Shopify's schema — every tool's
+          # input_schema lists "meta" as a top-level sibling of
+          # "catalog"/"cart"/"checkout"), not the MCP protocol's `_meta`
+          # envelope field. `MCP::Client#call_tool`'s own `meta:` kwarg sends
+          # the latter, so it's unused here — the caller-supplied meta gets
+          # folded into `arguments["meta"]` instead.
           def call_tool(name:, arguments:, meta: nil)
-            response = @client.call_tool(name: name, arguments: arguments, meta: meta)
+            idempotency_key = arguments[:idempotency_key] || arguments["idempotency_key"]
+            wire = wire_arguments(name, arguments)
+            wire["meta"] = wire_meta(meta, idempotency_key)
+            response = @client.call_tool(name: name, arguments: wire)
             ToolResult.extract(response, symbol_keys: false)
+          rescue ServerError, MCP::Client::RequestHandlerError => e
+            raise permission_error(e) if name == "complete_checkout" && permission_refusal?(e.message)
+
+            raise
+          end
+
+          private
+
+          # `idempotency_key` arrives via `arguments` — Session#call folds it
+          # in there for every mutating action — not via `meta`, so it has to
+          # be threaded through here rather than read off `meta` directly.
+          def wire_meta(meta, idempotency_key)
+            profile = meta && (meta[:agent_profile] || meta["agent_profile"])
+            unless profile
+              raise MissingAgentProfileError,
+                    "meta: { agent_profile: <url> } is required for HTTP calls — real UCP servers fetch " \
+                    "and verify this URL to identify the calling agent"
+            end
+
+            wire = { "ucp-agent" => { "profile" => profile } }
+            wire["idempotency-key"] = idempotency_key if idempotency_key
+            wire
+          end
+
+          def wire_arguments(name, arguments)
+            idempotency_key = arguments[:idempotency_key] || arguments["idempotency_key"]
+            arguments = arguments.dup
+            arguments.delete(:idempotency_key)
+
+            return complete_checkout_body(arguments, idempotency_key) if name == "complete_checkout"
+            return { "id" => arguments.fetch(ID_ARG[name]) } if ID_ARG.key?(name)
+            return catalog_body(name, arguments) if CATALOG_ACTIONS.include?(name)
+            return wrap_line_items("cart", arguments, id_key: :cart_id) if CART_ACTIONS.include?(name)
+            return wrap_line_items("checkout", arguments, id_key: :checkout_id) if CHECKOUT_ACTIONS.include?(name)
+
+            arguments
+          end
+
+          def catalog_body(name, arguments)
+            body = case name
+                   when "get_product" then { "id" => arguments.fetch(:product_id) }
+                   when "lookup_catalog" then { "ids" => arguments.fetch(:product_ids) }
+                   when "search_catalog" then search_catalog_body(arguments)
+                   end
+            { "catalog" => with_context(body, arguments) }
+          end
+
+          # `context` carries the buyer's locale/currency/region hints the UCP
+          # `context` object is specified for. It looks optional and isn't:
+          # Shopify resolves which market (and therefore which publication and
+          # inventory) a call is scoped to from it, and a cart built without it
+          # comes back with `line_items: []`, zeroed totals, and a
+          # `merchandise_out_of_stock` warning naming a product `search_catalog`
+          # had just reported as `availability.available == true` on the same
+          # store. Confirmed live 2026-09-22: identical `create_cart`, context
+          # added, returns the line item at its real price.
+          #
+          # A sweep of nine third-party Shopify stores the same day found the
+          # empty cart is only the loudest of three outcomes for an omitted
+          # context. Three stores built a correct cart without one; one
+          # emptied it; five priced it in the market of the *caller's IP*
+          # (a run from Bangkok got THB totals from stores whose shoppers had
+          # asked for nothing of the sort). So an omitted context doesn't
+          # merely degrade results — it produces a valid-shaped cart at the
+          # wrong currency, with nothing on the response saying so, which is
+          # the harder failure to notice of the two.
+          #
+          # Sending one is necessary, not sufficient: the cart is scoped to
+          # the market the context names, so a product the store doesn't
+          # publish into that market drops out with the same
+          # `merchandise_out_of_stock` message (mejuri.com, `US`/`USD` and
+          # `GB`/`GBP` empty, `CA`/`CAD` fine). That store's `search_catalog`
+          # ignored the context entirely and quoted CAD at
+          # `available: true` for every market asked, so the search result
+          # gives a caller no warning. Nothing to fix here — it's the store's
+          # market config — but callers shouldn't read this code as a
+          # guarantee that a context makes carts work.
+          def with_context(body, arguments)
+            context = arguments[:context] || arguments["context"]
+            return body if context.nil? || context.empty?
+
+            body.merge("context" => stringify(context))
+          end
+
+          def stringify(context)
+            context.to_h { |key, value| [key.to_s, value] }
+          end
+
+          def search_catalog_body(arguments)
+            { "query" => arguments[:query], "pagination" => { "limit" => arguments[:limit] }.compact }.compact
+          end
+
+          # `cart_id` on a checkout body is the cart→checkout conversion the
+          # spec's `checkout.cart_id` describes ("the business uses cart
+          # contents and ignores overlapping fields"). Its schema says
+          # `cart_id` alone is enough; the live server disagrees and rejects
+          # that with `Invalid arguments: object at '/checkout' is missing
+          # required properties: line_items` (confirmed live 2026-09-22), so
+          # the line items go out alongside it rather than instead of it.
+          def wrap_line_items(wrapper, arguments, id_key:)
+            body = { "line_items" => Array(arguments[:line_items]).map { |li| wire_line_item(li) } }
+            body["cart_id"] = arguments[:cart_id] if wrapper == "checkout" && arguments[:cart_id]
+            body = with_context(body, arguments)
+            { wrapper => body }.tap { |h| h["id"] = arguments[id_key] if arguments[id_key] }
+          end
+
+          def wire_line_item(line_item)
+            { "item" => { "id" => line_item[:product_id] || line_item["product_id"] },
+              "quantity" => line_item[:quantity] || line_item["quantity"] }
           end
         end
       end

data/lib/portage/ucp/client/transports/loopback.rb

@@ -15,14 +15,43 @@ module Portage
             @next_id = 0
           end
 
+          # `context`/`cart_id`/`handler_id`/`credential_type` are real-UCP
+          # wire concerns Session offers for Transports::Http to nest into a
+          # request body. This transport hands arguments straight to this
+          # gem's own Dispatcher, which splats them into an Adapter method
+          # signature that has no such keywords, so passing them on would be
+          # an ArgumentError on every call. Dropped here rather than branched
+          # on in Session, so each transport keeps owning which arguments it
+          # understands.
+          REMOTE_WIRE_ARGUMENTS = %i[context cart_id handler_id credential_type].freeze
+
           def call_tool(name:, arguments:, meta: nil)
             @next_id += 1
+            arguments = arguments.except(*REMOTE_WIRE_ARGUMENTS)
             response = @server.handle(
               { jsonrpc: "2.0", id: @next_id, method: "tools/call",
-                params: { name: name, arguments: arguments, **(meta ? { _meta: meta } : {}) } }
+                params: { name: name, arguments: arguments, **(meta ? { _meta: wire_meta(meta) } : {}) } }
             )
             ToolResult.extract(response, symbol_keys: true)
           end
+
+          private
+
+          # Session's transport-agnostic `meta: { agent_profile: <url> }`
+          # convention (the one `Buy#agent_meta` actually passes, regardless
+          # of which transport `session` turns out to be) has to reach
+          # `Mcp::Server.agent_profile_for`, which only ever looks at
+          # `_meta["ucp-agent.profile"]`/`_meta[:"ucp-agent.profile"]` — a
+          # different key. Without this, an own-store loopback buy silently
+          # dropped its agent_profile (no error, just a blank field in
+          # tool_call_received/tool_called events) while the real-store HTTP
+          # transport picked the same `agent_profile:` key up correctly.
+          # Merges rather than replaces so a caller already using the
+          # server's own key (as this gem's specs do) is untouched.
+          def wire_meta(meta)
+            profile = meta[:agent_profile] || meta["agent_profile"]
+            profile ? meta.merge("ucp-agent.profile" => profile) : meta
+          end
         end
       end
     end

data/lib/portage/ucp/client/transports/stdio.rb

@@ -12,8 +12,18 @@ module Portage
             @client.connect
           end
 
+          # `context`/`cart_id`/`handler_id`/`credential_type` are real-UCP
+          # wire concerns Session offers for Transports::Http to nest into a
+          # request body. This transport hands arguments straight to this
+          # gem's own Dispatcher, which splats them into an Adapter method
+          # signature that has no such keywords, so passing them on would be
+          # an ArgumentError on every call. Dropped here rather than branched
+          # on in Session, so each transport keeps owning which arguments it
+          # understands.
+          REMOTE_WIRE_ARGUMENTS = %i[context cart_id handler_id credential_type].freeze
+
           def call_tool(name:, arguments:, meta: nil)
-            response = @client.call_tool(name: name, arguments: arguments, meta: meta)
+            response = @client.call_tool(name: name, arguments: arguments.except(*REMOTE_WIRE_ARGUMENTS), meta: meta)
             ToolResult.extract(response, symbol_keys: false)
           end
         end

data/lib/portage/ucp/client/version.rb

@@ -1,7 +1,7 @@
 module Portage
   module Ucp
     module Client
-      VERSION = "0.3.3".freeze
+      VERSION = "0.6.1".freeze
     end
   end
 end

data/lib/portage/ucp/client.rb

@@ -70,17 +70,31 @@ module Portage
       end
       private_class_method :fetch_manifest
 
+      # Real UCP manifests (confirmed live on Casper, Allbirds, Glossier, and
+      # 34+ other Shopify UCP rollouts as of "2026-08-25") nest everything one
+      # level deeper under a "ucp" key. This gem's own server side
+      # (Portage::Ucp::Manifest) still emits the old flat shape, so both are
+      # supported rather than picking one — see docs/well-known-ucp.md.
+      def self.ucp_section(manifest)
+        manifest["ucp"] || manifest
+      end
+      private_class_method :ucp_section
+
       def self.mcp_endpoint(manifest)
-        service = Array(manifest["services"]).find { |s| s["transport"] == "mcp" }
-        endpoint = service && service["endpoint"]
-        raise DiscoveryError, "manifest has no mcp service entry to connect to" unless endpoint
+        services = ucp_section(manifest)["services"]
+        entries = services.is_a?(Hash) ? services.values.flatten : Array(services)
+        endpoint = entries.select { |s| s["transport"] == "mcp" }
+                          .max_by { |s| s["version"].to_s }
+                          &.fetch("endpoint", nil)
+        raise ManifestShapeError, "manifest has no mcp service entry to connect to" unless endpoint
 
         endpoint
       end
       private_class_method :mcp_endpoint
 
       def self.capability_names(manifest)
-        Array(manifest["capabilities"]).map { |c| c["name"] }
+        capabilities = ucp_section(manifest)["capabilities"]
+        capabilities.is_a?(Hash) ? capabilities.keys : Array(capabilities).map { |c| c["name"] }
       end
       private_class_method :capability_names
     end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-client
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.6.1
 platform: ruby
 authors:
 - Tom Whitbread
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -30,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -99,7 +113,8 @@ description: 'Every other portage-ucp gem lets a Ruby program expose a commerce
   /.well-known/ucp manifest, or drive your own Adapter directly, and place an order
   as the client. Three transports behind one interface (loopback over an in-process
   Adapter, stdio, Streamable HTTP) — callers never know which they got. Depends only
-  on portage-ucp + the mcp gem''s client half; no adapter gem is a dependency.'
+  on portage-ucp, the mcp gem''s client half, and faraday (the HTTP transport''s backend);
+  no adapter gem is a dependency.'
 email:
 executables: []
 extensions: []
@@ -113,6 +128,7 @@ files:
 - lib/portage/ucp/client/session.rb
 - lib/portage/ucp/client/tool_result.rb
 - lib/portage/ucp/client/transports/http.rb
+- lib/portage/ucp/client/transports/http/complete_checkout_wire_shape.rb
 - lib/portage/ucp/client/transports/loopback.rb
 - lib/portage/ucp/client/transports/stdio.rb
 - lib/portage/ucp/client/version.rb