@itpay/cli 0.2.12 → 0.2.13

package/docs/agent/buyer/recovery.json

@@ -11,23 +11,29 @@
     "Checkout or delivery is pending."
   ],
   "required_state": {
-    "needs": ["last known checkout_id, payment_intent_id, or variant_id"],
-    "must_not_need": ["ops token", "provider raw payload", "claim token"]
+    "needs": [
+      "last known checkout_id, payment_intent_id, or variant_id"
+    ],
+    "must_not_need": [
+      "ops token",
+      "provider raw payload",
+      "claim token"
+    ]
   },
   "commands": [
     {
       "intent": "resume checkout state",
-      "command": "itp buyer checkout resume <checkout_id> --json",
+      "command": "itp buyer checkout resume <checkout_id> --host <client> --json",
       "success_signal": "response.status and agent_next_actions describe the safe next action"
     },
     {
       "intent": "wait again on the same payment intent",
-      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --json",
+      "command": "itp buyer payment wait <payment_intent_id> --timeout 1 --host <client> --json",
       "success_signal": "response.payment_event.event_type is payment_intent.verified or still waiting"
     },
     {
       "intent": "refresh display QR only",
-      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --json",
+      "command": "itp buyer payment refresh-qr <payment_intent_id> --reason order-not-found --host <client> --json",
       "success_signal": "response.payment_intent.qr_image_url is present"
     }
   ],
@@ -62,5 +68,18 @@
       "command": "itp docs show secure-delivery --role buyer --json"
     }
   ],
-  "search_terms": ["recover", "resume", "timeout", "lost", "retry", "stuck", "恢复", "重试", "卡住", "没返回", "断了", "找不到"]
+  "search_terms": [
+    "recover",
+    "resume",
+    "timeout",
+    "lost",
+    "retry",
+    "stuck",
+    "恢复",
+    "重试",
+    "卡住",
+    "没返回",
+    "断了",
+    "找不到"
+  ]
 }

package/docs/agent/buyer/safety-policy.json

@@ -10,8 +10,13 @@
     "The agent is deciding between buyer and ops commands."
   ],
   "required_state": {
-    "needs": ["role=buyer"],
-    "must_not_need": ["ops token", "raw secret access"]
+    "needs": [
+      "role=buyer"
+    ],
+    "must_not_need": [
+      "ops token",
+      "raw secret access"
+    ]
   },
   "commands": [
     {
@@ -52,5 +57,14 @@
       "command": "itp docs show secure-delivery --role buyer --json"
     }
   ],
-  "search_terms": ["policy", "forbidden", "security", "secret", "ops", "安全", "禁止", "权限"]
+  "search_terms": [
+    "policy",
+    "forbidden",
+    "security",
+    "secret",
+    "ops",
+    "安全",
+    "禁止",
+    "权限"
+  ]
 }

package/docs/agent/buyer/secure-delivery.json

@@ -10,23 +10,30 @@
     "The user asks where the purchased key/content is."
   ],
   "required_state": {
-    "needs": ["checkout_id"],
-    "must_not_need": ["claim token", "claim link", "raw key", "storage ref"]
+    "needs": [
+      "checkout_id"
+    ],
+    "must_not_need": [
+      "claim token",
+      "claim link",
+      "raw key",
+      "storage ref"
+    ]
   },
   "commands": [
     {
       "intent": "check redacted delivery status",
-      "command": "itp buyer checkout status <checkout_id> --json",
+      "command": "itp buyer checkout status <checkout_id> --host <client> --json",
       "success_signal": "delivery.sensitive_content_redacted == true"
     },
     {
       "intent": "list agent-safe delivery state",
-      "command": "itp buyer deliveries list --checkout <checkout_id> --json",
+      "command": "itp buyer deliveries list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.deliveries contains no raw content or claim token"
     },
     {
       "intent": "after the human says they granted agent access, discover the current agent's grants",
-      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.agent_readable_grants contains only grants for this exact agent device"
     }
   ],
@@ -68,5 +75,16 @@
       "command": "itp docs show recovery --role buyer --json"
     }
   ],
-  "search_terms": ["delivery", "claim", "email", "key", "redeem", "secure delivery", "交付", "邮件", "领取", "密钥"]
+  "search_terms": [
+    "delivery",
+    "claim",
+    "email",
+    "key",
+    "redeem",
+    "secure delivery",
+    "交付",
+    "邮件",
+    "领取",
+    "密钥"
+  ]
 }

package/docs/agent/buyer/vault-agent-read.json

