portage-cli 0.6.0 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4acb63ece20e24b7d43048315145a96e15ded1c4e5b0cf83c3f045603a033af6
-  data.tar.gz: 536057c80badcd44ee1be90679fd7f9233adb3d5a1c07b5b11a12201fbae5701
+  metadata.gz: 72d2d335f8f6d40abab7b9307f4e3dcfc21b2cb9dfc4fc5f67c490dd2d42e5ee
+  data.tar.gz: 98065dbee850dd5db2141731f45078526b00b877bbe67278b13c5b6ffa7a448e
 SHA512:
-  metadata.gz: 54bc26bf74fe96c2a2154062ab41619e10bf046da1cc06f067fc1f0f7eaec9c29ff6ab461e9cf2907ede4084805b8718f65557e5d4c3c79c486650eea10c1075
-  data.tar.gz: deb45f093ce769ebae837bad5af628c8970aac76b6741ea8b083393b45038451a455ece2d603671c3d2884e3974858941ff6c29d96affd7bd3bbcc89f6a689d9
+  metadata.gz: 2ad81909c54bbf4ca6e588c8b3f72b19d8d7788d4762754b0f38783a51ce44dca60cd6e9a2aba7f05faeb0e7ca122bece589884194c44b982d7009615322432f
+  data.tar.gz: 81a8c3098e6dad475ec1138c44de866be4a349a3bc57a133330c6684b9924b050eebd44f1440292f2f28d0cd87bb1f6c3cbd356c85ccc4f769e7162dbff1803b

data/CHANGELOG.md

@@ -4,6 +4,85 @@ 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.4] - 2026-09-22
+
+- **Every dead-end hand-off pointed the shopper at the store's refund
+  policy.** `#checkout_url_of` took the first entry in the checkout's
+  `links` with a url, on the reasoning that not every backend types its
+  link entries. Live UCP stores put nothing *but* policy links there:
+  five third-party Shopify stores checked 2026-09-22 returned
+  `refund_policy`, `privacy_policy`, `terms_of_service`, `shipping_policy`
+  and `contact_information`, and never a checkout link — the checkout is
+  always at `continue_url`. So `requires_escalation`, permission-denied and
+  no-payment-token reports all handed over a policy page, `--auto-open`
+  opened it and `--notify-webhook` posted it. Now reads `continue_url`
+  first, and the `links` fallback skips policy/contact entries rather than
+  handing over a wrong URL.
+- `adapter_flow` rescued `LoadError` and `StandardError` identically,
+  returning `nil` either way — correct once the adapter gem genuinely isn't
+  installed, wrong once it's live and its own call actually failed. A live
+  adapter's `StandardError` (e.g. "no payment_method configured on this
+  Adapter") now comes back as its own report instead of the generic "no
+  automated path" dead end, distinguishable from "no adapter for this
+  platform" by `source`.
+
+## [0.6.3] - 2026-09-22
+
+- A store refusing a cart or checkout call on its own terms — out of stock,
+  a line it won't take, an expired cart — is reported as a normal outcome
+  carrying the store's own sentence and its `continue_url`, instead of
+  escaping `Buy#call` as an unhandled `Client::ServerError`. It printed a
+  Ruby backtrace whose "message" was the store's entire several-kilobyte
+  `ucp` error envelope; confirmed live 2026-09-22 against a genuinely
+  sold-out variant. Same posture `requires_escalation` and
+  `PaymentPermissionError` already had.
+- Requires `portage-ucp-client ~> 0.6` (was `~> 0.5`), which is what
+  `Buy#complete`'s `rescue Client::PaymentPermissionError` has actually
+  needed since 0.6.2 — that constant landed in client 0.6.0, and a `rescue`
+  naming a missing constant raises `NameError` over the top of whatever
+  error it was meant to catch.
+
+## [0.6.2] - 2026-09-22
+
+- `Buy#complete` treats a `Client::PaymentPermissionError` from
+  `complete_checkout` (this agent not yet granted checkout-completion on the
+  store) as a normal outcome rather than a failure — same posture as
+  `requires_escalation`: the report carries the checkout's `continue_url`
+  so the shopper can finish on the merchant's own checkout page.
+- Every dead-end `buy` outcome that hands a shopper a `checkout_url`
+  (`requires_escalation`, permission denied, no `--payment-token`) can now
+  auto-open that link in the shopper's browser and/or POST it to a webhook,
+  instead of leaving it as inert text/JSON. Both off by default; opt in with
+  `--auto-open`/`--notify-webhook <url>`, `PORTAGE_AUTO_OPEN_CHECKOUT`/
+  `PORTAGE_NOTIFY_WEBHOOK_URL`, or `~/.portage/config.json`
+  (`auto_open_checkout`/`notify_webhook_url`), in that precedence order.
+  Never fires on `--dry-run`. Best-effort throughout: a failed open or POST
+  never fails the buy, and surfaces instead as `handoff: {opened:,
+  notified:, notify_error:}` on the report. New `CheckoutHandoff`, `Notifier`,
+  and `Config` classes; `portage-ucp` core is untouched.
+
+## [0.6.1] - 2026-09-22
+
+- `portage generate agent-profile` emits the capability identifiers a UCP
+  server actually resolves an agent's tool registry from. It was emitting
+  `dev.ucp.shopping.catalog` — reusing `Portage::Ucp::Capabilities::CATALOG
+  .name`, which is correct for a business's own manifest, where one Capability
+  owns all three catalog actions, and wrong here: the registry is per action
+  (`dev.ucp.shopping.catalog.search`, `dev.ucp.shopping.catalog.lookup`). A
+  profile declaring the coarse name resolved to zero catalog tools, and stores
+  reported that as `-32602 Tool not found: search_catalog` seconds after
+  `tools/list` advertised it. Versions are now spec revisions (`2026-08-25`)
+  rather than `"1"`, and `ucp.services` declares the shopping service instead
+  of being left `{}`. The checked-in
+  `agent-profile/agent-profile.json` is regenerated, existing signing keys
+  kept. See `docs/ucp-tool-gating-investigation.md`.
+- New `Portage::Cli::BuyerContext` builds the UCP `context` object from
+  `PORTAGE_SHIP_COUNTRY`/`PORTAGE_SHIP_REGION`/`PORTAGE_SHIP_POSTAL_CODE`,
+  `PORTAGE_CURRENCY` and `PORTAGE_LANGUAGE`. `buy` and `find` send it on every
+  catalog and checkout call — without it a real store builds an empty cart and
+  calls it sold out. Partial by design, unlike `ShippingProfile`, which stays
+  all-or-nothing because a half-filled address can't be submitted.
+
 ## [0.6.0] - 2026-09-17
 
 - Fixed `buy`/`find` crashing with a raw `Faraday::UnprocessableContentError`

