@itpay/cli 0.2.6 → 0.2.8

package/README.md

@@ -239,7 +239,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 agent app clients, send `human_visible_markdown` or the relevant `render_plan` output to the human first.
+- In agent app clients, execute `render_plan.selected` first. Send its media, text/markdown, real links, and native buttons when the adapter supports them.
+- In OpenClaw Telegram, send `render_plan.selected.openclaw_message` with OpenClaw `message send --media ... --presentation ...`; do not put legacy inline media directives inside human prose.
+- Do not rewrite `render_plan.selected` into a custom table or omit the real URL.
 - If status is `payment_handoff_required`, `next` is the human reply step, not payment wait.
 - Treat only `payment_intent.verified` as payment success.
 

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

@@ -11,8 +11,16 @@
     "The human needs to scan with the payment provider."
   ],
   "required_state": {
-    "needs": ["payment_intent_id", "human_action", "qr_png_url/preferred_qr_url or local_qr_path"],
-    "must_not_need": ["raw provider QR", "provider sign", "ops token"]
+    "needs": [
+      "payment_intent_id",
+      "human_action",
+      "qr_png_url/preferred_qr_url or local_qr_path"
+    ],
+    "must_not_need": [
+      "raw provider QR",
+      "provider sign",
+      "ops token"
+    ]
   },
   "commands": [
     {
@@ -33,6 +41,11 @@
     "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.",
+    "If response.render_plan.selected exists, treat it as the final UI render plan for the current host. Execute selected before reading other platform branches.",
+    "Do not rewrite response.render_plan.selected into a custom table. Use selected.text/markdown, selected.media, selected.links, and selected.buttons as provided.",
+    "If selected.links exists, include the real URL. Do not only show the link label.",
+    "If selected.buttons exists but the current adapter cannot render native buttons, degrade to selected.links plus short text; do not fake payment success or skip the status check.",
+    "In OpenClaw Telegram, prefer selected.openclaw_message: send its message/media/presentation through OpenClaw message send. Do not place legacy inline media directives inside prose; that fallback cannot render inline buttons.",
     "In Codex or Claude Code app clients, send response.human_visible_markdown or response.render_plan.platforms.codex_app.markdown to the human first. Do not start a hidden long wait before the human-visible message is sent.",
     "For Telegram-style message clients, use response.render_plan.platforms.telegram: 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.",
@@ -68,5 +81,14 @@
       "command": "itp docs show qr-refresh --role buyer --json"
     }
   ],
-  "search_terms": ["qr", "payment qr", "alipay", "scan", "order not found", "二维码", "扫码", "付款码"]
+  "search_terms": [
+    "qr",
+    "payment qr",
+    "alipay",
+    "scan",
+    "order not found",
+    "二维码",
+    "扫码",
+    "付款码"
+  ]
 }

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

@@ -10,9 +10,17 @@
     "The CLI returned agent_wait metadata."
   ],
   "required_state": {
-    "needs": ["payment_intent_id"],
-    "optional": ["cursor"],
-    "must_not_need": ["ops token", "provider query permission", "human text proof"]
+    "needs": [
+      "payment_intent_id"
+    ],
+    "optional": [
+      "cursor"
+    ],
+    "must_not_need": [
+      "ops token",
+      "provider query permission",
+      "human text proof"
+    ]
   },
   "commands": [
     {
@@ -27,6 +35,7 @@
     }
   ],
   "agent_rules": [
+    "If payment wait returns payment_handoff_required, render response.render_plan.selected to the human before running 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 human_visible_markdown instead of long-polling.",
     "Payment wait/status check is a recovery loop around the same payment_intent_id, not a one-shot command.",
@@ -57,5 +66,18 @@
       "command": "itp docs show recovery --role buyer --json"
     }
   ],
-  "search_terms": ["wait", "long poll", "timeout", "still waiting", "paid", "payment", "等待", "付款", "付款成功", "没返回", "一直等", "超时"]
+  "search_terms": [
+    "wait",
+    "long poll",
+    "timeout",
+    "still waiting",
+    "paid",
+    "payment",
+    "等待",
+    "付款",
+    "付款成功",
+    "没返回",
+    "一直等",
+    "超时"
+  ]
 }

package/docs/agent/buyer/quickstart.json