@@ -10,35 +10,45 @@
     "A checkout/order has delivered a vault artifact and the human granted agent-readable access."
   ],
   "required_state": {
-    "needs": ["checkout_id or authenticated buyer account session", "current agent device binding", "order_id or checkout_id or vault_artifact_id"],
-    "must_not_need": ["human portal token", "claim token", "passkey credential", "raw protected payload", "grant id copied by the human"]
+    "needs": [
+      "checkout_id or authenticated buyer account session",
+      "current agent device binding",
+      "order_id or checkout_id or vault_artifact_id"
+    ],
+    "must_not_need": [
+      "human portal token",
+      "claim token",
+      "passkey credential",
+      "raw protected payload",
+      "grant id copied by the human"
+    ]
   },
   "commands": [
     {
       "intent": "check whether this agent has active human-approved grants for a checkout",
-      "command": "itp buyer vault grants list --checkout <checkout_id> --json",
+      "command": "itp buyer vault grants list --checkout <checkout_id> --host <client> --json",
       "success_signal": "response.agent_readable_grants is an array; count > 0 means the human has granted this exact agent access"
     },
     {
       "intent": "check whether this agent has active human-approved grants for one order or artifact",
-      "command": "itp buyer vault grants list --order <order_id> --artifact <vault_artifact_id> --json",
+      "command": "itp buyer vault grants list --order <order_id> --artifact <vault_artifact_id> --host <client> --json",
       "success_signal": "only grants scoped to this logged-in agent device are returned"
     },
     {
       "intent": "read a discovered grant view",
-      "command": "itp buyer vault grants read <agent_read_grant_id> --json",
+      "command": "itp buyer vault grants read <agent_read_grant_id> --host <client> --json",
       "success_signal": "response.grant contains selected_fields, structured_view, or summary according to the human-approved scope"
     },
     {
       "intent": "convenience read by order/artifact without asking the human for grant id",
-      "command": "itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --json",
+      "command": "itp buyer vault read --order <order_id> --artifact <vault_artifact_id> --host <client> --json",
       "success_signal": "the CLI discovers the active grant and reads its scoped view"
     }
   ],
   "agent_rules": [
     "Only read through `buyer vault` commands after the human has explicitly approved the agent grant in the ItPay portal.",
-    "Prefer `itp buyer vault grants list --checkout <checkout_id> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
-    "If the response includes buyer_session.status=buyer_session_saved, continue directly to `buyer vault grants read <agent_read_grant_id> --json`; do not ask the human for session tokens, auth IDs, or grant IDs.",
+    "Prefer `itp buyer vault grants list --checkout <checkout_id> --host <client> --json`; the CLI can automatically restore the buyer agent session from the checkout auth handoff when possible.",
+    "If the response includes buyer_session.status=buyer_session_saved, continue directly to `buyer vault grants read <agent_read_grant_id> --host <client> --json`; do not ask the human for session tokens, auth IDs, or grant IDs.",
     "Do not ask the human to copy or paste `agent_read_grant_id`; discover it with `buyer vault grants list`.",
     "If no grant is returned, tell the human to open their ItPay account portal, reveal with Passkey, choose fields, and confirm one-key agent authorization.",
     "If no grant is returned, explain likely causes: the human has not authorized yet, selected the wrong order/page, authorization has not synced yet, checkout/order/artifact does not match, buyer session expired, or the grant expired/revoked.",
@@ -46,7 +56,7 @@
     "Use only fields returned in the grant view. Do not infer that unreturned fields are accessible.",
     "When a grant view is returned, tell the user which fields are readable. If expires_at, ttl, or valid_until is present, tell the user the time limit; if no expiry is returned, say the response did not include an explicit expiry.",
     "If the returned fields are not enough for the user's task, ask the human to reopen Give to Agent and add the needed fields. Do not ask them to paste the missing raw content.",
-    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
+    "If the command still returns 401 or buyer_session_invalid after using `--checkout`, run `itp buyer checkout status <checkout_id> --host <client> --json`, then retry `itp buyer vault grants list --checkout <checkout_id> --host <client> --json`. Ask the human to reauthorize only if the checkout/auth handoff has expired."
   ],
   "forbidden": [
     "Do not open, click through, scrape, or automate the human web UI yourself.",
@@ -72,5 +82,14 @@
       "command": "itp docs show safety-policy --role buyer --json"
     }
   ],