data/lib/portage/cli/buy.rb

@@ -5,6 +5,8 @@ require "portage/ucp"
 require "portage/ucp/client"
 require "portage/ucp/journal"
 require_relative "payment_methods"
+require_relative "checkout_handoff"
+require_relative "notifier"
 
 module Portage
   module Cli
@@ -27,7 +29,16 @@ module Portage
       #   whatever the catalog search happens to rank first — how `portage
       #   find` hands a picked offer over without the ranking being guessed
       #   twice.
-      def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil)
+      # @param auto_open [Boolean, nil] per-invocation override for whether a
+      #   dead-end checkout_url auto-opens in the shopper's browser — nil
+      #   (the default) defers to PORTAGE_AUTO_OPEN_CHECKOUT / config.json
+      #   (see CheckoutHandoff).
+      # @param notify_webhook [String, nil] per-invocation override for the
+      #   webhook URL a dead-end checkout_url is POSTed to — nil (the
+      #   default) defers to PORTAGE_NOTIFY_WEBHOOK_URL / config.json (see
+      #   Notifier).
+      def initialize(url:, query:, qty: 1, payment_token: nil, yes: false, dry_run: false, product_id: nil,
+                     auto_open: nil, notify_webhook: nil)
         raw = url.to_s.strip
         raw = "https://#{raw}" unless raw =~ %r{\Ahttps?://}i
         @uri = URI.parse(raw)
@@ -37,8 +48,13 @@ module Portage
         @yes = yes
         @dry_run = dry_run
         @product_id = product_id
+        @auto_open = auto_open
+        @notify_webhook = notify_webhook
       end
 
+      # Link `type`s that are never the checkout — see #checkout_url_of.
+      POLICY_LINK_TYPES = /policy|policies|terms|contact|privacy|legal|imprint/i
+
       def call
         session = discover(@uri)
         return native_flow(session) if session
@@ -80,7 +96,7 @@ module Portage
           catalog_only(session)
         end
       rescue Portage::Ucp::Client::MissingAgentProfileError, Portage::Ucp::Client::UnsupportedWireShapeError,
-             MCP::Client::RequestHandlerError => e
+             Portage::Ucp::Client::ServerError, MCP::Client::RequestHandlerError => e
         native_flow_error_report(e)
       end
 
@@ -93,6 +109,8 @@ module Portage
         when Portage::Ucp::Client::UnsupportedWireShapeError
           build_report(source: "native_ucp", browse: true, checkout: false,
                        message: "Can't complete checkout on #{@uri} yet: #{error.message}")
+        when Portage::Ucp::Client::ServerError
+          server_error_report(error)
         else
           # MCP::Client::RequestHandlerError doesn't retain the server's JSON
           # error body on this path, so this can't quote the server's own
@@ -105,6 +123,28 @@ module Portage
         end
       end
 
+      # A store refusing a cart/checkout call on its own terms — out of stock,
+      # a line it won't accept, a cart that expired — is an answer, not a
+      # crash. This used to escape `#call` as an unhandled ServerError,
+      # printing a Ruby backtrace whose "message" was the server's entire
+      # several-kilobyte `ucp` envelope (confirmed live 2026-09-22: a
+      # genuinely sold-out variant on a Shopify store). Report the server's
+      # own sentence instead, and hand back the `continue_url` it supplied so
+      # the shopper has somewhere to go — same posture as
+      # #escalation_report/#permission_denied_report.
+      #
+      # Deliberately not routed through #hand_off: that fires the auto-open
+      # and webhook side effects, which belong to a checkout this agent
+      # actually built. There's no checkout here — the call that failed is
+      # what would have created one.
+      def server_error_report(error)
+        url = error.continue_url
+        build_report(
+          source: "native_ucp", browse: true, checkout: false, checkout_url: url,
+          message: "#{@uri} couldn't complete this: #{error.summary}#{url && " — finish it at #{url}"}"
+        )
+      end
+
       def catalog_only(session)
         products = safe_search(session)
         report = build_report(
@@ -145,14 +185,29 @@ module Portage
         env = Portage::Ucp::Resolver.env_for(platform)
         return nil if Portage::Ucp::Resolver.missing_env(platform, env).any?
 
-        adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
+        begin
+          adapter = Portage::Ucp::Resolver.build_adapter(platform, env)
+        rescue LoadError
+          return nil
+        end
+
+        run_adapter_flow(adapter, platform)
+      end
+
+      # Once the adapter gem is installed and the adapter itself is live, a
+      # `StandardError` it raises is a real, actionable failure (e.g. "no
+      # payment_method configured") — surface it instead of falling through
+      # to `dead_end`'s generic "visit it yourself" message, which would hide
+      # it identically to "there's no adapter for this platform at all".
+      def run_adapter_flow(adapter, platform)
         if adapter_supports_checkout?(adapter)
           full_buy(client_for(adapter), source: "adapter:#{platform.name}", fulfillment_adapter: adapter)
         else
           catalog_only_adapter(adapter, platform)
         end
-      rescue LoadError, StandardError
-        nil
+      rescue StandardError => e
+        build_report(source: "adapter:#{platform.name}", browse: false, checkout: false,
+                     message: "#{platform.name} adapter error: #{e.message}")
       end
 
       def adapter_supports_checkout?(adapter)
@@ -213,7 +268,7 @@ module Portage
 
         checkout = session.create_checkout(line_items: [{ product_id: line_item_id_of(product), quantity: @qty }],
                                            fulfillment: requested_fulfillment(fulfillment_adapter),
-                                           meta: agent_meta)
+                                           context: buyer_context, meta: agent_meta)
         checkout = select_cheapest_shipping(session, checkout) if fulfillment_adapter
         finish_checkout(session, source, products, checkout)
       end
@@ -324,13 +379,87 @@ module Portage
       def complete(session, source, products, checkout)
         @payment_token ||= PaymentMethods.default
         unless @payment_token
-          return checkout_report(source, products, checkout,
-                                 message: "No --payment-token given, and no default payment method on file — " \
-                                          "run `portage payment enroll` or pass --payment-token.")
+          url = checkout_url_of(checkout)
+          return checkout_report(
+            source, products, checkout,
+            checkout_url: url, handoff: hand_off(checkout, reason: "no_payment_token", source: source),
+            message: "No --payment-token given, and no default payment method on file — run " \
+                     "`portage payment enroll` or pass --payment-token, or visit the link to " \
+                     "finish this checkout yourself."
+          )
         end
 
         completed = session.complete_checkout(checkout_id: checkout["id"], payment_token: @payment_token)
         checkout_report(source, products, completed, message: "Purchased.")
+      rescue Portage::Ucp::Client::PaymentPermissionError
+        permission_denied_report(source, products, checkout)
+      end
+
+      # Same posture as #escalation_report: a completion this agent isn't
+      # granted permission for is a normal outcome, not a failure — the
+      # shopper finishes on the merchant's own continue_url/checkout link,
+      # same hand-off requires_escalation already uses (see
+      # Client::PaymentPermissionError).
+      def permission_denied_report(source, products, checkout)
+        url = checkout_url_of(checkout)
+        checkout_report(
+          source, products, checkout,
+          checkout_url: url, handoff: hand_off(checkout, reason: "permission_denied", source: source),
+          message: "This agent isn't yet granted permission to complete checkout on this store — " \
+                   "visit the link to finish it yourself."
+        )
+      end
+
+      # Never fires on --dry-run (a dry run creates a real checkout but never
+      # attempts completion — auto-opening/notifying over a preview run would
+      # be actively wrong), and never fires without a checkout_url to hand
+      # off. Best-effort: a failed open or failed webhook POST never raises
+      # out of #call (see CheckoutHandoff, Notifier), so the checkout itself
+      # — created, or correctly escalated — stays the outcome of record
+      # either way.
+      def hand_off(checkout, reason:, source:)
+        url = checkout_url_of(checkout)
+        return nil if @dry_run || url.nil?
+
+        opened = CheckoutHandoff.new(auto_open: @auto_open).call(url)
+        error = notifier.call(event: "checkout_handoff", reason: reason, checkout_url: url,
+                              checkout_id: checkout["id"], source: source, totals: checkout["totals"])
+        { url: url, opened: opened, notified: notifier.enabled? && error.nil?, notify_error: error }
+      end
+
+      def notifier
+        @notifier ||= Notifier.new(webhook_url: @notify_webhook)
+      end
+
+      # Every checkout that can't be finished by this process — no
+      # permission, no token, or an explicit requires_escalation — hands the
+      # shopper a URL rather than leaving them at a dead end.
+      #
+      # `continue_url` first, because on a real store it is the only field
+      # that ever holds the checkout. This used to be
+      # `links.find { |l| l["url"] }` on the reasoning that not every
+      # backend's link entries name a type — but live UCP stores put nothing
+      # *except* policy links in `links`: five third-party Shopify stores
+      # checked 2026-09-22 returned `refund_policy`, `privacy_policy`,
+      # `terms_of_service`, `shipping_policy`, `contact_information` and
+      # nothing else, with the checkout at `continue_url` every time. So the
+      # old "first link with a url" handed the shopper a refund policy on
+      # every real store, `--auto-open` opened it, and `--notify-webhook`
+      # posted it.
+      #
+      # The `links` fallback stays for backends whose checkout genuinely
+      # lives there, but skips anything named as a policy or contact link:
+      # for a hand-off, no URL is a better answer than the wrong one, since
+      # the report and the message both then say there's nowhere to go
+      # instead of pointing somewhere useless.
+      def checkout_url_of(checkout)
+        checkout["continue_url"] || checkout_link_url(checkout)
+      end
+
+      def checkout_link_url(checkout)
+        Array(checkout["links"])
+          .reject { |l| l["type"].to_s.match?(POLICY_LINK_TYPES) }
+          .find { |l| l["url"] }&.fetch("url", nil)
       end
 
       def confirmed?
@@ -338,9 +467,12 @@ module Portage
       end
 
       def escalation_report(source, products, checkout)
-        checkout_report(source, products, checkout,
-                        checkout_url: checkout["links"]&.find { |l| l["url"] }&.fetch("url", nil),
-                        message: "Checkout requires buyer escalation — visit the link to complete it.")
+        url = checkout_url_of(checkout)
+        checkout_report(
+          source, products, checkout,
+          checkout_url: url, handoff: hand_off(checkout, reason: "requires_escalation", source: source),
+          message: "Checkout requires buyer escalation — visit the link to complete it."
+        )
       end
 
       def dry_run_report(source, products, checkout)
@@ -355,14 +487,22 @@ module Portage
       # wants to see (id/status/totals) onto the report, rather than nesting
       # the raw hash under a key that'd collide with the boolean `checkout:`
       # field the output struct already reserves (§ output shape).
-      def checkout_report(source, products, checkout, message:, checkout_url: nil)
+      def checkout_report(source, products, checkout, message:, checkout_url: nil, handoff: nil)
         build_report(source: source, browse: true, checkout: true, products: products, message: message,
                      checkout_url: checkout_url, checkout_id: checkout["id"], checkout_status: checkout["status"],
-                     totals: checkout["totals"])
+                     totals: checkout["totals"], handoff: handoff)
       end
 
       def safe_search(session)
