@itpay/cli 0.2.9 → 0.2.11

package/README.md

@@ -239,9 +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.
-- If you know the current chat channel and `render_plan.platforms.<channel>` exists, use that branch before `render_plan.selected`.
-- In OpenClaw Telegram, send `render_plan.platforms.telegram.openclaw_message` with OpenClaw `message send --media ... --presentation ...`; do not put legacy inline media directives inside human prose.
-- If the channel is unsupported, use `render_plan.selected.fallback` / plain chat. Do not rewrite the chosen plan into a custom table or omit the real URL.
+- If `human_output_required=true`, send root `human_output` before any next ItPay command. It is not optional UI decoration.
+- In OpenClaw Telegram, pass `human_output.message/media/presentation` to `openclaw message send`; buttons use native `text/url/callback_data`.
+- `render_plan` is diagnostic/compatibility detail. Do not choose a shorter fallback when root `human_output` is present.
 - 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

@@ -26,7 +26,7 @@
     {
       "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; response.human_visible_markdown and response.render_plan are present; render the QR/link to the human before any status check"
+      "success_signal": "response.status is payment_handoff_required; response.human_output_required is true; send response.human_output to the human before any status check"
     },
     {
       "intent": "recover a scanner order-not-found display problem",
@@ -41,14 +41,12 @@
     "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 you know the current chat channel and response.render_plan.platforms.<channel> exists, use that channel branch before response.render_plan.selected.",
-    "If response.render_plan.selected.platform is current_channel_required, choose the branch matching the current channel; selected.fallback is only for unsupported plain chat clients.",
-    "Do not rewrite the chosen render plan into a custom table. Use its text/markdown, media, links, and 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 response.render_plan.platforms.telegram.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.",
+    "If response.human_output_required is true, send response.human_output before any next ItPay command. It is the mandatory human-facing output, not decoration.",
+    "Do not rewrite response.human_output into a custom table. Use its text/markdown, media, links, and buttons as provided.",
+    "If human_output links or buttons include URLs, include the real URL. Do not only show the link label.",
+    "In OpenClaw Telegram, pass human_output.message/media/presentation to openclaw message send. Its presentation.blocks[].buttons[] uses native text/url/callback_data; do not simulate buttons in normal prose.",
+    "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.",
+    "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.",
     "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.",

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

@@ -35,7 +35,7 @@
     }
   ],
   "agent_rules": [
-    "If payment wait returns payment_handoff_required, render response.render_plan.platforms.<current channel> when available; otherwise use response.render_plan.selected/fallback before running any later status check.",
+    "If payment wait returns payment_handoff_required, send response.human_output 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.",

package/docs/agent/buyer/quickstart.json

@@ -45,7 +45,7 @@
     {
       "intent": "buy a selected variant with the high-level cart-first flow",
       "command": "itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json",
-      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; if payment_handoff_required, render response.human_visible_markdown or response.render_plan to the human before any payment status check"
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; if human_output_required is true, send response.human_output before any payment status check"
     }
   ],
   "agent_rules": [
@@ -62,13 +62,13 @@
     "After showing auth_qr, keep running/resuming the same checkout unless the human explicitly asks you to pause. Do not stop merely because a QR was displayed.",
     "When a buyer command returns buyer_session.status=buyer_session_saved, the CLI has stored the buyer account session for this agent device. You may continue with checkout/payment or `buyer vault` commands without asking the human for a token.",
     "Vault grants are only for reading approved delivered artifacts. They are not buyer session credentials and do not authorize refunds or account/order management.",
-    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and show human_visible_markdown/render_plan, then only check status after the human responds or uses a platform button.",
-    "If response.human_visible_markdown is present, send it to the human immediately in the same user-visible message. It includes the QR image and payment link.",
+    "Use high-level itp buy when possible, but in agent app clients split payment into two visible steps: first return and send human_output, then only check status after the human responds or uses a platform button.",
+    "If response.human_output_required is true, send response.human_output immediately in the same user-visible message. It includes the QR image/link/buttons.",
     "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.",
-    "When a response includes render_plan, first use render_plan.platforms.<current channel> if it exists. If selected.platform is current_channel_required, selected.fallback is only for unsupported plain chat. In OpenClaw Telegram, use render_plan.platforms.telegram.openclaw_message instead of handwritten legacy media directive prose."
+    "When response.human_output_required is true, root human_output is the execution path. render_plan is diagnostic/compatibility detail. In OpenClaw Telegram, pass human_output.message/media/presentation to openclaw message send instead of handwritten prose."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",

package/lib/buyer.js

@@ -4,7 +4,7 @@ import {
   writeCredentials, writeSessionCredentials, writeState
 } from "./env.js";
 import { coreApi, coreApiBase } from "./http.js";
-import { buildHumanActionRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
+import { buildHumanActionRenderPlan, humanOutputFromRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
   rejectBuyerSandboxFlag(flags);
@@ -1512,6 +1512,12 @@ function compactBuyerOutput(value = {}) {
     result.must_reply_to_human_before_next_command = true;
     result.human_visible_markdown = value.payment_handoff.markdown;
   }
+  const humanOutput = humanOutputFromRenderPlan(value.render_plan);
+  if (humanOutput) {
+    result.human_output_required = true;
+    result.must_send_human_output_before_next_command = true;
+    result.human_output = humanOutput;
+  }
   for (const [key, item] of Object.entries(value)) {
     if (["docs", "status"].includes(key)) continue;
     result[key] = compactBuyerField(key, item);

package/lib/render-human.js

@@ -286,8 +286,9 @@ function annotateHumanActionPresentation(action, qrImageURL) {
 function buildHumanActionRenderPlan(action = {}, intent = {}, flags = {}) {
   if (!action || typeof action !== "object") return null;
   const kind = action.kind || (isPaymentIntentHandoff(intent) ? "payment_qr" : "human_action");
-  const planAction = action.kind === kind ? action : { ...action, kind };
   const entryURL = intent.payment_entry_url || intent.payment_url || action.url || action.web_url || "";
+  const checkoutID = intent.checkout_id || action.checkout_id || checkoutIDFromURL(entryURL);
+  const planAction = compactObject({ ...(action.kind === kind ? action : { ...action, kind }), checkout_id: checkoutID || undefined });
   const qrPNGURL = action.qr_png_url || intent.qr_png_url || intent.qr?.png_url || "";
   const preferredQRURL = action.preferred_qr_url || qrPNGURL || action.qr_image_url || intent.qr_image_url || intent.qr?.image_url || "";
   const localQRPath = action.local_qr_path || intent.local_qr_path || "";
@@ -371,7 +372,10 @@ function telegramRenderPlan(action = {}, { localQRPath = "", preferredQRURL = ""
       { text: "支付遇到问题 / 刷新", intent: "refresh_payment_qr" },
       { text: "我已付款，查询状态", intent: "check_payment_status" }
     ]
-    : entryURL ? [{ text: "打开授权页面", url: entryURL }] : [];
+    : [
+      ...(entryURL ? [{ text: "打开授权页面", url: entryURL }] : []),
+      ...(action.checkout_id ? [{ text: "我已完成，查询状态", intent: "check_checkout_status" }] : [])
+    ];
   return {
     format: action.kind === "payment_qr" ? "photo_text_inline_buttons" : "text_inline_buttons",
     media,
@@ -389,16 +393,19 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
   const text = action.kind === "payment_qr"
     ? "请扫码或点击链接完成支付。付款完成后点“我已付款，查询状态”，或直接回复“我已付款”。"
     : "请打开 ItPay 授权入口，完成后回到当前对话。";
-  const presentationButtons = links.map((link) => ({ label: link.label, url: link.url }));
+  const presentationButtons = links.map((link) => openclawURLButton(link.label, link.url));
   if (action.kind === "payment_qr") {
     presentationButtons.push(
-      { label: "支付遇到问题 / 刷新", action: { type: "command", command: "刷新付款二维码" } },
-      { label: "我已付款，查询状态", action: { type: "command", command: "我已付款，查询状态" } }
+      openclawCallbackButton("支付遇到问题 / 刷新", "refresh_payment_qr", action),
+      openclawCallbackButton("我已付款，查询状态", "check_payment_status", action)
     );
   } else {
     for (const button of buttons) {
       if (button.url && !presentationButtons.some((item) => item.url === button.url)) {
-        presentationButtons.push({ label: button.text || "打开链接", url: button.url });
+        presentationButtons.push(openclawURLButton(button.text || "打开链接", button.url));
+      }
+      if (button.intent === "check_checkout_status") {
+        presentationButtons.push(openclawCallbackButton("我已完成，查询状态", "check_checkout_status", action));
       }
     }
   }
@@ -419,10 +426,92 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
       message: text,
       media: mediaURL || undefined,
       presentation
+    }),
+    callbacks: openclawCallbackCommands(action)
+  });
+}
+
+function humanOutputFromRenderPlan(plan = {}) {
+  if (!plan || typeof plan !== "object") return null;
+  const selected = plan.selected || {};
+  const platforms = plan.platforms || {};
+  const base = {
+    required: true,
+    kind: plan.kind,
+    proof_rule: plan.proof_rule,
+    instruction: "Send this human_output to the human before running the next ItPay command."
+  };
+  if (selected.platform === "telegram") return { ...base, ...openclawHumanOutput(selected.openclaw_message) };
+  if (selected.platform === "codex_app" || selected.platform === "claude_code") return { ...base, method: "markdown_reply", markdown: selected.markdown };
+  if (selected.platform === "terminal") return { ...base, method: "terminal_display", print_terminal_qr: true, print_links: true };
+  if (selected.platform && selected.platform !== "current_channel_required") return { ...base, ...plainChatHumanOutput(selected) };
+  return {
+    ...base,
+    method: "current_channel_required",
+    instruction: "Choose the branch matching the current chat platform, send it to the human, then stop until the human responds or clicks a platform button.",
+    channels: compactObject({
+      openclaw_telegram: openclawHumanOutput(platforms.telegram?.openclaw_message),
+      codex_app: { method: "markdown_reply", markdown: platforms.codex_app?.markdown },
+      claude_code: { method: "markdown_reply", markdown: platforms.claude_code?.markdown },
+      plain_chat: plainChatHumanOutput(platforms.plain_chat),
+      terminal: { method: "terminal_display", print_terminal_qr: true, print_links: true }
     })
+  };
+}
+
+function openclawHumanOutput(message = {}) {
+  if (!message) return null;
+  return compactObject({
+    method: "openclaw_message_send",
+    channel: "telegram",
+    message: message.command_args?.message || message.message,
+    media: message.command_args?.media || message.media,
+    presentation: message.command_args?.presentation || message.presentation,
+    callbacks: message.callbacks
+  });
+}
+
+function plainChatHumanOutput(plan = {}) {
+  if (!plan) return null;
+  return compactObject({
+    method: "plain_chat_reply",
+    text: plan.text,
+    links: plan.links
   });
 }
 
+function openclawURLButton(text, url) {
+  return compactObject({ text, url });
+}
+
+function openclawCallbackButton(text, intent, action = {}) {
+  const id = action.payment_intent_id || action.checkout_id || action.id || "current";
+  return { text, callback_data: `itp:${intent}:${id}` };
+}
+
+function openclawCallbackCommands(action = {}) {
+  if (action.kind === "payment_qr") {
+    const id = action.payment_intent_id || action.id || "";
+    return compactObject({
+      refresh_payment_qr: id ? `itp buyer payment refresh-qr ${id} --json` : undefined,
+      check_payment_status: id ? `itp buyer payment wait ${id} --timeout 1 --json` : undefined
+    });
+  }
+  if (action.checkout_id) {
+    return { check_checkout_status: `itp buyer checkout resume ${action.checkout_id} --json` };
+  }
+  return undefined;
+}
+
+function checkoutIDFromURL(value = "") {
+  try {
+    const url = new URL(value);
+    return url.pathname.match(/\/checkouts\/([^/]+)/)?.[1] || "";
+  } catch {
+    return String(value || "").match(/\/checkouts\/([^/?#]+)/)?.[1] || "";
+  }
+}
+
 function selectedRenderPlatform(host = "") {
   const normalized = String(host || "").toLowerCase().replaceAll("-", "_");
   if (["codex", "codex_app", "codex_cli"].includes(normalized)) return "codex_app";
@@ -691,4 +780,4 @@ function openBrowser(targetURL) {
   return false;
 }
 
-export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };
+export { renderItPayPaymentAction, humanActionSummaryLines, writeHumanActionSummary, waitHeartbeatMs, writeWaitHeartbeat, renderHumanAction, buildHumanActionRenderPlan, humanOutputFromRenderPlan, preferredHumanActionQRURL, humanActionPresentationURL, annotateHumanActionPresentation, shouldPrepareLocalQRForJSON, shouldGenerateLocalQRFromActionURL, prepareLocalQRFile, prepareLocalQRFromActionURL, defaultQRFilePath, defaultGeneratedQRFilePath, qrFileExtension, qrMimeType, sanitizeFilename, formatActionTime, shouldUseAgentTextQR, shouldReturnAfterAgentTextQR, attachAgentQRImage, attachAgentLocalQR, downloadQRImage, persistHumanAction, shouldRenderTerminalQR, terminalQRType, shouldOpenBrowser, openBrowser };

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -211,13 +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
-agent/chat clients, prefer `--no-wait-payment`: if you know the current channel
-and `render_plan.platforms.<channel>` exists, use that branch first. In Codex
-or Claude Code app clients, send the platform markdown exactly. In OpenClaw
-Telegram, use `render_plan.platforms.telegram.openclaw_message` so media and
-native buttons are sent through the adapter. If `selected.platform` is
-`current_channel_required`, `selected.fallback` is only for unsupported plain
-chat clients. Do not invent a table or rewrite the UI plan.
+agent/chat clients, prefer `--no-wait-payment`: if `human_output_required=true`,
+send root `human_output` before any next ItPay command. In Codex or Claude Code
+app clients, send `human_output.markdown` exactly. In OpenClaw Telegram, pass
+`human_output.message/media/presentation` to `openclaw message send` so media
+and native `text/url/callback_data` buttons are sent through the adapter.
+`render_plan` is diagnostic/compatibility detail. 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