@itpay/cli 0.2.12 → 0.2.14

package/README.md

@@ -85,7 +85,7 @@ Non-interactive agent hosts such as Codex automatically use file storage to
 avoid OS keychain prompts. To force file storage anywhere:
 
 ```bash
-ITP_CREDENTIAL_STORE=file itp buyer auth status --json
+ITP_CREDENTIAL_STORE=file itp buyer auth status --host <client> --json
 ```
 
 If native credential storage is unavailable, the CLI falls back to:
@@ -101,7 +101,7 @@ The fallback file is written with `0600` permissions.
 After a buyer has completed first-purchase auth and the CLI has a buyer account session, an agent can create a one-time link for the human to view the ItPay account/order portal:
 
 ```bash
-itp account login-link --json
+itp account login-link --host <client> --json
 ```
 
 The agent should give the returned `login_url` to the human and must not open or scrape it. The portal shows the same redacted order/vault state available through buyer APIs; raw artifact reveal remains a separate human Passkey/WebAuthn flow.
@@ -155,9 +155,15 @@ from the current state.
 Before starting a new purchase, agents should inspect recoverable local state:
 
 ```bash
-itp status --refresh --json
+itp status --refresh --host <client> --json
 ```
 
+Every non-doc command needs a client context. Use `--host codex`,
+`--host claude-code`, `--host terminal`, or `--host plain-chat`. For OpenClaw
+Telegram private/group chat, use `--host telegram --target <inbound_meta.chat_id>`.
+If the CLI returns `client_context_required` or `client_target_required`, rerun
+the same command with the requested fields.
+
 Humans can use the default account overview:
 
 ```bash
@@ -174,7 +180,7 @@ Device:   Codex on MacBook-Pro (active)
 If an unfinished run exists, continue it:
 
 ```bash
-itp resume --run-id <run_id> --json
+itp resume --run-id <run_id> --host <client> --json
 ```
 
 ## Install From This Repo
@@ -211,26 +217,26 @@ show the human QR/payment entry, wait for verified payment, and report only
 redacted secure delivery status:
 
 ```bash
-itp buyer catalog search --query 企业工商 --json
-itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=阿里 --json
-itp buyer checkout create --cart <cart_id> --email <buyer_email> --json
-itp buyer payment wait <payment_intent_id> --timeout 1 --json
-itp buyer checkout status <checkout_id> --json
+itp buyer catalog search --query 企业工商 --host <client> --json
+itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=阿里 --host <client> --json
+itp buyer checkout create --cart <cart_id> --email <buyer_email> --host <client> --json
+itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json
+itp buyer checkout status <checkout_id> --host <client> --json
 ```
 
 For the one-command buyer helper:
 
 ```bash
-itp buy var_itpay_enterprise_fuzzy_search_cny01 --email <buyer_email> --input company_name=阿里 --display agent --no-wait-payment --json
+itp buy var_itpay_enterprise_fuzzy_search_cny01 --email <buyer_email> --input company_name=阿里 --display agent --no-wait-payment --host <client> --json
 ```
 
 For multi-item cart tests:
 
 ```bash
-itp buyer cart create --variants var_itpay_enterprise_precise_lookup_cny05,var_itpay_enterprise_fuzzy_search_cny01 --quantities 1,1 --json
-itp buyer cart show <cart_id> --json
-itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --quantity 1 --json
-itp buyer cart remove <cart_id> --line <cart_line_item_id> --json
+itp buyer cart create --variants var_itpay_enterprise_precise_lookup_cny05,var_itpay_enterprise_fuzzy_search_cny01 --quantities 1,1 --host <client> --json
+itp buyer cart show <cart_id> --host <client> --json
+itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --quantity 1 --host <client> --json
+itp buyer cart remove <cart_id> --line <cart_line_item_id> --host <client> --json
 ```
 
 Payment QR rules:
@@ -239,9 +245,9 @@ Payment QR rules:
 - Otherwise render the ItPay-hosted `qr_png_url` / `preferred_qr_url`.
 - Use `mobile_wallet_url` only as a human mobile fallback.
 - Do not generate your own QR from payment URLs.
-- In OpenClaw Telegram, use root `agent_instruction.openclaw_message.command_args` with `openclaw message send`; do not simulate buttons in normal prose.
+- In OpenClaw Telegram, run root `agent_action.command` or `agent_action.argv` before replying; do not simulate buttons in normal prose.
 - Telegram native buttons require `presentation.blocks[].type="buttons"` with `text/url/callback_data`.
-- If `human_output_required=true` appears for another client, send root `human_output` before any next ItPay command.
+- For Codex/Claude Code, send root `agent_instruction.markdown` before any next ItPay command.
 - If status is `payment_handoff_required`, `next` is the human reply step, not payment wait.
 - Treat only `payment_intent.verified` as payment success.
 
@@ -250,9 +256,9 @@ the artifact in the ItPay account portal with Passkey and choose "Give to
 Agent". The agent then discovers the approved grant itself:
 
 ```bash