-        CatalogProducts.from(session.search_catalog(query: @query, limit: 10, meta: agent_meta))
+        CatalogProducts.from(session.search_catalog(query: @query, limit: 10, context: buyer_context,
+                                                    meta: agent_meta))
+      end
+
+      # A real store resolves which market — and so which inventory and
+      # prices — a call is scoped to from this (see
+      # Portage::Cli::BuyerContext). The loopback/stdio transports drop it.
+      def buyer_context
+        @buyer_context ||= BuyerContext.from_env
       end
 
       # Real UCP servers fetch this URL to verify the caller's identity

data/lib/portage/cli/buyer_context.rb

@@ -0,0 +1,42 @@
+module Portage
+  module Cli
+    # Builds the UCP `context` object — the buyer locale hints a real store
+    # resolves a market from — out of the same `PORTAGE_SHIP_*` environment
+    # Portage::Cli::ShippingProfile reads, plus two of its own.
+    #
+    # Separate from ShippingProfile rather than a method on it because the two
+    # have opposite completeness rules. A shipping *address* is all-or-nothing:
+    # ShippingProfile returns nil unless every required field is set, since a
+    # half-filled address can't be submitted and this CLI never guesses at the
+    # missing half. A context is explicitly partial by design ("provisional
+    # context hints ... unsupported hints may be ignored without error"), and
+    # a country alone is enough to resolve a market, so sending what's known
+    # beats sending nothing.
+    #
+    # Sending nothing is the part that actually mattered: without a context,
+    # a live Shopify store builds a cart scoped to no market, drops every line
+    # item, and reports `merchandise_out_of_stock` for products its own
+    # `search_catalog` just returned as available (confirmed live 2026-09-22,
+    # see docs/ucp-tool-gating-investigation.md). So this returns `{}` rather
+    # than nil when nothing is configured — a caller passes it through either
+    # way, and `Transports::Http#with_context` omits an empty one from the
+    # wire.
+    module BuyerContext
+      ENV_VARS = {
+        address_country: "PORTAGE_SHIP_COUNTRY",
+        address_region: "PORTAGE_SHIP_REGION",
+        postal_code: "PORTAGE_SHIP_POSTAL_CODE",
+        currency: "PORTAGE_CURRENCY",
+        language: "PORTAGE_LANGUAGE"
+      }.freeze
+
+      # @return [Hash] context hints, empty when none are configured
+      def self.from_env
+        ENV_VARS.filter_map do |key, var|
+          value = ENV.fetch(var, nil)
+          [key, value] unless value.nil? || value.empty?
+        end.to_h
+      end
+    end
+  end
+end

