@itpay/cli 0.2.7 → 0.2.9

package/README.md

@@ -239,8 +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.
-- 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` 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 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,10 +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 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.",
     "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."
+    "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."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",

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

@@ -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,
@@ -377,8 +379,48 @@ 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 = "") {
@@ -387,7 +429,22 @@ function selectedRenderPlatform(host = "") {
   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 = {}) {
@@ -495,7 +552,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.7",
+  "version": "0.2.9",
   "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
-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, 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.
 
 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