feat(commerce): verification_agent_instructions accepts retry_step override (parity with node)

Mirror of node-commerce 1a0f8fe. retry_step REPLACES the canonical
"Retry the original merchant request..." step instead of appending via
extra_steps — eliminates the duplicate retry instruction when vendors need
merchant-specific retry mechanics (e.g. martin-estate's order_id resume).

extra_steps remains for genuinely additional steps that come AFTER retry.

Tests cover both cases: retry_step replaces (no duplicate canonical retry),
retry_step + extra_steps compose correctly.

485 → 487 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

agentscore_commerce/identity/_denial.py

@@ -136,6 +136,7 @@ def build_contact_support_next_steps(support_email: str, message: str | None = N
 def verification_agent_instructions(
     *,
     user_action: str | None = None,
+    retry_step: str | None = None,
     extra_steps: list[str] | None = None,
     poll_interval_seconds: int = 5,
     timeout_seconds: int = 3600,
@@ -147,6 +148,12 @@ def verification_agent_instructions(
     Tells the agent how to present verify_url, poll for the operator_token, and retry the
     original request. Universal across every AgentScore-gated merchant — overrides let vendors
     add merchant-specific steps.
+
+    ``retry_step`` REPLACES the generic "Retry the original merchant request..." step with a
+    merchant-specific one (e.g. "Retry POST /purchase with X-Operator-Token AND include
+    order_id..."). Use it when your retry instruction is a refinement of the canonical retry,
+    not an additional step. ``extra_steps`` is for genuinely additional steps that come AFTER
+    the retry (e.g. "After payment the same call returns 200").
     """
     base_steps = [
         "Present the verify_url directly to the user — it is a complete, ready-to-open URL with the session "
@@ -158,7 +165,8 @@ def verification_agent_instructions(
         "and closes the tab. They do NOT need to copy or paste anything back to you.",
         'When your poll returns status "verified", extract operator_token from the response. This is a one-time '
         'value — save it immediately. Subsequent polls return status "consumed" without the token.',
-        "Retry the original merchant request with header X-Operator-Token set to the operator_token value.",
+        retry_step
+        or "Retry the original merchant request with header X-Operator-Token set to the operator_token value.",
     ]
     out: dict[str, Any] = {
         "action": "poll_for_credential",

tests/test_denial.py

@@ -142,3 +142,20 @@ def test_extra_steps_and_order_ttl_and_extras(self):
         assert inst["steps"][-1] == "Resume by including order_id in the retry body."
         assert "1 hour" in inst["order_ttl"]
         assert inst["vendor_field"] == "value"
+
+    def test_retry_step_replaces_canonical_step(self):
+        custom = "Retry POST /purchase with X-Operator-Token AND include order_id from this response."
+        inst = verification_agent_instructions(retry_step=custom)
+        assert inst["steps"][4] == custom
+        canonical = "Retry the original merchant request with header X-Operator-Token set to the operator_token value."
+        assert canonical not in inst["steps"]
+
+    def test_retry_step_and_extra_steps_compose(self):
+        inst = verification_agent_instructions(
+            retry_step="Custom retry.",
+            extra_steps=["Then do X.", "Then do Y."],
+        )
+        assert len(inst["steps"]) == 7
+        assert inst["steps"][4] == "Custom retry."
+        assert inst["steps"][5] == "Then do X."
+        assert inst["steps"][6] == "Then do Y."