data/lib/portage/cli/checkout_handoff.rb

@@ -0,0 +1,82 @@
+require "uri"
+require_relative "config"
+
+module Portage
+  module Cli
+    # Phase 1 of docs/plans/checkout-handoff-delivery.md — auto-opens a
+    # checkout_url in the shopper's browser when a `Buy` dead-end
+    # (escalation, permission denied, no payment token) hands off a link
+    # rather than completing the purchase itself.
+    #
+    # Default off. Precedence for the toggle (open decision #1, resolved):
+    # a per-invocation `auto_open:` override (portage buy --auto-open /
+    # --no-auto-open) beats PORTAGE_AUTO_OPEN_CHECKOUT, which beats
+    # ~/.portage/config.json's "auto_open_checkout" (Config).
+    #
+    # No new gem for the actual open — every other shell-out in this repo
+    # (PaymentMethods::KeychainBackend, SecretServiceBackend) hand-rolls
+    # `system` rather than pulling in launchy for something the OS already
+    # provides. `system(cmd, url)` (array form, never an interpolated
+    # string) so a merchant-controlled checkout_url can't inject into a
+    # shell.
+    class CheckoutHandoff
+      ENV_VAR = "PORTAGE_AUTO_OPEN_CHECKOUT".freeze
+      CONFIG_KEY = "auto_open_checkout".freeze
+      TRUE_VALUES = %w[1 true yes].freeze
+
+      def initialize(auto_open: nil, config: Config.load)
+        @override = auto_open
+        @config = config
+      end
+
+      def auto_open?
+        return @override unless @override.nil?
+
+        env = env_override
+        return env unless env.nil?
+
+        !!@config.get(CONFIG_KEY)
+      end
+
+      # @return [Boolean] whether the browser was actually opened.
+      def call(checkout_url)
+        return false unless auto_open? && https?(checkout_url)
+
+        open_browser(checkout_url)
+      end
+
+      private
+
+      def env_override
+        raw = ENV.fetch(ENV_VAR, nil)
+        return nil if raw.nil?
+
+        TRUE_VALUES.include?(raw.downcase)
+      end
+
+      def https?(url)
+        URI.parse(url).scheme == "https"
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def open_browser(url)
+        command = platform_command
+        return false unless command
+
+        !!system(command, url)
+      rescue StandardError => e
+        warn "portage: couldn't open #{url} (#{e.message})"
+        false
+      end
+
+      def platform_command
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/i then "open"
+        when /linux|bsd/i then "xdg-open"
+        when /mswin|mingw|cygwin/i then "start"
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/config.rb