@@ -10,8 +10,16 @@
     "The agent is unsure which ItPay buyer command should come first."
   ],
   "required_state": {
-    "needs": ["itp CLI available", "buyer delivery email before checkout"],
-    "must_not_need": ["ops token", "claim token", "raw key", "provider raw payload"]
+    "needs": [
+      "itp CLI available",
+      "buyer delivery email before checkout"
+    ],
+    "must_not_need": [
+      "ops token",
+      "claim token",
+      "raw key",
+      "provider raw payload"
+    ]
   },
   "commands": [
     {
@@ -59,7 +67,8 @@
     "If response.status is payment_handoff_required, do not run payment wait from next.command; next is the human-visible reply. Only after the human asks to check payment should you run after_human_response.check_payment_command.",
     "Show the returned payment QR exactly as provided before starting payment wait.",
     "Payment truth comes only from payment_intent.verified.",
-    "Secure delivery goes to the human first; report redacted delivery status only."
+    "Secure delivery goes to the human first; report redacted delivery status only.",
+    "When a response includes render_plan.selected, execute that selected plan first; do not make the model choose a different platform branch or rewrite the payment/auth UI. In OpenClaw Telegram, use selected.openclaw_message instead of handwritten legacy media directive prose."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",
@@ -95,5 +104,14 @@
       "command": "itp docs show account-portal --role buyer --json"
     }
   ],
-  "search_terms": ["start", "quickstart", "first time", "buyer flow", "how to use itpay", "开始", "第一次", "怎么用"]
+  "search_terms": [
+    "start",
+    "quickstart",
+    "first time",
+    "buyer flow",
+    "how to use itpay",
+    "开始",
+    "第一次",
+    "怎么用"
+  ]
 }

package/lib/buyer.js

@@ -1649,6 +1649,7 @@ function compactHumanAction(action = null) {
     qr_image_url: action.qr_image_url,
     preferred_qr_url: action.preferred_qr_url,
     mobile_wallet_url: action.mobile_wallet_url,
+    presentation: action.presentation,
     agent_display_hint: action.agent_display_hint,
     expires_at: action.expires_at
   });

package/lib/render-human.js

