@itpay/cli 0.2.13 → 0.2.14

package/README.md

@@ -245,7 +245,7 @@ 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`.
 - 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.

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 --host <client> --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"
+      "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",
@@ -43,8 +43,10 @@
     "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.agent_instruction is present, it is the mandatory execution path. Use it before any next ItPay command.",
-    "In OpenClaw Telegram, use response.agent_instruction.openclaw_message.command_args with openclaw message send. Do not rewrite it into a custom table. Use its target, 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 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.",

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

@@ -36,7 +36,7 @@
   ],
   "agent_rules": [
     "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_instruction, send response.agent_instruction before running any later status check.",
+    "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/quickstart.json

@@ -45,14 +45,14 @@
     {
       "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 --host <client> --json",
-      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; in OpenClaw Telegram, if agent_instruction is present, send response.agent_instruction.openclaw_message.command_args before any payment status check"
+      "success_signal": "response.status becomes waiting_human_auth or payment_handoff_required; in OpenClaw Telegram, if agent_action is present, execute response.agent_action.command or response.agent_action.argv before any normal reply or payment status check"
     }
   ],
   "agent_rules": [
     "Use --json for every ItPay command.",
     "Every non-doc ItPay command must include the current client context: --host codex, --host claude-code, --host terminal, --host plain-chat, or for OpenClaw/Telegram use --host telegram --target <inbound_meta.chat_id>.",
     "Do not rely on the CLI to guess Telegram, Discord, WhatsApp, Codex, or Claude Code. If ItPay returns client_context_required or client_target_required, rerun the same command with the required --host/--target fields before continuing.",
-    "For Telegram group chat or @mention flows, pass the group/private chat target from OpenClaw inbound metadata, for example --target telegram:-1001234567890. ItPay only echoes the target into openclaw message send; OpenClaw owns group allowlist/mention policy.",
+    "For Telegram group chat or @mention flows, pass the group/private chat target from OpenClaw inbound metadata, for example --target telegram:-1001234567890. ItPay only echoes the target into agent_action; OpenClaw owns group allowlist/mention policy.",
     "Use `itp status --refresh --host <client> --json` before account, order, refund, or repeat-purchase decisions. Plain local memory is not identity.",
     "If `status --refresh` returns `recoverable_context.found=true`, do not blindly resume or blindly ignore it. Decide whether the old task is related to the current user intent; continue related tasks, ignore clearly unrelated tasks, and ask the human when unsure.",
     "If the catalog is unclear, read catalog-search docs and use buyer shelf manifest/snapshot as the shopping-list view before guessing keywords.",
@@ -66,13 +66,15 @@
     "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 send the human handoff instruction, then only check status after the human responds or uses a platform button.",
-    "If response.agent_instruction is present, it is the mandatory execution path for the current client. Do not use fallback fields or handwritten prose instead.",
-    "In OpenClaw Telegram, call openclaw message send with response.agent_instruction.openclaw_message.command_args. It includes target, QR media, exact message, and native button presentation.",
+    "If response.agent_action is present, it is the mandatory execution path for the current client. Execute response.agent_action.command or response.agent_action.argv before any normal prose reply.",
+    "In OpenClaw Telegram, response.agent_action is already the exact openclaw message send command. It includes target, QR media, exact message, and native button presentation.",
+    "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 or handwritten prose.",
+    "response.agent_instruction is natural-language reinforcement for the agent; it does not replace response.agent_action.",
     "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.",
-    "For OpenClaw Telegram, root agent_instruction is the execution path. Do not use handwritten prose when agent_instruction.openclaw_message.command_args is present."
+    "For OpenClaw Telegram, root agent_action is the execution path. Do not use handwritten prose when agent_action is present."
   ],
   "forbidden": [
     "Do not call ops commands from the buyer path.",

package/lib/buyer.js

@@ -1,7 +1,7 @@
 import {
   appendURLQuery, booleanFlag, cliCommand, cryptoRandom, csvValues, deleteSessionCredential, intFlag, output, positional, readConfig, readCredentials,
   readSessionToken, readState, safeErrorMessage, sleep, splitCSV, stripInternalBuyerFields, updateRun, writeConfig,
-  writeCredentials, writeSessionCredentials, writeState
+  writeCredentials, writeSessionCredentials, writeState, shellQuote
 } from "./env.js";
 import { clientCommandArgs, clientHost, clientTarget } from "./client-context.js";
 import { coreApi, coreApiBase } from "./http.js";
@@ -1592,38 +1592,61 @@ function telegramBuyerInstruction(value = {}, flags = {}) {
   const hasHumanEntry = Boolean(media || presentation.blocks?.some((block) => block.type === "buttons" && block.buttons?.some((button) => button.url)));
   const text = telegramBuyerInstructionText(plan.kind, summary, hasHumanEntry);
   const callbacks = rawMessage.callbacks || {};
+  const commandArgs = compactObject({
+    channel: "telegram",
+    target: clientTarget(flags) || undefined,
+    message: text,
+    media: media || undefined,
+    presentation
+  });
+  const action = telegramAgentAction(commandArgs);
+  const instruction = "必须先执行顶层 agent_action.command 或 agent_action.argv，把二维码、说明和 Telegram 原生按钮发给用户。不要手写 Markdown 表格，不要只贴链接，不要先运行 wait/status；如果不能执行 openclaw message send，就停止并说明工具缺失。";
   return compactObject({
     status: value.status,
+    instruction,
     must_send_to_human_before_next_command: true,
+    must_execute_agent_action_before_reply: true,
     order_summary: summary,
+    agent_action: action,
     agent_instruction: {
       type: plan.kind === "auth_qr" ? "send_telegram_auth_handoff" : "send_telegram_payment_handoff",
       platform: "telegram",
       proof_rule: plan.proof_rule,
-      instruction: "必须使用 openclaw_message.command_args 发送给用户。不要用自然语言伪造按钮，不要先运行 wait/status。只有 payment_intent.verified 才算付款成功。",
+      instruction,
       openclaw_message: {
         command: "openclaw message send",
-        command_args: compactObject({
-          channel: "telegram",
-          target: clientTarget(flags) || undefined,
-          message: text,
-          media: media || undefined,
-          presentation
-        }),
+        command_args: commandArgs,
         telegram_rule: "Telegram 原生按钮必须通过 openclaw message send --presentation 发送；presentation.blocks[].type=\"buttons\" 才会生成 Inline Keyboard。",
         callbacks
       }
     },
     after_human_response: telegramAfterHumanResponse(value, callbacks),
-    agent_next_actions: ["send_agent_instruction_to_human"],
+    agent_next_actions: ["execute_agent_action"],
     next: {
       type: "reply_to_human",
       safe_for_agent: false,
-      instruction: "先把 agent_instruction.openclaw_message.command_args 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
+      instruction: "先执行 agent_action.command/argv；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
     }
   });
 }
 
+function telegramAgentAction(commandArgs = {}) {
+  const argv = ["openclaw", "message", "send"];
+  if (commandArgs.channel) argv.push("--channel", commandArgs.channel);
+  if (commandArgs.target) argv.push("--target", commandArgs.target);
+  if (commandArgs.message) argv.push("--message", commandArgs.message);
+  if (commandArgs.media) argv.push("--media", commandArgs.media);
+  if (commandArgs.presentation) argv.push("--presentation", JSON.stringify(commandArgs.presentation));
+  return {
+    type: "openclaw_message_send",
+    tool: "shell",
+    instruction: "现在立刻执行这个 shell 命令发送 Telegram 原生消息；不要改写为普通聊天回复。执行成功后再简短告诉用户已发出。",
+    command: argv.map((item) => shellQuote(String(item))).join(" "),
+    argv,
+    if_unavailable: "如果当前 agent 不能执行 openclaw message send，停止并告诉用户：当前 agent 缺少 Telegram 原生按钮发送工具；不要降级成 Markdown 表格或普通链接。"
+  };
+}
+
 function markdownBuyerInstruction(value = {}, flags = {}, platform = "codex_app", markdown = "") {
   const plan = value.render_plan || {};
   const summary = buyerOrderSummary(value, plan.kind);

package/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -35,7 +35,13 @@ OpenClaw Telegram private/group chat: --host telegram --target <inbound_meta.cha
 For Telegram groups or @mention flows, use the same OpenClaw inbound
 `chat_id` as the target, for example `--target telegram:-1001234567890`.
 OpenClaw owns group allowlists and mention policy; ItPay only echoes the target
-into `openclaw message send`.
+into the returned `agent_action`.
+
+If a response contains `agent_action`, run `agent_action.command` or
+`agent_action.argv` before writing any normal reply. Do not summarize it, do
+not rewrite it as Markdown, and do not run wait/status first. If the command
+cannot run, stop and tell the human the agent lacks the required OpenClaw
+message tool.
 
 Run these commands before buying:
 
@@ -229,13 +235,12 @@ 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`. In OpenClaw Telegram, if
-`agent_instruction` is present, call `openclaw message send` with
-`agent_instruction.openclaw_message.command_args`. The `target` field is the
-OpenClaw chat target, `media` is the QR image, `message` is the exact human text, and
-`presentation.blocks[].type="buttons"` creates Telegram native inline buttons.
-Do not rewrite it as a table or normal prose. In Codex or Claude Code app
-clients, send `agent_instruction.markdown` exactly before any next ItPay
-command.
+`agent_action` is present, execute `agent_action.command` or `agent_action.argv`
+exactly. It already contains `openclaw message send`, the chat target, QR
+media, exact human text, and `presentation.blocks[].type="buttons"` for
+Telegram native inline buttons. Do not rewrite it as a table or normal prose.
+In Codex or Claude Code app clients, send `agent_instruction.markdown` exactly
+before any next ItPay command.
 
 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