@@ -0,0 +1,52 @@
+require "json"
+require "fileutils"
+
+module Portage
+  module Cli
+    # Durable, editable `portage-cli` config — `~/.portage/config.json` — for
+    # standing preferences that aren't payment/policy specific (the auto-open
+    # and notify-webhook toggles in docs/plans/checkout-handoff-delivery.md
+    # are the first two keys). Same shape as Portage::Ucp::Policy: absent
+    # file or absent key means "unset", a corrupt file raises rather than
+    # silently falling back.
+    class Config
+      PATH = File.join(Dir.home, ".portage", "config.json").freeze
+
+      def self.load(path: PATH) = new(path: path, data: read(path))
+
+      def initialize(path: PATH, data: {})
+        @path = path
+        @data = data
+      end
+
+      def get(key) = @data[key.to_s]
+
+      def set(key, value)
+        @data[key.to_s] = value
+        write
+        value
+      end
+
+      def to_h = @data.dup
+
+      def self.read(path)
+        return {} unless File.readable?(path)
+
+        raw = File.read(path)
+        return {} if raw.empty?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+      private_class_method :read
+
+      private
+
+      def write
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.write(@path, JSON.pretty_generate(@data))
+        File.chmod(0o600, @path)
+      end
+    end
+  end
+end

data/lib/portage/cli/find.rb

