@itpay/cli 0.2.12 → 0.2.14

package/lib/client-context.js

@@ -0,0 +1,126 @@
+const SUPPORTED_HOSTS = new Set(["codex", "claude-code", "telegram", "discord", "whatsapp", "terminal", "plain-chat"]);
+const RUNTIME_TARGETS = new Set(["codex", "claude-code", "openclaw", "generic"]);
+const EXEMPT_GROUPS = new Set(["", "--help", "-h", "help", "version", "docs", "skill", "doctor", "install"]);
+
+function clientContextGate(args = []) {
+  const group = args[0] || "";
+  if (EXEMPT_GROUPS.has(group)) return null;
+  const flags = parseArgFlags(args.slice(1));
+  const host = clientHost(flags);
+  if (!host) return clientContextRequired();
+  if (!SUPPORTED_HOSTS.has(host)) return unsupportedClientContext(host);
+  if (requiresTarget(host) && !clientTarget(flags)) return clientTargetRequired(host);
+  return null;
+}
+
+function clientHost(flags = {}) {
+  const raw = firstValue(
+    flags.host,
+    flags.client,
+    flags.channel,
+    argFlag("host"),
+    argFlag("client"),
+    argFlag("channel")
+  );
+  const host = normalizeHost(raw);
+  if (host === "openclaw" && flags.channel) return normalizeHost(flags.channel);
+  return host;
+}
+
+function clientTarget(flags = {}) {
+  const target = firstValue(flags.chat_target, flags.reply_target, argFlag("chat-target"), argFlag("reply-target"));
+  if (target) return target;
+  const flagTarget = flags.target || argFlag("target");
+  return flagTarget && !RUNTIME_TARGETS.has(normalizeHost(flagTarget)) ? String(flagTarget) : "";
+}
+
+function clientCommandArgs(flags = {}) {
+  const host = clientHost(flags);
+  const target = clientTarget(flags);
+  return [
+    ...(host ? ["--host", host] : []),
+    ...(target ? ["--target", target] : [])
+  ];
+}
+
+function requiresTarget(host) {
+  return host === "telegram" || host === "discord" || host === "whatsapp";
+}
+
+function clientContextRequired() {
+  return {
+    schema_version: "itp.client_context.v1",
+    status: "client_context_required",
+    must_rerun: true,
+    instruction: "Rerun the same itp command with --host <client>. ItPay will not guess the current chat/app client.",
+    allowed_hosts: Array.from(SUPPORTED_HOSTS),
+    examples: {
+      codex: "itp ... --host codex --json",
+      claude_code: "itp ... --host claude-code --json",
+      telegram: "itp ... --host telegram --target telegram:<chat_id> --json",
+      terminal: "itp ... --host terminal --json"
+    }
+  };
+}
+
+function clientTargetRequired(host) {
+  return {
+    schema_version: "itp.client_context.v1",
+    status: "client_target_required",
+    must_rerun: true,
+    host,
+    instruction: "Rerun the same itp command with the current chat target. For OpenClaw Telegram group/private chat, pass inbound_meta.chat_id as --target.",
+    examples: {
+      telegram_private: "itp ... --host telegram --target telegram:5559456744 --json",
+      telegram_group: "itp ... --host telegram --target telegram:-1001234567890 --json",
+      discord: "itp ... --host discord --target discord:<channel_id> --json"
+    }
+  };
+}
+
+function unsupportedClientContext(host) {
+  return {
+    schema_version: "itp.client_context.v1",
+    status: "unsupported_client_context",
+    must_rerun: true,
+    host,
+    instruction: "Use one supported --host value so ItPay can return a single executable human-output instruction.",
+    allowed_hosts: Array.from(SUPPORTED_HOSTS)
+  };
+}
+
+function normalizeHost(value = "") {
+  const normalized = String(value || "").trim().toLowerCase().replaceAll("_", "-");
+  if (["tg", "openclaw-telegram"].includes(normalized)) return "telegram";
+  if (["codex-app", "codex-cli"].includes(normalized)) return "codex";
+  if (["claude", "claudecode", "claude-code-app"].includes(normalized)) return "claude-code";
+  if (["plain", "plain-chat", "chat"].includes(normalized)) return "plain-chat";
+  return normalized;
+}
+
+function parseArgFlags(args = []) {
+  const flags = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!String(arg).startsWith("--")) continue;
+    const key = String(arg).slice(2).replaceAll("-", "_");
+    const next = args[i + 1];
+    if (!next || String(next).startsWith("--")) {
+      flags[key] = true;
+    } else {
+      flags[key] = next;
+      i += 1;
+    }
+  }
+  return flags;
+}
+
+function argFlag(name) {
+  return parseArgFlags(process.argv.slice(2))[String(name).replaceAll("-", "_")] || "";
+}
+
+function firstValue(...values) {
+  return values.find((value) => value !== undefined && value !== null && value !== false && String(value).trim() !== "") || "";
+}
+
+export { clientCommandArgs, clientContextGate, clientHost, clientTarget };

