portage-ucp-client 0.4.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d63c926220d7d3aa15f0d11d4e2bdddc27ac0ad3227ae1bec20ed1beddd471a
-  data.tar.gz: 8fc8999401c53b2cc6db65347aa1a377a20a2c9d316a94354328237c4727ec78
+  metadata.gz: 89837fec9676ad52dd925e44ea86b12df99ae2f01ea56eccd4b877bbde7dfb7a
+  data.tar.gz: 34e0f987ba86fb975eaed185950cc6c2690c3f177ae8eacbbdb718560be4fb5e
 SHA512:
-  metadata.gz: bd5574b147b2552c3a304e49ec71bac10183cd20eab5a06b7df7c0aa261c36642af1d9885d5880b5d08fd2320b9211c3ecc921c849dfe20c9b39b3a7c39ce537
-  data.tar.gz: 31fa3387860b6d094399c5dd596fece5cf921e5f6b4b013f7180d37b8970f3c9b2981efd1cf37b7f8fada533439221e6c2d25e45e1078a597d13f88842a3f320
+  metadata.gz: 99581702b0ff34ed5a8fd680ffac05a05576823a6381bf312b63436107fb55977be865f7649be32827b3503b28465e3a862df9730058fe7ba4033179acd28505
+  data.tar.gz: db7d14a2a8149ca8b526ab4fc0ee6f6f807cad84b83eb57229879659e75e5d13207f96faada575354da1981fb78bc2a1de72edc98c38405a81a5efc3ddcfa7e1

data/CHANGELOG.md

@@ -4,6 +4,80 @@ 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.
 
+## [0.6.2] - 2026-09-23
+
+- Fix: the loopback and stdio transports dropped `cart_id` from every call,
+  so `get_cart`, `update_cart` and `cancel_cart` always failed with
+  "Missing required arguments: cart_id". `cart_id` is a real-UCP wire
+  argument only on `create_checkout` (the cart-to-checkout conversion), and
+  now only that call drops it. The shared rule is
+  `Transports::LocalArguments`.
+- The UCP wire reshaping in `Transports::Http` moved to
+  `Transports::UcpWireShape`, so other transports can build the same body.
+  `portage-ucp-webmcp` uses it for UCP-shaped page tools. There is no
+  behavior change for `Http`.
+
+## [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

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

@@ -8,7 +8,51 @@ 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
+
+        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.
@@ -40,6 +84,18 @@ module Portage
       # 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,4 +1,5 @@
 require_relative "../errors"
+require_relative "ucp_wire_shape"
 
 module Portage
   module Ucp
@@ -22,16 +23,7 @@ module Portage
         # into that real wire format before the request goes out — Loopback
         # and Stdio are untouched.
         class Http
-          # 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
+          include UcpWireShape
 
           def initialize(url:, headers: {})
             @client = ::MCP::Client.new(transport: ::MCP::Client::HTTP.new(url: url, headers: headers))
@@ -51,6 +43,10 @@ module Portage
             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
@@ -70,49 +66,6 @@ module Portage
             wire["idempotency-key"] = idempotency_key if idempotency_key
             wire
           end