@@ -140,7 +140,8 @@ module Portage
 
       def offers_for(store)
         products = CatalogProducts.from(
-          store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS, meta: agent_meta)
+          store[:session].search_catalog(query: @query, limit: PER_STORE_RESULTS,
+                                         context: BuyerContext.from_env, meta: agent_meta)
         )
         products.filter_map { |product| offer(store, product) }
       rescue Portage::Ucp::Client::MissingAgentProfileError

data/lib/portage/cli/generate/agent_profile.rb

@@ -27,9 +27,15 @@ module Portage
       # Same-looking key material, structurally different document — not
       # interchangeable, so this doesn't subclass or reuse Manifest.
       #
-      # `Portage::Ucp::Manifest::UCP_VERSION` is reused as-is (not
-      # redeclared) so the two documents can never drift to different spec
-      # versions by accident.
+      # The version here is deliberately *not* reused from
+      # `Portage::Ucp::Manifest::UCP_VERSION`, unlike an earlier revision of
+      # this class. Those two versions answer different questions: the
+      # manifest's says which spec revision *this gem's own server* implements
+      # for the businesses it serves, while an agent profile's says which
+      # revision the agent speaks to *whichever remote store it dials*. A
+      # store on a newer rollout than our server-side support (Shopify's
+      # `2026-08-25` endpoints, today) negotiates against the profile, so
+      # pinning the profile to the server's revision under-declared us.
       #
       # Rotation is the future-proofing this exists for: re-running with
       # `rotate: true` keeps every key already published (so a request
@@ -38,10 +44,49 @@ module Portage
       # drops a key — retiring one is a deliberate, separate edit once
       # nothing signs with it any more.
       class AgentProfile
-        UCP_VERSION = Portage::Ucp::Manifest::UCP_VERSION
+        UCP_VERSION = "2026-08-25".freeze
+
+        SHOPPING_SERVICE = "dev.ucp.shopping".freeze
 
         Key = Struct.new(:kid, :jwk, :private_pem, keyword_init: true)
 