package/lib/render-human.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import QRCode from "qrcode";
+import { clientCommandArgs, clientHost, clientTarget } from "./client-context.js";
 import { apiTimeoutMs, cliCommand, commandExists, mergeRun, readRun, readState, safeErrorMessage, writeRun } from "./env.js";
 
 async function renderItPayPaymentAction(intent, flags = {}) {
@@ -423,6 +424,8 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
     media: mediaURL || undefined,
     presentation,
     command_args: compactObject({
+      channel: "telegram",
+      target: clientTarget() || undefined,
       message: text,
       media: mediaURL || undefined,
       presentation
@@ -431,55 +434,6 @@ function openclawTelegramMessage({ action = {}, media = [], links = [], buttons
   });
 }
 
-function humanOutputFromRenderPlan(plan = {}) {
-  if (!plan || typeof plan !== "object" || !plan.kind || !plan.selected) 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 });
 }
@@ -490,15 +444,16 @@ function openclawCallbackButton(text, intent, action = {}) {
 }
 
 function openclawCallbackCommands(action = {}) {
+  const contextArgs = clientCommandArgs();
   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
+      refresh_payment_qr: id ? cliCommand("buyer", "payment", "refresh-qr", id, ...contextArgs, "--json") : undefined,
+      check_payment_status: id ? cliCommand("buyer", "payment", "wait", id, "--timeout", "1", ...contextArgs, "--json") : undefined
     });
   }
   if (action.checkout_id) {
-    return { check_checkout_status: `itp buyer checkout resume ${action.checkout_id} --json` };
+    return { check_checkout_status: cliCommand("buyer", "checkout", "resume", action.checkout_id, ...contextArgs, "--json") };
   }
   return undefined;
 }