-
-          def wire_arguments(name, arguments)
-            arguments = arguments.dup
-            arguments.delete(:idempotency_key)
-
-            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)
-
-            raise_unsupported_payment_shape if name == "complete_checkout"
-
-            arguments
-          end
-
-          def catalog_body(name, arguments)
-            case name
-            when "get_product" then { "catalog" => { "id" => arguments.fetch(:product_id) } }
-            when "lookup_catalog" then { "catalog" => { "ids" => arguments.fetch(:product_ids) } }
-            when "search_catalog" then { "catalog" => search_catalog_body(arguments) }
-            end
-          end
-
-          def raise_unsupported_payment_shape
-            raise UnsupportedWireShapeError,
-                  "complete_checkout isn't wired to the real payment-instrument shape yet — " \
-                  "checkout.payment.instruments varies by handler (card/apple-pay/shop-pay) and hasn't " \
-                  "been verified against a real payment flow"
-          end
-
-          def search_catalog_body(arguments)
-            { "query" => arguments[:query], "pagination" => { "limit" => arguments[:limit] }.compact }.compact
-          end
-
-          def wrap_line_items(wrapper, arguments, id_key:)
-            body = { "line_items" => Array(arguments[:line_items]).map { |li| wire_line_item(li) } }
-            { 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
     end

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

@@ -0,0 +1,30 @@
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        # Session's arguments trimmed to what this gem's own flat-argument
+        # server (Portage::Ucp::Mcp::Server -> Dispatcher -> Adapter) takes.
+        # `context`/`cart_id`/`handler_id`/`credential_type` are real-UCP
+        # wire concerns Session offers for Transports::Http to nest into a
+        # request body; the Adapter method signatures have no such keywords,
+        # so passing them on would be an ArgumentError on every call.
+        #
+        # `cart_id` is the exception that needs care: it is only a wire
+        # concern on create_checkout (the cart->checkout conversion). On
+        # get_cart/update_cart/cancel_cart it *is* the Adapter's own keyword,
+        # and dropping it there made every cart read/update/cancel fail with
+        # "Missing required arguments: cart_id".
+        module LocalArguments
+          REMOTE_WIRE_ARGUMENTS = %i[context cart_id handler_id credential_type].freeze
+          CART_ID_IS_WIRE_ONLY = %w[create_checkout].freeze
+
+          def self.strip(name, arguments)
+            remote = REMOTE_WIRE_ARGUMENTS
+            remote -= [:cart_id] unless CART_ID_IS_WIRE_ONLY.include?(name.to_s)
+            arguments.except(*remote)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -15,8 +15,15 @@ module Portage
             @next_id = 0
           end
 
+          # Real-UCP wire concerns this transport drops before they reach the
+          # Adapter — see LocalArguments. Dropped here rather than branched on
+          # in Session, so each transport keeps owning which arguments it
+          # understands.
+          REMOTE_WIRE_ARGUMENTS = LocalArguments::REMOTE_WIRE_ARGUMENTS
+
           def call_tool(name:, arguments:, meta: nil)
             @next_id += 1
+            arguments = LocalArguments.strip(name, arguments)
             response = @server.handle(
               { jsonrpc: "2.0", id: @next_id, method: "tools/call",
                 params: { name: name, arguments: arguments, **(meta ? { _meta: wire_meta(meta) } : {}) } }

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

@@ -12,8 +12,14 @@ module Portage
             @client.connect
           end
 
+          # Real-UCP wire concerns this transport drops before they reach the
+          # Adapter — see LocalArguments. Dropped here rather than branched on
+          # in Session, so each transport keeps owning which arguments it
+          # understands.
+          REMOTE_WIRE_ARGUMENTS = LocalArguments::REMOTE_WIRE_ARGUMENTS
+
           def call_tool(name:, arguments:, meta: nil)
-            response = @client.call_tool(name: name, arguments: arguments, meta: meta)
+            response = @client.call_tool(name: name, arguments: LocalArguments.strip(name, arguments), meta: meta)
             ToolResult.extract(response, symbol_keys: false)
           end
         end

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

@@ -0,0 +1,121 @@
+require_relative "http/complete_checkout_wire_shape"
+
+module Portage
+  module Ucp
+    module Client
+      module Transports
+        # Session's flat arguments reshaped into the real UCP wire format —
+        # every tool nests its arguments under a capability key
+        # (catalog:/cart:/checkout:), confirmed live against Shopify's
+        # 2026-08-25 rollout (see Transports::Http). Split out of Http so any
+        # transport that reaches a UCP-shaped tool surface (Streamable HTTP
+        # today, a page's WebMCP tools in portage-ucp-webmcp) builds the same
+        # body from the same code rather than a second copy drifting from it.
+        # Private instance methods of the including transport, as before.
+        module UcpWireShape
+          include Http::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
+
+          private
+
+          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
+    end
+  end
+end

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

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

data/lib/portage/ucp/client.rb

@@ -8,6 +8,7 @@ require_relative "client/version"
 require_relative "client/errors"
 require_relative "client/tool_result"
 require_relative "client/session"
+require_relative "client/transports/local_arguments"
 require_relative "client/transports/loopback"
 require_relative "client/transports/stdio"
 require_relative "client/transports/http"

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-ucp-client
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Tom Whitbread
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -114,6 +115,7 @@ description: 'Every other portage-ucp gem lets a Ruby program expose a commerce
   Adapter, stdio, Streamable HTTP) — callers never know which they got. Depends only
   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: []
 extra_rdoc_files: []
@@ -126,8 +128,11 @@ 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/local_arguments.rb
 - lib/portage/ucp/client/transports/loopback.rb
 - lib/portage/ucp/client/transports/stdio.rb
+- lib/portage/ucp/client/transports/ucp_wire_shape.rb
 - lib/portage/ucp/client/version.rb
 homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp-client
 licenses:
@@ -136,6 +141,7 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-client
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-client/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -150,7 +156,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.21
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Client-side SDK for portage-ucp — act as the shopper's agent against any
   UCP/MCP server