+        # The capability identifiers a real UCP server resolves an incoming
+        # agent's tool registry from. These are NOT
+        # `Portage::Ucp::Capabilities::{CATALOG,CART,...}.name`, which an
+        # earlier revision of this class reused, and that reuse is what broke
+        # every live tool call for a month (see
+        # docs/ucp-tool-gating-investigation.md):
+        #
+        # - Catalog is registered per *action*
+        #   (`dev.ucp.shopping.catalog.search`, `.catalog.lookup`), not as one
+        #   coarse `dev.ucp.shopping.catalog`. A profile declaring only the
+        #   coarse name resolves to zero catalog tools, and the server then
+        #   answers `search_catalog` with `-32602 Tool not found:
+        #   search_catalog` — despite `tools/list` having advertised it
+        #   seconds earlier, and with no hint that the profile is the reason.
+        #   `Portage::Ucp::Capabilities::CATALOG` keeps the coarse name
+        #   because that's the right shape for *our own* server's manifest,
+        #   where one Capability object owns all three actions; the two
+        #   registries simply don't line up, so this document spells its own
+        #   ids out rather than deriving them.
+        # - Cart/Checkout/Order are registered at the root name, so those do
+        #   match — spelled out here anyway, so the whole declared set reads
+        #   from one place.
+        # - Versions are spec revisions (`2026-08-25`), not the `"1"` that
+        #   `Capability#version` carries.
+        #
+        # Live-verified 2026-09-22 against `catalog.shopify.com/api/ucp/mcp`
+        # and two per-shop endpoints: the granular ids answer `search_catalog`
+        # with real products at the anonymous tier (no token, no allowlist),
+        # the coarse id answers `Tool not found` on the same connection.
+        CAPABILITY_IDS = %w[
+          dev.ucp.shopping.catalog.search
+          dev.ucp.shopping.catalog.lookup
+          dev.ucp.shopping.cart
+          dev.ucp.shopping.checkout
+          dev.ucp.shopping.order
+        ].freeze
+
         # @param out [String] path to write the public profile JSON document
         # @param key_out [String] path to write the new private key's PEM —
         #   caller's responsibility to keep this out of version control
@@ -83,14 +128,29 @@ module Portage
           {
             "ucp" => {
               "version" => UCP_VERSION,
-              "services" => {},
-              "capabilities" => {},
+              "services" => service_hash,
+              "capabilities" => capability_hash,
               "payment_handlers" => {}
             },
             "signing_keys" => signing_keys
           }
         end
 
+        # Was `{}`. A server negotiating capabilities intersects its own
+        # service list with the profile's, so an empty `services` declares an
+        # agent that speaks no service at all — same class of under-declaration
+        # as the coarse capability ids above.
+        def service_hash
+          { SHOPPING_SERVICE => [{ "version" => UCP_VERSION,
+                                   "spec" => "https://ucp.dev/#{UCP_VERSION}/specification/overview",
+                                   "transport" => "mcp",
+                                   "schema" => "https://ucp.dev/#{UCP_VERSION}/services/shopping/mcp.openrpc.json" }] }
+        end
+
+        def capability_hash
+          CAPABILITY_IDS.to_h { |id| [id, [{ "version" => UCP_VERSION }]] }
+        end
+
         def write_profile(doc)
           FileUtils.mkdir_p(File.dirname(@out))
           File.write(@out, "#{JSON.pretty_generate(doc)}\n")

data/lib/portage/cli/notifier.rb

@@ -0,0 +1,77 @@
+require "net/http"
+require_relative "config"
+
+module Portage
+  module Cli
+    # Phase 2 of docs/plans/checkout-handoff-delivery.md — POSTs a JSON body
+    # to a configured webhook when a `Buy` dead-end (escalation, permission
+    # denied, no payment token) hands off a checkout_url, so a caller can
+    # wire that into Slack/Zapier/their own relay. Same "the actual
+    # notification transport is the caller's job" posture as
+    # Portage::Ucp::Confirmer::Webhook's own comments — this class only ever
+    # speaks HTTP.
+    #
+    # Default off. Precedence for the webhook URL (open decision #1,
+    # resolved, same shape as CheckoutHandoff's auto-open toggle): a
+    # per-invocation `webhook_url:` override (portage buy --notify-webhook)
+    # beats PORTAGE_NOTIFY_WEBHOOK_URL, which beats ~/.portage/config.json's
+    # "notify_webhook_url" (Config).
+    class Notifier
+      include Portage::Ucp::Support::HttpClient
+
+      ENV_VAR = "PORTAGE_NOTIFY_WEBHOOK_URL".freeze
+      CONFIG_KEY = "notify_webhook_url".freeze
+
+      def initialize(webhook_url: nil, config: Config.load)
+        @override = webhook_url
+        @config = config
+      end
+
+      def webhook_url
+        return @override unless @override.nil?
+
+        env = ENV.fetch(ENV_VAR, nil)
+        return env unless env.nil? || env.empty?
+
+        @config.get(CONFIG_KEY)
+      end
+
+      def enabled? = !webhook_url.to_s.empty?
+
+      # Best-effort, matching CheckoutHandoff's posture: a failed POST never
+      # raises out of `Buy#call` — the checkout itself is a real, correct
+      # outcome independent of whether this delivery succeeded.
+      #
+      # @return [String, nil] the delivery failure message, or nil when
+      #   disabled or on a successful POST.
+      def call(payload)
+        return nil unless enabled?
+
+        json_request(Net::HTTP::Post, webhook_url, body: payload)
+        nil
+      rescue StandardError => e
+        e.message
+      end
+
+      private
+
+      def api_error_class
+        NotifyApiError
+      end
+
+      # Raised (internally, always rescued by #call) when the webhook POST
+      # itself fails (non-2xx) — kept distinct from a plain network error
+      # only in that it carries the response body/status, same split
+      # Confirmer::WebhookApiError draws against a raw StandardError.
+      class NotifyApiError < Portage::Ucp::Error
+        include Portage::Ucp::Support::ApiError
+
+        private
+
+        def api_label
+          "Notifier"
+        end
+      end
+    end
+  end
+end