@@ -526,14 +481,7 @@ function selectedRenderPlan(host = "", platforms = {}) {
   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
-  });
+  return { platform: "plain_chat", ...platforms.plain_chat };
 }
 
 function compactObject(value = {}) {
@@ -641,20 +589,7 @@ function shouldReturnAfterAgentTextQR(flags = {}) {
 }
 
 function agentHost(flags = {}) {
-  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";
-  return "";
+  return clientHost(flags);
 }
 
 function agentTextQRHosts() {
@@ -780,4 +715,4 @@ function openBrowser(targetURL) {
   return false;
 }
 
-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 };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "0.2.12",
+  "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

@@ -20,10 +20,33 @@ protocol from this file. Use the CLI docs graph whenever you need details.
 
 ## Start Here
 
+Every non-doc ItPay command must include the current client context. The CLI
+will stop with `client_context_required` or `client_target_required` rather
+than guess.
+
+```text
+Codex app:        --host codex
+Claude Code app:  --host claude-code
+Terminal:         --host terminal
+Plain chat:       --host plain-chat
+OpenClaw Telegram private/group chat: --host telegram --target <inbound_meta.chat_id>
+```
+
+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 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:
 
 ```bash
-itp status --refresh --json
+itp status --refresh --host <client> --json
 itp docs show quickstart --role buyer --json
 itp docs list --role buyer --json
 ```
@@ -59,41 +82,41 @@ read this skill
 The high-level command can wrap this flow:
 
 ```bash
-itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
+itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --host <client> --json
 ```
 
 For step-by-step testing:
 
 ```bash
-itp buyer catalog search --query "<user request>" --json
-itp buyer catalog search --query "企业工商信息 查询" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --json
-itp buyer catalog get --variant <variant_id> --json
-itp buyer cart create --variant <variant_id> --json
-itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,1 --json
-itp buyer cart show <cart_id> --json
-itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --json
-itp buyer cart remove <cart_id> --line <cart_line_item_id> --json
-itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --json
-itp buyer checkout resume <checkout_id> --json
-itp buyer payment wait <payment_intent_id> --timeout 1 --json
-itp buyer checkout status <checkout_id> --json
-itp buyer refund create --order <order_id> --amount-minor <minor_units> --currency CNY --reason buyer_requested --json
-itp buyer refund list --order <order_id> --json
-itp buyer refund show <refund_id> --json
-itp buyer refund cancel <refund_id> --reason buyer_changed_mind --json
-itp buyer vault grants list --checkout <checkout_id> --json
-itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json
+itp buyer catalog search --query "<user request>" --host <client> --json
+itp buyer catalog search --query "企业工商信息 查询" --category business_data_api --provider itpay_enterprise_data --service-type ai_api --host <client> --json
+itp buyer catalog get --variant <variant_id> --host <client> --json
+itp buyer cart create --variant <variant_id> --host <client> --json
+itp buyer cart create --variants <variant_id_1>,<variant_id_2> --quantities 1,1 --host <client> --json
+itp buyer cart show <cart_id> --host <client> --json
+itp buyer cart add <cart_id> --variant <variant_id> --input key=value --quantity 1 --host <client> --json
+itp buyer cart remove <cart_id> --line <cart_line_item_id> --host <client> --json
+itp buyer checkout create --cart <cart_id> --email <buyer_email> --phone <buyer_phone> --host <client> --json
+itp buyer checkout resume <checkout_id> --host <client> --json
+itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json
+itp buyer checkout status <checkout_id> --host <client> --json
+itp buyer refund create --order <order_id> --amount-minor <minor_units> --currency CNY --reason buyer_requested --host <client> --json
+itp buyer refund list --order <order_id> --host <client> --json
+itp buyer refund show <refund_id> --host <client> --json
+itp buyer refund cancel <refund_id> --reason buyer_changed_mind --host <client> --json
+itp buyer vault grants list --checkout <checkout_id> --host <client> --json
+itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --host <client> --json
 ```
 
 For API products, read the product metadata input schema before cart creation.
 Enterprise data products require query input at cart time:
 
 ```bash
-itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --json
-itp buyer cart show <cart_id> --json
-itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --json
-itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --json
-itp buy var_itpay_enterprise_fuzzy_search_cny01 --email <buyer_email> --input company_name=京东 --display agent --no-wait-payment --json
+itp buyer cart create --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=京东 --host <client> --json
+itp buyer cart show <cart_id> --host <client> --json
+itp buyer cart add <cart_id> --variant var_itpay_enterprise_fuzzy_search_cny01 --input company_name=美团 --host <client> --json
+itp buyer cart create --variant var_itpay_enterprise_precise_lookup_cny05 --input company_name_or_credit_no=北京京东世纪贸易有限公司 --host <client> --json
+itp buy var_itpay_enterprise_fuzzy_search_cny01 --email <buyer_email> --input company_name=京东 --display agent --no-wait-payment --host <client> --json
 ```
 
 For cart edits, always read the server cart first with `buyer cart show`.
@@ -112,19 +135,19 @@ Refund commands use ItPay shared order state. If `itp buyer refund create`
 returns `policy_risk_confirmation_required`, explain the returned
 `refund_eligibility.policy` and `agent_guidance` to the human first. Only retry
 with `--confirm-policy-risk true` after explicit human confirmation.
-Do not guess `order_id`; if missing, run `buyer checkout status <checkout_id> --json`.
+Do not guess `order_id`; if missing, run `buyer checkout status <checkout_id> --host <client> --json`.
 Refund amounts use minor units: CNY 1000 means CNY 10.00.
 Refund commands require a server-verified buyer session, not a vault grant. If
 the CLI says the buyer session is required or expired, run
-`itp status --refresh --json` and follow the returned `next.command`.
+`itp status --refresh --host <client> --json` and follow the returned `next.command`.
 Current buyer refunds are whole-order only; do not use line-item refund scope.
 If the human cancels a refund before provider or money movement starts, use
-`buyer refund cancel <refund_id> --json`; after cancel, the delivery claim can
+`buyer refund cancel <refund_id> --host <client> --json`; after cancel, the delivery claim can
 be unlocked again by the ItPay backend.
 
 ## Non-Negotiable Rules
 
-1. Use `--json` for every ItPay command.
+1. Use `--json` and current client context for every non-doc ItPay command. Use `--host codex`, `--host claude-code`, `--host terminal`, `--host plain-chat`, or for OpenClaw Telegram use `--host telegram --target <inbound_meta.chat_id>`.
 2. Do not invent service IDs, variant IDs, checkout IDs, payment URLs, QR URLs,
    payment intent IDs, delivery IDs, or claim links.
 3. When the user asks for several compatible services, use one cart and one
@@ -206,18 +229,17 @@ Each docs page includes `next_docs`. Follow those links as the state changes.
 For payment creation in an agent/chat client, prefer:
 
 ```bash
-itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --json
+itp buy <variant_id> --email <buyer_email> --phone <buyer_phone> --display agent --no-wait-payment --host <client> --json
 ```
 
 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 `media` field 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, if `human_output_required=true`, send `human_output.markdown` exactly
+`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