-itp buyer vault grants list --checkout <checkout_id> --json
-itp buyer vault grants read <agent_read_grant_id> --json
-itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json
+itp buyer vault grants list --checkout <checkout_id> --host <client> --json
+itp buyer vault grants read <agent_read_grant_id> --host <client> --json
+itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --host <client> --json
 ```
 
 Agents must not ask humans to paste claim links, claim tokens, raw API results,
@@ -262,7 +268,7 @@ Order/account/refund commands require a server-verified buyer session, not a
 vault grant. If they fail with a buyer session error, run:
 
 ```bash
-itp status --refresh --json
+itp status --refresh --host <client> --json
 ```
 
 Then follow the returned `next.command`.

package/bin/itp

@@ -4,6 +4,7 @@ import { output, outputError, parseFlags, readState, VERSION } from "../lib/env.
 import { docs, skill } from "../lib/docs.js";
 import { ops, admin } from "../lib/ops.js";
 import { buyer, buyerBuy } from "../lib/buyer.js";
+import { clientContextGate } from "../lib/client-context.js";
 import {
   accountLoginLink, accountSetPassword, accountShow, agentStatus, authDevice, authLogin, authRegister, authStatus, balance,
   checkoutCreate, checkoutList, checkoutOpen, checkoutQR, checkoutRecover, doctor, grantsInstall, grantsList, grantsRevoke,
@@ -23,6 +24,11 @@ async function main() {
   }
 
   const [group, command, ...rest] = args;
+  const contextGate = clientContextGate(args);
+  if (contextGate) {
+    output(contextGate);
+    return;
+  }
   const flags = parseFlags(rest);
 
   if (group === "usage") return usage(parseFlags(args.slice(1)));
@@ -93,41 +99,41 @@ async function main() {
       output({
         version: VERSION,
         commands: [
-          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --phone +8613800000000 --display agent --no-wait-payment --json",
-          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --phone +8613800000000 --no-wait --json",
-          "buyer catalog search --query 企业工商 --category business_data_api --provider itpay_enterprise_data --json",
-          "buyer catalog get --variant var_pubg_couple_skin_cny20 --json",
-          "buyer cart create --variant var_pubg_couple_skin_cny20 --json",
-          "buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --json",
-          "buyer cart show <cart_id> --json",
-          "buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --quantity 1 --json",
-          "buyer cart remove <cart_id> --line <cart_line_item_id> --json",
-          "buyer shelf manifest --json",
-          "buyer shelf snapshot --version <catalog_version> --json",
-          "buyer shelf delta --since <catalog_version> --json",
-          "buyer checkout create --cart <cart_id> --method alipay --email <buyer_email> --phone +8613800000000 --json",
-          "buyer checkout status <checkout_id> --json",
-          "buyer checkout resume <checkout_id> --json",
-          "buyer auth status --json",
-          "buyer payment wait <payment_intent_id> --timeout 1 --json",
-          "buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
-          "buyer deliveries list --checkout <checkout_id> --json",
-          "buyer deliveries show <delivery_id> --checkout <checkout_id> --json",
-          "buyer refund create --order <order_id> --amount-minor 1000 --currency CNY --reason buyer_requested --json",
-          "buyer refund list --order <order_id> --json",
-          "buyer refund show <refund_id> --json",
-          "buyer refund cancel <refund_id> --reason buyer_changed_mind --json",
-          "buyer vault grants list --checkout <checkout_id> --json",
-          "buyer vault grants read <agent_read_grant_id> --json",
-          "buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
-          "account login-link --json",
-          "status --json",
-          "status --refresh --json",
+          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --phone +8613800000000 --display agent --no-wait-payment --host <client> --json",
+          "buy var_pubg_couple_skin_cny20 --email <buyer_email> --phone +8613800000000 --no-wait --host <client> --json",
+          "buyer catalog search --query 企业工商 --category business_data_api --provider itpay_enterprise_data --host <client> --json",
+          "buyer catalog get --variant var_pubg_couple_skin_cny20 --host <client> --json",
+          "buyer cart create --variant var_pubg_couple_skin_cny20 --host <client> --json",
+          "buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --host <client> --json",
+          "buyer cart show <cart_id> --host <client> --json",
+          "buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --quantity 1 --host <client> --json",
+          "buyer cart remove <cart_id> --line <cart_line_item_id> --host <client> --json",
+          "buyer shelf manifest --host <client> --json",
+          "buyer shelf snapshot --version <catalog_version> --host <client> --json",
+          "buyer shelf delta --since <catalog_version> --host <client> --json",
+          "buyer checkout create --cart <cart_id> --method alipay --email <buyer_email> --phone +8613800000000 --host <client> --json",
+          "buyer checkout status <checkout_id> --host <client> --json",
+          "buyer checkout resume <checkout_id> --host <client> --json",
+          "buyer auth status --host <client> --json",
+          "buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json",
+          "buyer payment refresh-qr <payment_intent_id> --reason order-not-found --host <client> --json",
+          "buyer deliveries list --checkout <checkout_id> --host <client> --json",
+          "buyer deliveries show <delivery_id> --checkout <checkout_id> --host <client> --json",
+          "buyer refund create --order <order_id> --amount-minor 1000 --currency CNY --reason buyer_requested --host <client> --json",
+          "buyer refund list --order <order_id> --host <client> --json",
+          "buyer refund show <refund_id> --host <client> --json",
+          "buyer refund cancel <refund_id> --reason buyer_changed_mind --host <client> --json",
+          "buyer vault grants list --checkout <checkout_id> --host <client> --json",
+          "buyer vault grants read <agent_read_grant_id> --host <client> --json",
+          "buyer vault read --order <order_id> --artifact <vault_artifact_id> --host <client> --json",
+          "account login-link --host <client> --json",
+          "status --host <client> --json",
+          "status --refresh --host <client> --json",
           "docs list --role buyer --json",
           "docs show quickstart --role buyer --json",
           "docs search <question> --role buyer --json",
-          "resume --json",
-          "resume --run-id <run_id> --host gemini --display none --json",
+          "resume --host <client> --json",
+          "resume --run-id <run_id> --host codex --display none --json",
           "runs list|current|show <run_id>|forget <run_id>",
           "account login-link",
           "skill show",

package/docs/agent/buyer/account-portal.json

@@ -10,23 +10,29 @@
     "The agent needs to explain that human UI and agent status share the same redacted order state."
   ],
   "required_state": {
-    "needs": ["authenticated buyer account session"],
-    "must_not_need": ["claim token", "raw content", "portal page contents"]
+    "needs": [
+      "authenticated buyer account session"
+    ],
+    "must_not_need": [
+      "claim token",
+      "raw content",
+      "portal page contents"
+    ]
   },
   "commands": [
     {
       "intent": "create a one-time human account portal link",
-      "command": "itp account login-link --json",
+      "command": "itp account login-link --host <client> --json",
       "success_signal": "response.status == account_portal_login_link_created and response.portal_login_link.one_time == true"
     },
     {
       "intent": "same command under buyer namespace",
-      "command": "itp buyer account login-link --json",
+      "command": "itp buyer account login-link --host <client> --json",
       "success_signal": "response.login_url is present"
     },
     {
       "intent": "agent-side state check without opening the human portal",
-      "command": "itp buyer checkout status <checkout_id> --json",
+      "command": "itp buyer checkout status <checkout_id> --host <client> --json",
       "success_signal": "response contains redacted order/delivery state only"
     }
   ],
@@ -61,5 +67,15 @@
       "command": "itp docs show safety-policy --role buyer --json"
     }
   ],
-  "search_terms": ["account portal", "orders", "login link", "one time link", "portal", "账号", "订单", "登录链接", "一次性链接"]
+  "search_terms": [
+    "account portal",
+    "orders",
+    "login link",
+    "one time link",
+    "portal",
+    "账号",
+    "订单",
+    "登录链接",
+    "一次性链接"
+  ]
 }

package/docs/agent/buyer/cart-checkout.json

@@ -28,47 +28,47 @@
   "commands": [
     {
       "intent": "create a cart estimate for the selected purchase option",
-      "command": "itp buyer cart create --variant <variant_id> --json",
+      "command": "itp buyer cart create --variant <variant_id> --host <client> --json",
       "success_signal": "response.cart.cart_id is present and response.cart_guidance tells the agent to show the cart to the human before checkout"
     },
     {
       "intent": "create a multi-item cart estimate for selected purchase options",
-      "command": "itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,2 --json",
+      "command": "itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,2 --host <client> --json",
       "success_signal": "response.cart.line_items contains every selected purchase option and response.cart_guidance.double_check_required is true"
     },
     {
       "intent": "create an enterprise fuzzy search cart with required query input",
-      "command": "itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --json",
+      "command": "itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --host <client> --json",
       "success_signal": "response.cart.cart_id is present; the raw provider result is not visible to the agent"
     },
     {
       "intent": "create an enterprise precise lookup cart with exact registered name or credit code",
-      "command": "itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --json",
+      "command": "itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --host <client> --json",
       "success_signal": "response.cart.cart_id is present; payment can proceed only after the exact query input is locked into the cart line"
     },
     {
       "intent": "view the current cart state without relying on model memory",
-      "command": "itp buyer cart show <cart_id> --json",
+      "command": "itp buyer cart show <cart_id> --host <client> --json",
       "success_signal": "response.cart.line_items and response.cart.totals reflect the server-side cart; show these fields to the human before checkout"
     },
     {
       "intent": "add one more selected UCP Variant.id to an existing cart before checkout",
-      "command": "itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --json",
+      "command": "itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --host <client> --json",
       "success_signal": "response.cart.cart_id is unchanged; response.cart.line_items either includes a new line for different input/settings or increments quantity for an identical line"
     },
     {
       "intent": "remove one line from an existing cart before checkout",
-      "command": "itp buyer cart remove <cart_id> --line <cart_line_item_id> --json",
+      "command": "itp buyer cart remove <cart_id> --line <cart_line_item_id> --host <client> --json",
       "success_signal": "response.cart.cart_id is unchanged and response.cart.line_items no longer contains that line id"
     },
     {
       "intent": "create checkout from cart_id",
-      "command": "itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --json",
+      "command": "itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --host <client> --json",
       "success_signal": "response.checkout.checkout_id is present; if response.checkout.next_required_action is auth_qr, show response.checkout.human_action and poll/resume until payment_intent_id appears"
     },
     {
       "intent": "do both steps through the high-level command",
-      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
+      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --host <client> --json",
       "success_signal": "response.status is waiting_human_auth, payment_handoff_required, payment_verified, or delivery_claimable"
     }
   ],

package/docs/agent/buyer/catalog-search.json

@@ -10,33 +10,39 @@
     "The agent needs to search standardized API products such as ItPay enterprise data APIs."
   ],
   "required_state": {
-    "needs": ["search query or service intent"],
-    "must_not_need": ["buyer login", "payment intent", "ops token"]
+    "needs": [
+      "search query or service intent"
+    ],
+    "must_not_need": [
+      "buyer login",
+      "payment intent",
+      "ops token"
+    ]
   },
   "commands": [
     {
       "intent": "inspect the service shelf before guessing keywords or facets",
-      "command": "itp buyer shelf manifest --json",
+      "command": "itp buyer shelf manifest --host <client> --json",
       "success_signal": "response.snapshot_version and response.snapshot_url are present; use snapshot/delta when the agent needs a shopping-list view of available services"
     },
     {
       "intent": "search public catalog by natural language query",
-      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --json",
+      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --host <client> --json",
       "success_signal": "response.products contains services with purchase options, id, title, price, metadata, and response.catalog_guidance explains how to choose safely"
     },
     {
       "intent": "search API services by stable category and safe facets",
-      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --delivery-mode managed_capability --use-case company_lookup --input-facet company_name --json",
+      "command": "itp buyer catalog search --query \"企业工商信息 查询\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --delivery-mode managed_capability --use-case company_lookup --input-facet company_name --host <client> --json",
       "success_signal": "response.products only contains products matching the requested category/facets"
     },
     {
       "intent": "search fuzzy company lookup when the user only provides a partial company name",
-      "command": "itp buyer catalog search --query \"企业 模糊 查询 公司简称\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --use-case company_disambiguation --input-facet company_name --json",
+      "command": "itp buyer catalog search --query \"企业 模糊 查询 公司简称\" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --use-case company_disambiguation --input-facet company_name --host <client> --json",
       "success_signal": "response.products includes the fuzzy enterprise search product before precise lookup"
     },
     {
       "intent": "get exact service details for a selected purchase option",
-      "command": "itp buyer catalog get --variant <variant_id> --json",
+      "command": "itp buyer catalog get --variant <variant_id> --host <client> --json",
       "success_signal": "response.selection.catalog_variant_id matches the selected purchase option and response.catalog_guidance says to explain before cart creation"
     }
   ],
@@ -75,5 +81,26 @@
       "command": "itp docs show cart-checkout --role buyer --json"
     }
   ],
-  "search_terms": ["catalog", "search", "shelf", "product", "variant", "purchase option", "api", "enterprise_data", "category", "facet", "business_data_api", "企业查询", "工商信息", "企业工商数据精准查询", "企业工商数据模糊查询", "搜索", "商品", "服务目录", "目录清单", "购买选项"]
+  "search_terms": [
+    "catalog",
+    "search",
+    "shelf",
+    "product",
+    "variant",
+    "purchase option",
+    "api",
+    "enterprise_data",
+    "category",
+    "facet",
+    "business_data_api",
+    "企业查询",
+    "工商信息",
+    "企业工商数据精准查询",
+    "企业工商数据模糊查询",
+    "搜索",
+    "商品",
+    "服务目录",
+    "目录清单",
+    "购买选项"
+  ]
 }

package/docs/agent/buyer/human-claim-ui.json

@@ -10,18 +10,23 @@
     "The delivery status says claim_link_sent or check_email."
   ],
   "required_state": {
-    "needs": ["delivery status or human email"],
-    "must_not_need": ["claim token in agent context", "raw content in CLI output"]
+    "needs": [
+      "delivery status or human email"
+    ],
+    "must_not_need": [
+      "claim token in agent context",
+      "raw content in CLI output"
+    ]
   },
   "commands": [
     {
       "intent": "show agent-safe delivery status only",
-      "command": "itp buyer deliveries list --checkout <checkout_id> --json",
+      "command": "itp buyer deliveries list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.secrets.raw_content_included == false"
     },
     {
       "intent": "check whether the human has granted this agent a scoped view",
-      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --host <client> --json",
       "success_signal": "count > 0 means the human approved agent-readable access for this exact agent device"
     }
   ],
@@ -32,7 +37,7 @@
     "If the human wants the agent to analyze or use the delivered result, ask them to click 'Give to Agent / 一键给 Agent' in the ItPay page and confirm with Passkey.",
     "Use clear user guidance: open the ItPay email or order/claim page, find 'Give to Agent / 一键给 Agent', select the fields the agent may read, then confirm with Passkey/WebAuthn.",
     "Tell the user they do not need to copy claim links, tokens, portal text, grant ids, or raw results into chat. The agent will discover the grant with CLI after approval.",
-    "After the human grants access, the agent should discover the grant with `itp buyer vault grants list --checkout <checkout_id> --json`; do not ask the human to paste the grant id. The CLI restores the buyer agent session from the checkout auth handoff when possible.",
+    "After the human grants access, the agent should discover the grant with `itp buyer vault grants list --checkout <checkout_id> --host <client> --json`; do not ask the human to paste the grant id. The CLI restores the buyer agent session from the checkout auth handoff when possible.",
     "If `buyer vault grants list` returns buyer_session.status=buyer_session_saved, the agent should proceed with the returned grant list; the saved session is intentionally not printed.",
     "If the human later wants the agent to install or use something, wait for an explicit human-granted install/capability flow."
   ],
@@ -59,5 +64,14 @@
       "command": "itp docs show safety-policy --role buyer --json"
     }
   ],
-  "search_terms": ["claim ui", "claim page", "human", "single use", "reveal", "领取页", "人类", "查看密钥"]
+  "search_terms": [
+    "claim ui",
+    "claim page",
+    "human",
+    "single use",
+    "reveal",
+    "领取页",
+    "人类",
+    "查看密钥"
+  ]
 }

package/docs/agent/buyer/payment-qr.json

@@ -25,29 +25,33 @@
   "commands": [
     {
       "intent": "create payment intent through the high-level buy flow",
-      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status is payment_handoff_required; for OpenClaw Telegram, send response.agent_instruction.openclaw_message.command_args with openclaw message send before any status check"
+      "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --host <client> --json",
+      "success_signal": "response.status is payment_handoff_required; for OpenClaw Telegram, execute response.agent_action.command or response.agent_action.argv before any normal reply or status check"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
-      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --display agent --json",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --display agent --host <client> --json",
       "success_signal": "response.payment_intent.human_action.local_qr_path or response.payment_intent.qr_png_url is present and status is still waiting_user_payment or verified"
     }
   ],
   "agent_rules": [
+    "Every non-doc ItPay command must include current client context. Use --host codex/claude-code/terminal/plain-chat, or for OpenClaw Telegram use --host telegram --target <inbound_meta.chat_id>.",
+    "If ItPay returns client_context_required or client_target_required, rerun the same command with the requested --host/--target before doing anything else.",
     "If human_action.kind is auth_qr, present the ItPay first-purchase entry URL/QR and explain it starts account login/registration/profile authorization and should continue to payment for the same checkout after approval.",
     "For auth_qr, the ItPay auth entry is the primary handoff. oauth_start_url is fallback/debug and should not replace the ItPay orchestration page.",
     "For auth_qr, do not call payment-intent creation directly or create a new checkout; poll checkout or run buyer checkout resume until payment_intent_id appears.",
     "Payment QR display requires both a valid/saved buyer session and payment_intent_id. If payment_intent_id appears before buyer_session is saved, run buyer checkout resume/status instead of showing payment QR.",
     "Do not stop after showing auth_qr unless the human explicitly asks you to pause. Keep waiting/resuming the same checkout so the post-auth payment handoff can continue.",
     "Do not describe auth_qr as payment success or payment proof. Only payment_intent.verified proves payment.",
-    "In OpenClaw Telegram, if response.agent_instruction is present, it is the mandatory execution path. Use response.agent_instruction.openclaw_message.command_args with openclaw message send before any next ItPay command.",
-    "Do not rewrite response.agent_instruction.openclaw_message into a custom table. Use its message, media, and presentation as provided.",
+    "If response.agent_action is present, it is the mandatory execution path. Execute response.agent_action.command or response.agent_action.argv before any normal prose reply or next ItPay command.",
+    "In OpenClaw Telegram, response.agent_action is already the exact openclaw message send command. Do not rebuild it, do not summarize it, and do not rewrite it into a custom table.",
+    "If response.agent_action cannot be executed, stop and tell the human this agent lacks OpenClaw native message-send capability. Do not fall back to Markdown.",
+    "response.agent_instruction is natural-language reinforcement for the agent; it does not replace response.agent_action.",
     "Telegram native buttons require openclaw message send --presentation; presentation.blocks[].type=\"buttons\" uses native text/url/callback_data. Do not simulate buttons in normal prose.",
-    "If agent_instruction or human_output links/buttons include URLs, include the real URL. Do not only show the link label.",
-    "In Codex or Claude Code app clients, send response.human_output.markdown first. Do not start a hidden long wait before the human-visible message is sent.",
+    "If agent_instruction links/buttons include URLs, include the real URL. Do not only show the link label.",
+    "In Codex or Claude Code app clients, send response.agent_instruction.markdown first. Do not start a hidden long wait before the human-visible message is sent.",
     "For Telegram-style message clients, send photo media first, include links, and expose native buttons for refresh/status when the adapter supports them.",
-    "For plain chat clients, show response.human_visible_markdown and stop unless the human asks you to check status or returns with a payment question.",
+    "For plain chat clients, show response.agent_instruction.message/links and stop unless the human asks you to check status or returns with a payment question.",
     "When response.status is payment_handoff_required, response.next is the human reply step, not payment wait.",
     "MUST show local_qr_path first when present. Many agent clients do not reliably render remote QR images; local_qr_path is the most reliable desktop/chat display artifact.",
     "If local_qr_path is not present, show qr_png_url or preferred_qr_url as the primary scannable QR. This is an ItPay-hosted human QR image; it may render the native provider payment code for scanner reliability, but the agent must not request or decode the raw provider payload.",

package/docs/agent/buyer/payment-wait.json

@@ -25,17 +25,18 @@
   "commands": [
     {
       "intent": "wait for payment verified event",
-      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json",
       "success_signal": "response.payment_event.event_type is payment_intent.verified or wait.timeout"
     },
     {
       "intent": "resume checkout after verified event",
-      "command": "itp buyer checkout status <checkout_id> --json",
+      "command": "itp buyer checkout status <checkout_id> --host <client> --json",
       "success_signal": "response.delivery.status or response.checkout.status is returned"
     }
   ],
   "agent_rules": [
-    "If payment wait returns payment_handoff_required with response.agent_instruction, send response.agent_instruction.openclaw_message.command_args before running any later status check.",
+    "Every payment wait/status command must include the same client context as the handoff command. For OpenClaw Telegram, keep --host telegram --target <same chat_id>.",
+    "If payment wait returns payment_handoff_required with response.agent_action, execute response.agent_action.command or response.agent_action.argv before any later status check. If only response.agent_instruction is present, follow it exactly before any later status check.",
     "Start payment status checks only after the QR image/link has already been sent to the human or the human asks to check status.",
     "If you run payment wait without a short timeout while payment is still pending, CLI returns payment_handoff_required and the human handoff instruction instead of long-polling.",
     "Payment wait/status check is a recovery loop around the same payment_intent_id, not a one-shot command.",

package/docs/agent/buyer/product-recommendation.json

@@ -22,7 +22,7 @@
   "commands": [
     {
       "intent": "refresh exact product detail before recommendation",
-      "command": "itp buyer catalog get --variant <variant_id> --json",
+      "command": "itp buyer catalog get --variant <variant_id> --host <client> --json",
       "success_signal": "response.product.variants includes current price and availability"
     }
   ],

package/docs/agent/buyer/qr-refresh.json

@@ -10,18 +10,24 @@
     "The payment intent is still not verified."
   ],
   "required_state": {
-    "needs": ["payment_intent_id"],
-    "must_not_need": ["ops token", "provider query", "new checkout"]
+    "needs": [
+      "payment_intent_id"
+    ],
+    "must_not_need": [
+      "ops token",
+      "provider query",
+      "new checkout"
+    ]
   },
   "commands": [
     {
       "intent": "ask ItPay for same-intent display recovery",
-      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --host <client> --json",
       "success_signal": "response.payment_intent.qr_png_url or response.payment_intent.qr_image_url is present"
     },
     {
       "intent": "continue waiting after refresh",
-      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json",
       "success_signal": "payment_event.event_type == payment_intent.verified"
     }
   ],
@@ -50,5 +56,12 @@
       "command": "itp docs show recovery --role buyer --json"
     }
   ],
-  "search_terms": ["refresh", "order not found", "expired qr", "qr unavailable", "刷新", "订单不存在"]
+  "search_terms": [
+    "refresh",
+    "order not found",
+    "expired qr",
+    "qr unavailable",
+    "刷新",
+    "订单不存在"
+  ]
 }