data/lib/portage/cli/version.rb

@@ -1,5 +1,5 @@
 module Portage
   module Cli
-    VERSION = "0.6.0".freeze
+    VERSION = "0.6.4".freeze
   end
 end

data/lib/portage/cli.rb

@@ -3,6 +3,7 @@ require "json"
 
 require_relative "cli/version"
 require_relative "cli/shipping_profile"
+require_relative "cli/buyer_context"
 require_relative "cli/catalog_products"
 require_relative "cli/buy"
 require_relative "cli/find"
@@ -21,7 +22,8 @@ module Portage
   module Cli
     USAGE = <<~USAGE.freeze
       usage: portage buy <url> --query "..." [--qty N] [--payment-token TOKEN]
-                                [--product-id ID] [--yes] [--dry-run] [--json]
+                                [--product-id ID] [--yes] [--dry-run]
+                                [--auto-open|--no-auto-open] [--notify-webhook URL] [--json]
              portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
              portage find --query "..." [--max-price N] [--limit N] [--json]
              portage compare <url> --product-id ID [--id VALUE ...] [--results N]
@@ -232,6 +234,8 @@ module Portage
         parser.on("--product-id ID") { |v| buy[:product_id] = v }
         parser.on("--yes") { buy[:yes] = true }
         parser.on("--dry-run") { buy[:dry_run] = true }
+        parser.on("--[no-]auto-open") { |v| buy[:auto_open] = v }
+        parser.on("--notify-webhook URL") { |v| buy[:notify_webhook] = v }
         parser.on("--json") { parsed[:json] = true }
         add_search_options(parser, buy, parsed)
       end
@@ -604,10 +608,18 @@ module Portage
       lines = ["#{report[:message]} (source: #{report[:source]})"]
       report[:products].each { |p| lines << "  - #{product_line(p)}" }
       lines << "  checkout: #{report[:checkout_url]}" if report[:checkout_url]
+      lines.concat(format_handoff(report[:handoff])) if report[:handoff]
       lines.join("\n")
     end
     private_class_method :format_report
 
+    def self.format_handoff(handoff)
+      lines = ["  opened in browser: #{handoff[:opened]}", "  notified: #{handoff[:notified]}"]
+      lines << "  notify error: #{handoff[:notify_error]}" if handoff[:notify_error]
+      lines
+    end
+    private_class_method :format_handoff
+
     def self.product_line(product)
       product.respond_to?(:title) ? "#{product.id}: #{product.title}" : "#{product['id']}: #{product['title']}"
     end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: portage-cli
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.4
 platform: ruby
 authors:
 - Tom Whitbread
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: portage-ucp
@@ -29,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: portage-ucp-journal
   requirement: !ruby/object:Gem::Requirement
@@ -119,6 +120,7 @@ description: 'Ships the `portage` executable. `portage buy <url>` tries native U
   portage-ucp-client (for the actual buy calls), and portage-ucp-journal (for `portage-console`''s
   read-only view of local purchase/transaction/order state); no single adapter gem
   is a hard dependency.'
+email:
 executables:
 - portage
 - portage-console
@@ -132,14 +134,18 @@ files:
 - exe/portage-console
 - lib/portage/cli.rb
 - lib/portage/cli/buy.rb
+- lib/portage/cli/buyer_context.rb
 - lib/portage/cli/catalog_products.rb
+- lib/portage/cli/checkout_handoff.rb
 - lib/portage/cli/compare.rb
+- lib/portage/cli/config.rb
 - lib/portage/cli/console.rb
 - lib/portage/cli/doctor.rb
 - lib/portage/cli/find.rb
 - lib/portage/cli/generate/adapter.rb
 - lib/portage/cli/generate/agent_profile.rb
 - lib/portage/cli/history.rb
+- lib/portage/cli/notifier.rb
 - lib/portage/cli/payment_methods.rb
 - lib/portage/cli/payment_methods/env_backend.rb
 - lib/portage/cli/payment_methods/keychain_backend.rb
@@ -155,6 +161,7 @@ metadata:
   source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-cli
   changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-cli/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -169,7 +176,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: portage — one CLI command to buy from any store, native UCP or not
 test_files: []