@@ -306,29 +306,38 @@ function buildHumanActionRenderPlan(action = {}, intent = {}, flags = {}) {
   if (mobileWalletURL) requiredOutputs.push({ type: "link", label: "手机钱包打开", url: mobileWalletURL });
   const markdown = humanActionMarkdown(planAction, { localQRPath, qrPNGURL, preferredQRURL, entryURL, mobileWalletURL });
   const telegram = telegramRenderPlan(planAction, { localQRPath, preferredQRURL, entryURL, mobileWalletURL });
+  const host = agentHost(flags);
+  const platforms = compactObject({
+    codex_app: { format: "markdown_image_and_links", markdown },
+    claude_code: { format: "markdown_image_and_links", markdown },
+    telegram,
+    plain_chat: {
+      format: "image_or_link_then_human_reply",
+      text: kind === "payment_qr"
+        ? "请扫码或点击链接完成支付。付完后回复“我已付款”，我再查询真实状态。"
+        : "请打开上面的授权入口。完成后告诉我，我再继续查询状态。",
+      links: requiredOutputs.filter((item) => item.type === "link")
+    },
+    terminal: {
+      format: "cli_prints_qr_then_wait",
+      print_terminal_qr: true,
+      print_links: true
+    }
+  });
+  const selectedPlatform = selectedRenderPlatform(host);
+  const selected = {
+    platform: selectedPlatform,
+    ...platforms[selectedPlatform]
+  };
   return compactObject({
     kind,
     proof_rule: kind === "payment_qr"
       ? "Only payment_intent.verified proves payment."
       : "This human action is not payment proof.",
-    host: agentHost(flags) || undefined,
+    host: host || undefined,
     required_outputs: requiredOutputs,
-    platforms: compactObject({
-      codex_app: { format: "markdown_image_and_links", markdown },
-      claude_code: { format: "markdown_image_and_links", markdown },
-      telegram,
-      plain_chat: {
-        format: "image_or_link_then_human_reply",
-        text: kind === "payment_qr"
-          ? "请扫码或点击链接完成支付。付完后回复“我已付款”，我再查询真实状态。"
-          : "请打开上面的授权入口。完成后告诉我，我再继续查询状态。"
-      },
-      terminal: {
-        format: "cli_prints_qr_then_wait",
-        print_terminal_qr: true,
-        print_links: true
-      }
-    }),
+    selected,
+    platforms,
     forbidden: [
       "Do not say 'scan the QR above' unless an image or scannable URL is actually attached.",
       "Do not read a local image file as model input and treat that as sent to the human.",
@@ -368,10 +377,59 @@ function telegramRenderPlan(action = {}, { localQRPath = "", preferredQRURL = ""
       ? "请扫码或点击链接完成支付。付款后点“我已付款，查询状态”。"
       : "请打开 ItPay 授权入口，完成后回到当前对话。",
     links,
-    buttons
+    buttons,
+    openclaw_message: openclawTelegramMessage({ action, media, links, buttons })
   };
 }
 
+function openclawTelegramMessage({ action = {}, media = [], links = [], buttons = [] } = {}) {
+  const mediaURL = media[0]?.local_path || media[0]?.fallback_url || "";
+  const text = action.kind === "payment_qr"
+    ? "请扫码或点击链接完成支付。付款完成后点“我已付款，查询状态”，或直接回复“我已付款”。"
+    : "请打开 ItPay 授权入口，完成后回到当前对话。";
+  const presentationButtons = links.map((link) => ({ label: link.label, url: link.url }));
+  if (action.kind === "payment_qr") {
+    presentationButtons.push(
+      { label: "支付遇到问题 / 刷新", action: { type: "command", command: "刷新付款二维码" } },
+      { label: "我已付款，查询状态", action: { type: "command", command: "我已付款，查询状态" } }
+    );
+  } else {
+    for (const button of buttons) {
+      if (button.url && !presentationButtons.some((item) => item.url === button.url)) {
+        presentationButtons.push({ label: button.text || "打开链接", url: button.url });
+      }
+    }
+  }
+  const presentation = {
+    blocks: [
+      { type: "text", text },
+      ...(presentationButtons.length ? [{ type: "buttons", buttons: presentationButtons }] : [])
+    ]
+  };
+  return compactObject({
+    adapter: "openclaw",
+    channel: "telegram",
+    use: "message send --media/--presentation; do not use legacy inline media directives",
+    message: text,
+    media: mediaURL || undefined,
+    presentation,
+    command_args: compactObject({
+      message: text,
+      media: mediaURL || undefined,
+      presentation
+    })
+  });
+}
+
+function selectedRenderPlatform(host = "") {
+  const normalized = String(host || "").toLowerCase().replaceAll("-", "_");
+  if (["codex", "codex_app", "codex_cli"].includes(normalized)) return "codex_app";
+  if (["claude", "claude_code", "claudecode"].includes(normalized)) return "claude_code";
+  if (["telegram", "tg"].includes(normalized)) return "telegram";
+  if (terminalQRHostAliases().has(normalized)) return "terminal";
+  return "plain_chat";
+}
+
 function compactObject(value = {}) {
   return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== null && item !== ""));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "ItPay CLI, buyer skill, and agent-readable docs for agent-native commerce.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -211,10 +211,13 @@ itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent
 
 This keeps JSON output machine-readable while allowing the CLI to prepare a
 local QR image path for clients that cannot render remote SVG reliably. In
-Codex or Claude Code app clients, prefer `--no-wait-payment`: send
-`human_visible_markdown` or `render_plan.platforms.codex_app.markdown` to the
-human first. If the human is on mobile, present `mobile_wallet_url` as a
-clickable human-only fallback; do not convert it into a QR.
+Codex or Claude Code app clients, prefer `--no-wait-payment`: execute
+`render_plan.selected` first. If `selected.markdown` exists, send it exactly to
+the human. If `selected.media` exists, attach the listed image before saying the
+human can scan it. If `selected.links` exists, include the real URL, not just
+the label. If `selected.buttons` exists and the current adapter supports native
+buttons, render them; otherwise fall back to the real URL plus short text. Do
+not invent a table or rewrite the UI plan.
 
 If a response has `status=payment_handoff_required`, `next` is the user-visible
 reply step, not payment wait. Do not run `buyer payment wait` until the human