-  "search_terms": ["vault", "agent read", "passkey grant", "one key agent", "授权给 agent", "可读授权", "字段授权", "查看报告"]
+  "search_terms": [
+    "vault",
+    "agent read",
+    "passkey grant",
+    "one key agent",
+    "授权给 agent",
+    "可读授权",
+    "字段授权",
+    "查看报告"
+  ]
 }

package/lib/buyer.js

@@ -3,8 +3,9 @@ import {
   readSessionToken, readState, safeErrorMessage, sleep, splitCSV, stripInternalBuyerFields, updateRun, writeConfig,
   writeCredentials, writeSessionCredentials, writeState
 } from "./env.js";
+import { clientCommandArgs, clientHost, clientTarget } from "./client-context.js";
 import { coreApi, coreApiBase } from "./http.js";
-import { buildHumanActionRenderPlan, humanOutputFromRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
+import { buildHumanActionRenderPlan, renderHumanAction, renderItPayPaymentAction, shouldReturnAfterAgentTextQR, writeWaitHeartbeat } from "./render-human.js";
 
 async function buyerBuy(flags) {
   rejectBuyerSandboxFlag(flags);
@@ -395,7 +396,7 @@ async function buyer(command, rest, flags) {
       agent_next_actions: event.agent_next_actions || intent.agent_next_actions || paymentAgentNextActions(intent, event),
       next: event.event_type === "payment_intent.verified"
         ? { command: intent.checkout_id ? cliCommand("buyer", "checkout", "status", intent.checkout_id, "--json") : undefined, safe_for_agent: true }
-        : { command: paymentStatusCheckCommand(paymentIntentID), safe_for_agent: true }
+        : { command: paymentStatusCheckCommand(paymentIntentID, flags), safe_for_agent: true }
     }));
     return;
   }
