@itpay/cli 0.2.8 → 0.2.10

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.
-- 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 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.command_args` with `openclaw message send`; its `presentation.blocks[].buttons[]` uses native `text/url/callback_data`.
+- 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 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

@@ -41,11 +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 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 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 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 OpenClaw Telegram, prefer response.render_plan.platforms.telegram.openclaw_message.command_args with 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_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.",

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

@@ -35,7 +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.",
+    "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.",
     "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

@@ -68,7 +68,7 @@
     "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.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."
+    "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, pass render_plan.platforms.telegram.openclaw_message.command_args to openclaw message send instead of handwritten prose."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",

package/lib/render-human.js

@@ -324,17 +324,19 @@ function buildHumanActionRenderPlan(action = {}, intent = {}, flags = {}) {
       print_links: true
     }
   });
-  const selectedPlatform = selectedRenderPlatform(host);
-  const selected = {
-    platform: selectedPlatform,
-    ...platforms[selectedPlatform]
-  };
+  const selected = selectedRenderPlan(host, platforms);
   return compactObject({
     kind,
     proof_rule: kind === "payment_qr"
       ? "Only payment_intent.verified proves payment."
       : "This human action is not payment proof.",
     host: host || undefined,
+    platform_selection: {
+      rule: host
+        ? "selected was chosen from the detected host. If your actual channel has a more specific branch in platforms, use that branch."
+        : "CLI could not detect the chat channel. If your current channel appears in platforms, use that branch; selected.fallback is only for unsupported plain chat.",
+      telegram: "For Telegram/OpenClaw, use platforms.telegram.openclaw_message instead of selected.fallback."
+    },
     required_outputs: requiredOutputs,
     selected,
     platforms,
@@ -387,16 +389,16 @@ 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));
       }
     }
   }
@@ -417,17 +419,45 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
       message: text,
       media: mediaURL || undefined,
       presentation
-    })
+    }),
+    callbacks: action.kind === "payment_qr" ? {
+      refresh_payment_qr: "收到 callback_data 后刷新或重新发送同一个 payment_intent 的付款入口。",
+      check_payment_status: "收到 callback_data 后运行 buyer payment wait/status，只信 payment_intent.verified。"
+    } : undefined
   });
 }
 
+function openclawURLButton(text, url) {
+  return compactObject({ text, url });
+}
+
+function openclawCallbackButton(text, intent, action = {}) {
+  const id = action.payment_intent_id || action.id || "current";
+  return { text, callback_data: `itp:${intent}:${id}` };
+}
+
 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";
+  return "";
+}
+
+function selectedRenderPlan(host = "", platforms = {}) {
+  const selectedPlatform = selectedRenderPlatform(host);
+  if (selectedPlatform && platforms[selectedPlatform]) {
+    return { platform: selectedPlatform, ...platforms[selectedPlatform] };
+  }
+  return compactObject({
+    platform: "current_channel_required",
+    rule: "Use render_plan.platforms.<current channel> when available; fallback is only for unsupported plain chat clients.",
+    telegram: platforms.telegram,
+    codex_app: platforms.codex_app,
+    claude_code: platforms.claude_code,
+    fallback: platforms.plain_chat
+  });
 }
 
 function compactObject(value = {}) {
@@ -535,7 +565,16 @@ function shouldReturnAfterAgentTextQR(flags = {}) {
 }
 
 function agentHost(flags = {}) {
-  const explicit = String(process.env.ITP_HOST || flags.host || "").toLowerCase();
+  const explicit = String(
+    process.env.ITP_HOST ||
+    flags.host ||
+    flags.channel ||
+    process.env.OPENCLAW_CURRENT_CHANNEL_PROVIDER ||
+    process.env.OPENCLAW_CHANNEL ||
+    process.env.CURRENT_CHANNEL_PROVIDER ||
+    process.env.AGENT_CHANNEL ||
+    ""
+  ).toLowerCase();
   if (explicit) return explicit;
   if (process.env.CODEX_THREAD_ID || process.env.CODEX_SHELL || process.env.CODEX_CI) return "codex";
   if (process.env.CLAUDECODE || process.env.CLAUDE_CODE || process.env.CLAUDECODE_SESSION_ID) return "claude-code";

package/lib/runtime.js

@@ -11,7 +11,7 @@ import { accountOverviewStatus, nextActionForAuthStatus, outputAccountStatus, re
 import {
   CREDENTIALS_PATH, CONFIG_DIR, RUNS_DIR, VERSION, apiBase, apiTimeoutMs, appendURLQuery, booleanFlag, cliCommand, commandExists,
   cryptoRandom, csvValues, currentExecutable, deleteGrantCredential, deleteSessionCredential, detectNativeCredentialStore,
-  escapeTomlString, fileMode, intFlag, listRuns, maskSecret, mergeRun, output, parseFlags, positional, prepareSetupRun,
+  escapeTomlString, fileMode, intFlag, listRuns, maskSecret, mergeRun, normalizePurchaseFlags, output, parseFlags, positional, prepareSetupRun,
   queryString, quoteShell, readConfig, readCredentials, readGrantCredential, readJSON, readRun, readSessionToken, readState,
   readText, replaceManagedBlock, safeErrorMessage, sanitizeAuthResponse, shellQuote, sleep, storeGrantCredential,
   updateCurrentRun, updateRun, withStateLock, writeConfig, writeCredentials, writeJSONWithBackup, writeRun,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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,14 @@ 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`: 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.
+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, pass `render_plan.platforms.telegram.openclaw_message.command_args`
+to `openclaw message send` so media and native `text/url/callback_data` 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.
 
 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