@@ -1093,49 +1094,14 @@ function paymentAgentNextActions(intent = {}, event = {}) {
 
 function paymentHandoffFields(intent = {}, flags = {}) {
   return {
-    payment_handoff: paymentHandoff(intent),
     render_plan: buildHumanActionRenderPlan(intent.human_action || {}, intent, flags),
-    after_human_response: paymentHandoffAfterHumanResponse(intent)
+    after_human_response: paymentHandoffAfterHumanResponse(intent, flags)
   };
 }
 
-function paymentHandoff(intent = {}) {
-  const action = intent.human_action || {};
-  const paymentIntentID = intent.payment_intent_id || action.id || "";
-  const entryURL = intent.payment_entry_url || intent.payment_url || action.url || "";
-  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 || "";
-  const mobileWalletURL = action.mobile_wallet_url || intent.mobile_wallet_url || "";
-  return {
-    type: "payment_qr_handoff",
-    payment_intent_id: paymentIntentID || null,
-    checkout_id: intent.checkout_id || null,
-    primary: localQRPath ? "local_qr_path" : (qrPNGURL ? "qr_png_url" : (preferredQRURL ? "preferred_qr_url" : "payment_entry_url")),
-    local_qr_path: localQRPath || null,
-    qr_png_url: qrPNGURL || null,
-    preferred_qr_url: preferredQRURL || null,
-    payment_entry_url: entryURL || null,
-    mobile_wallet_url: mobileWalletURL || null,
-    markdown: paymentHandoffMarkdown({ localQRPath, qrPNGURL, preferredQRURL, entryURL, mobileWalletURL }),
-    safe_for_agent: true,
-    instruction: "Render the QR/link to the human first. After the human responds or uses a platform button, query the same payment_intent_id. Only payment_intent.verified proves payment."
-  };
-}
-
-function paymentHandoffMarkdown({ localQRPath = "", qrPNGURL = "", preferredQRURL = "", entryURL = "", mobileWalletURL = "" } = {}) {
-  const imageURL = localQRPath || qrPNGURL || preferredQRURL;
-  const lines = ["请扫码付款："];
-  if (imageURL) lines.push(`![ItPay payment QR](${imageURL})`);
-  if (entryURL) lines.push(`[打开付款页面](${entryURL})`);
-  if (mobileWalletURL) lines.push(`[手机钱包打开](${mobileWalletURL})`);
-  lines.push("付款后回复“我已付款”，我会查询真实支付状态。");
-  return lines.join("\n\n");
-}
-
-function paymentStatusCheckCommand(paymentIntentID) {
+function paymentStatusCheckCommand(paymentIntentID, flags = {}) {
   if (!paymentIntentID) return "";
-  return cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "1", "--json");
+  return cliCommand("buyer", "payment", "wait", paymentIntentID, "--timeout", "1", ...clientCommandArgs(flags), "--json");
 }
 
 function shouldReturnPaymentHandoffBeforeWait(flags = {}) {
@@ -1185,36 +1151,26 @@ async function optionalBuyerPaymentContext(intent = {}, flags = {}) {
 }
 
 function isTelegramBuyerHost(flags = {}) {
-  const raw = 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().replaceAll("-", "_");
-  return raw === "telegram" || raw === "tg";
+  return clientHost(flags) === "telegram";
 }
 
 function paymentHandoffAgentNextActions() {
-  return ["show_human_visible_markdown"];
+  return ["send_agent_instruction_to_human"];
 }
 
 function paymentHandoffNext() {
   return {
     type: "reply_to_human",
     safe_for_agent: false,
-    instruction: "Send human_visible_markdown to the human now. Do not run payment wait until this message is visible to the human."
+    instruction: "Send agent_instruction to the human now. Do not run payment wait until this message is visible to the human."
   };
 }
 
-function paymentHandoffAfterHumanResponse(intent = {}) {
+function paymentHandoffAfterHumanResponse(intent = {}, flags = {}) {
   const paymentIntentID = intent.payment_intent_id || intent.human_action?.id || "";
   return {
-    check_payment_command: paymentStatusCheckCommand(paymentIntentID),
-    refresh_qr_command: paymentIntentID ? cliCommand("buyer", "payment", "refresh-qr", paymentIntentID, "--reason", "order-not-found", "--json") : "",
+    check_payment_command: paymentStatusCheckCommand(paymentIntentID, flags),
+    refresh_qr_command: paymentIntentID ? cliCommand("buyer", "payment", "refresh-qr", paymentIntentID, "--reason", "order-not-found", ...clientCommandArgs(flags), "--json") : "",
     safe_for_agent: true,
     instruction: "Use check_payment_command after the human says they paid or a platform button requests a status check. User text is not proof; only payment_intent.verified is."
   };
@@ -1586,8 +1542,8 @@ function isBuyerDeliveryComplete(result) {
     checkout.agent_next_actions?.includes("stop_check_email");
 }
 
-function buyerRunOutput(value = {}) {
-  const body = compactBuyerOutput(value);
+function buyerRunOutput(value = {}, flags = {}) {
+  const body = compactBuyerOutput(value, flags);
   return normalizeBuyerMoneyFields(stripInternalBuyerFields({
     schema_version: "itp.buyer.v1",
     ...body,
@@ -1600,21 +1556,11 @@ function buyerRunOutput(value = {}) {
   }));
 }
 
-function compactBuyerOutput(value = {}) {
-  const telegramInstruction = telegramBuyerInstruction(value);
-  if (telegramInstruction) return telegramInstruction;
+function compactBuyerOutput(value = {}, flags = {}) {
+  const clientInstruction = clientBuyerInstruction(value, flags);
+  if (clientInstruction) return clientInstruction;
   const result = {};
   if (value.status !== undefined) result.status = value.status;
-  if (value.payment_handoff?.markdown) {
-    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);
@@ -1622,7 +1568,20 @@ function compactBuyerOutput(value = {}) {
   return result;
 }
 
-function telegramBuyerInstruction(value = {}) {
+function clientBuyerInstruction(value = {}, flags = {}) {
+  const plan = value.render_plan || {};
+  const selected = plan.selected || {};
+  if (!plan.kind || !selected.platform) return null;
+  if (selected.platform === "telegram" && selected.openclaw_message) return telegramBuyerInstruction(value, flags);
+  if ((selected.platform === "codex_app" || selected.platform === "claude_code") && selected.markdown) {
+    return markdownBuyerInstruction(value, flags, selected.platform, selected.markdown);
+  }
+  if (selected.platform === "plain_chat") return plainChatBuyerInstruction(value, flags, selected);
+  if (selected.platform === "terminal") return terminalBuyerInstruction(value, flags);
+  return null;
+}
+
+function telegramBuyerInstruction(value = {}, flags = {}) {
   const plan = value.render_plan || {};
   const selected = plan.selected || {};
   if (selected.platform !== "telegram" || !selected.openclaw_message) return null;
@@ -1646,6 +1605,7 @@ function telegramBuyerInstruction(value = {}) {
         command: "openclaw message send",
         command_args: compactObject({
           channel: "telegram",
+          target: clientTarget(flags) || undefined,
           message: text,
           media: media || undefined,
           presentation
@@ -1664,6 +1624,59 @@ function telegramBuyerInstruction(value = {}) {
   });
 }
 
+function markdownBuyerInstruction(value = {}, flags = {}, platform = "codex_app", markdown = "") {
+  const plan = value.render_plan || {};
+  const summary = buyerOrderSummary(value, plan.kind);
+  return handoffInstructionOutput(value, flags, {
+    type: plan.kind === "auth_qr" ? "send_markdown_auth_handoff" : "send_markdown_payment_handoff",
+    platform,
+    proof_rule: plan.proof_rule,
+    instruction: "必须先把 markdown 原样发给用户；不要先运行 wait/status。只有 payment_intent.verified 才算付款成功。",
+    markdown
+  }, summary);
+}
+
+function plainChatBuyerInstruction(value = {}, flags = {}, selected = {}) {
+  const plan = value.render_plan || {};
+  const summary = buyerOrderSummary(value, plan.kind);
+  return handoffInstructionOutput(value, flags, {
+    type: plan.kind === "auth_qr" ? "send_plain_auth_handoff" : "send_plain_payment_handoff",
+    platform: "plain_chat",
+    proof_rule: plan.proof_rule,
+    instruction: "把 message 和 links 发给用户后停下，等用户回复再查状态。",
+    message: selected.text,
+    links: selected.links || []
+  }, summary);
+}
+
+function terminalBuyerInstruction(value = {}, flags = {}) {
+  const plan = value.render_plan || {};
+  const summary = buyerOrderSummary(value, plan.kind);
+  return handoffInstructionOutput(value, flags, {
+    type: plan.kind === "auth_qr" ? "terminal_auth_handoff" : "terminal_payment_handoff",
+    platform: "terminal",
+    proof_rule: plan.proof_rule,
+    instruction: "CLI 已负责终端展示；用户回复后再运行 after_human_response 里的命令。",
+    print_terminal_qr: true
+  }, summary);
+}
+
+function handoffInstructionOutput(value = {}, flags = {}, agentInstruction = {}, summary = {}) {
+  return compactObject({
+    status: value.status,
+    must_send_to_human_before_next_command: true,
+    order_summary: summary,
+    agent_instruction: agentInstruction,
+    after_human_response: genericAfterHumanResponse(value, flags, summary),
+    agent_next_actions: ["send_agent_instruction_to_human"],
+    next: {
+      type: "reply_to_human",
+      safe_for_agent: false,
+      instruction: "先把 agent_instruction 发送给用户；用户点击按钮或回复后，再运行 after_human_response 里的命令。"
+    }
+  });
+}
+
 function buyerOrderSummary(value = {}, kind = "") {
   const cart = value.cart || {};
   const checkout = value.checkout || {};
@@ -1758,6 +1771,19 @@ function telegramAfterHumanResponse(value = {}, callbacks = {}) {
   });
 }
 
+function genericAfterHumanResponse(value = {}, flags = {}, summary = {}) {
+  const paymentIntentID = summary.payment_intent_id;
+  const checkoutID = summary.checkout_id;
+  return compactObject({
+    check_status_command: value.after_human_response?.check_payment_command ||
+      (paymentIntentID ? paymentStatusCheckCommand(paymentIntentID, flags) : undefined) ||
+      (checkoutID ? cliCommand("buyer", "checkout", "resume", checkoutID, ...clientCommandArgs(flags), "--json") : undefined),
+    refresh_qr_command: value.after_human_response?.refresh_qr_command,
+    help_command: cliCommand("docs", "show", "payment-qr", "--role", "buyer", "--json"),
+    instruction: "用户点击查询按钮或回复已完成后，运行 check_status_command。用户口头说已付款不是证明。"
+  });
+}
+
 function compactBuyerField(key, value) {
   if (key === "selection") return compactSelection(value);
   if (key === "selections") return Array.isArray(value) ? value.map(compactSelection) : value;
@@ -1931,7 +1957,7 @@ function buyerDocsFor(value = {}) {
     topics.add("cart-checkout");
     topics.add("payment-qr");
   }
-  if (status.includes("payment_handoff") || status.includes("waiting_user_payment") || actions.includes("show_human_visible_markdown") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
+  if (status.includes("payment_handoff") || status.includes("waiting_user_payment") || actions.includes("send_agent_instruction_to_human") || actions.includes("wait_payment") || value.payment_intent?.human_action || value.payment_intent?.qr_image_url) {
     topics.add("payment-qr");
     topics.add("payment-wait");
   }

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 };